Module:Format ISBN/doc

This module checks and formats ISBNs. By convention, printed ISBNs use either hyphens or spaces to separate the elements within the number. The module accepts a string that represents an ISBN, and returns a formatted ISBN string. To format, the input ISBN must be valid. That is:
 * it must be 10 or 13 characters long after removing any existing hyphen or space formatting; and
 * for 13 character ISBNs, all the characters must be digits, and it must start with 978 or 979;
 * for 10 character ISBNs, all the characters except the final one must be digits, and the final character must be either a digit or X;
 * and, the final character must be the correct check digit.

The module's public functions are format and is_isbn for template use, and _format and _is_isbn for direct Lua calls.

The formatted ISBN uses hyphens or spaces, with hyphens as the default. The default prefix is ISBN, but the prefix is settable. ISBNs with 10 characters may optionally be converted to equivalent 13 character ISBNs. ISBNs with 13 characters and which start with "978" may optionally be converted to equivalent 10 character ISBNs. For invalid input ISBNs, the error return value is settable, and the default is ISBN error.

Usage
To format an ISBN, invoke with:

Parameters:
 * isbn: The ISBN to format. Must be supplied. Should be a valid 10 character or 13 character ISBN.
 * prefix: ISBN format prefix. Optional. Default is ISBN. If not empty, it is separated from the ISBN by.
 * use_spaces (or spaces): Indicate formatting with spaces instead of hyphens. Boolean. Optional. Default is false.
 * use_conversion (or convert): Convert 10 character ISBNs to 13 character ones before formatting. Boolean. Optional. Default is false. This parameter has no effect if the input ISBN is a 13 character one.
 * use_down_conversion (or convert_down): Convert 13 character ISBNs to 10 character ones before formatting. Boolean. Optional. Default is false. This parameter has no effect if the input ISBN is a 10 character one. Only 13 character ISBNs starting with "978" have an equivalent 10 character ISBN. An attempt to convert a 13 character ISBN starting with "979" returns an error.
 * error: Return value to use in place of ISBN error. Optional.
 * use_link (or link): Link the displayed ISBN to Special:BookSources. Optional. Useful where prefix is not ISBN.

Parameters may also be supplied by position, in the order shown above. If using positional parameters, a shorthand way to set prefix to the empty string is to follow the positional isbn with a single pipe character. For example, equivalent to.

To validate an ISBN, invoke with:

Parameters:
 * isbn: The string to check for ISBN validity.
 * valid: Return value if the input ISBN is valid. Optional. Default is true.
 * invalid: Return value if the input ISBN is invalid. Optional. Default is an empty string (no output).

Parameters may also be supplied by position, in the order shown above. The default return values allow wikitext to check for ISBNs with.

Examples
Formatting:
 * Using results in:
 * Using results in:
 * Using results in:
 * Using results in:

Validation:
 * Using results in:
 * Using results in:

Technical notes
For efficiency, this module lazy-loads its table data using mw.loadData rather than Lua's require. Data loaded this way has some severe limitations. Several Lua features will not work correctly with it. And worse, these features do not fail, but rather they return incorrect or misleading results. For example #value always returns zero no matter how many elements the item contains, and unpack returns nil.

When editing this module, be very careful to ensure that the Lua language feature you are using will work correctly with a data set that is loaded in this way.

For invocations from wikitext, this module retrieves arguments selectively:
 * For format, if called by a wrapper named Template:Format ISBN, it uses arguments only from the parent frame, otherwise only from the caller frame.
 * For is_isbn, it uses arguments only from the caller frame. This function has no wrapper template.