verse-reference-regex

Provides:

1. A regular expression that matches Bible verse references and ranges
2. A function that parses the captured groupings of that regular expression and returns it in a useful form

API

``
const {
createRegex,
extractRangeFromMatch,
createChapterVerseRangeRegex
} = require('verse-reference-regex')

// or, ESM
import {
createRegex,
extractRangeFromMatch,
createChapterVerseRangeRegex
} from 'verse-reference-regex'
`

createRegex({ requireVerse = false, flags = 'i', books = canonBooks })

createRegex takes in a map of options and returns a regular expression.

$3

- requireVerse: if true, will only match references with a verse. If false, will match references and ranges with chapter numbers only, like Genesis 1 or Gen. 2-3. Defaults to false.
- flags: flags to be used to create the RegExp. If you want to use the regex to match more than one reference in a string, you'll probably want to pass in 'ig'. Defaults to 'i'.
- books: an array of books with their aliases. Defaults to books-of-the-bible.

extractRangeFromMatch(match, books = canonBooks)

Given a result array, like the ones returned by exec or match, it will return an object that looks like this:

`json
{
"book": "Genesis",
"start": {
"chapter": 2,
"verse": null,
"section": null
},
"end": {
"chapter": 3,
"verse": null,
"section": null
}
}
`

createChapterVerseRangeRegex({ requireVerse = false, flags = 'i' })

Matches only the chapter/verse range portion of a reference.

Use extractRangeFromMatch.extractRangeFromMatch(match) to read the values out of the match object.

`js
const chapterVerseRegex = createChapterVerseRangeRegex()

const chapterVerseMatch = Tell me about 12:30-14:1a y'all.match(chapterVerseRegex)

const output = extractRangeFromMatch.chapterVerseRange(chapterVerseMatch)
const expected = {
book: null,
start: { chapter: 12, verse: 30, section: null },
end: { chapter: 14, verse: 1, section: 'a' }
}
output // => expected
`

Examples

`js
function rangeString(range) {
const { start, end } = range
return ${range.book} c${start.chapter}v${start.verse}s'${start.section}' to
+ c${end.chapter}v${end.verse}s'${end.section}'
}

const verseRequiringRegex = createRegex({ requireVerse: true })
`

Searching for ranges:

`js
const match = I'm talking about Prov 30:2-3 yo.match(verseRequiringRegex)

rangeString(extractRangeFromMatch(match)) // => Proverbs c30v2s'null' to c30v3s'null'

const match2 = I'm not talking about Proverbs 30-31 at all, yo!.match(verseRequiringRegex)

match2 // => null
`

A verse reference with no range:

`js
const match3 = Psalm 119:120b - I am afraid of Your judgments.match(verseRequiringRegex)

rangeString(extractRangeFromMatch(match3)) // => Psalms c119v120s'b' to c119v120s'b'
`

Matching verse sections identified by letters:

`js
const match4 = verseRequiringRegex.exec(Proverbs 30:2a-b really speaks to me)

rangeString(extractRangeFromMatch(match4)) // => Proverbs c30v2s'a' to c30v2s'b'
`

Matching ranges with only chapters, no verse numbers:

`js
const match5 = createRegex().exec(Doesn't require a verse to find the range Prov. 30-31)
const range = extractRangeFromMatch(match5)

range.book // => 'Proverbs'
range.start.chapter // => 30
range.start.verse // => null
range.end.chapter // => 31
`

Replacing verse references with arbitrary text:

`js
const replaced = Tell me about Rev. 1:1-4a will you.replace(verseRequiringRegex, (...args) => {
const match = args.slice(0, args.length - 2)
return rangeString(extractRangeFromMatch(match))
})
replaced // => Tell me about Revelation c1v1s'null' to c1v4s'a' will you
``

Book names

Book aliases (including ones with trailing periods) will be matched and normalized. You can find the default list of normalized book names and their aliases in the books-of-the-bible repository.

Other

Chapter/verse numbers and ranges are not validated.

If you find a verse range that you think should be matched but is not, add it to the list in test.js and open a pull request.

Any changes to the default book aliases will be published as minor/feature version bumps.

Licensed WTFPL.