hexapdf 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e9f612a2b916386baa8a689c47463faf4fff424732101ea75f3bb221c4cf824
-  data.tar.gz: 60384753e3b5ac2da147631c567933e94342115e8423f4fc718a55aac3bc986c
+  metadata.gz: d51b41e4326a58a6c3d51e8ee0ee3ce1ee194199d9967817240dac81205ba573
+  data.tar.gz: ac3ca606173c2fad485bf5df8d5fb8947c33aab2fc28b970516adedf804de5eb
 SHA512:
-  metadata.gz: c9dff3546d3a3636ea4d9a0f9a3d9e649c20c642b6bebb53b8c98adf49a46f6cce11a8cf2d8a0761766ad98fec360c54a52333ecad027ea0694941599266c648
-  data.tar.gz: bbc5c0d5af26c6369009a0ddf8d652b1a562c0d89c64e007f2e294af4f34032fa4524814e1dc19f20213148453f88f79de8def53121bb1fda4e44093458987c7
+  metadata.gz: dea3e27895918e159dedb6b8ff44b5db055e886656d1439d8d927fab57e9b1039489d9234392109b52a881ae67a02716c48a12dba9534e4d7894ab5e4c93251f
+  data.tar.gz: bef1d2e5217562c4772e1dc16a1a38e8342c741a1bcc404cabe203ed07268e8e25c2f5476749a8712362cece9dada4ed91e6e989a88872f7c4d08c3e24298823

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 1.9.0 - 2026-06-07
+
+### Added
+
+* Support for HarfBuzz based text shaping
+* [HexaPDF::Layout::Style#shaping_engine] for specifying the used shaping engine
+* [HexaPDF::Layout::Style#font_script] for specifying the script of text
+* [HexaPDF::Layout::Style#language] for specifying the language of text
+* [HexaPDF::Layout::Style#direction] for specifying the direction of text
+* [HexaPDF::Font::TrueTypeWrapper#filename] for retrieving the filename from
+  which the wrapped font was created
+* Inter as bundled font in variants regular, bold, italic and bold italic
+* [HexaPDF::Type::Annotations::Ink] for ink annotations as well as
+  [HexaPDF::Document::Annotations#create_scribble]
+
+### Changed
+
+* [HexaPDF::Layout::TableBox] to support splitting cells
+* [HexaPDF::Font::CMap::Writer] to support ToUnicode CMaps with mappings from
+  one input code to multiple codepoints
+
+### Fixed
+
+* [HexaPDF::Layout::ContainerBox] to correctly set width and height when
+  splitting
+
+
 ## 1.8.0 - 2026-05-14
 
 ### Added

data/README.md

@@ -177,6 +177,9 @@ Some included files have a different license:
 
 * The file `test/data/fonts/Ubuntu-Title.ttf` is licensed under the SIL Open Font License.
 
+* The files in `data/hexapdf/fonts` are licensed under SIL Open Font License, Version 1.1, see the
+  file `data/hexapdf/fonts/OFL.txt`.
+
 * The AES test vector files in `test/data/aes-test-vectors` have been created using the test vector
   file available from <http://csrc.nist.gov/groups/STM/cavp/block-ciphers.html#test-vectors>.
 

data/Rakefile

@@ -47,7 +47,7 @@ namespace :dev do
   end
 
   task :test_all do
-    versions = `rbenv versions --bare | grep -i ^3.`.split("\n")
+    versions = `rbenv versions --bare | grep -i '^3.[2-9]\\|^4.'`.split("\n")
     versions.each do |version|
       sh "eval \"$(rbenv init -)\"; rbenv shell #{version} && ruby -v && rake test"
     end

data/data/hexapdf/fonts/OFL.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

data/examples/019-acro_form.rb

@@ -4,7 +4,8 @@
 # fields. HexaPDF supports the creation and processing of these forms.
 #
 # This example show-cases how to create the various form field types and their
-# possible standard appearances.
+# possible standard appearances (e.g. setting the background color and border
+# style).
 #
 # The [HexaPDF::Type::AcroForm::Form] and [HexaPDF::Type::AcroForm::Field]
 # classes provide a plethora of convenience methods for working with forms, like
@@ -52,6 +53,7 @@ canvas.text("Text fields", at: [50, 480])
 canvas.text("Single line", at: [70, 450])
 tx = form.create_text_field("Single Line", font_size: 16)
 widget = tx.create_widget(page, Rect: [200, 445, 500, 465])
+widget.background_color("lightyellow").border_style(color: "black", style: [2])
 tx.field_value = "A sample test string!"
 
 canvas.text("Multiline", at: [70, 420])

data/examples/030-pdfa.rb

@@ -13,14 +13,6 @@ require 'hexapdf'
 
 HexaPDF::Composer.create('pdfa.pdf') do |composer|
   composer.document.task(:pdfa)
-  composer.document.config['font.map'] = {
-    'Lato' => {
-      none: '/usr/share/fonts/truetype/lato/Lato-Regular.ttf',
-      bold: '/usr/share/fonts/truetype/lato/Lato-Bold.ttf',
-      italic: '/usr/share/fonts/truetype/lato/Lato-Italic.ttf',
-      bold_italic: '/usr/share/fonts/truetype/lato/Lato-BoldItalic.ttf',
-    },
-  }
 
   company = {
     name: 'Sample Corp Limited',
@@ -29,21 +21,21 @@ HexaPDF::Composer.create('pdfa.pdf') do |composer|
 
   # Define all styles
   composer.styles(
-    base: {font: 'Lato', font_size: 10, line_spacing: 1.3},
+    base: {font: 'Inter', font_size: 10, line_spacing: 1.3},
     top: {font_size: 8},
     top_box: {padding: [100, 0, 0], margin: [0, 0, 10], border: {width: [0, 0, 1]}},
-    header: {font: 'Lato bold', font_size: 20, margin: [50, 0, 20]},
+    header: {font: 'Inter bold', font_size: 20, margin: [50, 0, 20]},
     line_items: {border: {width: 1, color: "eee"}, margin: [20, 0]},
     line_item_cell: {font_size: 8},
     footer: {border: {width: [1, 0, 0], color: "darkgrey"}, padding: [5, 0, 0],
              valign: :bottom},
-    footer_heading: {font: 'Lato bold', font_size: 8, padding: [0, 0, 8]},
+    footer_heading: {font: 'Inter bold', font_size: 8, padding: [0, 0, 8]},
     footer_text: {font_size: 8, fill_color: "darkgrey"},
   )
 
   # Top part
   composer.box(:container, style: :top_box) do |container|
-    container.formatted_text([{text: company[:name], font: 'Lato bold'},
+    container.formatted_text([{text: company[:name], font: 'Inter bold'},
                               " - " + company[:address].join(' - ')], style: :top)
   end
   composer.text("Mega Client\nSmall Lane 5\n67890 Noonestown", mask_mode: :box)
@@ -52,7 +44,7 @@ HexaPDF::Composer.create('pdfa.pdf') do |composer|
            ["Service date:", "2024-02-01"]]
   composer.table(cells, column_widths: [150, 80], style: {align: :right}) do |args|
     args[] = {cell: {border: {width: 0}, padding: 2}, text_align: :right}
-    args[0..-1, 0] = {font: 'Lato bold'}
+    args[0..-1, 0] = {font: 'Inter bold'}
   end
 
   # Middle part
@@ -67,10 +59,11 @@ HexaPDF::Composer.create('pdfa.pdf') do |composer|
   cells << [nil, nil, nil, "€ #{250 * max * (max + 1) / 2},00"]
   composer.table(cells, column_widths: [250, 80], style: :line_items) do |args|
     args[] = {cell: {border: {width: 0}, padding: 8}, style: :line_item_cell}
-    args[0] = {cell: {background_color: "eee"}, font: "Lato bold"}
+    args[0] = {cell: {background_color: "eee"}, font: "Inter bold"}
     args[-1] = {cell: {background_color: "eee", border: {width: [2, 0, 0]}},
-                font: "Lato bold"}
-    args[0..-1, 1..-1] = {text_align: :right}
+                font: "Inter bold"}
+    args[0..-1, 1..-1] = {text_align: :right, shaping_engine: :harfbuzz,
+                          font_features: {tnum: true}}
   end
 
   composer.text("Please transfer the total amount via SEPA transfer to the bank " \

data/examples/034-text_shaping.rb

@@ -0,0 +1,37 @@
+# # Text Shaping
+#
+# The built-in text shaping functionality is very limited. However, it is
+# possible to switch to a HarfBuzz based implementation (using the
+# `harfbuzz-ruby` gem) that supports many languages and scripts as well as
+# OpenType features. Note that this only works with TrueType fonts!
+#
+# In general it is advised to use TrueType font files and enable HarfBuzz as the
+# result is more correct and visually better. The disadvantage is that the
+# additional processing requirements have a slight performance impact.
+#
+# By using the 'font_features' style property it is possible to selectively
+# enable/disable OpenType features like discretionary ligatures. Note that fonts
+# determine which features are on by default (like 'calt' for the Inter font
+# used in this example).
+#
+# Usage:
+# : `ruby text_shaping.rb`
+#
+
+require 'hexapdf'
+
+sample_text = <<EOT.tr("\n", " ")
+This sample shows some OpenType features, like contextual alternatives (2*3 and
+-->), discretionary ligatures (difficult?!), fractions (15/157) or compositions
+(5⃝ ×⃞ 3⃝ =⃞ 1⃝5⃝).
+EOT
+
+HexaPDF::Composer.create('text_shaping.pdf') do |composer|
+  composer.style(:base, font: 'Inter')
+  composer.style(:header, font_bold: true, margin: [10, 0, 0])
+  composer.text('Without HarfBuzz', style: :header)
+  composer.text(sample_text)
+  composer.text('With HarfBuzz', style: :header)
+  composer.text(sample_text, shaping_engine: :harfbuzz,
+                font_features: {dlig: true, frac: true})
+end

data/lib/hexapdf/configuration.rb

@@ -36,6 +36,7 @@
 
 require 'hexapdf/font/invalid_glyph'
 require 'hexapdf/error'
+require 'hexapdf/data_dir'
 
 module HexaPDF
 
@@ -333,6 +334,8 @@ module HexaPDF
   #    [italic] For the italic or oblique variant of the font
   #    [bold_italic] For the bold and italic/oblique variant of the font
   #
+  #    The default value registers the bundled Inter font (see the files in data/hexapdf/fonts).
+  #
   # 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.
@@ -563,7 +566,14 @@ module HexaPDF
                       },
                       'font.default' => 'Times',
                       'font.fallback' => ['ZapfDingbats', 'Symbol'],
-                      'font.map' => {},
+                      'font.map' => {
+                        'Inter' => {
+                          none: File.join(HexaPDF.data_dir, 'fonts', 'Inter-Regular.ttf'),
+                          bold: File.join(HexaPDF.data_dir, 'fonts', 'Inter-Bold.ttf'),
+                          italic: File.join(HexaPDF.data_dir, 'fonts', 'Inter-Italic.ttf'),
+                          bold_italic: File.join(HexaPDF.data_dir, 'fonts', 'Inter-BoldItalic.ttf'),
+                        },
+                      },
                       'font.on_invalid_glyph' => method(:font_on_invalid_glyph),
                       'font.on_missing_glyph' => proc do |char, font_wrapper|
                         HexaPDF::Font::InvalidGlyph.new(font_wrapper, char)
@@ -786,6 +796,7 @@ module HexaPDF
                           Circle: 'HexaPDF::Type::Annotations::Circle',
                           Polygon: 'HexaPDF::Type::Annotations::Polygon',
                           PolyLine: 'HexaPDF::Type::Annotations::Polyline',
+                          Ink: 'HexaPDF::Type::Annotations::Ink',
                           XML: 'HexaPDF::Type::Metadata',
                           GTS_PDFX: 'HexaPDF::Type::OutputIntent',
                           GTS_PDFA1: 'HexaPDF::Type::OutputIntent',
@@ -819,6 +830,7 @@ module HexaPDF
                           Circle: 'HexaPDF::Type::Annotations::Circle',
                           Polygon: 'HexaPDF::Type::Annotations::Polygon',
                           PolyLine: 'HexaPDF::Type::Annotations::Polyline',
+                          Ink: 'HexaPDF::Type::Annotations::Ink',
                         },
                         XXAcroFormField: {
                           Tx: 'HexaPDF::Type::AcroForm::TextField',

data/lib/hexapdf/document/annotations.rb

@@ -205,6 +205,31 @@ module HexaPDF
           border_style(color: 0, width: 1)
       end
 
+      # :call-seq:
+      #   annotations.create_scribble(page, *points)  -> annotation
+      #
+      # Creates an ink annotation on the given page and returns it.
+      #
+      # If +points+ (alternating horizontal and vertical coordinates) are given, the path created
+      # from them is added to the annotation.
+      #
+      # The ink annotation uses a black color and a width of 1pt for the stroke style. It can be
+      # further styled using the convenience methods on the returned annotation object.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_scribble(doc.pages[0], 20, 20, 30, 70, 80, 60, 40, 30).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     regenerate_appearance
+      #
+      # See: Type::Annotations::Ink
+      def create_scribble(page, *points)
+        annot = create_and_add_to_page(:Ink, page)
+        annot.add_path(*points) unless points.empty?
+        annot.border_style(color: 0, width: 1)
+      end
+
       private
 
       # Returns the root of the destinations name tree.

data/lib/hexapdf/font/cmap/writer.rb

@@ -46,8 +46,8 @@ module HexaPDF
         # Maximum number of entries in one section.
         MAX_ENTRIES_IN_SECTION = 100
 
-        # Returns a ToUnicode CMap for the given input code to Unicode codepoint mapping which needs
-        # to be sorted by input codes.
+        # Returns a ToUnicode CMap for the given mapping of input codes to Unicode codepoints and/or
+        # Strings. The mapping needs to be sorted by input codes.
         #
         # Note that the returned CMap always uses a 16-bit input code space!
         def create_to_unicode_cmap(mapping)
@@ -57,9 +57,13 @@ module HexaPDF
 
           result = create_sections("bfchar", chars.size / 2) do |index|
             index *= 2
-            sprintf("<%04X>", chars[index]) << "<" <<
-              ((+'').force_encoding(::Encoding::UTF_16BE) << chars[index + 1]).unpack1('H*') <<
-              ">\n"
+            value = chars[index + 1]
+            value = if value.kind_of?(Integer)
+                      (+'').force_encoding(::Encoding::UTF_16BE) << value
+                    else
+                      value.encode(::Encoding::UTF_16BE)
+                    end
+            sprintf("<%04X>", chars[index]) << "<#{value.unpack1('H*')}>\n"
           end
 
           result << create_sections("bfrange", ranges.size / 3) do |index|
@@ -113,7 +117,9 @@ module HexaPDF
           last_code, last_value = *mapping[0]
           is_range = false
           mapping.slice(1..-1).each do |code, value|
-            if last_code + 1 == code && last_value + 1 == value && code % 256 != 0
+            if last_value.kind_of?(String)
+              chars << last_code << last_value
+            elsif last_code + 1 == code && last_value + 1 == value && code % 256 != 0
               ranges << last_code << nil << last_value unless is_range
               is_range = true
             elsif is_range
@@ -127,10 +133,10 @@ module HexaPDF
           end
 
           # Handle last remaining mapping
-          if is_range
-            ranges[-2] = last_code
-          else
+          if last_value.kind_of?(String) || !is_range
             chars << last_code << last_value
+          else
+            ranges[-2] = last_code
           end
 
           [chars, ranges]

data/lib/hexapdf/font/true_type_wrapper.rb

@@ -184,6 +184,11 @@ module HexaPDF
         !@subsetter.nil?
       end
 
+      # The filename of the wrapped TrueType font object if it was loaded from a file.
+      def filename
+        wrapped_font.io.path
+      end
+
       # Returns a Glyph object for the given glyph ID and +str+ pair.
       #
       # The optional argument +str+ should be the string representation of the glyph. It is possible
@@ -358,9 +363,7 @@ module HexaPDF
       def create_to_unicode_cmap(dict, document)
         stream = HexaPDF::StreamData.new do
           mapping = @encoded_glyphs.map do |glyph, (_, char_code)|
-            # Using 0xFFFD as mentioned in Adobe #5411, last line before section 1.5
-            # TODO: glyph.str assumed to consist of single char, No support for multiple chars
-            [char_code, glyph.str.ord || 0xFFFD]
+            [char_code, glyph.str.length == 1 ? glyph.str.ord : glyph.str]
           end.sort_by!(&:first)
           HexaPDF::Font::CMap.create_to_unicode_cmap(mapping)
         end

data/lib/hexapdf/font_loader.rb

@@ -45,6 +45,53 @@ module HexaPDF
   # needs to be usable by the PDF canvas. See below for details.
   #
   #
+  # == Available Font Loaders
+  #
+  # The following font loaders are available:
+  #
+  # HexaPDF::FontLoader::Standard14::
+  #     This one makes the standard 14 PDF fonts (Helvetica in variants none, italic, bold and bold
+  #     italic; Times in variants none, italic, bold and bold italic; Symbol; and ZapfDingbats)
+  #     available.
+  #
+  #     Usage:
+  #
+  #       canvas.font('Times', variant: :bold)
+  #
+  # HexaPDF::FontLoader::FromFile::
+  #     Interprets the font name as filename and tries to load the font from there. In this case a
+  #     +:variant+ argument cannot be used as the font file is directly specified.
+  #
+  #     Usage:
+  #
+  #       canvas.font('/usr/share/fonts/truetype/hack/Hack-Regular.ttf')
+  #
+  # HexaPDF::FontLoader::VariantFromName:
+  #     This one doesn't really load a font itself but makes it possible to append the variant name
+  #     to the font name. So it resolves e.g. 'Times bold' to the font 'Times' in variant :bold.
+  #
+  #     Usage:
+  #
+  #       canvas.font('Times bold')
+  #
+  # HexaPDF::FontLoader::FromConfiguration
+  #     This font loader defers to FromFile when loading the actual fonts. It allows defining font
+  #     mappings using the configuration option 'font.map' where a font name is mapped to a hash
+  #     that maps variant names to font file names.
+  #
+  #     Usage:
+  #
+  #       doc.config['font.map'] = {
+  #         'Hack' => {
+  #            none: '/usr/share/fonts/ttf/Hack-Regular.ttf',
+  #            bold: '/usr/share/fonts/ttf/Hack-Bold.ttf',
+  #            italic: '/usr/share/fonts/ttf/Hack-Italic.ttf',
+  #            bold_italic: '/usr/share/fonts/ttf/Hack-BoldItalic.ttf',
+  #          },
+  #        }
+  #        canvas.font('Hack', variant: :italic)
+  #
+  #
   # == Implementation of a Font Loader
   #
   # Each font loader is a (stateless) object (normally a module) that has to be callable, i.e. it

data/lib/hexapdf/layout/container_box.rb

@@ -163,15 +163,13 @@ module HexaPDF
         @box_fitter = BoxFitter.new([my_frame])
         children.each {|box| @box_fitter.fit(box) }
 
-        if @box_fitter.success?
+        if @box_fitter.success? || (!@box_fitter.fit_results.empty? && @splitable)
           update_content_width do
             result = @box_fitter.fit_results.max_by {|r| r.mask.x + r.mask.width }
             children.empty? ? 0 : result.mask.x + result.mask.width - my_frame.left
           end
           update_content_height { @box_fitter.content_heights.max }
-          fit_result.success!
-        elsif !@box_fitter.fit_results.empty? && @splitable
-          fit_result.overflow!
+          @box_fitter.success? ? fit_result.success! : fit_result.overflow!
         end
       end
 

data/lib/hexapdf/layout/style.rb

@@ -811,18 +811,76 @@ module HexaPDF
       #   font_features(features = nil)
       #
       # The font features (e.g. kerning, ligatures, ...) that should be applied by the shaping
-      # engine, defaults to {} (i.e. no font features are applied).
+      # engine, defaults to the empty hash {} (i.e. no font features are applied).
       #
-      # Each feature to be applied is indicated by a key with a truthy value.
+      # Each feature can either be activated using `true` as value, deactivated using `false` as
+      # value or set to a specific mode using an integer. What is actually supported depends on the
+      # used shaping engine.
       #
-      # See: HexaPDF::Layout::TextShaper#shape_text for available features.
+      # See: #shaping_engine
       #
       # Examples:
       #
       #   #>pdf-composer100
       #   composer.style(:base, font: ["Times", custom_encoding: true], font_size: 30)
       #   composer.text("Test flight")
-      #   composer.text("Test flight", font_features: {kern: true, liga: true})
+      #   composer.text("Test flight", font_features: {kern: true, liga: false})
+
+      ##
+      # :method: font_script
+      # :call-seq:
+      #   font_script(script = nil)
+      #
+      # The script in which the text is written, defaults to +nil+.
+      #
+      # This is used by the shaping engine to select the correct shaping implementation. If not set,
+      # the script is guessed from the text.
+      #
+      # See: #shaping_engine
+
+      ##
+      # :method: language
+      # :call-seq:
+      #   language(lang = nil)
+      #
+      # The language in which the text is written, defaults to +nil+.
+      #
+      # This is used, for example, by the shaping engine to correctly shape the text.
+      #
+      # See: #shaping_engine
+
+      ##
+      # :method: direction
+      # :call-seq:
+      #   direction(dir = nil)
+      #
+      # The direction of text, defaults to +:ltr+ (possible values are +:ltr+ and +:rtl+).
+      #
+      # This is used by the shaping engine to correctly shape the text.
+      #
+      # See: #shaping_engine
+
+      ##
+      # :method: shaping_engine
+      # :call-seq:
+      #   shaping_engine(engine = nil)
+      #
+      # The shaping engine that should be used, defaults to +:internal+. The other possible value is
+      # +:harfbuzz+.
+      #
+      # When set to +:harfbuzz+, the Rubygem +harfbuzz-ruby+ needs to be installed. If it is not
+      # available, HexaPDF will raise an error.
+      #
+      # See: HexaPDF::Layout::TextShaper for details.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer100
+      #   composer.style(:base, font: 'Inter')
+      #   composer.text("Incoming WAVE!")
+      #   composer.formatted_text(["Incoming WAVE!",
+      #                            {text: " Take Cover!", font_features: {ss06: true}}],
+      #                            shaping_engine: :harfbuzz)
 
       ##
       # :method: text_rendering_mode
@@ -1541,6 +1599,10 @@ module HexaPDF
         [:horizontal_scaling, 100],
         [:text_rise, 0],
         [:font_features, {}],
+        [:font_script, nil],
+        [:language, nil],
+        [:direction, :ltr, {valid_values: [:ltr, :rtl]}],
+        [:shaping_engine, :internal, {valid_values: [:internal, :harfbuzz]}],
         [:text_rendering_mode, "Content::TextRenderingMode::FILL",
          {setter: "Content::TextRenderingMode.normalize(value)"}],
         [:subscript, false,