Class: ReferenceParser
Defined in: Services/ReferenceParser.ts:120
Interface for reference parsing. Implementations handle language-specific book name resolution and formatting. Latin-script languages can reuse ReferenceParser with different book name tables; languages with fundamentally different syntax should provide a full implementation.
Implements
Constructors
Constructor
new ReferenceParser(
config?):ReferenceParser
Defined in: Services/ReferenceParser.ts:125
Parameters
config?
Returns
ReferenceParser
Methods
extractReferences()
extractReferences(
text):ParsedReference[]
Defined in: Services/ReferenceParser.ts:506
Extract all Bible references from a text string.
Splits the input on commas and semicolons, then attempts to parse each segment as a reference. Only returns segments that parse as valid references. For finding references embedded in running prose, use scanText instead.
Parameters
text
string
Text potentially containing multiple references separated by commas/semicolons
Returns
Array of valid parsed references found in the text
Example
const parser = new ReferenceParser();
const refs = parser.extractReferences("John 3:16; Romans 8:28");
// Returns two ParsedReference objects
Implementation of
IReferenceParser.extractReferences
format()
format(
ref):string
Defined in: Services/ReferenceParser.ts:451
Format a parsed reference as a canonical human-readable string.
Produces standard forms like "John 3:16", "Romans 8:28-30", or "John 3:16-4:2" for cross-chapter ranges. Falls back to the original text if the reference is invalid.
Parameters
ref
A previously parsed reference from parse
Returns
string
A formatted reference string (e.g., "John 3:16")
Implementation of
getBookName()
getBookName(
bookNumber):string
Defined in: Services/ReferenceParser.ts:485
Get the full canonical book name from a book number.
Parameters
bookNumber
number
The book number (1=Genesis, 66=Revelation)
Returns
string
The full book name (e.g., "Genesis", "1 Corinthians"), or "Book N" if the number is out of range
Implementation of
getBookNumber()
getBookNumber(
bookName):number|undefined
Defined in: Services/ReferenceParser.ts:275
Look up a book number (1-66) from a book name or abbreviation. Performs exact, case-insensitive matching only -- no fuzzy fallback.
Parameters
bookName
string
Full name or abbreviation (e.g., "Genesis", "gen", "Gn")
Returns
number | undefined
The book number (1-66), or undefined if no exact match is found
Implementation of
IReferenceParser.getBookNumber
getBookNumberFuzzy()
getBookNumberFuzzy(
bookName): {bookNumber:number;fuzzy:boolean;matchedName:string; } |undefined
Defined in: Services/ReferenceParser.ts:292
Look up a book number with fuzzy matching fallback.
Tries exact match first, then falls back to Damerau-Levenshtein distance matching (max distance 2, and less than half the input length). Skips very short keys (<=2 chars) during fuzzy matching to avoid ambiguity. Tiebreakers: character overlap, then length similarity.
Parameters
bookName
string
Full name or abbreviation to look up
Returns
{ bookNumber: number; fuzzy: boolean; matchedName: string; } | undefined
The book number, matched name, and whether fuzzy matching was used, or undefined if no match could be found
Implementation of
IReferenceParser.getBookNumberFuzzy
isReference()
isReference(
text,options?):boolean
Defined in: Services/ReferenceParser.ts:150
Check if the given text looks like a Bible reference.
Tests against a pattern matching formats like "John 3:16", "1 John 3:16", "Gen 1:1-5", "Psalm 23". Does not validate that the book, chapter, or verse actually exist -- use parse followed by validate for full validation.
Parameters
text
string
The text string to test
options?
Returns
boolean
true if the text matches a Bible reference pattern
Example
const parser = new ReferenceParser();
parser.isReference("John 3:16"); // true
parser.isReference("Hello world"); // false
parser.isReference("1 Cor 13:4-7"); // true
Implementation of
parse()
parse(
text,options?):ParsedReference
Defined in: Services/ReferenceParser.ts:203
Parse a Bible reference string into its component parts.
Handles numbered books ("1 John"), Roman numeral prefixes ("II Cor"), abbreviations ("Gen"), full names ("Genesis"), single-chapter books ("Jude 5" -> chapter 1, verse 5), and verse ranges ("John 3:16-18").
Uses exact book name matching first, then falls back to fuzzy matching (Damerau-Levenshtein distance <= 2) to handle typos like "Jonh" -> "John".
Parameters
text
string
The reference string to parse (e.g., "John 3:16", "Gen 1:1-5")
options?
Returns
A ParsedReference with isValid=true on success, or isValid=false if the text cannot be parsed as a Bible reference
Example
const parser = new ReferenceParser();
const ref = parser.parse("John 3:16");
// { isValid: true, book: 43, chapter: 3, verse: 16, ... }
const range = parser.parse("Romans 8:28-30");
// { isValid: true, book: 45, chapter: 8, verse: 28, endVerse: 30, ... }
const typo = parser.parse("Jonh 3:16");
// { isValid: true, book: 43, fuzzyMatch: true, correctedBookName: "john", ... }
Implementation of
scanText()
scanText(
text):ParsedReference&object[]
Defined in: Services/ReferenceParser.ts:538
Scan running text for Bible references and return their positions. Unlike extractReferences() which expects pre-segmented input, this method finds references embedded in sentences.
Returns matches with start/end character offsets so callers can create decorations, links, or highlights in editors.
Only exact book name matches are used (no fuzzy matching) to avoid false positives like "Task 1" matching a Bible book name.
Supports comma-separated verses: "John 3:16, 17" produces two references (John 3:16 and John 3:17).
Parameters
text
string
Returns
ParsedReference & object[]
Implementation of
validate()
validate(
ref):string|undefined
Defined in: Services/ReferenceParser.ts:413
Validate a parsed reference for logical correctness.
Checks that the book number is 1-66, chapter/verse are positive, and range endpoints are ordered correctly (end >= start). Does NOT verify that the chapter or verse actually exists in the book.
Parameters
ref
A previously parsed reference from parse
Returns
string | undefined
An error message string if invalid, or undefined if valid