Data.ISBN

Introduction

This library contains tools for validating and working with International Standard Book Numbers (ISBNs). An ISBN value can be in either the format of a ten digit ISBN-10 or a thirteen digit ISBN-13. This library uses a single ISBN data type with two value constructors to represent ISBN values, so that a single entry point can be used to validate text inputs as either an ISBN10, ISBN13, or neither.

For most users, importing only the Data.ISBN module is necessary, as this module re-exports all of the data types and functions necessary for validating, creating, and converting between ISBN values.

Documentation

data ISBN

Data type for representing ISBN values. Values of this type should be created safely using validateISBN, which will produce ISBN10 or ISBN13 values after validating the input.

The validateISBN10 and validateISBN13 functions can also be used to only attempt to create ISBNs of a specific type.

To create ISBN values without validation, use the unsafeToISBN10 and unsafeToISBN13 functions to coerce Text values into ISBN values.

Instances

Show ISBN

Defined in Data.ISBN.Types

Methods

showsPrec :: Int -> ISBN -> ShowS

show :: ISBN -> String

showList :: [ISBN] -> ShowS

Eq ISBN

Defined in Data.ISBN.Types

Methods

(==) :: ISBN -> ISBN -> Bool

(/=) :: ISBN -> ISBN -> Bool

NOTE: This module does not export the constructors in the ISBN type. For access to the constructors, import the Data.Types.ISBN module.

renderISBN :: ISBN -> Text

Convert an ISBN value to a Text string. Can be used when displaying an ISBN in an application interface or before storing the plain ISBN text values in a database.

ISBN values created using validateISBN, validateISBN10, or validateISBN13 will never contain hyphens.

Examples:

renderISBN (ISBN10 "080701429X")    == "080701429X"
renderISBN (ISBN13 "9780060899226") == "9780060899226"

ISBN Validation

validateISBN :: Text -> Either ISBNValidationError ISBN

Used to safely create ISBN values. Assumes that the Text input is an ISBN-10 or ISBN-13 string, either with or without hyphens.

Will return either a validated ISBN or an ISBNValidationError, which can be rendered as a descriptive string using renderISBNValidationError.

Examples:

validateISBN "0345816021"        == Right (ISBN10 "0345816021")
validateISBN "0-807-01429-X"     == Right (ISBN10 "080701429X")
validateISBN "9780807014295"     == Right (ISBN13 "9780807014295")
validateISBN "978-0-306-40615-7" == Right (ISBN13 "9780306406157")
validateISBN "0-345-816"         == Left InvalidISBNInputLength
validateISBN "X-345-81602-1"     == Left IllegalCharactersInISBN10Body
validateISBN "0-345-81602-B"     == Left IllegalCharacterAsISBN10CheckDigit
validateISBN "0-345-81602-3"     == Left InvalidISBN10CheckDigit
validateISBN "00000000000000"    == Left InvalidISBNInputLength
validateISBN "9780807014299"     == Left InvalidISBN13CheckDigit
validateISBN "0X00000000000"     == Left IllegalCharactersInISBN13Input

ISBN Validation Errors

data ISBNValidationError

Possible validation errors resulting from ISBN validation. Can be rendered as a descriptive error message using renderISBNValidationError.

Constructors

InvalidISBNInputLength

The length of the input string is not 10 or 13 characters, not counting hyphens

IllegalCharactersInISBN10Body

The first nine characters of the ISBN-10 input contain non-numeric characters

IllegalCharactersInISBN13Input

The ISBN-13 input contains non-numeric characters

IllegalCharacterAsISBN10CheckDigit

The check digit of the ISBN-10 is not a valid character (0-9 or 'X')

InvalidISBN10CheckDigit

The check digit is not valid for the given ISBN-10

InvalidISBN13CheckDigit

The check digit is not valid for the given ISBN-13

Instances

Show ISBNValidationError

Defined in Data.ISBN

Methods

showsPrec :: Int -> ISBNValidationError -> ShowS

show :: ISBNValidationError -> String

showList :: [ISBNValidationError] -> ShowS

Eq ISBNValidationError

Defined in Data.ISBN

Methods

(==) :: ISBNValidationError -> ISBNValidationError -> Bool

(/=) :: ISBNValidationError -> ISBNValidationError -> Bool

renderISBNValidationError :: ISBNValidationError -> Text

Convert an ISBNValidationError into a human-friendly error message.

Validating only ISBN-10

validateISBN10 :: Text -> Either ISBN10ValidationError ISBN

Used to safely create ISBN10 values represented by the ISBN data type. Assumes that the Text input is an ISBN-10 string, either with or without hyphens.

Will return either a validated ISBN-10 or an ISBN10ValidationError, which can be rendered as a descriptive string using renderISBN10ValidationError.

Examples:

validateISBN10 "0-345-81602-1" == Right (ISBN10 "0345816021")
validateISBN10 "0345816021"    == Right (ISBN10 "0345816021")
validateISBN10 "0-807-01429-X" == Right (ISBN10 "080701429X")
validateISBN10 "0-345-816"     == Left ISBN10InvalidInputLength
validateISBN10 "X-345-81602-1" == Left ISBN10IllegalCharactersInBody
validateISBN10 "0-345-81602-B" == Left ISBN10IllegalCharacterAsCheckDigit
validateISBN10 "0-345-81602-3" == Left ISBN10InvalidCheckDigit

ISBN-13 Validation Errors

data ISBN10ValidationError

Possible validation errors resulting from ISBN-10 validation.

Instances

Show ISBN10ValidationError

Defined in Data.ISBN.ISBN10

Methods

showsPrec :: Int -> ISBN10ValidationError -> ShowS

show :: ISBN10ValidationError -> String

showList :: [ISBN10ValidationError] -> ShowS

Eq ISBN10ValidationError

Defined in Data.ISBN.ISBN10

Methods

(==) :: ISBN10ValidationError -> ISBN10ValidationError -> Bool

(/=) :: ISBN10ValidationError -> ISBN10ValidationError -> Bool

renderISBN10ValidationError :: ISBN10ValidationError -> Text

Convert an ISBN10ValidationError into a human-friendly error message.

Validating only ISBN-13

validateISBN13 :: Text -> Either ISBN13ValidationError ISBN

Used to safely create ISBN13 values represented by the ISBN data type. Assumes that the Text input is an ISBN-13 string, either with or without hyphens.

Will return either a validated ISBN-13 or an ISBN13ValidationError, which can be rendered as a descriptive string using renderISBN13ValidationError.

Examples:

validateISBN13 "9780345816023"     == Right (ISBN13 "9780345816023")
validateISBN13 "9780807014295"     == Right (ISBN13 "9780807014295")
validateISBN13 "9780306406157"     == Right (ISBN13 "9780306406157")
validateISBN13 "978-0-306-40615-7" == Right (ISBN13 "9780306406157")
validateISBN13 "9780345816029"     == Left ISBN13InvalidCheckDigit
validateISBN13 "9780807014299"     == Left ISBN13InvalidCheckDigit
validateISBN13 "00000000000000"    == Left ISBN13InvalidInputLength
validateISBN13 "0X00000000000"     == Left ISBN13IllegalCharactersInInput

ISBN-10 Validation Errors

data ISBN13ValidationError

Possible validation errors resulting from ISBN-13 validation.

Constructors

ISBN13InvalidInputLength

The length of the input string is not 13 characters, not counting hyphens

ISBN13IllegalCharactersInInput

The ISBN-13 input contains non-numeric characters

ISBN13InvalidCheckDigit

The check digit is not valid for the given ISBN-13

Instances

Show ISBN13ValidationError

Defined in Data.ISBN.ISBN13

Methods

showsPrec :: Int -> ISBN13ValidationError -> ShowS

show :: ISBN13ValidationError -> String

showList :: [ISBN13ValidationError] -> ShowS

Eq ISBN13ValidationError

Defined in Data.ISBN.ISBN13

Methods

(==) :: ISBN13ValidationError -> ISBN13ValidationError -> Bool

(/=) :: ISBN13ValidationError -> ISBN13ValidationError -> Bool

renderISBN13ValidationError :: ISBN13ValidationError -> Text

Convert an ISBN13ValidationError into a human-friendly error message.

Conversion between ISBN-10 and ISBN-13

ISBN values can be converted from ISBN-10 to ISBN-13 and vise versa.

convertISBN10toISBN13 :: ISBN -> ISBN

Convert an ISBN-10 to an ISBN-13. Since all ISBN-10s can be converted to ISBN-13s, this operation cannot fail.

Example:

convertISBN10toISBN13 (unsafeToISBN10 "0060899220") == ISBN13 "9780060899226"

convertISBN13toISBN10 :: ISBN -> Maybe ISBN

Convert an ISBN-13 to an ISBN-10. Since only ISBN-13s starting with '978' can be converted, this operation may fail.

Example:

convertISBN13toISBN10 (unsafeToISBN13 "9780060899226") == Just (ISBN10 "0060899220")

ISBN Helpers

isISBN10 :: ISBN -> Bool

Determines whether an ISBN value is an ISBN-10.

Examples:

isISBN10 (unsafeToISBN10 "0060899220")    == True
isISBN10 (unsafeToISBN13 "9780060899226") == False

Since: 1.1.0.0

isISBN13 :: ISBN -> Bool

Determines whether an ISBN value is an ISBN-13.

Examples:

isISBN13 (unsafeToISBN10 "0060899220")    == False
isISBN13 (unsafeToISBN13 "9780060899226") == True

Since: 1.1.0.0

Creating ISBN values without validation

In most cases, creating ISBN10 and ISBN13 values should be performed using the validateISBN, validateISBN10, or validateISBN13 functions, which ensure the ISBN values they produce are valid.

The functions below allow for the creation of ISBN values without any validation. They should only be used in specific cases. For example, when loading already-validated ISBN values stored in a text column in a database.

unsafeToISBN10 :: Text -> ISBN

Will create an ISBN10 value without any validation.

unsafeToISBN13 :: Text -> ISBN

Will create an ISBN13 value without any validation.