hexapdf 0.32.2 → 0.33.0

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,8 +397,7 @@ 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
 
@@ -393,7 +445,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)

data/lib/hexapdf/configuration.rb

@@ -44,12 +44,12 @@ module HexaPDF
   # == Overview
   #
   # HexaPDF allows detailed control over many aspects of PDF manipulation. If there is a need to
-  # use a certain default value somewhere, it is defined as configuration options so that it can
+  # use a certain default value somewhere, it is defined as a configuration option so that it can
   # easily be changed.
   #
   # Some options are defined as global options because they are needed on the class level - see
-  # HexaPDF::GlobalConfiguration[index.html#GlobalConfiguration]. Other options can be configured for
-  # individual documents as they allow to fine-tune some behavior - see
+  # HexaPDF::GlobalConfiguration[index.html#GlobalConfiguration]. Other options can be configured
+  # for individual documents as they allow to fine-tune some behavior - see
   # HexaPDF::DefaultDocumentConfiguration[index.html#DefaultDocumentConfiguration].
   #
   # A configuration option name is dot-separted to provide a hierarchy of option names. For
@@ -155,9 +155,6 @@ module HexaPDF
   #    A boolean specifying whether an AcroForm field's appearances should automatically be
   #    generated if they are missing.
   #
-  # acro_form.text_field.default_width::
-  #    A number specifying the default width of AcroForm text fields which should be auto-sized.
-  #
   # acro_form.default_font_size::
   #    A number specifying the default font size of AcroForm text fields which should be auto-sized.
   #
@@ -248,7 +245,7 @@ module HexaPDF
   #
   #    The most often used filters are implemented and readily available.
   #
-  #    See PDF1.7 s7.4.1, ADB sH.3 3.3
+  #    See PDF2.0 s7.4.1, ADB sH.3 3.3
   #
   # font.map::
   #    Defines a mapping from font names and variants to font files.
@@ -278,7 +275,14 @@ module HexaPDF
   #    was called, you can use +font_wrapper.pdf_object.document+.
   #
   #    The default implementation returns an object of class HexaPDF::Font::InvalidGlyph which, when
-  #    not removed before encoding, will raise an error.
+  #    not removed before encoding, will raise a HexaPDF::MissingGlyphError.
+  #
+  #    If a replacement glyph should be displayed instead of an error, the following provides a good
+  #    starting implementation:
+  #
+  #      doc.config['font.on_missing_glyph'] = lambda do |character, font_wrapper|
+  #        font_wrapper.custom_glyph(font_wrapper.font_type == :Type1 ? :question : 0, character)
+  #      end
   #
   # font.on_missing_unicode_mapping::
   #    Callback hook when a character code point cannot be converted to a Unicode character.
@@ -298,11 +302,6 @@ module HexaPDF
   #
   #    See the HexaPDF::FontLoader module for information on how to implement a font loader object.
   #
-  # graphic_object.map::
-  #    A mapping from graphic object names to graphic object factories.
-  #
-  #    See HexaPDF::Content::GraphicObject for more information.
-  #
   # graphic_object.arc.max_curves::
   #    The maximum number of curves used for approximating a complete ellipse using Bezier curves.
   #
@@ -310,6 +309,11 @@ module HexaPDF
   #    to compute. It should not be set to values lower than 4, otherwise the approximation of a
   #    complete ellipse is visibly false.
   #
+  # graphic_object.map::
+  #    A mapping from graphic object names to graphic object factories.
+  #
+  #    See HexaPDF::Content::GraphicObject for more information.
+  #
   # image_loader::
   #    An array with image loader implementations. When an image should be loaded, the array is
   #    iterated in sequence to find a suitable image loader.
@@ -381,14 +385,6 @@ module HexaPDF
   #
   #    Defaults to +true+.
   #
-  # sorted_tree.max_leaf_node_size::
-  #    The maximum number of nodes that should be in a leaf node of a node tree.
-  #
-  # style.layers_map::
-  #    A mapping from style layer names to layer objects.
-  #
-  #    See HexaPDF::Layout::Style::Layers for more information.
-  #
   # signature.signing_handler::
   #   A mapping from a Symbol to a signing handler class (see
   #   HexaPDF::Document::Signatures::DefaultHandler). If the value is a String, it should contain
@@ -403,6 +399,14 @@ module HexaPDF
   #    filter value of a signature dictionary is ignored since we only support the standard
   #    signature algorithms.
   #
+  # sorted_tree.max_leaf_node_size::
+  #    The maximum number of nodes that should be in a leaf node of a node tree.
+  #
+  # style.layers_map::
+  #    A mapping from style layer names to layer objects.
+  #
+  #    See HexaPDF::Layout::Style::Layers for more information.
+  #
   # task.map::
   #    A mapping from task names to callable task objects. See HexaPDF::Task for more information.
   DefaultDocumentConfiguration =
@@ -459,13 +463,13 @@ module HexaPDF
                         'HexaPDF::FontLoader::FromConfiguration',
                         'HexaPDF::FontLoader::FromFile',
                       ],
+                      'graphic_object.arc.max_curves' => 6,
                       'graphic_object.map' => {
                         arc: 'HexaPDF::Content::GraphicObject::Arc',
                         endpoint_arc: 'HexaPDF::Content::GraphicObject::EndpointArc',
                         solid_arc: 'HexaPDF::Content::GraphicObject::SolidArc',
                         geom2d: 'HexaPDF::Content::GraphicObject::Geom2D',
                       },
-                      'graphic_object.arc.max_curves' => 6,
                       'image_loader' => [
                         'HexaPDF::ImageLoader::JPEG',
                         'HexaPDF::ImageLoader::PNG',
@@ -479,15 +483,12 @@ module HexaPDF
                         image: 'HexaPDF::Layout::ImageBox',
                         column: 'HexaPDF::Layout::ColumnBox',
                         list: 'HexaPDF::Layout::ListBox',
+                        table: 'HexaPDF::Layout::TableBox',
                       },
                       'page.default_media_box' => :A4,
                       'page.default_media_orientation' => :portrait,
                       'parser.on_correctable_error' => proc { false },
                       'parser.try_xref_reconstruction' => true,
-                      'sorted_tree.max_leaf_node_size' => 64,
-                      'style.layers_map' => {
-                        link: 'HexaPDF::Layout::Style::LinkLayer',
-                      },
                       'signature.signing_handler' => {
                         default: 'HexaPDF::DigitalSignature::Signing::DefaultHandler',
                         timestamp: 'HexaPDF::DigitalSignature::Signing::TimestampHandler',
@@ -498,6 +499,10 @@ module HexaPDF
                         'ETSI.CAdES.detached': 'HexaPDF::DigitalSignature::CMSHandler',
                         'ETSI.RFC3161': 'HexaPDF::DigitalSignature::CMSHandler',
                       },
+                      'sorted_tree.max_leaf_node_size' => 64,
+                      'style.layers_map' => {
+                        link: 'HexaPDF::Layout::Style::LinkLayer',
+                      },
                       'task.map' => {
                         optimize: 'HexaPDF::Task::Optimize',
                         dereference: 'HexaPDF::Task::Dereference',
@@ -512,12 +517,19 @@ module HexaPDF
   #
   #    Classes for the most often used color space families are implemented and readily available.
   #
-  #    See PDF1.7 s8.6
+  #    See PDF2.0 s8.6
   #
   # 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::
+  #    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).
+  #
+  #    The HexaPDF default value of 6 has been found in tests to be nearly equivalent to the Zlib
+  #    default of 8 in terms of speed and compression level but uses less memory.
+  #
   # filter.flate.on_error::
   #    Callback hook when a potentially recoverable Zlib error occurs in the FlateDecode filter.
   #
@@ -527,13 +539,6 @@ module HexaPDF
   #
   #    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).
-  #
-  #    The HexaPDF default value of 6 has been found in tests to be nearly equivalent to the Zlib
-  #    default of 8 in terms of speed and compression level but uses less memory.
-  #
   # filter.predictor.strict::
   #    Specifies whether the predictor algorithm used by LZWDecode and FlateDecode should operate in
   #    strict mode, i.e. adhering to the PDF specification without correcting for common deficiences
@@ -555,15 +560,15 @@ 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.on_error' => proc { false },
-                      'filter.flate.memory' => 6,
-                      'filter.predictor.strict' => false,
-                      'color_space.map' => {
+    Configuration.new('color_space.map' => {
                         DeviceRGB: 'HexaPDF::Content::ColorSpace::DeviceRGB',
                         DeviceCMYK: 'HexaPDF::Content::ColorSpace::DeviceCMYK',
                         DeviceGray: 'HexaPDF::Content::ColorSpace::DeviceGray',
                       },
+                      'filter.flate.compression' => 9,
+                      'filter.flate.memory' => 6,
+                      'filter.flate.on_error' => proc { false },
+                      'filter.predictor.strict' => false,
                       'object.type_map' => {
                         XRef: 'HexaPDF::Type::XRefStream',
                         ObjStm: 'HexaPDF::Type::ObjectStream',