bible-ref-parser

The most universal module to parse bible reference to an object with the information of the given reference.

Table of Contents

• Installation
• Usage
• Bible editions
• Known issues
• Notes
• Contribute
• License

⚙️ Installation

npm install bible-ref-parser

📑 Usage

const { parseQuery } = require('bible-ref-parser');

const reference = "Matthew 28:18-20";
try {
    const parsedRef = parseQuery(reference);
    console.log(parsedRef);
    // output : { book: "MT", chapter: "28", type: "RANGE", verses: ["18", "20"], edition: undefined }
}
catch (e) {
    console.log(`Error ${e.code} as been raised : ${e.message}`);
}

If all goes well, the returned object will always contain the keys version, book, chapter and type. Depending on the value of type, the object may or may not contain the following key: verses, which contains the verses to be retrieved. Below the possible type :

Type	Request prototype	is verses ?
WHOLE_CHAPTER	<book> <chapter>	No
RANGE	<book> <chapter>:<verseStart>-<verseEnd>	Yes
MAP	<book> <chapter>:<verse>	Yes
MAP	<book> <chapter>:<verse1>,<verse2>,...,<verseN>	Yes

Then, the processing of the reference you've parsed must be conditioned on the value of the type. Here are a few examples:

try {
    const parsedRef = parseQuery("Matthew 28:18-20");
    if (parsedRef.type === "RANGE") {
        const [startIndex, stopIndex] = parsedRef.verses;
        // your logic for a range
    }
    else if (parsedRef.type === "MAP") {
        for(const verse of parsedRef.verses) {
            // your logic for a single verse or separated verses in a same chapter
        }
    }
    // other cases ...
}
catch (e) {
    console.log(`Error ${e.code} as been raised : ${e.message}`);
}

🤔 Why return only the starting and ending verses? Some versions of the Bible have non-linear indexing or verses with letter indexes. It is therefore not possible to generate an array containing the indexes between two given values. The most general way of managing references in ranges is to provide only the starting and ending verses. A well thought-out logic allows you to retrieve all the verses between.

⚠️ The function is likely to throw exceptions. Remember to surround it with a try ... catch block to ensure your program runs correctly.

All the exceptions are raised with the following structure:

{ code: HTTP_ERROR_CODE, message: STRING_TO_DISPLAY }

• No valid reference to match : raised with code 400 when the function receive a string that doesn't contain a biblical reference.
• No book founded for the given reference: raised with code 404 when the book of the reference sent is unknown to the canon.
• Invalid reference: code 400 when the reference sent contains an range such as A-A, which is nonsense.

✏️ Bible editions

The module also extracts a desired edition of the Bible, if known to the parser.

try {
    const parsed1 = parseQuery("Luke 13:34 KJV");
    console.log(parsed1.edition); // output: "KJV"

    const parsed2 = parseQuery("Matthew 28:18-20 Foo");
    console.log(parsed2.edition); // output: undefined
}
catch (e) {
    console.log(`Error ${e.code} as been raised : ${e.message}`);
}

If the edition is not known, the parser will return undefined; you can then redefine the value according to your preference. Below is a list of supported editions:

Edition	Abbreviation	Language
King James Version	KJV	English
New King James Version	NKJV	English
Revised Standard Version	RSV	English
The Jerusalem Bible	TJB	English
Vulgate	VULG	Latin
Bible de Jérusalem	BDJ	French
Bible catholique Crampon 1928	BCC1928	French
Bible Fillion	BF	French
Traduction officielle Liturgique	AELF	French
Traduction OEcuménique de la Bible	TOB	French
Parole de vie	PDV	French
Bible du semeur	BDS	French
Bible Louis Segond	LSG	French

Want a specific edition? submit a pull-request on github.

🛑 Known issues

The regex works great for isolated references (see next section), but can return unexpected values if the input is a whole text containing the references. Indeed, if you try "I want 2 John 5:7", you'll get two matches: 'want 2' and 'John 5:7' (or only the first one if the regex is set without the g flag) whereas the expected match is '2 John 5:7'.

The best solution I can provide at the moment if your input is whole text is to ignore the whole chapter format using the following regex:

\b((?:\d ?)?[A-Za-zÀ-ÿ]+) (\d+):((?:\d+[a-zA-Z]?)(?:(?:-\d+[a-zA-Z]?)|(?:,\d+[a-zA-Z]?)+){0,1})\b

Keep in mind that there is no problem if all of your inputs are standalone ref, the issue only concern input that are plain text like paragraph etc.

❓ Notes

The function fully supports the following formats:

• <book> <chapter>
• <book> <chapter>:<verse>
• <book> <chapter>:<verseStart>-<verseEnd>
• <book> <chapter>:<verse1>,<verse2>,...,<verseN>

bible-ref-parser uses the bookTag function of the bible-abbreviation@0.0.3 module to support a large variety of abbreviations for references.

💻 Contribute

Want to improve the module? submit a pull-request on github or open an issue.

📜 License

Copyright © 2023 RyanHmd
This project is MIT licensed.