scotttomaszewski_obsidian-disciples-journal/docs/reference-formats.md

Bible reference formats

Supported reference syntax and how it is parsed. Primary code: src/core/BibleReference.ts (BibleReference.parse) and src/services/BookNames.ts.

Supported formats

Example	Meaning	Parsed fields
Genesis 1	whole chapter	chapter
Genesis 1-2	chapter range	chapter, endChapter
John 3:16	single verse	chapter, verse
Genesis 1:1-10	verse range in one chapter	chapter, verse, endVerse
Philippians 1:27-2:11	cross-chapter range	chapter, verse, endChapter, endVerse
1 Corinthians 13:4-7	book name with a number/space	(as above)
Song of Solomon 2:1	multi-word book name	(as above)

How parsing works

BibleReference.parse(str):

1. Extracts the book name with BookNames.extractBookFromReference, then normalizes it via BookNames.normalize (handles abbreviations and multi-word / numbered book names). An unknown book → parse returns null.
2. Normalizes en-dashes (–) to hyphens in the chapter/verse remainder.
3. Matches the remainder against patterns in this order: cross-chapter (C:V-C:V) → chapter range (C-C) → verse range (C:V-V) → single verse (C:V) → single chapter (C). The first match wins.

parse returns null (not throws) for anything it can't interpret. The BibleReference constructor, however, throws if given an unnormalizable book name — parse guards against this by normalizing first.

The value object

BibleReference carries { book, chapter, verse?, endVerse?, endChapter? } and provides:

• toString() — canonical form (round-trips the formats above).
• isChapterReference() — true when no specific verse is set.
• isRange() — true when endVerse or endChapter is set.
• clone() — deep copy.

These fields also drive note filenames — see esv-api.md and BibleFiles.pathForPassage.

Non-contiguous (comma) lists

Verse selection (see gotchas.md) can produce non-contiguous references like Genesis 1:2-3, 5 or Genesis 1:31, 2:1. These are parsed by BibleReference.parseList, not the single-range parse:

• The first comma-separated item is a full reference (any format above).
• Later items may be a bare verse (5), a bare verse range (5-7) — both inheriting the previous item's book and chapter — or chapter:verse[-end], inheriting only the book.
• The result is a BibleReference[] (one per contiguous run); any invalid item makes the whole list null.

A rendered list resolves each run and concatenates the HTML (BibleContentService.getBibleContentList); the passage heading/link uses the first run.