fillform 0.1.0

data/lib/fillform/pdf/parser.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Fillform
+  module PDF
+    # Reads PDF objects and content stream operations from bytes.
+    class Parser
+      WHITESPACE = /(?:[\0\t\n\f\r ]+|%[^\r\n]*)+/
+      REGULAR = %r{[^\0\t\n\f\r ()<>\[\]{}/%]+}
+      NUMBER = /[+-]?(?:\d+\.?\d*|\.\d+)\z/
+      REFERENCE = %r{(\d+)[\0\t\n\f\r ]+(\d+)[\0\t\n\f\r ]+R(?=[\0\t\n\f\r ()<>\[\]{}/%]|\z)}
+      ESCAPES = { "n" => "\n", "r" => "\r", "t" => "\t", "b" => "\b", "f" => "\f" }.freeze
+      Keyword = Struct.new(:name)
+
+      attr_reader :scanner
+
+      # The length resolver turns an indirect /Length of a stream into a number.
+      def initialize(data, position = 0, &length_resolver)
+        @scanner = StringScanner.new(data)
+        @scanner.pos = position
+        @length_resolver = length_resolver
+      end
+
+      def position = @scanner.pos
+
+      # An indirect object at the current position: [number, generation, value].
+      def parse_indirect
+        skip_whitespace
+        @scanner.scan(/(\d+)\s+(\d+)\s+obj\b/) or raise MalformedError, "no object at #{position}"
+        number = @scanner[1].to_i
+        generation = @scanner[2].to_i
+        [number, generation, stream_after(parse_object)]
+      end
+
+      def parse_object
+        token = next_token
+        raise MalformedError, "unexpected end of data" if token.equal?(:eof)
+        if token.is_a?(Keyword) && !token.name.match?(/\A(true|false|null)\z/)
+          raise MalformedError,
+                "unexpected #{token.name}"
+        end
+
+        token.is_a?(Keyword) ? keyword_value(token.name) : token
+      end
+
+      # Content stream operations: [operator, operands].
+      def each_operation
+        operands = []
+        loop do
+          token = next_token
+          break if token.equal?(:eof)
+
+          if token.is_a?(Keyword) && !%w[true false null].include?(token.name)
+            yield token.name.to_sym, operands
+            skip_inline_image if token.name == "ID"
+            operands = []
+          else
+            operands << (token.is_a?(Keyword) ? keyword_value(token.name) : token)
+          end
+        end
+      end
+
+      def next_token
+        skip_whitespace
+        return :eof if @scanner.eos?
+
+        return Reference.new(@scanner[1].to_i, @scanner[2].to_i) if @scanner.scan(REFERENCE)
+
+        case @scanner.peek(1)
+        when "/" then name
+        when "(" then literal_string
+        when "<" then @scanner.peek(2) == "<<" ? dictionary : hex_string
+        when "[" then array
+        when "]", ">", ")", "{", "}"
+          raise MalformedError, "unexpected #{@scanner.getch} at #{position}"
+        else word
+        end
+      end
+
+      def skip_whitespace = @scanner.skip(WHITESPACE)
+
+      private
+
+      def keyword_value(word)
+        { "true" => true, "false" => false, "null" => nil }.fetch(word)
+      end
+
+      def word
+        text = @scanner.scan(REGULAR) or raise MalformedError, "unexpected #{@scanner.getch.inspect} at #{position}"
+        return Keyword.new(text) unless text.match?(NUMBER)
+
+        text.include?(".") ? text.to_f : text.to_i
+      end
+
+      def name
+        @scanner.getch
+        text = (@scanner.scan(REGULAR) || "").b
+        text.gsub(/#(\h\h)/) { ::Regexp.last_match(1).hex.chr }.to_sym
+      end
+
+      def array
+        @scanner.getch
+        result = []
+        loop do
+          skip_whitespace
+          raise MalformedError, "unterminated array" if @scanner.eos?
+          break @scanner.getch if @scanner.peek(1) == "]"
+
+          result << parse_object
+        end
+        result
+      end
+
+      def dictionary
+        @scanner.pos += 2
+        result = {}
+        loop do
+          skip_whitespace
+          raise MalformedError, "unterminated dictionary" if @scanner.eos?
+          break @scanner.pos += 2 if @scanner.peek(2) == ">>"
+
+          key = next_token
+          raise MalformedError, "dictionary key #{key.inspect} is not a name" unless key.is_a?(Symbol)
+
+          skip_whitespace
+          result[key] = @scanner.peek(2) == ">>" ? nil : parse_object
+        end
+        result
+      end
+
+      def hex_string
+        @scanner.getch
+        digits = @scanner.scan_until(/>/) or raise MalformedError, "unterminated hex string"
+        digits = digits.delete("^0-9A-Fa-f")
+        [digits.length.odd? ? "#{digits}0" : digits].pack("H*")
+      end
+
+      def literal_string
+        @scanner.getch
+        result = +"".b
+        depth = 1
+        loop do
+          chunk = @scanner.scan(/[^()\\]+/)
+          result << chunk.b.gsub(/\r\n?/, "\n") if chunk
+          char = @scanner.getch or raise MalformedError, "unterminated string"
+          case char
+          when "(" then depth += 1
+                        result << "("
+          when ")"
+            depth -= 1
+            break if depth.zero?
+
+            result << ")"
+          else result << escape
+          end
+        end
+        result
+      end
+
+      def escape
+        if (octal = @scanner.scan(/[0-7]{1,3}/))
+          (octal.to_i(8) & 0xFF).chr
+        elsif @scanner.skip(/\r\n?|\n/)
+          ""
+        else
+          char = @scanner.getch.to_s
+          ESCAPES.fetch(char, char).b
+        end
+      end
+
+      def stream_after(value)
+        return value unless value.is_a?(Hash)
+
+        skip_whitespace
+        return value unless @scanner.skip(/stream\r?\n/)
+
+        Stream.new(value, stream_data(value))
+      end
+
+      def stream_data(dictionary)
+        start = position
+        length = dictionary[:Length]
+        length = @length_resolver&.call(length) if length.is_a?(Reference)
+        if length_valid?(start, length)
+          @scanner.pos = start + length
+        elsif !@scanner.scan_until(/(?=\r?\n?endstream)/)
+          raise MalformedError, "unterminated stream"
+        end
+        data = @scanner.string.byteslice(start, position - start)
+        @scanner.skip(/\s*endstream/)
+        data
+      end
+
+      def length_valid?(start, length)
+        length.is_a?(Integer) && @scanner.string.byteslice(start + length, 30).to_s.match?(/\A\s*endstream/)
+      end
+
+      def skip_inline_image
+        @scanner.getch
+        @scanner.scan_until(/[\0\t\n\f\r ]EI(?=[\0\t\n\f\r ]|\z)/)
+      end
+    end
+  end
+end

data/lib/fillform/pdf/serializer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Fillform
+  module PDF
+    # Writes PDF objects as bytes.
+    module Serializer
+      NAME_ESCAPE = %r{[^!-~]|[#()<>\[\]{}/%]}n
+
+      module_function
+
+      def serialize(value)
+        case value
+        when nil then "null"
+        when true then "true"
+        when false then "false"
+        when Integer, Reference then value.to_s
+        when Float then number(value)
+        when Symbol then name(value)
+        when String then string(value)
+        when Array then "[#{value.map { |item| serialize(item) }.join(" ")}]"
+        when Hash then dictionary(value)
+        else raise ArgumentError, "cannot serialize #{value.class}"
+        end
+      end
+
+      def number(value)
+        return "0" unless value.finite?
+
+        text = value.to_s
+        text = format("%.12f", value).sub(/\.?0+\z/, "") if text.include?("e")
+        text == "-0" ? "0" : text
+      end
+
+      def name(value)
+        "/#{value.to_s.b.gsub(NAME_ESCAPE) { |char| format("#%02X", char.ord) }}"
+      end
+
+      def string(value)
+        "(#{value.b.gsub(/[()\\\r]/n) { |char| char == "\r" ? "\\r" : "\\#{char}" }})"
+      end
+
+      def dictionary(value)
+        "<<#{value.map { |key, item| "#{name(key)} #{serialize(item)}" }.join(" ")}>>"
+      end
+    end
+  end
+end

data/lib/fillform/pdf/text.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Fillform
+  module PDF
+    # Text strings: PDFDocEncoding, or UTF-16BE (and UTF-8 since PDF 2.0) with a byte order mark.
+    module Text
+      # The bytes where PDFDocEncoding differs from ISO-8859-1 (PDF 32000-1, annex D.2).
+      PDF_DOC_DIFFERENCES = {
+        0x18 => 0x02D8, 0x19 => 0x02C7, 0x1A => 0x02C6, 0x1B => 0x02D9, 0x1C => 0x02DD, 0x1D => 0x02DB,
+        0x1E => 0x02DA, 0x1F => 0x02DC, 0x7F => nil, 0x80 => 0x2022, 0x81 => 0x2020, 0x82 => 0x2021,
+        0x83 => 0x2026, 0x84 => 0x2014, 0x85 => 0x2013, 0x86 => 0x0192, 0x87 => 0x2044, 0x88 => 0x2039,
+        0x89 => 0x203A, 0x8A => 0x2212, 0x8B => 0x2030, 0x8C => 0x201E, 0x8D => 0x201C, 0x8E => 0x201D,
+        0x8F => 0x2018, 0x90 => 0x2019, 0x91 => 0x201A, 0x92 => 0x2122, 0x93 => 0xFB01, 0x94 => 0xFB02,
+        0x95 => 0x0141, 0x96 => 0x0152, 0x97 => 0x0160, 0x98 => 0x0178, 0x99 => 0x017D, 0x9A => 0x0131,
+        0x9B => 0x0142, 0x9C => 0x0153, 0x9D => 0x0161, 0x9E => 0x017E, 0x9F => nil, 0xA0 => 0x20AC, 0xAD => nil
+      }.freeze
+      PDF_DOC = Array.new(256) { |byte| PDF_DOC_DIFFERENCES.fetch(byte, byte)&.chr(Encoding::UTF_8) }.freeze
+      PDF_DOC_BYTES = PDF_DOC.each_with_index.filter_map { |char, byte| [char, byte.chr] if char }.to_h.freeze
+
+      module_function
+
+      def decode(bytes)
+        bytes = bytes.b
+        if bytes.start_with?("\xFE\xFF".b)
+          bytes.byteslice(2..).force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8, invalid: :replace)
+        elsif bytes.start_with?("\xEF\xBB\xBF".b)
+          bytes.byteslice(3..).force_encoding(Encoding::UTF_8).scrub
+        else
+          bytes.each_byte.map { |byte| PDF_DOC[byte] || "�" }.join
+        end
+      end
+
+      def pdf_doc_char(byte) = PDF_DOC[byte]
+
+      def encode(text)
+        text = text.to_s.encode(Encoding::UTF_8)
+        if text.each_char.all? { PDF_DOC_BYTES.key?(_1) }
+          return text.each_char.map do |char|
+            PDF_DOC_BYTES[char]
+          end.join.b
+        end
+
+        "\xFE\xFF".b + text.encode(Encoding::UTF_16BE).b
+      end
+    end
+  end
+end

data/lib/fillform/pdf/writer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Fillform
+  module PDF
+    # Writes the given objects of a document as a single revision with a cross-reference table.
+    class Writer
+      def initialize(document, numbers)
+        @document = document
+        @numbers = numbers
+      end
+
+      def to_pdf
+        out = "%PDF-#{version}\n%\xE2\xE3\xCF\xD3\n".b
+        offsets = {}
+        @numbers.each do |number|
+          offsets[number] = out.bytesize
+          out << "#{number} 0 obj\n".b << body(@document.object(number)) << "\nendobj\n".b
+        end
+        size = (@numbers.max || 0) + 1
+        xref = out.bytesize
+        out << cross_references(offsets, size)
+        out << "trailer\n#{Serializer.serialize(trailer(size))}\nstartxref\n#{xref}\n%%EOF\n".b
+      end
+
+      private
+
+      def version
+        catalog_version = @document.catalog[:Version].to_s
+        [catalog_version, @document.version].max
+      end
+
+      def body(value)
+        return Serializer.serialize(value).b unless value.is_a?(Stream)
+
+        dictionary = value.dictionary.merge(Length: value.raw.bytesize)
+        "#{Serializer.serialize(dictionary)}\nstream\n".b << value.raw.b << "\nendstream".b
+      end
+
+      def cross_references(offsets, size)
+        lines = Array.new(size) do |number|
+          offsets.key?(number) ? format("%010d 00000 n \n", offsets[number]) : "0000000000 65535 f \n"
+        end
+        "xref\n0 #{size}\n#{lines.join}".b
+      end
+
+      def trailer(size)
+        @document.trailer.slice(:Root, :Info, :ID).merge(Size: size)
+      end
+    end
+  end
+end

data/lib/fillform/pdf.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "pdf/objects"
+require_relative "pdf/filters"
+require_relative "pdf/parser"
+require_relative "pdf/text"
+require_relative "pdf/serializer"
+require_relative "pdf/writer"
+require_relative "pdf/document"

data/lib/fillform/pdf_forms.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "fillform"
+require_relative "data_format"
+require_relative "pdftk_wrapper"
+
+# The API of the pdf-forms gem, backed by Fillform. `gem "fillform", require: "fillform/pdf_forms"`
+# replaces `gem "pdf-forms"` without changing the code that calls it.
+module PdfForms
+  PdftkError = Fillform::Error
+
+  def self.new(*)
+    Fillform::PdftkWrapper.new(*)
+  end
+end

data/lib/fillform/pdftk_wrapper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Fillform
+  class PdftkWrapper
+    UNSUPPORTED_OPTIONS = %i[encrypt encrypt_password encrypt_options replacement_font drop_xfa drop_xmp
+                             need_appearances].freeze
+
+    attr_reader :options
+
+    # The path of the pdftk executable, if given, is ignored: pdftk is no longer needed.
+    def initialize(pdftk_or_options = nil, options = {})
+      @options = pdftk_or_options.is_a?(Hash) ? pdftk_or_options : options
+      check_options(@options)
+    end
+
+    # The values change on their way into the form like they do through the pdf-forms data format.
+    def fill_form(template, destination, data = {}, fill_options = {})
+      check_options(fill_options)
+      flatten = fill_options.fetch(:flatten, options[:flatten])
+      Fillform.fill(template, destination, encode(data), flatten: flatten ? true : false)
+    end
+
+    def read(path)
+      Pdf.new(path)
+    end
+
+    def get_fields(template)
+      read(template).fields
+    end
+
+    def get_field_names(template)
+      get_fields(template).map(&:name)
+    end
+
+    private
+
+    def encode(data)
+      data.each_with_object({}) do |(key, value), result|
+        if value.is_a?(Hash)
+          value.each { |sub_key, sub_value| result[name("#{key}_#{sub_key}")] = encode_value(sub_value) }
+        else
+          result[name(key.to_s)] = encode_value(value)
+        end
+      end
+    end
+
+    def format = options[:data_format] || "Fdf"
+
+    def name(key) = DataFormat.field_name(format, key)
+
+    def encode_value(value)
+      # pdf-forms writes the values of an array in one XFDF value, separated by spaces.
+      value = value.join(" ") if value.is_a?(Array) && format.to_s == "XFdf"
+      return value.map { |item| DataFormat.apply(format, item.to_s) } if value.is_a?(Array)
+
+      DataFormat.apply(format, value.to_s)
+    end
+
+    def check_options(options)
+      unsupported = options.keys.map(&:to_sym) & UNSUPPORTED_OPTIONS
+      raise Error, "Fillform does not support the pdftk options #{unsupported.join(", ")}" if unsupported.any?
+    end
+  end
+
+  class Pdf
+    attr_reader :path
+
+    def initialize(path)
+      @path = path.to_s
+      raise IOError, "#{@path} is not readable" unless File.readable?(@path)
+    end
+
+    def fields
+      @fields ||= Fillform.fields(path)
+    end
+
+    def field(name)
+      fields.find { |field| field.name == name }
+    end
+  end
+end

data/lib/fillform/report.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Fillform
+  # The field report of `pdftk dump_data_fields`, as pdf-forms parses it: pdftk's ReportAcroFormFields,
+  # which walks the field tree with an accumulated state and reports a node when its kids are unnamed.
+  class Report
+    State = Struct.new(:type, :name, :name_alt, :flags, :field_values, :default, :justification, :max_length,
+                       :option_list, :states, :pairs) do
+      def self.empty = new("", "", "", 0, [], "", 0, 0, false, [], [])
+
+      def copy = State.new(*to_a.map { |value| value.is_a?(Array) ? value.dup : value })
+    end
+
+    TYPES = { Btn: "Button", Tx: "Text", Ch: "Choice", Sig: "Signature" }.freeze
+    JUSTIFICATIONS = %w[Left Center Right].freeze
+
+    def initialize(document)
+      @document = document
+    end
+
+    def fields
+      @fields = []
+      form = @document.deref(@document.catalog&.[](:AcroForm))
+      kids = @document.deref(form[:Fields]) if form.is_a?(Hash)
+      walk(kids, State.empty, 0) if kids.is_a?(Array)
+      @fields
+    end
+
+    private
+
+    # Returns whether any kid has a name.
+    def walk(kids, state, depth)
+      saved = state.copy
+      named = false
+      kids.each do |kid|
+        node = @document.deref(kid)
+        next unless node.is_a?(Hash)
+        next unless read?(node, state)
+
+        if (children = @document.deref(node[:Kids])).is_a?(Array) && depth < 32
+          children_named = walk(children, state, depth + 1)
+          output(state) if !children_named && name?(node)
+          restore(state, saved)
+          named ||= children_named
+        elsif name?(node)
+          output(state)
+          restore(state, saved)
+          named = true
+        end
+      end
+      named
+    end
+
+    # Reads the attributes of a node into the state; false when its value is a null object.
+    def read?(node, state)
+      type = value(node, :FT)
+      state.type = TYPES.fetch(type, state.type) if type.is_a?(Symbol)
+      title = value(node, :T)
+      if title.is_a?(String)
+        state.name = [state.name.empty? ? nil : state.name,
+                      PDF::Text.decode(title)].compact.join(".")
+      end
+      alternate = value(node, :TU)
+      state.name_alt = alternate.is_a?(String) ? PDF::Text.decode(alternate) : ""
+      state.flags = value(node, :Ff).to_i if value(node, :Ff).is_a?(Numeric)
+      return false unless read_value?(node, state)
+
+      read_attributes(node, state)
+      true
+    end
+
+    def read_value?(node, state)
+      return true unless node.key?(:V)
+
+      value = value(node, :V)
+      return false if value.nil?
+
+      Array(value.is_a?(Array) ? value : [value]).each do |item|
+        text = text_or_name(@document.deref(item))
+        state.field_values |= [text] if text
+      end
+      true
+    end
+
+    def read_attributes(node, state)
+      default = text_or_name(value(node, :DV))
+      state.default = default if default
+      state.justification = value(node, :Q).to_i if value(node, :Q).is_a?(Numeric)
+      state.max_length = value(node, :MaxLen).to_i if value(node, :MaxLen).is_a?(Numeric)
+      read_options(value(node, :Opt), state) if value(node, :Opt).is_a?(Array)
+      appearances = value(node, :AP)
+      %i[N D R].each { |kind| read_states(@document.deref(appearances[kind]), state) } if appearances.is_a?(Hash)
+    end
+
+    def read_options(options, state)
+      state.option_list = true
+      options.each do |option|
+        option = @document.deref(option)
+        if option.is_a?(String)
+          state.states |= [PDF::Text.decode(option)]
+        elsif option.is_a?(Array)
+          texts = option.map { |item| @document.deref(item) }.grep(String)
+          state.pairs |= [texts.map { |text| PDF::Text.decode(text) }] if texts.size == 2
+        end
+      end
+    end
+
+    # pdftk lists the states of an appearance dictionary in the iteration order of a java.util.HashMap,
+    # and only the Off state when the field has an option list.
+    def read_states(appearances, state)
+      return unless appearances.is_a?(Hash)
+
+      names = JavaHashMap.order(appearances.keys)
+      names = names.select { |name| name == :Off } if state.option_list
+      state.states |= names.map { |name| Field.latin1(name) }
+    end
+
+    def restore(state, saved)
+      saved.copy.to_a.each_with_index { |value, index| state[index] = value }
+    end
+
+    def name?(node) = value(node, :T).is_a?(String)
+
+    def value(node, key) = @document.deref(node[key])
+
+    def text_or_name(value)
+      case value
+      when String then PDF::Text.decode(value)
+      when Symbol then Field.latin1(value)
+      end
+    end
+
+    # As pdf-forms reads the lines: the last value wins, leading whitespace and a trailing line end go.
+    def output(state)
+      @fields << Field.new(
+        name: state.name, type: state.type, flags: state.flags.to_s,
+        options: lines(state.states + state.pairs.map(&:first)),
+        justification: JUSTIFICATIONS.fetch(state.justification, state.justification.to_s),
+        value: line(interpret(state, state.field_values.last)),
+        value_default: line(state.default.empty? ? nil : interpret(state, state.default)),
+        name_alt: line(state.name_alt.empty? ? nil : state.name_alt),
+        max_length: (state.max_length.to_s if state.max_length.positive?)
+      )
+    end
+
+    # pdftk shows the value of a button with an option list as the option its number points to.
+    def interpret(state, value)
+      return value unless value && state.type == "Button" && state.option_list && value.match?(/\A[+-]?\d{1,9}\z/)
+
+      index = value.to_i
+      index.between?(0, state.states.size - 1) ? state.states[index] : value
+    end
+
+    def lines(values) = values.empty? ? nil : values.map { |value| value.lstrip.chomp }
+
+    def line(value) = value&.lstrip&.chomp
+  end
+
+  # The iteration order of the keys of a java.util.HashMap holding iText PdfNames.
+  module JavaHashMap
+    ESCAPED = [32, 35, 37, 40, 41, 47, 60, 62, 91, 93, 123, 125].freeze
+
+    module_function
+
+    def order(names)
+      capacity = 16
+      capacity *= 2 while names.size > capacity * 3 / 4
+      names.each_with_index.sort_by { |name, index| [bucket(name, capacity), index] }.map(&:first)
+    end
+
+    # The hash of iText's PdfName is computed over the name in iText's encoding, with the slash.
+    def bucket(name, capacity)
+      encoded = name.to_s.b.each_byte.map do |byte|
+        ESCAPED.include?(byte) || !byte.between?(32, 126) ? format("#%02x", byte) : byte.chr
+      end
+      hash = "/#{encoded.join}".each_byte.reduce(0) { |sum, byte| ((sum * 31) + byte) & 0xFFFFFFFF }
+      (hash ^ (hash >> 16)) & (capacity - 1)
+    end
+  end
+end

data/lib/fillform/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fillform
+  VERSION = "0.1.0"
+end