hexapdf 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 506ca50e79972288ec42dcfb6b31b436500da5c7
-  data.tar.gz: ea88dc0891a1ce15cf40a6d8cc4e6a15e9a05583
+  metadata.gz: 3d9818c9cdb9673d2349c392e35b0b1460841a9d
+  data.tar.gz: cef36589c13850c4b3c1fd6fa976fb605a536bff
 SHA512:
-  metadata.gz: b9a9fd668aa6a2ad42a93a42c7cd6d1e2864a5841cf21bd1191815916a8cca4a229d3a1ed5657ece44edbadd1b82975f974c2dc10ae10bd8ca9a720649ce4dcf
-  data.tar.gz: e2bf96c4158ca5cb440bebe9fb85b3d1a61e7b8caa53a13908ab1ac4b9638488593ff6875382d799477e1fedcea4620f248e71f9970fd6478b1ce94b06a9ed61
+  metadata.gz: e174684958b97a165844e15fdb458172c095cc4c8c1d3a2cfce9a73bd9a3bc1d367e34195d8fbe729cb61b1b71a2ab0dca0fbd91e19cc408510107fafa5c0518
+  data.tar.gz: 27a927ffbd911851187867ae59afbb31b0edabfb2edb6912b682e5af9236711aa51edc683304b0a4b6cdbfba6dd736fee8b6c11766afd8e1b631dc35c04cce30

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## 0.5.0 - 2017-06-24
+
+### Added
+
+* [HexaPDF::Layout::TextBox] for easy positioning and layouting of text
+* [HexaPDF::Layout::LineFragment] for single text line layout calculations
+* [HexaPDF::Layout::TextShaper] for text shaping functionality
+* [HexaPDF::Layout::TextFragment] for basic text metrics calculations
+* [HexaPDF::Layout::InlineBox] for fixed size inline graphics
+* [HexaPDF::Layout::Style] as container for text and graphics styling properties
+* Support for kerning of TrueType fonts via the 'kern' table
+* Support for determining the features provided by a font
+
+### Changed
+
+* Handling of invalid glyphs is done using the special
+  [HexaPDF::Font::InvalidGlyph] class
+* Configuration option 'font.on_missing_glyph'; returns an invalid glyph
+  instead of raising an error
+* Bounding box of TrueType glyphs without contours is set to `[0, 0, 0, 0]`
+* Ligature pairs for AFM fonts are stored like kerning pairs
+* Use TrueType configuration option 'font.true_type.unknown_format' in all
+  places where applicable
+* Allow passing a font object to [HexaPDF::Content::Canvas#font]
+* Handle invalid entry in TrueType format 4 cmap subtable encountered in the
+  wild gracefully
+* Invalid positive descent values in font descriptors are now changed into
+  negative ones by the validation feature
+* Allow specifying the page media box or a page format when adding a new page
+  through [HexaPDF::Document::Pages#add]
+
+### Fixed
+
+* [HexaPDF::Task::Dereference] to work correctly when encountering invalid
+  references
+* [HexaPDF::Tokenizer] and HexaPDF::Content::Tokenizer to parse a solitary
+  plus sign
+* Usage of Strings instead of Symbols for AFM font kerning and ligature pairs
+* Processing the contents of form XObjects in case they don't have a resources
+  dictionary
+* Deletion of valid page node when optimizing page trees with the `hexapdf
+  optimize` command
+* [HexaPDF::Type::FontType0] to always wrap the descendant font even if it is a
+  direct object
+
+
 ## 0.4.0 - 2017-03-19
 
 ### Added

data/CONTRIBUTERS

@@ -1,3 +1,3 @@
   Count Name
 ======= ====
-    741 Thomas Leitner <t_leitner@gmx.at>
+    802 Thomas Leitner <t_leitner@gmx.at>

data/README.md

@@ -43,8 +43,8 @@ documentation, example code and more.
 ## Requirements and Installation
 
 Since HexaPDF is written in Ruby, a working Ruby installation is needed - see the
-[official installation documentation][rbinstall] for details. Note that you need Ruby version 2.3 or
-higher as prior versions are not (officially) supported!
+[official installation documentation][rbinstall] for details. Note that you need Ruby version 2.4 or
+higher as prior versions are not supported!
 
 Apart from Ruby itself the HexaPDF library has no external dependencies. The `hexapdf` application
 has a dependency on `cmdparse`, a command line parsing library.
@@ -69,9 +69,9 @@ Prawn has no such functionality. There is basic support for using a PDF as a tem
 featureful API when it comes to creating content, for individual pages as well as across pages.
 
 Such functionality will be incorporated into HexaPDF in the near future. The main functionality for
-providing such a feature is already available in HexaPDF (the [page canvas API]). What's missing
-(and this is quite big chunk) is automatic box and page layout so that one can say: There is a box
-on this page with these dimensions at this position; show this text in the box.
+providing such a feature is already available in HexaPDF (the [page canvas API]). Additionally,
+laying out text inside a box with line wrapping and such is also supported. What's missing (and this
+is still quite a big chunk) is support for advanced features like tables, page breaking and so on.
 
 So why use HexaPDF?
 

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

data/examples/graphics.rb

@@ -102,9 +102,9 @@ canvas.translate(0, 550) do
   canvas.translate(490, 0) do
     canvas.line_width(1)
     [[[1, 1]],
-     [[3, 1]], 
-     [[3, 3]], 
-     [[5, 1, 1, 1, 1, 1]], 
+     [[3, 1]],
+     [[3, 3]],
+     [[5, 1, 1, 1, 1, 1]],
      [[3, 5], 6]].each_with_index do |(value, phase), index|
       canvas.line_dash_pattern(value, phase || 0)
       canvas.line(20 * index, 0, 20 * index, 100)
@@ -140,7 +140,7 @@ canvas.translate(0, 320) do
   canvas.arc(380, 50, a: 40, b: 20, start_angle: -60, end_angle: 115, inclination: 45)
   canvas.fill
 
-  arc = canvas.graphic_object(:arc, cx: 450, cy: 50, a: 30, b: 30, 
+  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.move_to(450, 50)
@@ -196,10 +196,11 @@ end
 canvas.translate(0, 190) do
   canvas.fill_color(0.3, 0.7, 0.7)
 
-  [[:stroke], [:close_stroke], [:fill, :nonzero], [:fill, :even_odd],
-   [:fill_stroke, :nonzero], [:fill_stroke, :even_odd],
-   [:close_fill_stroke, :nonzero], [:close_fill_stroke, :even_odd],
-   ].each_with_index do |op, index|
+  [
+    [:stroke], [:close_stroke], [:fill, :nonzero], [:fill, :even_odd],
+    [:fill_stroke, :nonzero], [:fill_stroke, :even_odd],
+    [:close_fill_stroke, :nonzero], [:close_fill_stroke, :even_odd]
+  ].each_with_index do |op, index|
     row = (1 - (index / 4))
     column = index % 4
     x = 50 + 80 * column

data/examples/standard_pdf_fonts.rb

@@ -42,7 +42,8 @@ HexaPDF::FontLoader::Standard14::MAPPING.each do |font_name, mapping|
       data = []
       (0..15).each do |x|
         code = y * 16 + x
-        glyph = font.glyph(encoding.name(code)) rescue font.glyph(:space)
+        glyph = font.glyph(encoding.name(code))
+        glyph = font.glyph(:space) if glyph.id == font.wrapped_font.missing_glyph_id
         used_glyphs << glyph.name
         data << glyph << -(2000 - glyph.width)
       end

data/examples/text_box_alignment.rb

@@ -0,0 +1,47 @@
+# ## Text Box Alignment
+#
+# The [HexaPDF::Layout::TextBox] class can be used to easily lay out text inside
+# a rectangular area, with various horizontal and vertical alignment options.
+#
+# The text inside the box 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.
+#
+# Usage:
+# : `ruby text_box_alignment.rb`
+#
+
+require 'hexapdf'
+
+sample_text = "Lorem ipsum dolor sit amet, consectetur adipiscing 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. at".tr("\n", ' ')
+
+doc = HexaPDF::Document.new
+canvas = doc.pages.add.canvas
+canvas.font("Times", size: 10, variant: :bold)
+
+width = 100
+height = 150
+y_base = 800
+box = HexaPDF::Layout::TextBox.create(sample_text, width: width,
+                                      height: height,
+                                      font: doc.fonts.load("Times"))
+
+[:left, :center, :right, :justify].each_with_index do |align, x_index|
+  x = x_index * (width + 20) + 70
+  canvas.text(align.to_s, at: [x + 40, y_base + 15])
+
+  [:top, :center, :bottom].each_with_index do |valign, y_index|
+    y = y_base - (height + 30) * y_index
+    canvas.text(valign.to_s, at: [20, y - height / 2]) if x_index == 0
+
+    box.style.align(align).valign(valign)
+    box.draw(canvas, x, y, fit: true)
+    canvas.stroke_color(128, 0, 0).rectangle(x, y, width, -height).stroke
+  end
+end
+
+doc.write("text_box_alignment.pdf", optimize: true)

data/examples/text_box_inline_boxes.rb

@@ -0,0 +1,56 @@
+# ## Text Box with Inline Boxes
+#
+# The [HexaPDF::Layout::TextBox] class can be used to easily lay out text mixed
+# with inline boxes.
+#
+# Inline boxes are used for showing graphics that follow the flow of the text.
+# This means that their horizontal and their general vertical position is
+# determined by the text layout functionality. However, inline boxes may be
+# vertically aligned to various positions, like the baseline, the top/bottom of
+# the text and the top/bottom of the line.
+#
+# This example shows some text containing emoticons that are replaced with their
+# graphical representation, with normal smileys being aligned to the baseline
+# and winking smileys to the top of the line.
+#
+# Usage:
+# : `ruby text_box_inline_boxes.rb`
+#
+
+require 'hexapdf'
+
+include HexaPDF::Layout
+
+sample_text = "Lorem ipsum :-) dolor sit amet, consectetur adipiscing
+;-) 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 ;-). Duis aute irure
+dolor in reprehenderit in voluptate velit esse cillum :-) dolore eu
+fugiat nulla pariatur. ".tr("\n", ' ') * 4
+
+doc = HexaPDF::Document.new
+emoji_smile = doc.images.add(File.join(__dir__, "emoji-smile.png"))
+emoji_wink = doc.images.add(File.join(__dir__, "emoji-wink.png"))
+size = 10
+
+items = sample_text.split(/(:-\)|;-\))/).map do |part|
+  case part
+  when ':-)'
+    InlineBox.new(size * 2, size * 2, valign: :baseline) do |box, canvas|
+      canvas.image(emoji_smile, at: [0, 0], width: box.width)
+    end
+  when ';-)'
+    InlineBox.new(size, size, valign: :top) do |box, canvas|
+      canvas.image(emoji_wink, at: [0, 0], width: box.width)
+    end
+  else
+    TextFragment.create(part, font: doc.fonts.load("Times"), font_size: 18)
+  end
+end
+
+box = TextBox.new(items: items, width: 500, height: 700)
+box.style.align = :justify
+box.style.line_spacing(:proportional, 1.5)
+box.draw(doc.pages.add.canvas, 50, 800)
+
+doc.write("text_box_inline_boxes.pdf")

data/examples/text_box_line_wrapping.rb

@@ -0,0 +1,57 @@
+# ## Text Box Line Wrapping
+#
+# The [HexaPDF::Layout::TextBox] class can be used to easily lay out text,
+# automatically wrapping it appropriately.
+#
+# Text is broken only at certain characters:
+#
+# * The most important break points are **spaces**.
+#
+# * Lines can be broken at **tabulators** which represent eight spaces.
+#
+# * **Newline characters** are respected when wrapping and introduce a line
+#   break. They have to be removed beforehand if this is not wanted. All Unicode
+#   newline separators are recognized.
+#
+# * **Hyphens** are used as break points, possibly breaking just after them.
+#
+# * In addition to hyphens, **soft-hyphens** can be used to indicate break
+#   points. In contrast to hyphens, soft-hyphens won't be visible unless a line
+#   is broken at its position.
+#
+# * **Zero-width spaces** can be used to indicate break points at any position.
+#
+# * **Non-breaking spaces** can be used to prohibit a break between two words.
+#   It has the same appearance as a space in the PDF.
+#
+# This example shows all these specially handled characters in action, e.g. a
+# hard line break after "Fly-fishing", soft-hyphen in "wandering", tabulator
+# instead of space after "wandering", zero-width space in "fantastic" and
+# non-breaking spaces in "1 0 1".
+#
+# Usage:
+# : `ruby text_box_line_wrapping.rb`
+#
+
+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
+[30, 60, 100, 160].each do |width|
+  box = HexaPDF::Layout::TextBox.create(text, width: width,
+                                        font: doc.fonts.load("Times"))
+  _, height = box.fit
+  box.draw(canvas, x, y)
+  canvas.stroke_color(255, 0, 0).line_width(0.2)
+  canvas.rectangle(x, y, width, -height).stroke
+  y -= height + 5
+end
+
+doc.write("text_box_line_wrapping.pdf", optimize: true)

data/examples/text_box_shapes.rb

@@ -0,0 +1,166 @@
+# ## Text Box Shapes
+#
+# The [HexaPDF::Layout::TextBox] class can be used to easily lay out text, not
+# limiting the area to a rectangle but any shape. There is only one restriction:
+# In the case of arbitrary shapes the vertical alignment has to be "top".
+#
+# Arbitrary shapes boil down to varying line widths and horizontal offsets from
+# left. Imagine a circle: If text is fit in a circle, the line widths start at
+# zero, getting larger and larger until the middle of the cirle. And then they
+# get smaller until zero again. The x-values of the left half circle determine
+# the horizontal offsets.
+#
+# Both, the line widths and the horizontal offsets can be calculated given a
+# certain height, and this is exactly what HexaPDF uses. If the `width` argument
+# to [HexaPDF::Layout::TextBox::new] is an object responding to #call (e.g. a
+# lambda), it is used for determining the line widths. And the `x_offsets`
+# argument can be used in a similar way for the horizontal offsets.
+#
+# This example shows text layed out in various shapes, using the above mentioned
+# techniques.
+#
+# Usage:
+# : `ruby text_box_shapes.rb`
+#
+
+require 'hexapdf'
+
+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)
+
+sample_text = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur
+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", ' ') * 10
+
+########################################################################
+# Circly things on the top
+radius = 100
+circle_top = 800
+half_circle_widths = lambda do |height, line_height|
+  sum = height + line_height
+  if sum <= radius * 2
+    [Math.sqrt(radius**2 - (radius - height)**2),
+     Math.sqrt([radius**2 - (radius - sum)**2, 0].max)].min
+  else
+    0
+  end
+end
+circle_widths = lambda do |height, line_height|
+  2 * half_circle_widths.call(height, line_height)
+end
+left_half_circle_offsets = lambda do |height, line_height|
+  radius - half_circle_widths.call(height, line_height)
+end
+
+# Left: right half circle
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: half_circle_widths,
+                                      height: radius * 2,
+                                      font: doc.fonts.load("Times"))
+box.draw(canvas, 0, circle_top)
+canvas.circle(0, circle_top - radius, radius).stroke
+
+# Center: full circle
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: circle_widths,
+                                      x_offsets: left_half_circle_offsets,
+                                      height: radius * 2,
+                                      font: doc.fonts.load("Times"),
+                                      align: :justify)
+box.draw(canvas, page.box(:media).width / 2.0 - radius, circle_top)
+canvas.circle(page.box(:media).width / 2.0, circle_top - radius, radius).stroke
+
+# Right: left half circle
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: half_circle_widths,
+                                      x_offsets: left_half_circle_offsets,
+                                      height: radius * 2,
+                                      font: doc.fonts.load("Times"),
+                                      align: :right)
+box.draw(canvas, page.box(:media).width - radius, circle_top)
+canvas.circle(page.box(:media).width, circle_top - radius, radius).stroke
+
+
+########################################################################
+# Pointy, diamondy things in the middle
+
+diamond_width = 100
+diamond_top = circle_top - 2 * radius - 50
+half_diamond_widths = lambda do |height, line_height|
+  sum = height + line_height
+  if sum < diamond_width
+    height
+  else
+    [diamond_width * 2 - sum, 0].max
+  end
+end
+full_diamond_widths = lambda do |height, line_height|
+  2 * half_diamond_widths.call(height, line_height)
+end
+left_half_diamond_offsets = lambda do |height, line_height|
+  diamond_width - half_diamond_widths.call(height, line_height)
+end
+
+# Left: right half diamond
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: half_diamond_widths,
+                                      height: 2 * diamond_width,
+                                      font: doc.fonts.load("Times"))
+box.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
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: full_diamond_widths,
+                                      x_offsets: left_half_diamond_offsets,
+                                      height: 2 * diamond_width,
+                                      font: doc.fonts.load("Times"),
+                                      align: :justify)
+left = page.box(:media).width / 2.0 - diamond_width
+box.draw(canvas, left, diamond_top)
+canvas.polyline(left + diamond_width, diamond_top,
+                left + 2 * diamond_width, diamond_top - diamond_width,
+                left + diamond_width, diamond_top - 2 * diamond_width,
+                left, diamond_top - diamond_width).close_subpath.stroke
+
+# Right: left half diamond
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: half_diamond_widths,
+                                      x_offsets: left_half_diamond_offsets,
+                                      height: 2 * diamond_width,
+                                      font: doc.fonts.load("Times"),
+                                      align: :right)
+middle = page.box(:media).width
+box.draw(canvas, middle - diamond_width, diamond_top)
+canvas.polyline(middle, diamond_top,
+                middle - diamond_width, diamond_top - diamond_width,
+                middle, diamond_top - 2 * diamond_width).stroke
+
+########################################################################
+# Sine wave thing at the bottom
+
+sine_wave_height = 200.0
+sine_wave_top = diamond_top - 2 * diamond_width - 50
+sine_wave_offsets = lambda do |height, line_height|
+  [40 * Math.sin(2 * Math::PI * (height / sine_wave_height)),
+   40 * Math.sin(2 * Math::PI * (height + line_height) / sine_wave_height)].max
+end
+sine_wave_widths = lambda do |height, line_height|
+  sine_wave_height + 100 + sine_wave_offsets.call(height, line_height) * -2
+end
+box = HexaPDF::Layout::TextBox.create(sample_text,
+                                      width: sine_wave_widths,
+                                      x_offsets: sine_wave_offsets,
+                                      height: sine_wave_height,
+                                      font: doc.fonts.load("Times"),
+                                      align: :justify)
+middle = page.box(:media).width / 2.0
+box.draw(canvas, middle - (sine_wave_height + 100) / 2, sine_wave_top)
+
+doc.write("text_box_shapes.pdf", optimize: true)