Manual of Lua-ISBN: issn

Manual of Lua-ISBN: issn

Lua-ISSN - Lua 5.1 module for parsing and checking ISSN codes

Overview

This module allows you to check whether ISSN numbers are valid, to calculate or correct their checksum digits, and to format them with or without the hyphen in the standard place.

This is part of the Lua-ISBN package, and has a very similar interface to the isbn module itself.

Loading the module

When you load the module, store its table into a variable like this: 

local ISSN = require "issn"

Creating ISSN objects and testing validity

You have to create an ISSN object before you can do anything else, by calling the module as a function and passing it an ISSN 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 ISSN(foo) then
    error("bad ISSN")
end

-- Assume it's valid
local issn = assert(ISSN(foo))
print(issn)

-- Extra info for debugging
local issn, err = ISSN(foo)
if issn then
    print("good ISSN:", issn)
else
    print("bad ISSN:", 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 ISSN.

ISSN 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 issn = ISSN("foo: 02613077")

-- Returns nil, the extra text isn't allowed
local issn = ISSN("foo: 02613077", "strict")

-- OK, even in strict mode whitespace and '-' allowed
local issn = ISSN("026-130 77", "strict")

-- Returns nil, wrong checksum digit
local issn = ISSN("02613076")

-- OK, checksum corrected
local issn = ISSN("02613076", "fix-checksum")

The modes allowed are:

normal (default)

Allows extra characters to appear in your ISSN 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 ISSN 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 ISSN 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 value ending in an X checksum digit, it won't matter if it's lowercase or uppercase.

Formatting ISSN values

The normal way to present an ISSN code is with a single hyphen in the middle. The __tostring metamethod will use this format: 

local str = tostring(issn)

print("with a hyphen:", issn)

Calling tostring on an ISSN object will always return a nine character string where the middle character is a hyphen.

To extra the digits without any extra punctuation, call the issn method. This will always return an eight character string: 

print("without a hyphen:", issn:issn())

You can extract just the checksum digit with the checksum method, which will always return a single character string. It will either be a decimal digit or the uppercase letter X.

Comparing ISSN numbers

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

if issn1 == issn2 then ...
if issn1 ~= issn2 then ...

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

local issn = ISSN(...)
if issn:eq(other) then ...

Copyright

This software and documentation is Copyright © 2008 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