diff --git a/Cargo.lock b/Cargo.lock index d1e5d3cec..11dcdd679 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2553,6 +2553,7 @@ name = "craft-ps" version = "0.1.0" dependencies = [ "craft-eps", + "flate2", "kurbo 0.13.1", "miniz_oxide 0.8.9", "pdf-writer", diff --git a/crates/ps/Cargo.toml b/crates/ps/Cargo.toml index baa9050e4..fe3b9ca99 100644 --- a/crates/ps/Cargo.toml +++ b/crates/ps/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "craft-ps" -description = "PostScript and EPS for Craft apps: an EPS interpreter that paints into PDF" +description = "PostScript and EPS for Craft apps: writing primitives, and an EPS interpreter that paints into PDF" version.workspace = true edition.workspace = true license.workspace = true @@ -13,6 +13,7 @@ workspace = true [features] default = [] read = ["dep:craft-eps", "dep:pdf-writer", "dep:miniz_oxide", "dep:weezl", "dep:skrifa", "dep:kurbo"] +write = ["dep:kurbo", "dep:flate2"] [dependencies] craft-eps = { workspace = true, optional = true } @@ -21,6 +22,7 @@ miniz_oxide = { workspace = true, optional = true } weezl = { workspace = true, optional = true } skrifa = { workspace = true, optional = true } kurbo = { workspace = true, optional = true } +flate2 = { version = "1", default-features = false, features = ["rust_backend"], optional = true } [[example]] name = "eps2pdf" diff --git a/crates/ps/README.md b/crates/ps/README.md index 51deedcc2..2ccc83247 100644 --- a/crates/ps/README.md +++ b/crates/ps/README.md @@ -4,9 +4,17 @@ PostScript and EPS for the Craft apps. No feature is enabled by default. | Feature | Provides | | --- | --- | +| `write` | PostScript writing primitives: numbers, strings, matrices, path data and Flate | | `read` | An EPS interpreter: runs the program and returns what it paints as a one-page PDF | -Writing PostScript and EPS (craft-libs #115) is planned as a separate feature next to `read`. +## Writing PostScript + +`write` emits the tokens of a PostScript or EPS program. The caller writes the page program and +any short operator names a prolog binds; this module formats numbers (non-finite values as zero), +escapes string and byte literals, writes matrices, raises quadratic segments to cubics, and +compresses or inflates Flate (`FlateDecode`) payloads. Path and paint operators can use the +Language Reference names or the one-letter names a bound prolog defines. Container concerns (DSC +comments, a binary preview header, ASCII85) stay in `craft-eps`. ## Reading EPS diff --git a/crates/ps/src/lib.rs b/crates/ps/src/lib.rs index ab5383259..291820ee4 100644 --- a/crates/ps/src/lib.rs +++ b/crates/ps/src/lib.rs @@ -1,5 +1,7 @@ //! PostScript and EPS for the Craft apps. //! +//! - [`write`] (feature `write`): numbers, strings, matrices, path data and Flate, so an app can +//! emit a PostScript or EPS program. //! - [`read`] (feature `read`): runs an EPS and gives what it paints as a one-page vector PDF, //! for apps that place EPS files as graphics. #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] @@ -7,3 +9,5 @@ #[cfg(feature = "read")] pub mod read; +#[cfg(feature = "write")] +pub mod write; diff --git a/crates/ps/src/write.rs b/crates/ps/src/write.rs new file mode 100644 index 000000000..3cb5d9664 --- /dev/null +++ b/crates/ps/src/write.rs @@ -0,0 +1,333 @@ +//! PostScript writing primitives: numbers, strings, matrices, path data and Flate. +//! +//! The caller decides the page program and any short operator names a prolog binds; this module +//! makes what it writes valid PostScript tokens. Numbers that are not finite are written as zero, +//! because PostScript has no spelling for them. Strings and byte strings are escaped so no value +//! can break out of a literal. +//! +//! ``` +//! use craft_ps::write::{num, push_path, string, PathOps}; +//! use kurbo::BezPath; +//! +//! assert_eq!(num(1.5), "1.5"); +//! assert_eq!(string("a (b)"), "(a \\(b\\))"); +//! +//! let mut path = BezPath::new(); +//! path.move_to((1.0, 2.0)); +//! path.line_to((3.0, 4.0)); +//! path.close_path(); +//! let mut out = String::new(); +//! push_path(&mut out, &path, PathOps::SHORT); +//! assert_eq!(out, "1 2 m\n3 4 l\nh\n"); +//! ``` + +use std::fmt::Write; +use std::io::{Read, Write as _}; + +use kurbo::{Affine, BezPath, PathEl}; + +/// `v` as PostScript writes it: at most four decimals, no trailing zeros (0 when not finite). +pub fn num(v: f64) -> String { + let mut s = String::new(); + push_num(&mut s, v); + s +} + +/// Append [`num`]`(v)` to `s`. +pub fn push_num(s: &mut String, v: f64) { + push_num_places(s, v, 4); +} + +/// The value [`num`]`(v)` stands for, as a reader parses it back. +pub fn written(v: f64) -> f64 { + num(v).parse().unwrap_or(0.0) +} + +/// Append `v` to `s` with at most `places` decimals (up to 9), no trailing zeros (0 when not +/// finite). +pub fn push_num_places(s: &mut String, v: f64, places: u32) { + let places = places.min(9); + let scale = 10f64.powi(places as i32); + // Past where the scaling overflows, values have no fractional digits to round. + let v = if !v.is_finite() { + 0.0 + } else if (v * scale).is_finite() { + (v * scale).round() / scale + } else { + v + }; + if v == v.trunc() && v.abs() < 1e15 { + let _ = write!(s, "{}", v as i64); + return; + } + let start = s.len(); + let _ = write!(s, "{v:.*}", places as usize); + let keep = s[start..].trim_end_matches('0').trim_end_matches('.').len(); + s.truncate(start + keep); +} + +/// `vs` as numbers separated by spaces, then a space. +pub fn push_nums(s: &mut String, vs: &[f64]) { + for v in vs { + push_num(s, *v); + s.push(' '); + } +} + +/// `text` as a PostScript string: `(` `)` `\` escaped, anything outside printable ASCII as octal +/// escapes of its UTF-8 bytes. +pub fn string(text: &str) -> String { + ps_literal(text.bytes()) +} + +/// `bytes` as a PostScript string: `(` `)` `\` escaped, carriage returns, line feeds and tabs as +/// `\r` `\n` `\t`, other bytes outside printable ASCII as octal escapes. +pub fn bytes(bytes: &[u8]) -> String { + ps_literal_bytes(bytes, true) +} + +fn ps_literal(bytes: impl Iterator) -> String { + ps_literal_bytes_iter(bytes, false) +} + +fn ps_literal_bytes(bytes: &[u8], escape_whitespace: bool) -> String { + ps_literal_bytes_iter(bytes.iter().copied(), escape_whitespace) +} + +fn ps_literal_bytes_iter(bytes: impl Iterator, escape_whitespace: bool) -> String { + let mut s = String::from("("); + for b in bytes { + match b { + b'(' | b')' | b'\\' => { + s.push('\\'); + s.push(char::from(b)); + } + b'\r' if escape_whitespace => s.push_str("\\r"), + b'\n' if escape_whitespace => s.push_str("\\n"), + b'\t' if escape_whitespace => s.push_str("\\t"), + 0x20..=0x7e => s.push(char::from(b)), + _ => { + let _ = write!(s, "\\{b:03o}"); + } + } + } + s.push(')'); + s +} + +/// A matrix operand `[a b c d e f]`. +pub fn matrix(a: Affine) -> String { + let mut s = String::from("["); + push_nums(&mut s, &a.as_coeffs()); + s.pop(); + s.push(']'); + s +} + +/// Names of the path operators written after each segment. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PathOps { + pub moveto: &'static str, + pub lineto: &'static str, + pub curveto: &'static str, + pub closepath: &'static str, +} + +impl PathOps { + /// The PostScript Language Reference names. + pub const STANDARD: Self = Self { moveto: "moveto", lineto: "lineto", curveto: "curveto", closepath: "closepath" }; + /// One-letter names a bound prolog can define (`m`, `l`, `c`, `h`). + pub const SHORT: Self = Self { moveto: "m", lineto: "l", curveto: "c", closepath: "h" }; +} + +/// Append path `path` (`moveto`, `lineto`, `curveto`, `closepath` by default; quadratics raised to +/// cubics), one segment a line. Pass [`PathOps::SHORT`] for the one-letter names a prolog binds. +pub fn push_path(s: &mut String, path: &BezPath, ops: PathOps) { + let mut last = kurbo::Point::ZERO; + let mut start = kurbo::Point::ZERO; + for el in path.elements() { + match *el { + PathEl::MoveTo(p) => { + push_nums(s, &[p.x, p.y]); + s.push_str(ops.moveto); + s.push('\n'); + (last, start) = (p, p); + } + PathEl::LineTo(p) => { + push_nums(s, &[p.x, p.y]); + s.push_str(ops.lineto); + s.push('\n'); + last = p; + } + PathEl::QuadTo(a, p) => { + let c1 = last + (a - last) * (2.0 / 3.0); + let c2 = p + (a - p) * (2.0 / 3.0); + push_nums(s, &[c1.x, c1.y, c2.x, c2.y, p.x, p.y]); + s.push_str(ops.curveto); + s.push('\n'); + last = p; + } + PathEl::CurveTo(a, b, p) => { + push_nums(s, &[a.x, a.y, b.x, b.y, p.x, p.y]); + s.push_str(ops.curveto); + s.push('\n'); + last = p; + } + PathEl::ClosePath => { + s.push_str(ops.closepath); + s.push('\n'); + last = start; + } + } + } +} + +/// The winding rule a fill or clip uses. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum FillRule { + NonZero, + EvenOdd, +} + +/// Operator names written for a fill or a clip (which also ends the path). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PaintOps { + pub fill: &'static str, + pub eofill: &'static str, + pub clip: &'static str, + pub eoclip: &'static str, +} + +impl PaintOps { + /// The PostScript Language Reference names. The clip operators also start a new path. + pub const STANDARD: Self = Self { fill: "fill\n", eofill: "eofill\n", clip: "clip newpath\n", eoclip: "eoclip newpath\n" }; + /// Short names a bound prolog can define (`f`, `f*`, `W`, `W*`). + pub const SHORT: Self = Self { fill: "f\n", eofill: "f*\n", clip: "W\n", eoclip: "W*\n" }; +} + +/// The fill operator for `rule`. +pub fn fill_op(rule: FillRule, ops: PaintOps) -> &'static str { + match rule { + FillRule::NonZero => ops.fill, + FillRule::EvenOdd => ops.eofill, + } +} + +/// The clip operator for `rule` (it also ends the path). +pub fn clip_op(rule: FillRule, ops: PaintOps) -> &'static str { + match rule { + FillRule::NonZero => ops.clip, + FillRule::EvenOdd => ops.eoclip, + } +} + +/// `data` compressed for `FlateDecode` (zlib). +pub fn deflate(data: &[u8]) -> Vec { + let mut encoder = flate2::write::ZlibEncoder::new(Vec::with_capacity(data.len() / 2), flate2::Compression::default()); + // Writing to a Vec doesn't fail. + let _ = encoder.write_all(data); + encoder.finish().unwrap_or_default() +} + +/// zlib `data` inflated, when it is valid and at most `max` bytes. +pub fn inflate(data: &[u8], max: u64) -> Option> { + let mut out = vec![]; + flate2::read::ZlibDecoder::new(data).take(max + 1).read_to_end(&mut out).ok()?; + (out.len() as u64 <= max).then_some(out) +} + +#[cfg(test)] +mod tests { + use super::{ + FillRule, PaintOps, PathOps, bytes, clip_op, deflate, fill_op, inflate, matrix, num, push_num, push_num_places, push_nums, push_path, string, + written, + }; + use kurbo::{Affine, BezPath}; + + #[test] + fn huge_finite_numbers_are_valid_postscript() { + for v in [1.5e305, -1.5e305, f64::MAX, f64::MIN] { + let s = num(v); + assert!(!s.is_empty() && s.chars().all(|c| c.is_ascii_digit() || c == '-' || c == '.'), "{v}: got {s:?}"); + } + } + + #[test] + fn numbers_keep_the_decimals_asked_for() { + let places = |v: f64, n: u32| { + let mut s = String::new(); + push_num_places(&mut s, v, n); + s + }; + assert_eq!(num(0.123_456_78), "0.1235"); + assert_eq!(places(0.123_456_78, 7), "0.1234568"); + assert_eq!(places(f64::from(0.4f32), 7), "0.4"); + assert_eq!(places(2.5, 7), "2.5"); + assert_eq!(places(f64::NAN, 7), "0"); + assert_eq!(places(f64::INFINITY, 2), "0"); + assert_eq!(places(f64::NEG_INFINITY, 2), "0"); + assert_eq!(num(-2.0), "-2"); + assert_eq!(num(0.0), "0"); + assert_eq!(written(0.123_456_78), 0.1235); + let mut s = String::new(); + push_num(&mut s, 3.0); + assert_eq!(s, "3"); + let mut nums = String::new(); + push_nums(&mut nums, &[1.0, 2.5]); + assert_eq!(nums, "1 2.5 "); + assert_eq!(places(1.0, 20), "1"); + assert_eq!(places(1.23456789, 9), "1.23456789"); + } + + #[test] + fn strings_and_bytes_are_escaped() { + assert_eq!(string("ok"), "(ok)"); + assert_eq!(string("a (b) \\c"), "(a \\(b\\) \\\\c)"); + assert_eq!(string("รค"), "(\\303\\244)"); + assert_eq!(bytes(b"ok"), "(ok)"); + assert_eq!(bytes(b"(\r\n\t)"), "(\\(\\r\\n\\t\\))"); + assert_eq!(bytes(&[0x01, 0xff]), "(\\001\\377)"); + assert_eq!(string("a\nb"), "(a\\012b)"); + } + + #[test] + fn matrix_and_paths_use_the_operator_names_asked_for() { + assert_eq!(matrix(Affine::new([1.0, 0.0, 0.0, 1.0, 10.0, 20.0])), "[1 0 0 1 10 20]"); + let mut path = BezPath::new(); + path.move_to((1.0, 2.0)); + path.line_to((3.0, 4.0)); + path.quad_to((5.0, 6.0), (7.0, 8.0)); + path.curve_to((9.0, 10.0), (11.0, 12.0), (13.0, 14.0)); + path.close_path(); + let mut short = String::new(); + push_path(&mut short, &path, PathOps::SHORT); + assert_eq!(short, "1 2 m\n3 4 l\n4.3333 5.3333 5.6667 6.6667 7 8 c\n9 10 11 12 13 14 c\nh\n"); + let mut standard = String::new(); + push_path(&mut standard, &path, PathOps::STANDARD); + assert!( + standard.contains("moveto\n") && standard.contains("lineto\n") && standard.contains("curveto\n") && standard.ends_with("closepath\n") + ); + let mut empty = String::new(); + push_path(&mut empty, &BezPath::new(), PathOps::STANDARD); + assert!(empty.is_empty()); + assert_eq!(fill_op(FillRule::NonZero, PaintOps::SHORT), "f\n"); + assert_eq!(fill_op(FillRule::EvenOdd, PaintOps::SHORT), "f*\n"); + assert_eq!(clip_op(FillRule::NonZero, PaintOps::SHORT), "W\n"); + assert_eq!(clip_op(FillRule::EvenOdd, PaintOps::SHORT), "W*\n"); + assert_eq!(fill_op(FillRule::NonZero, PaintOps::STANDARD), "fill\n"); + assert_eq!(fill_op(FillRule::EvenOdd, PaintOps::STANDARD), "eofill\n"); + assert_eq!(clip_op(FillRule::NonZero, PaintOps::STANDARD), "clip newpath\n"); + assert_eq!(clip_op(FillRule::EvenOdd, PaintOps::STANDARD), "eoclip newpath\n"); + } + + #[test] + fn flate_round_trips_and_honours_the_size_limit() { + let data = b"PostScript FlateDecode payload \x00\xff".repeat(32); + let compressed = deflate(&data); + assert_ne!(compressed, data); + assert_eq!(inflate(&compressed, data.len() as u64).as_deref(), Some(data.as_slice())); + assert_eq!(inflate(&compressed, (data.len() as u64) - 1), None); + assert_eq!(inflate(b"not zlib", 64), None); + assert_eq!(inflate(&deflate(b""), 0).as_deref(), Some(&b""[..])); + } +}