hexapdf 0.11.9 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f56bc512ed28de11d43f5b2eb662729086734dc3120e6c8e96b56eab89420da4
-  data.tar.gz: 4b9e75f7d533cc7b3c3a6e297d26ab0358dcaa4ac0f0a5346df3e95c90d9c173
+  metadata.gz: 34c65a5eca10ade6778049ce85a8913ce180c32fed6826254e61a9cd801482fb
+  data.tar.gz: 7fd2cd5870e03acd71e5d723e41199664d9cabd2ddb1fd9430f997918cc15dd3
 SHA512:
-  metadata.gz: 3651a7ed4a7fb305c79a70b0c009441b0e3012188ce5e8baf8847107bce27793e0c48a577ae0bbc9ae3d6bece5356b86955b4deb2abd505d0b7a856053461ab3
-  data.tar.gz: 7cfd77439479567d81133e39243715dd05b3a3b31ccc64fd923ec7391ba745834977011e4618f1f9462cdcb2a682ed1b102c20474a4b3f5d7c69be438c6abd51
+  metadata.gz: 843a8e201d625d0d1d4a6755aeecf0d2ed810372058d1fec0136bf781e51ed9c46346d3d52fb4d0eda50100aac0b29112f6e4d42c3555bc923deee4583dbba00
+  data.tar.gz: d2042cb0b6cbd82bae3d6252a87ef68ee7791e02bf87e96a233d10bf3bb37eb991dca63c7293396ad5c75d03ecc668938722dbc03ade777131c4cc190cbfbda4

data/CHANGELOG.md

@@ -1,3 +1,85 @@
+## 0.12.0 - 2020-08-12
+
+### Added
+
+* Convenience methods for accessing field flags for
+  [HexaPDF::Type::AcroForm::Field]
+* [HexaPDF::Type::AcroForm::TextField] and
+  [HexaPDF::Type::AcroForm::VariableTextField] for basic text field support
+* [HexaPDF::Type::AcroForm::ButtonField] for push button, radio button and
+  check box support
+* [HexaPDF::Type::AcroForm::ChoiceField] for combo box and list box support
+* [HexaPDF::Type::AcroForm::AppearanceGenerator] as central class for
+  generating appearance streams for form fields
+* Various convenience methods for [HexaPDF::Type::AcroForm::Form]
+* Various convenience methods for [HexaPDF::Type::AcroForm::Field]
+* Various convenience methods for [HexaPDF::Type::Annotations::Widget]
+* [HexaPDF::Type::Annotation::AppearanceDictionary]
+* [HexaPDF::Document#acro_form] and [HexaPDF::Type::Catalog#acro_form]
+  convenience methods
+* CLI command `hexapdf form` for listing fields of interactive forms and filling
+  them out
+* [HexaPDF::Rectangle] methods for setting the left, top, right, bottom, width
+  and height
+* Method #prenormalized_color to all color space implementations
+* [HexaPDF::Type::Font#font_wrapper] for accessing an associated font wrapper
+  instance
+* [HexaPDF::Type::FontType1#font_wrapper] for providing a font wrapper for the
+  standard PDF fonts
+* [HexaPDF::Type::Annotation::Border] class
+* [HexaPDF::Content::ColorSpace::device_color_from_specification] for easily
+  getting a device color object
+* [HexaPDF::Content::ColorSpace::prenormalized_device_color] for getting a device
+  color object without normalizing values
+* [HexaPDF::Type::Annotation#appearance] for returning the associated appearance
+  dictionary
+* [HexaPDF::Type::Annotation#appearance?] for checking whether an appearance for
+  the annotation exists
+* Configuration option 'acro_form.create_appearance_streams' for automatically
+  creating appearance streams
+* [HexaPDF::Type::Resources] methods `#pattern` and `add_pattern`
+
+### Changed
+
+* Deletion of pages to delete them from the document as well
+* Refactored [HexaPDF::Font::Type1Wrapper] and [HexaPDF::Font::TrueTypeWrapper]
+  and renamed `#dict` to `#pdf_object`
+* Fall back to the Type1 font's internal encoding when decoding a string
+* All [HexaPDF::Content::ColorSpace] implementations to only normalize values
+  when using the ::color method
+* [HexaPDF::Content::Parser#parse] to also accept a block in place of a
+  processor object
+* HexaPDF::Type::AcroForm::Field#full_name to
+  [HexaPDF::Type::AcroForm::Field#full_field_name]
+* Moved `HexaPDF::Content::Canvas#color_space_for_components` to class method on
+  [HexaPDF::Content::ColorSpace]
+* Added bit unsetter method to[HexaPDF::Utils::BitField]
+* [HexaPDF::Type::AcroForm::Form#find_root_fields] and `#each_field` to take the
+  field type into account when wrapping a field dictionary
+* Pages specification of CLI commands to allow counting from the end using the
+  new `r<N>` notation
+* [HexaPDF::Font::Type1Wrapper] to use the internal encoding of a font with a
+  'Special' character set instead of a custom encoding
+* Configuration 'filter.map' to use the pass-through filter on all unsupported
+  filters
+
+### Fixed
+
+* Wrong normalization of color values when invoking a color operator
+* Invalid type of `/DR` field of [HexaPDF::Type::AcroForm::Form]
+* Invalid ordering of types for the `/V` and `/DV` fields of
+  [HexaPDF::Type::AcroForm::Field]
+* [HexaPDF::Type::AcroForm::Field#terminal_field?] to work according to the spec
+* Handling of empty files by throwing better error messages
+* [HexaPDF::Type::Image#info] to correctly identify images with a soft mask as
+  currently not supported for writing
+* [HexaPDF::Revision#delete] to remove the connection between the object and the
+  document
+* Missing `#definition` method of `DeviceRGB`, `DeviceCMYK` and `DeviceGray`
+  color spaces
+* Handling of 'Pattern' color spaces when parsing content streams
+
+
 ## 0.11.9 - 2020-06-15
 
 ### Changed

data/LICENSE

@@ -1,5 +1,5 @@
 HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-Copyright (C) 2014-2019 Thomas Leitner
+Copyright (C) 2014-2020 Thomas Leitner
 
 HexaPDF is free software: you can redistribute it and/or modify it
 under the terms of the GNU Affero General Public License version 3 as

data/examples/001-hello_world.rb

@@ -1,4 +1,4 @@
-# ## Hello World
+# # Hello World
 #
 # This simple example mimics the classic "hello world" examples from
 # programming languages.

data/examples/002-graphics.rb

@@ -1,4 +1,4 @@
-# ## Graphics Primitives
+# # Graphics Primitives
 #
 # This example shows many of the operations that the canvas implementation
 # allows.

data/examples/003-arcs.rb

@@ -1,4 +1,4 @@
-# ## Arcs and Solid Arcs
+# # Arcs and Solid Arcs
 #
 # This example shows how to use the graphic objects `:arc` and `:solid_arc` to
 # draw simple pie charts.

data/examples/004-optimizing.rb

@@ -1,4 +1,4 @@
-# ## Optimizing a PDF File
+# # Optimizing a PDF File
 #
 # This example shows how to read a PDF file, optimize it and write it
 # out again.

data/examples/005-merging.rb

@@ -1,4 +1,4 @@
-# ## Merging PDF Files
+# # Merging PDF Files
 #
 # Merging of PDF files can be done in various ways of sophistication.
 #

data/examples/006-standard_pdf_fonts.rb

@@ -1,4 +1,4 @@
-# ## Standard PDF Fonts
+# # Standard PDF Fonts
 #
 # This example shows all characters that are available in the standard 14 PDF
 # fonts.

data/examples/007-truetype.rb

@@ -1,4 +1,4 @@
-# ## TrueType Fonts
+# # TrueType Fonts
 #
 # This example displays all glyphs of a TrueType font and shows that using a
 # TrueType font with HexaPDF is very similar to using one of the standard PDF

data/examples/008-show_char_bboxes.rb

@@ -1,4 +1,4 @@
-# ## Show Character Bounding Boxes
+# # Show Character Bounding Boxes
 #
 # This examples shows how to process the contents of a page. It finds all
 # characters on a page and surrounds them with their bounding box. Additionally,

data/examples/009-text_layouter_alignment.rb

@@ -1,4 +1,4 @@
-# ## Text Layouter - Alignment
+# # Text Layouter - Alignment
 #
 # The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text
 # inside a rectangular area, with various horizontal and vertical alignment

data/examples/010-text_layouter_inline_boxes.rb

@@ -1,4 +1,4 @@
-# ## Text Layouter - Inline Boxes
+# # Text Layouter - Inline Boxes
 #
 # The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text
 # mixed with inline boxes.

data/examples/011-text_layouter_line_wrapping.rb

@@ -1,4 +1,4 @@
-# ## Text Layouter - Line Wrapping
+# # Text Layouter - Line Wrapping
 #
 # The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text,
 # automatically wrapping it appropriately.

data/examples/012-text_layouter_styling.rb

@@ -1,4 +1,4 @@
-# ## Text Layouter - Styling
+# # Text Layouter - Styling
 #
 # The text used as part of a [HexaPDF::Layout::TextLayouter] class can be styled
 # using [HexaPDF::Layout::Style]. To do this [HexaPDF::Layout::TextFragment]

data/examples/013-text_layouter_shapes.rb

@@ -1,4 +1,4 @@
-# ## Text Layouter - Shapes
+# # Text Layouter - Shapes
 #
 # The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text,
 # not limiting the area to a rectangle but any shape. There is only one

data/examples/014-text_in_polygon.rb

@@ -1,4 +1,4 @@
-# ## Text in Polygon
+# # Text in Polygon
 #
 # While creating width specifications for the [HexaPDF::Layout::TextLayouter]
 # class by hand is possible, the [HexaPDF::Layout::WidthFromPolygon] class

data/examples/015-boxes.rb

@@ -1,4 +1,4 @@
-# ## Boxes
+# # Boxes
 #
 # The [HexaPDF::Layout::Box] class is used as the basis for all document layout
 # features.

data/examples/016-frame_automatic_box_placement.rb

@@ -1,4 +1,4 @@
-# ## Frame - Automatic Box Placement
+# # Frame - Automatic Box Placement
 #
 # The [HexaPDF::Layout::Frame] class is used for placing rectangular boxes.
 #

data/examples/017-frame_text_flow.rb

@@ -1,4 +1,4 @@
-# ## Frame - Text Flow
+# # Frame - Text Flow
 #
 # This example shows how [HexaPDF::Layout::Frame] and [HexaPDF::Layout::TextBox]
 # can be used to flow text around objects.

data/examples/018-composer.rb

@@ -1,4 +1,4 @@
-# ## Composer
+# # Composer
 #
 # This example shows how [HexaPDF::Composer] simplifies the creation of PDF
 # documents by providing a high-level interface to the box layouting engine.

data/examples/019-acro_form.rb

@@ -0,0 +1,51 @@
+# # PDF Forms
+#
+# PDF files can be used for interactive forms, containing various types of form
+# fields. HexaPDF supports the creation and processing of these forms.
+#
+# This example show-cases how to create the various form field types and their
+# possible standard appearances.
+#
+# Usage:
+# : `ruby acro_form.rb`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+page = doc.pages.add
+canvas = page.canvas
+
+canvas.font("Helvetica", size: 36)
+canvas.text("Form Example", at: [50, 750])
+form = doc.acro_form(create: true)
+
+canvas.font_size(16)
+canvas.text("Check boxes", at: [50, 650])
+[:check, :circle, :cross, :diamond, :square, :star].each_with_index do |symbol, index|
+  cb = form.create_check_box("Checkbox #{index}")
+  widget = cb.create_widget(page, Rect: [200 + 50 * index, 640, 240 + 50 * index, 680])
+  widget.background_color(1 - 0.05 * index)
+  widget.marker_style(style: symbol, color: [0.166 * index, 0, 1 - 0.166 * index],
+                      size: 7 * index)
+  cb.field_value = true
+end
+
+canvas.text("Radio buttons", at: [50, 550])
+rb = form.create_radio_button("Radio")
+[:check, :circle, :cross, :diamond, :square, :star].each_with_index do |symbol, index|
+  widget = rb.create_widget(page, value: :"button#{index}",
+                            Rect: [200 + 50 * index, 540, 240 + 50 * index, 580])
+  widget.background_color(1 - 0.05 * index)
+  widget.marker_style(style: symbol, color: [0.166 * index, 0, 1 - 0.166 * index],
+                      size: 7 * index)
+end
+rb.field_value = :button0
+
+canvas.text("Text field", at: [50, 450])
+tx = form.create_text_field("Single Line")
+widget = tx.create_widget(page, Rect: [200, 445, 500, 465])
+tx.set_default_appearance_string(font_size: 16)
+tx.field_value = "A sample test string!"
+
+doc.write('acro_form.pdf', optimize: true)

data/lib/hexapdf.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/cli.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -46,6 +46,7 @@ require 'hexapdf/cli/batch'
 require 'hexapdf/cli/split'
 require 'hexapdf/cli/watermark'
 require 'hexapdf/cli/image2pdf'
+require 'hexapdf/cli/form'
 require 'hexapdf/version'
 require 'hexapdf/document'
 
@@ -99,6 +100,7 @@ module HexaPDF
         add_command(HexaPDF::CLI::Split.new)
         add_command(HexaPDF::CLI::Watermark.new)
         add_command(HexaPDF::CLI::Image2PDF.new)
+        add_command(HexaPDF::CLI::Form.new)
         add_command(CmdParse::HelpCommand.new)
         version_command = CmdParse::VersionCommand.new(add_switches: false)
         add_command(version_command)

data/lib/hexapdf/cli/batch.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/cli/command.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -80,7 +80,7 @@ module HexaPDF
       # Creates a HexaPDF::Document instance for the PDF file and yields it.
       #
       # If +out_file+ is given, the document is written to it after yielding.
-      def with_document(file, password: nil, out_file: nil) #:yield: document
+      def with_document(file, password: nil, out_file: nil, incremental: false) #:yield: document
         if file == out_file
           doc = HexaPDF::Document.open(file, **pdf_options(password))
         else
@@ -90,7 +90,7 @@ module HexaPDF
 
         yield(doc)
 
-        write_document(doc, out_file)
+        write_document(doc, out_file, incremental: incremental)
       ensure
         file_io&.close
       end
@@ -116,7 +116,7 @@ module HexaPDF
       end
 
       # Writes the document to the given file or does nothing if +out_file+ is +nil+.
-      def write_document(doc, out_file)
+      def write_document(doc, out_file, incremental: false)
         if out_file
           doc.validate(auto_correct: true) do |object, msg, correctable|
             if command_parser.strict && !correctable
@@ -126,7 +126,7 @@ module HexaPDF
                 "for object (#{object.oid},#{object.gen}): #{msg}"
             end
           end
-          doc.write(out_file, validate: false)
+          doc.write(out_file, validate: false, incremental: incremental)
         end
       end
 
@@ -289,7 +289,16 @@ module HexaPDF
         end
       end
 
-      PAGE_NUMBER_SPEC = "([1-9]\\d*|e)" #:nodoc:
+      PAGE_NUMBER_SPEC = "(r?[1-9]\\d*|e)" #:nodoc:
+      PAGE_MAP = lambda do |result, count|
+        if result == 'e'
+          count
+        elsif result.start_with?('r')
+          count - result[1..-1].to_i + 1
+        else
+          result.to_i
+        end
+      end
       ROTATE_MAP = {'l' => 90, 'r' => -90, 'd' => 180, 'n' => :none}.freeze #:nodoc:
 
       # Parses the pages specification string and returns an array of tuples containing a page
@@ -304,12 +313,12 @@ module HexaPDF
         range.split(',').each_with_object([]) do |str, arr|
           case str
           when /\A#{PAGE_NUMBER_SPEC}(l|r|d|n)?\z/o
-            page_num = ($1 == 'e' ? count : str.to_i)
+            page_num = PAGE_MAP[$1, count]
             next if page_num > count
             arr << [page_num - 1, ROTATE_MAP[$2]]
           when /\A#{PAGE_NUMBER_SPEC}-#{PAGE_NUMBER_SPEC}(?:\/([1-9]\d*))?(l|r|d|n)?\z/o
-            start_nr = ($1 == 'e' ? count : [$1.to_i, count].min) - 1
-            end_nr = ($2 == 'e' ? count : [$2.to_i, count].min) - 1
+            start_nr = [PAGE_MAP[$1, count], count].min - 1
+            end_nr = [PAGE_MAP[$2, count], count].min - 1
             step = ($3 ? $3.to_i : 1) * (start_nr > end_nr ? -1 : 1)
             rotation = ROTATE_MAP[$4]
             start_nr.step(to: end_nr, by: step) {|n| arr << [n, rotation] }

data/lib/hexapdf/cli/files.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/cli/form.rb

@@ -0,0 +1,240 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2020 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/cli/command'
+require 'strscan'
+
+module HexaPDF
+  module CLI
+
+    # Processes a PDF that contains an interactive form (AcroForm).
+    class Form < Command
+
+      def initialize #:nodoc:
+        super('form', takes_commands: false)
+        short_desc("Show form fields and fill out a form")
+        long_desc(<<~EOF)
+          Use this command to process interactive PDF forms.
+
+          If the the output file name is not given, all form fields are listed in page order. Use
+          the global --verbose option to show additional information like field type and location.
+
+          If the output file name is given, the fields can be interactively filled out. By
+          additionally using the --template option, the data for the fields is read from the given
+          template file instead of the standard input.
+        EOF
+
+        options.on("--password PASSWORD", "-p", String,
+                   "The password for decryption. Use - for reading from standard input.") do |pwd|
+          @password = (pwd == '-' ? read_password : pwd)
+        end
+        options.on("--template TEMPLATE_FILE", "-t TEMPLATE_FILE",
+                   "Use the template file for the field values") do |template|
+          @template = template
+        end
+        options.on("--[no-]viewer-override", "Let the PDF viewer override the visual " \
+                   "appearance. Default: use setting from input PDF") do |need_appearances|
+          @need_appearances = need_appearances
+        end
+        options.on("--[no-]incremental-save", "Append the changes instead of rewriting the " \
+                   "whole file. Default: true") do |incremental|
+          @incremental = incremental
+        end
+
+        @password = nil
+        @template = nil
+        @need_appearances = nil
+        @incremental = true
+      end
+
+      def execute(in_file, out_file = nil) #:nodoc:
+        maybe_raise_on_existing_file(out_file) if out_file
+        with_document(in_file, password: @password, out_file: out_file,
+                      incremental: @incremental) do |doc|
+          if !doc.acro_form
+            raise "This PDF doesn't contain an interactive form"
+          elsif out_file
+            doc.acro_form[:NeedAppearances] = @need_appearances unless @need_appearances.nil?
+            if @template
+              fill_form_with_template(doc)
+            else
+              fill_form(doc)
+            end
+          else
+            list_form_fields(doc)
+          end
+        end
+      end
+
+      private
+
+      # Lists all terminal form fields.
+      def list_form_fields(doc)
+        current_page_index = -1
+        each_field(doc) do |_page, page_index, field, widget|
+          if current_page_index != page_index
+            puts "Page #{page_index + 1}"
+            current_page_index = page_index
+          end
+
+          field_name = field.full_field_name +
+            (field.alternate_field_name ? " (#{field.alternate_field_name})" : '')
+          concrete_field_type = field.concrete_field_type
+          nice_field_type = concrete_field_type.to_s.split('_').map(&:capitalize).join(' ')
+          position = "(#{widget[:Rect].left}, #{widget[:Rect].bottom})"
+
+          puts "  #{field_name}"
+          if command_parser.verbosity_info?
+            printf("    └─ %-22s | %-20s\n", nice_field_type, position)
+          end
+          puts "    └─ #{field.field_value.inspect}"
+          if command_parser.verbosity_info?
+            if field.field_type == :Ch
+              puts "    └─ Options: #{field.option_items.map(&:inspect).join(', ')}"
+            elsif concrete_field_type == :radio_button
+              puts "    └─ Options: #{field.radio_button_values.map(&:inspect).join(', ')}"
+            end
+          end
+        end
+      end
+
+      # Fills out the form by interactively asking the user for field values.
+      def fill_form(doc)
+        current_page_index = -1
+        each_field(doc) do |_page, page_index, field, _widget|
+          if current_page_index != page_index
+            puts "Page #{page_index + 1}"
+            current_page_index = page_index
+          end
+
+          field_name = field.full_field_name +
+            (field.alternate_field_name ? " (#{field.alternate_field_name})" : '')
+          concrete_field_type = field.concrete_field_type
+
+          puts "  #{field_name}"
+          puts "    └─ Current value: #{field.field_value.inspect}"
+
+          if field.field_type == :Ch
+            puts "    └─ Possible values: #{field.option_items.map(&:inspect).join(', ')}"
+          elsif concrete_field_type == :radio_button
+            puts "    └─ Possible values: #{field.radio_button_values.map(&:inspect).join(', ')}"
+          elsif concrete_field_type == :check_box
+            puts "    └─ Possible values: y(es), t(rue); n(o), f(alse)"
+          end
+
+          begin
+            print "    └─ New value: "
+            value = $stdin.readline.chomp
+            next if value.empty?
+            apply_field_value(field, value)
+          rescue HexaPDF::Error => e
+            puts "       ⚠  #{e.message}"
+            retry
+          end
+        end
+      end
+
+      # Fills out the form using the data from the provided template file.
+      def fill_form_with_template(doc)
+        data = parse_template
+        form = doc.acro_form
+        data.each do |name, value|
+          field = form.field_by_name(name)
+          raise "Field '#{name}' not found in input PDF" unless field
+          apply_field_value(field, value)
+        end
+      end
+
+      # Parses the data from the given template file.
+      def parse_template
+        data = {}
+        scanner = StringScanner.new(File.read(@template))
+        until scanner.eos?
+          field_name = scanner.scan(/(\\:|[^:])*?:/)
+          break unless field_name
+          field_name.gsub!(/\\:/, ':')
+          field_value = scanner.scan(/.*?(?=^\S|\z)/m)
+          data[field_name.chop] = field_value.strip.gsub(/^\s*/, '') if field_value
+        end
+        if !scanner.eos? && command_parser.verbosity_warning?
+          $stderr.puts "Warning: Some template could not be parsed"
+        end
+        data
+      end
+
+      # Applies the given value to the field.
+      def apply_field_value(field, value)
+        case field.concrete_field_type
+        when :single_line_text_field
+          field.field_value = value
+        when :combo_box, :list_box
+          field.field_value = value
+        when :editable_combo_box
+          field.field_value = value
+        when :check_box
+          unless value.match?(/y(es)?|t(rue)?|f(alse)?|n(o)/)
+            raise HexaPDF::Error, "Invalid input, use one of the possible values"
+          end
+          field.field_value = value.match?(/y(es)?|t(rue)?/)
+        when :radio_button
+          field.field_value = value.intern
+        else
+          raise "Field type not yet supported"
+        end
+      end
+
+      # Iterates over all non-push button fields in page order. If a field appears on multiple
+      # pages, it is only yielded on the first page.
+      def each_field(doc) # :yields: page, page_index, field
+        seen = {}
+
+        doc.pages.each_with_index do |page, page_index|
+          page[:Annots]&.each do |annotation|
+            next unless annotation[:Subtype] == :Widget
+            field = annotation.form_field
+            next if field.concrete_field_type == :push_button
+            unless seen[field]
+              yield(page, page_index, field, annotation)
+              seen[field] = true
+            end
+          end
+        end
+      end
+
+    end
+
+  end
+end