Options
All
  • Public
  • Public/Protected
  • All
Menu

awoken-bible-reference

Index

Enumerations

Interfaces

Type aliases

Variables

Functions

Type aliases

BibleRef

BibleRef: BibleVerse | BibleRange

Union type that represents any continous section of bible, including a single verse, to a span of text over multiple chapters/books

BibleRefLibConstructor

BibleRefLibConstructor: (v: Versification) => BibleRefLib

Constructor interface

We are using a hybrid interface to this lib, you can just require(lib) and call function such as parse, parseOrThrow, etc - or you can construct a new instance with a non standard versification scheme and then call methods of that

Type declaration

FormatArg

FormatArg: FormatOptions | string

Set of arguments that can be passed to represent a formatting scheme

Either a full FormatOptions object describing the options, or a present name such as "osis" for OSIS formatted references

Present name can be combined with :, eg: url:combined to use url formatting, and combine ranges Later presets override earlier presets

For a full list of present names, see FormatPreset

FormatPreset

FormatPreset: "osis" | "url" | "compact" | "lowercase" | "combined"

Enumeration of possible format presets

  • osis -> uses . separators and osis book ids, eg: "Gen.1.1"
  • url -> uses url safe separators and usfm book ids, eg: gen1v1_exo1v2-3
  • compact -> sets the compact flag to true
  • lowercase -> sets the lowercase flag to true
  • combined -> sets the combine_ranges flag to true
  • complete -> sets the complete_refs flag to true

IntersectionSet

IntersectionSet: { segments: LineSegment[] }

Opaque type containing data for use by getIntersection or intersects

Type declaration

  • segments: LineSegment[]

ParseResult

ParseResult: ParseResultSuccess | ParseResultFailure

Represents the output of attempting to parse a string containing a Bible reference Check the status field to see if the parse succeeded, and then utalize the fields of ParseResultSuccess and ParseResultFailure as appropriate

ValidationError

ValidationError: { got: string; is_warning: false; kind: BadBook; message: string; ref: BibleVerse } | { got: number; is_warning: false; kind: BadVerse | BadChapter; max_value: number; message: string; ref: BibleVerse } | { component: "book" | "chapter" | "verse"; is_warning: false; kind: BackwardsRange; message: string; ref: BibleRange } | { is_warning: true; kind: RangeOfOne; message: string; ref: BibleRange }

Represents an error which was detected during validation

Variables

Const VERSIFICATION

VERSIFICATION: Versification = createVersification(default_data)

Functions

combineRanges

  • Generates the most compressed representation possible of some set of BibleVerses/BibleRanges by combining adjacent or overlapping ranges into larger ones

    For example, an input list of "Gen 1", "Gen 2", "Gen 3", would produce a single BibleRange for "Gen 1-3"

    Order of input ranges in unimportant, since this functional will interally call sort first

    Parameters

    • this: BibleRefLibData
    • refs: BibleRef[]

    Returns BibleRef[]

contains

countVerses

  • countVerses(v: Versification, ref: BibleRef): number

  • Counts the total number of verses expressed by a BibleRef

    Parameters

    Returns number

createIntersectionSet

  • Precomputes data regarding BibleRef list as used by getIntersection and intersects

    This is more performant if you call either of these functions multiple times where one of the two inputs remains constant

    Parameters

    Returns IntersectionSet

createVersification

  • createVersification(data: BookMetaRaw[]): Versification

  • Creates a full Versification object from the minimal data set by computing the rest

    Parameters

    • data: BookMetaRaw[]

    Returns Versification

firstNVerses

  • Takes a list of BibleRefs and returns a new list containing just the first N verses from the set

    note

    This is a no-op if countVerses(refs) < n

    Parameters

    • v: Versification
    • refs: BibleRef[]

      List of references to consider

    • n: number

      Maximum number of verses to include in output set

    Returns BibleRef[]

format

fromVidx

  • Converts a "Verse Index" produced by [[toVidex]] back into a JSON BibleVerse

    note

    You should ensure the versification scheme used is the same in both directions, else unexpected results are likely to occur

    Parameters

    Returns BibleVerse

getDifference

  • Computes the subtraction of two sets of BibleRefs, returing a new list of BibleRef instances containing all verses in set x but not in set y

    Parameters

    Returns BibleRef[]

    Set operation x \ y -> IE: all verses in x but not in y

getIntersection

getUnion

groupByBook

  • Groups a list of references into buckets split by book

    Returns list of RefsByBook representing the buckets that the input references have been sorted into. Returns list will be in order from the bucket for the first book to the last book, however the individual references within each bucket will maintain their order relative to the input array - hence input order matters. Pre-sort if desired.

    Parameters

    Returns RefsByBook[]

groupByChapter

  • Groups a list of references into buckets split by book, chapter

    Returns list of RefsByChapter representing the buckets that the input references have been sorted into. Returns list will be in order from the bucket for the first book to the last book, however the individual references within each bucket will maintain their order relative to the input array - hence input order matters. Pre-sort if desired.

    Parameters

    Returns RefsByChapter[]

groupByLevel

  • groupByLevel(this: BibleRefLibData, refs: BibleRef[] | BibleRef, options?: RefsByLevelOptions): RefsByLevel

  • Sorts a list of references into seperate lists for full books, full chapters, and individual verses

    For example, Gen, Exo.1, Lev.1.1 would be grouped into the object: { books : [ Gen ], chapters : [ Exo.1 ], verses : [ Lev.1.1 ], }

    The books and chapters array will contain only BibleRanges, where as verses will contain only BibleVerses

    The output arrays will be de-deuplicated when multiple inputs would create the same output, and arrays will be sorted into verse order - hence input order is not important

    Parameters

    • this: BibleRefLibData
    • refs: BibleRef[] | BibleRef
    • Optional options: RefsByLevelOptions

    Returns RefsByLevel

indexOf

  • Given a (potentially non-continous) set of BibleRef's, computes the index of some BibleVerse within the set.

    For example, given the input set "Revelation 1:1; Exodus 1:2-4; Genesis 10:5" the following verses appear at each index:

    • 0: Revelation 1:1
    • 1: Exodus 1:2
    • 2: Exodus 1:3
    • 3: Exodus 1:4
    • 4: Genesis 10:5
    note

    If the same verse appears at multiple positions within the input array then only the first index is returned

    note

    The inverse of this function is verseAtIndex

    Parameters

    • this: BibleRefLibData
    • array: BibleRef | BibleRef[]

      The array of input verses you wish to search (aka, the haystack)

    • verse: BibleVerse

      The verse whose index you wish to determnine (aka, the needle)

    Returns number

    The zero based index at which verse can be found, or -1 if the verse does not appear within the input array

intersects

isFullBook

  • isFullBook(this: BibleRefLibData, ref: BibleRef): boolean

  • Determines if a BibleRef is in fact just a single BibleRange which represents exactly the entirety of a single book - no more, no less

    Parameters

    Returns boolean

    Boolean representing decision

isFullChapter

  • isFullChapter(this: BibleRefLibData, ref: BibleRef): boolean

  • Determines if a BibleRef is in fact just a single BibleRange which represents exactly the entirety of a single chapter - no more, no less

    Parameters

    Returns boolean

    Boolean representing decision

iterateByBook

  • iterateByBook(this: BibleRefLibData, refs: BibleRef | BibleRef[], expand_verses?: undefined | false | true): Iterable<BibleRef>

  • Returns an iterator that traverses over the objects that would have been returned by splitByBook

    Parameters

    • this: BibleRefLibData
    • refs: BibleRef | BibleRef[]
    • Optional expand_verses: undefined | false | true

    Returns Iterable<BibleRef>

iterateByChapter

  • iterateByChapter(this: BibleRefLibData, refs: BibleRef | BibleRef[], expand_verses?: undefined | false | true): Iterable<BibleRef>

  • Returns an iterator that traverses over the objects that would have been returned by splitByChapter

    Parameters

    • this: BibleRefLibData
    • refs: BibleRef | BibleRef[]
    • Optional expand_verses: undefined | false | true

    Returns Iterable<BibleRef>

iterateByVerse

makeRange

  • makeRange(this: BibleRefLibData, book: string, chapter?: undefined | number): BibleRange

  • Creates a BibleRange representing either an entire book, or an entire chapter

    note

    This function will throw if the specified book is not a valid book ID, or if the specified chapter is too high

    Parameters

    • this: BibleRefLibData

      Any object with a versification field

    • book: string
    • Optional chapter: undefined | number

    Returns BibleRange

nextBook

  • Given a BibleRef, returns a new BibleRef which represents the range of verses making up the next book after the book containing the last verse in the input range

    Parameters

    Returns BibleRange | null

    BibleRef or null if there is no next book (IE: input is revelation)

nextChapter

  • nextChapter(this: BibleRefLibData, ref: BibleRef, constrain_book?: undefined | false | true): BibleRange | null

  • Given a BibleRef, returns a new BibleRef which represents the next chapter after the last verse in the input ref.

    Parameters

    • this: BibleRefLibData
    • ref: BibleRef
    • Optional constrain_book: undefined | false | true

      If true, will not cross book boundaries to find another chapter

    Returns BibleRange | null

    BibleRef or null if there is no next chapter

nextVerse

  • nextVerse(this: BibleRefLibData, ref: BibleRef, opts?: { constrain_book?: undefined | false | true; constrain_chapter?: undefined | false | true }): BibleVerse | null

  • Given a BibleRef, returns a new BibleVerse which represents the next verse after the last verse in the input ref

    Parameters

    • this: BibleRefLibData
    • ref: BibleRef
    • Default value opts: { constrain_book?: undefined | false | true; constrain_chapter?: undefined | false | true } = {}
      • Optional constrain_book?: undefined | false | true

        If set, will not cross book boundaries to find another verse

      • Optional constrain_chapter?: undefined | false | true

        If set, will not cross chapter boundaries to find another verse

    Returns BibleVerse | null

parse

  • Parses a string which may (or may not) represent a BibleRef and returns a ParseResult representing whether the parse was successful, and if so what value was obtained.

    Examples of valid input strings include:

    Book references (returns (list of) range(s) representing entire book):

    • Genesis
    • Gen
    • GEN
    • Genesis; Revelation

    Chapter references (returns (list of) range(s) representing entire chapters):

    • Genesis 1
    • GEN1
    • Genesis 1; Exodus 2; REV1

    Verse References (represents a single verse):

    • Genesis 1:1
    • Gen 1v1
    • GEN1.1

    Verse Ranges (continous blocks of verses, can cross chapter/book boundaries):

    • Genesis 1:1-4
    • Genesis 1:1 - 2:2
    • Genesis 50 - Exodus 2

    Complex sets/combinations:

    • Genesis 1:1, 2-4, 6
    • GEN1.1-2; EXO3:4 - DEU5v6,10; Revelation 22

    Parameters

    • this: BibleRefLib

      Instance of BibleRefLib (includes the versification to use)

    • str: string

      The string to parse

    Returns ParseResult

parseBookName

  • parseBookName(this: BibleRefLib, str: string): string | null

  • Parses the name of a book and returns either a string containing the USFM book id or null if the book name was not recognised

    Parameters

    • this: BibleRefLib

      Instance of BibleRefLib (includes the versification to use)

    • str: string

      The string to parse

    Returns string | null

parseOrThrow

  • As with parse, but throws error if the input string is not a valid representation of a BibleRef

    If the input string is known to be in syntax as written by format function using the 'url' preset, parseUrlEncoded is equivalent to this function but runs ~20x faster

    Parameters

    • this: BibleRefLib

      Instance of BibleRefLib (includes the versification to use)

    • str: string

      The string to parse

    Returns BibleRef[]

parseUrlEncoded

  • parseUrlEncoded(this: BibleRefLibData, raw: string): BibleRef[]

  • Function to parse data written using format with the 'url' preset This operates ~20x faster than the generic parser and guarantied to produce the exact same output as standard parseOrThrow on good input. Behaviour is undefined on bad input - some checks are omitted for increased performance which may cause this function to return garbage output when parseOrThrow would have thrown

    For reference, a 5.5kb url-encoded BibleRef string takes 1.5ms to parse with this function, or 30ms to parse with the generic parser. The equivalent JSON representation of the data is 72kb, but can be parsed in ~0.7ms using the native JSON.parse function

    Parameters

    • this: BibleRefLibData
    • raw: string

    Returns BibleRef[]

previousBook

  • Given a BibleRef, returns a new BibleRef which represents the range of verses making up the book before the book containing the first verse in the input range

    Parameters

    Returns BibleRange | null

    BibleRef or null if there is no previous book (IE: input is genesis)

previousChapter

  • previousChapter(this: BibleRefLibData, ref: BibleRef, constrain_book?: undefined | false | true): BibleRange | null

  • Returns BibleRef representing the range of verses making up the chapter BEFORE the first verse of the input ref

    Parameters

    • this: BibleRefLibData
    • ref: BibleRef
    • Optional constrain_book: undefined | false | true

      If true, will not cross book boundaries to find another chapter

    Returns BibleRange | null

    BibleRef or null if there is no previous chapter

previousVerse

  • previousVerse(this: BibleRefLibData, ref: BibleRef, opts?: { constrain_book?: undefined | false | true; constrain_chapter?: undefined | false | true }): BibleVerse | null

  • Given a BibleRef, returns a new BibleVerse which represents the verse preceeding the first verse in the input ref

    Parameters

    • this: BibleRefLibData
    • ref: BibleRef
    • Default value opts: { constrain_book?: undefined | false | true; constrain_chapter?: undefined | false | true } = {}
      • Optional constrain_book?: undefined | false | true

        If set, will not cross book boundaries to find another verse

      • Optional constrain_chapter?: undefined | false | true

        If set, will not cross chapter boundaries to find another verse

    Returns BibleVerse | null

repair

  • repair(v: Versification, ref: BibleRef, include_warnings?: undefined | false | true): BibleRef

  • Attempts to fix errors identified by "validate". Will modify the specified ref in place rather than making a copy Will throw if the error is unfixable

    Parameters

    • v: Versification
    • ref: BibleRef
    • Optional include_warnings: undefined | false | true

    Returns BibleRef

    reference to the passed in BibleRef

sort

  • Takes an array of BibleRef instances and sorts them into order as per the versification scheme in use, from the BibleRef which appears first, to the one which apears last

    note

    [[BibleRanges]] are compared based on their start value

    Parameters

    Returns BibleRef[]

splitByBook

  • Splits an array of ranges such that any input range spanning multiple books is subdivided into multiple smaller ranges, one for each book

    Parameters

    • this: BibleRefLibData
    • refs: BibleRef | BibleRef[]

      The list of refs to be split

    • Optional expand_verses: undefined | false | true

      If set then even single verses will be represented as ranges of length 1, ensuring all returned objects have the same schema

    Returns BibleRef[]

splitByChapter

  • splitByChapter(this: BibleRefLibData, refs: BibleRef | BibleRef[], expand_verses?: undefined | false | true): BibleRef[]

  • Splits an array of ranges such that any input range spanning multiple chapters is subdivided into multiple smaller ranges, one for each chapter

    Parameters

    • this: BibleRefLibData
    • refs: BibleRef | BibleRef[]

      The list of refs to be split

    • Optional expand_verses: undefined | false | true

      If set then even single verses will be represented as ranges of length 1, ensuring all returned objects have the same schema.

    Returns BibleRef[]

splitByVerse

toVidx

  • toVidx(versification: Versification, verse: BibleVerse): number

  • Converts a BibleVerse to a "Verse Index" which would be the 0-based index of the verse in an array contain all verse of the bible

    Parameters

    Returns number

validate

  • Validates a BibleRef, returning an array of errors, or empty array if no issues Note that the .ref field of each error produced will be a reference to the BibleRef passed in rather than a copy

    Parameters

    • v: Versification
    • ref: BibleRef
    • Optional include_warnings: undefined | false | true

      if true then warning messages will be included

    Returns ValidationError[]

verseAtIndex

  • Given a (potentially non-continous) set of BibleRef's, finds the BibleVerse at the specified index. This is the inverse of indexOf

    note

    Semantically, the call AwokenRef.verseAtIndex(array, n) is equivalent to AwokenRef.splitByVerse(array)[n], however this version is more efficent for a single call, since it does not have build the full temporary array, but intead internally operates by blocks of verses represented by the BibleRef instances in the input array

    Parameters

    • this: BibleRefLibData
    • array: BibleRef | BibleRef[]

      The set of BibleRef instances (or singular instance) to extract a verse from

    • index: number

      The zero based index of the verse you wish to extract from the input set

    Returns BibleVerse | undefined

    BibleVerse instance, or undefined if index is out of bounds

Generated using TypeDoc