Expand description
§pdf-untangle
Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture (headers/footers/page numbers), repairs hyphenation and page-break flow, and — with a profile — splits a document into structured, citable provisions (rules, statutes, sections).
A PDF stores text as thousands of individually positioned glyphs with no notion of paragraphs, columns, headings, or reading order. Naive extraction yields the familiar mishmash. This crate rebuilds the logical document in three layers:
- extract — PDF → positioned text runs per page (pluggable backends)
- layout — runs → ordered lines/blocks (columns, furniture, flow)
- structure — blocks → provisions, driven by a declarative TOML
Profile(heading patterns, citation template, date formats)
The same crate ships a CLI (cargo install pdf-untangle).
§Status
Layer 1 (extraction) is implemented with two feature-gated backends —
backend-pdfium (Google PDFium, highest fidelity, native library loaded
at runtime) and backend-pure (pure Rust, zero native dependencies; the
crate default) — see extract::runs and the extract
module docs.
Layer 2 (layout reconstruction) is implemented: layout::reconstruct
turns per-page runs into reading-ordered lines and blocks with columns
handled, page furniture stripped (with accounting), hyphenation repaired,
and indentation quantized — this is what pdf-untangle text prints.
Layer 3 (profile-driven structure) is implemented: structure::detect
applies a Profile to the reconstructed layout — this is what the
high-level extract() entry point and the
pdf-untangle extract / pdf-untangle check subcommands run.
§Example
let profile = pdf_untangle::Profile::builtin("cnmi-rules")?;
let doc = pdf_untangle::extract(std::path::Path::new("R05.pdf"), &profile)?;
for p in &doc.provisions {
println!("{} — {} (effective {})", p.citation, p.heading.as_deref().unwrap_or(""), p.effective_date);
}
assert!(doc.line_coverage >= 0.98, "unconsumed: {:?}", doc.unconsumed_lines);Re-exports§
Modules§
- extract
- Layer 1 — PDF → positioned text runs.
- layout
- Layer 2 — positioned runs → ordered logical lines and blocks.
- output
- Output model: structured provisions plus document-level accounting.
- profile
- Declarative document-family profiles (TOML). All jurisdiction knowledge is data, not code: adding a new document family means writing a profile.
- structure
- Layer 3 — blocks → provisions, driven by a
Profile.
Functions§
- extract
- Extract structured provisions from a text-based PDF file using
profile. - extract_
bytes - [
extract], but from PDF bytes already in memory.source_fileis recorded verbatim on every provision (use the original file name).