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 ISMN numbers for tests
SOURCE AVAILABILITY¶
This source is part of a SourceForge project which always has the latest sources
in CVS, as well as all of the previous releases.
http://sourceforge.net/projects/brian-d-foy/
If, for some reason, I disappear from the world, one of the other members of the
project can shepherd this module appropriately.
AUTHOR¶
brian d foy, "<bdfoy@cpan.org>"
COPYRIGHT AND LICENSE¶
Copyright (c) 2001-2007, brian d foy, All Rights Reserved.
You may redistribute this under the same terms as Perl itself.