imprimatur 0.3.0 → 0.4.0

data/ext/imprimatur_native/core/src/pdf/truetype.rs

@@ -0,0 +1,149 @@
+//! A complete TrueType font as a horizontal Type 0 / `CIDFontType2` resource
+//! (ISO 32000-1, 9.7 and 9.10). Document font selection and layout are separate.
+
+mod descriptor;
+mod program;
+#[cfg(test)]
+mod tests;
+
+use std::collections::BTreeMap;
+use std::fmt::{self, Write as _};
+use std::io::Write;
+
+use super::objects::{Num, PdfWriter};
+use crate::font::TrueTypeFont;
+use crate::{Error, Result};
+use descriptor::Descriptor;
+
+/// Objects written in order: Type 0 font, descendant, descriptor, font file,
+/// CID-to-glyph map, `ToUnicode` character map.
+pub const OBJECTS: usize = 6;
+
+/// Collects glyph uses before writing the font resource once for all its pages.
+/// CIDs are allocated per (glyph, original text), not per glyph alone: distinct
+/// characters can share an outline, and a ligature can represent several.
+pub struct EmbeddedFont<'a> {
+    font: TrueTypeFont<'a>,
+    descriptor: Descriptor,
+    program: Vec<u8>,
+    /// CID 1 onwards, with unscaled advances; CID 0 is reserved for .notdef.
+    glyphs: Vec<(u16, u16)>,
+    codes: BTreeMap<(u16, String), u16>,
+}
+
+impl<'a> EmbeddedFont<'a> {
+    /// Reads the metadata needed for a PDF descriptor and checks embedding rights.
+    pub fn new(font: TrueTypeFont<'a>) -> Result<Self> {
+        let descriptor = Descriptor::read(&font)?;
+        let program = program::for_pdf(&font)?;
+        Ok(Self { font, descriptor, program, glyphs: Vec::new(), codes: BTreeMap::new() })
+    }
+
+    /// The two big-endian bytes to put in a PDF text string for this glyph use.
+    /// `text` is its original Unicode sequence, in logical order. Empty text
+    /// omits its `ToUnicode` entry, for glyphs with no text of their own.
+    /// This does not shape text or infer glyphs from characters.
+    pub fn encode_glyph(&mut self, glyph: u16, text: &str) -> Result<[u8; 2]> {
+        // A ToUnicode destination string may contain at most 512 bytes.
+        (text.encode_utf16().take(257).count() <= 256)
+            .ok_or_else(|| invalid("Unicode mapping exceeds 256 UTF-16 code units"))?;
+        let width = self
+            .font
+            .advance_width(glyph)
+            .filter(|_| glyph != 0)
+            .ok_or_else(|| invalid("glyph is missing or outside the font's glyph range"))?;
+        let key = (glyph, text.to_owned());
+        if let Some(code) = self.codes.get(&key) {
+            return Ok(code.to_be_bytes());
+        }
+        let code = u16::try_from(self.glyphs.len() + 1)
+            .map_err(|_| invalid("more than 65535 distinct glyph mappings"))?;
+        self.glyphs.push((glyph, width));
+        self.codes.insert(key, code);
+        Ok(code.to_be_bytes())
+    }
+
+    /// Writes six consecutive objects, starting at `first`, which is the font
+    /// reference for a page's resources. Collect every glyph before calling this.
+    /// Every glyph is embedded with its original ID and outline. The font's cmap
+    /// is replaced by PDF mappings; its table directory and checksums are rebuilt.
+    pub fn write<W: Write>(&self, pdf: &mut PdfWriter<W>, first: usize) -> Result<()> {
+        let (descendant, descriptor, file, mapping, unicode) =
+            (first + 1, first + 2, first + 3, first + 4, first + 5);
+        let name = &self.descriptor.name;
+        pdf.object(
+            first,
+            format_args!(
+                "<< /Type /Font /Subtype /Type0 /BaseFont /{name} /Encoding /Identity-H \
+                 /DescendantFonts [{descendant} 0 R] /ToUnicode {unicode} 0 R >>"
+            ),
+        )?;
+        let scale = 1000.0 / f64::from(self.font.metrics().units_per_em);
+        let default_width = Num(f64::from(self.font.advance_width(0).unwrap_or(0)) * scale);
+        let widths = fmt::from_fn(|f| {
+            // Keep both the outer W array and each inner width array below the
+            // PDF 1.7 implementation limit of 8191 elements (Annex C).
+            for (index, glyphs) in self.glyphs.chunks(256).enumerate() {
+                if index > 0 {
+                    f.write_str(" ")?;
+                }
+                write!(f, "{} [", 1 + index * 256)?;
+                for &(_, width) in glyphs {
+                    write!(f, "{} ", Num(f64::from(width) * scale))?;
+                }
+                f.write_str("]")?;
+            }
+            Ok(())
+        });
+        pdf.object(
+            descendant,
+            format_args!(
+                "<< /Type /Font /Subtype /CIDFontType2 /BaseFont /{name} \
+                 /CIDSystemInfo << /Registry (Adobe) /Ordering (Identity) /Supplement 0 >> \
+                 /FontDescriptor {descriptor} 0 R /DW {default_width} /W [{widths}] \
+                 /CIDToGIDMap {mapping} 0 R >>"
+            ),
+        )?;
+        self.descriptor.write(pdf, descriptor, file)?;
+        pdf.stream(file, &self.program, &[("Length1", &self.program.len())])?;
+        let mut gids = Vec::with_capacity(2 * (self.glyphs.len() + 1));
+        gids.extend_from_slice(&[0, 0]);
+        for &(glyph, _) in &self.glyphs {
+            gids.extend_from_slice(&glyph.to_be_bytes());
+        }
+        pdf.stream(mapping, &gids, &[])?;
+        pdf.stream(unicode, self.to_unicode().as_bytes(), &[])
+    }
+
+    fn to_unicode(&self) -> String {
+        let mut cmap = String::from(
+            "/CIDInit /ProcSet findresource begin\n12 dict begin\nbegincmap\n\
+             /CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def\n\
+             /CMapName /Imprimatur-UCS def\n/CMapType 2 def\n\
+             1 begincodespacerange\n<0000> <FFFF>\nendcodespacerange\n",
+        );
+        let mappings: Vec<_> =
+            self.codes.iter().filter(|((_, text), _)| !text.is_empty()).collect();
+        // CMap mapping operators accept at most 100 entries per block.
+        for chunk in mappings.chunks(100) {
+            // Writing to a String cannot fail.
+            let _ = writeln!(cmap, "{} beginbfchar", chunk.len());
+            for ((_, text), code) in chunk {
+                // Writing to a String cannot fail.
+                let _ = write!(cmap, "<{code:04X}> <");
+                for unit in text.encode_utf16() {
+                    // Writing to a String cannot fail.
+                    let _ = write!(cmap, "{unit:04X}");
+                }
+                cmap.push_str(">\n");
+            }
+            cmap.push_str("endbfchar\n");
+        }
+        cmap.push_str("endcmap\nCMapName currentdict /CMap defineresource pop\nend\nend\n");
+        cmap
+    }
+}
+
+fn invalid(reason: &str) -> Error {
+    Error::malformed("PDF font", reason)
+}

data/ext/imprimatur_native/core/src/pdf.rs

@@ -1,6 +1,7 @@
 //! PDF output: the document laid out with the standard Helvetica fonts
 //! (`WinAnsiEncoding`, so Windows-1252 text), written with our own object
-//! writer. Embedded TrueType fonts, and with them every other script, come next.
+//! writer. `truetype` serializes embedded font resources; connecting these to
+//! document layout, shaping and bidirectional text comes next.
 
 mod font;
 mod layout;
@@ -10,6 +11,12 @@ mod objects;
 mod picture;
 #[cfg(test)]
 mod tests;
+#[cfg(feature = "fonts")]
+#[cfg_attr(
+    not(test),
+    expect(dead_code, reason = "font resources are connected to document layout in a follow-up")
+)]
+mod truetype;
 
 use std::fmt;
 use std::io::Write;
@@ -38,6 +45,7 @@ pub fn write<W: Write>(document: &Document, out: W) -> Result<W> {
                 layout.picture(picture, pictures.len());
                 pictures.push(picture);
             }
+            Block::Symbol(symbol) => layout.symbol(symbol),
             Block::PageBreak => layout.page_break(),
         }
     }

data/ext/imprimatur_native/core/src/read/image.rs

@@ -128,6 +128,20 @@ pub fn png(
     bits: u8,
     palette: Option<&[u8]>,
     rows: &[u8],
+) -> Vec<u8> {
+    png_with_transparency(width, height, color, bits, palette, &[], rows)
+}
+
+/// As [`png`], with a `tRNS` chunk unless `transparency` is empty: a
+/// palette's alphas by index, or the gray or RGB color that is transparent.
+pub fn png_with_transparency(
+    width: u32,
+    height: u32,
+    color: PngColor,
+    bits: u8,
+    palette: Option<&[u8]>,
+    transparency: &[u8],
+    rows: &[u8],
 ) -> Vec<u8> {
     let channels: usize = match color {
         PngColor::Gray | PngColor::Palette => 1,
@@ -157,6 +171,9 @@ pub fn png(
     if let Some(palette) = palette {
         chunk(&mut out, *b"PLTE", palette);
     }
+    if !transparency.is_empty() {
+        chunk(&mut out, *b"tRNS", transparency);
+    }
     chunk(&mut out, *b"IDAT", &compressed);
     chunk(&mut out, *b"IEND", &[]);
     out

data/ext/imprimatur_native/core/src/read.rs

@@ -38,9 +38,10 @@ pub use content::{
     Block, Bounds, Cell, Columns, Content, Grid, Look, Mark, Note, Page, Placed, Sheet, Styled,
     Text, Validation, Value,
 };
-pub use image::{Image, ImageFormat, ImageLocation};
 #[cfg(test)]
-pub(crate) use image::{PngColor, png};
+pub(crate) use image::png;
+pub use image::{Image, ImageFormat, ImageLocation};
+pub(crate) use image::{PngColor, png_with_transparency};
 
 use crate::zip::reader::ZipReader;
 use crate::{Error, Result};

data/ext/imprimatur_native/core/src/style.rs

@@ -41,6 +41,17 @@ impl Color {
     pub(crate) fn argb(self) -> String {
         format!("FF{:06X}", self.0)
     }
+
+    /// `#RRGGBB`, as SVG takes it.
+    pub(crate) fn hex(self) -> String {
+        format!("#{:06X}", self.0)
+    }
+
+    /// Red, green and blue bytes.
+    pub(crate) const fn bytes(self) -> [u8; 3] {
+        let [_, r, g, b] = self.0.to_be_bytes();
+        [r, g, b]
+    }
 }
 
 /// Horizontal alignment within the cell.

data/ext/imprimatur_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "imprimatur_native"
-version = "0.3.0"
+version = "0.4.0"
 description = "Ruby bindings for the imprimatur crate"
 publish = false
 edition.workspace = true

data/ext/imprimatur_native/ffi/src/barcode.rs

@@ -0,0 +1,147 @@
+//! `Imprimatur::Barcode`: a barcode symbol, drawn as SVG or PNG or placed in
+//! a document. `lib/imprimatur/barcode.rb` owns the keyword interface.
+
+use imprimatur::barcode::{self, Level, Look, Symbology};
+use imprimatur::style::Color;
+use magnus::{Error, RString, Ruby, Symbol};
+
+use crate::{OrRaise, argument_error, keyword};
+
+#[magnus::wrap(class = "Imprimatur::Barcode", free_immediately, size)]
+pub struct Barcode(pub barcode::Barcode);
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Kind {
+    Qr,
+    DataMatrix,
+    Ean13,
+    Ean8,
+    UpcA,
+    Code128,
+}
+
+const KINDS: [(&str, Kind); 6] = [
+    ("qr", Kind::Qr),
+    ("datamatrix", Kind::DataMatrix),
+    ("ean13", Kind::Ean13),
+    ("ean8", Kind::Ean8),
+    ("upca", Kind::UpcA),
+    ("code128", Kind::Code128),
+];
+const LEVELS: [(&str, Level); 4] =
+    [("l", Level::Low), ("m", Level::Medium), ("q", Level::Quartile), ("h", Level::High)];
+
+#[expect(clippy::needless_pass_by_value, reason = "magnus passes Ruby arguments as owned values")]
+impl Barcode {
+    /// Called by `Imprimatur::Barcode.encode`.
+    pub fn encode(
+        ruby: &Ruby,
+        symbology: String,
+        data: String,
+        gs1: bool,
+        level: Option<String>,
+    ) -> Result<Self, Error> {
+        let kind = keyword(ruby, "symbology", &symbology, &KINDS)?;
+        let level = level.map(|level| keyword(ruby, "level", &level, &LEVELS)).transpose()?;
+        if level.is_some() && kind != Kind::Qr {
+            return Err(argument_error(ruby, "level: applies to :qr only"));
+        }
+        if gs1 && !matches!(kind, Kind::Qr | Kind::DataMatrix | Kind::Code128) {
+            return Err(argument_error(ruby, "gs1: applies to :qr, :datamatrix and :code128"));
+        }
+        let level = level.unwrap_or_default();
+        let code = match (kind, gs1) {
+            (Kind::Qr, false) => barcode::Barcode::qr(&data, level),
+            (Kind::Qr, true) => barcode::Barcode::gs1_qr(&data, level),
+            (Kind::DataMatrix, false) => barcode::Barcode::data_matrix(&data),
+            (Kind::DataMatrix, true) => barcode::Barcode::gs1_data_matrix(&data),
+            (Kind::Ean13, _) => barcode::Barcode::ean13(&data),
+            (Kind::Ean8, _) => barcode::Barcode::ean8(&data),
+            (Kind::UpcA, _) => barcode::Barcode::upc_a(&data),
+            (Kind::Code128, false) => barcode::Barcode::code128(&data),
+            (Kind::Code128, true) => barcode::Barcode::gs1_128(&data),
+        };
+        Ok(Self(code.or_raise(ruby)?))
+    }
+
+    fn svg(
+        ruby: &Ruby,
+        rb_self: &Self,
+        module: f64,
+        look: (String, Option<String>, bool, Option<u32>),
+    ) -> Result<String, Error> {
+        rb_self.0.svg(module, &self::look(ruby, look)?).or_raise(ruby)
+    }
+
+    /// The PNG as a binary String.
+    fn png(
+        ruby: &Ruby,
+        rb_self: &Self,
+        scale: u32,
+        look: (String, Option<String>, bool, Option<u32>),
+    ) -> Result<RString, Error> {
+        let png = rb_self.0.png(scale, &self::look(ruby, look)?).or_raise(ruby)?;
+        Ok(ruby.str_from_slice(&png))
+    }
+
+    fn symbology(ruby: &Ruby, rb_self: &Self) -> Symbol {
+        let name = match rb_self.0.symbology() {
+            Symbology::QrCode => "qr",
+            Symbology::DataMatrix => "datamatrix",
+            Symbology::Ean13 => "ean13",
+            Symbology::Ean8 => "ean8",
+            Symbology::UpcA => "upca",
+            _ => "code128",
+        };
+        ruby.to_symbol(name)
+    }
+
+    fn text(&self) -> String {
+        self.0.text().to_owned()
+    }
+
+    const fn is_gs1(&self) -> bool {
+        self.0.is_gs1()
+    }
+
+    const fn width(&self) -> usize {
+        self.0.size().0
+    }
+
+    const fn height(&self) -> usize {
+        self.0.size().1
+    }
+
+    /// Rows of modules, true for dark ones.
+    fn modules(&self) -> Vec<Vec<bool>> {
+        let (columns, rows) = self.0.size();
+        (0..rows).map(|y| (0..columns).map(|x| self.0.is_dark(x, y)).collect()).collect()
+    }
+}
+
+/// `[color, background, quiet_zone, bar_height]`, as `Imprimatur::Barcode`
+/// passes them.
+fn look(
+    ruby: &Ruby,
+    (dark, light, quiet_zone, bar_height): (String, Option<String>, bool, Option<u32>),
+) -> Result<Look, Error> {
+    let dark = Color::from_hex(&dark).or_raise(ruby)?;
+    let light = light.map(|light| Color::from_hex(&light)).transpose().or_raise(ruby)?;
+    Ok(Look { dark, light, quiet_zone, bar_height })
+}
+
+pub fn define(ruby: &Ruby, imprimatur: magnus::RModule) -> Result<(), Error> {
+    use magnus::{function, method, prelude::*};
+
+    let class = imprimatur.define_class("Barcode", ruby.class_object())?;
+    class.define_singleton_method("__encode", function!(Barcode::encode, 4))?;
+    class.define_method("__svg", method!(Barcode::svg, 2))?;
+    class.define_method("__png", method!(Barcode::png, 2))?;
+    class.define_method("symbology", method!(Barcode::symbology, 0))?;
+    class.define_method("text", method!(Barcode::text, 0))?;
+    class.define_method("gs1?", method!(Barcode::is_gs1, 0))?;
+    class.define_method("width", method!(Barcode::width, 0))?;
+    class.define_method("height", method!(Barcode::height, 0))?;
+    class.define_method("modules", method!(Barcode::modules, 0))?;
+    Ok(())
+}

data/ext/imprimatur_native/ffi/src/document.rs

@@ -2,10 +2,11 @@
 
 use std::cell::RefCell;
 
-use imprimatur::doc::{Document, PageSize, Paragraph, Picture, Run, Table};
+use imprimatur::doc::{Document, PageSize, Paragraph, Picture, Run, Symbol, Table};
 use imprimatur::style::Color;
 use magnus::{Error, RModule, RString, Ruby, function, method, prelude::*};
 
+use crate::barcode::Barcode;
 use crate::{ALIGNS, DIRECTIONS, OrRaise, RubyBytes, borrow, keyword};
 
 /// `[text, bold, italic, underline, color]`, as `Imprimatur::Paragraph` collects it.
@@ -88,6 +89,32 @@ impl NativeDocument {
         Ok(())
     }
 
+    /// A barcode, `width` and `height` in points, in a `color` "#RRGGBB".
+    fn barcode(
+        ruby: &Ruby,
+        rb_self: &Self,
+        barcode: &Barcode,
+        (width, height): (Option<f64>, Option<f64>),
+        align: Option<String>,
+        color: Option<String>,
+    ) -> Result<(), Error> {
+        let mut symbol = Symbol::new(barcode.0.clone());
+        if let Some(width) = width {
+            symbol = symbol.width(width).or_raise(ruby)?;
+        }
+        if let Some(height) = height {
+            symbol = symbol.height(height).or_raise(ruby)?;
+        }
+        if let Some(align) = align {
+            symbol = symbol.align(keyword(ruby, "align", &align, &ALIGNS)?);
+        }
+        if let Some(color) = color {
+            symbol = symbol.color(Color::from_hex(&color).or_raise(ruby)?);
+        }
+        borrow(ruby, &rb_self.0, "document")?.barcode(symbol);
+        Ok(())
+    }
+
     fn heading(ruby: &Ruby, rb_self: &Self, level: u8, text: String) -> Result<(), Error> {
         borrow(ruby, &rb_self.0, "document")?.heading(level, text).or_raise(ruby)?;
         Ok(())
@@ -175,6 +202,7 @@ pub fn define(ruby: &Ruby, native: RModule) -> Result<(), Error> {
     class.define_method("set_page_points", method!(NativeDocument::set_page_points, 3))?;
     class.define_method("set_margin", method!(NativeDocument::set_margin, 1))?;
     class.define_method("picture", method!(NativeDocument::picture, 4))?;
+    class.define_method("barcode", method!(NativeDocument::barcode, 4))?;
     class.define_method("heading", method!(NativeDocument::heading, 2))?;
     class.define_method("paragraph", method!(NativeDocument::paragraph, 3))?;
     class.define_method("table", method!(NativeDocument::table, 2))?;

data/ext/imprimatur_native/ffi/src/lib.rs

@@ -4,6 +4,7 @@
 //! drives them; sheets cross as indices.
 
 mod archive;
+mod barcode;
 mod blocking;
 mod convert;
 mod document;
@@ -202,16 +203,16 @@ impl std::io::Write for RubyBytes {
     }
 }
 
-/// Mutable access to a wrapped value; Ruby code that calls back into the
-/// same object mid-call gets a `RuntimeError`, not a panic.
 /// A Ruby String's bytes, copied out.
 fn bytes(string: RString) -> Vec<u8> {
+    #[allow(unsafe_code)]
     // SAFETY: the bytes are copied out at once, while the GVL is held and
     // before any Ruby code can run and move or free the string.
-    #[allow(unsafe_code)]
     unsafe { string.as_slice() }.to_vec()
 }
 
+/// Mutable access to a wrapped value; Ruby code that calls back into the
+/// same object mid-call gets a `RuntimeError`, not a panic.
 fn borrow<'a, T>(ruby: &Ruby, cell: &'a RefCell<T>, what: &str) -> Result<RefMut<'a, T>, Error> {
     cell.try_borrow_mut().map_err(|_| {
         Error::new(
@@ -315,6 +316,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     style.define_singleton_method("__build", function!(Style::build, 13))?;
     let validation = imprimatur.define_class("Validation", ruby.class_object())?;
     validation.define_singleton_method("__build", function!(Validation::build, 8))?;
+    barcode::define(ruby, imprimatur)?;
 
     let native = imprimatur.define_module("Native")?;
     native.define_singleton_method("markdown", function!(read::markdown_native, 4))?;

data/lib/imprimatur/barcode.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # A barcode: QR Code, Data Matrix, EAN-13, EAN-8, UPC-A or Code 128, and the
+  # GS1 forms of QR Code, Data Matrix and Code 128 (GS1-128). Built with
+  # {Imprimatur.barcode}; draw it with {#svg} or {#png}, or place it in a
+  # {Document} with {Document#barcode}. The class itself is native.
+  #
+  #   qr = Imprimatur.barcode(:qr, 'https://id.gs1.org/01/09506000134352')
+  #   File.write('qr.svg', qr.svg(module_size: 4))
+  #
+  #   label = Imprimatur.barcode(:code128, '(00)106141412345678908', gs1: true)
+  #   File.binwrite('label.png', label.png(module_size: 3))
+  #
+  #   Imprimatur.barcode(:ean13, '950600013435').text # => "9506000134352"
+  class Barcode
+    SYMBOLOGIES = %i[qr datamatrix ean13 ean8 upca code128].freeze
+
+    # @param symbology [:qr, :datamatrix, :ean13, :ean8, :upca, :code128]
+    # @param data [String] text; a GTIN's digits for EAN and UPC, the check
+    #   digit added when left out; with +gs1: true+, a GS1 element string
+    #   such as "(01)09506000134352(17)251231(10)AB12"
+    # @param gs1 [Boolean] a GS1 QR Code, GS1 DataMatrix or GS1-128
+    # @param level [:l, :m, :q, :h, nil] a QR Code's error correction, :m unless set
+    # @return [Barcode]
+    # @raise [Imprimatur::Error] data the symbology cannot hold, an invalid
+    #   element string, or a wrong check digit
+    # @raise [ArgumentError] an unknown symbology or level, or one that does not apply
+    def self.encode(symbology, data, gs1: false, level: nil)
+      __encode(symbology.to_s, String(data), gs1 ? true : false, level&.to_s)
+    end
+
+    private_class_method :__encode
+
+    # @param module_size [Numeric] user units (pixels) a module, 0.01 to 1000
+    # @param color [String] the bars, "#RRGGBB"
+    # @param background [String, nil] "#RRGGBB", or nil for none
+    # @param quiet_zone [Boolean] keep the blank margin scanners need
+    # @param bar_height [Integer, nil] a linear code's bar height in modules;
+    #   the symbology's nominal height unless set
+    # @return [String] SVG markup
+    # @raise [Imprimatur::Error] a module size or color out of range
+    def svg(module_size: 4, color: '#000000', background: '#FFFFFF', quiet_zone: true, bar_height: nil)
+      __svg(Float(module_size), look(color, background, quiet_zone, bar_height))
+    end
+
+    # @param module_size [Integer] pixels a module
+    # @param (see #svg)
+    # @return [String] the PNG bytes (binary): one bit a pixel, the background
+    #   transparent when nil
+    # @raise [Imprimatur::Error] a size of 0, an image above 65 536 pixels a side,
+    #   or an invalid color
+    def png(module_size: 4, color: '#000000', background: '#FFFFFF', quiet_zone: true, bar_height: nil)
+      __png(Integer(module_size), look(color, background, quiet_zone, bar_height))
+    end
+
+    # @!method symbology
+    #   @return [Symbol] one of {SYMBOLOGIES}
+    # @!method text
+    #   @return [String] what it encodes: the data given, or a GTIN with its check digit
+    # @!method gs1?
+    #   @return [Boolean] whether it carries a GS1 element string
+    # @!method width
+    #   @return [Integer] modules across, without the quiet zone
+    # @!method height
+    #   @return [Integer] modules down; 1 for a linear code
+    # @!method modules
+    #   @return [Array<Array<Boolean>>] rows of modules, true for dark
+
+    def inspect = "#<#{self.class} #{symbology}#{' gs1' if gs1?} #{text.inspect}>"
+
+    private
+
+    def look(color, background, quiet_zone, bar_height)
+      [color.to_s, background&.to_s, quiet_zone ? true : false, bar_height && Integer(bar_height)]
+    end
+  end
+end

data/lib/imprimatur/document.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  # A flowing document (headings, paragraphs, tables, pictures, page breaks)
+  # A flowing document (headings, paragraphs, tables, pictures, barcodes, page breaks)
   # that renders to PDF and DOCX from the same content.
   #
   #   doc = Imprimatur::Document.new(page_numbers: true)
@@ -49,6 +49,22 @@ module Imprimatur
       self
     end
 
+    # A barcode in the flow: vector shapes in a PDF, a 300 dpi picture in DOCX.
+    # Drawn at +width+ or +height+ points (a QR Code or Data Matrix keeps
+    # square modules; a linear code's height is its bars'), or else at its
+    # symbology's usual module size; never larger than the page leaves room for.
+    # Its quiet zone is part of its size.
+    #
+    # @param barcode [Barcode] from {Imprimatur.barcode}
+    # @param align [:left, :center, :right, nil]
+    # @param color [String, nil] the bars, "#RRGGBB"; black unless set
+    # @return [self]
+    # @raise [Imprimatur::Error] a size out of range, or an invalid color
+    def barcode(barcode, width: nil, height: nil, align: nil, color: nil)
+      @native.barcode(barcode, [width && Float(width), height && Float(height)], align&.to_s, color&.to_s)
+      self
+    end
+
     # @param text [String]
     # @param level [Integer] 1 (the title) to 3
     # @return [self]

data/lib/imprimatur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/imprimatur.rb

@@ -6,6 +6,7 @@ require_relative 'imprimatur/formula'
 require_relative 'imprimatur/native'
 require_relative 'imprimatur/style'
 require_relative 'imprimatur/validation'
+require_relative 'imprimatur/barcode'
 require_relative 'imprimatur/xlsx'
 require_relative 'imprimatur/document'
 require_relative 'imprimatur/reader'
@@ -38,6 +39,9 @@ module Imprimatur
     # @see Validation.build
     def validation(**) = Validation.build(**)
 
+    # @see Barcode.encode
+    def barcode(symbology, data, **) = Barcode.encode(symbology, data, **)
+
     # Builds a {Document} and renders it as PDF. With a path, saves it there
     # and returns the path; without, returns the bytes.
     #