Add a setting for writing PDF files in a more compact way (#72)

Author: LaurenzV

src/annotations.rs

@@ -796,10 +796,13 @@ mod tests {
     #[test]
     fn test_annotations() {
         test!(
-            crate::tests::slice(|w| {
-                w.annotation(Ref::new(1)).rect(Rect::new(0.0, 0.0, 1.0, 1.0));
-                w.annotation(Ref::new(2)).rect(Rect::new(1.0, 1.0, 0.0, 0.0));
-            }),
+            crate::tests::slice(
+                |w| {
+                    w.annotation(Ref::new(1)).rect(Rect::new(0.0, 0.0, 1.0, 1.0));
+                    w.annotation(Ref::new(2)).rect(Rect::new(1.0, 1.0, 0.0, 0.0));
+                },
+                Settings::default()
+            ),
             b"1 0 obj",
             b"<<",
             b"  /Type /Annot",

src/chunk.rs

@@ -1,5 +1,25 @@
 use super::*;
 
+/// Settings that should be applied while writing a PDF file.
+#[derive(Debug, Clone, Copy)]
+pub struct Settings {
+    /// Whether to enable pretty-writing. In this case, `pdf-writer` will
+    /// serialize PDFs in such a way that they are easier to read by humans by
+    /// applying more padding and indentation, at the cost of larger file sizes.
+    /// If disabled, `pdf-writer` will serialize objects as compactly as
+    /// possible, leading to better file sizes but making it harder to inspect
+    /// the file manually.
+    ///
+    /// _Default value_: `true`.
+    pub pretty: bool,
+}
+
+impl Default for Settings {
+    fn default() -> Self {
+        Self { pretty: true }
+    }
+}
+
 /// A builder for a collection of indirect PDF objects.
 ///
 /// This type holds written top-level indirect PDF objects. Typically, you won't
@@ -14,18 +34,37 @@ use super::*;
 pub struct Chunk {
     pub(crate) buf: Buf,
     pub(crate) offsets: Vec<(Ref, usize)>,
+    pub(crate) settings: Settings,
 }
 
 impl Chunk {
-    /// Create a new chunk with the default capacity (currently 1 KB).
+    /// Create a new chunk with the default settings and buffer capacity
+    /// (currently 1 KB).
     #[allow(clippy::new_without_default)]
     pub fn new() -> Self {
-        Self::with_capacity(1024)
+        Self::with_settings(Settings::default())
     }
 
-    /// Create a new chunk with the specified initial capacity.
+    /// Create a new chunk with the given settings and the default buffer
+    /// capacity (currently 1 KB).
+    pub fn with_settings(settings: Settings) -> Self {
+        Self::with_settings_and_capacity(settings, 1204)
+    }
+
+    /// Create a new chunk with the default settings and the specified initial
+    /// capacity.
     pub fn with_capacity(capacity: usize) -> Self {
-        Self { buf: Buf::with_capacity(capacity), offsets: vec![] }
+        Self::with_settings_and_capacity(Settings::default(), capacity)
+    }
+
+    /// Create a new chunk with the given settings and the specified initial
+    /// buffer capacity.
+    pub fn with_settings_and_capacity(settings: Settings, capacity: usize) -> Self {
+        Self {
+            buf: Buf::with_capacity(capacity),
+            offsets: vec![],
+            settings,
+        }
     }
 
     /// The number of bytes that were written so far.
@@ -35,6 +74,11 @@ impl Chunk {
         self.buf.len()
     }
 
+    /// Reserve an additional number of bytes in the buffer.
+    pub fn reserve(&mut self, additional: usize) {
+        self.buf.reserve(additional);
+    }
+
     /// The bytes already written so far.
     pub fn as_bytes(&self) -> &[u8] {
         self.buf.as_slice()
@@ -148,7 +192,7 @@ impl Chunk {
     /// Start writing an indirectly referenceable object.
     pub fn indirect(&mut self, id: Ref) -> Obj<'_> {
         self.offsets.push((id, self.buf.len()));
-        Obj::indirect(&mut self.buf, id)
+        Obj::indirect(&mut self.buf, id, self.settings)
     }
 
     /// Start writing an indirectly referenceable stream.

src/content.rs

@@ -1,9 +1,11 @@
 use super::*;
-use crate::object::TextStrLike;
+use crate::chunk::Settings;
+use crate::object::{is_delimiter_character, TextStrLike};
 
 /// A builder for a content stream.
 pub struct Content {
     buf: Buf,
+    settings: Settings,
     q_depth: usize,
 }
 
@@ -16,15 +18,26 @@ impl Content {
         Self::with_capacity(1024)
     }
 
+    /// Create a new content stream with the given settings.
+    pub fn with_settings(settings: Settings) -> Self {
+        let mut content = Self::new();
+        content.settings = settings;
+        content
+    }
+
     /// Create a new content stream with the specified initial buffer capacity.
     pub fn with_capacity(capacity: usize) -> Self {
-        Self { buf: Buf::with_capacity(capacity), q_depth: 0 }
+        Self {
+            buf: Buf::with_capacity(capacity),
+            q_depth: 0,
+            settings: Default::default(),
+        }
     }
 
     /// Start writing an arbitrary operation.
     #[inline]
     pub fn op<'a>(&'a mut self, operator: &'a str) -> Operation<'a> {
-        Operation::start(&mut self.buf, operator)
+        Operation::start(&mut self.buf, operator, self.settings)
     }
 
     /// Return the buffer of the content stream.
@@ -51,12 +64,13 @@ pub struct Operation<'a> {
     buf: &'a mut Buf,
     op: &'a str,
     first: bool,
+    settings: Settings,
 }
 
 impl<'a> Operation<'a> {
     #[inline]
-    pub(crate) fn start(buf: &'a mut Buf, op: &'a str) -> Self {
-        Self { buf, op, first: true }
+    pub(crate) fn start(buf: &'a mut Buf, op: &'a str, settings: Settings) -> Self {
+        Self { buf, op, first: true, settings }
     }
 
     /// Write a primitive operand.
@@ -79,25 +93,47 @@ impl<'a> Operation<'a> {
         self
     }
 
-    /// Start writing an an arbitrary object operand.
+    /// Start writing an arbitrary object operand.
     #[inline]
     pub fn obj(&mut self) -> Obj<'_> {
-        if !self.first {
-            self.buf.push(b' ');
-        }
+        // In case we are writing the first object, we want a newline to
+        // separate it from previous operations (looks nicer). Otherwise, a
+        // space is sufficient.
+        let pad_byte = if self.first { b'\n' } else { b' ' };
+
+        // Similarly to how chunks are handled, we always add padding when
+        // pretty-writing is enabled, and only lazily add padding depending on
+        // whether it's really necessary if not.
+        let needs_padding = if self.settings.pretty {
+            if !self.buf.is_empty() {
+                self.buf.push(pad_byte);
+            }
+
+            false
+        } else {
+            true
+        };
+
         self.first = false;
-        Obj::direct(self.buf, 0)
+        Obj::direct(self.buf, 0, self.settings, needs_padding)
     }
 }
 
 impl Drop for Operation<'_> {
     #[inline]
     fn drop(&mut self) {
-        if !self.first {
-            self.buf.push(b' ');
+        let pad_byte = if self.first { b'\n' } else { b' ' };
+
+        // For example, in case we previously wrote a BT operator and then a
+        // `[]` operand in the next operation, we don't need to pad them.
+        if (self.settings.pretty
+            || self.buf.last().is_some_and(|b| !is_delimiter_character(*b)))
+            && !self.buf.is_empty()
+        {
+            self.buf.push(pad_byte);
         }
+
         self.buf.extend(self.op.as_bytes());
-        self.buf.push(b'\n');
     }
 }
 
@@ -1708,4 +1744,44 @@ mod tests {
             b"/F1 12 Tf\nBT\n[] TJ\n[(AB) 2 (CD)] TJ\nET"
         );
     }
+
+    #[test]
+    fn test_content_array_no_pretty() {
+        let mut content = Content::with_settings(Settings { pretty: false });
+
+        content.set_font(Name(b"F1"), 12.0);
+        content.set_font(Name(b"F2"), 15.0);
+        content.begin_text();
+        content.show_positioned().items();
+        content
+            .show_positioned()
+            .items()
+            .show(Str(b"AB"))
+            .adjust(2.0)
+            .show(Str(b"CD"))
+            .adjust(4.0)
+            .show(Str(b"EF"));
+        content.end_text();
+
+        assert_eq!(
+            content.finish().into_vec(),
+            b"/F1 12 Tf/F2 15 Tf\nBT[]TJ[(AB)2(CD)4(EF)]TJ\nET"
+        );
+    }
+
+    #[test]
+    fn test_content_dict_no_pretty() {
+        let mut content = Content::with_settings(Settings { pretty: false });
+
+        let mut mc = content.begin_marked_content_with_properties(Name(b"Test"));
+        let mut properties = mc.properties();
+        properties.actual_text(TextStr("Actual")).identify(1);
+        properties.artifact().kind(ArtifactType::Background);
+        mc.finish();
+
+        assert_eq!(
+            content.finish().into_vec(),
+            b"/Test<</ActualText(Actual)/MCID 1/Type/Background>>BDC"
+        );
+    }
 }

src/lib.rs

@@ -191,7 +191,7 @@ pub mod types {
 }
 
 pub use self::buf::{Buf, Limits};
-pub use self::chunk::Chunk;
+pub use self::chunk::{Chunk, Settings};
 pub use self::content::Content;
 pub use self::object::{
     Array, Date, Dict, Filter, Finish, LanguageIdentifier, Name, Null, Obj, Primitive,
@@ -221,15 +221,29 @@ pub struct Pdf {
 }
 
 impl Pdf {
-    /// Create a new PDF with the default buffer capacity (currently 8 KB).
+    /// Create a new PDF with the default settings and buffer capacity
+    /// (currently 8 KB).
     #[allow(clippy::new_without_default)]
     pub fn new() -> Self {
-        Self::with_capacity(8 * 1024)
+        Self::with_settings(Settings::default())
     }
 
-    /// Create a new PDF with the specified initial buffer capacity.
+    /// Create a new PDF with the given settings and the default buffer capacity
+    /// (currently 8 KB).
+    pub fn with_settings(settings: Settings) -> Self {
+        Self::with_settings_and_capacity(settings, 8 * 1024)
+    }
+
+    /// Create a new PDF with the default settings and the specified initial
+    /// buffer capacity.
     pub fn with_capacity(capacity: usize) -> Self {
-        let mut chunk = Chunk::with_capacity(capacity);
+        Self::with_settings_and_capacity(Settings::default(), capacity)
+    }
+
+    /// Create a new PDF with the given settings and the specified initial
+    /// buffer capacity.
+    pub fn with_settings_and_capacity(settings: Settings, capacity: usize) -> Self {
+        let mut chunk = Chunk::with_settings_and_capacity(settings, capacity);
         chunk.buf.extend(b"%PDF-1.7\n%\x80\x80\x80\x80\n\n");
         Self {
             chunk,
@@ -298,7 +312,7 @@ impl Pdf {
     ///
     /// Panics if any indirect reference id was used twice.
     pub fn finish(self) -> Vec<u8> {
-        let Chunk { mut buf, mut offsets } = self.chunk;
+        let Chunk { mut buf, mut offsets, settings } = self.chunk;
 
         offsets.sort();
 
@@ -346,7 +360,7 @@ impl Pdf {
         // Write the trailer dictionary.
         buf.extend(b"trailer\n");
 
-        let mut trailer = Obj::direct(&mut buf, 0).dict();
+        let mut trailer = Obj::direct(&mut buf, 0, settings, false).dict();
         trailer.pair(Name(b"Size"), xref_len);
 
         if let Some(catalog_id) = self.catalog_id {
@@ -412,11 +426,11 @@ mod tests {
     }
 
     /// Return the slice of bytes written during the execution of `f`.
-    pub fn slice<F>(f: F) -> Vec<u8>
+    pub fn slice<F>(f: F, settings: Settings) -> Vec<u8>
     where
         F: FnOnce(&mut Pdf),
     {
-        let mut w = Pdf::new();
+        let mut w = Pdf::with_settings(settings);
         let start = w.len();
         f(&mut w);
         let end = w.len();
@@ -425,12 +439,16 @@ mod tests {
     }
 
     /// Return the slice of bytes written for an object.
-    pub fn slice_obj<F>(f: F) -> Vec<u8>
+    pub fn slice_obj<F>(f: F, settings: Settings) -> Vec<u8>
     where
         F: FnOnce(Obj<'_>),
     {
-        let buf = slice(|w| f(w.indirect(Ref::new(1))));
-        buf[8..buf.len() - 9].to_vec()
+        let buf = slice(|w| f(w.indirect(Ref::new(1))), settings);
+        if settings.pretty {
+            buf[8..buf.len() - 9].to_vec()
+        } else {
+            buf[8..buf.len() - 8].to_vec()
+        }
     }
 
     #[test]

src/macros.rs

@@ -19,7 +19,15 @@ macro_rules! test {
 #[cfg(test)]
 macro_rules! test_obj {
     (|$obj:ident| $write:expr, $($tts:tt)*) => {{
-        test!(crate::tests::slice_obj(|$obj| { $write; }), $($tts)*)
+        test!(crate::tests::slice_obj(|$obj| { $write; }, crate::Settings::default()), $($tts)*)
+    }}
+}
+
+/// Test how an object is written, without pretty-printing.
+#[cfg(test)]
+macro_rules! test_obj_no_pretty {
+    (|$obj:ident| $write:expr, $($tts:tt)*) => {{
+        test!(crate::tests::slice_obj(|$obj| { $write; }, crate::Settings { pretty: false }), $($tts)*)
     }}
 }