Rasura

Rust API

Every item on the facade, with its signature, parameters and errors. This surface was designed first; the JavaScript one wraps it.

The API is synchronous. Nothing in the library does IO, so there is nothing to await. The asynchrony on the JavaScript side is the Worker boundary, not the work.

Crate layering

Each crate is publishable and usable alone. Dependencies only go upward: nothing in rasura-cos knows what a paragraph is, and nothing in rasura-layout knows how to write a file.

Text
rasura-cos objects, xref, filters, decryption, the writer
rasura-content content streams, graphics and text state, layers
rasura-font parsing, shaping, subsetting, injection, embedding
rasura-layout glyph runs to lines to blocks to a document model
rasura-edit edit operations, reflow, stream patching, sessions
rasura-flow the flow model, the layout engine, composition
rasura the facade documented on this page
rasura-wasm the wasm-bindgen surface
TOML
[dependencies]
rasura = "0.1"
# Or one layer, if that is all you need:
rasura-cos = "0.1"

Opening and creating

On Document.

Reading

On Document.

Whole-document operations

On Document.

Session

On Session<'a>.

Types

Rust
pub enum Fidelity { Exact, Reembedded, Substituted, Overlaid }
pub struct Outcome {
pub fidelity: Fidelity,
pub compromises: Vec<Compromise>,
pub retargeted: usize,
}
pub struct Saved {
pub bytes: Vec<u8>,
pub mode: SaveMode,
/// Zero for a full rewrite, where the concept does not apply.
pub bytes_appended: usize,
pub warnings: Vec<Warning>,
}
pub struct OpenOptions { pub password: String, pub recovery: Recovery }
pub enum Recovery { Auto, Never }
pub struct SaveOptions {
pub mode: Option<SaveMode>,
pub accept_signature_destruction: bool,
}
pub enum SaveMode { Incremental, FullRewrite }
pub enum DocumentKind { BornDigital, Scanned, Mixed }
pub enum TaggedStatus { Tagged, Untagged, Degraded }

Composition has its own small set:

Rust
pub enum Content {
Heading { level: u8, text: String },
Paragraph { text: String },
List { items: Vec<String> },
}
pub struct PageGeometry {
pub size: (f64, f64),
/// Top, right, bottom, left, clockwise from the top.
pub margins: (f64, f64, f64, f64),
pub columns: usize,
pub gutter: f64,
}
pub struct Composition {
pub pages: usize,
pub lines: usize,
pub approximated: usize,
/// Dropped, not substituted.
pub missing: Vec<char>,
pub base_font: String,
pub composite: bool,
/// /StemV cannot be measured from a TrueType file. Always true today.
pub stem_v_estimated: bool,
}

Errors

One error type, always coded. The layers below have their own richer enums; those are kept in Error::detail rather than discarded, because throwing the cause away to keep the surface clean makes debugging somebody else’s PDF impossible.

Rust
pub struct Error { /* private */ }
impl Error {
pub fn code(&self) -> Code;
pub fn message(&self) -> &str;
/// What the failing layer said, when it said anything.
pub fn detail(&self) -> &str;
}
pub enum Code {
Malformed,
EncryptedPasswordRequired,
EncryptedUnsupported,
ScannedNoText,
XfaUnsupported,
Type3GlyphMissing,
FontUnavailable,
Overflow,
StaleSession,
FidelityBelowRequired,
SignatureWouldBeDestroyed,
UnsupportedFilter,
InvalidArgument,
Internal,
}

Matching on codes

Code is Copy and PartialEq, so a match on e.code() is the intended way to branch. The string forms used by the TypeScript surface come from Code::as_str and are written out rather than derived, because a rename that silently changed one would break every caller.