Business::ISMN (3)

Leading comments

Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Business::ISMN.3pm".)

NAME

Business::ISMN - work with International Standard Music Numbers

SYNOPSIS

        use Business::ISMN;

        $ismn_object = new Business::ISMN('M021765430');
        $ismn_object = new Business::ISMN('M-021-76543-0');

        #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 publisher or publisher code
        print $ismn->publisher;
        print $ismn->publisher_code;

        #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('0123456789')
                eq Business::ISMN::GOOD_ISMN )
                { ... }

        #convert to EAN (European Article Number)
        $ean = ismn_to_ean('1565921496');

        #convert from EAN (European Article Number)
        $ismn = ean_to_ismn('9781565921498');

DESCRIPTION

Methods

new($ismn)

The constructor accepts a scalar representing the

ISMN.

The string representing the

ISMN

may contain characters other than "[0-9mM]", although these will be removed in the internal representation. The resulting string must look like an

ISMN -

the first character is an 'M' and the following nine characters must be digits.

The constructor attempts to determine the country code and the publisher code. If these data cannot be determined, the constructor sets "$obj->is_valid" to something other than "GOOD_ISMN". An object is still returned and it is up to the program to check "$obj->is_valid" 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.

        Business::ISMN::INVALID_PUBLISHER_CODE
        Business::ISMN::BAD_CHECKSUM
        Business::ISMN::GOOD_ISMN
        Business::ISMN::BAD_ISMN

The string passed as the

ISMN

need not be a valid

ISMN

as long as it superficially looks like one. This allows one to use the "fix_checksum()" method. Despite the disclaimer in the discussion of that method, the author has found it extremely useful. One should check the validity of the

ISMN

with "is_valid()" rather than relying on the return value of the constructor. If all one wants to do is check the validity of an

ISMN,

one can skip the object-oriented interface and use the "is_valid_checksum()" function which is exportable on demand.

If the constructor decides it cannot create an object, it returns "undef". It may do this if the string passed as the

ISMN

cannot be munged to the internal format meaning that it does not even come close to looking like an

ISMN.

ismn

Returns the

ISMN

as a string

publisher

Returns the country associated with the publisher code.

publisher_code

Returns the publisher code or "undef" if no publisher code was found.

article_code

Returns the article code or "undef" if no article code was found.

checksum

Returns the checksum or "undef" if no publisher code was found.

hyphen_positions

Returns the list of hyphen positions as determined from the country and publisher codes. the "as_string" method provides a way to temporarily override these positions and to even forego them altogether.

as_string(), as_string([])

Return the

ISMN

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

ISMN

based on the discovered publisher code. An

ISMN

that is not valid may produce strange results.

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.

is_valid

Returns "Business::ISMN::GOOD_ISMN" if the checksum is valid and the country and publisher codes are defined.

Returns "Business::ISMN::BAD_CHECKSUM" if the

ISMN

does not pass the checksum test. The constructor accepts invalid

ISMN

's so that they might be fixed with "fix_checksum".

Returns "Business::ISMN::INVALID_PUBLISHER_CODE" if a publisher code could not be determined.

Returns "Business::ISMN::BAD_ISMN" if the string has no hope of ever looking like a valid

ISMN.

This might include strings such as "abc", "123456", and so on.

is_valid_publisher_code

Returns true if the publisher code is valid, and false otherwise.

fix_checksum()

Replace the tenth character with the checksum the corresponds to the previous nine digits. This does not guarantee that the

ISMN

corresponds to the product one thinks it does, or that the

ISMN

corresponds to any product at all. It only produces a string that passes the checksum routine. If the

ISMN

passed to the constructor was invalid, the error might have been in any of the other nine positions.

$obj->as_ean()

Converts the

ISMN

to the equivalent

EAN

(European Article Number). No pricing extension is added. Returns the

EAN

as a string. This method can also be used as an exportable function since it checks its argument list to determine what to do.

png_barcode()

Creates a

PNG

image of the

EAN13

barcode which corresponds to the

ISMN.

Returns the image as a string.

EXPORTABLE FUNCTIONS

Some functions can be used without the object interface. These do not use object technology behind the scenes.

is_valid_checksum('M021765430')

Takes the

ISMN

string and runs it through the checksum comparison routine. Returns "Business::ISMN::GOOD_ISMN" if the

ISMN

is valid, "Business::ISMN::BAD_CHECKSUM" if the string looks like an

ISMN

but has an invalid checksum, and "Business::ISMN::BAD_ISMN" if the string does not look like an

ISMN.

ismn_to_ean('M021765430')

Takes the

ISMN

string and converts it to the equivalent

EAN

string. This function checks for a valid

ISMN

and will return undef for invalid ISMNs, otherwise it returns the

EAN

as a string. Uses as_ean internally, which checks its arguments to determine what to do.

ean_to_ismn('9790021765439')

Takes the

EAN

string and converts it to the equivalent

ISMN

string. This function checks for a valid

ISMN

and will return undef for invalid ISMNs, otherwise it returns the

EAN

as a string. Uses as_ean internally, which checks its arguments to determine what to do.

TO DO

* i need more numbers for tests

SOURCE AVAILABILITY

This source is in Github:

    github.com/briandfoy/business--isbn/tree/master

AUTHOR

brian d foy, "<bdfoy@cpan.org>"

COPYRIGHT AND LICENSE

Copyright © 2001-2016, brian d foy <bdfoy@cpan.org>. All rights reserved.

You may redistribute this under the same terms as Perl itself.