hexapdf 0.34.1 → 0.35.0

data/lib/hexapdf/content/canvas.rb

@@ -36,6 +36,7 @@
 
 require 'hexapdf/content/graphics_state'
 require 'hexapdf/content/operator'
+require 'hexapdf/content/canvas_composer'
 require 'hexapdf/serializer'
 require 'hexapdf/utils/math_helpers'
 require 'hexapdf/utils/graphics_helpers'
@@ -1450,6 +1451,43 @@ module HexaPDF
         self
       end
 
+      # :call-seq:
+      #   canvas.form {|form_canvas| block }                  => form
+      #   canvas.form(width, height) {|form_canvas| block }   => form
+      #
+      # Creates a reusable Form XObject, yields its canvas and then returns it.
+      #
+      # If no arguments are provided, the bounding box of the form is the same as that of the
+      # context object of this canvas. Otherwise you need to provide the +width+ and +height+ for
+      # the form.
+      #
+      # Once the form has been created, it can be used like an image and drawn mulitple times with
+      # the #xobject method. Note that the created form object is independent of this canvas and its
+      # context object. This means it can also be used with other canvases.
+      #
+      # Examples:
+      #
+      #   #>pdf
+      #   form = canvas.form do |form_canvas|
+      #     form_canvas.fill_color("hp-blue").line_width(5).
+      #       rectangle(10, 10, 80, 80).fill_stroke
+      #   end
+      #   canvas.xobject(form, at: [0, 0])
+      #   canvas.xobject(form, width: 50, at: [100, 100])
+      #
+      # See: HexaPDF::Type::Form
+      def form(width = nil, height = nil) # :yield: canvas
+        obj = if width && height
+                context.document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height]})
+              elsif width || height
+                raise ArgumentError, "Both arguments width and height need to be provided"
+              else
+                context.document.add({Type: :XObject, Subtype: :Form, BBox: context.box.value.dup})
+              end
+        yield(obj.canvas) if block_given?
+        obj
+      end
+
       # :call-seq:
       #   canvas.graphic_object(obj, **options)      => obj
       #   canvas.graphic_object(name, **options)     => graphic_object
@@ -2535,6 +2573,31 @@ module HexaPDF
       # See: PDF2.0 s8.11
       alias :end_optional_content :end_marked_content_sequence
 
+      # :call-seq:
+      #   canvas.composer(margin: 0) {|composer| block }  -> composer
+      #
+      # Creates a CanvasComposer object for composing content using high-level document layout
+      # features, yields it, if a block is given, and returns it.
+      #
+      # The +margin+ can be any value allowed by HexaPDF::Layout::Style::Quad#set and defines the
+      # margin that should not be used during composition. For the remaining area of the canvas a
+      # frame object will be created.
+      #
+      # Examples:
+      #
+      #   #>pdf
+      #   canvas.composer(margin: [10, 30]) do |composer|
+      #     composer.image(machu_picchu, height: 30, position: :float)
+      #     composer.lorem_ipsum(position: :flow)
+      #   end
+      #
+      # See: CanvasComposer, HexaPDF::Document::Layout
+      def composer(margin: 0)
+        composer = CanvasComposer.new(self, margin: margin)
+        yield(composer) if block_given?
+        composer
+      end
+
       # Creates and returns a color object from the given color specification. See #stroke_color for
       # details on the possible color specifications.
       #

data/lib/hexapdf/content/canvas_composer.rb

@@ -0,0 +1,142 @@
+# -*- 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-2023 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/layout'
+
+module HexaPDF
+  module Content
+
+    # The CanvasComposer class allows using the document layout functionality for a single canvas.
+    # It works in a similar manner as the HexaPDF::Composer class.
+    #
+    # See: HexaPDF::Composer, HexaPDF::Document::Layout
+    class CanvasComposer
+
+      # The associated canvas.
+      attr_reader :canvas
+
+      # The associated HexaPDF::Document instance.
+      attr_reader :document
+
+      # The HexaPDF::Layout::Frame instance into which the boxes are laid out.
+      attr_reader :frame
+
+      # Creates a new CanvasComposer instance for the given +canvas+.
+      #
+      # The +margin+ can be any value allowed by HexaPDF::Layout::Style::Quad#set and defines the
+      # margin that should not be used during composition. For the remaining area of the canvas a
+      # frame object will be created.
+      def initialize(canvas, margin: 0)
+        @canvas = canvas
+        @document = @canvas.context.document
+
+        box = @canvas.context.box
+        margin = Layout::Style::Quad.new(margin)
+        @frame = Layout::Frame.new(box.left + margin.left,
+                                   box.bottom + margin.bottom,
+                                   box.width - margin.left - margin.right,
+                                   box.height - margin.bottom - margin.top,
+                                   context: @canvas.context)
+      end
+
+      # Invokes HexaPDF::Document::Layout#style with the given arguments to create/update and return
+      # a style object.
+      def style(name, base: :base, **properties)
+        @document.layout.style(name, base: base, **properties)
+      end
+
+      # Draws the given HexaPDF::Layout::Box and returns the last drawn box.
+      #
+      # The box is drawn into the frame. 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 again.
+      #
+      # If none or only some parts of the box fit into the frame, an exception is thrown.
+      def draw_box(box)
+        while true
+          result = @frame.fit(box)
+          if result.success?
+            @frame.draw(@canvas, result)
+            break
+          elsif @frame.full?
+            raise HexaPDF::Error, "Frame for canvas composer is full and box doesn't fit anymore"
+          else
+            draw_box, box = @frame.split(result)
+            if draw_box
+              @frame.draw(@canvas, result)
+            elsif !@frame.find_next_region
+              raise HexaPDF::Error, "Frame for canvas composer is full and box doesn't fit anymore"
+            end
+          end
+        end
+        box
+      end
+
+      # Draws any box that can be created using HexaPDF::Document::Layout.
+      #
+      # This includes all named boxes defined in the 'layout.boxes.map' configuration option.
+      #
+      # Examples:
+      #
+      #   #>pdf
+      #   canvas.composer(margin: 10) do |composer|
+      #     composer.text("Some text", position: :float)
+      #     composer.image(machu_picchu, height: 30, align: :right)
+      #     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"},
+      #                              {text: "\n#{klass}", font_size: 7}])
+      #       end
+      #     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))
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, _private) # :nodoc:
+        @document.layout.box_creation_method?(name) || super
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/content.rb

@@ -51,6 +51,7 @@ module HexaPDF
     autoload(:Processor, 'hexapdf/content/processor')
     autoload(:ColorSpace, 'hexapdf/content/color_space')
     autoload(:Operator, 'hexapdf/content/operator')
+    autoload(:CanvasComposer, 'hexapdf/content/canvas_composer')
 
   end
 

data/lib/hexapdf/dictionary.rb

@@ -257,14 +257,25 @@ module HexaPDF
       end
     end
 
+    # Iterates over all currently set entries and all fields that are required.
+    def each_set_key_or_required_field #:yields: name, field
+      value.keys.each {|name| yield(name, self.class.field(name)) }
+      self.class.each_field do |name, field|
+        yield(name, field) if field.required? && !value.key?(name)
+      end
+    end
+
     # Performs validation tasks based on the currently set keys and defined fields.
     def perform_validation(&block)
       super
-      self.class.each_field do |name, field|
-        next unless field.required? || value.key?(name)
-
+      each_set_key_or_required_field do |name, field|
         obj = key?(name) ? self[name] : nil
 
+        validate_nested(obj, &block)
+
+        # The checks below need associated field information
+        next unless field
+
         # Check that required fields are set
         if field.required? && obj.nil?
           yield("Required field #{name} is not set", field.default?)

data/lib/hexapdf/document/layout.rb

@@ -260,6 +260,28 @@ module HexaPDF
                                      style: retrieve_style(style), **box_options)
       end
 
+      # Creates an array of HexaPDF::Layout::TextFragment objects for the given +text+.
+      #
+      # This method uses the configuration option 'font.on_invalid_glyph' to map Unicode characters
+      # without a valid glyph in the given font to zero, one or more glyphs in a fallback font.
+      #
+      # +style+, +style_properties+::
+      #     The text is styled using the given +style+. This can either be a style name set via
+      #     #style or anything Layout::Style::create accepts. If any additional +style_properties+
+      #     are specified, the style is duplicated and the additional styles are applied.
+      #
+      # +properties+::
+      #     This can be used to set custom properties on the created text fragments. See
+      #     Layout::Box#properties for details and usage.
+      def text_fragments(text, style: nil, properties: nil, **style_properties)
+        style = retrieve_style(style, style_properties)
+        fragments = HexaPDF::Layout::TextFragment.create_with_fallback_glyphs(
+          text, style, &@document.config['font.on_invalid_glyph']
+        )
+        fragments.each {|f| f.properties.update(properties) } if properties
+        fragments
+      end
+
       # Creates a HexaPDF::Layout::TextBox for the given text.
       #
       # This method is of the two main methods for creating text boxes, the other being
@@ -300,7 +322,7 @@ module HexaPDF
                    **style_properties)
         style = retrieve_style(style, style_properties)
         box_style = (box_style ? retrieve_style(box_style) : style)
-        box_class_for_name(:text).new(items: [HexaPDF::Layout::TextFragment.create(text, style)],
+        box_class_for_name(:text).new(items: text_fragments(text, style: style),
                                       width: width, height: height, properties: properties,
                                       style: box_style)
       end
@@ -319,11 +341,11 @@ module HexaPDF
       # * Hashes can contain any style properties and the following special keys:
       #
       #   text:: The text to be formatted. If this is set and :box is not, the hash will be
-      #          transformed into a text fragment.
+      #          transformed into text fragments.
       #
       #   link:: A URL that should be linked to. If no text is provided but a link, the link is used
-      #          for the text. If this is set and :box is not, the hash will be transformed into a
-      #          text fragment with an appropriate link overlay.
+      #          for the text. If this is set and :box is not, the hash will be transformed into
+      #          text fragments with an appropriate link overlay.
       #
       #   style:: The style to use as base style instead of the style created from the +style+ and
       #           +style_properties+ arguments. This can either be a style name set via #style or
@@ -334,6 +356,8 @@ module HexaPDF
       #
       #           The final style is used for a created text fragment.
       #
+      #   properties:: The custom properties that should be set on the created text fragments.
+      #
       #   box:: An inline box to be used. If this is set, the hash will be transformed into an
       #         inline box.
       #
@@ -379,26 +403,24 @@ module HexaPDF
                              **style_properties)
         style = retrieve_style(style, style_properties)
         box_style = (box_style ? retrieve_style(box_style) : style)
-        data.map! do |item|
+        data = data.inject([]) do |result, item|
           case item
           when String
-            HexaPDF::Layout::TextFragment.create(item, style)
+            result.concat(text_fragments(item, style: style))
           when Hash
             if (args = item.delete(:box))
               block = item.delete(:block)
-              inline_box(*args, **item, &block)
+              result << inline_box(*args, **item, &block)
             else
               link = item.delete(:link)
               (item[:overlays] ||= []) << [:link, {uri: link}] if link
               text = item.delete(:text) || link || ""
-              properties = item.delete(:properties)
+              item_properties = item.delete(:properties)
               frag_style = retrieve_style(item.delete(:style) || style, item)
-              fragment = HexaPDF::Layout::TextFragment.create(text, frag_style)
-              fragment.properties.update(properties) if properties
-              fragment
+              result.concat(text_fragments(text, style: frag_style, properties: item_properties))
             end
           when HexaPDF::Layout::InlineBox
-            item
+            result << item
           else
             raise ArgumentError, "Invalid item of class #{item.class} in data array"
           end
@@ -506,7 +528,7 @@ module HexaPDF
       #     # row 0 has a grey background and bold text
       #     args[0] = {font: ['Helvetica', variant: :bold], cell: {background_color: 'eee'}}
       #     # text in last column is right aligned
-      #     args[0..-1, -1] = {align: :right}
+      #     args[0..-1, -1] = {text_align: :right}
       #   end
       #
       # See: HexaPDF::Layout::TableBox

data/lib/hexapdf/encryption/standard_security_handler.rb

@@ -250,6 +250,18 @@ module HexaPDF
         end
       end
 
+      # Returns the type of password used for decrypting the PDF document.
+      #
+      # The return value is one of the following:
+      #
+      # :none:: No password was needed for decryption.
+      # :user:: The provided user password was used for decryption.
+      # :owner:: The provided owner password was used for decryption.
+      # :unknown:: The document was not decrypted, only encrypted.
+      def decryption_password_type
+        @decryption_password_type || :unknown
+      end
+
       def decrypt(obj) #:nodoc:
         if dict[:V] >= 4 && obj.type == :Metadata && obj[:Subtype] == :XML && !dict[:EncryptMetadata]
           obj
@@ -345,10 +357,13 @@ module HexaPDF
         password = prepare_password(password)
 
         if user_password_valid?(prepare_password(''))
+          @decryption_password_type = :none
           encryption_key = compute_user_encryption_key(prepare_password(''))
         elsif user_password_valid?(password)
+          @decryption_password_type = :user
           encryption_key = compute_user_encryption_key(password)
         elsif owner_password_valid?(password)
+          @decryption_password_type = :owner
           encryption_key = compute_owner_encryption_key(password)
         else
           raise HexaPDF::EncryptionError, "Invalid password specified"

data/lib/hexapdf/error.rb

@@ -94,7 +94,8 @@ module HexaPDF
     end
 
     def message # :nodoc:
-      "No glyph for #{glyph.str.inspect} in font '#{glyph.font.full_name}' found. \n\n" \
+      "No glyph for #{glyph.str.inspect} in font '#{glyph.font_wrapper.wrapped_font.full_name}' " \
+        "found. \n\n" \
         "Use the configuration option 'font.on_missing_glyph' to customize missing glyph handling."
     end
 

data/lib/hexapdf/font/invalid_glyph.rb

@@ -34,6 +34,8 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 
+require 'set'
+
 module HexaPDF
   module Font
 
@@ -41,21 +43,21 @@ module HexaPDF
     # font.
     class InvalidGlyph
 
-      # The associated font object.
-      attr_reader :font
+      # The associated font wrapper object, either a Type1Wrapper or a TrueTypeWrapper.
+      attr_reader :font_wrapper
 
       # The string that could not be represented as a glyph.
       attr_reader :str
 
       # Creates a new Glyph object.
-      def initialize(font, str)
-        @font = font
+      def initialize(font_wrapper, str)
+        @font_wrapper = font_wrapper
         @str = str
       end
 
       # Returns the appropriate missing glyph id based on the used font.
       def id
-        @font.missing_glyph_id
+        @font_wrapper.wrapped_font.missing_glyph_id
       end
       alias name id
 
@@ -73,9 +75,23 @@ module HexaPDF
         false
       end
 
+      # Returns +false+ since this is an invalid glyph.
+      def valid?
+        false
+      end
+
+      # Set of codepoints for text control characters, like tabulator, line separators, non-breaking
+      # space etc.
+      CONTROL_CHARS = Set.new([9, 10, 11, 12, 13, 133, 8232, 8233, 8203, 173, 160]) #:nodoc:
+
+      # Returns +true+ if this glyph represents a control character like tabulator or newline.
+      def control_char?
+        CONTROL_CHARS.include?(str.ord)
+      end
+
       #:nodoc:
       def inspect
-        "#<#{self.class.name} font=#{@font.full_name.inspect} id=#{id} #{@str.inspect}>"
+        "#<#{self.class.name} font=#{@font_wrapper.wrapped_font.full_name.inspect} id=#{id} #{@str.inspect}>"
       end
 
     end

data/lib/hexapdf/font/true_type_wrapper.rb

@@ -59,8 +59,8 @@ module HexaPDF
       # Represents a single glyph of the wrapped font.
       class Glyph
 
-        # The associated font object.
-        attr_reader :font
+        # The associated TrueTypeWrapper object.
+        attr_reader :font_wrapper
 
         # The glyph ID.
         attr_reader :id
@@ -69,35 +69,40 @@ module HexaPDF
         attr_reader :str
 
         # Creates a new Glyph object.
-        def initialize(font, id, str)
-          @font = font
+        def initialize(font_wrapper, id, str)
+          @font_wrapper = font_wrapper
           @id = id
           @str = str
         end
 
         # Returns the glyph's minimum x coordinate.
         def x_min
-          @x_min ||= @font[:glyf][id].x_min * 1000.0 / @font[:head].units_per_em
+          @x_min ||= @font_wrapper.wrapped_font[:glyf][id].x_min * 1000.0 /
+            @font_wrapper.wrapped_font[:head].units_per_em
         end
 
         # Returns the glyph's maximum x coordinate.
         def x_max
-          @x_max ||= @font[:glyf][id].x_max * 1000.0 / @font[:head].units_per_em
+          @x_max ||= @font_wrapper.wrapped_font[:glyf][id].x_max * 1000.0 /
+            @font_wrapper.wrapped_font[:head].units_per_em
         end
 
         # Returns the glyph's minimum y coordinate.
         def y_min
-          @y_min ||= @font[:glyf][id].y_min * 1000.0 / @font[:head].units_per_em
+          @y_min ||= @font_wrapper.wrapped_font[:glyf][id].y_min * 1000.0 /
+            @font_wrapper.wrapped_font[:head].units_per_em
         end
 
         # Returns the glyph's maximum y coordinate.
         def y_max
-          @y_max ||= @font[:glyf][id].y_max * 1000.0 / @font[:head].units_per_em
+          @y_max ||= @font_wrapper.wrapped_font[:glyf][id].y_max * 1000.0 /
+            @font_wrapper.wrapped_font[:head].units_per_em
         end
 
         # Returns the width of the glyph.
         def width
-          @width ||= @font[:hmtx][id].advance_width * 1000.0 / @font[:head].units_per_em
+          @width ||= @font_wrapper.wrapped_font[:hmtx][id].advance_width * 1000.0 /
+            @font_wrapper.wrapped_font[:head].units_per_em
         end
 
         # Returns +false+ since the word spacing parameter is never applied for multibyte font
@@ -106,9 +111,14 @@ module HexaPDF
           false
         end
 
+        # Returns +true+ since this is a valid glyph.
+        def valid?
+          true
+        end
+
         #:nodoc:
         def inspect
-          "#<#{self.class.name} font=#{@font.full_name.inspect} id=#{id} #{str.inspect}>"
+          "#<#{self.class.name} font=#{@font_wrapper.wrapped_font.full_name.inspect} id=#{id} #{str.inspect}>"
         end
 
       end
@@ -154,6 +164,16 @@ module HexaPDF
         @scaling_factor ||= 1000.0 / @wrapped_font[:head].units_per_em
       end
 
+      # Returns +true+ if the font contains bold glyphs.
+      def bold?
+        @wrapped_font.weight > 500
+      end
+
+      # Returns +true+ if the font contains glyphs with an incline (italic or slant).
+      def italic?
+        @wrapped_font.italic_angle.to_i != 0
+      end
+
       # Returns +true+ if the wrapped TrueType font will be subset.
       def subset?
         !@subsetter.nil?
@@ -168,7 +188,7 @@ module HexaPDF
       def glyph(id, str = nil)
         @id_to_glyph[id] ||=
           if id >= 0 && id < @wrapped_font[:maxp].num_glyphs
-            Glyph.new(@wrapped_font, id, str || (+'' << (@cmap.gid_to_code(id) || 0xFFFD)))
+            Glyph.new(self, id, str || (+'' << (@cmap.gid_to_code(id) || 0xFFFD)))
           else
             @pdf_object.document.config['font.on_missing_glyph'].call("\u{FFFD}", self)
           end
@@ -183,19 +203,27 @@ module HexaPDF
         if id < 0 || id >= @wrapped_font[:maxp].num_glyphs
           raise HexaPDF::Error, "Glyph ID #{id} is invalid for font '#{@wrapped_font.full_name}'"
         end
-        Glyph.new(@wrapped_font, id, string)
+        Glyph.new(self, id, string)
       end
 
       # Returns an array of glyph objects representing the characters in the UTF-8 encoded string.
+      #
+      # See #decode_codepoint for details.
       def decode_utf8(str)
-        str.codepoints.map! do |c|
-          @codepoint_to_glyph[c] ||=
-            if (gid = @cmap[c])
-              glyph(gid, +'' << c)
-            else
-              @pdf_object.document.config['font.on_missing_glyph'].call(+'' << c, self)
-            end
-        end
+        str.codepoints.map! {|c| @codepoint_to_glyph[c] || decode_codepoint(c) }
+      end
+
+      # Returns a glyph object for the given Unicode codepoint.
+      #
+      # The configuration option 'font.on_missing_glyph' is invoked if no glyph for a given
+      # codepoint is available.
+      def decode_codepoint(codepoint)
+        @codepoint_to_glyph[codepoint] ||=
+          if (gid = @cmap[codepoint])
+            glyph(gid, +'' << codepoint)
+          else
+            @pdf_object.document.config['font.on_missing_glyph'].call(+'' << codepoint, self)
+          end
       end
 
       # Encodes the glyph and returns the code string.