awoken-bible-reference v3.1.2

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:

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 vs gen10v6-10
  • Song of Solomon vs sng
• 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 BibleRefs 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 with new 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