Skip to main content

Crate pdf_untangle

Crate pdf_untangle 

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

  1. extract — PDF → positioned text runs per page (pluggable backends)
  2. layout — runs → ordered lines/blocks (columns, furniture, flow)
  3. 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§

pub use output::Document;
pub use output::Provision;
pub use profile::Profile;

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_file is recorded verbatim on every provision (use the original file name).