Crate pdf_writer

A step-by-step, zero-unsafe PDF writer.

The entry point into the API is the main PdfWriter, which constructs the document into one big internal buffer. The top-level writer has many methods to create specialized writers for specific PDF objects. These all follow the same general pattern: They borrow the main buffer mutably, expose a builder pattern for writing individual fields in a strongly typed fashion and finish up the object when dropped.

There are a few more top-level structs with internal buffers, like the builder for Content streams, but wherever possible buffers are borrowed from parent writers to minimize allocations.

Writers

The writers contained is this crate fall roughly into two categories.

Core writers enable you to write arbitrary PDF objects.

• The Obj writer allows to write most fundamental PDF objects (numbers, strings, arrays, dictionaries, …). It is exposed through PdfWriter::indirect to write top-level indirect objects and through Array::obj and Dict::key to compose objects.
• Streams are exposed through a separate PdfWriter::stream method since they must be indirect objects.

Specialized writers for things like a page or an image stream expose the core writer’s capabilities in a strongly typed fashion.

• A Page writer, for example, is just a thin wrapper around a Dict and it even derefs to a dictionary in case you need to write a field that is not yet exposed by the typed API.
• Similarly, the ImageStream derefs to a Stream, so that the filter() function can be shared by all kinds of streams. The Stream in turn derefs to a Dict so that you can add arbitrary fields to the stream dictionary.

When you bind a writer to a variable instead of just writing a chained builder pattern, you may need to manually drop() it before starting a new object.

Minimal example

The following example creates a PDF with a single, empty A4 page.

use pdf_writer::{PdfWriter, Rect, Ref};

// Define some indirect reference ids we'll use.
let catalog_id = Ref::new(1);
let page_tree_id = Ref::new(2);
let page_id = Ref::new(3);

// Start writing with the PDF version 1.7 header.
let mut writer = PdfWriter::new(1, 7);

// The document catalog and a page tree with one A4 page that uses no resources.
writer.catalog(catalog_id).pages(page_tree_id);
writer.pages(page_tree_id).kids(vec![page_id]);
writer.page(page_id)
    .parent(page_tree_id)
    .media_box(Rect::new(0.0, 0.0, 595.0, 842.0))
    .resources();

// Finish with cross-reference table and trailer and write to file.
std::fs::write("target/empty.pdf", writer.finish(catalog_id))?;

For a more comprehensive overview, check out the hello world example in the repository, which creates a document with text in it.

Note

This crate does not validate whether you use the correct indirect reference ids or whether you write all required fields for an object. Refer to the PDF specification to make sure you create valid PDFs.

Modules

writers

Writers for specific PDF structures.

Structs

Array	Writer for an array.
Content	Builder for a content stream.
Dict	Writer for a dictionary.
FontFlags	Bitflags describing various characteristics of fonts.
IndirectGuard	A guard that finishes an indirect object when released.
Name	A name object.
Null	The null object.
Obj	Writer for an arbitrary object.
PdfWriter	The root writer.
Rect	A rectangle, specified by two opposite corners.
Ref	A reference to an indirect object.
Str	A string object (any byte sequence).
Stream	Writer for a stream dictionary.
StreamGuard	A guard that finishes a stream when released.
SystemInfo	Specifics about a character collection.
TypedArray	Writer for an array with fixed primitive value type.
TypedDict	Writer for a dictionary with fixed primitive value type.
UnicodeCmap	Builder for a /ToUnicode character map stream.

Enums

CidFontType	The subtype of a CID font.
ColorSpace	A color space.
Filter	A compression filter.
LineCapStyle	How to terminate lines.

Traits

Guard	Finishes an entity when released.
Primitive	A primitive PDF object.