flpdf
A Pure Rust PDF toolkit modeled on the qpdf
workflow. flpdf aims for writer-level parity with qpdf — its outputs are
continuously compared against qpdf reference outputs through a golden matrix
(see docs/qpdf-compat.md).
Workspace layout
This repository is a Cargo workspace with two crates:
| Crate | Path | Purpose |
|---|---|---|
flpdf |
crates/flpdf |
Core PDF reader / writer library. |
flpdf-cli |
crates/flpdf-cli |
CLI (flpdf binary) that wraps the library. |
Both crates are licensed under MIT OR Apache-2.0.
Building
The default build is Pure Rust. The optional qpdf-zlib-compat feature links
classic libz via libz-sys so flate2's deflate output matches qpdf's
compress2() byte-for-byte; it is used by bytes-identical tests only and is
not required for production builds.
CLI usage
Common subcommands (flpdf <subcommand> --help for full options):
Encrypted inputs are supported via --password, --password-file, and
--password-mode {auto,bytes,hex-bytes,unicode} (the unicode mode applies
SASLprep for V=5 R=5/R=6 handlers). RC4-backed handlers and revision 5
encryption are gated behind --allow-weak-crypto.
--static-id, --min-version, --force-version, and the qpdf compatibility
flags (--compress-streams, --linearize-pass1) are accepted on rewrite
to keep qtest-style command lines parsing cleanly.
Library usage
use File;
use BufReader;
use ;
The crate is organized as a few small layers:
Pdf— parsed-but-lazy document handle (Pdf::openreads the trailer and cross-reference table, then resolves objects on demand viaPdf::resolve).Object,Dictionary,Stream,ObjectRef— the data model.pages,outline,fonts— read-only traversal helpers that mirrorqpdf --show-pages,--show-outline, and--show-fonts.write_pdf/write_qdf— incremental rewrite and qdf-style flat dump.check_reader— diagnostics gathered during parsing/repair, returning aCheckReportofDiagnostics.
Errors flow through the unified Error enum and the crate-level Result
alias. See the rustdoc on crates/flpdf/src/lib.rs for the full API.
qpdf compatibility
flpdf's writer-level outputs are compared against qpdf in two places:
- Golden matrix —
tests/golden/compat-matrix.md, one row per (fixture, flag) tuple and one column per comparator strategy. Regenerated withBLESS=1 cargo test -p flpdf-cli --test compat_matrix_baseline. - Decisions registry —
docs/qpdf-compat-decisions.mdrecords every deliberate divergence point so contributors can tell intentional gaps from incidental ones.
The full workflow lives in docs/qpdf-compat.md. When
your change re-blesses the matrix or the static-ID baseline, check the PR
template's "Compat matrix" section.
Contributing
See CONTRIBUTING.md for the contributor guide and
AGENTS.md / CLAUDE.md for AI-agent conventions.
Issue tracking uses beads; start with
bd ready to see available work.
License
Licensed under either of
- Apache License, Version 2.0
- MIT License
at your option.