Awoken Bible Reference
Bible verse reference parsing, formating and manipulation
Click for public API reference docs.
Quick Start Guide
Node JS
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.
Browser
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>
var refs = AwokenRef.parseOrThrow('Tobit 1.1'); // error!
var lib = new AwokenRef(myCustomVersificationWithApocrytha);
var myRefs = lib.parseOrThrow('Tobit 1.1'); // success!
</script>
Type Representations
Bible Verses
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 |
interface BibleVerse {
book : string,
chapter : number,
verse : number,
} |
{
"book" : "GEN",
"chapter" : 1,
"verse" : 1,
} |
{
"book" : "REV",
"chapter" : 22,
"verse" : 21,
} |
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
BibleRanges are represented by an object of the form:
/** Representation of continous block of verses */
interface BibleRange {
is_range : true,
start : BibleVerse,
end : BibleVerse,
};
Mixed Sets
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;
Overview of Functionality
API methods include functionality to:
- Parse partial references, ranges, and comma separated lists there of:
Genesis 1:1-10,12, 2:14
EXO 3:1 - DEU 4:1
Matt 1; Luke3.16; Mark 1 v 2-3,5
- Generate verbose human readable reference strings, and compact URL encodable equivalents
-
Genesis 10 v6-10
vsgen10v6-10
-
Song of Solomon
vssng
-
- Validate and fix references, including out of range chapters and verses, and inverted ranges:
-
validate({book: 'GEN', chapter: 51, verse: 1})
becomes
{ message: "Genesis has only 50 chapters", got: 51, max_value: 50, ... }
-
fixErrors({book: 'GEN', chapter: 51, verse: 1})
becomes
{book: 'GEN', chapter: 50, verse: 26}
-
- Sorting a list of references
- Counting the number of verses in a list of
BibleRef
instances - Iterating/Splitting by book/chapter/verse
- Truncating a list of
BibleRef
s to contain only the first N verses (useful for pagination, or short previews of a longer text) - Combining/Simplifying ranges, as well as finding the intersection/union of ranges
For a full list of the exported functions and data types, see the generated typedoc API reference.
Build Targets
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 esbuild -
dist/awoken-ref.esm.mjs
- ESModule loadable via import() in nodejs type=module projects - built via esbuild -
dist/awoken-ref.min.js
- Browser bundle, loadable via<script>
tag, and will create a global AwokenRef variable with attached functions using the default versification, or you can create a new instance withnew AwokenRef(customVersification)
- built via webpack/babel -
dist/types
- Contains typescript declaration (.d.ts) files - package.json is setup such that these should be auto-loaded by typescript consumers of this library