hexapdf 0.32.2 → 0.34.0

data/examples/027-composer_optional_content.rb

@@ -0,0 +1,83 @@
+# # Composer - Optional Content
+#
+# This example shows how to use the optional content feature to create a quiz
+# where the answers can be individually shown and hidden. There is also a link
+# after the questions to toggle all answers.
+#
+# Note: To provide the "All answers" layer switch functionality we need to make
+# use of optional content membership dictionaries. However, this PDF feature is
+# not supported by all PDF viewers. To enable the "All answers" switch in this
+# example, use `a1m`, `a2m`, and `a3m` instead of `a1`, `a2`, and `a3` when
+# defining the optional content for a box.
+#
+# Usage:
+# : `ruby composer_optional_content.rb`
+#
+require 'hexapdf'
+
+HexaPDF::Composer.create('composer_optional_content.pdf') do |composer|
+  composer.style(:question, font_size: 16, margin: [0, 0, 16], fill_color: 'hp-blue')
+  composer.style(:answer, font: 'ZapfDingbats', fill_color: "green")
+
+  all = composer.document.optional_content.ocg('All answers')
+  a1 = composer.document.optional_content.ocg('Answer 1')
+  a1m = composer.document.optional_content.create_ocmd([a1, all], policy: :any_on)
+  a2 = composer.document.optional_content.ocg('Answer 2')
+  a2m = composer.document.optional_content.create_ocmd([a2, all], policy: :any_on)
+  a3 = composer.document.optional_content.ocg('Answer 3')
+  a3m = composer.document.optional_content.create_ocmd([a3, all], policy: :any_on)
+
+  composer.text('The Great Ruby Quiz', align: :center, margin: [0, 0, 24],
+                font: ['Helvetica', variant: :bold], font_size: 24)
+
+  composer.list(item_type: :decimal, item_spacing: 32, style: :question) do |listing|
+    listing.multiple do |item|
+      item.text('Who created Ruby?', style: :question)
+      item.column(columns: 3, gaps: 5) do |cols|
+        cols.list(item_type: :decimal) do |answers|
+          answers.text('Guido van Rossum')
+          answers.multiple do |answer|
+            answer.text('Yukihiro “Matz” Matsumoto', position: :float)
+            answer.text("\u{a0}\u{a0}4", style: :answer,
+                        properties: {'optional_content' => a1})
+          end
+          answers.text('Rob Pike')
+        end
+      end
+    end
+
+    listing.multiple do |item|
+      item.text('When was Ruby created?', style: :question)
+      item.column(columns: 3, gaps: 5) do |cols|
+        cols.list(item_type: :decimal) do |answers|
+          answers.text('1991')
+          answers.text('1992')
+          answers.multiple do |answer|
+            answer.text('1993', position: :float)
+            answer.text("\u{a0}\u{a0}4", style: :answer,
+                        properties: {'optional_content' => a2})
+          end
+        end
+      end
+    end
+
+    listing.multiple do |item|
+      item.text('What is the best PDF library for Ruby?', style: :question)
+      answer = composer.document.layout.text('There are several PDF libraries for ' \
+                                             'Ruby but the best is HexaPDF! :)',
+                                             width: 400,
+                                             properties: {'optional_content' => a3})
+      item.formatted_text([{box: answer}], border: {width: [0, 0, 1]})
+    end
+  end
+
+  action = composer.document.wrap({Type: :Action, S: :SetOCGState})
+  action.add_state_change(:toggle, [a1, a2, a3])
+  composer.text("Click to toggle answers", border: {width: 1, color: "red"},
+                position_hint: :right, padding: 2, overlays: [[:link, action: action]])
+
+  composer.document.optional_content.default_configuration(
+    BaseState: :OFF,
+    Order: [all, a1, a2, a3],
+  )
+end

data/lib/hexapdf/cli/command.rb

@@ -43,6 +43,9 @@ require 'hexapdf/font/true_type'
 module HexaPDF
   module CLI
 
+    # Raised when problems occur on the CLI side of things.
+    class Error < HexaPDF::Error; end
+
     # Base class for all hexapdf commands. It provides utility methods needed by the individual
     # commands.
     class Command < CmdParse::Command
@@ -50,9 +53,15 @@ module HexaPDF
       module Extensions #:nodoc:
         def help_banner #:nodoc:
           "hexapdf #{HexaPDF::VERSION} - Versatile PDF Manipulation Tool\n" \
-            "Copyright (c) 2014-2021 Thomas Leitner; licensed under the AGPLv3\n\n" \
+            "Copyright (c) 2014-2023 Thomas Leitner; licensed under the AGPLv3\n\n" \
             "#{format(usage, indent: 7)}\n\n"
         end
+
+        def help #:nodoc:
+          super << format("See https://hexapdf.gettalong.org/documentation/hexapdf.1.html " \
+                          "for the full manual page with examples.", indent: 0)
+        end
+
       end
 
       include Extensions
@@ -134,7 +143,7 @@ module HexaPDF
           doc.trailer.update_id
           doc.validate(auto_correct: true) do |msg, correctable, object|
             if command_parser.strict && !correctable
-              raise "Validation error for object (#{object.oid},#{object.gen}): #{msg}"
+              raise Error, "Validation error for object (#{object.oid},#{object.gen}): #{msg}"
             elsif command_parser.verbosity_info?
               $stderr.puts "#{correctable ? 'Corrected' : 'Ignored'} validation problem " \
                 "for object (#{object.oid},#{object.gen}): #{msg}"
@@ -151,7 +160,7 @@ module HexaPDF
       # HexaPDF::CLI#force is not set.
       def maybe_raise_on_existing_file(filename)
         if !command_parser.force && File.exist?(filename)
-          raise "Output file '#{filename}' already exists, not overwriting. Use --force to " \
+          raise Error, "Output file '#{filename}' already exists, not overwriting. Use --force to " \
             "force writing"
         end
       end

data/lib/hexapdf/cli/fonts.rb

@@ -127,7 +127,7 @@ module HexaPDF
           page.resources[:Font]&.each(&font_proc)
           page.resources[:XObject]&.each do |_, xobj|
             next unless xobj[:Subtype] == :Form
-            xobj.ressources[:Font]&.each(&font_proc)
+            xobj.resources[:Font]&.each(&font_proc)
           end
           page.each_annotation do |annotation|
             appearance = annotation.appearance

data/lib/hexapdf/cli/form.rb

@@ -97,7 +97,7 @@ module HexaPDF
       def execute(in_file, out_file = nil) #:nodoc:
         maybe_raise_on_existing_file(out_file) if out_file
         if (@fill || @flatten) && !out_file
-          raise "Output file missing"
+          raise Error, "Output file missing"
         end
         with_document(in_file, password: @password, out_file: out_file,
                       incremental: @incremental) do |doc|
@@ -106,7 +106,7 @@ module HexaPDF
           end
 
           if !doc.acro_form
-            raise "This PDF doesn't contain an interactive form"
+            raise Error, "This PDF doesn't contain an interactive form"
           elsif out_file
             doc.acro_form[:NeedAppearances] = @need_appearances unless @need_appearances.nil?
             if @fill || !@flatten
@@ -220,7 +220,7 @@ module HexaPDF
         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
+          raise Error, "Field '#{name}' not found in input PDF" unless field
           apply_field_value(field, value)
         end
       end
@@ -268,10 +268,10 @@ module HexaPDF
         when :radio_button
           field.field_value = value.to_sym
         else
-          raise "Field type #{field.concrete_field_type} not yet supported"
+          raise Error, "Field type #{field.concrete_field_type} not yet supported"
         end
       rescue StandardError
-        raise "Error while setting '#{field.full_field_name}': #{$!.message}"
+        raise Error, "Error while setting '#{field.full_field_name}': #{$!.message}"
       end
 
       # Iterates over all non-push button fields in page order. If a field appears on multiple

data/lib/hexapdf/cli/inspect.rb

@@ -93,11 +93,9 @@ module HexaPDF
 
       private
 
-      # :nodoc:
-      COMMAND_LIST = %w[object recursive stream raw-stream xref catalog trailer pages
+      COMMAND_LIST = %w[object recursive stream raw-stream xref catalog trailer pages # :nodoc:
                         page-count search quit help]
-      # :nodoc:
-      RELINE_COMPLETION_PROC = proc do |s|
+      RELINE_COMPLETION_PROC = proc do |s| # :nodoc:
         if s.empty?
           COMMAND_DESCRIPTIONS.map {|cmd, desc| cmd.ljust(35) << desc }
         else
@@ -266,11 +264,11 @@ module HexaPDF
       # Resolves the PDF object from the given string reference and returns it.
       def pdf_object_from_string_reference(str)
         if str.nil?
-          raise "Error: Missing argument object identifier OID[,GEN]"
+          raise Error, "Error: Missing argument object identifier OID[,GEN]"
         elsif !str.match?(/^\d+(,\d+)?$/)
-          raise "Error: Invalid argument: Must be of form OID[,GEN], not '#{str}'"
+          raise Error, "Error: Invalid argument: Must be of form OID[,GEN], not '#{str}'"
         elsif !(obj = @doc.object(pdf_reference_from_string(str)))
-          raise "Error: No object with the given object identifier '#{str}' found"
+          raise Error, "Error: No object with the given object identifier '#{str}' found"
         else
           obj
         end

data/lib/hexapdf/composer.rb

@@ -51,17 +51,18 @@ module HexaPDF
   # On creation a HexaPDF::Document object is created as well the first page and an accompanying
   # HexaPDF::Layout::Frame object. The frame is used by the various methods for general document
   # layout tasks, like positioning of text, images, and so on. By default, it covers the whole page
-  # except the margin area. How the frame gets created can be customized by overriding the
-  # #create_frame method.
+  # except the margin area. How the frame gets created can be customized by defining a custom page
+  # style, see #page_style. Use the +skip_page_creation+ argument to avoid the initial page
+  # creation when creating a Composer instance.
   #
   # Once the Composer object is created, its methods can be used to draw text, images, ... on the
-  # page. Behind the scenes HexaPDF::Layout::Box (and subclass) objects are created and drawn on the
-  # page via the frame.
+  # page. Behind the scenes HexaPDF::Layout::Box (and subclass) objects are created using the
+  # HexaPDF::Document::Layout methods and drawn on the page via the frame.
   #
   # If the frame of a page is full and a box doesn't fit anymore, a new page is automatically
   # created. The box is either split into two boxes where one fits on the first page and the other
   # on the new page, or it is drawn completely on the new page. A new page can also be created by
-  # calling the #new_page method.
+  # calling the #new_page method, optionally providing a page style.
   #
   # The #x and #y methods provide the point where the next box would be drawn if it fits the
   # available space. This information can be used, for example, for custom drawing operations
@@ -75,30 +76,36 @@ module HexaPDF
   #
   # == Example
   #
-  #   HexaPDF::Composer.create('output.pdf', margin: 36) do |pdf|
-  #     pdf.base_style.font_size(20).align(:center)
+  #   #>pdf-full
+  #   HexaPDF::Composer.create('out.pdf', page_size: :A6, margin: 36) do |pdf|
+  #     pdf.style(:base, font_size: 20, align: :center)
   #     pdf.text("Hello World", valign: :center)
   #   end
+  #
+  # See: HexaPDF::Document::Layout, HexaPDF::Layout::Frame, HexaPDF::Layout::Box
   class Composer
 
-    # Creates a new PDF document and writes it to +output+. The +options+ are passed to ::new.
+    # Creates a new PDF document and writes it to +output+. The argument +options+ and +block+ are
+    # passed to ::new.
     #
     # Example:
     #
-    #   HexaPDF::Composer.create('output.pdf', margin: 36) do |pdf|
+    #   HexaPDF::Composer.create('out.pdf', margin: 36) do |pdf|
     #     ...
     #   end
     def self.create(output, **options, &block)
       new(**options, &block).write(output)
     end
 
-    # The PDF document that is created.
+    # The PDF document (HexaPDF::Document) that is created.
     attr_reader :document
 
     # The current page (a HexaPDF::Type::Page object).
     attr_reader :page
 
-    # The Content::Canvas of the current page. Can be used to perform arbitrary drawing operations.
+    # The canvas instance (a Content::Canvas object) of the current page.
+    #
+    # Can be used to perform arbitrary drawing operations.
     attr_reader :canvas
 
     # The HexaPDF::Layout::Frame for automatic box placement.
@@ -107,43 +114,53 @@ module HexaPDF
     # Creates a new Composer object and optionally yields it to the given block.
     #
     # skip_page_creation::
-    #     If this argument is +true+ (the default), the arguments +page_size+, +page_orientation+
-    #     and +margin+ are used to create a page style with the name :default and an initial page is
-    #     created as well.
+    #     If this argument is +false+ (the default), the arguments +page_size+, +page_orientation+
+    #     and +margin+ are used to create a page style with the name :default. Additionally, an
+    #     initial page/frame is created using this page style.
     #
-    #     Otherwise, i.e. when this argument is +false+, no initial page or default page style is
-    #     created. This has to be done manually using the #page_style and #new_page methods.
+    #     Otherwise, i.e. when this argument is +true+, no initial page or default page style is
+    #     created. This is useful when the first page needs a custom page style. The #page_style
+    #     method needs to be used to define a page style which is then used with the #new_page
+    #     method to create the initial page/frame.
     #
     # page_size::
     #     Can be any valid predefined page size (see Type::Page::PAPER_SIZE) or an array [llx, lly,
     #     urx, ury] specifying a custom page size.
     #
+    #     Only used if +skip_page_creation+ is +false+.
+    #
     # page_orientation::
-    #     Specifies the orientation of the page, either +:portrait+ or +:landscape+. Only used if
-    #     +page_size+ is one of the predefined page sizes.
+    #     Specifies the orientation of the page, either +:portrait+ or +:landscape+, if +page_size+
+    #     is one of the predefined page sizes.
+    #
+    #     Only used if +skip_page_creation+ is +false+.
     #
     # margin::
     #     The margin to use. See HexaPDF::Layout::Style::Quad#set for possible values.
     #
+    #     Only used if +skip_page_creation+ is +false+.
+    #
     # Example:
     #
-    #   composer = HexaPDF::Composer.new            # uses the default values
+    #   # Uses the default values
+    #   composer = HexaPDF::Composer.new
     #
     #   HexaPDF::Composer.new(page_size: :Letter, margin: 72) do |composer|
     #     #...
     #   end
     #
     #   HexaPDF::Composer.new(skip_page_creation: true) do |composer|
-    #     page_template = lambda {|canvas, style| style.create_frame(canvas.context, 36) }
-    #     page_style(:default, template: page_template)
-    #     new_page
+    #     composer.page_style(:default) do |canvas, style|
+    #       style.frame = style.create_frame(canvas.context, 36)
+    #     end
+    #     composer.new_page
     #     # ...
     #   end
     def initialize(skip_page_creation: false, page_size: :A4, page_orientation: :portrait,
                    margin: 36) #:yields: composer
       @document = HexaPDF::Document.new
       @page_styles = {}
-      @page_style = :default
+      @next_page_style = :default
       unless skip_page_creation
         page_style(:default, page_size: page_size, orientation: page_orientation) do |canvas, style|
           style.frame = style.create_frame(canvas.context, margin)
@@ -155,41 +172,61 @@ module HexaPDF
 
     # Creates a new page, making it the current one.
     #
-    # The page style to use for the new page can be set via the +style+ argument. If not provided,
-    # the currently set page style is used.
+    # The page style (see #page_style) to use for the new page can be set via the +style+ argument.
+    # If not provided, the currently set page style is used (:default is the initial value for
+    # @next_page_style).
     #
-    # The used page style determines the page style that should be used for the following new pages.
-    # If this information is not provided, the used page style is used again.
+    # The applied page style determines the page style that should be used for the following new
+    # pages (see Layout::PageStyle#next_style). If this information is not provided by the applied
+    # page style, that page style is used again.
     #
     # Examples:
     #
-    #   composer.page_style(:cover, page_size: :A4).next_style = :content
+    #   # Define two page styles
+    #   composer.page_style(:cover, page_size: :A4, next_style: :content)
     #   composer.page_style(:content, page_size: :A4)
+    #
     #   composer.new_page(:cover)           # uses the :cover style, set next style to :content
     #   composer.new_page                   # uses the :content style, next style again :content
-    def new_page(style = @page_style)
+    def new_page(style = @next_page_style)
       page_style = @page_styles.fetch(style) do |key|
         raise ArgumentError, "Page style #{key} has not been defined"
       end
       @page = @document.pages.add(page_style.create_page(@document))
       @canvas = @page.canvas
       @frame = page_style.frame
-      @page_style = page_style.next_style || style
+      @next_page_style = page_style.next_style || style
     end
 
-    # The x-position of the cursor inside the current frame.
+    # The x-position inside the current frame where the next box (provided it fits) will be placed.
+    #
+    # Example:
+    #
+    #   #>pdf-composer
+    #   composer.text("Hello", position: :float)
+    #   composer.canvas.stroke_color("hp-blue").
+    #     circle(composer.x, composer.y, 0.5).fill.
+    #     circle(composer.x, composer.y, 5).stroke
     def x
       @frame.x
     end
 
-    # The y-position of the cursor inside the current frame.
+    # The y-position inside the current frame.where the next box (provided it fits) will be placed.
+    #
+    # Example:
+    #
+    #   #>pdf-composer
+    #   composer.text("Hello", position: :float)
+    #   composer.canvas.stroke_color("hp-blue").
+    #     circle(composer.x, composer.y, 0.5).fill.
+    #     circle(composer.x, composer.y, 5).stroke
     def y
       @frame.y
     end
 
-    # Writes the PDF document to the given output.
+    # Writes the created PDF document to the given output.
     #
-    # See Document#write for details.
+    # See HexaPDF::Document#write for details.
     def write(output, optimize: true, **options)
       @document.write(output, optimize: optimize, **options)
     end
@@ -201,6 +238,8 @@ module HexaPDF
     # Creates or updates the HexaPDF::Layout::Style object called +name+ with the given property
     # values and returns it.
     #
+    # If neither +base+ nor any style properties are specified, the style +name+ is just returned.
+    #
     # See HexaPDF::Document::Layout#style for details; this method is just a thin wrapper around
     # that method.
     #
@@ -225,15 +264,15 @@ module HexaPDF
     # +nil+ is returned.
     #
     # If one or more page style attributes are given, a new HexaPDF::Layout::PageStyle object with
-    # those attribute values is created, stored under +name+ and returned. If a block is provided,
-    # it is used to define the page template.
+    # those attribute values is created, stored under +name+ and returned. Additionally, if a block
+    # is provided, it is used to define the page template.
     #
     # Example:
     #
     #   composer.page_style(:default)
     #   composer.page_style(:cover, page_size: :A4) do |canvas, style|
     #     page_box = canvas.context.box
-    #     canvas.fill_color("fd0") do
+    #     canvas.fill_color("green") do
     #       canvas.rectangle(0, 0, page_box.width, page_box.height).
     #         fill
     #     end
@@ -251,9 +290,9 @@ module HexaPDF
 
     # Draws the given text at the current position into the current frame.
     #
-    # The text will be positioned at the current position if possible. Otherwise the next best
-    # position is used. If the text doesn't fit onto the current page or only partially, new pages
-    # are created automatically.
+    # The text will be positioned at the current position (see #x and #y) if possible. Otherwise the
+    # next best position is used. If the text doesn't fit onto the current page or only partially,
+    # one or more new pages are created automatically.
     #
     # This method is of the two main methods for creating text boxes, the other being
     # #formatted_text. It uses HexaPDF::Document::Layout#text_box behind the scenes to create the
@@ -264,18 +303,21 @@ module HexaPDF
     # Examples:
     #
     #   #>pdf-composer
-    #   composer.text("Test " * 15)
+    #   composer.text("Test it now " * 15)
     #   composer.text("Now " * 7, width: 100)
-    #   composer.text("Another test", font_size: 15, fill_color: "green")
+    #   composer.text("Another test", font_size: 15, fill_color: "hp-blue")
     #   composer.text("Different box style", fill_color: 'white', box_style: {
     #     underlays: [->(c, b) { c.rectangle(0, 0, b.content_width, b.content_height).fill }]
     #   })
+    #
+    # See: #formatted_text, HexaPDF::Layout::TextBox, HexaPDF::Layout::TextFragment
     def text(str, width: 0, height: 0, style: nil, box_style: nil, **style_properties)
       draw_box(@document.layout.text_box(str, width: width, height: height, style: style,
                                          box_style: box_style, **style_properties))
     end
 
-    # Draws text like #text but allows parts of the text to be formatted differently.
+    # Draws text like #text but allows parts of the text to be formatted differently and
+    # interspersing with inline boxes.
     #
     # It uses HexaPDF::Document::Layout#formatted_text_box behind the scenes to create the
     # HexaPDF::Layout::TextBox that does the actual work. See that method for details on the
@@ -285,10 +327,13 @@ module HexaPDF
     #
     #   #>pdf-composer
     #   composer.formatted_text(["Some string"])
-    #   composer.formatted_text(["Some ", {text: "string", fill_color: 128}])
+    #   composer.formatted_text(["Some ", {text: "string", fill_color: "hp-orange"}])
     #   composer.formatted_text(["Some ", {link: "https://example.com",
-    #                                      fill_color: 'blue', text: "Example"}])
+    #                                      fill_color: 'hp-blue', text: "Example"}])
     #   composer.formatted_text(["Some ", {text: "string", style: {font_size: 20}}])
+    #   block = lambda {|list| list.text("First item"); list.text("Second item") }
+    #   composer.formatted_text(["Some ", {box: :list, width: 50,
+    #                                      valign: :bottom, block: block}])
     #
     # See: #text, HexaPDF::Layout::TextBox, HexaPDF::Layout::TextFragment
     def formatted_text(data, width: 0, height: 0, style: nil, box_style: nil, **style_properties)
@@ -296,7 +341,7 @@ module HexaPDF
                                                    box_style: box_style, **style_properties))
     end
 
-    # Draws the given image at the current position.
+    # Draws the given image at the current position (see #x and #y).
     #
     # It uses HexaPDF::Document::Layout#image_box behind the scenes to create the
     # HexaPDF::Layout::ImageBox that does the actual work. See that method for details on the
@@ -314,7 +359,7 @@ module HexaPDF
                                           style: style, **style_properties))
     end
 
-    # Draws the named box at the current position.
+    # Draws the named box at the current position (see #x and #y).
     #
     # It uses HexaPDF::Document::Layout#box behind the scenes to create the named box. See that
     # method for details on the arguments.
@@ -331,11 +376,19 @@ module HexaPDF
 
     # Draws any custom box that can be created using HexaPDF::Document::Layout.
     #
+    # This includes all named boxes defined in the 'layout.boxes.map' configuration option.
+    #
     # Examples:
     #
     #   #>pdf-composer
-    #   composer.lorem_ipsum
-    #   composer.column {|column| column.lorem_ipsum }
+    #   composer.lorem_ipsum(sentences: 1, margin: [0, 0, 5])
+    #   composer.list(item_spacing: 2) do |list|
+    #     composer.document.config['layout.boxes.map'].each do |name, klass|
+    #       list.formatted_text([{text: name.to_s, fill_color: "hp-blue-dark"}, "\n#{klass}"])
+    #     end
+    #   end
+    #
+    # See: HexaPDF::Document::Layout#box
     def method_missing(name, *args, **kwargs, &block)
       if @document.layout.box_creation_method?(name)
         draw_box(@document.layout.send(name, *args, **kwargs, &block))
@@ -344,12 +397,11 @@ module HexaPDF
       end
     end
 
-    # :nodoc:
-    def respond_to_missing?(name, _private)
+    def respond_to_missing?(name, _private) # :nodoc:
       @document.layout.box_creation_method?(name) || super
     end
 
-    # Draws the given HexaPDF::Layout::Box.
+    # Draws the given HexaPDF::Layout::Box and returns the last drawn box.
     #
     # The box is drawn into the current frame if possible. If it doesn't fit, the box is split. If
     # it still doesn't fit, a new region of the frame is determined and then the process starts
@@ -381,6 +433,7 @@ module HexaPDF
           end
         end
       end
+      box
     end
 
     # Creates a stamp (Form XObject) which can be used like an image multiple times on a single page
@@ -393,7 +446,7 @@ module HexaPDF
     #
     #   #>pdf-composer
     #   stamp = composer.create_stamp(50, 50) do |canvas|
-    #     canvas.fill_color("red").line_width(5).
+    #     canvas.fill_color("hp-blue").line_width(5).
     #       rectangle(10, 10, 30, 30).fill_stroke
     #   end
     #   composer.image(stamp, width: 20, height: 20)