pdf-untangle 0.3.0

Untangle garbled PDF text: layout-aware extraction that reconstructs reading order, strips page furniture, and splits documents into structured, citable sections
Documentation
//! # 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`](mod@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()`](crate::extract()) entry point and the
//! `pdf-untangle extract` / `pdf-untangle check` subcommands run.
//!
//! ## Example
//!
//! ```no_run
//! # fn main() -> anyhow::Result<()> {
//! 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);
//! # Ok(()) }
//! ```

pub mod extract;
pub mod layout;
pub mod output;
pub mod profile;
pub mod structure;

pub use output::{Document, Provision};
pub use profile::Profile;

use std::path::Path;

use anyhow::{Context, Result};

/// Extract structured provisions from a text-based PDF file using `profile`.
///
/// This is the single high-level entry point: Layer 1 (extraction) → Layer 2
/// (layout reconstruction) → Layer 3 (profile-driven structure detection).
/// The file's name (final path component) becomes each provision's
/// `source_file`. See [`extract_bytes`] to work from an in-memory PDF.
pub fn extract(pdf: &Path, profile: &Profile) -> Result<Document> {
    let bytes = std::fs::read(pdf).with_context(|| format!("reading {}", pdf.display()))?;
    let source_file = pdf
        .file_name()
        .map(|n| n.to_string_lossy().into_owned())
        .unwrap_or_else(|| pdf.display().to_string());
    extract_bytes(&bytes, profile, &source_file)
}

/// [`extract`], but from PDF bytes already in memory. `source_file` is
/// recorded verbatim on every provision (use the original file name).
pub fn extract_bytes(pdf_bytes: &[u8], profile: &Profile, source_file: &str) -> Result<Document> {
    let pages = extract::runs(pdf_bytes)?;
    let layout = layout::reconstruct(&pages);
    structure::detect(&layout, profile, source_file)
}