hexapdf 0.32.1 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bee477049a8d45aa858093fa683fef19c4760626c3368bf782b74ca10c26d4e1
-  data.tar.gz: e543e4d73eaf80d6f6e434e499715de454f43fb7dae789773282236c2154bc57
+  metadata.gz: 689e6d8b70951307055c635c744a85bcade50f7065af32b35bd5fd15230cdf4e
+  data.tar.gz: a4186126b30e18ad629db5e176be38f81b7367c72c369d8e715a1e952ad49298
 SHA512:
-  metadata.gz: d2204bac09267cc3459511a4580480b6157dc5eceafd34c61881dbbcc5c52cc457e7862b3d888d0aa5b8260470b38febf2779ee442f697ce971f82044d81f7ee
-  data.tar.gz: b77bbcb040ab16e98d3023447a96d7d942a8c80613969bece44ee96427d9235d6db25446dc1ddf6db6ba1f9d0010f4d4f076fdc7ee189947e7ab4cf94a871807
+  metadata.gz: 05ad5c0f6b7819499ef0f013d28c7ee821f94cdb02f3487d27bd91089c5238c3b5b91d25ed8be0dc9b548a1e3daae17dea96171f38522587afe6b0aed47d8585
+  data.tar.gz: 51119d2f079f827271378fc9a36310ff3abcda221113096cae0fe4abee42bf2421b6ac73232fe586d9cfcf0045b5f238bd8ff69491d6f6329decc77bba0285ff

data/CHANGELOG.md

@@ -1,3 +1,75 @@
+## 0.33.0 - 2023-08-02
+
+### Added
+
+* [HexaPDF::Layout::TableBox] for rendering tables
+* [HexaPDF::Document::Layout#table_box] for easier table box creation
+* [HexaPDF::Content::GraphicObject::EndpointArc#max_curves] for setting the
+  approximation accuracy
+* [HexaPDF::Importer::copy] for completely copying (including referenced
+  indirect objects) a single PDF object (which may be from the same document)
+* [HexaPDF::Layout::Style::Border#draw_on_bounds] for drawing the border on the
+  bounds instead of inside
+* [HexaPDF::MissingGlyphError] for better error messages when a font is missing
+  a glyph
+* [HexaPDF::Font::Type1Wrapper#custom_glyph] and
+  [HexaPDF::Font::TrueTypeWrapper#custom_glyph] for custom glyph creation
+* [HexaPDF::FiberDoubleForString] to avoid creating real `Fiber` instances when
+  not necessary
+* Support for drawing `Geom2D::Rectangle` instances via the :geom2d graphic
+  object
+* Optional argument `apply_first_text_indent` to
+  [HexaPDF::Layout::TextLayouter#fit]
+
+### Changed
+
+* [HexaPDF::Layout::Frame] to use more efficient `Geom2D::Rectangle` class
+* Internal constant `HexaPDF::Content::ColorSpace::CSS_COLOR_NAMES` changed to
+  [HexaPDF::Content::ColorSpace::COLOR_NAMES]
+* Constructor of [HexaPDF::Layout::PageStyle] to allow setting `next_style`
+  attribute
+* The encryption dictionary is now validated before using it for decryption
+* Changed encryption permissions to be compatible to PDF 2.0 by always
+  activating the "extract content" permission
+* Digital signature creation in case of signature widgets containing images to
+  work around bug in Adobe Acrobat
+* [HexaPDF::Type::Page#each_annotation] and
+  [HexaPDF::Type::Page#flatten_annotations] to process certain invalid /Annot
+  keys without errors
+
+### Fixed
+
+**Breaking change**: [HexaPDF::Object::make_direct] now needs the document
+  instance as second argument to correctly resolve references
+* [HexaPDF::Layout::ColumnBox], [HexaPDF::Layout::ListBox] and
+  [HexaPDF::Layout::ImageBox] to correctly respond to `#empty?`
+* [HexaPDF::Layout::ColumnBox] and [HexaPDF::Layout::ListBox] to take different
+  final box positions into account
+* [HexaPDF::Content::Canvas#text] to set the leading only when multiple lines
+  are drawn
+* [HexaPDF::Layout::TextBox#split] to use float comparison
+* Validation of standard encryption dictionary to auto-correct invalid /U and
+  /O fields in case they are padded with zeros
+* [HexaPDF::Document#wrap] handling of sub-type mapping in case of missing type
+* [HexaPDF::Type::AcroForm::AppearanceGenerator] to also take a text field
+  widget's width into account when auto-sizing
+* [HexaPDF::Layout::TextBox] to correctly handle text indentation for split
+  boxes
+
+
+## 0.32.2 - 2023-05-06
+
+### Changed
+
+* Cross-reference table reconstruction to be more relaxed concerning the
+  `endobj` keyword
+
+### Fixed
+
+* [HexaPDF::Type::ObjectStream] to not compress any encryption dictionary
+  instead of only the current one
+
+
 ## 0.32.1 - 2023-04-20
 
 ### Added
@@ -25,7 +97,7 @@
 ### Added
 
 * [HexaPDF::Document::Layout#method_missing] for more convenient box creation
-* [HexaPDF::Document::Composer#method_missing] for more convenient box drawing
+* [HexaPDF::Composer#method_missing] for more convenient box drawing
 * [HexaPDF::Document::Layout#inline_box] for easy creation of inline boxes
 * [HexaPDF::Type::OutlineItem#open?] for getting the open state of an outline
   item
@@ -52,6 +124,8 @@
 
 * [HexaPDF::Layout::PageStyle] for collecting all styling information for pages
 * [HexaPDF::Composer#page_style] for configuring different page styles
+* Configuration option 'filter.flate.on_error' for handling potentially
+  recoverable flate errors
 
 ### Changed
 
@@ -71,6 +145,7 @@
   deleted
 * `HexaPDF::Type::Page#perform_validation` to set a /MediaBox for invalid pages
   that don't have one
+* Parsing of invalid flate encoded streams that can potentially be recovered
 
 
 ## 0.30.0 - 2023-02-13

data/README.md

@@ -13,6 +13,9 @@ In short, it allows
 * **securing** PDF files by encrypting or signing them and
 * **optimizing** PDF files for smaller file size or other criteria.
 
+HexaPDF is available under two license, the AGPL and a commercial license, see the [License
+section](#License) for details.
+
 
 ## Features
 
@@ -156,6 +159,12 @@ dependencies as well as make sure that all applications needed for the tests are
 AGPL - see the LICENSE file for licensing details. Commercial licenses are available at
 <https://gettalong.at/hexapdf/>.
 
+A commercial license is needed as soon as HexaPDF is distributed with your software or remotely
+accessed via a network and you don't provide the source code of your application under the AGPL. For
+example, if you serve PDFs on the fly in a web application.
+
+Contact <sales@gettalong.at> for more information!
+
 Some included files have a different license:
 
 * For the license of the included AFM files in the `data/hexapdf/afm` directory, see the file

data/examples/002-graphics.rb

@@ -29,8 +29,8 @@ end
 
 # Basic transformations: translate, scale, rotate, skew
 canvas.translate(0, 710) do
-  normal_color = [0.7, 0.7, 0.3]
-  transformed_color = [0.3, 0.7, 0.7]
+  normal_color = "black"
+  transformed_color = "hp-blue"
 
   canvas.translate(50, 0) do
     transformation_shape(canvas, normal_color)
@@ -134,7 +134,7 @@ canvas.translate(0, 320) do
   canvas.arc(180, 50, a: 40, b: 20, start_angle: -60, end_angle: 115, inclination: 45)
   canvas.stroke
 
-  canvas.fill_color(0.4, 0.3, 0.4)
+  canvas.fill_color("hp-blue")
   canvas.arc(250, 50, a: 10, start_angle: -60, end_angle: 115)
   canvas.arc(300, 50, a: 40, b: 20, start_angle: -60, end_angle: 115)
   canvas.arc(380, 50, a: 40, b: 20, start_angle: -60, end_angle: 115, inclination: 45)
@@ -142,13 +142,13 @@ canvas.translate(0, 320) do
 
   arc = canvas.graphic_object(:arc, cx: 450, cy: 50, a: 30, b: 30,
                               start_angle: -30, end_angle: 105)
-  canvas.fill_color(0.4, 0.3, 0.4)
+  canvas.fill_color("hp-blue")
   canvas.move_to(450, 50)
   canvas.line_to(*arc.start_point)
   arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
   canvas.fill
   arc.configure(start_angle: 105, end_angle: -30)
-  canvas.fill_color(0.3, 0.7, 0.7)
+  canvas.fill_color("hp-orange")
   canvas.move_to(450, 50)
   canvas.line_to(*arc.start_point)
   arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
@@ -156,13 +156,13 @@ canvas.translate(0, 320) do
 
   arc = canvas.graphic_object(:arc, cx: 530, cy: 50, a: 40, b: 20,
                               start_angle: -30, end_angle: 105)
-  canvas.fill_color(0.4, 0.3, 0.4)
+  canvas.fill_color("hp-blue")
   canvas.move_to(530, 50)
   canvas.line_to(*arc.start_point)
   arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
   canvas.fill
   arc.configure(start_angle: 105, end_angle: -30)
-  canvas.fill_color(0.7, 0.7, 0.3)
+  canvas.fill_color("hp-orange")
   canvas.move_to(530, 50)
   canvas.line_to(*arc.start_point)
   arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
@@ -194,7 +194,7 @@ end
 # fill nonzero and stroke, close fill even-odd and stroke, clip even-odd, clip
 # nonzero
 canvas.translate(0, 190) do
-  canvas.fill_color(0.3, 0.7, 0.7)
+  canvas.fill_color("hp-blue")
 
   [
     [:stroke], [:close_stroke], [:fill, :nonzero], [:fill, :even_odd],
@@ -212,8 +212,6 @@ canvas.translate(0, 190) do
     end
   end
 
-  canvas.fill_color(0.7, 0.7, 0.3)
-
   [:even_odd, :nonzero].each_with_index do |op, index|
     canvas.translate(370 + 110 * index, 20) do
       canvas.circle(50, 50, 50)
@@ -228,7 +226,7 @@ end
 
 # Some composite shapes, an image and a form XObject
 canvas.translate(0, 80) do
-  canvas.fill_color(0.3, 0.7, 0.7)
+  canvas.fill_color("hp-blue")
   canvas.rectangle(50, 0, 80, 80, radius: 80)
   canvas.fill
 
@@ -237,14 +235,14 @@ canvas.translate(0, 80) do
 
   canvas.line_width(0.5)
   canvas.opacity(fill_alpha: 0.5, stroke_alpha: 0.2) do
-    canvas.fill_color('AA8888').draw(solid).fill_stroke
-    canvas.fill_color('88AA88').draw(solid, start_angle: 130, end_angle: 220).fill_stroke
-    canvas.fill_color('8888AA').draw(solid, start_angle: 220, end_angle: 10).fill_stroke
+    canvas.fill_color("hp-blue").draw(solid).fill_stroke
+    canvas.fill_color("hp-orange").draw(solid, start_angle: 130, end_angle: 220).fill_stroke
+    canvas.fill_color("hp-teal").draw(solid, start_angle: 220, end_angle: 10).fill_stroke
 
     solid.configure(inner_a: 0, inner_b: 0, outer_a: 40, outer_b: 40, cx: 290)
-    canvas.fill_color('AA8888').draw(solid, start_angle: 10, end_angle: 130).fill_stroke
-    canvas.fill_color('88AA88').draw(solid, start_angle: 130, end_angle: 220).fill_stroke
-    canvas.fill_color('8888AA').draw(solid, start_angle: 220, end_angle: 10).fill_stroke
+    canvas.fill_color("hp-blue").draw(solid, start_angle: 10, end_angle: 130).fill_stroke
+    canvas.fill_color("hp-orange").draw(solid, start_angle: 130, end_angle: 220).fill_stroke
+    canvas.fill_color("hp-teal").draw(solid, start_angle: 220, end_angle: 10).fill_stroke
 
     canvas.image(File.join(__dir__, 'machupicchu.jpg'), at: [350, 0], height: 80)
   end

data/examples/003-arcs.rb

@@ -19,20 +19,20 @@ radius = 75
 center = [page.box.width * 0.25, page.box.height * 0.85]
 pie = canvas.graphic_object(:solid_arc, cx: center[0], cy: center[1],
                             outer_a: radius, outer_b: radius)
-canvas.fill_color('ddddff')
+canvas.fill_color("hp-orange-light")
 canvas.draw(pie, start_angle: 30, end_angle: 110).fill
-canvas.fill_color('ffdddd')
+canvas.fill_color("hp-teal-light")
 canvas.draw(pie, start_angle: 110, end_angle: 130).fill
-canvas.fill_color('ddffdd')
+canvas.fill_color("hp-blue-light")
 canvas.draw(pie, start_angle: 130, end_angle: 30).fill
 
 arc = canvas.graphic_object(:arc, cx: center[0], cy: center[1],
                             a: radius, b: radius)
-canvas.stroke_color('0000ff')
+canvas.stroke_color("hp-orange")
 canvas.draw(arc, start_angle: 30, end_angle: 110).stroke
-canvas.stroke_color('ff0000')
+canvas.stroke_color("hp-teal")
 canvas.draw(arc, start_angle: 110, end_angle: 130).stroke
-canvas.stroke_color('00ff00')
+canvas.stroke_color("hp-blue-dark")
 canvas.draw(arc, start_angle: 130, end_angle: 30).stroke
 
 # Right pie chart
@@ -40,11 +40,11 @@ center = [page.box.width * 0.75, page.box.height * 0.85]
 canvas.stroke_color('777777')
 pie = canvas.graphic_object(:solid_arc, cx: center[0], cy: center[1],
                             outer_a: radius, outer_b: radius)
-canvas.fill_color('ddddff')
+canvas.fill_color("hp-orange-light")
 canvas.draw(pie, start_angle: 30, end_angle: 110).fill_stroke
-canvas.fill_color('ffdddd')
+canvas.fill_color("hp-teal-light")
 canvas.draw(pie, start_angle: 110, end_angle: 130).fill_stroke
-canvas.fill_color('ddffdd')
+canvas.fill_color("hp-blue-light")
 canvas.draw(pie, start_angle: 130, end_angle: 30).fill_stroke
 
 doc.write('arcs.pdf', optimize: true)

data/examples/009-text_layouter_alignment.rb

@@ -40,7 +40,7 @@ tl = HexaPDF::Layout::TextLayouter.new
 
     tl.style.align(align).valign(valign)
     tl.fit([tf], width, height).draw(canvas, x, y)
-    canvas.stroke_color(128, 0, 0).rectangle(x, y, width, -height).stroke
+    canvas.stroke_color("hp-blue-dark").rectangle(x, y, width, -height).stroke
   end
 end
 

data/examples/010-text_layouter_inline_boxes.rb

@@ -42,13 +42,13 @@ items = sample_text.split(/(:-\)|;-\))/).map do |part|
   case part
   when ':-)'
     InlineBox.create(width: size * 2, height: size * 2, content_box: true,
-                     background_color: [162, 234, 247], padding: 2) do |canvas, box|
+                     background_color: "hp-blue-light", padding: 2) do |canvas, box|
       canvas.image(emoji_smile, at: [0, 0], width: box.content_width)
     end
   when ';-)'
     InlineBox.create(width: size, height: size, content_box: true,
                      valign: :top, padding: 5, margin: [0, 10],
-                     border: {width: [1, 2], color: [200, 40]}) do |canvas, box|
+                     border: {width: [1, 2], color: "hp-blue"}) do |canvas, box|
       canvas.image(emoji_wink, at: [0, 0], width: box.content_width)
     end
   else

data/examples/011-text_layouter_line_wrapping.rb

@@ -49,7 +49,7 @@ layouter = HexaPDF::Layout::TextLayouter.new
 [30, 60, 100, 160].each do |width|
   result = layouter.fit([frag], width, 400)
   result.draw(canvas, x, y)
-  canvas.stroke_color(255, 0, 0).line_width(0.2)
+  canvas.stroke_color("hp-blue-dark").line_width(0.2)
   canvas.rectangle(x, y, width, -result.height).stroke
   y -= result.height + 5
 end

data/examples/012-text_layouter_styling.rb

@@ -44,9 +44,9 @@ base_style = {font: base_font, font_size: 12, text_indent: 20}
 styles = {
   "Fonts | Font Sizes | Colors" => [
     {font: doc.fonts.add("Times", variant: :italic),
-     font_size: 12, fill_color: [0, 0, 255]},
+     font_size: 12, fill_color: "hp-blue-light"},
     {font: doc.fonts.add("Courier"), font_size: 14,
-     fill_color: [0, 255, 0]},
+     fill_color: "hp-orange"},
     {font: doc.fonts.add("Helvetica", variant: :bold),
      font_size: 20, fill_alpha: 0.5},
   ],
@@ -72,16 +72,16 @@ styles = {
     {**base_style, text_rendering_mode: :stroke,
      stroke_width: 0.1},
     {**base_style, font_size: 20, text_rendering_mode: :fill_stroke,
-     stroke_color: [0, 255, 0], stroke_width: 0.7,
+     stroke_color: "hp-orange-light", stroke_width: 0.7,
      stroke_dash_pattern: [0.5, 1, 1.5], stroke_cap_style: :round},
   ],
   "Underlays | Overlays" => [
     {**base_style, underlays: [lambda do |canv, box|
-       canv.fill_color(240, 240, 0).opacity(fill_alpha: 0.5).
+       canv.fill_color("hp-orange-light2").opacity(fill_alpha: 0.5).
          rectangle(0, 0, box.width, box.height).fill
       end]},
     {**base_style, overlays: [lambda do |canv, box|
-       canv.line_width(1).stroke_color([0, 255, 0]).
+       canv.line_width(1).stroke_color("hp-teal-light2").
          line(0, -box.y_min, box.width, box.y_max - box.y_min).stroke
       end]},
   ],
@@ -91,7 +91,7 @@ styles = {
     ]},
     {**base_style, overlays: [
       [:link, uri: "https://hexapdf.gettalong.org",
-       border: [0, 0, 2, [3, 3]], border_color: [89, 150, 220]],
+       border: [0, 0, 2, [3, 3]], border_color: "hp-blue"],
     ]},
     {**base_style, overlays: [
       [:link, file: "text_layouter_styling.pdf", border: true],
@@ -115,7 +115,7 @@ styles.each do |desc, variations|
       fragment(str, base_style)
     end
   end
-  items.unshift(fragment(desc + ": ", fill_color: [255, 0, 0], **base_style))
+  items.unshift(fragment(desc + ": ", fill_color: "hp-blue-dark", **base_style))
   y = draw_text(layouter.fit(items, width, 400), canvas, left, y) - 20
 end
 

data/examples/013-text_layouter_shapes.rb

@@ -31,7 +31,7 @@ doc = HexaPDF::Document.new
 page = doc.pages.add
 canvas = page.canvas
 canvas.font("Times", size: 10, variant: :bold)
-canvas.stroke_color(255, 0, 0).line_width(0.2)
+canvas.stroke_color("hp-blue-dark").line_width(0.2)
 font = doc.fonts.add("Times")
 
 sample_text = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur

data/examples/014-text_in_polygon.rb

@@ -53,7 +53,7 @@ width_spec = WidthFromPolygon.new(polygon)
 result = layouter.fit(items, width_spec, polygon.bbox.height)
 result.draw(canvas, 150, 550)
 canvas.translate(150, 100).
-  stroke_color(255, 0, 0).opacity(stroke_alpha: 0.5).
+  stroke_color("hp-blue-dark").
   line_width(0.5).
   draw(:geom2d, object: polygon)
 

data/examples/015-boxes.rb

@@ -37,13 +37,14 @@ end
 
 canvas = doc.pages.add.canvas
 
-[[1, 140], [5, 190], [15, 240]].each_with_index do |(width, red), row|
-  [[:solid, 140], [:dashed, 177], [:dashed_round, 207],
-   [:dotted, 240]].each_with_index do |(style, green), column|
+[[1, "hp-blue-light"], [5, "hp-teal-light"],
+ [15, "hp-orange-light"]].each_with_index do |(width, color), row|
+  color = canvas.color_from_specification([color])
+  [:solid, :dashed, :dashed_round, :dotted].each_with_index do |style, column|
     box = HexaPDF::Layout::Box.create(
       width: 100, height: 100, content_box: true,
       border: {width: width, style: style},
-      background_color: [red, green, 0],
+      background_color: color.components.map {|c| c + 0.2 * column },
       &annotate_box)
     box.draw(canvas, 20 + 140 * column, 700 - 150 * row)
   end
@@ -54,9 +55,9 @@ box = HexaPDF::Layout::Box.create(
   width: 470, height: 200, content_box: true,
   padding: [20, 5, 10, 15],
   border: {width: [20, 40, 30, 15],
-           color: [[46, 185, 206], [206, 199, 46], [188, 46, 206], [59, 206, 46]],
+           color: ["hp-blue", "hp-orange", "hp-teal", "hp-blue-light"],
            style: [:solid, :dashed, :dashed_round, :dotted]},
-  background_color: [255, 255, 180],
+  background_color: "hp-orange-light2",
   underlays: [
     lambda do |canv, _|
       canv.stroke_color([255, 0, 0]).line_width(10).line_cap_style(:butt).
@@ -66,7 +67,7 @@ box = HexaPDF::Layout::Box.create(
   ],
   overlays: [
     lambda do |canv, _|
-      canv.stroke_color([0, 0, 255]).line_width(5).
+      canv.stroke_color("hp-blue-dark").line_width(5).
         rectangle(10, 10, box.width - 20, box.height - 20).stroke
     end
   ],

data/examples/016-frame_automatic_box_placement.rb

@@ -28,9 +28,9 @@ frame = Frame.new(page_box.left + 20, page_box.bottom + 20,
 
 box_counter = 1
 draw_box = lambda do |**args|
-  b = Box.create(**args, border: {width: 1, color: [[255, 0, 0]]}) do |canv, box|
+  b = Box.create(**args, border: {width: 1, color: "hp-blue-dark"}) do |canv, box|
     canv.save_graphics_state do
-      canv.stroke_color(255, 0, 0)
+      canv.stroke_color("hp-blue-dark")
       canv.line(0, 0, box.content_width, box.content_height).
         line(0, box.content_height, box.content_width, 0).
         stroke

data/examples/017-frame_text_flow.rb

@@ -29,7 +29,8 @@ 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,
-                    border: {width: 1, color: [[255, 0, 0]]})
+                    background_color: "hp-blue-light2",
+                    border: {width: 1, color: "hp-blue-dark"})
 boxes << doc.layout.lorem_ipsum_box(count: 3, position: :flow, align: :justify)
 
 i = 0

data/examples/018-composer.rb

@@ -27,7 +27,7 @@ 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(:image, border: {width: 1}, padding: 5, margin: 10)
-  pdf.style(:link, fill_color: [6, 158, 224], underline: true)
+  pdf.style(:link, fill_color: "hp-blue-dark", underline: true)
   image = File.join(__dir__, 'machupicchu.jpg')
 
   pdf.text(lorem_ipsum * 2)

data/examples/020-column_box.rb

@@ -29,7 +29,8 @@ columns = doc.layout.column(columns: 2, style: {position: :flow}) do |column|
                  style: {margin: [10, 30], position: :float})
     column.box(:base, width: 50, height: 50,
                style: {margin: 20, position: :float, position_hint: :right,
-                       border: {width: 1, color: [[255, 0, 0]]}})
+                       background_color: "hp-blue-light2",
+                       border: {width: 1, color: "hp-blue-dark"}})
     column.lorem_ipsum(count: 2, position: :flow, align: :justify)
   end
 end

data/examples/025-table_box.rb

@@ -0,0 +1,46 @@
+# # Table Box
+#
+# This example shows how [HexaPDF::Layout::TableBox] can be used to
+# create tables.
+#
+# Usage:
+# : `ruby table_box.rb`
+#
+
+require 'hexapdf'
+
+image = File.join(__dir__, 'machupicchu.jpg')
+
+HexaPDF::Composer.create("table_box.pdf") do |composer|
+  # We start with the simplest table
+  data = [['Hello', 'World'], ['How', 'are you?']]
+  composer.table(data)
+
+  # The width of the columns can be specified
+  composer.table(data, column_widths: [100, 50])
+
+  # Besides text a table cell can contain any other element
+  l = composer.document.layout
+  data = [['Text', 'Just simple text'],
+          ['Image', l.image(image)],
+          ['List', l.list {|list| list.text('Hello'); list.text('List')}],
+          ['Columns', l.column {|c| c.lorem_ipsum(count: 4) }]]
+  composer.table(data, column_widths: [50])
+
+  # A table can be split if necessary
+  composer.table([[l.lorem_ipsum(sentences: 1), l.lorem_ipsum(sentences: 1)],
+                  [l.lorem_ipsum, l.lorem_ipsum]])
+
+  # It is possible to specify headers and footers which all split parts
+  # will have
+  composer.column(height: 200) do |column|
+    header = lambda {|table| [[l.text('Header left'), l.text('Header right')]] }
+    footer = lambda {|table| [[l.text('Footer left'), l.text('Footer right')]] }
+    column.table([[l.lorem_ipsum(sentences: 1), l.lorem_ipsum(sentences: 1)],
+                  [l.lorem_ipsum(sentences: 1), l.lorem_ipsum(sentences: 1)],
+                  [l.lorem_ipsum(sentences: 1), l.lorem_ipsum(sentences: 1)],
+                  [l.lorem_ipsum(sentences: 1), l.lorem_ipsum(sentences: 1)]],
+                 header: header, footer: footer)
+
+  end
+end

data/lib/hexapdf/cli/command.rb

@@ -43,6 +43,9 @@ require 'hexapdf/font/true_type'
 module HexaPDF
   module CLI
 
+    # Raised when problems occur on the CLI side of things.
+    class Error < HexaPDF::Error; end
+
     # Base class for all hexapdf commands. It provides utility methods needed by the individual
     # commands.
     class Command < CmdParse::Command
@@ -134,7 +137,7 @@ module HexaPDF
           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}"
+              raise Error, "Validation error for object (#{object.oid},#{object.gen}): #{msg}"
             elsif command_parser.verbosity_info?
               $stderr.puts "#{correctable ? 'Corrected' : 'Ignored'} validation problem " \
                 "for object (#{object.oid},#{object.gen}): #{msg}"
@@ -151,7 +154,7 @@ module HexaPDF
       # HexaPDF::CLI#force is not set.
       def maybe_raise_on_existing_file(filename)
         if !command_parser.force && File.exist?(filename)
-          raise "Output file '#{filename}' already exists, not overwriting. Use --force to " \
+          raise Error, "Output file '#{filename}' already exists, not overwriting. Use --force to " \
             "force writing"
         end
       end

data/lib/hexapdf/cli/form.rb

@@ -97,7 +97,7 @@ module HexaPDF
       def execute(in_file, out_file = nil) #:nodoc:
         maybe_raise_on_existing_file(out_file) if out_file
         if (@fill || @flatten) && !out_file
-          raise "Output file missing"
+          raise Error, "Output file missing"
         end
         with_document(in_file, password: @password, out_file: out_file,
                       incremental: @incremental) do |doc|
@@ -106,7 +106,7 @@ module HexaPDF
           end
 
           if !doc.acro_form
-            raise "This PDF doesn't contain an interactive form"
+            raise Error, "This PDF doesn't contain an interactive form"
           elsif out_file
             doc.acro_form[:NeedAppearances] = @need_appearances unless @need_appearances.nil?
             if @fill || !@flatten
@@ -220,7 +220,7 @@ module HexaPDF
         form = doc.acro_form
         data.each do |name, value|
           field = form.field_by_name(name)
-          raise "Field '#{name}' not found in input PDF" unless field
+          raise Error, "Field '#{name}' not found in input PDF" unless field
           apply_field_value(field, value)
         end
       end
@@ -268,10 +268,10 @@ module HexaPDF
         when :radio_button
           field.field_value = value.to_sym
         else
-          raise "Field type #{field.concrete_field_type} not yet supported"
+          raise Error, "Field type #{field.concrete_field_type} not yet supported"
         end
       rescue StandardError
-        raise "Error while setting '#{field.full_field_name}': #{$!.message}"
+        raise Error, "Error while setting '#{field.full_field_name}': #{$!.message}"
       end
 
       # Iterates over all non-push button fields in page order. If a field appears on multiple

data/lib/hexapdf/cli/inspect.rb

@@ -266,11 +266,11 @@ module HexaPDF
       # Resolves the PDF object from the given string reference and returns it.
       def pdf_object_from_string_reference(str)
         if str.nil?
-          raise "Error: Missing argument object identifier OID[,GEN]"
+          raise Error, "Error: Missing argument object identifier OID[,GEN]"
         elsif !str.match?(/^\d+(,\d+)?$/)
-          raise "Error: Invalid argument: Must be of form OID[,GEN], not '#{str}'"
+          raise Error, "Error: Invalid argument: Must be of form OID[,GEN], not '#{str}'"
         elsif !(obj = @doc.object(pdf_reference_from_string(str)))
-          raise "Error: No object with the given object identifier '#{str}' found"
+          raise Error, "Error: No object with the given object identifier '#{str}' found"
         else
           obj
         end

data/lib/hexapdf/cli.rb

@@ -62,6 +62,10 @@ module HexaPDF
       Application.new.parse(args)
     rescue StandardError => e
       $stderr.puts "Problem encountered: #{e.message}"
+      unless e.kind_of?(HexaPDF::Error)
+        $stderr.puts "--> The problem might indicate a faulty PDF or a bug in HexaPDF."
+        $stderr.puts "--> Please report this at https://github.com/gettalong/hexapdf/issues - thanks!"
+      end
       exit(1)
     end