Crate pdf_writer[−][src]
Expand description
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 throughPdfWriter::indirect
to write top-level indirect objects and throughArray::obj
andDict::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 aDict
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 aStream
, so that thefilter()
function can be shared by all kinds of streams. TheStream
in turn derefs to aDict
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 and a link 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 for specific PDF structures.
Structs
Bitflags describing various characteristics of annotations.
Writer for an array.
Builder for a content stream.
A date, represented as a text string.
Writer for a dictionary.
Bitflags describing various characteristics of fonts.
A guard that finishes an indirect object when released.
A name object.
The null object.
Writer for an arbitrary object.
Bitflags describing the appearance of an outline item.
The root writer.
A rectangle, specified by two opposite corners.
A reference to an indirect object.
A string object (any byte sequence).
Writer for a stream dictionary.
A guard that finishes a stream when released.
Specifics about a character collection.
A unicode text string object.
Writer for an array with fixed primitive value type.
Writer for a dictionary with fixed primitive value type.
Builder for a /ToUnicode
character map stream.
Enums
What kind of action to perform when clicking a link annotation.
Possible icons for an annotation.
Kind of the annotation to produce.
The kind of line to draw on the border.
The subtype of a CID font.
A color space.
Predominant reading order of text.
A compression filter.
Highlighting effect applied when a user holds the mouse button over some annotations.
How to terminate lines.
How the viewer should lay out the pages in the document.
Elements of the viewer chrome that should be visible when opening the document.
The angle at which the transition plays.
The kind of transition.