.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Business::ISMN 3pm"
.TH Business::ISMN 3pm "2018-12-22" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Business::ISMN \- work with International Standard Music Numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Business::ISMN;
\&
\&        $ismn_object = new Business::ISMN(\*(AqM021765430\*(Aq);
\&        $ismn_object = new Business::ISMN(\*(AqM\-021\-76543\-0\*(Aq);
\&
\&        #print the ISMN with hyphens at positions specified
\&        #by constructor
\&        print $ismn_object\->as_string;
\&
\&        #print the ISMN with hyphens at specified positions.
\&        #this not does affect the default positions
\&        print $ismn_object\->as_string([]);
\&
\&        #print the publication country or publisher code
\&        print $ismn\->country;         # two letter country string
\&        print $ismn\->publisher_code;  # digits
\&
\&        #check to see if the ISMN is valid
\&        $ismn_object\->is_valid;
\&
\&        #fix the ISMN checksum.  BEWARE:  the error might not be
\&        #in the checksum!
\&        $ismn_object\->fix_checksum;
\&
\&        # create an EAN13 barcode in PNG format
\&        $ismn_object\->png_barcode;
\&
\&        #EXPORTABLE FUNCTIONS
\&
\&        use Business::ISMN qw( is_valid_checksum
\&                ismn_to_ean ean_to_ismn );
\&
\&        #verify the checksum
\&        if( is_valid_checksum(\*(Aq0123456789\*(Aq)
\&                eq Business::ISMN::GOOD_ISMN )
\&                { ... }
\&
\&        #convert to EAN (European Article Number)
\&        $ean = ismn_to_ean(\*(Aq1565921496\*(Aq);
\&
\&        #convert from EAN (European Article Number)
\&        $ismn = ean_to_ismn(\*(Aq9781565921498\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Methods"
.IX Subsection "Methods"
.IP "new($ismn)" 4
.IX Item "new($ismn)"
The constructor accepts a scalar representing the \s-1ISMN.\s0
.Sp
The string representing the \s-1ISMN\s0 may contain characters
other than \f(CW\*(C`[0\-9mM]\*(C'\fR, although these will be removed in the
internal representation.  The resulting string must look
like an \s-1ISMN\s0 \- the first character is an 'M' and the
following nine characters must be digits.
.Sp
The constructor attempts to determine the country
code and the publisher code.  If these data cannot
be determined, the constructor sets \f(CW\*(C`$obj\->is_valid\*(C'\fR
to something other than \f(CW\*(C`GOOD_ISMN\*(C'\fR.
An object is still returned and it is up to the program
to check \f(CW\*(C`$obj\->is_valid\*(C'\fR for one of five values (which
may be exported on demand). The actual values of these
symbolic versions are the same as those from previous
versions of this module which used literal values.
.Sp
.Vb 4
\&        Business::ISMN::INVALID_PUBLISHER_CODE
\&        Business::ISMN::BAD_CHECKSUM
\&        Business::ISMN::GOOD_ISMN
\&        Business::ISMN::BAD_ISMN
.Ve
.Sp
The string passed as the \s-1ISMN\s0 need not be a valid \s-1ISMN\s0 as
long as it superficially looks like one.  This allows one to
use the \f(CW\*(C`fix_checksum()\*(C'\fR method.  Despite the disclaimer in
the discussion of that method, the author has found it
extremely useful.  One should check the validity of the \s-1ISMN\s0
with \f(CW\*(C`is_valid()\*(C'\fR rather than relying on the return value
of the constructor.  If all one wants to do is check the
validity of an \s-1ISMN,\s0 one can skip the object-oriented
interface and use the \f(CW\*(C`is_valid_checksum()\*(C'\fR function
which is exportable on demand.
.Sp
If the constructor decides it cannot create an object, it
returns \f(CW\*(C`undef\*(C'\fR.  It may do this if the string passed as the
\&\s-1ISMN\s0 cannot be munged to the internal format meaning that it
does not even come close to looking like an \s-1ISMN.\s0
.IP "ismn" 4
.IX Item "ismn"
Returns the \s-1ISMN\s0 as a string
.IP "country" 4
.IX Item "country"
.PD 0
.IP "publisher" 4
.IX Item "publisher"
.PD
Returns the country associated with the publisher code. This method was
formerly called \f(CW\*(C`publisher\*(C'\fR (and that still works), but it's really
returns a two letter country code.
.IP "publisher_code" 4
.IX Item "publisher_code"
Returns the publisher code or \f(CW\*(C`undef\*(C'\fR if no publisher code was found.
.IP "article_code" 4
.IX Item "article_code"
Returns the article code or \f(CW\*(C`undef\*(C'\fR if no article
code was found.
.IP "checksum" 4
.IX Item "checksum"
Returns the checksum or \f(CW\*(C`undef\*(C'\fR if no publisher
code was found.
.IP "hyphen_positions" 4
.IX Item "hyphen_positions"
Returns the list of hyphen positions as determined from the
country and publisher codes.  the \f(CW\*(C`as_string\*(C'\fR method provides
a way to temporarily override these positions and to even
forego them altogether.
.IP "\fBas_string()\fR,  as_string([])" 4
.IX Item "as_string(), as_string([])"
Return the \s-1ISMN\s0 as a string.  This function takes an
optional anonymous array (or array reference) that specifies
the placement of hyphens in the string.  An empty anonymous array
produces a string with no hyphens. An empty argument list
automatically hyphenates the \s-1ISMN\s0 based on the discovered
publisher code.  An \s-1ISMN\s0 that is not valid may
produce strange results.
.Sp
The positions specified in the passed anonymous array
are only used for one method use and do not replace
the values specified by the constructor. The method
assumes that you know what you are doing and will attempt
to use the least three positions specified.  If you pass
an anonymous array of several positions, the list will
be sorted and the lowest three positions will be used.
Positions less than 1 and greater than 9 are silently
ignored.
.IP "is_valid" 4
.IX Item "is_valid"
Returns \f(CW\*(C`Business::ISMN::GOOD_ISMN\*(C'\fR if the checksum is valid and the
country and publisher codes are defined.
.Sp
Returns \f(CW\*(C`Business::ISMN::BAD_CHECKSUM\*(C'\fR if the \s-1ISMN\s0 does not pass
the checksum test. The constructor accepts invalid \s-1ISMN\s0's so that
they might be fixed with \f(CW\*(C`fix_checksum\*(C'\fR.
.Sp
Returns \f(CW\*(C`Business::ISMN::INVALID_PUBLISHER_CODE\*(C'\fR if a publisher code
could not be determined.
.Sp
Returns \f(CW\*(C`Business::ISMN::BAD_ISMN\*(C'\fR if the string has no hope of ever
looking like a valid \s-1ISMN.\s0  This might include strings such as \f(CW"abc"\fR,
\&\f(CW"123456"\fR, and so on.
.IP "is_valid_country_code" 4
.IX Item "is_valid_country_code"
.PD 0
.IP "is_valid_publisher_code" 4
.IX Item "is_valid_publisher_code"
.PD
Returns true if the country code is valid, and false otherwise.
.Sp
This method was formerly called \f(CW\*(C`is_valid_publisher_code\*(C'\fR. That's
deprecated but still there.
.IP "\fBfix_checksum()\fR" 4
.IX Item "fix_checksum()"
Replace the tenth character with the checksum the
corresponds to the previous nine digits.  This does not
guarantee that the \s-1ISMN\s0 corresponds to the product one
thinks it does, or that the \s-1ISMN\s0 corresponds to any product
at all.  It only produces a string that passes the checksum
routine.  If the \s-1ISMN\s0 passed to the constructor was invalid,
the error might have been in any of the other nine positions.
.ie n .IP "$obj\->\fBas_ean()\fR" 4
.el .IP "\f(CW$obj\fR\->\fBas_ean()\fR" 4
.IX Item "$obj->as_ean()"
Converts the \s-1ISMN\s0 to the equivalent \s-1EAN\s0 (European Article Number).
No pricing extension is added.  Returns the \s-1EAN\s0 as a string.  This
method can also be used as an exportable function since it checks
its argument list to determine what to do.
.IP "\fBpng_barcode()\fR" 4
.IX Item "png_barcode()"
Creates a \s-1PNG\s0 image of the \s-1EAN13\s0 barcode which corresponds to the
\&\s-1ISMN.\s0 Returns the image as a string.
.SS "\s-1EXPORTABLE FUNCTIONS\s0"
.IX Subsection "EXPORTABLE FUNCTIONS"
Some functions can be used without the object interface.  These
do not use object technology behind the scenes.
.IP "is_valid_checksum('M021765430')" 4
.IX Item "is_valid_checksum('M021765430')"
Takes the \s-1ISMN\s0 string and runs it through the checksum
comparison routine.  Returns \f(CW\*(C`Business::ISMN::GOOD_ISMN\*(C'\fR
if the \s-1ISMN\s0 is valid, \f(CW\*(C`Business::ISMN::BAD_CHECKSUM\*(C'\fR if the
string looks like an \s-1ISMN\s0 but has an invalid checksum, and
\&\f(CW\*(C`Business::ISMN::BAD_ISMN\*(C'\fR if the string does not look like
an \s-1ISMN.\s0
.IP "ismn_to_ean('M021765430')" 4
.IX Item "ismn_to_ean('M021765430')"
Takes the \s-1ISMN\s0 string and converts it to the equivalent
\&\s-1EAN\s0 string.  This function checks for a valid \s-1ISMN\s0 and will return
undef for invalid ISMNs, otherwise it returns the \s-1EAN\s0 as a string.
Uses as_ean internally, which checks its arguments to determine
what to do.
.IP "ean_to_ismn('9790021765439')" 4
.IX Item "ean_to_ismn('9790021765439')"
Takes the \s-1EAN\s0 string and converts it to the equivalent
\&\s-1ISMN\s0 string.  This function checks for a valid \s-1ISMN\s0 and will return
undef for invalid ISMNs, otherwise it returns the \s-1EAN\s0 as a string.
Uses as_ean internally, which checks its arguments to determine
what to do.
.SH "TO DO"
.IX Header "TO DO"
* i need more \s-1ISMN\s0 numbers for tests
.SH "SOURCE AVAILABILITY"
.IX Header "SOURCE AVAILABILITY"
This source is in Github:
.PP
.Vb 1
\&    https://github.com/briandfoy/business\-ismn/
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
brian d foy, \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright © 2001\-2018, brian d foy <bdfoy@cpan.org>. All rights reserved.
.PP
You may redistribute this under the terms of the Artistic License 2.0.