Crate pdfrum_edit

Expand description

§pdfrum-edit

The crate that writes (ISO 32000-1 §7.5.8). A save either rewrites the whole file or appends a new body, cross-reference section and trailer to the bytes already there. Page import and reordering, N-up imposition, font subsetting, image embedding and re-encryption live here.

use std::sync::Arc;
use pdfrum_edit::{EditDoc, SaveOptions, save};
use pdfrum_parser::{LoadOptions, load};

let bytes = std::fs::read(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/files/hello.pdf"))?;
let doc = load(Arc::from(bytes), &LoadOptions::default())?;
let mut out = Vec::new();
save(&EditDoc::new(&doc), &SaveOptions::default(), &mut out)?;
assert!(out.starts_with(b"%PDF"));

An untouched page is copied as stored; a touched one is regenerated, and regeneration is lossy. This is the single fact to know before editing. The content of a page you did not modify is written back byte for byte, so a save is not a re-encode of the document. A page whose graph you did change has its content stream rebuilt from that graph, and the rebuild does not preserve everything the original said: colour comes back as rg/RG, and shadings, text clipping modes and Type 3 glyph runs are dropped. Edit the pages you mean to change and nothing else.

SaveMode chooses between the two file shapes. An incremental save appends and leaves the original bytes intact, which is what keeps an existing digital signature verifiable and what a reader expects of a form fill; a full save rewrites and can drop what nothing references any more. An unencrypted save is byte-reproducible under IdSource::Fixed. An encrypted one draws its file key and AES vectors from the operating system: reproducible ciphertext is reproducible secrets, which is not what a seed is for.

Part of pdfrum. #![forbid(unsafe_code)].

MIT OR Apache-2.0

Structs§

AttachmentOptions: What an attachment carries besides its name and bytes.
AttachmentOptionsBuilder: Builds an AttachmentOptions a setting at a time.
Canvas: One page’s drawing surface.
Dash: A dash pattern — ISO 32000-1 §8.4.3.6’s dash array and phase, written as d.
EditDoc: A document plus the edits made to it.
EmbeddedFont: A font dictionary this session added, ready to name from a content stream.
EmbeddedImage: An image XObject this session added, ready to place on a page.
Encryption: How a document is to be encrypted on save (ISO 32000-2 §7.6.4.4).
Encryptor: Enciphers the strings and stream payloads of one indirect object.
FileId: The /ID array a save will write, and whether minting it invalidated the document’s encryption key.
GidMap: How the glyphs of a font were renumbered by subsetting.
ImageBuilder: An image placement, ready to PageEdit::push.
ImportOptions: How an import behaves.
IvSource: Where a save’s AES initialisation vectors come from.
MissingGlyph: A character an embedded font has no glyph for.
MiterLimit: The ratio of miter length to line width past which a LineJoin::Miter corner is drawn beveled instead — ISO 32000-1 §8.4.3.5’s M.
NUpOptions: How an N-up imposition behaves.
PageRange: A parsed page range: zero-based page indices, in the order named, with duplicates kept.
PageRewrite: Everything a save has to do to a page whose objects were edited.
PathBuilder: A filled or stroked path, ready to PageEdit::push.
Regenerated: One regenerated /Contents element.
ResourceTable: The resource dictionaries of one page, while its streams are regenerated.
SaveOptions: Everything a save may be asked to do differently.
StampOptions: How a stamp is drawn.
StampOptionsBuilder: Builds a StampOptions a setting at a time.
Stroke: A stroke’s colour, width and pen shape, in canvas units.
Subsetted: A subset font program and the renumbering it performed.
SvgFontssvg-text: The font faces an ingested SVG’s <text> may be set in.
SvgFormsvg-import: Drawing compiled once into a Form XObject, placeable on any number of pages.
SvgIngestReportsvg-import: Everything one draw_svg could not carry into the page.
TextBuilder: A run of text, ready to PageEdit::push.
UnknownFlattenMode: The error FlattenMode’s FromStr returns.
UnknownStampPosition: The error StampPosition’s FromStr returns.
UnsupportedItemsvg-import: One construct the walk could not carry, and where it was.

Enums§

ContentsShape: Where a regenerated element lands in the page’s /Contents.
Error: A failure that stops the editor producing output.
Fill: Which points a fill considers inside.
FlattenMode: Which annotations flattening draws.
Flattened: What flattening a page did.
FontEncoding: How character codes in a content stream select glyphs of an embedded font.
IdSource: Where the bytes of a fresh /ID element come from.
LineCap: How the open ends of a stroked subpath are drawn — ISO 32000-1 §8.4.3.3’s line cap style, written as J.
LineJoin: How two segments meet at a corner — ISO 32000-1 §8.4.3.4’s line join style, written as j.
PageBox: One of the five page boxes (ISO 32000-1 §14.11.2).
Paint: How a shape is painted.
PixelFormat: How the bytes handed to crate::EditDoc::embed_image are laid out.
SaveMode: How a document is written back out.
StampPosition: Where a stamp sits on the page, as the page is displayed.
StandardFont: One of the fourteen standard fonts.
SvgFitsvg-import: How the SVG’s own coordinate box is placed in the destination rectangle.
Unsupportedsvg-import: A construct in the source SVG that PDF drawing cannot carry.

Functions§

add_attachment: Adds an embedded file named name, sorted into the /EmbeddedFiles name tree by name — creating the tree when the document has none — and returns its index among the attachments.
add_blank_page: Add an empty page of width by height points at index at (past the end appends), and return its reference.
apply_rewrite: Apply a page’s regenerated content to edit.
build_graph: The object graph of dict’s page for editing, read through r: the base document for a page as it was opened, or an editing session’s overlay for the page as that session’s edits leave it — so a stream an earlier edit appended is a clean stream of the graph, and the names it uses are kept.
delete_attachment: Removes attachment index from the name tree; Ok(false) when there is no such attachment.
delete_pages: Delete the pages range names, by the base document’s numbering.
flatten: Bakes the page’s annotation appearances into its content and removes the annotations, the reference implementation’s way: one form XObject FFT<n> (the first such name free in the page’s /XObject resources), its box the crop box, drawing each appearance stream through the matrix that lands its box on the annotation’s rectangle; the page’s own content wrapped in q … Q with the form’s Do after it; /MediaBox and /CropBox normalized and written; the retired widgets pruned from the interactive form, which goes when it empties. A widget another page also lists keeps the form.
import_pages: Import pages from src into dest.
n_page_to_one: Impose pages from src onto sheets in dest.
pdf_date: time as a PDF date string (ISO 32000-1 §7.9.4): D:YYYYMMDDHHmmSSZ00'00', always in UTC, which is the one zone every reader agrees on.
pdf_date_to_iso8601: A PDF date string (D:YYYYMMDDHHmmSSOHH'mm') as XMP’s ISO 8601.
regenerate: Rewrite the dirty content streams of page, or None when none is dirty.
remove_attachment: Removes every attachment named name from the name tree; Ok(false) when there is none. The objects go with the next full save’s garbage collection.
save: Write doc to out.
set_attachment_description: Sets the file specification’s /Desc; Ok(false) when there is no such attachment.
set_attachment_file: Replaces attachment index’s embedded file with a new stream carrying /Type /EmbeddedFile, /DL <len> and /Params << /Size <len> /CheckSum <md5> >>, linked as /EF << /F <ref> >> on the file specification; a MIME type or date the old stream had is not carried over. Ok(false) when there is no such attachment.
set_attachment_param: Sets a /Params text entry on attachment index’s embedded file — CreationDate, ModDate, any key — creating /Params when missing; a CheckSum given as <HEX…> is stored as that hex string. Ok(false) when the attachment has no embedded file.
set_info_entry: Set or remove one text entry of the document’s /Info dictionary.
set_page_box: Set one of a page’s boxes.
set_page_rotation: Set a page’s /Rotate. degrees is normalized to a multiple of 90; a value that is not one is rounded to the nearest.
shared_objects: The object numbers more than one object in doc points at.
string_width: The advance of codes in the font font names, in thousandths of an em.
subset: Subset a font program to gids.
to_pdfa: Run the conversion, returning what it did and the bytes when it converted.
write_float: Append one number: 10.5, .29, -7, 0.
write_matrix: Append a matrix as a b c d e f — single spaces, no brackets, no trailing space. This is the operand list of cm and Tm.
write_point: Append a point as x y.
write_rect: Append a rectangle as left bottom width height — not the x0 y0 x1 y1 an array-valued /MediaBox uses. This is the operand list of re, so the last two numbers are extents and may be negative.

Type Aliases§

ShareCounts: How many objects still reference each object number.