Manual of Lua-ISBN

Lua-ISBN - Lua 5.1 module for parsing and checking ISBN numbers

Overview

This module allows you to check whether ISBN numbers are valid, to extract the different parts from them, and to format them with the standard arrangement of hyphens. It works with ISBN-10 and ISBN-13 values (the old ten digit codes, and the newer thirteen digit ones which are now starting to appear on books), and can convert between them.

Loading the module

The ISBN module doesn't install itself into any global tables, so you can decide what name you want to use to access it. You will probably want to load it like this:

local ISBN = require "isbn"

You can use a variable called something other than ISBN if you'd like, or you could assign the table returned by require to a global variable. In this documentation we'll assume you're using a variable called ISBN. The capital letters help to distinguish the class name from variables.

Creating ISBN objects and testing validity

You have to create an ISBN object before you can do anything else, by calling the module as a function and passing it an ISBN number as a string. If the number is valid it will return an object representing it, otherwise it will return nil and a short error message indicating what the problem was. For example, if foo contains a string:

-- Valid, yes or no
if not ISBN(foo) then
    error("bad ISBN")
end

-- Assume it's valid
local isbn = assert(ISBN(foo))
print(isbn)

-- Extra info for debugging
local isbn, err = ISBN(foo)
if isbn then
    print("good ISBN:", isbn)
else
    print("bad ISBN:", err)
end

The error message is only really intended to help you debug problems. If you want to report back to a user I'd suggest simply telling them that they gave you an invalid ISBN.

ISBN objects are immutable, so once you've created one you can't change the value inside.

You can give an extra argument to the constructor function if you want to change how it checks validity. It should be a string indicating what mode you want to use.

-- This will work, the extra text is ignored
local isbn = ISBN("foo: 0936756764")

-- Returns nil, the extra text isn't allowed
local isbn = ISBN("foo: 0936756764", "strict")

-- OK, even in strict mode whitespace and '-' allowed
local isbn = ISBN("0-936756-76 4", "strict")

-- Returns nil, wrong checksum digit
local isbn = ISBN("0936756769")

-- OK, checksum corrected
local isbn = ISBN("0936756769", "fix-checksum")

The modes allowed are:

normal (default)

Allows extra characters to appear in your ISBN value (anything that's not a digit or the letter x), which are ignored.

strict

Extra characters that are normally to be found in an ISBN number (whitespace and hyphens) are ignored, but if any other unexpected characters are found then the value is considered to be invalid.

fix-checksum

Same as normal, except that if the checksum digit at the end of the ISBN is wrong, or missing, then the value is adjusted to have the correct checksum.

In any mode the value is handled case insensitively, so if you give it an ISBN-10 value ending in an X checksum digit, it won't matter if it's lowercase or uppercase. ISBN-13 values never have an X as their checksum, but if you use fix-checksum mode it will still be corrected properly.

Formatting ISBN values with hyphens

There's a standard way of formatting an ISBN value with hyphens separating the various parts. The ISBN module will do this when you convert ISBN objects to strings with the Lua tostring function. You can get the raw digits with the isbn() method (which will return a string of exactly ten or thirteen characters).

local book1 = ISBN("0-936756-76 4")
print(book1:isbn()) -- 0936756764

local book2 = ISBN("0450055949")

-- Print calls 'tostring' automatically
print(book1)    -- 0-936756-76-4
print(book2)    -- 0-450-05594-9

-- You can also use it directly
local str = tostring(book1)

(In this case one of the hyphens appears in a different place for book2 because it comes from a bigger publisher, and they need more numbers to play with in the third part which identifies individual books.)

Extracting information

You can extract the individual parts of an ISBN value by calling methods on an ISBN object:

local book = ISBN("0450055949")

print(book:group_code())     -- "0"
print(book:group_name())     -- "English speaking area"
print(book:publisher_code()) -- "450"
print(book:article_code())   -- "05594"
print(book:checksum())       -- "9"

Note that the group_name() method returns a string based on what ISBN International call the different groups, but I don't know if these values have much significance. They may change in future versions of this module.

You can also get the three-digit prefix at the start of an ISBN-13 value (but this will always be empty string for ISBN-10 values):

local book13 = ISBN("9780450055942")
print(book:prefix())    -- ""
print(book13:prefix())  -- "978"

Converting between ISBN-10 and ISBN-13

All ISBN-10 values can be converted into an equivalent ISBN-13 with the prefix code 978. You can do this with the as_isbn13() method. Calling it on an object which already contains an ISBN-13 value will simple return the same object.

local book10 = ISBN("0450055949")
local book13 = book10:as_isbn13()
print(book13)   -- 978-0-450-05594-2

You can also use the as_isbn10() method to convert an ISBN-13 value into the equivalent ISBN-10 one, but this won't work for any ISBN-13 value with a prefix other than 978 (in which case the method will return nil).

local book13 = ISBN("9780450055942")
local book10 = book13:as_isbn10()
print(book10)   -- 0-450-05594-9

Comparing ISBN numbers

You can test whether two ISBN values are equivalent with the == and ~= operators or the eq() method. If you have two ISBN objects (not plain Lua strings) you can do this:

if isbn1 == isbn2 then ...
if isbn1 ~= isbn2 then ...

or if you've got one object you can pass it a string or object to compare with:

local isbn = ISBN(...)
if isbn:eq(other) then ...

These comparisons will return true for two equivalent ISBN values even if one is an ISBN-10 and the other an ISBN-13 value.

Copyright

The Lua-ISBN code was originally based on the Perl modules ISBN::Business and ISBN::Business::Data by brian d foy , but is now a completely new implementation with a simpler structure and much less code.

This software and documentation is Copyright © 2007 Geoff Richards <geoff at this domain dot co dot uk>. It is free software; you can redistribute it and/or modify it under the terms of the Lua 5.0 license. The full terms are given in the file COPYRIGHT supplied with the source code package, and are also available here: http://www.lua.org/license.html