Bible verse reference parsing, formating and manipulation
Click for public API reference docs.
To use the default versification scheme, simple import the libary and use the global API functions.
import AwokenRef from 'awoken-bible-reference';
let vref = AwokenRef.parseOrThrow('Genesis 1');
if(AwokenRef.countVerses(vref) > 10)){
vref = AwokenRef.firstNVerses(vref, 10);
}
vref = AwokenRef.getIntersection(vref, AwokenRef.parseOrThrow('GEN 1 v6,9-20'));
// Print as human readable verse reference (IE: "Genesis 1:6,9-10")
console.log(AwokenRef.format(vref));
// Print as url encodable reference (IE: "gen1v6,9-10")
console.log(AwokenRef.format(vref, { url: true }));
// Inspect the object, will yield:
// [ { book: 'GEN', chapter: 1, verse: 6 },
// { is_range : true,
// start : { book: 'GEN', chapter: 1, verse: 9 },
// end : { book: 'GEN', chapter: 1, verse: 10 },
// }
// ]
console.dir(vref);
Non-standard versification schemes can be used by instead creating an instance of the library. This allows support to be added for the Apocrypha, or translations that use a different split of verses per chapter.
import __AwokenRef__ from 'awoken-bible-reference';
const AwokenRef = new __AwokenRef__(my_versificaton);
let vref = AwokenRef.parse('MyBook 100:999');
The full list of methods on the AwokenRef
object can be found in the API docs.
If using plain javascript in the browser with no build-system to bundle your dependencies, you may simply reference the file found in ./dist.browser/awoken-ref.js
.
This will create a global "AwokenRef` variable, which can be used as both an instance of the library, and a constructor to create new instances with non-default versification schemes.
<script src="[path]/awoken-ref.js"/></script>
awoken-bible-reference
can represent (and convert between) the following representations of a Bible verse:
What | Typescript Type | Example 1 | Example 2 |
---|---|---|---|
Human readable string | string | Genesis 1:1 | Revelation 22:21 |
Verse Index | number | 0 | 33021 |
JSON |
|
|
|
Note that the verse index representation should be avoided unless you are sure that all translations you care about utalize the exact same versification scheme. While it is useful for assigning unique IDs and computing offsets etc, it should probably not be used as a portable data exchange format.
The book
field is always a 3 character mix of upper case letters and digits, as per the USFM specification.
BibleRanges are represented by an object of the form:
/** Representation of continous block of verses */
interface BibleRange {
is_range : true,
start : BibleVerse,
end : BibleVerse,
};
Note that most API function can take either BibleRange
or BibleVerse
objects (or lists thereof), and thus the is_range
field can be used to easily distinguish the types from one another.
The following union type is also exported for convenience:
/** Generic reference to verse or range */
type BibleRef = BibleVerse | BibleRange;
API methods include functionality to:
Genesis 1:1-10,12, 2:14
EXO 3:1 - DEU 4:1
Matt 1; Luke3.16; Mark 1 v 2-3,5
Genesis 10 v6-10
vs gen10v6-10
Song of Solomon
vs sng
validate({book: 'GEN', chapter: 51, verse: 1})
{ message: "Genesis has only 50 chapters", got: 51, max_value: 50, ... }
fixErrors({book: 'GEN', chapter: 51, verse: 1})
{book: 'GEN', chapter: 50, verse: 26}
BibleRef
instancesBibleRef
s to contain only the first N verses (useful for pagination, or short previews of a longer text)For a full list of the exported functions and data types, see the generated typedoc API reference.
The published copy of this library multiple output targets. Node.js projects should autoload the correct version, and there also exists a browser bundle.
dist/awoken-ref.cjs.js
- CommonJS module loadable via require() in nodejs project - built via esbuilddist/awoken-ref.esm.mjs
- ESModule loadable via import() in nodejs type=module projects - built via esbuilddist/awoken-ref.min.js
- Browser bundle, loadable via