hexapdf 0.46.0 → 1.6.0

data/lib/hexapdf/digital_signature/signing/timestamp_handler.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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
@@ -53,8 +53,8 @@ module HexaPDF
       # == Usage
       #
       # It is necessary to provide at least the URL of the timestamp authority server (TSA) via
-      # #tsa_url, everything else is optional and uses default values. The TSA server must not use
-      # authentication to be usable.
+      # #tsa_url, everything else is optional and uses default values. The TSA server can optionally
+      # use HTTP basic authentication.
       #
       # Example:
       #
@@ -66,6 +66,18 @@ module HexaPDF
         # This value is required.
         attr_accessor :tsa_url
 
+        # The username for basic authentication to the TSA server.
+        #
+        # If the username is not set, no basic authentication is done.
+        #
+        # See: #tsa_password
+        attr_accessor :tsa_username
+
+        # The password for basic authentication to the TSA server.
+        #
+        # See: #tsa_username
+        attr_accessor :tsa_password
+
         # The hash algorithm to use for timestamping. Defaults to SHA512.
         attr_accessor :tsa_hash_algorithm
 
@@ -127,8 +139,14 @@ module HexaPDF
           req.message_imprint = digest.digest
           req.policy_id = tsa_policy_id if tsa_policy_id
 
-          http_response = Net::HTTP.post(URI(tsa_url), req.to_der,
-                                         'content-type' => 'application/timestamp-query')
+          url = URI(tsa_url)
+          http_request = Net::HTTP::Post.new(url, 'Content-Type' => 'application/timestamp-query')
+          http_request.body = req.to_der
+          http_request.basic_auth(tsa_username, tsa_password) if tsa_username
+          http_response = Net::HTTP.start(url.hostname, url.port, use_ssl: (url.scheme == 'https')) do |http|
+            http.request(http_request)
+          end
+
           if http_response.kind_of?(Net::HTTPOK)
             response = OpenSSL::Timestamp::Response.new(http_response.body)
             if response.status == 0
@@ -136,6 +154,8 @@ module HexaPDF
             else
               raise HexaPDF::Error, "Timestamp token could not be created: #{response.failure_info}"
             end
+          elsif http_response.kind_of?(Net::HTTPUnauthorized)
+            raise HexaPDF::Error, "Basic authentication to the server failed: #{http_response.body}"
           else
             raise HexaPDF::Error, "Invalid TSA server response: #{http_response.body}"
           end

data/lib/hexapdf/digital_signature/signing.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/digital_signature/verification_result.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/digital_signature.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/document/annotations.rb

@@ -0,0 +1,220 @@
+# -*- 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-2025 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/dictionary'
+require 'hexapdf/error'
+
+module HexaPDF
+  class Document
+
+    # This class provides methods for creating and managing the annotations of a PDF file.
+    #
+    # An annotation is an object that can be added to a certain location on a page, provides a
+    # visual appearance and allows for interaction with the user via keyboard and mouse.
+    #
+    # == Usage
+    #
+    # To create an annotation either call the general #create method or a specific creation method
+    # for an annotation type. After the annotation has been created customize it using the
+    # convenience methods on the annotation object. The last step should be the call to
+    # +regenerate_appearance+ so that the appearance is generated.
+    #
+    # See: PDF2.0 s12.5
+    class Annotations
+
+      include Enumerable
+
+      # Creates a new Annotations object for the given PDF document.
+      def initialize(document)
+        @document = document
+      end
+
+      # :call-seq:
+      #   annotations.create(type, page, **options)      -> annotation
+      #
+      # Creates a new annotation object with the given +type+ and +page+ by calling the respective
+      # +create_type+ method.
+      #
+      # The +options+ are passed on the specific annotation creation method.
+      def create(type, page, *args, **options)
+        method_name = "create_#{type}"
+        unless respond_to?(method_name)
+          raise ArgumentError, "Invalid type specified"
+        end
+        send("create_#{type}", page, *args, **options)
+      end
+
+      # :call-seq:
+      #   annotations.create_line(page, start_point:, end_point:)  -> annotation
+      #
+      # Creates a line annotation from +start_point+ to +end_point+ on the given page and returns
+      # it.
+      #
+      # The line uses a black color and a width of 1pt. It can be further styled using the
+      # convenience methods on the returned annotation object.
+      #
+      # Example:
+      #
+      #   doc.annotations.create_line(doc.pages[0], start_point: [100, 100], end_point: [130, 180]).
+      #     border_style(color: "blue", width: 2).
+      #     leader_line_length(10).
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Line
+      def create_line(page, start_point:, end_point:)
+        create_and_add_to_page(:Line, page).
+          line(*start_point, *end_point).
+          border_style(color: 0, width: 1)
+      end
+
+      # :call-seq:
+      #   annotations.create_rectangle(page, x, y, width, height)  -> annotation
+      #
+      # Creates a rectangle (called "square" in the PDF specification) annotation with the
+      # lower-left corner at (+x+, +y+) and the given +width+ and +height+.
+      #
+      # The rectangle uses a black stroke color, no interior color and a line width of 1pt by
+      # default. It can be further styled using the convenience methods on the returned annotation
+      # object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_rectangle(doc.pages[0], 20, 20, 20, 60).
+      #     regenerate_appearance
+      #
+      #   doc.annotations.create_rectangle(doc.pages[0], 60, 20, 20, 60).
+      #     border_style(color: "hp-blue", width: 2).
+      #     interior_color("hp-orange").
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Square
+      def create_rectangle(page, x, y, w, h)
+        annot = create_and_add_to_page(:Square, page)
+        annot[:Rect] = [x, y, x + w, y + h]
+        annot.border_style(color: 0, width: 1)
+        annot
+      end
+
+      # :call-seq:
+      #   annotations.create_ellipse(page, cx, cy, a:, b:)  -> annotation
+      #
+      # Creates an ellipse (called "circle" in the PDF specification) annotation with the center
+      # point at (+cx+, +cy+), the semi-major axis +a+ and the semi-minor axis +b+.
+      #
+      # The ellipse uses a black stroke color, no interior color and a line width of 1pt by
+      # default. It can be further styled using the convenience methods on the returned annotation
+      # object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_ellipse(doc.pages[0], 30, 50, a: 15, b: 20).
+      #     regenerate_appearance
+      #
+      #   doc.annotations.create_ellipse(doc.pages[0], 70, 50, a: 15, b: 20).
+      #     border_style(color: "hp-blue", width: 2).
+      #     interior_color("hp-orange").
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Circle
+      def create_ellipse(page, x, y, a:, b:)
+        annot = create_and_add_to_page(:Circle, page)
+        annot[:Rect] = [x - a, y - b, x + a, y + b]
+        annot.border_style(color: 0, width: 1)
+        annot
+      end
+
+      # :call-seq:
+      #   annotations.create_polyline(page, *points)  -> annotation
+      #
+      # Creates a polyline annotation for the given +points+ (alternating horizontal and vertical
+      # coordinates) on the given page and returns it.
+      #
+      # The polyline uses a black color and a width of 1pt. It can be further styled using the
+      # convenience methods on the returned annotation object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_polyline(doc.pages[0], 20, 20, 30, 70, 80, 60, 40, 30).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Polyline
+      def create_polyline(page, *points)
+        create_and_add_to_page(:PolyLine, page).
+          vertices(*points).
+          border_style(color: 0, width: 1)
+      end
+
+      # :call-seq:
+      #   annotations.create_polygon(page, *points)  -> annotation
+      #
+      # Creates a polygon annotation for the given +points+ (alternating horizontal and vertical
+      # coordinates) on the given page and returns it.
+      #
+      # The polygon uses a black color and a width of 1pt for the border and no interior color. It
+      # can be further styled using the convenience methods on the returned annotation object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_polygon(doc.pages[0], 20, 20, 30, 70, 80, 60, 40, 30).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     interior_color("hp-orange").
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Polygon
+      def create_polygon(page, *points)
+        create_and_add_to_page(:Polygon, page).
+          vertices(*points).
+          border_style(color: 0, width: 1)
+      end
+
+      private
+
+      # Returns the root of the destinations name tree.
+      def create_and_add_to_page(subtype, page)
+        annot = @document.add({Type: :Annot, Subtype: subtype})
+        (page[:Annots] ||= []) << annot
+        annot
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/document/destinations.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/document/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-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/document/fonts.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/document/images.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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/document/layout.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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
@@ -92,13 +92,23 @@ module HexaPDF
     #
     #     style.font = ['Helvetica', variant: :bold]
     #
-    #   Helvetica in bold could also be set the conventional way:
+    #   Helvetica in bold could also be set in the following ways:
     #
     #     style.font = 'Helvetica bold'
+    #     # or
+    #     style.font_bold = true
+    #     style.font = 'Helvetica'
+    #
+    #   The font_bold and font_italic style properties are always taken into account. For example,
+    #   if the font is set to 'Helvetica italic' and font_bold to +true+, the actual font would be
+    #   the bold _and_ italic Helvetica font.
     #
     #   However, using an array it is also possible to specify other options when setting a font,
     #   like the :subset option.
     #
+    # * It is possible to resolve the font of a style object manually by using the #resolve_font
+    #   method.
+    #
     class Layout
 
       # This class is used when a box can contain child boxes and the creation of such boxes should
@@ -218,6 +228,77 @@ module HexaPDF
         style
       end
 
+      # Returns +true+ if a style with the given +name+ exists, else +false+.
+      #
+      # Example:
+      #
+      #   layout.style(:header, font: 'Helvetica')
+      #   layout.style?(:header)     # => true
+      #   layout.style?(:paragraph)  # => false
+      #
+      # See: #style
+      def style?(name)
+        @styles.key?(name)
+      end
+
+      FONT_BOLD_VARIANT_MAPPER = { #:nodoc:
+        nil => {true => :bold, false: :none},
+        none: {true => :bold, false: :none},
+        bold: {true => :bold, false: :none},
+        italic: {true => :bold_italic, false: :italic},
+        bold_italic: {true => :bold_italic, false: :italic},
+      }
+
+      FONT_ITALIC_VARIANT_MAPPER = { #:nodoc:
+        nil => {true => :italic, false: :none},
+        none: {true => :italic, false: :none},
+        italic: {true => :italic, false: :none},
+        bold: {true => :bold_italic, false: :bold},
+        bold_italic: {true => :bold_italic, false: :bold},
+      }
+
+      # Resolves the font object for the given +style+ and applies the result to it.
+      #
+      # The Layout::Style#font property is the only one without a default value but is needed for
+      # many operations. This method ensures that the +style+ has a valid font object for the font
+      # property by resolving the font name.
+      #
+      # The font object is resolved in the following way:
+      #
+      # * If the font property is not set, the font value of the :base style is used and if that is
+      #   also not set, the 'font.default' configuration value is used.
+      #
+      # * Afterwards, if the font property is a valid font object, nothing needs to be done.
+      #
+      # * Otherwise, if the font property is a single font name or a [font name, options hash]
+      #   array, it is resolved to a font object, also taking the font_bold and font_italic style
+      #   properties into account.
+      #
+      # Example:
+      #
+      #   style = layout.style(:header, font: 'Helvetica')
+      #   style.font                   # => 'Helvetica'
+      #   layout.resolve_font(style)
+      #   style.font                   # => #<HexaPDF::Font::Type1Wrapper>
+      #
+      # See: The "Box Styles" section in Layout for more details.
+      def resolve_font(style)
+        unless style.font?
+          style.font(@styles[:base].font? && @styles[:base].font || @document.config['font.default'])
+        end
+        unless style.font.respond_to?(:pdf_object)
+          name, options = *style.font
+          options ||= {}
+          if style.font_bold?
+            options[:variant] = FONT_BOLD_VARIANT_MAPPER.dig(options[:variant], style.font_bold)
+          end
+          if style.font_italic?
+            options[:variant] = FONT_ITALIC_VARIANT_MAPPER.dig(options[:variant], style.font_italic)
+          end
+          style.font(@document.fonts.add(name, **options))
+        end
+      end
+
       # :call-seq:
       #    layout.styles            -> styles
       #    layout.styles(**mapping)   -> styles
@@ -286,8 +367,9 @@ module HexaPDF
             box_options[:children] = ChildrenCollector.collect(self, &block)
           end
         end
+        style = retrieve_style(style)
         box_class_for_name(name).new(width: width, height: height,
-                                     style: retrieve_style(style), **box_options, &box_block)
+                                     style: style, **style.box_options, **box_options, &box_block)
       end
 
       # Creates an array of HexaPDF::Layout::TextFragment objects for the given +text+.
@@ -354,7 +436,7 @@ module HexaPDF
         box_style = (box_style ? retrieve_style(box_style) : style)
         box_class_for_name(:text).new(items: text_fragments(text, style: style),
                                       width: width, height: height, properties: properties,
-                                      style: box_style)
+                                      style: box_style, **box_style.box_options)
       end
       alias text text_box
 
@@ -457,7 +539,8 @@ module HexaPDF
           end
         end
         box_class_for_name(:text).new(items: data, width: width, height: height,
-                                      properties: properties, style: box_style)
+                                      properties: properties, style: box_style,
+                                      **box_style.box_options)
       end
       alias formatted_text formatted_text_box
 
@@ -479,7 +562,7 @@ module HexaPDF
         style = retrieve_style(style, style_properties)
         image = file.kind_of?(HexaPDF::Stream) ? file : @document.images.add(file)
         box_class_for_name(:image).new(image: image, width: width, height: height,
-                                       properties: properties, style: style)
+                                       properties: properties, style: style, **style.box_options)
       end
       alias image image_box
 
@@ -533,9 +616,10 @@ module HexaPDF
           @argument_infos.each_with_object({}) do |arg_info, result|
             next unless arg_info.rows.include?(row) && arg_info.cols.include?(col)
             if arg_info.args[:cell]
-              arg_info.args[:cell] = (result[:cell] || {}).merge(arg_info.args[:cell])
+              result.update(arg_info.args, cell: (result[:cell] || {}).merge(arg_info.args[:cell]))
+            else
+              result.update(arg_info.args)
             end
-            result.update(arg_info.args)
           end
         end
 
@@ -608,7 +692,8 @@ module HexaPDF
         end
         box_class_for_name(:table).new(cells: cells, column_widths: column_widths, header: header,
                                        footer: footer, cell_style: cell_style, width: width,
-                                       height: height, properties: properties, style: style)
+                                       height: height, properties: properties, style: style,
+                                       **style.box_options)
       end
       alias table table_box
 
@@ -685,13 +770,7 @@ module HexaPDF
         end
         style = HexaPDF::Layout::Style.create(@styles[style] || style || @styles[:base])
         style = style.dup.update(**properties) unless properties.nil? || properties.empty?
-        unless style.font?
-          style.font(@styles[:base].font? && @styles[:base].font || @document.config['font.default'])
-        end
-        unless style.font.respond_to?(:pdf_object)
-          name, options = *style.font
-          style.font(@document.fonts.add(name, **(options || {})))
-        end
+        resolve_font(style)
         style
       end
 

data/lib/hexapdf/document/metadata.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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
@@ -430,8 +430,12 @@ module HexaPDF
         @metadata[ns_dc]['creator'] = info_dict[:Author] if info_dict.key?(:Author)
         @metadata[ns_dc]['description'] = info_dict[:Subject] if info_dict.key?(:Subject)
         @metadata[ns_xmp]['CreatorTool'] = info_dict[:Creator] if info_dict.key?(:Creator)
-        @metadata[ns_xmp]['CreateDate'] = info_dict[:CreationDate] if info_dict.key?(:CreationDate)
-        @metadata[ns_xmp]['ModifyDate'] = info_dict[:ModDate] if info_dict.key?(:ModDate)
+        if info_dict.key?(:CreationDate) && !info_dict[:CreationDate].kind_of?(String)
+          @metadata[ns_xmp]['CreateDate'] = info_dict[:CreationDate]
+        end
+        if info_dict.key?(:ModDate) && !info_dict[:ModDate].kind_of?(String)
+          @metadata[ns_xmp]['ModifyDate'] = info_dict[:ModDate] if info_dict.key?(:ModDate)
+        end
         @metadata[ns_pdf]['Keywords'] = info_dict[:Keywords] if info_dict.key?(:Keywords)
         @metadata[ns_pdf]['Producer'] = info_dict[:Producer] if info_dict.key?(:Producer)
         if info_dict.key?(:Trapped) && info_dict[:Trapped] != :Unknown
@@ -528,7 +532,10 @@ module HexaPDF
       # Formats the given date-time object (Time, Date, or DateTime) to be a valid XMP date-time
       # value.
       def xmp_date(date)
-        date.strftime("%Y-%m-%dT%H:%M:%S%:z")
+        case date
+        when Time, Date, DateTime then date.strftime("%Y-%m-%dT%H:%M:%S%:z")
+        else ''
+        end
       end
 
     end

data/lib/hexapdf/document/pages.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2024 Thomas Leitner
+# Copyright (C) 2014-2025 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