hayro-syntax

A low-level library for reading PDF files.

This crate implements most of the points in the Syntax chapter of the PDF reference, and therefore serves as a very good basis for building various abstractions on top of it, without having to reimplement the PDF parsing logic.

This crate does not provide more high-level functionality, such as parsing fonts or color spaces. Such functionality is out-of-scope for hayro-syntax, since this crate is supposed to be as light-weight and application-agnostic as possible. Functionality-wise, this crate is therefore close to feature-complete (the main missing feature is support for encrypted documents), though more low-level APIs might be added in the future.

Example

This short example shows you how to load a PDF file and iterate over the content streams of all pages.

use std::path::PathBuf;
use std::sync::Arc;
use hayro_syntax::Pdf;

let data = std::fs::read(PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../hayro-tests/pdfs/text_with_rise.pdf")).unwrap();
let pdf = Pdf::new(Arc::new(data)).unwrap();
let pages = pdf.pages();

for page in pages.iter() {
    for op in page.typed_operations() {
        println!("{:?}", op);
    }
}

Safety

There is one usage of unsafe, needed to implement caching using a self-referential struct. Other than that, there is no usage of unsafe, especially in any of the parser code.

Features

The supported features include:

• Parsing the xref table in all of its possible formats, including xref streams.
• Best-effort attempt at repairing broken PDF files.
• Parsing of all objects types (also in object streams).
• Parsing and evaluating PDF functions.
• Parsing and decoding PDF streams.
• Iterating over pages as well as their content streams in a typed fashion.
• The crate is very lightweight, especially in comparison to other PDF crates, assuming you don't enable the jpeg2000 feature (see further below).

Limitations

• There are still a few features missing, for example, support for encrypted PDFs. In addition to that, many properties (like page annotations) are currently not exposed.
• This crate is for read-only processing, you cannot directly use it to manipulate PDF files. If you need to do that, there are other crates in the Rust ecosystem that are suitable for this.

Cargo features

This crate has one feature, jpeg2000. PDF allows for the insertion of JPEG2000 images. However, unfortunately, JPEG2000 is a very complicated format. There exists a Rust jpeg2k crate that allows decoding such images. However, it is a relatively heavy dependency, a lot of unsafe code (due to having been ported with c2rust), and also has a dependency on libc, meaning that you might be restricted in the targets you can build to. Because of this, I recommend not enabling this feature unless you absolutely need to be able to support such images.