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

NAME

6       Business::ISBN - work with International Standard Book Numbers
7

SYNOPSIS

9               use Business::ISBN;
10
11               # 10 digit ISBNs
12               $isbn10 = Business::ISBN->new('1565922573');
13               $isbn10 = Business::ISBN->new('1-56592-257-3');
14
15               # 13 digit ISBNs
16               $isbn13 = Business::ISBN->new('978-0-596-52724-2');
17
18               # convert
19               $isbn10 = $isbn13->as_isbn10;    # for the 978 prefixes
20
21               $isbn13 = $isbn10->as_isbn13;
22
23               # maybe you don't care what it is as long as everything works
24               $isbn = Business::ISBN->new( $ARGV[0] );
25
26               #print the ISBN with hyphens at usual positions
27               print $isbn->as_string;
28
29               #print the ISBN with hyphens at specified positions.
30               #this not does affect the default positions
31               print $isbn->as_string([]);
32
33               #print the group code or publisher code
34               print $isbn->group_code;
35
36               print $isbn->publisher_code;
37
38               #check to see if the ISBN is valid
39               $isbn->is_valid;
40
41               #fix the ISBN checksum.  BEWARE:  the error might not be
42               #in the checksum!
43               $isbn->fix_checksum;
44
45               # create an EAN13 barcode in PNG format
46               $isbn->png_barcode;
47

DESCRIPTION

49       This modules handles International Standard Book Numbers, including
50       ISBN-10 and ISBN-13.
51
52   Function interface
53       valid_isbn_checksum( ISBN10 | ISBN13 )
54           This function is exportable on demand, and works for either 10 or
55           13 character ISBNs).
56
57                   use Business::ISBN qw( valid_isbn_checksum );
58
59           Returns 1 if the ISBN is a valid ISBN with the right checksum.
60
61           Returns 0 if the ISBN has valid prefix and publisher codes, but an
62           invalid checksum.
63
64           Returns undef if the ISBN does not validate for any other reason.
65
66   Object interface
67       new($isbn)
68           The constructor accepts a scalar representing the ISBN.
69
70           The string representing the ISBN may contain characters other than
71           "[0-9xX]", although these will be removed in the internal
72           representation.  The resulting string must look like an ISBN - the
73           first nine characters must be digits and the tenth character must
74           be a digit, 'x', or 'X'.
75
76           The constructor attempts to determine the group code and the
77           publisher code.  If these data cannot be determined, the
78           constructor sets "$obj->error" to something other than "GOOD_ISBN".
79           An object is still returned and it is up to the program to check
80           the "error" method for one of five values or one of the "error_*"
81           methods to check for a particular error. The actual values of these
82           symbolic versions are the same as those from previous versions of
83           this module which used literal values:
84
85                   Business::ISBN::INVALID_PUBLISHER_CODE
86                   Business::ISBN::INVALID_GROUP_CODE
87                   Business::ISBN::BAD_CHECKSUM
88                   Business::ISBN::GOOD_ISBN
89                   Business::ISBN::BAD_ISBN
90
91           If you have one of these values and want to turn it into a string,
92           you can use the %Business::ISBN::ERROR_TEXT hash, which is
93           exportable by asking for it explicitly in the import list:
94
95                   use Business::ISBN qw(%ERROR_TEXT);
96
97           As of version 2.010_01, you can get this text from "error_text" so
98           you don't have to import anything.
99
100           The string passed as the ISBN need not be a valid ISBN as long as
101           it superficially looks like one.  This allows one to use the
102           "fix_checksum()" method.  Despite the disclaimer in the discussion
103           of that method, the author has found it extremely useful.  One
104           should check the validity of the ISBN with "is_valid()" rather than
105           relying on the return value of the constructor.  If all one wants
106           to do is check the validity of an ISBN, one can skip the object-
107           oriented interface and use the "valid_isbn_checksum()" function
108           which is exportable on demand.
109
110           If the constructor decides it cannot create an object, it returns
111           "undef".  It may do this if the string passed as the ISBN cannot be
112           munged to the internal format meaning that it does not even come
113           close to looking like an ISBN.
114
115   Instance methods
116       input_isbn
117           Returns the starting ISBN. Since you may insert hyphens or fix
118           checksums, you might want to see the original data.
119
120       common_data
121           Returns the starting ISBN after normalization, which removes
122           anything that isn't a digit or a valid checksum character.
123
124       isbn
125           Returns the current value of ISBN, even if it has an invalid
126           checksum.  This is the raw data so it doesn't have the hyphens. If
127           you want hyphenation, try "as_string".
128
129           The "isbn" method should be the same as "as_string( [] )".
130
131       error
132           Return the error code for the reason the ISBN isn't valid. The
133           return value is a key in %ERROR_TEXT.
134
135       error_is_bad_group
136       error_is_bad_publisher
137       error_is_article_out_of_range
138       error_is_bad_checksum
139           Returns true if the ISBN error is that type.
140
141       error_text
142           Returns a text version of the error text
143
144       is_valid
145           Return true if the ISBN is valid, meaning that it has a valid
146           prefix (for ISBN-13), group code, and publisher code; and its
147           checksum validates.
148
149       type
150           Returns either "ISBN10" or "ISBN13".
151
152       prefix
153           Returns the prefix for the ISBN. This is currently either 978 or
154           979 for ISBN-13. It returns the empty string (so, a defined value)
155           for ISBN-10.
156
157       group_code
158           Returns the group code for the ISBN. This is the numerical version,
159           for example, '0' for the English group. The valid group codes come
160           from "Business::ISBN::Data".
161
162       group
163           Returns the group name for the ISBN. This is the string version.
164           For instance, 'English' for the '0' group. The names come from
165           "Business::ISBN::Data".
166
167       publisher_code
168           Returns the publisher code for the ISBN. This is the numeric
169           version, for instance '596' for O'Reilly Media.
170
171       article_code
172           Returns the article code for the ISBN. This is the numeric version
173           that uniquely identifies the item.
174
175       article_code_length
176           Returns the article code length for the ISBN.
177
178       article_code_min
179           Returns the minimum article code length for the publisher code.
180
181       article_code_max
182           Returns the max article code length for the publisher code.
183
184       checksum
185           Returns the checksum code for the ISBN. This checksum may not be
186           valid since you can create an object an fix the checksum later with
187           "fix_checksum".
188
189       is_valid_checksum
190           Returns "Business::ISBN::GOOD_ISBN" for valid checksums and
191           "Business::ISBN::BAD_CHECKSUM" otherwise. This does not guarantee
192           that the rest of the ISBN is actually assigned to a book.
193
194       fix_checksum
195           Checks the checksum and modifies the ISBN to set it correctly if
196           needed.
197
198       as_string(), as_string([])
199           Return the ISBN as a string.  This function takes an optional
200           anonymous array (or array reference) that specifies the placement
201           of hyphens in the string.  An empty anonymous array produces a
202           string with no hyphens. An empty argument list automatically
203           hyphenates the ISBN based on the discovered group and publisher
204           codes.  An ISBN that is not valid may produce strange results.
205
206           The positions specified in the passed anonymous array are only used
207           for one method use and do not replace the values specified by the
208           constructor. The method assumes that you know what you are doing
209           and will attempt to use the least three positions specified.  If
210           you pass an anonymous array of several positions, the list will be
211           sorted and the lowest three positions will be used.  Positions less
212           than 1 and greater than 12 are silently ignored.
213
214           A terminating 'x' is changed to 'X'.
215
216       as_isbn10
217           Returns a new ISBN object. If the object is already ISBN-10, this
218           method clones it. If it is an ISBN-13 with the prefix 978, it
219           returns the ISBN-10 equivalent. For all other cases it returns
220           undef.
221
222       as_isbn13
223           Returns a new ISBN object. If the object is already ISBN-13, this
224           method clones it. If it is an ISBN-10, it returns the ISBN-13
225           equivalent with the 978 prefix.
226
227       increment
228           Returns the next "Business::ISBN" by incrementing the article code
229           of the specified ISBN (object or scalar).
230
231           Returns undef, if the parameter is invalid or equals the maximum
232           possible ISBN for the publisher.
233
234                   $isbn = Business::ISBN->new('1565922573');  # 1-56592-257-3
235                   $next_isbn = $isbn->increment;              # 1-56592-258-1
236
237           If the next article code would exceed the maximum possible article
238           code (such as incrementing 999 to 1000), this returns
239           ARTICLE_CODE_OUT_OF_RANGE as the error.
240
241       decrement
242           Returns the previous "Business::ISBN" by decrementing the article
243           code of the specified ISBN (object or scalar).
244
245           Returns undef, if the parameter is invalid or equals the minimum
246           possible ISBN for the publisher.
247
248                   $isbn = Business::ISBN->new('1565922573');  # 1-56592-257-3
249                   $prev_isbn = $isbn->decrement;              # 1-56592-256-5
250
251           If the next article code would exceed the maximum possible article
252           code (such as incrementing 000 to -1), this returns
253           ARTICLE_CODE_OUT_OF_RANGE as the error.
254
255       png_barcode
256           Returns image data in PNG format for the barcode for the ISBN. This
257           works with ISBN-10 and ISBN-13. The ISBN-10s are automaically
258           converted to ISBN-13.
259
260           This requires "GD::Barcode::EAN13".
261

BUGS

TO DO

264       * i would like to create the bar codes with the price extension
265

SOURCE AVAILABILITY

267       This source is in Github:
268
269           https://github.com/briandfoy/business-isbn
270

AUTHOR

272       brian d foy "<bdfoy@cpan.org>"
273
275       Copyright © 2001-2017, brian d foy <bdfoy@cpan.org>. All rights
276       reserved.
277
278       This module is licensed under the Artistic License 2.0. See the LICENSE
279       file in the distribution, or
280       https://opensource.org/licenses/Artistic-2.0
281

CREDITS

283       Thanks to Mark W. Eichin "<eichin@thok.org>" for suggestions and
284       discussions on EAN support.
285
286       Thanks to Andy Lester "<andy@petdance.com>" for lots of bug fixes and
287       testing.
288
289       Ed Summers "<esummers@cpan.org>" has volunteered to help with this
290       module.
291
292       Markus Spann "<markus_spann@gmx.de>" added "increment" and "decrement".
293
294
295
296perl v5.28.1                      2017-04-24                 Business::ISBN(3)
Impressum