Returns true if the given book string is a recognized Bible book.

This check uses the canonical, OSIS, and shortened maps in BibleEx.BibleData and does not attempt to correct misspellings.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.check_book(book: "Genesis")
true

iex> Librarian.check_book(book: "Gen")
true

iex> Librarian.check_book(book: "NotABook")
false

Renders a human-readable reference string from its components.

This family of functions builds strings such as:

• "Genesis 1"
• "Genesis 1:1"
• "John 3:16 - 4:3"
• "Genesis 1-2"

Depending on which arguments are provided, the output adjusts to match a conventional Bible reference format. If the inputs are not sufficient to build a reference (for example, missing book and chapter), nil is returned.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.create_reference_string(book: "Genesis", start_chapter: 1)
"Genesis 1"

iex> Librarian.create_reference_string(book: "Genesis", start_chapter: 1, start_verse: 1)
"Genesis 1:1"

iex> Librarian.create_reference_string(book: "John", start_chapter: 3, start_verse: 16, end_chapter: 4, end_verse: 3)
"John 3:16 - 4:3"

Returns the book number (1–66) for a given book identifier.

The book argument may be:

• The full lowercased book name, e.g. "genesis".
• An OSIS identifier, e.g. "gen".
• A shortened/abbreviated key from BibleEx.BibleData.
• A variant key, e.g. "mat" for Matthew.

If the book cannot be resolved, nil is returned.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.find_book_number(book: "Genesis")
1

iex> Librarian.find_book_number(book: "rom")
45

iex> Librarian.find_book_number(book: "NotABook")
nil

Returns all name variants for a book as a map.

The result map contains:

• :osis – OSIS identifier (e.g. "Gen")
• :abbr – Paratext-style abbreviation (e.g. "GEN")
• :name – Full book name (e.g. "Genesis")
• :short – Shortened form (e.g. "Gn")

The book argument may be a name/abbreviation string or a 1-based book number. If the book cannot be resolved, an empty map is returned.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.get_book_names(book: "Genesis")[:name]
"Genesis"

iex> Librarian.get_book_names(book: 45)[:osis]
"Rom"

iex> Librarian.get_book_names(book: "NotABook")
%{}

Returns a list of BibleEx.Chapter structs for a book.

Supported forms:

• get_chapters/1 – all chapters in a book.
• get_chapters/2 – a single chapter.
• get_chapters/3 – a range of chapters.

Chapters outside the valid range are clamped to the book's first/last chapter. Returns nil if the book is invalid.

examples

Examples

iex> alias BibleEx.Librarian
iex> chs = Librarian.get_chapters(book: "Genesis")
iex> length(chs)
50

iex> [ch] = Librarian.get_chapters(book: "Genesis", start_chapter: 1)
iex> ch.chapter_number
1

iex> range = Librarian.get_chapters(book: "Genesis", start_chapter: 1, end_chapter: 3)
iex> Enum.map(range, & &1.chapter_number)
[1, 2, 3]

Returns a BibleEx.Chapter for the last chapter of a book.

Returns nil if the book cannot be resolved.

examples

Examples

iex> alias BibleEx.Librarian
iex> ch = Librarian.get_last_chapter(book: "Psalms")
iex> ch.chapter_number
150

Returns the number of chapters in a book.

The book argument may be a name/abbreviation string or a book number. If the book is not recognized, nil is returned.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.get_last_chapter_number(book: "Genesis")
50

iex> Librarian.get_last_chapter_number(book: "NotABook")
nil

Builds a BibleEx.Verse struct for the last verse of a book or chapter.

When only book is given, the verse is the last verse of the last chapter. When chapter is given, the verse is the last verse of that chapter.

Returns nil if the book or chapter cannot be resolved.

examples

Examples

iex> alias BibleEx.Librarian
iex> last = Librarian.get_last_verse(book: "Jude")
iex> {last.chapter_number, last.verse_number}
{1, v} when v > 0

iex> Librarian.get_last_verse(book: "NotABook")
nil

Returns the last verse number for a given book, or for a specific chapter.

When only book is given, the last verse in the final chapter is returned. When chapter is given, the last verse in that chapter is returned, or nil if the chapter is out of range.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.get_last_verse_number(book: "Genesis", chapter: 1) > 0
true

iex> Librarian.get_last_verse_number(book: "Revelation")
v when is_integer(v) and v > 0

iex> Librarian.get_last_verse_number(book: "Genesis", chapter: 999)
nil

Returns all verses in a chapter as a list of BibleEx.Verse structs.

When only book and chapter are given, the entire chapter is returned. When start_verse and/or end_verse are given, a subrange of verses is returned.

Returns nil if the book or chapter is invalid, or if the requested range is out of bounds (e.g. start_verse > end_verse).

examples

Examples

iex> alias BibleEx.Librarian
iex> verses = Librarian.get_verses(book: "Genesis", chapter: 1)
iex> hd(verses).reference
"Genesis 1:1"

iex> range = Librarian.get_verses(book: "Genesis", chapter: 1, start_verse: 1, end_verse: 3)
iex> Enum.map(range, & &1.verse_number)
[1, 2, 3]

Infers the type of a reference (:book, :chapter, :verse, :chapter_range, :verse_range).

This set of overloads allows calling with increasing specificity:

• identify_reference_type/1 – book only.
• identify_reference_type/2 – book and start chapter.
• identify_reference_type/3 – book, start chapter, start verse.
• identify_reference_type/4 – plus end chapter.
• identify_reference_type/5 – plus end verse.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.identify_reference_type(book: "Genesis")
:book

iex> Librarian.identify_reference_type(book: "Genesis", start_chapter: 1)
:chapter

iex> Librarian.identify_reference_type(book: "Genesis", start_chapter: 1, start_verse: 1)
:verse

iex> Librarian.identify_reference_type(book: "Genesis", start_chapter: 1, end_chapter: 2)
:chapter_range

iex> Librarian.identify_reference_type(book: "Genesis", start_chapter: 1, start_verse: 1, end_chapter: 1, end_verse: 5)
:verse_range

Validates a fully-specified reference, including optional start and end chapters and verses.

This is the most general form and checks that:

• The book exists.
• The start and end chapters are within range and ordered correctly.
• The start and end verses, if present, are within their chapter ranges and ordered correctly relative to each other and the chapter range.

It returns true for structurally valid references and false otherwise; it does not check theological or translation-specific constraints.

examples

Examples

iex> alias BibleEx.Librarian
iex> Librarian.verify_reference(book: "John", start_chapter: 3, start_verse: 16, end_chapter: 4, end_verse: 3)
true

iex> Librarian.verify_reference(book: "Genesis", start_chapter: 50, start_verse: 1, end_chapter: 49, end_verse: 10)
false