Skip to main content

Crate bible_io_references

Crate bible_io_references 

Source
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-references

Enable 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.txt

Batch 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 and are 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§

LocalizedBook
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§

VerseRangeRef
Compatibility name for callers familiar with the Dart package.