hexapdf 0.34.1 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f2aec69ce9d984994c40912cd86d4cd10c38f23d5b975288ab11cd9e967d28b
-  data.tar.gz: 3012460ef7ca03cf81d65ac4a507dd7e23f31292d60d6e101bc555eee60f66a0
+  metadata.gz: 85a526812bcfbeae9fbe103513c3fac73ac2d736b2ac965305c8c1164fc976b7
+  data.tar.gz: f999566105d0ac42c5037bf642256fd6c9a0c515bffb2329ef32456009b46dbd
 SHA512:
-  metadata.gz: 10004ae421f4daefb3fa0a3672b56ff8cd208048ca61aaaa75de687af4ac0f9bad8470de011f4944828c4b530a61cd0f52d27dc74530af365f556bdbfcaf3373
-  data.tar.gz: 12c0e3dbca50e6dd05a8e2a211aa8459e7e085a30570769af4b98b85c46e36202275765ea64b2c5805ccca4bc8f28b3b5d1c1322085978b3e0ce5cfce6e9f6bd
+  metadata.gz: 77d31b7c95a8ffd8c1189b062aac8dd7adc75a78ca3f1d8c91033401a1311b446a387c8c1b52932d5573d7721b5a6d4210433ac44d500fa3389dd17daf1be865
+  data.tar.gz: 686e6e041a2723a54f1ff5acf0e46c9f7231b4ee5220f4dfe127579549c28c093f28c60ba4470d4be9fba0ccad0202905a57132f1e64596412308ab49b3ab1ed

data/CHANGELOG.md

@@ -1,3 +1,62 @@
+## 0.35.0 - 2024-01-06
+
+### Added
+
+* Command 'psd' for CLI `hexapdf inspect` to show a decoded content stream
+* Style property 'mask_mode' for more control over the region that gets removed
+  from a frame after placing a box
+* Style property 'valign' for vertically centering a box in a frame
+* [HexaPDF::Content::Canvas#form] for creating reusable Form XObjects
+* Method `#valid?` to all Glyph classes
+* [HexaPDF::Font::InvalidGlyph#control_char?] for detecting invalid glyphs that
+  represent a control character (like a newline)
+* [HexaPDF::Font::Type1Wrapper#decode_codepoint] and
+  [HexaPDF::Font::TrueTypeWrapper#decode_codepoint] for decoding a single
+  Unicode codepoint into a glyph
+* [HexaPDF::Layout::TextFragment::create_with_fallback_glyphs] for creating an
+  array of text fragments with support for fallback glyphs
+* Configuration option 'font.on_invalid_glyph' for use together with the new
+  method for creating text fragments with fallback glyphs
+* Configuration option 'font.fallback' which is used by the default
+  implementation of 'font.on_invalid_glyph'
+* [HexaPDF::Document::Layout#text_fragments] for creating text fragments with
+  support for fallback glyphs via 'font.on_invalid_glyph'
+* [HexaPDF::Content::CanvasComposer] for using high-level layout functionality
+  on a single canvas
+* [HexaPDF::Content::Canvas#composer] for easily creating a canvas composer
+* [HexaPDF::Font::TrueTypeWrapper#bold?] and [HexaPDF::Font::Type1Wrapper#bold?]
+  for determining whether a font is bold
+* [HexaPDF::Font::TrueTypeWrapper#italic?] and
+  [HexaPDF::Font::Type1Wrapper#italic?] for determining whether a font is italic
+* [HexaPDF::Encryption::StandardSecurityHandler#decryption_password_type] for
+  information on the type of password used for decryption
+
+### Changed
+
+* **Breaking change**: Style property 'align' is now called 'text_align' and
+  'valign' is 'text_valign'
+* **Breaking change**: Style property 'position' now takes the absolute position
+  directly as value instead of in the 'position_hint' property
+* **Breaking change**: Style property 'position_hint' is now called 'align'
+* **Breaking change**: Glyph objects now take the font wrapper instead of the
+  font on creation
+* **Breaking change**: The item marker type of a [HexaPDF::Layout::ListBox] item
+  is now set via `#marker_type` instead of `#item_type`
+* [HexaPDF::Object#validate] to catch exceptions and provided an appropriate
+  validation message
+
+### Fixed
+
+* [HexaPDF::Layout::ColumnBox#fit] to correctly take initial height into account
+* [HexaPDF::Layout::ColumnBox#fit] to ensure correct results in case the
+  requested dimensions are larger than the current region
+* [HexaPDF::Document::Layout#formatted_text_box] to correctly handle properties
+* [HexaPDF::Layout::Frame#fit] to raise an error if an invalid value for the
+  style property 'position' is used
+* Validation of PDF arrays and dictionaries by making sure only processed values
+  are used
+
+
 ## 0.34.1 - 2023-11-01
 
 ### Added

data/examples/009-text_layouter_alignment.rb

@@ -4,9 +4,10 @@
 # inside a rectangular area, with various horizontal and vertical alignment
 # options.
 #
-# The text can be aligned horizontally by setting [HexaPDF::Layout::Style#align]
-# and vertically by [HexaPDF::Layout::Style#valign]. In this example, a sample
-# text is laid out in all possible combinations.
+# The text can be aligned horizontally by setting
+# [HexaPDF::Layout::Style#text_align] and vertically by
+# [HexaPDF::Layout::Style#text_valign]. In this example, a sample text is laid
+# out in all possible combinations.
 #
 # Usage:
 # : `ruby text_layouter_alignment.rb`
@@ -26,8 +27,7 @@ canvas.font("Times", size: 10, variant: :bold)
 width = 100
 height = 150
 y_base = 800
-tf = HexaPDF::Layout::TextFragment.create(sample_text,
-                                          font: doc.fonts.add("Times"))
+tf = doc.layout.text_fragments(sample_text, font: doc.fonts.add("Times"))
 tl = HexaPDF::Layout::TextLayouter.new
 
 [:left, :center, :right, :justify].each_with_index do |align, x_index|
@@ -38,8 +38,8 @@ tl = HexaPDF::Layout::TextLayouter.new
     y = y_base - (height + 30) * y_index
     canvas.text(valign.to_s, at: [20, y - height / 2]) if x_index == 0
 
-    tl.style.align(align).valign(valign)
-    tl.fit([tf], width, height).draw(canvas, x, y)
+    tl.style.text_align(align).text_valign(valign)
+    tl.fit(tf, width, height).draw(canvas, x, y)
     canvas.stroke_color("hp-blue-dark").rectangle(x, y, width, -height).stroke
   end
 end

data/examples/010-text_layouter_inline_boxes.rb

@@ -57,7 +57,7 @@ items = sample_text.split(/(:-\)|;-\))/).map do |part|
 end
 
 layouter = TextLayouter.new
-layouter.style.align = :justify
+layouter.style.text_align = :justify
 layouter.style.line_spacing(:proportional, 1.5)
 layouter.fit(items, 500, 700).draw(doc.pages.add.canvas, 50, 800)
 

data/examples/011-text_layouter_line_wrapping.rb

@@ -37,17 +37,15 @@ require 'hexapdf'
 
 doc = HexaPDF::Document.new
 canvas = doc.pages.add([0, 0, 180, 230]).canvas
-canvas.font("Times", size: 10, variant: :bold)
-
 text = "Hello! Fly-fishing\nand wand\u{00AD}ering\taround - fanta\u{200B}stic" \
   " 1\u{00A0}0\u{00A0}1"
 
 x = 10
 y = 220
-frag = HexaPDF::Layout::TextFragment.create(text, font: doc.fonts.add("Times"))
+frag = doc.layout.text_fragments(text, font: doc.fonts.add("Times"))
 layouter = HexaPDF::Layout::TextLayouter.new
 [30, 60, 100, 160].each do |width|
-  result = layouter.fit([frag], width, 400)
+  result = layouter.fit(frag, width, 400)
   result.draw(canvas, x, y)
   canvas.stroke_color("hp-blue-dark").line_width(0.2)
   canvas.rectangle(x, y, width, -result.height).stroke

data/examples/013-text_layouter_shapes.rb

@@ -25,8 +25,6 @@
 
 require 'hexapdf'
 
-include HexaPDF::Layout
-
 doc = HexaPDF::Document.new
 page = doc.pages.add
 canvas = page.canvas
@@ -40,8 +38,8 @@ dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
 ullamco laboris nisi ut aliquip ex ea commodo consequat.
 ".tr("\n", ' ') * 10
 
-items = [TextFragment.create(sample_text, font: font)]
-layouter = TextLayouter.new
+items = doc.layout.text_fragments(sample_text, font: font)
+layouter = HexaPDF::Layout::TextLayouter.new
 
 ########################################################################
 # Circly things on the top
@@ -71,13 +69,13 @@ result.draw(canvas, 0, circle_top)
 canvas.circle(0, circle_top - radius, radius).stroke
 
 # Center: full circle
-layouter.style.align = :justify
+layouter.style.text_align = :justify
 result = layouter.fit(items, circle, radius * 2)
 result.draw(canvas, page.box.width / 2.0 - radius, circle_top)
 canvas.circle(page.box.width / 2.0, circle_top - radius, radius).stroke
 
 # Right: left half circle
-layouter.style.align = :right
+layouter.style.text_align = :right
 result = layouter.fit(items, left_half_circle, radius * 2)
 result.draw(canvas, page.box.width - radius, circle_top)
 canvas.circle(page.box.width, circle_top - radius, radius).stroke
@@ -106,14 +104,14 @@ left_half_diamond = lambda do |height, line_height|
 end
 
 # Left: right half diamond
-layouter.style.align = :left
+layouter.style.text_align = :left
 result = layouter.fit(items, half_diamond_width, 2 * diamond_width)
 result.draw(canvas, 0, diamond_top)
 canvas.polyline(0, diamond_top, diamond_width, diamond_top - diamond_width,
                 0, diamond_top - 2 * diamond_width).stroke
 
 # Center: full diamond
-layouter.style.align = :justify
+layouter.style.text_align = :justify
 result = layouter.fit(items, full_diamond, 2 * diamond_width)
 left = page.box.width / 2.0 - diamond_width
 result.draw(canvas, left, diamond_top)
@@ -123,7 +121,7 @@ canvas.polyline(left + diamond_width, diamond_top,
                 left, diamond_top - diamond_width).close_subpath.stroke
 
 # Right: left half diamond
-layouter.style.align = :right
+layouter.style.text_align = :right
 result = layouter.fit(items, left_half_diamond, 2 * diamond_width)
 middle = page.box.width
 result.draw(canvas, middle - diamond_width, diamond_top)
@@ -142,7 +140,7 @@ sine_wave = lambda do |height, line_height|
             40 * Math.sin(2 * Math::PI * (height + line_height) / sine_wave_height)].max
   [offset, sine_wave_height + 100 + offset * -2]
 end
-layouter.style.align = :justify
+layouter.style.text_align = :justify
 result = layouter.fit(items, sine_wave, sine_wave_height)
 middle = page.box.width / 2.0
 result.draw(canvas, middle - (sine_wave_height + 100) / 2, sine_wave_top)
@@ -167,7 +165,7 @@ house = lambda do |height, line_height|
     0
   end
 end
-layouter.style.align = :justify
+layouter.style.text_align = :justify
 result = layouter.fit(items, house, 200)
 
 middle = page.box.width / 2.0

data/examples/014-text_in_polygon.rb

@@ -28,9 +28,9 @@ adipis\u{00AD}cing elit, sed do eiusmod tempor incididunt ut labore et
 dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
 ullamco laboris nisi ut aliquip ex ea commodo consequat.
 ".tr("\n", ' ') * 12
-items = [TextFragment.create(sample_text, font: doc.fonts.add("Times"))]
+items = doc.layout.text_fragments(sample_text, font: doc.fonts.add("Times"))
 layouter = TextLayouter.new
-layouter.style.align = :justify
+layouter.style.text_align = :justify
 
 # The house example
 house = Geom2D::Polygon([100, 200], [400, 200], [500, 100], [400, 100], [400, 0],

data/examples/016-frame_automatic_box_placement.rb

@@ -57,8 +57,7 @@ draw_box = lambda do |**args|
 end
 
 # Absolutely positioned box with margin
-draw_box.call(width: 100, height: 100, position: :absolute, margin: 10,
-              position_hint: [250, 250])
+draw_box.call(width: 100, height: 100, position: [250, 250], margin: 10)
 
 # Fixed sized box with automatic width
 draw_box.call(height: 100)
@@ -71,23 +70,23 @@ draw_box.call(width: 100, height: 100)
 draw_box.call(width: 100, height: 100)
 
 # Fixed sized floating box, space to the right can be used
-draw_box.call(width: 100, height: 100, position: :float, position_hint: :left)
+draw_box.call(width: 100, height: 100, position: :float, align: :left)
 
 # Fixed sized floating box again, floating to the right
-draw_box.call(width: 100, height: 100, position: :float, position_hint: :right)
+draw_box.call(width: 100, height: 100, position: :float, align: :right)
 
 # Fixed sized floating box again, floating to the left with margin
-draw_box.call(width: 100, height: 100, position: :float, position_hint: :left,
+draw_box.call(width: 100, height: 100, position: :float, align: :left,
               margin: [0, 10])
 
 # Fixed sized box, no floating
 draw_box.call(width: 100, height: 100)
 
 # Fixed sized box, center aligned in the available space
-draw_box.call(width: 100, height: 100, position_hint: :center)
+draw_box.call(width: 100, height: 100, align: :center)
 
 # Fixed sized box, right aligned in the available space
-draw_box.call(width: 100, height: 100, position_hint: :right)
+draw_box.call(width: 100, height: 100, align: :right)
 
 # Fixed sized box, consuming the whole remaining available space
 draw_box.call

data/examples/017-frame_text_flow.rb

@@ -28,10 +28,10 @@ boxes = []
 boxes << doc.layout.image_box(File.join(__dir__, 'machupicchu.jpg'),
                               width: 100, margin: [10, 30], position: :float)
 boxes << Box.create(width: 50, height: 50, margin: 20,
-                    position: :float, position_hint: :right,
+                    position: :float, align: :right,
                     background_color: "hp-blue-light2",
                     border: {width: 1, color: "hp-blue-dark"})
-boxes << doc.layout.lorem_ipsum_box(count: 3, position: :flow, align: :justify)
+boxes << doc.layout.lorem_ipsum_box(count: 3, position: :flow, text_align: :justify)
 
 i = 0
 frame_filled = false

data/examples/018-composer.rb

@@ -4,9 +4,9 @@
 # documents by providing a high-level interface to the box layouting engine.
 #
 # Basic style properties can be set using the [HexaPDF::Composer#style] method
-# and the style name `:basic`. These properties are reused by every box and can
+# and the style name `:base`. These properties are reused by every box and can
 # be adjusted on a box-by-box basis. Newly defined styles also inherit the
-# properties from the `:basic` style.
+# properties from the `:base` style.
 #
 # Various methods allow the easy creation of boxes, for example, text and image
 # boxes. All these boxes are automatically drawn on the page. If the page has
@@ -25,20 +25,19 @@ dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exer\u{00AD}citation
 ullamco laboris nisi ut aliquip ex ea commodo consequat. ".tr("\n", " ")
 
 HexaPDF::Composer.create('composer.pdf') do |pdf|
-  pdf.style(:base, line_spacing: 1.5, last_line_gap: true, align: :justify)
+  pdf.style(:base, line_spacing: 1.5, last_line_gap: true, text_align: :justify)
   pdf.style(:image, border: {width: 1}, padding: 5, margin: 10)
   pdf.style(:link, fill_color: "hp-blue-dark", underline: true)
   image = File.join(__dir__, 'machupicchu.jpg')
 
   pdf.text(lorem_ipsum * 2)
   pdf.image(image, style: :image, width: 200, position: :float)
-  pdf.image(image, style: :image, width: 200, position: :absolute,
-            position_hint: [200, 300])
+  pdf.image(image, style: :image, width: 200, position: [200, 300])
   pdf.text(lorem_ipsum * 20, position: :flow)
 
   pdf.formatted_text(["Produced by ",
                       {link: "https://hexapdf.gettalong.org", text: "HexaPDF",
                        style: :link},
                       " via HexaPDF::Composer"],
-                      font_size: 15, align: :center, padding: 15)
+                      font_size: 15, text_align: :center, padding: 15)
 end

data/examples/020-column_box.rb

@@ -28,10 +28,10 @@ columns = doc.layout.column(columns: 2, style: {position: :flow}) do |column|
     column.image(File.join(__dir__, 'machupicchu.jpg'), width: 100,
                  style: {margin: [10, 30], position: :float})
     column.box(:base, width: 50, height: 50,
-               style: {margin: 20, position: :float, position_hint: :right,
+               style: {margin: 20, position: :float, align: :right,
                        background_color: "hp-blue-light2",
                        border: {width: 1, color: "hp-blue-dark"}})
-    column.lorem_ipsum(count: 2, position: :flow, align: :justify)
+    column.lorem_ipsum(count: 2, position: :flow, text_align: :justify)
   end
 end
 result = frame.fit(columns)

data/examples/021-list_box.rb

@@ -16,7 +16,7 @@ HexaPDF::Composer.create("list_box.pdf") do |composer|
   composer.list(content_indentation: 40, item_spacing: 20) do |list|
     list.lorem_ipsum
     list.image(File.join(__dir__, 'machupicchu.jpg'), height: 100)
-    list.list(item_type: :decimal) do |sub_list|
+    list.list(marker_type: :decimal) do |sub_list|
       1.upto(10) {|i| sub_list.text("Item #{i}") }
     end
     list.column do |column|

data/examples/027-composer_optional_content.rb

@@ -27,14 +27,14 @@ HexaPDF::Composer.create('composer_optional_content.pdf') do |composer|
   a3 = composer.document.optional_content.ocg('Answer 3')
   a3m = composer.document.optional_content.create_ocmd([a3, all], policy: :any_on)
 
-  composer.text('The Great Ruby Quiz', align: :center, margin: [0, 0, 24],
+  composer.text('The Great Ruby Quiz', text_align: :center, margin: [0, 0, 24],
                 font: ['Helvetica', variant: :bold], font_size: 24)
 
-  composer.list(item_type: :decimal, item_spacing: 32, style: :question) do |listing|
+  composer.list(marker_type: :decimal, item_spacing: 32, style: :question) do |listing|
     listing.multiple do |item|
       item.text('Who created Ruby?', style: :question)
       item.column(columns: 3, gaps: 5) do |cols|
-        cols.list(item_type: :decimal) do |answers|
+        cols.list(marker_type: :decimal) do |answers|
           answers.text('Guido van Rossum')
           answers.multiple do |answer|
             answer.text('Yukihiro “Matz” Matsumoto', position: :float)
@@ -49,7 +49,7 @@ HexaPDF::Composer.create('composer_optional_content.pdf') do |composer|
     listing.multiple do |item|
       item.text('When was Ruby created?', style: :question)
       item.column(columns: 3, gaps: 5) do |cols|
-        cols.list(item_type: :decimal) do |answers|
+        cols.list(marker_type: :decimal) do |answers|
           answers.text('1991')
           answers.text('1992')
           answers.multiple do |answer|
@@ -74,7 +74,7 @@ HexaPDF::Composer.create('composer_optional_content.pdf') do |composer|
   action = composer.document.wrap({Type: :Action, S: :SetOCGState})
   action.add_state_change(:toggle, [a1, a2, a3])
   composer.text("Click to toggle answers", border: {width: 1, color: "red"},
-                position_hint: :right, padding: 2, overlays: [[:link, action: action]])
+                align: :right, padding: 2, overlays: [[:link, action: action]])
 
   composer.document.optional_content.default_configuration(
     BaseState: :OFF,

data/examples/028-frame_mask_mode.rb

@@ -0,0 +1,23 @@
+# # Frame - Mask Mode
+#
+# This example shows how to use the style property 'mask_mode' to achieve
+# certain effects like overlaying boxes on each other or using multiple
+# horizontal alignments on one line.
+#
+# Usage:
+# : `ruby frame_mask_mode.rb`
+#
+require 'hexapdf'
+
+HexaPDF::Composer.create('frame_mask_mode.pdf') do |composer|
+  box = composer.image(File.join(__dir__, 'machupicchu.jpg'),
+                       border: {width: 1}, mask_mode: :none)
+  composer.text('Text overlaid over image', height: box.height, text_align: :center,
+               font_size: 50, text_valign: :center, text_rendering_mode: :fill_stroke,
+               fill_color: 'white', stroke_color: 'hp-blue', margin: [0, 0, 10])
+  composer.column(columns: 1, style: {border: {width: 1}, padding: 10}) do |col|
+    col.text('Center', mask_mode: :box, align: :center)
+    col.text('Left', mask_mode: :fill_horizontal)
+    col.text('Right', align: :right)
+  end
+end

data/examples/029-composer_fallback_fonts.rb

@@ -0,0 +1,22 @@
+# # Composer - Fallback Fonts
+#
+# This example shows how to use the fallback font support of HexaPDF to replace
+# invalid glyphs with ones from other fonts.
+#
+# While the examples shows the usage of a single fallback font, it can easily be
+# generalized to support multiple fallback fonts.
+#
+# Usage:
+# : `ruby composer_fallback_fonts.rb`
+#
+
+require 'hexapdf'
+
+HexaPDF::Composer.create('composer_fallback_fonts.pdf') do |composer|
+  zapf_dingbats = composer.document.fonts.add('ZapfDingbats')
+  composer.document.config['font.fallback'] = ['ZapfDingbats']
+  composer.text('This text contains the scissors symbol ✂ which is not available in ' \
+                'the default font Times but available in the set ZapfDingbats fallback ' \
+                'font. Other symbols from ZapfDingbats like ✐ and ✈ can also be used.' \
+                "\n\n❤ HexaPDF")
+end

data/lib/hexapdf/cli/info.rb

@@ -128,6 +128,7 @@ module HexaPDF
             details = doc.security_handler.encryption_details
             data = "yes (version: #{details[:version]}, key length: #{details[:key_length]}bits)"
             output_line("Encrypted", data)
+            output_line("  Used Password", doc.security_handler.decryption_password_type)
             output_line("  String algorithm", details[:string_algorithm].to_s)
             output_line("  Stream algorithm", details[:stream_algorithm].to_s)
             output_line("  EFF algorithm", details[:embedded_file_algorithm].to_s)

data/lib/hexapdf/cli/inspect.rb

@@ -42,6 +42,55 @@ module HexaPDF
     # Shows the internal structure of a PDF file.
     class Inspect < Command
 
+      # Outputs the content of a page in a nicer form.
+      class ContentProcessor < HexaPDF::Content::Processor
+
+        # :nodoc:
+        def initialize(*)
+          super
+          @indent = 0
+          @serializer = HexaPDF::Serializer.new
+        end
+
+        # :nodoc:
+        def paint_xobject(name)
+          puts "#{indent}paint_xobject #{@serializer.serialize(name)}"
+          @indent += 1
+          super
+          @indent -= 1
+        end
+
+        # :nodoc:
+        def method_missing(operator, *operands)
+          case operator
+          when :save_graphics_state, :begin_text, :begin_marked_content
+            puts "#{indent}#{operator}"
+            @indent += 1
+          when :restore_graphics_state, :end_text, :end_marked_content
+            @indent -= 1
+            puts "#{indent}#{operator}"
+          when :show_text, :show_text_with_positioning
+            puts "#{indent}text> #{decode_text(*operands)}"
+          else
+            puts "#{indent}#{operator} #{operands.map {|op| @serializer.serialize(op) }.join(' ')}"
+            @indent += 1 if operator == :begin_marked_content_with_property_list
+          end
+        end
+
+        # :nodoc:
+        def respond_to_missing?(*)
+          true
+        end
+
+        private
+
+        # Returns the current indentation string.
+        def indent
+          '  ' * @indent
+        end
+
+      end
+
       def initialize #:nodoc:
         super('inspect', takes_commands: false)
         short_desc("Dig into the internal structure of a PDF file")
@@ -176,7 +225,7 @@ module HexaPDF
               puts str
             end
 
-          when 'po', 'ps'
+          when 'po', 'ps', 'psd'
             page_number_str = data.shift
             unless page_number_str
               $stderr.puts("Error: Missing PAGE argument to #{command}")
@@ -188,8 +237,11 @@ module HexaPDF
               next
             end
             page = @doc.pages[page_number]
-            if command.start_with?('ps')
+            case command
+            when 'ps'
               $stdout.write(page.contents)
+            when 'psd'
+              page.process_contents(ContentProcessor.new)
             else
               puts "#{page.oid} #{page.gen} obj"
               serialize(page.value, recursive: false)
@@ -375,6 +427,7 @@ module HexaPDF
         ["p[ages] [RANGE]",  "Print information about pages"],
         ["po PAGE", "Print the page object"],
         ["ps PAGE", "Print the content stream of the page"],
+        ["psd PAGE", "Print the decoded content stream of the page"],
         ["pc | page-count", "Print the number of pages"],
         ["search REGEXP", "Print objects matching the pattern"],
         ["h[elp]", "Show the help"],

data/lib/hexapdf/composer.rb

@@ -78,8 +78,8 @@ module HexaPDF
   #
   #   #>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)
+  #     pdf.style(:base, font_size: 20, text_align: :center)
+  #     pdf.text("Hello World", text_valign: :center)
   #   end
   #
   # See: HexaPDF::Document::Layout, HexaPDF::Layout::Frame, HexaPDF::Layout::Box

data/lib/hexapdf/configuration.rb

@@ -138,6 +138,30 @@ module HexaPDF
 
   end
 
+  # Provides the default implementation for the configuration option 'font.on_invalid_glyph'.
+  #
+  # It uses the first font in the list provided by the 'font.fallback' configuration option that
+  # contains a glyph for the +codepoint+ (taking the font variant into account). If no fallback font
+  # contains such a glyph, +invalid_glyph+ is used.
+  def self.font_on_invalid_glyph(codepoint, invalid_glyph)
+    font_wrapper = invalid_glyph.font_wrapper
+    document = font_wrapper.pdf_object.document
+    variant = case
+              when font_wrapper.italic? && font_wrapper.bold? then :bold_italic
+              when font_wrapper.bold? then :bold
+              when font_wrapper.italic? then :italic
+              else :none
+              end
+    document.config['font.fallback'].each do |font_name|
+      font = document.fonts.add(font_name, variant: variant) rescue document.fonts.add(font_name)
+      glyph = font.decode_codepoint(codepoint)
+      unless glyph.kind_of?(HexaPDF::Font::InvalidGlyph)
+        return [glyph]
+      end
+    end
+    [invalid_glyph]
+  end
+
   # The default document specific configuration object.
   #
   # Modify this object if you want to globally change document specific options or if you want to
@@ -247,6 +271,14 @@ module HexaPDF
   #
   #    See PDF2.0 s7.4.1, ADB sH.3 3.3
   #
+  # font.fallback::
+  #    An array of fallback font names to be used when replacing invalid glyphs.
+  #
+  #    The values can be anything that can be passed to Document::Fonts#add. Note that the +variant+
+  #    of a font is determined by looking at the font for which a invalid glyph should be replaced.
+  #
+  #    The default value consists of the built-in fonts ZapfDingbats and Symbol.
+  #
   # font.map::
   #    Defines a mapping from font names and variants to font files.
   #
@@ -263,6 +295,32 @@ module HexaPDF
   #    [italic] For the italic or oblique variant of the font
   #    [bold_italic] For the bold and italic/oblique variant of the font
   #
+  # font.on_invalid_glyph::
+  #    Callback hook when a character cannot be mapped to a glyph and one or more glyphs from a
+  #    different font should be used. Only applies when using high-level text creation facilities.
+  #
+  #    The value needs to be an object that responds to \#call(codepoint, invalid_glyph) where
+  #    +codepoint+ is the Unicode codepoint that cannot be mapped to a valid glyph. The
+  #    +invalid_glyph+ argument is the HexaPDF::Font::InvalidGlyph object that was the result of the
+  #    initial mapping. The return value has to be an array of glyph objects which can be from any
+  #    font but all need to be from the same one.
+  #
+  #    The default implementation is provided by ::font_on_invalid_glyph and uses the
+  #    'font.fallback' configuration option. It is usually not necessary to change this
+  #    configuration option or the 'font.on_missing_glyph' one.
+  #
+  #    Note: The 'font.on_missing_glyph' configuration option does something similar but is
+  #    restricted to returning a single glyph from the same font. Whenever a glyph is not found,
+  #    'font.on_missing_glyph' is invoked first and if an invalid glyph instance is returned, this
+  #    callback hook is invoked when using the layout engine.
+  #
+  #    A typical implementation would use one or more fallback fonts (probably choosing one in the
+  #    correct font variant) for providing the necessary glyph(s):
+  #
+  #      doc.config['font.on_invalid_glyph'] = lambda do |codepoint, glyph|
+  #        [other_font.decode_codepoint(codepoint)]
+  #      end
+  #
   # font.on_missing_glyph::
   #    Callback hook when an UTF-8 character cannot be mapped to a glyph of a font.
   #
@@ -451,9 +509,11 @@ module HexaPDF
                         Crypt: 'HexaPDF::Filter::Crypt',
                         Encryption: 'HexaPDF::Filter::Encryption',
                       },
+                      'font.fallback' => ['ZapfDingbats', 'Symbol'],
                       'font.map' => {},
+                      'font.on_invalid_glyph' => method(:font_on_invalid_glyph),
                       'font.on_missing_glyph' => proc do |char, font_wrapper|
-                        HexaPDF::Font::InvalidGlyph.new(font_wrapper.wrapped_font, char)
+                        HexaPDF::Font::InvalidGlyph.new(font_wrapper, char)
                       end,
                       'font.on_missing_unicode_mapping' => proc do |code_point, font|
                         raise HexaPDF::Error, "No Unicode mapping for code point #{code_point} " \