The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Business-ISBN-1.56
River stage two • 11 direct dependents • 14 total dependents
6 ++
/ Business::ISBN

NAME

Business::ISBN - work with International Standard Book Numbers

SYNOPSIS

        use Business::ISBN;
        
        $isbn_object = new Business::ISBN('1565922573');
        $isbn_object = new Business::ISBN('1-56592-257-3');
                
        #print the ISBN with hyphens at positions specified
        #by constructor
        print $isbn_object->as_string;
        
        #print the ISBN with hyphens at specified positions.
        #this not does affect the default positions
        print $isbn_object->as_string([]);
        
        #print the country code or publisher code
        print $isbn->country_code;
        print $isbn->publisher_code;
        
        #check to see if the ISBN is valid
        $isbn_object->is_valid;
        
        #fix the ISBN checksum.  BEWARE:  the error might not be
        #in the checksum!
        $isbn_object->fix_checksum;

        #EXPORTABLE FUNCTIONS
        
        use Business::ISBN qw( is_valid_checksum isbn_to_ean ean_to_isbn );
        
        #verify the checksum
        if( is_valid_checksum('0123456789') eq Business::ISBN::GOOD_ISBN ) 
                { ... }
        
        #convert to EAN (European Article Number)
        $ean = isbn_to_ean('1565921496');

        #convert from EAN (European Article Number)
        $isbn = ean_to_isbn('9781565921498');

DESCRIPTION

new($isbn)

The constructor accepts a scalar representing the ISBN.

The string representing the ISBN may contain characters other than [0-9xX], although these will be removed in the internal representation. The resulting string must look like an ISBN - the first nine characters must be digits and the tenth character must be a digit, 'x', or 'X'.

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

        C<Business::ISBN::INVALID_PUBLISHER_CODE>
        C<Business::ISBN::INVALID_COUNTRY_CODE>
        C<Business::ISBN::BAD_CHECKSUM>
        C<Business::ISBN::GOOD_ISBN>
        C<Business::ISBN::BAD_ISBN>

The string passed as the ISBN need not be a valid ISBN 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 ISBN 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 ISBN, one can skip the object-oriented interface and use the c<is_valid_checksum()> function which is exportable on demand.

If the constructor decides it can't create an object, it returns undef. It may do this if the string passed as the ISBN can't be munged to the internal format.

$obj->publisher_code

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

$obj->country_code

Returns the country code or undef if no country code was found.

$obj->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.

$obj->as_string(), $obj->as_string([])

Return the ISBN as a string. This function takes an optional anonymous array (or array reference) that specifies the placement of hyphens in the string. An empty list produces a string with no hyphens.

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.

Positions less than 1 and greater than 9 are silently ignored.

A terminating 'x' is changed to 'X'.

$obj->is_valid()

Returns Business::ISBN::GOOD_ISBN if the checksum is valid and the country and publisher codes are defined.

Returns Business::ISBN::BAD_CHECKSUM if the ISBN does not pass the checksum test. The constructor accepts invalid ISBN's so that they might be fixed with fix_checksum.

Returns Business::ISBN::INVALID_COUNTRY_CODE if a country code could not be determined (relies on a valid checksum).

Returns Business::ISBN::INVALID_PUBLISHER_CODE if a publisher code could not be determined (relies on a valid checksum and country code).

$obj->fix_checksum()

Replace the tenth character with the checksum the corresponds to the previous nine digits. This does not guarantee that the ISBN corresponds to the product one thinks it does, or that the ISBN corresponds to any product at all. It only produces a string that passes the checksum routine. If the ISBN passed to the constructor was invalid, the error might have been in any of the other nine positions.

$obj->as_ean()

Converts the ISBN 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.

EXPORTABLE FUNCTIONS

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

is_valid_checksum('1565921496')

Takes the ISBN string and runs it through the checksum comparison routine. Returns Business::ISBN::GOOD_ISBN if the ISBN is valid, Business::ISBN::BAD_CHECKSUM if the string looks like an ISBN but has an invalid checksum, and Business::ISBN::BAD_ISBN if the string does not look like an ISBN.

isbn_to_ean('1565921496')

Takes the ISBN string and converts it to the equivalent EAN string. This function checks for a valid ISBN and will return undef for invalid ISBNs, otherwise it returns the EAN as a string. Uses as_ean internally, which checks its arguments to determine what to do.

ean_to_isbn('9781565921498')

Takes the EAN string and converts it to the equivalent ISBN string. This function checks for a valid ISBN and will return undef for invalid ISBNs, otherwise it returns the EAN as a string. Uses as_ean internally, which checks its arguments to determine what to do.

AUTHOR

brian d foy <bdfoy@cpan.org>

Copyright 2001 brian d foy

Country code and publisher code graciously provided by Steve Fisher <stevef@teleord.co.uk> of Whitaker (the UK ISBN folks and the major bibliographic data provider in the UK). "Whitaker - helping to link authors to readers worldwide"

Thanks to Julie Koo of Kaya Publishing <URL:http://www.kaya.com> for useful discussions.

Thanks to Mark W. Eichin <eichin@thok.org> for suggestions and discussions on EAN support.