Expand description
§bible-io-references
A Rust library for parsing, formatting, serializing, and extracting multilingual Bible references and richer passage expressions, without assuming a particular translation, canon, or versification table.
§Features
- Single verses and inclusive same-chapter, cross-chapter, or cross-book ranges
- Whole books, chapter ranges, comma-separated verse selections, and sequences
- English plus 12 complete localized parsing and formatting packs
- Unicode-aware syntax normalization and UTF-8 source-span mapping
- Configurable aliases, language priority, ambiguity handling, and parse metadata
- Read-only localized alias registries and automatic-collision introspection
- OSIS and USFM serialization and strict reverse parsing for all 83 books
- Parser-driven extraction, replacement, and Markdown linkification in prose
- Optional stable JSON serialization through
serde - No required runtime dependencies
§Installation
cargo add bible-io-referencesEnable Serde support when JSON interoperability is needed:
cargo add bible-io-references --features serde§Reference Parsing
Rust’s standard parsing traits are the primary API:
use bible_io_references::{Book, Reference, VerseRef};
let verse: VerseRef = "John 3:16".parse()?;
assert_eq!(verse.book(), Book::John);
assert_eq!(verse.chapter(), 3);
assert_eq!(verse.verse(), 16);
let range: Reference = "John 3:16-Acts 1:2".parse()?;
assert_eq!(range.to_string(), "John 3:16-Acts 1:2");
VerseRef, VerseRange, and Reference expose strict subtype parsing. All
constructors enforce chapter and verse coordinates in 1..=999; ranges must
move forward in the crate’s documented 83-book order.
§Rich Passages
Use Passage for expressions broader than one contiguous range:
use bible_io_references::Passage;
let passage: Passage = "John 3:16,18-20; Acts 2; Romans 8".parse()?;
assert_eq!(
passage.to_string(),
"John 3:16,18-20; Acts 2; Romans 8"
);
Bare numbers in Obadiah, Philemon, 2 John, 3 John, and Jude use standard
single-chapter shorthand. PassageParser::with_single_chapter_books can replace
that set for a specific application.
§Languages And Formatting
Automatic detection is the default. An explicit language is useful for short aliases or predictable user interfaces:
use bible_io_references::{
BookNameStyle, Language, Passage, ReferenceFormatter,
};
let passage = Passage::parse_with_language("Juan 3:16,18-20", Language::Spanish)?;
let formatter = ReferenceFormatter::for_language(Language::Spanish)
.with_book_name_style(BookNameStyle::Short);
assert_eq!(formatter.format_passage(&passage).to_string(), "Jn 3:16,18-20");
Bundled parsing packs: Arabic, Chinese, English, French, German, Hebrew, Hindi, Indonesian, Korean, Portuguese, Russian, Spanish, and Tagalog. Reserved language variants remain available for custom aliases.
localized_books exposes every registered long name and abbreviation without
allowing mutation. auto_language_collisions returns the normalized aliases
that can identify distinct books during automatic detection.
§Configurable Parsing
use bible_io_references::{
AmbiguityPolicy, Book, Language, ReferenceParser,
};
let parser = ReferenceParser::builder()
.alias("favorite", Book::John)
.preferred_languages([Language::Spanish])
.ambiguity_policy(AmbiguityPolicy::Reject)
.build()?;
let parsed = parser.parse_detailed("favorite 3:16")?;
assert_eq!(parsed.value().start().book(), Book::John);
assert!(parsed.metadata().book_matches()[0].selected().is_custom());
assert_eq!(parsed.metadata().book_matches()[0].selected().alias(), "favorite");
Errors carry a typed ParseErrorKind, a stable snake-case code, and a detailed
diagnostic. Ordinary Rust Result is the non-throwing parse API; try_parse
helpers return Option where error detail is not needed.
§OSIS And USFM
use bible_io_references::{
MachineIdentifiers, Reference, reference_from_osis_identifier,
};
let reference: Reference = "2 Corinthians 6:14-7:1".parse()?;
assert_eq!(reference.osis_identifier(), "2Cor.6.14-2Cor.7.1");
assert_eq!(reference.usfm_identifier(), "2CO 6:14-7:1");
assert_eq!(
reference_from_osis_identifier("2Cor.6.14-2Cor.7.1")?,
reference
);
Machine identifier parsing is intentionally case-sensitive. Cross-book USFM
ranges use the crate’s reversible extension, for example JHN-ACT 21:25-1:2.
§Extraction
Extraction reports Rust-native UTF-8 byte ranges and preserves exact source text:
use bible_io_references::ReferenceExtractor;
let source = "Study John 3:16,18-20 and Acts 2 today.";
let matches = ReferenceExtractor::new().extract(source);
assert_eq!(matches.len(), 2);
assert_eq!(matches[0].source_text(), "John 3:16,18-20");
assert_eq!(&source[matches[0].range()], matches[0].source_text());replace_matches and linkify_markdown process matches once, so text returned
by a callback is never scanned again. Bare-book extraction is opt-in.
§Unicode Normalization
The syntax normalizer handles fullwidth ASCII, Arabic-Indic and Persian digits, common punctuation variants, Unicode spaces, combining marks, and directional controls. It is intentionally reference-specific rather than a general transliteration or Unicode normalization library.
normalize_detailed maps normalized UTF-8 byte ranges back to slice-safe byte
ranges in the original input.
§JSON
With the serde feature, Book, references, and passages use stable wire
shapes. For example, John 3:16 serializes as:
{"type":"verse","book":"jo","chapter":3,"verse":16}Deserialization calls the same checked constructors as normal Rust code, so zero coordinates, empty passage collections, and reversed ranges are rejected. Parse candidates, token matches, and parse metadata also use stable camel-case field names.
§Command Line
cargo install bible-io-references
bible-io-references "John 3:16,18-20"
cargo run -- "John 3:16,18-20"
cargo run -- --language es --format osis "Juan 3:16-17"
cargo run -- --format usfm --input references.txtBatch mode reads one nonblank UTF-8 expression per line. Exit codes are 0
for success, 64 for usage errors, 65 for parse failures, and 66 for input
errors.
§Scope
- Coordinates receive broad sanity checks, not edition-specific validation.
- The ordered 83-book model includes Protestant books, separately modeled Catholic additions, and Eastern Orthodox additions. It is a deterministic range order, not a claim that every tradition uses one universal canon.
- Passage lists use commas and sequences use semicolons; prose words such as
andare not grammar separators.
§Upstream Parity
The Dart package is the authoritative behavioral upstream. The pinned commit, parity evidence, and intentionally allowed Rust differences are documented in UPSTREAM.md. Check a local Dart checkout with:
pwsh tools/parity/check.ps1 -DartCheckout PATH§Development
Test implementations live under tests/unit/ and are included from their
corresponding production modules so private invariants remain covered. Run the
release checks with:
cargo fmt --all -- --check
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo package --allow-dirty --locked§License
GNU Affero General Public License v3.0 only. See LICENSE.
Re-exports§
pub use book::Book;pub use book::ParseBookError;pub use error::ParseError;pub use error::ParseErrorKind;pub use extractor::DEFAULT_MAX_LOOKAHEAD;pub use extractor::DEFAULT_MAX_LOOKBEHIND;pub use extractor::ExtractorConfigError;pub use extractor::ExtractorWindow;pub use extractor::PassageMatch;pub use extractor::ReferenceExtractor;pub use extractor::ReferenceExtractorBuilder;pub use formatter::BookNameStyle;pub use formatter::FormattedBook;pub use formatter::FormattedPassage;pub use formatter::FormattedReference;pub use formatter::ReferenceFormatter;pub use identifiers::IdentifierError;pub use identifiers::IdentifierErrorKind;pub use identifiers::IdentifierFormat;pub use identifiers::MachineIdentifiers;pub use identifiers::book_from_osis_identifier;pub use identifiers::book_from_usfm_identifier;pub use identifiers::reference_from_osis_identifier;pub use identifiers::reference_from_usfm_identifier;pub use language::Language;pub use language::ParseLanguageError;pub use parser::AUTO_LANGUAGE_PRECEDENCE;pub use parser::AmbiguityPolicy;pub use parser::BookCandidate;pub use parser::BookMatch;pub use parser::ParseMetadata;pub use parser::Parsed;pub use parser::ParserBuilder;pub use parser::ReferenceParser;pub use parser::auto_language_collisions;pub use passage::BookPassage;pub use passage::ChapterPassage;pub use passage::DEFAULT_SINGLE_CHAPTER_BOOKS;pub use passage::Passage;pub use passage::PassageBuildError;pub use passage::PassageParser;pub use passage::PassageSequence;pub use passage::VersePassage;pub use reference::Coordinate;pub use reference::CoordinateError;pub use reference::MAX_CHAPTER_NUMBER;pub use reference::MAX_VERSE_NUMBER;pub use reference::RangeOrderError;pub use reference::Reference;pub use reference::VerseRange;pub use reference::VerseRef;
Modules§
- book
- Canonical Bible book names and standard machine-readable identifiers.
- error
- Typed parsing errors and stable machine-readable error codes.
- extractor
- Parser-driven extraction and replacement of passages embedded in prose.
- formatter
- Localized, configurable formatting for references and passages.
- identifiers
- Strict OSIS and USFM machine identifiers.
- language
- Language identifiers and bundled parsing-support introspection.
- normalize
- Unicode normalization tailored to Bible-reference syntax.
- parser
- Reusable, configurable parsing for verse references and ranges.
- passage
- Rich Bible passage values and parsing.
- reference
- Checked verse, range, and reference value types.
Structs§
- Localized
Book - Bundled localized names and abbreviations for one Bible book.
Functions§
- localized_
books - Returns the bundled localized records for a concrete language.
- localized_
name - Returns a preferred bundled name without applying an English fallback.
- long_
name - Returns the preferred long book name, falling back to English.
- parse_
reference - Parse a verse or inclusive verse range using automatic language detection.
- short_
name - Returns the preferred compact book abbreviation, falling back to English.
- verse_
range_ ref_ from_ str - Parse an inclusive verse range using the crate’s normalized parser.
- verse_
ref_ from_ str - Parse a verse reference using the crate’s normalized parser.
Type Aliases§
- Verse
Range Ref - Compatibility name for callers familiar with the Dart package.