hexapdf 0.35.1 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a7769176f4b753c876ecfb95a6cd2a954249388a7da9e308fbd8c25ba071c9b
-  data.tar.gz: f39b081ab1408fd08a3dff88f8aa3417283e98478b3e9fad60a692afb16e92c1
+  metadata.gz: 464355c84e7dd5636fe34bb0feb96038e06d4e0701d0ce9e915a2a9bddd3c18a
+  data.tar.gz: 8bcebc03512574b0fd71396bbe21330f59cb49e75f2194d1cd47ced0648ef7ad
 SHA512:
-  metadata.gz: 21fcdbd57cdcf436edd1de50f0268d05573b92b70edd1eafeb00af0414eed3cbaa8f107ac1310419a29a113dc5a33ec991fa49a4fa0b47edea1bd2eb7afb0768
-  data.tar.gz: 0c6732024ebd325a4216fe8e4a2fdc69d51365b873ec53c926a9a1e575730cdb6d5f45eea5cd211c1cb2a21afd16cb75f3a1782411a2971eed7afe2f61708dfd
+  metadata.gz: ccfbc72734d74178b1eb49da85bcd364410b12abfbb2d2cd730e6a37176dc85c7b87369bd0463869d6815d911e3428a21b0e18e1492f75d75b59c53a68ebf835
+  data.tar.gz: bc7001b82ec40571b6257575923d0fb5ef4c1011ff4067b3b53c40822240328c461c358084f9de8d5271809d9d85b8bd2de91ce219e211cd84154b3156c7c426

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+## 0.37.0 - 2024-01-29
+
+### Added
+
+* [HexaPDF::Document::Metadata] for working with metadata (reading the info
+  dictionary and writing it as well as the XMP metadata stream)
+
+### Changed
+
+* Minimum Ruby version to be 2.7
+
+### Fixed
+
+* [HexaPDF::FiberDoubleForString#length] to not assume a binary string
+
+
+## 0.36.0 - 2024-01-20
+
+### Added
+
+* [HexaPDF::Layout::ContainerBox] for grouping child boxes together
+
+### Changed
+
+* [HexaPDF::Layout::Frame::FitResult#draw] to allow drawing at an offset
+* [HexaPDF::Layout::Box#fit] to delegate the actual content fitting to the
+  `#fit_content` method
+* [HexaPDF::Document::Layout#box] to allow using the block as drawing block for
+  the base box class
+
+### Fixed
+
+* [HexaPDF::Type::FontSimple#to_utf8] to work in case the font's encoding cannot
+  be retrieved
+
+
 ## 0.35.1 - 2024-01-11
 
 ### Added

data/Rakefile

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

data/lib/hexapdf/configuration.rb

@@ -545,6 +545,7 @@ module HexaPDF
                         column: 'HexaPDF::Layout::ColumnBox',
                         list: 'HexaPDF::Layout::ListBox',
                         table: 'HexaPDF::Layout::TableBox',
+                        container: 'HexaPDF::Layout::ContainerBox',
                       },
                       'page.default_media_box' => :A4,
                       'page.default_media_orientation' => :portrait,
@@ -687,6 +688,7 @@ module HexaPDF
                         XXReference: 'HexaPDF::Type::Form::Reference',
                         XXCIDSystemInfo: 'HexaPDF::Type::CIDFont::CIDSystemInfo',
                         Group: 'HexaPDF::Type::Form::Group',
+                        Metadata: 'HexaPDF::Type::Metadata',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -705,6 +707,7 @@ module HexaPDF
                           Text: 'HexaPDF::Type::Annotations::Text',
                           Link: 'HexaPDF::Type::Annotations::Link',
                           Widget: 'HexaPDF::Type::Annotations::Widget',
+                          XML: 'HexaPDF::Type::Metadata'
                         },
                         XObject: {
                           Image: 'HexaPDF::Type::Image',

data/lib/hexapdf/content/canvas_composer.rb

@@ -118,7 +118,7 @@ module HexaPDF
       #     composer.list(item_spacing: 2) do |list|
       #       composer.document.config['layout.boxes.map'].each do |name, klass|
       #         list.formatted_text([{text: name.to_s, fill_color: "hp-blue-dark"},
-      #                              {text: "\n#{klass}"}, font_size: 7])
+      #                              {text: "\n#{klass}"}], font_size: 6)
       #       end
       #     end
       #   end

data/lib/hexapdf/document/layout.rb

@@ -238,10 +238,12 @@ module HexaPDF
       #
       # The +name+ argument refers to the registered name of the box class that is looked up in the
       # 'layout.boxes.map' configuration option. The +box_options+ are passed as-is to the
-      # initialization method of that box class
+      # initialization method of that box class.
       #
       # If a block is provided, a ChildrenCollector is yielded and the collected children are passed
-      # to the box initialization method via the :children keyword argument.
+      # to the box initialization method via the :children keyword argument. There is one exception
+      # to this rule in case +name+ is +base+: The provided block is passed to the initialization
+      # method of the base box class to function as drawing method.
       #
       # See #text_box for details on +width+, +height+ and +style+ (note that there is no
       # +style_properties+ argument).
@@ -252,12 +254,19 @@ module HexaPDF
       #   layout.box(:column) do |column|            # column box with one child
       #     column.lorem_ipsum
       #   end
-      def box(name, width: 0, height: 0, style: nil, **box_options, &block)
-        if block_given? && !box_options.key?(:children)
-          box_options[:children] = ChildrenCollector.collect(self, &block)
+      #   layout.box(width: 100) do |canvas, box|
+      #     canvas.line(0, 0, box.content_width, box.content_height).stroke
+      #   end
+      def box(name = :base, width: 0, height: 0, style: nil, **box_options, &block)
+        if block_given?
+          if name == :base
+            box_block = block
+          elsif !box_options.key?(:children)
+            box_options[:children] = ChildrenCollector.collect(self, &block)
+          end
         end
         box_class_for_name(name).new(width: width, height: height,
-                                     style: retrieve_style(style), **box_options)
+                                     style: retrieve_style(style), **box_options, &box_block)
       end
 
       # Creates an array of HexaPDF::Layout::TextFragment objects for the given +text+.

data/lib/hexapdf/document/metadata.rb

@@ -0,0 +1,488 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2023 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'securerandom'
+require 'hexapdf/dictionary'
+require 'hexapdf/error'
+
+module HexaPDF
+  class Document
+
+    # This class provides methods for reading and writing the document-level metadata.
+    #
+    # When an instance is created (usually through HexaPDF::Document#metadata), the metadata is read
+    # from the document's information dictionary (see HexaPDF::Type::Info) and made available
+    # through the various methods.
+    #
+    # By default, the metadata is written to the information dictionary as well as to the document's
+    # metadata stream (see HexaPDF::Type::Metadata) once the document is written. This can be
+    # controlled via the #write_info_dict and #write_metdata_stream methods.
+    #
+    # While HexaPDF is able to write an XMP packet (using a limited form) to the document's metadata
+    # stream, it provides no way for reading XMP metadata. If reading functionality or extended
+    # writing functionality is needed, make sure this class does not write the metadata and
+    # read/create the metadata stream yourself.
+    #
+    #
+    # == Caveats
+    #
+    # * Disabling writing to the information dictionary will only prevent parts from being written.
+    #   The #producer is always written to the information dictionary as per the AGPL license terms.
+    #   The #modification_date may be written depending on the arguments to HexaPDF::Document#write.
+    #
+    # * If writing the metadata stream is enabled, any existing metadata stream is completely
+    #   overwritten. This means the metadata stream is *not* updated with the changed information.
+    #
+    #
+    # == Adding custom metadata properties
+    #
+    # All the properties specified for the information dictionary are supported.
+    #
+    # Furthermore, HexaPDF supports writing custom properties to the metadata stream. For this to
+    # work the used XMP namespaces need to be registered using #register_namespace. Additionally,
+    # the types of all used XMP properties need to be registered using #register_property.
+    #
+    # The following types for XMP properties are supported:
+    #
+    # String::
+    #     Maps to the XMP simple string value. Values need to be of type String.
+    #
+    # Date::
+    #     Maps to the XMP simple string value, correctly formatted. Values need to be of type Time,
+    #     Date, or DateTime
+    #
+    # URI::
+    #     Maps to the XMP simple value variant of URI. Values need to be of type String or URI.
+    #
+    # Boolean::
+    #     Maps to the XMP simple string value, correctly formatted. Values need to be either +true+
+    #     or +false+.
+    #
+    # OrderedArray::
+    #     Maps to the XMP ordered array. Values need to be of type Array and items must be XMP
+    #     simple values.
+    #
+    # UnorderedArray::
+    #     Maps to the XMP unordered array. Values need to be of type Array and items must be
+    #     simple values.
+    #
+    # LanguageArray
+    #     Maps to the XMP language alternatives array. Values need to be of type Array and items
+    #     must either be strings (they are associated with the set default language) or
+    #     LocalizedString instances.
+    #
+    #
+    # See: PDF2.0 s14.3, https://www.adobe.com/products/xmp.html
+    class Metadata
+
+      # Represents a localized XMP string, i.e. as string with an attached language.
+      class LocalizedString < String
+        # The language identifier for the string in RFC3066 format.
+        attr_accessor :language
+      end
+
+      # Contains a mapping of predefined prefixes for XMP namespaces for metadata.
+      PREDEFINED_NAMESPACES = {
+        "rdf" => "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+        "xmp" => "http://ns.adobe.com/xap/1.0/",
+        "pdf" => "http://ns.adobe.com/pdf/1.3/",
+        "dc"  => "http://purl.org/dc/elements/1.1/",
+        "x"   => "adobe:ns:meta/",
+      }.freeze
+
+      # Contains a mapping of predefined XMP properties to their types, i.e. from namespace to
+      # property and then type.
+      PREDEFINED_PROPERTIES = {
+        "http://ns.adobe.com/xap/1.0/" => {
+          'CreatorTool' => 'String',
+          'CreateDate' => 'Date',
+          'ModifyDate' => 'Date',
+        }.freeze,
+        "http://ns.adobe.com/pdf/1.3/" => {
+          'Keywords' => 'String',
+          'Producer' => 'String',
+          'Trapped' => 'Boolean',
+        }.freeze,
+        "http://purl.org/dc/elements/1.1/" => {
+          'creator' => 'OrderedArray',
+          'description' => 'LanguageArray',
+          'title' => 'LanguageArray',
+        }.freeze,
+      }.freeze
+
+
+      # Creates a new Metadata object for the given PDF document.
+      def initialize(document)
+        @document = document
+        @namespaces = PREDEFINED_NAMESPACES.dup
+        @properties = PREDEFINED_PROPERTIES.transform_values {|value| value.dup}
+        @default_language = document.catalog[:Lang] || 'en'
+        @metadata = Hash.new {|h, k| h[k] = {} }
+        write_info_dict(true)
+        write_metadata_stream(true)
+        @document.register_listener(:complete_objects, &method(:write_metadata))
+        parse_metadata
+      end
+
+      # :call-seq:
+      #   metadata.default_language          -> language
+      #   metadata.default_language(value)   -> value
+      #
+      # Returns the default language in RFC3066 format used for unlocalized strings if no argument
+      # is given. Otherwise sets the default language to the given language.
+      #
+      # The initial default lanuage is taken from the document catalog's /Lang entry. If that is not
+      # set, the default language is assumed to be English ('en').
+      def default_language(value = :UNSET)
+        if value == :UNSET
+          @default_language
+        else
+          @default_language = value
+        end
+      end
+
+      # Returns +true+ if the information dictionary should be written.
+      def write_info_dict?
+        @write_info_dict
+      end
+
+      # Makes HexaPDF write the information dictionary if +value+ is +true+.
+      #
+      # See the class documentation for caveats.
+      def write_info_dict(value)
+        @write_info_dict = value
+      end
+
+      # Returns +true+ if the metadata stream should be written.
+      def write_metadata_stream?
+        @write_metadata_stream
+      end
+
+      # Makes HexaPDF write the metadata stream if +value+ is +true+.
+      #
+      # See the class documentation for caveats.
+      def write_metadata_stream(value)
+        @write_metadata_stream = value
+      end
+
+      # Registers the +prefix+ for the given namespace +uri+.
+      def register_namespace(prefix, uri)
+        @namespaces[prefix] = uri
+      end
+
+      # Returns the namespace URI associated with the given prefix.
+      def namespace(ns)
+        @namespaces.fetch(ns) do
+          raise HexaPDF::Error, "Namespace prefix '#{ns}' not registered"
+        end
+      end
+
+      # Registers the +property+ for the namespace specified via +prefix+ as the given +type+.
+      #
+      # The argument +type+ has to be one of the following: 'String', 'Date', 'URI', 'Boolean',
+      # 'OrderedArray', 'UnorderedArray', or 'LanguageArray'.
+      def register_property_type(prefix, property, type)
+        (@properties[namespace(prefix)] ||= {})[property] = type
+      end
+
+      # :call-seq:
+      #   metadata.property(ns_prefix, name)           -> property_value
+      #   metadata.property(ns_prefix, name, value)    -> value
+      #
+      # Returns the value for the property specified via the namespace prefix +ns_prefix+ and +name+
+      # if the +value+ argument is not provided. Otherwise sets the property to +value+.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      def property(ns, property, value = :UNSET)
+        ns = @metadata[namespace(ns)]
+        if value == :UNSET
+          ns[property]
+        elsif value.nil?
+          ns.delete(property)
+        else
+          ns[property] = value
+        end
+      end
+
+      # :call-seq:
+      #   metadata.title          -> title or nil
+      #   metadata.title(value    -> value
+      #
+      # Returns the document's title if no argument is given. Otherwise sets the document's title to
+      # the given value.
+      #
+      # The language for the title is specified via #default_language.
+      #
+      # The value +nil+ is returned if the property is not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name dc:title.
+      def title(value = :UNSET)
+        property('dc', 'title', value)
+      end
+
+      # :call-seq:
+      #   metadata.author           -> author or nil
+      #   metadata.author(value)    -> value
+      #
+      # Returns the name of the person who created the document (author) if no argument is given.
+      # Otherwise sets the author to the given value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name dc:creator.
+      def author(value = :UNSET)
+        property('dc', 'creator', value)
+      end
+
+      # :call-seq:
+      #   metadata.subject           -> subject or nil
+      #   metadata.subject(value)    -> value
+      #
+      # Returns the subject of the document if no argument is given. Otherwise sets the subject to
+      # the given value.
+      #
+      # The language for the subject is specified via #default_language.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name dc:description.
+      def subject(value = :UNSET)
+        property('dc', 'description', value)
+      end
+
+      # :call-seq:
+      #   metadata.keywords           -> keywords or nil
+      #   metadata.keywords(value)    -> value
+      #
+      # Returns the keywords associated with the document if no argument is given. Otherwise sets
+      # keywords to the given value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name pdf:Keywords.
+      def keywords(value = :UNSET)
+        property('pdf', 'Keywords', value)
+      end
+
+      # :call-seq:
+      #   metadata.creator           -> creator or nil
+      #   metadata.creator(value)    -> value
+      #
+      # Returns the name of the PDF processor that created the original document from which this PDF
+      # was converted if no argument is given. Otherwise sets the name of the creator tool to the
+      # given value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name xmp:CreatorTool.
+      def creator(value = :UNSET)
+        property('xmp', 'CreatorTool', value)
+      end
+
+      # :call-seq:
+      #   metadata.producer           -> producer or nil
+      #   metadata.producer(value)    -> value
+      #
+      # Returns the name of the PDF processor that converted the original document to PDF if no
+      # argument is given. Otherwise sets the name of the producer to the given value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name pdf:Producer.
+      def producer(value = :UNSET)
+        property('pdf', 'Producer', value)
+      end
+
+      # :call-seq:
+      #   metadata.creation_date           -> creation_date or nil
+      #   metadata.creation_date(value)    -> value
+      #
+      # Returns the date and time (a Time object) the document was created if no argument is given.
+      # Otherwise sets the creation date to the given value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name xmp:CreateDate.
+      def creation_date(value = :UNSET)
+        property('xmp', 'CreateDate', value)
+      end
+
+      # :call-seq:
+      #   metadata.modification_date           -> modification_date or nil
+      #   metadata.modification_date(value)    -> value
+      #
+      # Returns the date and time (a Time object) the document was most recently modified if no
+      # argument is given. Otherwise sets the modification date to the given value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name xmp:ModifyDate.
+      def modification_date(value = :UNSET)
+        property('xmp', 'ModifyDate', value)
+      end
+
+      # :call-seq:
+      #   metadata.trapped           -> trapped or nil
+      #   metadata.trapped(value)    -> value
+      #
+      # Returns +true+ if the document has been modified to include trapping information if no
+      # argument is given. Otherwise sets the trapped status to the given boolean value.
+      #
+      # The value +nil+ is returned if the property ist not set. And by using +nil+ as +value+ the
+      # property is deleted from the metadata.
+      #
+      # This metadata property is represented by the XMP name pdf:Trapped.
+      def trapped(value = :UNSET)
+        property('pdf', 'Trapped', value)
+      end
+
+      private
+
+      # Parses the metadata from the information dictionary into the internal data structure.
+      def parse_metadata
+        info_dict = @document.trailer.info
+        ns_dc = namespace('dc')
+        ns_xmp = namespace('xmp')
+        ns_pdf = namespace('pdf')
+        @metadata[ns_dc]['title'] = info_dict[:Title] if info_dict.key?(:Title)
+        @metadata[ns_dc]['creator'] = info_dict[:Author] if info_dict.key?(:Author)
+        @metadata[ns_dc]['description'] = info_dict[:Subject] if info_dict.key?(:Subject)
+        @metadata[ns_xmp]['CreatorTool'] = info_dict[:Creator] if info_dict.key?(:Creator)
+        @metadata[ns_xmp]['CreateDate'] = info_dict[:CreationDate] if info_dict.key?(:CreationDate)
+        @metadata[ns_xmp]['ModifyDate'] = info_dict[:ModDate] if info_dict.key?(:ModDate)
+        @metadata[ns_pdf]['Keywords'] = info_dict[:Keywords] if info_dict.key?(:Keywords)
+        @metadata[ns_pdf]['Producer'] = info_dict[:Producer] if info_dict.key?(:Producer)
+        if info_dict.key?(:Trapped) && info_dict[:Trapped] != :Unknown
+          @metadata[ns_pdf]['Trapped'] = (info_dict[:Trapped] == :True)
+        end
+      end
+
+      # Writes the metadata to the specified destinations.
+      def write_metadata
+        ns_dc = namespace('dc')
+        ns_xmp = namespace('xmp')
+        ns_pdf = namespace('pdf')
+
+        if write_info_dict?
+          info_dict = @document.trailer.info
+          info_dict[:Title] = Array(@metadata[ns_dc]['title']).first
+          info_dict[:Author] = Array(@metadata[ns_dc]['creator']).join(', ')
+          info_dict[:Subject] = Array(@metadata[ns_dc]['description']).first
+          info_dict[:Creator] = @metadata[ns_xmp]['CreatorTool']
+          info_dict[:CreationDate] = @metadata[ns_xmp]['CreateDate']
+          info_dict[:ModDate] = @metadata[ns_xmp]['ModifyDate']
+          info_dict[:Keywords] = @metadata[ns_pdf]['Keywords']
+          info_dict[:Producer] = @metadata[ns_pdf]['Producer']
+          info_dict[:Trapped] = @metadata[ns_pdf]['Trapped'] ? :True : :False
+        end
+
+        if write_metadata_stream?
+          descriptions = @metadata.map do |namespace, values|
+            xmp_description(@namespaces.key(namespace), values)
+          end.join("\n")
+          obj = @document.catalog[:Metadata] ||= @document.add({Type: :Metadata, Subtype: :XML})
+          obj.stream = xmp_packet(descriptions)
+        end
+      end
+
+      # Creates an XMP packet with the given payload +data+.
+      def xmp_packet(data)
+        <<~XMP
+        <?xpacket begin="\u{FEFF}" id="#{SecureRandom.uuid.tr('-', '')}"?>
+        <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+        #{data}
+        </rdf:RDF>
+        <?xpacket end="r"?>
+        XMP
+      end
+
+      # Creates an 'rdf:Description' element for all metadata +values+ with the given +ns_prefix+.
+      def xmp_description(ns_prefix, values)
+        values = values.map do |name, value|
+          str = +"<#{ns_prefix}:#{name}"
+          case (property_type = @properties[namespace(ns_prefix)][name])
+          when 'String'
+            str << ">#{xmp_escape(value)}</#{ns_prefix}:#{name}>"
+          when 'Date'
+            str << ">#{xmp_date(value)}</#{ns_prefix}:#{name}>"
+          when 'URI'
+            str << " rdf:resource=\"#{xmp_escape(value.to_s)}\" />"
+          when 'Boolean'
+            str << ">#{value ? 'True' : 'False'}</#{ns_prefix}:#{name}>"
+          when 'LanguageArray'
+            value = Array(value).map do |item|
+              lang = item.respond_to?(:language) ? item.language : default_language
+              "<rdf:li xml:lang=\"#{lang}\">#{xmp_escape(item)}</rdf:li>"
+            end.join("\n")
+            str << "><rdf:Alt>\n#{value}\n</rdf:Alt></#{ns_prefix}:#{name}>"
+          when 'OrderedArray', 'UnorderedArray'
+            value = Array(value).map {|item| "<rdf:li>#{xmp_escape(item)}</rdf:li>" }.join("\n")
+            el_type = (property_type == 'OrderedArray' ? 'Seq' : 'Bag')
+            str << "><rdf:#{el_type}>\n#{value}\n</rdf:#{el_type}></#{ns_prefix}:#{name}>"
+          end
+          str
+        end.join("\n")
+        <<~XMP.strip
+        <rdf:Description rdf:about="" xmlns:#{ns_prefix}="#{xmp_escape(namespace(ns_prefix))}">
+        #{values}
+        </rdf:Description>
+        XMP
+      end
+
+      # Escapes the given value so as to be usable as XMP simple value.
+      def xmp_escape(value)
+        value.gsub(/<|>|"/, {'<' => '&lt;', '>' => '&gt;', '"' => '&quot;'})
+      end
+
+      # Formats the given date-time object (Time, Date, or DateTime) to be a valid XMP date-time
+      # value.
+      def xmp_date(date)
+        date.strftime("%Y-%m-%dT%H:%M:%S%:z")
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/document.rb

@@ -120,6 +120,7 @@ module HexaPDF
     autoload(:Files, 'hexapdf/document/files')
     autoload(:Destinations, 'hexapdf/document/destinations')
     autoload(:Layout, 'hexapdf/document/layout')
+    autoload(:Metadata, 'hexapdf/document/metadata')
 
     # :call-seq:
     #   Document.open(filename, **docargs)                   -> doc
@@ -486,6 +487,16 @@ module HexaPDF
       pdf_data ? @cache[pdf_data].clear : @cache.clear
     end
 
+    # Returns the Metadata object that provides a convenience interface for working with the
+    # document metadata.
+    #
+    # Note that invoking this method means that, depending on the settings, the info dictionary as
+    # well as the metadata stream will be overwritten when the document gets written. See the
+    # "Caveats" section in the Metadata documentation.
+    def metadata
+      @metadata ||= Metadata.new(self)
+    end
+
     # Returns the Pages object that provides convenience methods for working with the pages of the
     # PDF file.
     #
@@ -706,13 +717,17 @@ module HexaPDF
     #   Optimize the file size by using object and cross-reference streams. This will raise the PDF
     #   version to at least 1.5.
     def write(file_or_io, incremental: false, validate: true, update_fields: true, optimize: false)
-      dispatch_message(:complete_objects)
-
       if update_fields
         trailer.update_id
-        trailer.info[:ModDate] = Time.now
+        if @metadata
+          metadata.modification_date(Time.now)
+        else
+          trailer.info[:ModDate] = Time.now
+        end
       end
 
+      dispatch_message(:complete_objects)
+
       if validate
         self.validate(auto_correct: true) do |msg, correctable, obj|
           next if correctable

data/lib/hexapdf/filter.rb

@@ -69,11 +69,11 @@ module HexaPDF
       @block_used = false
     end
 
-    # Returns the length of the wrapped string.
+    # Returns the length in bytes of the wrapped string.
     #
     # May only be called before #resume!
     def length
-      str.length
+      str.bytesize
     end
 
     # Returns +true+ if #resume has not yet been called.