fillform 0.1.0

data/lib/fillform/data_format.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Fillform
+  # The changes pdf-forms and pdftk make to the values and the field names on their way into the
+  # form, per data format.
+  module DataFormat
+    module_function
+
+    def apply(format, value)
+      case format.to_s
+      when "XFdf" then xfdf(value)
+      when "FdfHex" then value
+      else fdf(value)
+      end
+    end
+
+    # The name pdftk looks the field up with. In FDF the names are literal strings that pdftk reads in
+    # PDFDocEncoding, so a field whose name is not in PDFDocEncoding is not found and not filled.
+    def field_name(format, name)
+      case format.to_s
+      when "XFdf" then name
+      when "FdfHex" then PDF::Text.decode(name.b)
+      else latin9_as_pdf_doc(name)
+      end
+    end
+
+    # Fdf, the default of pdf-forms: the values are written in ISO-8859-15 and read back by pdftk in
+    # PDFDocEncoding, a line feed is written as an escaped carriage return and a raw carriage return
+    # is read as a line feed.
+    def fdf(value)
+      latin9_as_pdf_doc(value).gsub(/[\r\n]/, "\r" => "\n", "\n" => "\r")
+    end
+
+    # XFdf: pdftk's XML parser collapses a run of the same space, tab or line feed into one and reads
+    # carriage returns as line feeds.
+    def xfdf(value)
+      value.gsub(/([ \t\n])\1+/, '\1').gsub(/\r\n?/, "\n")
+    end
+
+    def latin9_as_pdf_doc(text)
+      latin = text.encode(Encoding::ISO_8859_15, invalid: :replace, undef: :replace, replace: "?")
+      latin.b.each_byte.map { |byte| PDF::Text.pdf_doc_char(byte) || "�" }.join
+    end
+  end
+end

data/lib/fillform/field.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Fillform
+  # The metadata of a form field, with the attributes and string values pdf-forms reads from
+  # `pdftk dump_data_fields`. See Report for how pdftk walks the field tree.
+  Field = Struct.new(:name, :type, :options, :flags, :justification, :value, :value_default, :name_alt,
+                     :max_length, keyword_init: true)
+
+  class Field
+    # pdftk reads the bytes of a name as Latin-1.
+    def self.latin1(name) = name.to_s.b.force_encoding(Encoding::ISO_8859_1).encode(Encoding::UTF_8)
+
+    def to_hash = to_h
+  end
+end

data/lib/fillform/filler.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Fillform
+  class Filler
+    def initialize(template)
+      @doc = PDF::Document.open(template.to_s)
+      @form = Form.new(@doc)
+    end
+
+    def fill(data, flatten: false)
+      return self unless @form.present?
+
+      fields = @form.fields.to_h { |field| [field.name, field] }
+      data.each do |name, value|
+        field = fields[name.to_s]
+        next unless field
+
+        case field.concrete_type
+        when :check_box, :radio_button then select_state(field, value.to_s)
+        when :text_field then appearance(field).fill(value.to_s)
+        when :combo_box then appearance(field).fill_choice(value.to_s)
+        when :list_box then appearance(field).fill_list(Array(value).map(&:to_s))
+        end
+      end
+      Flattener.new(@doc, @form).flatten if flatten
+      self
+    end
+
+    # Not validated: like pdftk, a value longer than the field's MaxLen is kept as it is.
+    def write(destination)
+      @doc.write(destination.to_s)
+    end
+
+    private
+
+    # Like pdftk, an unknown state leaves the button as it is, and the template's own appearance of
+    # the state is drawn.
+    def select_state(field, value)
+      state = value == "Off" ? :Off : on_states(field).find { |name| state_name?(name, value) }
+      return unless state
+
+      field[:V] = state
+      field.widgets.each do |widget|
+        appearances = widget.normal_appearances
+        widget[:AS] = appearances.is_a?(Hash) && appearances.key?(state) ? state : :Off
+      end
+    end
+
+    def on_states(field)
+      field.widgets.flat_map do |widget|
+        appearances = widget.normal_appearances
+        appearances.is_a?(Hash) ? appearances.keys : []
+      end.uniq - [:Off]
+    end
+
+    # pdftk shows and matches the bytes of a state name as Latin-1, so its users pass "Sì" for "Sì".
+    def state_name?(name, value)
+      bytes = name.to_s.b
+      utf8 = bytes.dup.force_encoding(Encoding::UTF_8)
+      (utf8.valid_encoding? && utf8 == value) || Field.latin1(name) == value
+    end
+
+    def appearance(field)
+      Appearance.new(@doc, field, form: @form) { |resources, name| font(resources, name) }
+    end
+
+    # iText draws with Helvetica when the font of the field is not in its resources.
+    def font(resources, name)
+      @fonts ||= {}
+      @fonts[[resources.object_id, name]] ||= begin
+        fonts = @doc.deref(resources[:Font]) if resources.is_a?(Hash)
+        resource = fonts[name.to_sym] if fonts.is_a?(Hash) && name
+        @doc.deref(resource).is_a?(Hash) ? Font.new(name.to_sym, resource, @doc) : helvetica
+      end
+    end
+
+    def helvetica
+      @helvetica ||= Font.new(:Helv, @doc.add({ Type: :Font, Subtype: :Type1, BaseFont: :Helvetica,
+                                                Encoding: :WinAnsiEncoding }), @doc, fallback: true)
+    end
+  end
+end

data/lib/fillform/flattener.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Fillform
+  # Draws the appearances of the fields into their pages and removes the fields, like iText's
+  # PdfStamperImp#flatFields: in the order of the field names, each appearance moved to the lower left
+  # corner of its widget, only for widgets that are printed and not hidden.
+  class Flattener
+    HIDDEN = 1 << 1
+    PRINT = 1 << 2
+
+    def initialize(document, form)
+      @document = document
+      @form = form
+    end
+
+    def flatten
+      pages = @document.pages
+      page_of = page_index(pages)
+      drawings = Hash.new { |hash, key| hash[key] = [] }
+      removed = {}
+      @form.fields.sort_by(&:name).each do |field|
+        field.widgets.each do |widget|
+          index = widget.reference.is_a?(PDF::Reference) ? page_of[widget.reference.number] : nil
+          next unless index
+
+          appearance = appearance(widget) if visible?(widget)
+          drawings[index] << [appearance, *widget.rect[0, 2]] if appearance
+          removed[widget.reference.number] = true
+        end
+      end
+      pages.each_with_index do |(_reference, page, inherited), index|
+        remove_widgets(page, removed)
+        draw(page, inherited, drawings[index]) if drawings.key?(index)
+      end
+      @form.dictionary[:Fields] = []
+    end
+
+    private
+
+    def page_index(pages)
+      pages.each_with_index.with_object({}) do |((_reference, page, _inherited), index), result|
+        Array(@document.deref(page[:Annots])).each do |annotation|
+          result[annotation.number] ||= index if annotation.is_a?(PDF::Reference)
+        end
+      end
+    end
+
+    def visible?(widget)
+      flags = widget[:F].to_i
+      flags.anybits?(PRINT) && !flags.anybits?(HIDDEN)
+    end
+
+    # The normal appearance, or the one of the widget's state.
+    def appearance(widget)
+      appearances = widget[:AP]
+      return unless appearances.is_a?(Hash)
+
+      normal = appearances[:N]
+      value = @document.deref(normal)
+      reference = case value
+                  when PDF::Stream then normal.is_a?(PDF::Reference) ? normal : @document.add(value)
+                  when Hash then value[widget[:AS]] if widget[:AS]
+                  end
+      stream = @document.deref(reference) if reference.is_a?(PDF::Reference)
+      return unless stream.is_a?(PDF::Stream)
+
+      stream[:Subtype] = :Form
+      reference
+    end
+
+    def remove_widgets(page, removed)
+      annotations = Array(@document.deref(page[:Annots]))
+      kept = annotations.reject { |annotation| annotation.is_a?(PDF::Reference) && removed[annotation.number] }
+      return if kept.size == annotations.size
+
+      kept.empty? ? page.delete(:Annots) : page[:Annots] = kept
+    end
+
+    def draw(page, inherited, drawings)
+      xobjects = xobjects(page, inherited)
+      operations = drawings.map do |reference, left, bottom|
+        name = next_name(xobjects)
+        xobjects[name] = reference
+        "q 1 0 0 1 #{Fillform.number(left)} #{Fillform.number(bottom)} cm #{PDF::Serializer.name(name)} Do Q\n"
+      end
+      page[:Contents] = [@document.add(PDF::Stream.new({}, "q\n".b)), *contents(page),
+                         @document.add(PDF::Stream.new({}, "\nQ\n#{operations.join}".b))]
+    end
+
+    def contents(page)
+      contents = page[:Contents]
+      value = @document.deref(contents)
+      case value
+      when Array then value
+      when nil then []
+      else [contents]
+      end
+    end
+
+    def xobjects(page, inherited)
+      page[:Resources] = @document.deref(inherited[:Resources]).dup || {} unless page.key?(:Resources)
+      resources = @document.deref(page[:Resources])
+      xobjects = @document.deref(resources[:XObject])
+      resources[:XObject] = xobjects = {} unless xobjects.is_a?(Hash)
+      xobjects
+    end
+
+    def next_name(xobjects)
+      index = 0
+      index += 1 while xobjects.key?(:"Xi#{index}")
+      :"Xi#{index}"
+    end
+  end
+end

data/lib/fillform/float32.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Fillform
+  # iText computes the layout with Java floats: each operation is rounded to single precision.
+  module Float32
+    module_function
+
+    def f(value) = [value].pack("e").unpack1("e")
+
+    THOUSANDTH = f(0.001)
+  end
+end

data/lib/fillform/font.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Fillform
+  # The metrics and the encoding iText reads from a font of the form's resources.
+  class Font
+    # iText encodes with the Java charsets of these encodings; any other encoding goes by glyph names.
+    CHARSETS = { WinAnsiEncoding: Encoding::Windows_1252, MacRomanEncoding: Encoding::MacRoman }.freeze
+
+    attr_reader :key, :resource
+
+    # iText's own fallback font drops the characters it cannot show, a font of the form shows code 0.
+    # The resource is what the appearance stream lists for the font: a reference or a dictionary.
+    def initialize(key, resource, document, fallback: false)
+      @key = key
+      @resource = resource
+      @document = document
+      @dictionary = document.deref(resource)
+      @missing = fallback ? nil : 0
+    end
+
+    def encode(char)
+      @codes ||= {}
+      return @codes[char] if @codes.key?(char)
+
+      @codes[char] = differences[char] || charset_code(char) || (charset ? nil : base_codes[char]) || @missing
+    end
+
+    def encode_all(chars) = chars.filter_map { |char| encode(char) }
+
+    # iText's BaseFont#getWidthPoint with the integer width of the glyph.
+    def char_width(char, size)
+      code = encode(char)
+      f(f(f(code ? width(code).to_i : 0) * Float32::THOUSANDTH) * f(size))
+    end
+
+    # iText's quirk: the height of a line is measured from the lower left to the upper right corner.
+    def auto_size_factor = f(metric(bounding_box[2], 1) - metric(bounding_box[1], 1))
+
+    def line_factor = f(metric(bounding_box[3], 1) - metric(bounding_box[1], 1))
+
+    def top(size) = metric(bounding_box[3], size)
+
+    def bottom(size) = metric(bounding_box[1], size)
+
+    def ascent(size) = metric(metrics[1], size)
+
+    def descent(size) = metric(metrics[2], size)
+
+    private
+
+    # iText's BaseFont#getFontDescriptor: value * size / 1000 in floats.
+    def metric(value, size) = f(f(f(value) * f(size)) / 1000)
+
+    def f(value) = Float32.f(value)
+
+    def width(code)
+      @widths ||= {}
+      @widths[code] ||=
+        if (widths = deref(@dictionary[:Widths]))
+          first = @dictionary[:FirstChar].to_i
+          code.between?(first, first + widths.size - 1) ? deref(widths[code - first]).to_f : missing_width
+        elsif standard_font?
+          standard_metrics.widths[names[code]] || 0
+        else
+          missing_width
+        end
+    end
+
+    def missing_width = deref(descriptor&.[](:MissingWidth)).to_f
+
+    def encoding = deref(@dictionary[:Encoding])
+
+    def base_encoding_name
+      encoding.is_a?(Hash) ? encoding[:BaseEncoding] : encoding
+    end
+
+    def charset
+      return @charset if defined?(@charset)
+
+      @charset = CHARSETS[base_encoding_name]
+    end
+
+    # Where Ruby's MacRoman table differs from Java's.
+    JAVA_MAC_ROMAN = { "¤" => nil, "Ω" => 0xBD, "€" => 0xDB, "Ω" => nil, "" => 0xF0 }.freeze
+
+    def charset_code(char)
+      return unless charset
+      return JAVA_MAC_ROMAN[char] if charset == Encoding::MacRoman && JAVA_MAC_ROMAN.key?(char)
+
+      char.encode(charset).ord
+    rescue EncodingError
+      nil
+    end
+
+    # Glyph names by code: the base encoding with the differences of the font applied.
+    def names
+      @names ||= base_names.dup.tap do |result|
+        difference_names.each { |code, name| result[code] = name }
+      end
+    end
+
+    def base_names
+      Glyphs.encoding(base_encoding_name) || builtin_names
+    end
+
+    def builtin_names
+      standard_font? ? standard_metrics.encoding : Glyphs.encoding(:StandardEncoding)
+    end
+
+    def difference_names
+      @difference_names ||= begin
+        code = 0
+        Array(deref(encoding.is_a?(Hash) ? encoding[:Differences] : nil)).each_with_object({}) do |item, result|
+          item = deref(item)
+          if item.is_a?(Numeric)
+            code = item.to_i
+          else
+            result[code] = item
+            code += 1
+          end
+        end
+      end
+    end
+
+    def differences
+      @differences ||= unicode_codes(difference_names)
+    end
+
+    def base_codes
+      @base_codes ||= unicode_codes(base_names.each_with_index.to_h { |name, code| [code, name] })
+    end
+
+    def unicode_codes(names_by_code)
+      dingbats = @dictionary[:BaseFont].to_s == "ZapfDingbats"
+      names_by_code.each_with_object({}) do |(code, name), result|
+        next unless name
+
+        char = Glyphs.unicode(name, dingbats: dingbats)
+        result[char] = code if char && !result.key?(char)
+      end
+    end
+
+    def bounding_box = metrics[0]
+
+    def metrics
+      @metrics ||=
+        if standard_font?
+          [standard_metrics.bounding_box, standard_metrics.ascender, standard_metrics.descender]
+        else
+          [deref(descriptor[:FontBBox]).map { |value| deref(value).to_f }, deref(descriptor[:Ascent]).to_f,
+           deref(descriptor[:Descent]).to_f]
+        end
+    end
+
+    def descriptor = deref(@dictionary[:FontDescriptor])
+
+    def standard_metrics = Glyphs.metrics(@dictionary[:BaseFont])
+
+    def standard_font?
+      @dictionary[:Subtype] == :Type1 && Glyphs.standard_font?(@dictionary[:BaseFont])
+    end
+
+    def deref(value) = @document.deref(value)
+  end
+end

data/lib/fillform/form.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Fillform
+  # The interactive form of a document: its terminal fields, in the order of the field tree.
+  class Form
+    attr_reader :document, :dictionary
+
+    def initialize(document)
+      @document = document
+      @dictionary = document.deref(document.catalog&.[](:AcroForm))
+    end
+
+    def present? = @dictionary.is_a?(Hash)
+
+    def [](key) = present? ? @document.deref(@dictionary[key]) : nil
+
+    def fields
+      return [] unless present?
+
+      @fields ||= Array(self[:Fields]).flat_map { |reference| terminal_fields(reference, nil, 0) }
+    end
+
+    def field(name) = fields.find { |field| field.name == name }
+
+    private
+
+    def terminal_fields(reference, parent, depth)
+      dictionary = @document.deref(reference)
+      return [] unless dictionary.is_a?(Hash) && depth < 32
+
+      field = FormField.new(@document, reference, dictionary, parent)
+      kids = field.field_kids
+      kids.empty? ? [field] : kids.flat_map { |kid| terminal_fields(kid, field, depth + 1) }
+    end
+  end
+
+  # A field of the form, with the attributes it inherits from its parents.
+  class FormField
+    INHERITABLE = %i[FT Ff V DV DA Q MaxLen].freeze
+    PUSH_BUTTON = 1 << 16
+    RADIO = 1 << 15
+    COMBO = 1 << 17
+
+    attr_reader :document, :reference, :dictionary, :parent
+
+    def initialize(document, reference, dictionary, parent)
+      @document = document
+      @reference = reference
+      @dictionary = dictionary
+      @parent = parent
+    end
+
+    def [](key)
+      value = @document.deref(@dictionary[key])
+      return value unless value.nil? && INHERITABLE.include?(key) && @parent
+
+      @parent[key]
+    end
+
+    def []=(key, value)
+      @dictionary[key] = value
+    end
+
+    def key?(key) = @dictionary.key?(key)
+
+    # A value of the field or of the nearest parent that has it.
+    def lookup(key)
+      @dictionary.key?(key) ? @document.deref(@dictionary[key]) : @parent&.lookup(key)
+    end
+
+    def name
+      own = @dictionary[:T] && PDF::Text.decode(@document.deref(@dictionary[:T]))
+      [@parent&.name, own].compact.join(".")
+    end
+
+    def field_type = self[:FT]
+
+    def flags = self[:Ff].to_i
+
+    def concrete_type
+      case field_type
+      when :Btn then button_type
+      when :Ch then flags.nobits?(COMBO) ? :list_box : :combo_box
+      when :Tx then :text_field
+      else field_type
+      end
+    end
+
+    # Kids with a name are fields, the other kids are widgets.
+    def field_kids
+      kids.select { |kid| @document.deref(kid).is_a?(Hash) && @document.deref(kid).key?(:T) }
+    end
+
+    # The field itself when its widget is merged into it.
+    def widgets
+      widget_kids = kids.reject { |kid| @document.deref(kid).is_a?(Hash) && @document.deref(kid).key?(:T) }
+      references = kids.empty? ? [@reference] : widget_kids
+      references.filter_map do |reference|
+        dictionary = @document.deref(reference)
+        Widget.new(@document, reference, dictionary) if dictionary.is_a?(Hash)
+      end
+    end
+
+    private
+
+    def kids = Array(@document.deref(@dictionary[:Kids]))
+
+    def button_type
+      return :push_button if flags.anybits?(PUSH_BUTTON)
+
+      flags.nobits?(RADIO) ? :check_box : :radio_button
+    end
+  end
+
+  # A widget annotation of a field.
+  class Widget
+    attr_reader :reference, :dictionary
+
+    def initialize(document, reference, dictionary)
+      @document = document
+      @reference = reference
+      @dictionary = dictionary
+    end
+
+    def [](key) = @document.deref(@dictionary[key])
+
+    # A value of the widget's entries, with any reference inside it resolved.
+    def resolve(value)
+      value = @document.deref(value)
+      case value
+      when Array then value.map { |item| resolve(item) }
+      when Hash then value.transform_values { |item| resolve(item) }
+      else value
+      end
+    end
+
+    def []=(key, value)
+      @dictionary[key] = value
+    end
+
+    def key?(key) = @dictionary.key?(key)
+
+    # The normalized rectangle: [left, bottom, right, top].
+    def rect
+      left, bottom, right, top = Array(self[:Rect]).map { |value| @document.deref(value).to_f }
+      [[left, right].min, [bottom, top].min, [left, right].max, [bottom, top].max]
+    end
+
+    def normal_appearances
+      appearances = self[:AP]
+      appearances.is_a?(Hash) ? @document.deref(appearances[:N]) : nil
+    end
+
+    # The names of the states the widget has a normal, down and rollover appearance for.
+    def states_by_kind
+      appearances = self[:AP]
+      return [] unless appearances.is_a?(Hash)
+
+      %i[N D R].map do |key|
+        states = @document.deref(appearances[key])
+        states.is_a?(Hash) ? states.keys : []
+      end
+    end
+  end
+end

data/lib/fillform/glyphs.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Fillform
+  # Glyph names, the metrics of the 14 standard fonts, and the simple font encodings.
+  # The data files are Adobe's: the core 14 AFM files and the Adobe Glyph List, see data/.
+  module Glyphs
+    DATA = File.expand_path("../../data", __dir__)
+    STANDARD_FONTS = %w[Courier Courier-Bold Courier-BoldOblique Courier-Oblique Helvetica Helvetica-Bold
+                        Helvetica-BoldOblique Helvetica-Oblique Symbol Times-Bold Times-BoldItalic Times-Italic
+                        Times-Roman ZapfDingbats].freeze
+
+    Metrics = Struct.new(:widths, :encoding, :bounding_box, :ascender, :descender)
+
+    class << self
+      def standard_font?(name) = STANDARD_FONTS.include?(name.to_s)
+
+      def metrics(font_name)
+        @metrics ||= {}
+        @metrics[font_name.to_s] ||= read_afm(File.join(DATA, "afm", "#{font_name}.afm"))
+      end
+
+      def unicode(name, dingbats: false)
+        name = name.to_s
+        (dingbats && zapf_dingbats[name]) || glyph_list[name] || algorithmic(name)
+      end
+
+      # Glyph names by code of the encodings a font can name.
+      def encoding(name)
+        @encodings ||= {}
+        @encodings[name] ||=
+          case name
+          when :StandardEncoding then metrics("Helvetica").encoding
+          when :WinAnsiEncoding then charset_encoding(Encoding::Windows_1252, 0xA0 => :space, 0xAD => :hyphen)
+          when :MacRomanEncoding then charset_encoding(Encoding::MacRoman, 0xCA => :space)
+          end
+      end
+
+      private
+
+      def read_afm(path)
+        widths = {}
+        encoding = Array.new(256)
+        values = {}
+        File.foreach(path, encoding: Encoding::ISO_8859_1) do |line|
+          if line.start_with?("C ")
+            code = line[/\AC (-?\d+)/, 1].to_i
+            name = line[/; N (\S+)/, 1].to_sym
+            widths[name] = line[/WX (\S+)/, 1].to_f
+            encoding[code] = name if code.between?(0, 255)
+          elsif (match = line.match(/\A(FontBBox|Ascender|Descender) (.+)/))
+            values[match[1]] = match[2].split.map(&:to_f)
+          end
+        end
+        box = values["FontBBox"]
+        Metrics.new(widths, encoding, box, values.dig("Ascender", 0) || box[3], values.dig("Descender", 0) || box[1])
+      end
+
+      def charset_encoding(charset, overrides)
+        names = metrics("Helvetica").widths.keys.to_h { |name| [unicode(name), name] }
+        Array.new(256) do |code|
+          overrides.fetch(code) do
+            names[code.chr.force_encoding(charset).encode(Encoding::UTF_8)]
+          rescue EncodingError
+            nil
+          end
+        end
+      end
+
+      def glyph_list
+        @glyph_list ||= read_list("glyphlist.txt")
+      end
+
+      def zapf_dingbats
+        @zapf_dingbats ||= read_list("zapfdingbats.txt")
+      end
+
+      def read_list(file)
+        File.foreach(File.join(DATA, "agl", file)).each_with_object({}) do |line, list|
+          next if line.start_with?("#")
+
+          name, codes = line.chomp.split(";")
+          list[name] = codes.split.map(&:hex).pack("U*") if codes
+        end
+      end
+
+      # uniXXXX and uXXXX[XX] names, and names with a suffix like a.sc.
+      def algorithmic(name)
+        base = name.split(".").first.to_s
+        if (hex = base[/\Auni((?:\h{4})+)\z/, 1])
+          hex.scan(/\h{4}/).map(&:hex).pack("U*")
+        elsif (hex = base[/\Au(\h{4,6})\z/, 1])
+          [hex.hex].pack("U")
+        elsif base != name
+          glyph_list[base]
+        end
+      end
+    end
+  end
+end