codexparser 0.1.59 → 0.1.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexparser",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "This is a Javascript Bible parser and text scanner. It will search through texts and collate all scripture references into an array and parse them into objects, and it will parse passages into objects by book, chapter, verse, and testament. ",
   "main": "index.js",
   "scripts": {

package/src/CodexParser.js

@@ -1,3 +1,10 @@
+/**
+ * CodexParser.js
+ * A class for scanning and parsing scripture references from text, supporting various formats
+ * (e.g., single verses, ranges, multi-chapter references) with validation and version-specific
+ * versification. Handles book names, abbreviations, and SBL-style formatting.
+ */
+
 const versified = require("./versified")
 const bible = require("./bible")
 const { bookRegex, chapterRegex, verseRegex, scripturesRegex } = require("./regex")
@@ -8,28 +15,37 @@ const dd = require("./functions").dd
 const sch = require("./functions").sch
 const chapter_verses = require("./chapterVerseCombine")
 
+/**
+ * Class for parsing and validating scripture references.
+ * @class
+ */
 class CodexParser {
+    /**
+     * Initializes the parser with default properties and data.
+     */
     constructor() {
-        this.found = []
-        this.passages = []
-        this.bible = bible
-        this.bookRegex = bookRegex
-        this.chapterRegex = chapterRegex
-        this.verseRegex = verseRegex
-        this.scripturesRegex = scripturesRegex
-        this.abbreviations = abbreviations
-        this.sblAbbreviations = sblAbbreviations
-        this.versificationDifferences = versified
+        this.found = [] // Array to store detected references
+        this.passages = [] // Array to store parsed passages
+        this.bible = bible // Bible data (Old/New Testament books)
+        this.bookRegex = bookRegex // Regex for book names
+        this.chapterRegex = chapterRegex // Regex for chapters
+        this.verseRegex = verseRegex // Regex for verses
+        this.scripturesRegex = scripturesRegex // Regex for full references
+        this.abbreviations = abbreviations // Book abbreviation mappings
+        this.sblAbbreviations = sblAbbreviations // SBL-style abbreviation mappings
+        this.versificationDifferences = versified // Version-specific verse differences
         this.singleChapterBook = [
+            // Books with a single chapter and their verse counts
             sch("Jude", 25),
             sch("2 John", 13),
             sch("3 John", 15),
             sch("Obadiah", 21),
             sch("Philemon", 25),
         ]
-        this.chapterVerses = chapter_verses
-        this.error = false
-        this.version = null
+        this.chapterVerses = chapter_verses // Chapter-verse mappings
+        this.error = false // Error flag
+        this.version = null // Bible version (e.g., lxx, mt, eng)
+        // Reference type constants
         this.SINGLE_CHAPTER = "single_chapter"
         this.CHAPTER_VERSE = "chapter_verse"
         this.CHAPTER_VERSE_RANGE = "chapter_verse_range"
@@ -38,11 +54,22 @@ class CodexParser {
         this.MULTI_CHAPTER_RANGE = "multi_chapter_verse_range"
     }
 
+    /**
+     * Retrieves available verses for a given book and chapter.
+     * @param {string} book - The book name (e.g., "Genesis").
+     * @param {number} chapter - The chapter number.
+     * @returns {number[]} Array of valid verse numbers.
+     */
     getChapterVerses(book, chapter) {
         const singleChapterBook = this.singleChapterBook.find((b) => Object.keys(b)[0] === book)
         return singleChapterBook ? singleChapterBook[book][chapter] || [] : this.chapterVerses[book]?.[chapter] || []
     }
 
+    /**
+     * Scans text for scripture references and stores them in `this.found`.
+     * @param {string} text - The text to scan.
+     * @returns {CodexParser} The parser instance for method chaining.
+     */
     scan(text) {
         const fullNames = [...this.bible.old, ...this.bible.new]
         const abbreviations = Object.keys(this.abbreviations)
@@ -66,19 +93,25 @@ class CodexParser {
         }
         const detectSuffix = (startIndex) => {
             const suffixMatch = normalizedText.substring(startIndex).match(/\b(LXX|MT)\b/i)
-            return suffixMatch ? suffixMatch[0].toUpperCase() : null
+            return suffixMatch
+                ? {
+                      suffix: suffixMatch[0].toUpperCase(),
+                      length:
+                          suffixMatch[0].length + (normalizedText[startIndex + suffixMatch[0].length] === " " ? 1 : 0),
+                  }
+                : null
         }
 
         while (i < lowerCaseText.length) {
             let foundBook = null
-            let foundIndex = -1
+            let startIndex = -1
             let matchedLength = 0
 
             for (let j = 0; j < lowercaseBibleFullNames.length; j++) {
                 const book = lowercaseBibleFullNames[j]
                 if (lowerCaseText.startsWith(book, i) && book.length > matchedLength) {
                     foundBook = fullNames[j]
-                    foundIndex = i
+                    startIndex = i
                     matchedLength = book.length
                 }
             }
@@ -88,7 +121,7 @@ class CodexParser {
                     const abbreviation = lowercaseBibleAbbreviations[k]
                     if (lowerCaseText.startsWith(abbreviation, i) && abbreviation.length > matchedLength) {
                         foundBook = this.abbreviations[abbreviations[k]]
-                        foundIndex = i
+                        startIndex = i
                         matchedLength = abbreviation.length
                     }
                 }
@@ -98,6 +131,7 @@ class CodexParser {
                 i += matchedLength
                 let chapterVerse = ""
                 const references = []
+                const startOfReference = startIndex
 
                 while (i < normalizedText.length && isValidChapterVerseChar(normalizedText[i])) {
                     if (isNextBibleBook(i)) break
@@ -117,7 +151,15 @@ class CodexParser {
                     if (formattedReference) references.push(formattedReference)
                 }
 
-                const suffix = detectSuffix(i)
+                const suffixData = detectSuffix(i)
+                const suffix = suffixData ? suffixData.suffix : null
+                if (suffixData) i += suffixData.length
+
+                // Adjust endIndex to exclude trailing space if present
+                let endIndex = i
+                if (endIndex > 0 && normalizedText[endIndex - 1] === " ") {
+                    endIndex--
+                }
 
                 references.forEach((ref) => {
                     let type
@@ -146,9 +188,11 @@ class CodexParser {
                     this.found.push({
                         book: foundBook,
                         reference: ref,
-                        index: foundIndex,
+                        startIndex: startOfReference,
+                        endIndex: endIndex,
                         version: suffix || null,
                         type,
+                        originalText: normalizedText.slice(startOfReference, endIndex),
                     })
                 })
             } else {
@@ -159,6 +203,11 @@ class CodexParser {
         return this
     }
 
+    /**
+     * Sets the Bible version for parsing.
+     * @param {string} version - The version (e.g., "lxx", "mt", "eng").
+     * @returns {CodexParser} The parser instance.
+     */
     bibleVersion(version) {
         const lowerVersion = version.toLowerCase()
         this.version =
@@ -168,6 +217,11 @@ class CodexParser {
         return this
     }
 
+    /**
+     * Parses a scripture reference into structured passage objects.
+     * @param {string} reference - The reference to parse (e.g., "John 3:16").
+     * @returns {CodexParser} The parser instance.
+     */
     parse(reference) {
         this.scan(reference)
 
@@ -181,13 +235,16 @@ class CodexParser {
                 verses: [],
                 type: passage.type,
                 testament,
-                index: passage.index,
+                startIndex: passage.startIndex,
+                endIndex: passage.endIndex,
+                originalText: passage.originalText,
                 version: this._handleVersion(passage.version, testament),
                 passages: [],
                 scripture: null,
                 valid: true,
                 start: null,
                 end: null,
+                abbr: null,
             }
 
             this.parseReferenceParts(parsedPassage, passage.reference.split(","))
@@ -195,15 +252,13 @@ class CodexParser {
             parsedPassage.scripture = this.scripturize(parsedPassage)
             parsedPassage.valid = this._isValid(parsedPassage, passage.reference)
 
-            // Add SBL abbreviation as full reference with en dashes and space after commas for comma-separated verses
-            const sblEntry = this.sblAbbreviations[book] || { value: book, abbr: false }
-            const sblBook = sblEntry.value + (sblEntry.abbr ? "." : "")
-            let abbr = parsedPassage.scripture.passage.replace(book, sblBook).replace(/-/g, "–")
-            if (parsedPassage.type === "comma_separated_verses") {
-                const versePart = parsedPassage.verses.map((v) => `${v}`).join(", ")
-                abbr = `${sblBook} ${parsedPassage.chapter}:${versePart}`
-            }
-            parsedPassage.abbr = abbr
+            // Set abbr property using SBL-style abbreviation
+            const abbrKey = Object.keys(this.abbreviations).find(
+                (abbr) => this.abbreviations[abbr].toLowerCase() === book.toLowerCase()
+            )
+            parsedPassage.abbr = abbrKey
+                ? `${abbrKey}. ${passage.reference}${passage.version ? " " + passage.version : ""}`
+                : parsedPassage.original
 
             if (parsedPassage.type === this.MULTI_CHAPTER_RANGE) {
                 this.handleMultiChapterRange(parsedPassage, passage.reference)
@@ -211,6 +266,7 @@ class CodexParser {
                 delete parsedPassage.to
             }
 
+            // Calculate start and end based on passages array
             if (parsedPassage.passages.length > 0) {
                 const sortedPassages = parsedPassage.passages.slice().sort((a, b) => {
                     if (a.chapter !== b.chapter) return a.chapter - b.chapter
@@ -238,11 +294,6 @@ class CodexParser {
                 }
             }
 
-            // Attach the reference method to this individual passage object
-            parsedPassage.reference = function () {
-                return this.scripture.passage
-            }
-
             return parsedPassage
         })
 
@@ -250,6 +301,12 @@ class CodexParser {
         return this
     }
 
+    /**
+     * Parses reference parts into chapter and verse components.
+     * @param {Object} passage - The passage object to populate.
+     * @param {string[]} parts - Array of reference parts.
+     * @private
+     */
     parseReferenceParts(passage, parts) {
         const singleChapterBook = this.singleChapterBook.find((b) => Object.keys(b)[0] === passage.book)
 
@@ -269,6 +326,13 @@ class CodexParser {
         })
     }
 
+    /**
+     * Parses chapter-verse references (e.g., "3:16").
+     * @param {Object} passage - The passage object.
+     * @param {string} part - The reference part.
+     * @param {boolean} isFirstPart - Whether this is the first part.
+     * @private
+     */
     parseChapterVerse(passage, part, isFirstPart) {
         const [chapter, verse] = part.split(":")
         if (isFirstPart) passage.chapter = Number(chapter)
@@ -276,6 +340,13 @@ class CodexParser {
         passage.verses.push(verse.includes("-") ? verse : Number(verse))
     }
 
+    /**
+     * Parses references for single-chapter books (e.g., "Jude 5").
+     * @param {Object} passage - The passage object.
+     * @param {string} part - The reference part.
+     * @param {boolean} isWholeChapter - Whether the reference is for the whole chapter.
+     * @private
+     */
     parseSingleChapterBook(passage, part, isWholeChapter) {
         const verseCount = this.getChapterVerses(passage.book, 1).length
         if (part === "1" && isWholeChapter) {
@@ -296,6 +367,13 @@ class CodexParser {
         }
     }
 
+    /**
+     * Parses range references (e.g., "1-3").
+     * @param {Object} passage - The passage object.
+     * @param {string} part - The reference part.
+     * @param {boolean} isFirstPart - Whether this is the first part.
+     * @private
+     */
     parseRange(passage, part, isFirstPart) {
         if (!passage.chapter && isFirstPart) {
             const [start, end] = part.split("-").map(Number)
@@ -318,6 +396,13 @@ class CodexParser {
         }
     }
 
+    /**
+     * Parses single number references (e.g., "3" for chapter or verse).
+     * @param {Object} passage - The passage object.
+     * @param {string} part - The reference part.
+     * @param {boolean} isFirstPart - Whether this is the first part.
+     * @private
+     */
     parseSingleNumber(passage, part, isFirstPart) {
         if (isFirstPart && !passage.chapter) {
             passage.chapter = Number(part)
@@ -332,6 +417,12 @@ class CodexParser {
         }
     }
 
+    /**
+     * Handles multi-chapter range references (e.g., "3:16-4:5").
+     * @param {Object} passage - The passage object.
+     * @param {string} reference - The full reference string.
+     * @private
+     */
     handleMultiChapterRange(passage, reference) {
         const parts = reference.split(",")
         const lastPart = parts[parts.length - 1]
@@ -345,6 +436,13 @@ class CodexParser {
         }
     }
 
+    /**
+     * Generates a range of numbers.
+     * @param {number} start - Start number.
+     * @param {number} end - End number.
+     * @returns {number[]} Array of numbers.
+     * @private
+     */
     _generateRange(start, end) {
         const range = []
         for (let i = start; i <= end; i++) {
@@ -353,10 +451,47 @@ class CodexParser {
         return range
     }
 
+    /**
+     * Searches for versification differences for a book and chapter.
+     * @param {string} book - The book name.
+     * @param {number} chapter - The chapter number.
+     * @param {string} version - The Bible version.
+     * @returns {Object|undefined} Updated chapter verses or undefined.
+     * @private
+     */
     _searchVersificationDifferences(book, chapter, version) {
         version = version.toLowerCase()
-        if (!this.chapterVerses[book][chapter]) return
-        if (!this.versificationDifferences[book]) return
+
+        // Handle single-chapter book "Obadiah"
+        if (book === "Obadiah") {
+            const singleChapterBook = this.singleChapterBook.find((b) => Object.keys(b)[0] === "Obadiah")
+            if (!singleChapterBook || !singleChapterBook[book][chapter]) {
+                return // No data for Obadiah or chapter
+            }
+            if (!this.versificationDifferences[book]) {
+                return // No versification differences for Obadiah
+            }
+            // Process versification differences
+            for (const [key, value] of Object.entries(this.versificationDifferences[book])) {
+                if (value[version].startsWith(`${chapter}:`)) {
+                    if (value[version]) {
+                        const verse = value[version].split(":")[1]
+                        singleChapterBook[book][chapter].push(Number(verse))
+                    }
+                }
+            }
+            // Ensure unique verses and update the singleChapterBook entry
+            singleChapterBook[book][chapter] = Array.from(new Set(singleChapterBook[book][chapter]))
+            return singleChapterBook[book] // Return updated chapter data
+        }
+
+        // Handle all other books using chapterVerses
+        if (!this.chapterVerses[book][chapter]) {
+            return // No data for this book/chapter
+        }
+        if (!this.versificationDifferences[book]) {
+            return // No versification differences
+        }
         for (const [key, value] of Object.entries(this.versificationDifferences[book])) {
             if (value[version].startsWith(`${chapter}:`)) {
                 if (value[version]) {
@@ -366,9 +501,16 @@ class CodexParser {
             }
         }
         this.chapterVerses[book][chapter] = Array.from(this.chapterVerses[book][chapter])
-        return this.chapterVerses
+        return this.chapterVerses // Return updated chapterVerses
     }
 
+    /**
+     * Sets the Bible version and applies versification differences.
+     * @param {string} book - The book name.
+     * @param {number} chapter - The chapter number.
+     * @param {string} version - The Bible version.
+     * @private
+     */
     _setVersion(book, chapter, version) {
         this.version = version ? version : "eng"
         if (this.version !== "eng") {
@@ -376,6 +518,9 @@ class CodexParser {
         }
     }
 
+    /**
+     * Applies versification differences to parsed passages.
+     */
     versification() {
         this.passages.forEach((passage) => {
             const hasVersification = this.versificationDifferences[passage.book]
@@ -407,6 +552,11 @@ class CodexParser {
         })
     }
 
+    /**
+     * Populates passage with expanded verse objects.
+     * @param {Object} passage - The passage object.
+     * @returns {Object[]} Array of verse objects.
+     */
     populate(passage) {
         const { book, chapter, verses, type, to } = passage
         const version = passage.version?.abbreviation || "eng"
@@ -449,6 +599,13 @@ class CodexParser {
         return []
     }
 
+    /**
+     * Expands verse references into individual verse objects.
+     * @param {string} book - The book name.
+     * @param {number} chapter - The chapter number.
+     * @param {Array<string|number>} verses - Array of verses or ranges.
+     * @returns {Object[]} Array of verse objects.
+     */
     expandVerses(book, chapter, verses) {
         const passages = []
         const chapterVerses = this.getChapterVerses(book, chapter)
@@ -466,27 +623,31 @@ class CodexParser {
         return passages
     }
 
+    /**
+     * Normalizes book names using abbreviations or full names.
+     * @param {string|Array} book - The book name or array.
+     * @returns {string} Normalized book name.
+     */
     bookify(book) {
         if (typeof book !== "string") {
             book = book[0]
         }
-        let bookified = Object.keys(this.abbreviations).find((abbr) => {
-            return abbr.toLowerCase() === book.toLowerCase()
-        })
-        bookified = this.abbreviations[bookified]
-        if (!bookified) {
-            bookified = this.bible.new.find(
-                (b) => b.toLowerCase() === book.toLowerCase() && b.toLowerCase().includes(book.toLowerCase())
-            )
-            if (!bookified) {
-                bookified = this.bible.old.find(
-                    (b) => b.toLowerCase() === book.toLowerCase() && b.toLowerCase().includes(book.toLowerCase())
-                )
-            }
+        book = book.toLowerCase()
+        // Check if book is an abbreviation
+        let bookified = this.abbreviations[Object.keys(this.abbreviations).find((abbr) => abbr.toLowerCase() === book)]
+        if (bookified) {
+            return bookified
         }
-        return bookified
+        // Check if book is a full name
+        bookified =
+            this.bible.new.find((b) => b.toLowerCase() === book) || this.bible.old.find((b) => b.toLowerCase() === book)
+        return bookified || book // Fallback to input if not found
     }
 
+    /**
+     * Returns parsed passages with utility methods.
+     * @returns {Object[]} Array of passages with methods.
+     */
     getPassages() {
         const passagesArray = [...this.passages]
 
@@ -553,10 +714,19 @@ class CodexParser {
         return passagesArray
     }
 
+    /**
+     * Returns the first parsed passage.
+     * @returns {Object|null} The first passage or null.
+     */
     first() {
         return this.passages.length > 0 ? this.passages[0] : null
     }
 
+    /**
+     * Formats a passage into a human-readable reference.
+     * @param {Object} passage - The passage object.
+     * @returns {Object} Formatted passage data.
+     */
     scripturize(passage) {
         const formatChapterVerse = (chapter, verses) => {
             if (!chapter || !verses || verses.length === 0) return ""
@@ -602,6 +772,11 @@ class CodexParser {
         }
     }
 
+    /**
+     * Combines multiple passages into a single reference.
+     * @param {Object[]} passages - Array of passages to combine.
+     * @returns {Object} Combined passage object.
+     */
     combine(passages) {
         if (!passages || passages.length === 0) {
             throw new Error("No passages provided to join.")
@@ -717,6 +892,11 @@ class CodexParser {
         return combined
     }
 
+    /**
+     * Merges verses into ranges or comma-separated lists.
+     * @param {number[]} verses - Array of verse numbers.
+     * @returns {string[]} Array of verse strings.
+     */
     mergeRanges(verses) {
         const sortedVerses = [...new Set(verses)].sort((a, b) => a - b)
         const merged = []
@@ -746,6 +926,11 @@ class CodexParser {
         return merged
     }
 
+    /**
+     * Generates a table of contents for the Bible.
+     * @param {string} [version="ESV"] - The Bible version.
+     * @returns {Object} TOC with book-chapter-verse mappings.
+     */
     getToc(version = "ESV") {
         const toc = {}
         this.bible.old.forEach((book) => {
@@ -775,6 +960,13 @@ class CodexParser {
         return orderedToc
     }
 
+    /**
+     * Validates a passage for correctness.
+     * @param {Object} passage - The passage object.
+     * @param {string} reference - The original reference.
+     * @returns {boolean|Object} True if valid, error object if invalid.
+     * @private
+     */
     _isValid(passage, reference) {
         const { book, chapter, verses, type } = passage
 
@@ -806,6 +998,15 @@ class CodexParser {
         return this.validateVerses(book, chapter, verses, reference)
     }
 
+    /**
+     * Validates verse numbers for a chapter.
+     * @param {string} book - The book name.
+     * @param {number} chapter - The chapter number.
+     * @param {Array<string|number>} verses - Array of verses or ranges.
+     * @param {string} reference - The original reference.
+     * @returns {boolean|Object} True if valid, error object if invalid.
+     * @private
+     */
     validateVerses(book, chapter, verses, reference) {
         const chapterVerses = this.getChapterVerses(book, chapter)
         for (const verse of verses) {
@@ -826,6 +1027,13 @@ class CodexParser {
         return true
     }
 
+    /**
+     * Creates an error object for validation failures.
+     * @param {number} code - Error code.
+     * @param {string} message - Error message.
+     * @returns {Object} Error object.
+     * @private
+     */
     validationError(code, message) {
         return {
             error: true,
@@ -834,6 +1042,13 @@ class CodexParser {
         }
     }
 
+    /**
+     * Determines the Bible version for a passage.
+     * @param {string} version - The version (e.g., "lxx").
+     * @param {string} testament - The testament ("old" or "new").
+     * @returns {Object} Version object.
+     * @private
+     */
     _handleVersion(version, testament) {
         const effectiveVersion = this.version || version || "eng"
         const lowerVersion = effectiveVersion.toLowerCase()
@@ -846,6 +1061,27 @@ class CodexParser {
         }
         return { name: "English", value: "ENG", abbreviation: "eng" }
     }
+
+    replace(text, useAbbreviations = true) {
+        if (!this.passages.length) {
+            console.log("No parsed passages to replace")
+            return text
+        }
+
+        let result = text
+        // Process replacements in reverse order to avoid index shifting
+        for (let i = this.passages.length - 1; i >= 0; i--) {
+            const passage = this.passages[i]
+            const { startIndex, endIndex, originalText, abbr, original } = passage
+
+            // Use abbreviated or full reference
+            const newReference = useAbbreviations ? abbr : original
+            console.log(`Replacing "${originalText}" with "${newReference}" at [${startIndex}, ${endIndex}]`) // Debug
+            result = result.slice(0, startIndex) + newReference + result.slice(endIndex)
+        }
+
+        return result
+    }
 }
 
 module.exports = CodexParser

package/src/abbr.js

@@ -158,6 +158,7 @@ const abbrevations = {
     Mal: "Malachi",
     Ml: "Malachi",
     Matt: "Matthew",
+    Mat: "Matthew",
     Mt: "Matthew",
     Mark: "Mark",
     Mc: "Mark",