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

BUGS

TO DO

269       * i would like to create the bar codes with the price extension
270

SOURCE AVAILABILITY

272       This source is in Github:
273
274           https://github.com/briandfoy/business-isbn
275

AUTHOR

277       brian d foy "<bdfoy@cpan.org>"
278
280       Copyright © 2001-2023, brian d foy <bdfoy@cpan.org>. All rights
281       reserved.
282
283       This module is licensed under the Artistic License 2.0. See the LICENSE
284       file in the distribution, or
285       https://opensource.org/licenses/Artistic-2.0
286

CREDITS

288       Thanks to Mark W. Eichin "<eichin@thok.org>" for suggestions and
289       discussions on EAN support.
290
291       Thanks to Andy Lester "<andy@petdance.com>" for lots of bug fixes and
292       testing.
293
294       Ed Summers "<esummers@cpan.org>" has volunteered to help with this
295       module.
296
297       Markus Spann "<markus_spann@gmx.de>" added "increment" and "decrement".
298
299
300
301perl v5.38.0                      2023-07-20                 Business::ISBN(3)
Impressum