# flpdf
A Pure Rust PDF toolkit modeled on the [qpdf](https://github.com/qpdf/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`](docs/qpdf-compat.md)).
## Workspace layout
This repository is a Cargo workspace with two crates:
| `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
```bash
cargo build --workspace
cargo test --workspace
```
The default build is Pure Rust; flpdf depends on `flate2` without pinning a
backend, so `cargo build` resolves to flate2's default (`miniz_oxide`).
### Choosing a DEFLATE backend (downstream consumers)
flpdf does **not** re-export flate2's backend features (`zlib-rs`, `zlib`,
`zlib-ng`, …) as its own features. A downstream crate that wants a specific
backend adds `flate2` as a direct dependency and enables the feature there;
Cargo's feature unification applies it to flpdf's copy of `flate2` too. This
follows the pattern that
[krilla PR #390](https://github.com/LaurenzV/krilla/pull/390) settled on —
keeping the backend choice with the consumer avoids forcing a single
implementation on every downstream build.
```toml
# Pure Rust, faster than miniz_oxide, WASM-friendly.
[dependencies]
flpdf = "..."
flate2 = { version = "1", features = ["zlib-rs"] }
```
```toml
# System libz — matches qpdf's compress2() byte-for-byte.
[dependencies]
flpdf = "..."
flate2 = { version = "1", features = ["zlib"] }
```
> [!TIP]
> Because `flate2` here is a Cargo-feature knob rather than a crate you
> actually `use`, tools like `cargo-machete` and `cargo-udeps` will flag it as
> an unused dependency. Ignore it in your `Cargo.toml`:
>
> ```toml
> [package.metadata.cargo-machete]
> ignored = ["flate2"]
>
> [package.metadata.cargo-udeps.ignore]
> normal = ["flate2"]
> ```
### `qpdf-zlib-compat` (internal parity feature)
The optional `qpdf-zlib-compat` feature on the `flpdf` crate pins flate2's
backend to classic libz (via `libz-sys`) for flpdf's own bytes-identical test
suite. It is used by the parity CI job only and is not intended for production
consumers — pick a backend via the pattern above instead.
```bash
cargo test -p flpdf --features qpdf-zlib-compat
```
## CLI usage
```bash
cargo build --release -p flpdf-cli
./target/release/flpdf --help
```
Common subcommands (`flpdf <subcommand> --help` for full options):
```bash
flpdf check input.pdf # validate structure / report diagnostics
flpdf pages input.pdf # show page structure
flpdf qdf input.pdf out.qdf # qdf-style flat dump
flpdf rewrite input.pdf out.pdf # fresh full rewrite
flpdf rewrite --linearize in.pdf out.pdf # produce a linearized PDF
flpdf zlib-flate -compress < in.bin > out.z # raw zlib compression (stdin/stdout)
```
The `zlib-flate` subcommand also ships as a standalone `zlib-flate` binary
alias. It accepts qpdf's `-uncompress`, `-compress`, and `-compress=n` forms.
Encrypted inputs are supported via `--password`, `--password-file`, and
`--password-mode {auto,bytes,hex-bytes,unicode}` (the `unicode` mode validates
UTF-8 and preserves the supplied bytes for V=5 R=5/R=6 handlers, matching qpdf
11.9.0). 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
```rust
use std::fs::File;
use std::io::BufReader;
use flpdf::{pages, write_pdf, Pdf};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let file = BufReader::new(File::open("input.pdf")?);
let mut pdf = Pdf::open(file)?;
for object_ref in pages::page_refs(&mut pdf)? {
println!("page: {object_ref}");
}
let mut out = File::create("output.pdf")?;
write_pdf(&mut pdf, &mut out)?;
Ok(())
}
```
The crate is organized as a few small layers:
- `Pdf` — parsed-but-lazy document handle (`Pdf::open` reads the trailer and
cross-reference table; `ObjectHandle::try_*` accessors resolve objects on demand).
- `Object`, `Dictionary`, `Stream`, `ObjectRef` — the data model.
- `pages`, `outline_object_helper` — read-only traversal helpers that mirror
`qpdf --show-pages` and `--json-key=outlines`.
- `write_pdf` / `write_qdf` — fresh full rewrite and qdf-style flat dump.
- `job::QPDFJob::check` — qpdf-compatible document validation and warning
completion for CLI and library job consumers.
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.
## Examples
Runnable examples live in [`crates/flpdf/examples`](crates/flpdf/examples).
Each one is a small, self-contained program; run any of them with:
```bash
cargo run --example <name> -p flpdf
```
| `inspect` | Inspect and dump a PDF's basic structure end to end. |
| `extract_page` | Extract a single page (0-based) into a new minimal PDF. |
| `extract_pages` | Extract a non-contiguous selection (pages 1, 3, 5) into a new file. |
| `extract_first_5_pages` | Extract the first 5 pages of a document into a new file. |
| `list_form_fields` | List every interactive form field with its type and value. |
| `walk_outline` | Walk the document outline (bookmarks) as an indented tree. |
| `pull_attachments` | Pull every embedded attachment out of a document to disk. |
| `reorder_pages` | Reorder a document's pages (here: reverse them) and write the result. |
| `merge_pdfs` | Merge two PDFs, preserving fonts shared between the merged-in pages. |
| `splice_pages` | Splice pages from one document into another at a given index. |
## 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
with `BLESS=1 cargo test -p flpdf-cli --test compat_matrix_baseline`.
- **Decisions registry** — [`docs/qpdf-compat-decisions.md`](docs/qpdf-compat-decisions.md)
records every deliberate divergence point so contributors can tell
intentional gaps from incidental ones.
The full workflow lives in [`docs/qpdf-compat.md`](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`](CONTRIBUTING.md) for the contributor guide and
[`AGENTS.md`](AGENTS.md) / [`CLAUDE.md`](CLAUDE.md) for AI-agent conventions.
Issue tracking uses [beads](https://github.com/steveyegge/beads); start with
`bd ready` to see available work.
## License
Licensed under either of
- Apache License, Version 2.0
- MIT License
at your option.