mirror of
https://github.com/scotttomaszewski/obsidian-disciples-journal.git
synced 2026-07-22 05:42:13 +00:00
62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# 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](esv-api.md) and `BibleFiles.pathForPassage`.
|
||
|
||
## Non-contiguous (comma) lists
|
||
|
||
Verse selection (see [gotchas.md](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.
|