1Business::ISMN(3) User Contributed Perl Documentation Business::ISMN(3)
2
3
4
6 Business::ISMN - work with International Standard Music Numbers
7
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
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
200 * i need more ISMN numbers for tests
201
203 This source is in Github:
204
205 https://github.com/briandfoy/business-ismn/
206
208 brian d foy, "<bdfoy@cpan.org>"
209
211 Copyright © 2001-2018, 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.30.0 2019-07-26 Business::ISMN(3)