1Business::ISMN(3)     User Contributed Perl Documentation    Business::ISMN(3)
2
3
4

NAME

6       Business::ISMN - work with International Standard Music Numbers
7

SYNOPSIS

9               use Business::ISMN;
10
11               $ismn_object = new Business::ISMN('M021765430');
12               $ismn_object = new Business::ISMN('M-021-76543-0');
13
14               #print the ISMN with hyphens at positions specified
15               #by constructor
16               print $ismn_object->as_string;
17
18               #print the ISMN with hyphens at specified positions.
19               #this not does affect the default positions
20               print $ismn_object->as_string([]);
21
22               #print the publication country or publisher code
23               print $ismn->country;         # two letter country string
24               print $ismn->publisher_code;  # digits
25
26               #check to see if the ISMN is valid
27               $ismn_object->is_valid;
28
29               #fix the ISMN checksum.  BEWARE:  the error might not be
30               #in the checksum!
31               $ismn_object->fix_checksum;
32
33               # create an EAN13 barcode in PNG format
34               $ismn_object->png_barcode;
35
36               #EXPORTABLE FUNCTIONS
37
38               use Business::ISMN qw( is_valid_checksum
39                       ismn_to_ean ean_to_ismn );
40
41               #verify the checksum
42               if( is_valid_checksum('0123456789')
43                       eq Business::ISMN::GOOD_ISMN )
44                       { ... }
45
46               #convert to EAN (European Article Number)
47               $ean = ismn_to_ean('1565921496');
48
49               #convert from EAN (European Article Number)
50               $ismn = ean_to_ismn('9781565921498');
51

DESCRIPTION

53   Methods
54       new($ismn)
55           The constructor accepts a scalar representing the ISMN.
56
57           The string representing the ISMN may contain characters other than
58           "[0-9mM]", although these will be removed in the internal
59           representation.  The resulting string must look like an ISMN - the
60           first character is an 'M' and the following nine characters must be
61           digits.
62
63           The constructor attempts to determine the country code and the
64           publisher code.  If these data cannot be determined, the
65           constructor sets "$obj->is_valid" to something other than
66           "GOOD_ISMN".  An object is still returned and it is up to the
67           program to check "$obj->is_valid" for one of five values (which may
68           be exported on demand). The actual values of these symbolic
69           versions are the same as those from previous versions of this
70           module which used literal values.
71
72                   Business::ISMN::INVALID_PUBLISHER_CODE
73                   Business::ISMN::BAD_CHECKSUM
74                   Business::ISMN::GOOD_ISMN
75                   Business::ISMN::BAD_ISMN
76
77           The string passed as the ISMN need not be a valid ISMN as long as
78           it superficially looks like one.  This allows one to use the
79           "fix_checksum()" method.  Despite the disclaimer in the discussion
80           of that method, the author has found it extremely useful.  One
81           should check the validity of the ISMN with "is_valid()" rather than
82           relying on the return value of the constructor.  If all one wants
83           to do is check the validity of an ISMN, one can skip the object-
84           oriented interface and use the "is_valid_checksum()" function which
85           is exportable on demand.
86
87           If the constructor decides it cannot create an object, it returns
88           "undef".  It may do this if the string passed as the ISMN cannot be
89           munged to the internal format meaning that it does not even come
90           close to looking like an ISMN.
91
92       ismn
93           Returns the ISMN as a string
94
95       country
96       publisher
97           Returns the country associated with the publisher code. This method
98           was formerly called "publisher" (and that still works), but it's
99           really returns a two letter country code.
100
101       publisher_code
102           Returns the publisher code or "undef" if no publisher code was
103           found.
104
105       article_code
106           Returns the article code or "undef" if no article code was found.
107
108       checksum
109           Returns the checksum or "undef" if no publisher code was found.
110
111       hyphen_positions
112           Returns the list of hyphen positions as determined from the country
113           and publisher codes.  the "as_string" method provides a way to
114           temporarily override these positions and to even forego them
115           altogether.
116
117       as_string(),  as_string([])
118           Return the ISMN as a string.  This function takes an optional
119           anonymous array (or array reference) that specifies the placement
120           of hyphens in the string.  An empty anonymous array produces a
121           string with no hyphens. An empty argument list automatically
122           hyphenates the ISMN based on the discovered publisher code.  An
123           ISMN that is not valid may produce strange results.
124
125           The positions specified in the passed anonymous array are only used
126           for one method use and do not replace the values specified by the
127           constructor. The method assumes that you know what you are doing
128           and will attempt to use the least three positions specified.  If
129           you pass an anonymous array of several positions, the list will be
130           sorted and the lowest three positions will be used.  Positions less
131           than 1 and greater than 9 are silently ignored.
132
133       is_valid
134           Returns "Business::ISMN::GOOD_ISMN" if the checksum is valid and
135           the country and publisher codes are defined.
136
137           Returns "Business::ISMN::BAD_CHECKSUM" if the ISMN does not pass
138           the checksum test. The constructor accepts invalid ISMN's so that
139           they might be fixed with "fix_checksum".
140
141           Returns "Business::ISMN::INVALID_PUBLISHER_CODE" if a publisher
142           code could not be determined.
143
144           Returns "Business::ISMN::BAD_ISMN" if the string has no hope of
145           ever looking like a valid ISMN.  This might include strings such as
146           "abc", "123456", and so on.
147
148       is_valid_country_code
149       is_valid_publisher_code
150           Returns true if the country code is valid, and false otherwise.
151
152           This method was formerly called "is_valid_publisher_code". That's
153           deprecated but still there.
154
155       fix_checksum()
156           Replace the tenth character with the checksum the corresponds to
157           the previous nine digits.  This does not guarantee that the ISMN
158           corresponds to the product one thinks it does, or that the ISMN
159           corresponds to any product at all.  It only produces a string that
160           passes the checksum routine.  If the ISMN passed to the constructor
161           was invalid, the error might have been in any of the other nine
162           positions.
163
164       $obj->as_ean()
165           Converts the ISMN to the equivalent EAN (European Article Number).
166           No pricing extension is added.  Returns the EAN as a string.  This
167           method can also be used as an exportable function since it checks
168           its argument list to determine what to do.
169
170       png_barcode()
171           Creates a PNG image of the EAN13 barcode which corresponds to the
172           ISMN. Returns the image as a string.
173
174   EXPORTABLE FUNCTIONS
175       Some functions can be used without the object interface.  These do not
176       use object technology behind the scenes.
177
178       is_valid_checksum('M021765430')
179           Takes the ISMN string and runs it through the checksum comparison
180           routine.  Returns "Business::ISMN::GOOD_ISMN" if the ISMN is valid,
181           "Business::ISMN::BAD_CHECKSUM" if the string looks like an ISMN but
182           has an invalid checksum, and "Business::ISMN::BAD_ISMN" if the
183           string does not look like an ISMN.
184
185       ismn_to_ean('M021765430')
186           Takes the ISMN string and converts it to the equivalent EAN string.
187           This function checks for a valid ISMN and will return undef for
188           invalid ISMNs, otherwise it returns the EAN as a string.  Uses
189           as_ean internally, which checks its arguments to determine what to
190           do.
191
192       ean_to_ismn('9790021765439')
193           Takes the EAN string and converts it to the equivalent ISMN string.
194           This function checks for a valid ISMN and will return undef for
195           invalid ISMNs, otherwise it returns the EAN as a string.  Uses
196           as_ean internally, which checks its arguments to determine what to
197           do.
198

TO DO

200       * i need more ISMN numbers for tests
201

SOURCE AVAILABILITY

203       This source is in Github:
204
205           https://github.com/briandfoy/business-ismn/
206

AUTHOR

208       brian d foy, "<bdfoy@cpan.org>"
209
211       Copyright © 2001-2021, brian d foy <bdfoy@cpan.org>. All rights
212       reserved.
213
214       You may redistribute this under the terms of the Artistic License 2.0.
215
216
217
218perl v5.34.0                      2021-07-22                 Business::ISMN(3)
Impressum