awoken-bible-reference/dist/types/printer.d.ts

Bible verse reference parser, generator and manipulator

/**
 * Contains utilities to print a BibleRef as a string
 */
import { Versification } from './Versification';
import { BibleRef, BibleVerse, BibleRange } from './BibleRef';
/**
 * Set of optional flags which can be passed to the format function
 */
export interface FormatOptions {
    /**
     * The format to use for book name
     * - name -> The full name      -> Judges
     * - usfm -> The 3 char usfm id -> JDG
     * - osis -> The OSIS id        -> Judg
     */
    book_format?: "name" | "usfm" | "osis";
    /**
     * The character/string to use to separate the book name/id from the chapter/verse
     * numbers
     * Defaults to ' ', can use '.' and still be conformant with parser
     */
    book_separator?: string;
    /**
     * The character to use to separate the chapter number from the verse number
     * To be conformant with the parse this should be set to one of:
     * [ ':', 'v', '.', ' v ' ]
     */
    verse_separator?: string;
    /**
     * The character to use to separate multiple references if a list of distinct refs is passed in.
     * To be conformat with the parser this should be set to a string matching the regex \s*[;_]\s*
     * Defaults to '; '
     */
    ref_separator?: string;
    /**
     * If set then all printer added whitespace will be stripped
     * (IE: excludes whitespace in any custom separator options)
     * This makes for harder to read outputs, but URL encodable output strings
     */
    strip_whitespace?: boolean;
    /**
     * If set then implict elements will be hidden, for example a range
     * reperenting an chapter will be printed as "Genesis 1" rather than
     * "Genesis 1:1-31", and a range representing an entire book will be
     * printed "Genesis" rather than "Genesis 1:1 - 50:26"]
     */
    compact?: boolean;
    /**
     * If true, references will always be output in there entirety
     * (IE: never reusing part of the previous reference as implicit context)
     *
     * Eg, Rather than "Genesis 1:4,6" we will return "Genesis 1:4; Genesis 1:6"
     *
     * Additionally, ranges will contain complete references on both sides of the separator
     * character, Eg, Rather than "Genesis 1:4-6" we will return "Genesis 1:4 - Genesis 1:6"
     *
     * Defaults to false, must be true to adhear to OSIS reference specification
     */
    complete_refs?: boolean;
    /**
     * If true then adjacent/overlapping ranges will sorted into order and
     * combined before printing
     */
    combine_ranges?: boolean;
    /**
     * If true then string will be converted to lower case before being returned
     */
    lowercase?: boolean;
}
/**
 * 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
 */
export declare type FormatPreset = "osis" | "url" | "compact" | "lowercase" | "combined";
/**
 * 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]]
 *
 */
export declare type FormatArg = FormatOptions | string;
/**
 * Format a single BibleVerse to a string
 * @private
 */
export declare function formatBibleVerse(v: Versification, x: BibleVerse, arg_opts?: FormatArg): string;
/**
 * Format a single BibleRange to a string
 * @private
 */
export declare function formatBibleRange(v: Versification, x: BibleRange, arg_opts?: FormatArg): string;
/**
 * Format a list of BibleRefs to strings using commas to shorten the output
 * wherever possible
 * Eg, mapping formatBibleVerse over [
 *   { book: 'GEN', chapter: 1, verse: 1 },
 *   { book: 'GEN', chapter: 1, verse: 2 },
 * ]
 * would produce "Genesis 1:1" and "Genesis 1:2"
 * By using this function we instead get the more compact "Genesis 1:1,2"
 * @private
 */
export declare function formatBibleRefList(v: Versification, xs: BibleRef[], arg_opts?: FormatArg): string;