This is a port of the Dart package https://github.com/joshpetit/reference_parser to Elixir.
An Elixir package that parses strings for bible references. You can parse single references or multiple references from a string in a variety of formats.
Really 99% of what you need to know will be found in Parsing References headers. But if you have more complicated needs this package can handle those!
to include this in your Swift application:
import BibleEx
use the parse_references
function to retrieve a single reference:
alias BibleEx.RefParser
refs = RefParser.parse_references("I like Mat 2:4-10 and 1john 3:16")
This will return two reference objects, one describing "Matthew 2:4-10" and the other "1 John 3:16"
Note: The word 'is' will be parsed as the book of Isaiah.
[
%BibleEx.Reference{
book: "Matthew",
book_names: %{abbr: "MAT", name: "Matthew", osis: "Matt", short: "Mt"},
book_number: 40,
reference: "Matthew 2:4-10",
reference_type: :verse_range,
start_chapter: %BibleEx.Chapter{
...
}
...
},
%BibleEx.Reference{
book: "1 John",
book_names: %{abbr: "1JO", name: "1 John", osis: "1John", short: "1 Jn"},
book_number: 62,
reference: "1 John 3:16",
reference_type: :verse,
start_chapter: %BibleEx.Chapter{
...
}
...
]
Reference objects are the broadest kind of reference. You can directly construct one by following this format:
genesis_ref = Reference.new(book: "Genesis", start_chapter: 2, start_verse: 3, end_chapter: 4, end_verse: 5)
%BibleEx.Reference{
book: "Genesis",
book_names: %{abbr: "GEN", name: "Genesis", osis: "Gen", short: "Gn"},
book_number: 1,
reference: "Genesis 2:3 - 4:5",
reference_type: :chapter_range,
start_chapter: %BibleEx.Chapter{
...
}
}
Their most important fields are these:
genesis_ref.reference # The string representation (osis_reference, short_reference, and abbr also available)
genesis_ref.start_verse_number
genesis_ref.end_verse_number
genesis_ref.start_chapter_number
genesis_ref.end_chapter_number
genesis_ref.reference_type # :verse, :chapter, :verse_range, :chapter_range, :book
Based on what is passed in, the constructor will figure out
certain fields. For example, if you were to construct Reference('James')
the last chapter and verse numbers in James will be initialized accordingly.
There are many other fields that may prove useful such as ones that subdivid the reference, look [here](#other-fun stuff)
Reference
objects have a start_verse
and end_verse
field
that return objects of the Verse type.
genbook = Reference.new(book: "Genesis")
first_verse = genbook.start_verse;
# same as first_verse above
first = Verse(book: "Genesis", chapter_number: 1, verse_number: 1)
%BibleEx.Verse{
book: "Genesis",
book_names: %{abbr: "GEN", name: "Genesis", osis: "Gen", short: "Gn"},
book_number: 1,
reference_type: :verse,
reference: "Genesis 1:1",
chapter_number: 1,
verse_number: 1,
is_valid: true
}
You can also construct Reference
s that 'act' like
verses by using the named constructor
gen_11 = Reference.verse(book: "Genesis", chapter: 1, verse: 1)
%BibleEx.Reference{
book: "Genesis",
book_names: %{abbr: "GEN", name: "Genesis", osis: "Gen", short: "Gn"},
book_number: 1,
reference: "Genesis 1:1",
reference_type: :verse,
start_chapter: %BibleEx.Chapter{
...
}
...
}
james5 = RefParser.parse_references("James 5 is a chapter") |> List.first()
The james5
object now holds a Reference
to "James 5". Despite this, start_verse_number and end_verse_number are initialized to the first and last verses in James 5.
james5.start_verse_number # 1
james5.end_verse_number # 20
james5.reference_type # :chapter
The Reference object also has start/end chapter fields
james510 = RefParser.parse_references("James 5-10 is cool") |> List.first()
james510.start_chapter_number # 5
james510.end_chapter_number # 10
Just like verses you can create chapter objects:
john1 = Chapter.new(book: "John", chapter_number: 1)
ecc = RefParser.parse_references("Ecclesiastes is hard to spell") |> List.first()
ecc.start_chapter_number # 1
ecc.end_chapter_number # 12
ecc.reference_type # :chapter_range
Books are the equivalent of a Reference
object.
matt24 = Reference.new(book: "Mat", start_chapter: 2, start_verse: 4)
matt24 = Reference.verse(book: "Mat", chapter: 2, verse: 4)
matt24 = Verse.new(book: "Matt", chapter_number: 2, verse_number: 4)
Note that the verse
object has different fields than a
Reference
object. Check the API.
matt2410 = Reference.new(book: "Mat", start_chapter: 2, start_verse: 4, end_chapter: nil, end_verse: 10)
matt2410 = Reference.verse_range(book: "Mat", chapter: 2, start_verse: 4, end_verse: 10)
These are equivalents that create a reference to 'Matthew 2:4-10'.
All references have an is_valid
field that says whether this reference
is within the bible.
mcd = Reference.new(book: "McDonald", start_chapter: 2, start_verse: 4, end_chapter: 10)
print(mcd.is_valid) # false, as far as I know at least.
Notice that the other fields are still initialized!! So if needed, make sure to check that a reference is valid before using it.
mcd.reference # "McDonald 2:4-10"
mcd.book # "McDonald"
mcd.start_verse_number # 4
mcd.osis_book # nil, and so will be other formats.
The same logic applies to chapters and verse numbers.
jude2 = Reference.new(book: "Jude", start_chapter: 2, start_verse: 10)
jude2.is_valid # false (Jude only has one chapter)
If available in Hex, the package can be installed
by adding bible_ex
to your list of dependencies in mix.exs
:
def deps do
[
{
:bible_ex,
git: "https://github.com/mazz/bible_ex.git", branch: "main"
}
]
end
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/bible_ex.