usfm3

An error-tolerant USFM 3.x parser written in Rust. Outputs USJ (JSON), USX (XML), normalized USFM, and verse-reference maps.

Also available as a Python package and npm package (WebAssembly).

Features

• Parses all USFM 3.x markers including tables, milestones, sidebars, figures, and nested character styles
• Error-tolerant: always produces a document tree, even from malformed input
• Structured diagnostics with source locations, severity levels, and machine-readable codes
• Semantic validation (chapter/verse sequence, attribute rules, milestone pairing, etc.)
• Multiple output formats: USJ, USX, USFM, and verse-reference maps

Installation

[dependencies]
usfm3 = "0.1"

Usage

let result = usfm3::builder::parse(r#"\id GEN
\c 1
\p
\v 1 In the beginning God created the heavens and the earth.
"#);

// Check for errors
for diag in result.diagnostics.iter() {
    eprintln!("{diag}");
}

// Output as USJ (JSON)
let usj = usfm3::usj::to_usj_string_pretty(&result.document).unwrap();

// Output as USX (XML)
let usx = usfm3::usx::to_usx_string(&result.document).unwrap();

// Output as normalized USFM
let usfm = usfm3::usfm::to_usfm_string(&result.document);

// Output as verse-reference map
let vref = usfm3::vref::to_vref_json_string(&result.document);

// Run semantic validation
let validation_diags = usfm3::validation::validate(&result.document);

Output Formats

License

MIT