acrofill 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28d2db0f5f96d10602a2c8dd994a9957665df1426cffdbc045b3860c675e504e
-  data.tar.gz: c683b238b9ff31d182ad316712e3982c3ffa6dd38a92fa6547efca3e784d02c4
+  metadata.gz: 8192b1e65d4be56876296608eecae9371866700b8a2016d6bbedad79062fca33
+  data.tar.gz: 750c2b6ccd33d9e335933c6f5e5f906f0ca8adb0f5aa07e98a4eb6019104c0f9
 SHA512:
-  metadata.gz: fb49f9bb0fe9efd45665d92c09c845a4156695b457bd9a3fddc13e7496a1221a009732147958f2a753130ebd5dc2f78b569b0ad117bf10ffa3262ba85bd3464e
-  data.tar.gz: 492ac4103cfa6fb500c70a648a94f479cf7411eb2293d5b7fc29ab7753e90bcd3a52f244facd94732e237f410a0038a9ca2a0ed2e7321a6ae4cc907744a4c265
+  metadata.gz: c081d29edbd239103797267d4f47cf2ed18ef3fa46026acae8ffc03b8d27e1b13e9477bba89c7646a554774059905bd833cd7d5df41717d95eb90ab72286d0f6
+  data.tar.gz: a0b575761f075a4fc8f7690b85ec7addee099fcf5ef29ff5f1201e72ee47fd873398645c2dd51af07476073f3cb85f8cbc7570b46af158900372201c60841098

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-07-24
+
+### Added
+
+- Expanded regression coverage: `/Q 2` right alignment, per-line multiline
+  centering, flatten geometry with a non-identity `/Matrix`, checkbox
+  state stamping, pushbutton and signature fields, deep hierarchical
+  names, reference-cycle guards, and `Template` snapshot isolation.
+  No library code changes.
+
+## [0.1.1] - 2026-07-24
+
+### Fixed
+
+- Parse failures from lazily materialized objects and parser stack
+  overflows on deeply nested objects now raise `Acrofill::Error` instead
+  of leaking `PDF::Reader::MalformedPDFError` or `SystemStackError`.
+- The page-tree and field-tree walks are iterative, so deep linear
+  `/Pages` or `/Kids` chains no longer overflow the stack.
+- Indirect references are dereferenced where they were previously assumed
+  direct: field `/V` in metadata, `/Rect` and `/BBox` corner values,
+  `/Matrix` elements, and the `/Q` alignment value.
+- A checkbox/radio whose on state is literally named `no` or `false` can
+  now be checked: an exact state-name match takes precedence over the
+  false-ish uncheck heuristic.
+
+### Changed
+
+- Single-line appearance baseline placement now matches pdftk exactly:
+  `ty = (h - ascent * size) / 2`.
+- Required Ruby version raised from `>= 3.0` to `>= 3.2` (3.0/3.1 are EOL
+  and untested in CI).
+
+## [0.1.0] - 2026-07-24
+
+### Added
+
+- Initial release: pure-Ruby AcroForm filling and flattening.
+- Text fields (`/Tx`): hierarchical names, inherited `/DA`, `/Q` alignment,
+  auto font size, shrink-to-fit, multiline word wrapping.
+- Checkboxes and radio groups (`/Btn`) via `/V` + `/AS` state selection.
+- Choice fields (`/Ch`).
+- Flattening of visible widget appearances into page content.
+- `Acrofill::Template` for parse-once, fill-many workloads.
+- `PdfForms`-compatible entry points (`Acrofill.new`, `fill_form`, `fields`,
+  `field_names`).
+
+[Unreleased]: https://github.com/stiig/acrofill/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/stiig/acrofill/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/stiig/acrofill/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/stiig/acrofill/releases/tag/v0.1.0

data/README.md

@@ -137,9 +137,10 @@ Acrofill is pure Ruby with no `eval`/`system`/native calls in its hot
 path, so the worst an input can do is cause an exception — never memory
 corruption or code execution. Specifically it defends against:
 
-- **Cyclic and exponentially-shared object graphs** — the page tree and
-  field tree walkers carry visited-sets, so a `/Pages` or `/Kids` cycle,
-  or a "billion laughs" DAG, terminates in O(objects) instead of hanging
+- **Cyclic, exponentially-shared and deeply nested object graphs** — the
+  page tree and field tree walkers are iterative and carry visited-sets,
+  so a `/Pages` or `/Kids` cycle, a "billion laughs" DAG, or a
+  thousands-deep linear chain terminates in O(objects) instead of hanging
   or overflowing the stack.
 - **Content-stream injection via `/DA`** — the template's default
   appearance string is sanitized: the font name must be a regular PDF
@@ -150,8 +151,9 @@ corruption or code execution. Specifically it defends against:
   mistyped dictionaries are clamped or rejected rather than crashing the
   writer.
 - **Encrypted / unparseable input** — rejected up front; every failure
-  at the parse boundary surfaces as `Acrofill::Error`, so callers only
-  ever rescue one error type.
+  at the parse boundary surfaces as `Acrofill::Error` (including lazy
+  per-object parse errors and parser stack overflow on pathologically
+  nested objects), so callers only ever rescue one error type.
 
 ## Feature matrix
 

data/lib/acrofill/appearance.rb

@@ -27,7 +27,7 @@ module Acrofill
 
       font_name, size, color_ops = parse_da(field_node)
       base_font = base_font_for(font_name)
-      align = @doc.inherited_value(field_node, :Q) || @acroform[:Q] || 0
+      align = alignment(field_node)
 
       body =
         if multiline
@@ -38,7 +38,9 @@ module Acrofill
           text = printable_text(value)
           size = [height * 0.66, 12.0].min if size.zero?
           size = shrink_to_fit(text, base_font, size, width)
-          ty = [(height - (size * (ASCENT - DESCENT))) / 2.0, size * DESCENT].max
+          # Vertically center the ascent box, matching pdftk's baseline
+          # placement exactly: ty = (h - ascent*size) / 2.
+          ty = [(height - (size * ASCENT)) / 2.0, size * DESCENT].max
           "#{fmt(line_x(text, base_font, size, width, align))} #{fmt(ty)} Td\n" \
             "(#{escape_literal(text)}) Tj\n"
         end
@@ -65,6 +67,12 @@ module Acrofill
       Serializer.format_number(num.to_f)
     end
 
+    # /Q (0 left, 1 center, 2 right), inheritable and possibly indirect.
+    def alignment(field_node)
+      align = @doc.deref(@doc.inherited_value(field_node, :Q) || @acroform[:Q])
+      align.is_a?(Integer) ? align : 0
+    end
+
     def line_x(text, base_font, size, width, align)
       text_width = Metrics.string_width(text, base_font, size)
       case align
@@ -117,12 +125,17 @@ module Acrofill
       lines
     end
 
+    # Array entries may legally be indirect objects, so each corner is
+    # dereferenced; a rect that is not four numbers is unusable.
     def normalized_rect(rect)
       rect = @doc.deref(rect)
       return nil unless rect.is_a?(Array) && rect.size == 4
 
-      xs = [rect[0].to_f, rect[2].to_f].sort
-      ys = [rect[1].to_f, rect[3].to_f].sort
+      nums = rect.map { |n| @doc.deref(n) }
+      return nil unless nums.all?(Numeric)
+
+      xs = [nums[0].to_f, nums[2].to_f].sort
+      ys = [nums[1].to_f, nums[3].to_f].sort
       [xs[0], ys[0], xs[1], ys[1]]
     end
 

data/lib/acrofill/document.rb

@@ -14,14 +14,18 @@ module Acrofill
     attr_reader :objects, :trailer
 
     def initialize(path)
-      hash = load_object_hash(path)
+      hash = parse_boundary { PDF::Reader::ObjectHash.new(path) }
       raise Error, 'encrypted PDFs are not supported' if hash.trailer[:Encrypt]
 
       @objects = {}
       @max_oid = 0
-      hash.each do |ref, obj|
-        @objects[ref.id] = obj
-        @max_oid = ref.id if ref.id > @max_oid
+      # ObjectHash parses object bodies lazily, so the iteration that
+      # materializes them must also stay inside the parse boundary.
+      parse_boundary do
+        hash.each do |ref, obj|
+          @objects[ref.id] = obj
+          @max_oid = ref.id if ref.id > @max_oid
+        end
       end
       @trailer = hash.trailer.slice(:Root, :Info, :ID)
       raise Error, 'PDF has no document catalog' unless @trailer[:Root]
@@ -56,11 +60,13 @@ module Acrofill
     # The parse boundary for untrusted input: pdf-reader (and the decryptors
     # it calls) can raise a wide assortment of errors on crafted files, so
     # everything is normalized to a single Acrofill::Error type.
-    def load_object_hash(path)
-      PDF::Reader::ObjectHash.new(path)
+    # SystemStackError is not a StandardError but must be caught too: the
+    # recursive-descent parser overflows on deeply nested objects.
+    def parse_boundary
+      yield
     rescue PDF::Reader::EncryptedPDFError => e
       raise Error, "encrypted PDFs are not supported (#{e.message})"
-    rescue StandardError => e
+    rescue StandardError, SystemStackError => e
       raise Error, "could not parse PDF (#{e.class}: #{e.message})"
     end
 
@@ -94,23 +100,31 @@ module Acrofill
       deref(@trailer[:Root])
     end
 
-    def each_page(node = root[:Pages], seen = {}, &block)
-      dict = deref(node)
-      return unless dict.is_a?(Hash)
-
-      # Guard against cyclic and shared (billion-laughs) /Pages trees: a
-      # node reachable more than once is walked only the first time.
-      if node.is_a?(PDF::Reader::Reference)
-        return if seen[node.id]
-
-        seen[node.id] = true
-      end
-
-      case dict[:Type]
-      when :Pages
-        (deref(dict[:Kids]) || []).each { |kid| each_page(kid, seen, &block) }
-      when :Page
-        yield dict
+    # Depth-first, document-order walk over the /Pages tree. Iterative with
+    # an explicit stack (a deep linear chain must not overflow the Ruby
+    # stack) and a visited set (a cyclic or shared billion-laughs tree must
+    # not hang or amplify).
+    def each_page
+      stack = [root[:Pages]]
+      seen = {}
+      until stack.empty?
+        node = stack.pop
+        dict = deref(node)
+        next unless dict.is_a?(Hash)
+
+        if node.is_a?(PDF::Reader::Reference)
+          next if seen[node.id]
+
+          seen[node.id] = true
+        end
+
+        case dict[:Type]
+        when :Pages
+          kids = deref(dict[:Kids])
+          stack.concat(kids.reverse) if kids.is_a?(Array)
+        when :Page
+          yield dict
+        end
       end
     end
 

data/lib/acrofill/form.rb

@@ -21,7 +21,8 @@ module Acrofill
       # single logical field, e.g. "SSN" repeated on every page) — filling
       # must update all of them.
       @fields = Hash.new { |h, k| h[k] = [] }
-      collect_fields(doc.deref(@acroform[:Fields]) || [], nil, {})
+      roots = doc.deref(@acroform[:Fields])
+      collect_fields(roots.is_a?(Array) ? roots : [])
     end
 
     # Metadata for every logical field, in document order.
@@ -31,7 +32,7 @@ module Acrofill
         Field.new(
           name: name,
           type: type,
-          value: decode_text_string(groups.first[:node][:V]),
+          value: decode_text_string(@doc.deref(groups.first[:node][:V])),
           states: type == :Btn ? on_states(all_widgets(groups)) : nil
         )
       end
@@ -103,7 +104,9 @@ module Acrofill
     # Checkboxes and radio groups carry per-state appearance streams, so
     # filling only selects a state: /V on the field, /AS on each widget.
     # The value may be a state name ("Yes"), or anything non-empty when the
-    # group has a single on state. Empty, "Off" or false-ish unchecks.
+    # group has a single on state. Empty, "Off" or false-ish unchecks —
+    # unless the value exactly names an on state (a checkbox whose state is
+    # literally called "no" must remain checkable).
     def fill_button(groups, value)
       widgets = all_widgets(groups)
       states = on_states(widgets)
@@ -112,10 +115,10 @@ module Acrofill
       # symbol creation from attacker-controlled field values).
       named = states.find { |s| s.to_s == value }
       state =
-        if ['', 'Off', 'false', 'no'].include?(value)
-          :Off
-        elsif named
+        if named
           named
+        elsif ['', 'Off', 'false', 'no'].include?(value)
+          :Off
         elsif states.size == 1
           states.first
         else
@@ -158,23 +161,27 @@ module Acrofill
       false
     end
 
-    def collect_fields(kids, prefix, seen)
-      kids.each do |ref|
+    # Depth-first, document-order walk over the field tree. Iterative with
+    # an explicit stack of [ref, prefix] pairs (a deep linear /Kids chain
+    # must not overflow the Ruby stack), with a visited set against cycles
+    # and shared nodes.
+    def collect_fields(roots)
+      seen = {}
+      stack = roots.reverse.map { |ref| [ref, nil] }
+      until stack.empty?
+        ref, prefix = stack.pop
         next if visited?(ref, seen)
 
         node = @doc.deref(ref)
         next unless node.is_a?(Hash)
 
         name = [prefix, decode_name(node[:T])].compact.join('.')
-        child_refs = @doc.deref(node[:Kids]) || []
-        child_pairs = child_refs.map { |kid| [kid, @doc.deref(kid)] }
-                                .select { |_kid, dict| dict.is_a?(Hash) }
-        subfields, widgets = child_pairs.partition { |_kid, dict| dict.key?(:T) }
+        subfields, widgets = partition_kids(node)
 
         if subfields.any?
-          # Recurse only into the named subfields; a stray bare widget mixed
+          # Descend only into the named subfields; a stray bare widget mixed
           # into the same /Kids must not register itself under this name.
-          collect_fields(subfields.map(&:first), name, seen)
+          stack.concat(subfields.map { |kid, _dict| [kid, name] }.reverse)
         else
           widget_dicts = widgets.map(&:last)
           widget_dicts = [node] if widget_dicts.empty? && node[:Rect]
@@ -183,6 +190,16 @@ module Acrofill
       end
     end
 
+    # Splits a node's /Kids into named subfields and bare widgets, dropping
+    # anything that does not deref to a dictionary.
+    def partition_kids(node)
+      child_refs = @doc.deref(node[:Kids])
+      child_refs = [] unless child_refs.is_a?(Array)
+      child_refs.map { |kid| [kid, @doc.deref(kid)] }
+                .select { |_kid, dict| dict.is_a?(Hash) }
+                .partition { |_kid, dict| dict.key?(:T) }
+    end
+
     def decode_name(raw)
       decode_text_string(@doc.deref(raw))
     end
@@ -207,7 +224,9 @@ module Acrofill
     end
 
     def flatten_page(page)
-      annots = (@doc.deref(page[:Annots]) || []).map { |a| [a, @doc.deref(a)] }
+      annot_refs = @doc.deref(page[:Annots])
+      annot_refs = [] unless annot_refs.is_a?(Array)
+      annots = annot_refs.map { |a| [a, @doc.deref(a)] }
       widgets, others = annots.partition { |_ref, dict| dict.is_a?(Hash) && dict[:Subtype] == :Widget }
       return if widgets.empty?
 
@@ -246,16 +265,16 @@ module Acrofill
       dict = xobject.is_a?(StreamObject) ? xobject.dict : xobject&.hash
       return nil unless dict.is_a?(Hash)
 
-      bbox = @doc.deref(dict[:BBox])
-      rect = @doc.deref(widget[:Rect])
-      return nil unless bbox.is_a?(Array) && rect.is_a?(Array)
+      bbox = normalize_box(@doc.deref(dict[:BBox]))
+      rect = normalize_box(@doc.deref(widget[:Rect]))
+      return nil unless bbox && rect
 
       # Appearance streams are form XObjects, but /Type and /Subtype are
       # sometimes omitted; /Do requires them.
       dict[:Type] ||= :XObject
       dict[:Subtype] ||= :Form
 
-      llx, lly, urx, ury = normalize_box(rect)
+      llx, lly, urx, ury = rect
       bx0, by0, bx1, by1 = transformed_bbox(bbox, @doc.deref(dict[:Matrix]))
       bw = bx1 - bx0
       bh = by1 - by0
@@ -269,10 +288,11 @@ module Acrofill
       "q #{ops.join(' ')} cm /#{name} Do Q"
     end
 
-    # Bounding box of the BBox corners after the form's /Matrix (identity
-    # when absent or malformed).
+    # Bounding box of the (already normalized) BBox corners after the
+    # form's /Matrix (identity when absent or malformed).
     def transformed_bbox(bbox, matrix)
-      x0, y0, x1, y1 = normalize_box(bbox)
+      x0, y0, x1, y1 = bbox
+      matrix = matrix.map { |m| @doc.deref(m) } if matrix.is_a?(Array)
       return [x0, y0, x1, y1] unless matrix.is_a?(Array) && matrix.size == 6 &&
                                      matrix.all?(Numeric)
 
@@ -302,9 +322,17 @@ module Acrofill
       normal
     end
 
+    # Derefs each element (array entries may legally be indirect objects)
+    # and returns [llx, lly, urx, ury], or nil when the box is not four
+    # numbers.
     def normalize_box(box)
-      xs = [box[0].to_f, box[2].to_f].sort
-      ys = [box[1].to_f, box[3].to_f].sort
+      return nil unless box.is_a?(Array) && box.size == 4
+
+      nums = box.map { |n| @doc.deref(n) }
+      return nil unless nums.all?(Numeric)
+
+      xs = [nums[0].to_f, nums[2].to_f].sort
+      ys = [nums[1].to_f, nums[3].to_f].sort
       [xs[0], ys[0], xs[1], ys[1]]
     end
 

data/lib/acrofill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Acrofill
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/acrofill.rb

@@ -14,8 +14,8 @@ module Acrofill
   class Error < StandardError; end
 
   # Mirrors the PdfForms.new(pdftk_path) constructor shape.
-  def self.new(*args)
-    Filler.new(*args)
+  def self.new(*)
+    Filler.new(*)
   end
 
   def self.fill_form(template, destination, data = {}, options = {})

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: acrofill
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - stiig
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pdf-reader
@@ -27,11 +26,11 @@ dependencies:
 description: Fills PDF form fields (text, checkbox, radio, choice) in-process and
   optionally flattens the result into static page content. An MIT-licensed, no-dependencies-on-binaries
   alternative to the pdftk fill_form pipeline.
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/acrofill.rb
@@ -50,8 +49,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/stiig/acrofill
   source_code_uri: https://github.com/stiig/acrofill
+  changelog_uri: https://github.com/stiig/acrofill/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/stiig/acrofill/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -59,15 +59,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Pure-Ruby PDF form (AcroForm) filling and flattening
 test_files: []