hexapdf 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fdace78c8d34d39c345e2ccd04edda4755e2fc8076cc7320793a4ef16f48520
-  data.tar.gz: a0ec03dc2d579eb8663512ec0c84cadbc877b9ec43cabb8ea0d6ab58df337585
+  metadata.gz: 7a32d8f7558ea14ae5dc40849c690b79f5ed4a797cffb85253e7fd6d00c54736
+  data.tar.gz: 92713168ee64efc59f86ff1d4f8989054ab02653ccaf84795aed3fea02a4811d
 SHA512:
-  metadata.gz: a8b18782359af03f0eda710658d0839554f0e95cd8068683dcaea56e8493c3b8a0b4cc30c9e39a3fdbe743df4d5e34b84ce4ab27125c8c14300b861ecbff16e9
-  data.tar.gz: 8d5c60a368d85fa9c2b118d955933943f5d0cf79e91d744348cf1e3f1c9435d44880033c844b58ab098c8ab8d1e2e7cd4c5e04710133b25543f31457277d0ba2
+  metadata.gz: 43b05643d9a59e9656a464eda221fa28e04bb4fe8ba1f97d0e31e434fbce64ffb9ed551689ce68957c8b4a7b82fbc85ecd91c1eac6d177b0109d4b9b5d275a6c
+  data.tar.gz: 780e7051327b0463e800ca4ea3b9f1ac1c3723d960154a2ac27c9e9bed867d0a257c48c20762cd0947f8638dc1f72b598a33ff76e1f0d1d2b0f1ff843497eb29

data/CHANGELOG.md

@@ -1,3 +1,48 @@
+## 0.31.0 - 2023-02-22
+
+### Added
+
+* [HexaPDF::Layout::PageStyle] for collecting all styling information for pages
+* [HexaPDF::Composer#page_style] for configuring different page styles
+
+### Changed
+
+* **Breaking change**: [HexaPDF::Composer] uses page styles underneath
+* **Breaking change**: Configuration options `filter.flate_compression` and
+  `filter.flate_memory` are changed to `filter.flate.compression` and
+  `filter.flate.memory`
+* **Breaking change**: [HexaPDF::Document#wrap] handles cross-reference and
+  object stream specially to avoid problems with invalid PDFs
+* [HexaPDF::Composer::new] to allow skipping the initial page creation
+* CLI command `hexapdf info --check` to process streams to reveal stream errors
+* CLI commands to output the name of created PDF files in verbose mode
+
+### Fixed
+
+* Validation of document outline items in case the first or last item got
+  deleted
+* `HexaPDF::Type::Page#perform_validation` to set a /MediaBox for invalid pages
+  that don't have one
+
+
+## 0.30.0 - 2023-02-13
+
+### Added
+
+* [HexaPDF::Document::Pages#create] for creating a page object without adding it
+  to the page tree
+
+### Changed
+
+* `HexaPDF::Type::FontSimple#perform_validation` to correct /Widths fields in
+  case it has an invalid number of entries
+
+### Fixed
+
+* [HexaPDF::DictionaryFields::DateConverter] to handle invalid months, day,
+  hour, minute and second values
+
+
 ## 0.29.0 - 2023-01-30
 
 ### Added

data/lib/hexapdf/cli/command.rb

@@ -101,6 +101,17 @@ module HexaPDF
       def pdf_options(password)
         hash = {decryption_opts: {password: password}, config: {}}
         HexaPDF::GlobalConfiguration['filter.predictor.strict'] = command_parser.strict
+        HexaPDF::GlobalConfiguration['filter.flate.on_error'] =
+          if command_parser.strict
+            proc { true }
+          else
+            proc do |_, error|
+              if command_parser.verbosity_info?
+                $stderr.puts "Ignoring error in flate encoded stream: #{error}"
+              end
+              false
+            end
+          end
         hash[:config]['parser.try_xref_reconstruction'] = !command_parser.strict
         hash[:config]['parser.on_correctable_error'] =
           if command_parser.strict
@@ -120,6 +131,7 @@ module HexaPDF
       # Writes the document to the given file or does nothing if +out_file+ is +nil+.
       def write_document(doc, out_file, incremental: false)
         if out_file
+          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}"
@@ -128,6 +140,9 @@ module HexaPDF
                 "for object (#{object.oid},#{object.gen}): #{msg}"
             end
           end
+          if command_parser.verbosity_info?
+            puts "Creating output document #{out_file}"
+          end
           doc.write(out_file, validate: false, incremental: incremental)
         end
       end
@@ -331,7 +346,7 @@ module HexaPDF
             rotation = ROTATE_MAP[$4]
             start_nr.step(to: end_nr, by: step) {|n| arr << [n, rotation] }
           else
-            raise OptionParser::InvalidArgument, "invalid page range format: #{str}"
+            raise OptionParser::InvalidArgument, "invalid page range format: #{str.inspect}"
           end
         end
       end

data/lib/hexapdf/cli/info.rb

@@ -106,6 +106,13 @@ module HexaPDF
             doc.each(only_loaded: false) do |obj|
               indirect_object = obj
               obj.validate(auto_correct: true, &validation_block)
+              if obj.data.stream
+                begin
+                  obj.stream
+                rescue StandardError
+                  puts "ERROR: Stream of object (#{obj.oid},#{obj.gen}) invalid: #{$!.message}"
+                end
+              end
             end
           end
 
@@ -177,7 +184,8 @@ module HexaPDF
       def pdf_options(password)
         if @check_file
           options = {decryption_opts: {password: password}, config: {}}
-          HexaPDF::GlobalConfiguration['filter.predictor.strict'] = false
+          HexaPDF::GlobalConfiguration['filter.predictor.strict'] = true
+          HexaPDF::GlobalConfiguration['filter.flate.on_error'] = proc { true }
           options[:config]['parser.try_xref_reconstruction'] = true
           options[:config]['parser.on_correctable_error'] = lambda do |_, msg, pos|
             puts "WARNING: Parse error at position #{pos}: #{msg}"

data/lib/hexapdf/cli/inspect.rb

@@ -166,8 +166,8 @@ module HexaPDF
           when 'p', 'pages'
             begin
               pages = parse_pages_specification(data.shift || '1-e', @doc.pages.count)
-            rescue StandardError
-              $stderr.puts("Error: Invalid page range argument")
+            rescue StandardError => e
+              $stderr.puts("Error: #{e}")
               next
             end
             page_list = @doc.pages.to_a

data/lib/hexapdf/composer.rb

@@ -106,6 +106,14 @@ 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.
+    #
+    #     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.
+    #
     # 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.
@@ -120,36 +128,53 @@ module HexaPDF
     # Example:
     #
     #   composer = HexaPDF::Composer.new            # uses the default values
+    #
     #   HexaPDF::Composer.new(page_size: :Letter, margin: 72) do |composer|
     #     #...
     #   end
-    def initialize(page_size: :A4, page_orientation: :portrait, margin: 36) #:yields: composer
+    #
+    #   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
+    #     # ...
+    #   end
+    def initialize(skip_page_creation: false, page_size: :A4, page_orientation: :portrait,
+                   margin: 36) #:yields: composer
       @document = HexaPDF::Document.new
-      @page_size = page_size
-      @page_orientation = page_orientation
-      @margin = Layout::Style::Quad.new(margin)
-
-      new_page
+      @page_styles = {}
+      @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)
+        end
+        new_page
+      end
       yield(self) if block_given?
     end
 
     # Creates a new page, making it the current one.
     #
-    # If any of +page_size+, +page_orientation+ or +margin+ are set, they will be used instead of
-    # the default values and will become the default values.
+    # 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 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.
     #
     # Examples:
     #
-    #   composer.new_page  # uses the default values
-    #   composer.new_page(page_size: :A5, margin: [72, 36])
-    def new_page(page_size: nil, page_orientation: nil, margin: nil)
-      @page_size = page_size if page_size
-      @page_orientation = page_orientation if page_orientation
-      @margin = Layout::Style::Quad.new(margin) if margin
-
-      @page = @document.pages.add(@page_size, orientation: @page_orientation)
+    #   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)
+      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
-      create_frame
+      @frame = page_style.frame
+      @page_style = page_style.next_style || style
     end
 
     # The x-position of the cursor inside the current frame.
@@ -190,6 +215,40 @@ module HexaPDF
       @document.layout.style(name, base: base, **properties)
     end
 
+    # :call-seq:
+    #    composer.page_style(name)                                 -> page_style
+    #    composer.page_style(name, **attributes, &template_block)  -> page_style
+    #
+    # Creates and/or returns the page style +name+.
+    #
+    # If no attributes are given, the page style +name+ is returned. In case it does not exist,
+    # +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.
+    #
+    # 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.rectangle(0, 0, page_box.width, page_box.height).
+    #         fill
+    #     end
+    #     style.frame = style.create_frame(canvas.context, 36)
+    #   end
+    #
+    # See: HexaPDF::Layout::PageStyle
+    def page_style(name, **attributes, &block)
+      if attributes.empty?
+        @page_styles[name]
+      else
+        @page_styles[name] = HexaPDF::Layout::PageStyle.new(**attributes, &block)
+      end
+    end
+
     # 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
@@ -325,17 +384,6 @@ module HexaPDF
       stamp
     end
 
-    private
-
-    # Creates the frame into which boxes are layed out when a new page is created.
-    def create_frame
-      media_box = @page.box
-      @frame = Layout::Frame.new(media_box.left + @margin.left,
-                                 media_box.bottom + @margin.bottom,
-                                 media_box.width - @margin.left - @margin.right,
-                                 media_box.height - @margin.bottom - @margin.top)
-    end
-
   end
 
 end

data/lib/hexapdf/configuration.rb

@@ -350,6 +350,9 @@ module HexaPDF
   #    The media box that is used for new pages that don't define a media box. Default value is
   #    A4. See HexaPDF::Type::Page::PAPER_SIZE for a list of predefined paper sizes.
   #
+  #    This configuration option (together with 'page.default_media_orientation') is also used when
+  #    validating pages and a page without a media box is found.
+  #
   #    The value can either be a rectangle defining the paper size or a Symbol referencing one of
   #    the predefined paper sizes.
   #
@@ -511,11 +514,20 @@ module HexaPDF
   #
   #    See PDF1.7 s8.6
   #
-  # filter.flate_compression::
+  # filter.flate.compression::
   #    Specifies the compression level that should be used with the FlateDecode filter. The level
   #    can range from 0 (no compression), 1 (best speed) to 9 (best compression, default).
   #
-  # filter.flate_memory::
+  # filter.flate.on_error::
+  #    Callback hook when a potentially recoverable Zlib error occurs in the FlateDecode filter.
+  #
+  #    The value needs to be an object that responds to \#call(stream, error) where stream is the
+  #    Zlib stream object and error is the thrown error. The method needs to return +true+ if an
+  #    error should be raised.
+  #
+  #    The default implementation prevents errors from being raised.
+  #
+  # filter.flate.memory::
   #    Specifies the memory level that should be used with the FlateDecode filter. The level can
   #    range from 1 (minimum memory usage; slow, reduces compression) to 9 (maximum memory usage).
   #
@@ -543,8 +555,9 @@ module HexaPDF
   #    This mapping is used to provide automatic wrapping of objects in the HexaPDF::Document#wrap
   #    method.
   GlobalConfiguration =
-    Configuration.new('filter.flate_compression' => 9,
-                      'filter.flate_memory' => 6,
+    Configuration.new('filter.flate.compression' => 9,
+                      'filter.flate.on_error' => proc { false },
+                      'filter.flate.memory' => 6,
                       'filter.predictor.strict' => false,
                       'color_space.map' => {
                         DeviceRGB: 'HexaPDF::Content::ColorSpace::DeviceRGB',

data/lib/hexapdf/dictionary_fields.rb

@@ -305,8 +305,13 @@ module HexaPDF
                      else
                        (m[7] == '-' ? -1 : 1) * (m[8].to_i * 3600 + m[9].to_i * 60).clamp(0, 86399)
                      end
-        Time.new(m[1].to_i, (m[2] ? m[2].to_i : 1), (m[3] ? m[3].to_i : 1),
-                 m[4].to_i, m[5].to_i, m[6].to_i, utc_offset)
+        begin
+          Time.new(m[1].to_i, (m[2] ? m[2].to_i : 1), (m[3] ? m[3].to_i : 1),
+                   m[4].to_i, m[5].to_i, m[6].to_i, utc_offset)
+        rescue ArgumentError
+          Time.new(m[1].to_i, m[2].to_i.clamp(1, 12), m[3].to_i.clamp(1, 31),
+                   m[4].to_i.clamp(0, 23), m[5].to_i.clamp(0, 59), m[6].to_i.clamp(0, 59), utc_offset)
+        end
       end
 
     end

data/lib/hexapdf/document/pages.rb

@@ -75,28 +75,41 @@ module HexaPDF
         @document.catalog.pages
       end
 
-      # :call-seq:
-      #   pages.add                                     -> new_page
-      #   pages.add(media_box, orientation: :portrait)  -> new_page
-      #   pages.add(page)                               -> page
+      # Creates a page object and returns it *without* adding it to the page tree.
+      #
+      # +media_box+::
+      #     If this argument is +nil+/not specified, the value is taken from the configuration
+      #     option 'page.default_media_box'.
+      #
+      #     If the resulting value is an array with four numbers (specifying the media box), the new
+      #     page will have these exact dimensions.
       #
-      # Adds the page or a new empty page at the end and returns it.
+      #     If the value is a symbol, it is taken as a reference to a pre-defined media box in
+      #     HexaPDF::Type::Page::PAPER_SIZE. The +orientation+ can then be used to specify the page
+      #     orientation.
       #
-      # If no argument is given, a new page with the default dimensions (see configuration option
-      # 'page.default_media_box') is used.
+      # +orientation+::
+      #     If this argument is not specified, it is taken from 'page.default_media_orientation'. It
+      #     is only used if +media_box+ is a symbol and not an array.
+      def create(media_box: nil, orientation: nil)
+        media_box ||= @document.config['page.default_media_box']
+        orientation ||= @document.config['page.default_media_orientation']
+        box = Type::Page.media_box(media_box, orientation: orientation)
+        @document.add({Type: :Page, MediaBox: box})
+      end
+
+      # :call-seq:
+      #   pages.add                               -> new_page
+      #   pages.add(page)                         -> page
+      #   pages.add(media_box, orientation: nil)  -> new_page
       #
-      # If the single argument is an array with four numbers (specifying the media box), the new
-      # page will have these dimensions.
+      # Adds the given page or a new empty page at the end and returns it.
       #
-      # If the single argument is a symbol, it is taken as referencing a pre-defined media box in
-      # HexaPDF::Type::Page::PAPER_SIZE for the new page. The optional argument +orientation+ can be
-      # used to change the orientation to :landscape if needed.
-      def add(page = nil, orientation: :portrait)
-        if page.kind_of?(Array)
-          page = @document.add({Type: :Page, MediaBox: page})
-        elsif page.kind_of?(Symbol)
-          box = Type::Page.media_box(page, orientation: orientation)
-          page = @document.add({Type: :Page, MediaBox: box})
+      # If called with a page object as argument, that page object is used. Otherwise #create is
+      # called with the arguments +media_box+ and +orientation+ to create a new page.
+      def add(page = nil, orientation: nil)
+        unless page.kind_of?(HexaPDF::Type::Page)
+          page = create(media_box: page, orientation: orientation)
         end
         @document.catalog.pages.add_page(page)
       end

data/lib/hexapdf/document.rb

@@ -325,7 +325,14 @@ module HexaPDF
         type = (klass <= HexaPDF::Dictionary ? klass.type : nil)
       else
         type ||= deref(data.value[:Type]) if data.value.kind_of?(Hash)
-        klass = GlobalConfiguration.constantize('object.type_map', type) { nil } if type
+        if type
+          klass = GlobalConfiguration.constantize('object.type_map', type) { nil }
+          if (type == :ObjStm || type == :XRef) &&
+              klass.each_field.any? {|name, field| field.required? && !data.value.key?(name) }
+            data.value.delete(:Type)
+            klass = nil
+          end
+        end
       end
 
       if data.value.kind_of?(Hash)

data/lib/hexapdf/encryption/standard_security_handler.rb

@@ -324,10 +324,10 @@ module HexaPDF
       def prepare_decryption(password: '', check_permissions: true)
         if dict[:Filter] != :Standard
           raise(HexaPDF::UnsupportedEncryptionError,
-                "Invalid /Filter value for standard security handler")
+                "Invalid /Filter value #{dict[:Filter]} for standard security handler")
         elsif ![2, 3, 4, 6].include?(dict[:R])
           raise(HexaPDF::UnsupportedEncryptionError,
-                "Invalid /R value for standard security handler")
+                "Invalid /R value #{dict[:R]} for standard security handler")
         elsif dict[:R] <= 4 && !document.trailer[:ID].kind_of?(PDFArray)
           document.trailer[:ID] = ['', '']
         end

data/lib/hexapdf/filter/flate_decode.rb

@@ -55,21 +55,33 @@ module HexaPDF
       def self.decoder(source, options = nil)
         fib = Fiber.new do
           inflater = Zlib::Inflate.new
+          error_raised = nil
+
           while source.alive? && (data = source.resume)
             next if data.empty?
             begin
-              data = inflater.inflate(data)
-            rescue StandardError => e
-              raise FilterError, "Problem while decoding Flate encoded stream: #{e}"
+              Fiber.yield(inflater.inflate(data))
+            rescue Zlib::DataError, Zlib::BufError => e
+              # Only swallow the error if it appears at the end of the stream
+              if error_raised || HexaPDF::GlobalConfiguration['filter.flate.on_error'].call(inflater, e)
+                raise FilterError, "Problem while decoding Flate encoded stream: #{e}"
+              else
+                Fiber.yield(inflater.flush_next_out)
+                error_raised = e
+              end
             end
-            Fiber.yield(data)
           end
+
           begin
             data = inflater.total_in == 0 || (data = inflater.finish).empty? ? nil : data
             inflater.close
             data
-          rescue StandardError => e
-            raise FilterError, "Problem while decoding Flate encoded stream: #{e}"
+          rescue Zlib::DataError, Zlib::BufError => e
+            if HexaPDF::GlobalConfiguration['filter.flate.on_error'].call(inflater, e)
+              raise FilterError, "Problem while decoding Flate encoded stream: #{e}"
+            else
+              Fiber.yield(inflater.flush_next_out)
+            end
           end
         end
 
@@ -87,9 +99,9 @@ module HexaPDF
         end
 
         Fiber.new do
-          deflater = Zlib::Deflate.new(HexaPDF::GlobalConfiguration['filter.flate_compression'],
+          deflater = Zlib::Deflate.new(HexaPDF::GlobalConfiguration['filter.flate.compression'],
                                        Zlib::MAX_WBITS,
-                                       HexaPDF::GlobalConfiguration['filter.flate_memory'])
+                                       HexaPDF::GlobalConfiguration['filter.flate.memory'])
           while source.alive? && (data = source.resume)
             data = deflater.deflate(data)
             Fiber.yield(data)

data/lib/hexapdf/layout/page_style.rb

@@ -0,0 +1,144 @@
+# -*- 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/error'
+require 'hexapdf/layout/style'
+require 'hexapdf/layout/frame'
+
+module HexaPDF
+  module Layout
+
+    # A PageStyle defines the initial look of a page and the placement of one or more frames.
+    class PageStyle
+
+      # The page size.
+      #
+      # Can be any valid predefined page size (see HexaPDF::Type::Page::PAPER_SIZE) or an array
+      # [llx, lly, urx, ury] specifying a custom page size.
+      #
+      # Example:
+      #
+      #   style.page_size = :A4
+      #   style.page_size = [0, 0, 200, 200]
+      attr_accessor :page_size
+
+      # The page orientation, either +:portrait+ or +:landscape+.
+      #
+      # Only used if #page_size is one of the predefined page sizes and not an array.
+      attr_accessor :orientation
+
+      # A callable object that defines the initial content of a page created with #create_page.
+      #
+      # The callable object is given a canvas and the page style as arguments. It needs to draw the
+      # initial content of the page. Note that the graphics state of the canvas is *not* saved
+      # before executing the template code and restored afterwards. If this is needed, the object
+      # needs to do it itself.
+      #
+      # Furthermore it should set the #frame and #next_style attributes appropriately, if not done
+      # beforehand. The #create_frame method can be used for easily creating a rectangular frame.
+      #
+      # Example:
+      #
+      #   page_style.template = lambda do |canvas, style
+      #     box = canvas.context.box
+      #     canvas.fill_color("fd0") do
+      #       canvas.rectangle(0, 0, box.width, box.height).fill
+      #     end
+      #     style.frame = style.create_frame(canvas.context, 72)
+      #   end
+      attr_accessor :template
+
+      # The HexaPDF::Layout::Frame object that defines the area on the page where content should be
+      # placed.
+      #
+      # This can either be set beforehand or during execution of the #template.
+      #
+      # If no frame has been set, a frame covering the page except for a default margin on all sides
+      # is set during #create_page.
+      attr_accessor :frame
+
+      # Defines the name of the page style that should be used for the next page.
+      #
+      # If this attribute is +nil+ (the default), it means that this style should be used again.
+      attr_accessor :next_style
+
+      # Creates a new page style instance for the given page size and orientation. If a block is
+      # given, it is used as template for defining the initial content.
+      #
+      # Example:
+      #
+      #   PageStyle.new(page_size: :Letter) do |canvas, style|
+      #     style.frame = style.create_frame(canvas.context, 72)
+      #     style.next_style = :other
+      #     canvas.fill_color("fd0") { canvas.circle(100, 100, 50).fill }
+      #   end
+      def initialize(page_size: :A4, orientation: :portrait, &block)
+        @page_size = page_size
+        @orientation = orientation
+        @template = block
+        @frame = nil
+        @next_style = nil
+      end
+
+      # Creates a new page in the given document with this page style and returns it.
+      #
+      # If #frame has not been set beforehand or during execution of the #template, a default frame
+      # covering the whole page except a margin of 36 is created.
+      def create_page(document)
+        page = document.pages.create(media_box: page_size, orientation: orientation)
+        template&.call(page.canvas, self)
+        self.frame ||= create_frame(page, 36)
+        page
+      end
+
+      # Creates a frame based on the given page's box and margin.
+      #
+      # The +margin+ can be any value allowed by HexaPDF::Layout::Style::Quad#set.
+      #
+      # *Note*: This is a helper method for use inside the #template callable.
+      def create_frame(page, margin = 36)
+        box = page.box
+        margin = Layout::Style::Quad.new(margin)
+        Layout::Frame.new(box.left + margin.left,
+                          box.bottom + margin.bottom,
+                          box.width - margin.left - margin.right,
+                          box.height - margin.bottom - margin.top)
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/layout.rb

@@ -56,6 +56,7 @@ module HexaPDF
     autoload(:ImageBox, 'hexapdf/layout/image_box')
     autoload(:ColumnBox, 'hexapdf/layout/column_box')
     autoload(:ListBox, 'hexapdf/layout/list_box')
+    autoload(:PageStyle, 'hexapdf/layout/page_style')
 
   end