imprimatur 0.3.0-aarch64-linux-gnu → 0.5.0-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cec8c0fa26e3628bd1d67a514909be24610c8d03ca7f087e422a0a05e66fb8ee
-  data.tar.gz: d80d26028f03816a403fb1907f934ebd5d643d8d22bea5a0d7e2677a1963701d
+  metadata.gz: 5a6d6451a7a370921f43b37e27a8edb7d886a4923981afd28a256b424b85234e
+  data.tar.gz: e74c978a45ce43cc0856b186b71f38d3204aea8cb71c4f0ed5d961bd4f0dc874
 SHA512:
-  metadata.gz: 7a9153c976c1571f303e65cd0e41bc9c9768122e57ad928dcf81ca8f973aca20b7812d42f82e1455d183deaa05ebdb707e0545302b84aad0cb3f2e0b03cd287f
-  data.tar.gz: 94498b1778cc9cd937070971bec6f9261f5e4c4d5fb916f5a2ef0c8a62efb3187201b9d64ea92bfd241c35779fea50bf50624845d23a729f4dfcea602c1976a8
+  metadata.gz: bf5c3cc806be6379e109c335d65e4b1f84662cbdcb569db4ae0e9fd0e028d4185cf0f9f0b4cd7cc37ac00cc8a313878aaddaee276898b5835e4365f25fe0dfb4
+  data.tar.gz: 0ac1716d1208f48001683efafd3bba638ddc134ff1d67c545a7ad123f99213ee9ff83a96eb7603ca3f3f64ba1cdb8a14507128f530adf21c3e6a5ab989ebca95

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.5.0](https://github.com/seuros/imprimatur/compare/v0.4.0...v0.5.0) (2026-10-18)
+
+
+### Features
+
+* a binary String is always a document's bytes, a path must name a regular file, and reads stop at max_bytes ([3484a64](https://github.com/seuros/imprimatur/commit/3484a64b791beb2e9f90cd485441fae255e223f0))
+
+## [0.4.0](https://github.com/seuros/imprimatur/compare/v0.3.0...v0.4.0) (2026-10-18)
+
+
+### Features
+
+* barcodes: QR Code, Data Matrix, EAN-13, EAN-8, UPC-A and Code 128, GS1 forms included, as SVG, PNG and in documents ([ade7b68](https://github.com/seuros/imprimatur/commit/ade7b68f4c5adcab9d2ee0b935288eea7ec2eea6))
+* **pdf:** add embedded TrueType font resources ([c0e3be4](https://github.com/seuros/imprimatur/commit/c0e3be4ef46ede94fcc840840e82d8ccb6679f3e))
+* **pdf:** add embedded TrueType font resources ([313075f](https://github.com/seuros/imprimatur/commit/313075fe8ba1bedc9f4156060aeedcbb0e0a8bef))
+
 ## [0.3.0](https://github.com/seuros/imprimatur/compare/v0.2.0...v0.3.0) (2026-10-17)
 
 

data/README.md

@@ -9,7 +9,8 @@ a 40,000-character cell is refused at the door, not discovered by Excel's
   as `imprimatur` on crates.io; the gem wraps it.
 - **No third-party format stack.** The XML writer and the zip container are
   written here, from ECMA-376 and the zip specification; only deflate
-  (`miniz_oxide`) and CRC-32 (`crc32fast`) come from crates.
+  (`miniz_oxide`) and CRC-32 (`crc32fast`) come from crates, and QR Code and
+  Data Matrix encoding (`qrcode`, `datamatrix`) for barcodes.
 - **Deterministic.** The same document always gives the same bytes.
 - **Native only.** CRuby 4.0+. No pure Ruby fallback, no JRuby, no TruffleRuby.
 
@@ -223,6 +224,45 @@ dashes, the euro sign. Anything else (Arabic, Hebrew, Greek, CJK, emoji) raises
 script. Embedded TrueType fonts, and with them every script and proper RTL in
 PDF, are the next step.
 
+## Barcodes
+
+QR Code, Data Matrix, EAN-13, EAN-8, UPC-A and Code 128, and the GS1 forms of
+QR Code, Data Matrix and Code 128 (GS1-128):
+
+```ruby
+qr = Imprimatur.barcode(:qr, "https://id.gs1.org/01/09506000134352", level: :m)
+File.write("qr.svg", qr.svg(module_size: 4))
+File.binwrite("qr.png", qr.png(module_size: 8, background: nil)) # transparent
+
+ean = Imprimatur.barcode(:ean13, "950600013435")
+ean.text # => "9506000134352", the check digit added (or checked when given)
+
+label = Imprimatur.barcode(:code128, "(00)106141412345678908", gs1: true)  # GS1-128
+dpp = Imprimatur.barcode(:datamatrix, "(01)09506000134352(21)ABC123", gs1: true)
+
+Imprimatur.pdf("label.pdf", page_size: [300, 200], margin: 10) do |doc|
+  doc.barcode label, width: 280
+  doc.barcode dpp, width: 72, align: :right
+end
+```
+
+- `:qr` (`level:` `:l`, `:m`, `:q` or `:h`), `:datamatrix` (square),
+  `:ean13`, `:ean8`, `:upca` and `:code128`; `gs1: true` for the GS1 forms of
+  `:qr`, `:datamatrix` and `:code128`.
+- GS1 element strings are written as people write them, AIs in parentheses,
+  and checked: AI syntax, GS1's character set, the AIs whose lengths are
+  predefined, and the check digits of SSCCs, GTINs and GLNs. Separators go in
+  only where a variable-length field needs one.
+- `svg` and `png` take `module_size:`, `color:`, `background:` (nil for
+  none), `quiet_zone:` and, for linear codes, `bar_height:` in modules. PNGs
+  are one bit a pixel.
+- In documents, barcodes are vector shapes in a PDF and a 300 dpi picture in
+  DOCX, at `width:` or `height:` points or else at their usual module size
+  (0.33 mm for EAN and UPC, 0.495 mm for GS1-128, 0.7 mm for QR Code and Data
+  Matrix), quiet zone included.
+- `text`, `symbology`, `gs1?`, `width`, `height` (in modules), and `modules`
+  (rows of booleans) for drawing them some other way.
+
 ## Reading: documents as Markdown
 
 The other direction: a PDF, a workbook (XLSX, legacy XLS, ODS) or a DOCX
@@ -278,6 +318,13 @@ fibers keep running, and `Timeout` or `Thread#raise` cancels it.
 `Imprimatur::PasswordRequired` and `Imprimatur::UnsupportedDocument` (legacy
 `.doc`, `.xlsb`, presentations) are the other errors to expect.
 
+A binary String is always the document's bytes, never a path: an upload
+holding `/etc/passwd` or `/dev/zero` is refused as `UnsupportedDocument`,
+not read from the server. A path (a `Pathname`, or a String that is not
+binary and has no document signature) must name a regular file; devices,
+pipes and directories are refused. An IO or a path is read no further than
+`max_bytes:`, so an endless stream or a huge file stops there.
+
 ### Structure and images
 
 Markdown is one rendering of what a read finds. `Imprimatur.content` gives

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/reader.rb

@@ -12,22 +12,29 @@ module Imprimatur
   # Documents in: Markdown, their structure, their images. See
   # {Imprimatur.markdown}, {Imprimatur.content} and {Imprimatur.images}.
   module Reader
-    # File signatures a document's bytes start with; a String that starts
-    # with neither is taken for a path.
+    # File signatures a document's bytes start with; a String that is not
+    # binary and starts with neither is taken for a path.
     SIGNATURES = ["%PDF-".b, "PK\x03\x04".b, "PK\x05\x06".b, "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b].freeze
     private_constant :SIGNATURES
 
+    # The largest document read in unless told, as the native core's own limit.
+    MAX_BYTES = 512 * 1024 * 1024
+    private_constant :MAX_BYTES
+
     # @see Imprimatur.markdown
-    def self.markdown(document, **) = Native.markdown(read(document), *limits(**))
+    def self.markdown(document, max_bytes: nil, **)
+      Native.markdown(read(document, max_bytes), *limits(max_bytes:, **))
+    end
 
     # @see Imprimatur.content
-    def self.content(document, styles: false, **)
-      JSON.parse(Native.content(read(document), *limits(**), styles ? true : false), symbolize_names: true)
+    def self.content(document, styles: false, max_bytes: nil, **)
+      bytes = read(document, max_bytes)
+      JSON.parse(Native.content(bytes, *limits(max_bytes:, **), styles ? true : false), symbolize_names: true)
     end
 
     # @see Imprimatur.images
-    def self.images(document, **)
-      Native.images(read(document), *limits(**)).map do |data, description|
+    def self.images(document, max_bytes: nil, **)
+      Native.images(read(document, max_bytes), *limits(max_bytes:, **)).map do |data, description|
         found = JSON.parse(description, symbolize_names: true)
         Image.new(data:, **Image.members.drop(1).to_h { [it, found[it]] })
       end
@@ -38,22 +45,52 @@ module Imprimatur
       [max_bytes, max_inflated, timeout && Float(timeout)]
     end
 
+    # A path or an IO is read no further than +max_bytes+ (one byte past it
+    # tells it is passed): an endless stream or a huge file stops there.
+    #
     # @api private
-    def self.read(document)
+    def self.read(document, max_bytes = nil)
+      limit = max_bytes.is_a?(Integer) && max_bytes >= 0 ? max_bytes : MAX_BYTES
       case document
-      when Pathname then File.binread(document)
-      when String then bytes?(document) ? document : File.binread(document)
+      when Pathname then file(document, limit)
+      when String then bytes?(document) ? document : file(document, limit)
       else
         raise TypeError, "expected a path, bytes or an IO, not #{document.class}" unless document.respond_to?(:read)
 
-        document.read.to_s.b
+        within(document.read(limit + 1).to_s.b, limit)
       end
     end
 
+    # A binary String (what +File.binread+, a binary IO or a download give)
+    # is bytes, whatever it holds: uploaded bytes never name a file to read.
+    #
     # @api private
     def self.bytes?(string)
+      return true if string.encoding == Encoding::BINARY
+
       head = string.byteslice(0, 1024).b
       SIGNATURES.any? { head.start_with?(it) } || head.include?("%PDF-") || head.include?("\0")
     end
+
+    # A regular file's bytes. Opened without blocking and checked through
+    # the open file, so a pipe cannot hang the read, a device such as
+    # +/dev/zero+ is refused, and the file cannot be swapped in between.
+    #
+    # @api private
+    def self.file(path, limit)
+      File.open(path, File::RDONLY | File::NONBLOCK | File::BINARY) do |io|
+        stat = io.stat
+        raise UnsupportedDocument, "cannot read this document: #{path} is not a regular file" unless stat.file?
+
+        within(stat.size > limit ? '' : io.read(limit + 1).to_s, limit, stat.size)
+      end
+    end
+
+    # @api private
+    def self.within(bytes, limit, size = bytes.bytesize)
+      raise LimitExceeded, 'the document exceeds the input size limit' if [size, bytes.bytesize].max > limit
+
+      bytes
+    end
   end
 end

data/lib/imprimatur/spreadsheet.rb

@@ -123,7 +123,7 @@ module Imprimatur
     # @raise [UnsupportedDocument] a PDF, a Word document or another format
     # @raise [Imprimatur::Error] a damaged workbook, or past a limit
     def self.open(document, styles: false, **limits)
-      new(Native.sheets(Reader.read(document), *Reader.limits(**limits), styles ? true : false))
+      new(Native.sheets(Reader.read(document, limits[:max_bytes]), *Reader.limits(**limits), styles ? true : false))
     end
 
     # @return [Array<Sheet>] in the workbook's order, hidden ones included

data/lib/imprimatur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  VERSION = '0.3.0'
+  VERSION = '0.5.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.
     #
@@ -62,7 +66,8 @@ module Imprimatur
     #   Imprimatur.markdown(File.open('sales.xlsx'))
     #
     # @param document [String, Pathname, #read] a path, the document's bytes
-    #   (told apart by their signature), or an IO
+    #   (a binary String always is; another String only with a document's
+    #   signature), or an IO. A path must name a regular file.
     # @param timeout [Numeric, nil] seconds the read may take (60), +nil+ for none
     # @param max_bytes [Integer, nil] the largest document accepted (512 MiB)
     # @param max_inflated [Integer, nil] decompressed bytes allowed in all (1 GiB)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imprimatur
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: aarch64-linux-gnu
 authors:
 - Abdelkader Boudih
@@ -24,6 +24,7 @@ files:
 - README.md
 - lib/imprimatur.rb
 - lib/imprimatur/4.0/imprimatur_native.so
+- lib/imprimatur/barcode.rb
 - lib/imprimatur/document.rb
 - lib/imprimatur/error.rb
 - lib/imprimatur/formula.rb