hexapdf 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7cec7494ffe5e4f8031e5a05f2a31da13741879ff138513f737048880702389
-  data.tar.gz: 238a71920dcd9bde03497a22f0583bf72f11d358176f28217214f86ca835764d
+  metadata.gz: 464355c84e7dd5636fe34bb0feb96038e06d4e0701d0ce9e915a2a9bddd3c18a
+  data.tar.gz: 8bcebc03512574b0fd71396bbe21330f59cb49e75f2194d1cd47ced0648ef7ad
 SHA512:
-  metadata.gz: 7850251dba07dbae11c280bc87852c91aa72e166da7983c4b4a1508a4c76d99306eaacbc108dad8f0ba54246a2fe6648714cd8bfd5f6d9bddeb0ec67abab9867
-  data.tar.gz: dace9a43ef57a0d27d33218ef4dc6503a961edfc2c96c04c16ebeb0d8675e09373c21908d159c992c4d2125499bdd1818acdf1150c86106e23888552210f4fc8
+  metadata.gz: ccfbc72734d74178b1eb49da85bcd364410b12abfbb2d2cd730e6a37176dc85c7b87369bd0463869d6815d911e3428a21b0e18e1492f75d75b59c53a68ebf835
+  data.tar.gz: bc7001b82ec40571b6257575923d0fb5ef4c1011ff4067b3b53c40822240328c461c358084f9de8d5271809d9d85b8bd2de91ce219e211cd84154b3156c7c426

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 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

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

@@ -688,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 => {
@@ -706,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/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.

data/lib/hexapdf/type/annotation.rb

@@ -132,6 +132,77 @@ module HexaPDF
       define_field :StructParent, type: Integer, version: '1.3'
       define_field :OC,           type: Dictionary, version: '1.5'
 
+      ##
+      # :method: flags
+      #
+      # Returns an array of flag names representing the set bit flags for /F.
+      #
+      # The available flags are:
+      #
+      # :invisible or 0::
+      #     Applies only to non-standard annotations. If set, do not render or print the annotation.
+      #
+      # :hidden or 1::
+      #     If set, do not render the annotation or allow interactions.
+      #
+      # :print or 2::
+      #     If set, print the annotation unless the hidden flag is also set. Otherwise never print
+      #     the annotation.
+      #
+      # :no_zoom or 3::
+      #     If set, do not scale the annotation's appearance to match the magnification of the page.
+      #
+      # :no_rotate or 4::
+      #     If set, do not rotate the annotation's appearance to match the rotation of the page.
+      #
+      # :no_view or 5::
+      #     If set, do not render the annotation on the screen or allow interactions.
+      #
+      # :read_only or 6::
+      #     If set, do not allow user interactions.
+      #
+      # :locked or 7::
+      #     If set, do not allow the annotation to be deleted or its properties be modified.
+      #
+      # :toggle_no_view or 8::
+      #     If set, invert the interpretation of the :no_view flag for annotation selection and
+      #     mouse hovering.
+      #
+      # :locked_contents or 9::
+      #     If set, do not allow the contents of the annotation to be modified.
+      #
+
+      ##
+      # :method: flagged?
+      # :call-seq:
+      #   flagged?(flag)
+      #
+      # Returns +true+ if the given flag is set on /F. The argument can either be the flag name or
+      # the bit index.
+      #
+      # See #flags for the list of available flags.
+      #
+
+      ##
+      # :method: flag
+      # :call-seq:
+      #   flag(*flags, clear_existing: false)
+      #
+      # Sets the given flags on /F, given as flag names or bit indices. If +clear_existing+ is
+      # +true+, all prior flags will be cleared.
+      #
+      # See #flags for the list of available flags.
+      #
+
+      ##
+      # :method: unflag
+      # :call-seq:
+      #   flag(*flags)
+      #
+      # Clears the given flags from /F, given as flag names or bit indices.
+      #
+      # See #flags for the list of available flags.
+      #
       bit_field(:flags, {invisible: 0, hidden: 1, print: 2, no_zoom: 3, no_rotate: 4,
                          no_view: 5, read_only: 6, locked: 7, toggle_no_view: 8,
                          locked_contents: 9},

data/lib/hexapdf/type/catalog.rb

@@ -71,7 +71,7 @@ module HexaPDF
       define_field :AA,                type: Dictionary, version: '1.4'
       define_field :URI,               type: Dictionary, version: '1.1'
       define_field :AcroForm,          type: :XXAcroForm, version: '1.2'
-      define_field :Metadata,          type: Stream,     indirect: true, version: '1.4'
+      define_field :Metadata,          type: :Metadata,  indirect: true, version: '1.4'
       define_field :StructTreeRoot,    type: Dictionary, version: '1.3'
       define_field :MarkInfo,          type: :XXMarkInformation, version: '1.4'
       define_field :Lang,              type: String,     version: '1.4'

data/lib/hexapdf/type/metadata.rb

@@ -0,0 +1,63 @@
+# -*- 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 'hexapdf/stream'
+
+module HexaPDF
+  module Type
+
+    # Represents an XMP metadata stream.
+    #
+    # XMP metadata streams may be attached to most PDF objects, though it only makes sense for some
+    # of them.
+    #
+    # There is also a main XMP metadata stream for the whole document that is accessible via the
+    # /Metadata key of the document catalog. That metadata stream should contain the same values as
+    # the PDF's info dictionary and may contain additional entries. This can be accomplished via
+    # HexaPDF::Document#metadata.
+    #
+    # See: PDF2.0 s14.3.2
+    class Metadata < Stream
+
+      define_type :Metadata
+
+      define_field :Type, type: Symbol, default: type, required: true
+      define_field :Subtype, type: Symbol, default: :XML, required: true
+
+    end
+
+  end
+end

data/lib/hexapdf/type.rb

@@ -80,6 +80,7 @@ module HexaPDF
     autoload(:OptionalContentMembership, 'hexapdf/type/optional_content_membership')
     autoload(:OptionalContentProperties, 'hexapdf/type/optional_content_properties')
     autoload(:OptionalContentConfiguration, 'hexapdf/type/optional_content_configuration')
+    autoload(:Metadata, 'hexapdf/type/metadata')
 
   end
 

data/lib/hexapdf/version.rb

@@ -37,6 +37,6 @@
 module HexaPDF
 
   # The version of HexaPDF.
-  VERSION = '0.36.0'
+  VERSION = '0.37.0'
 
 end

data/test/hexapdf/document/test_metadata.rb

@@ -0,0 +1,192 @@
+# -*- encoding: utf-8 -*-
+
+require 'test_helper'
+require 'stringio'
+require 'hexapdf/document'
+
+describe HexaPDF::Document::Metadata do
+  before do
+    @doc = HexaPDF::Document.new
+    @doc.trailer.info[:Title] = 'Title'
+    @metadata = @doc.metadata
+  end
+
+  it "parses the info dictionary on creation" do
+    assert_equal('Title', @metadata.title)
+    @doc.trailer.info[:Trapped] = :Unknown
+    assert_nil(HexaPDF::Document::Metadata.new(@doc).trapped)
+    @doc.trailer.info[:Trapped] = :True
+    assert_equal(true, HexaPDF::Document::Metadata.new(@doc).trapped)
+    @doc.trailer.info[:Trapped] = :False
+    assert_equal(false, HexaPDF::Document::Metadata.new(@doc).trapped)
+  end
+
+  describe "default_language" do
+    it "use the document's language as default" do
+      @doc.catalog[:Lang] = 'de'
+      assert_equal("de", HexaPDF::Document::Metadata.new(@doc).default_language)
+    end
+
+    it "falls back to English if the document doesn't have a default language set" do
+      assert_equal('en', @metadata.default_language)
+    end
+
+    it "allows changing the default language" do
+      @metadata.default_language('de')
+      assert_equal('de', @metadata.default_language)
+    end
+  end
+
+  it "enables writing the info dict by default" do
+    assert(@metadata.write_info_dict?)
+  end
+
+  it "allows setting whether the info dict is written" do
+    @metadata.write_info_dict(false)
+    refute(@metadata.write_info_dict?)
+  end
+
+  it "enables writing the metadata stream by default" do
+    assert(@metadata.write_metadata_stream?)
+  end
+
+  it "allows setting whether the metadata stream is written" do
+    @metadata.write_metadata_stream(false)
+    refute(@metadata.write_metadata_stream?)
+  end
+
+  it "resolves namespace URI via a prefix" do
+    assert_equal('http://www.w3.org/1999/02/22-rdf-syntax-ns#', @metadata.namespace('rdf'))
+  end
+
+  it "allows registering prefixes for namespaces" do
+    err = assert_raises(HexaPDF::Error) { @metadata.namespace('hexa') }
+    assert_match(/prefix.*hexa.*not registered/, err.message)
+    @metadata.register_namespace('hexa', 'hexa:')
+    assert_equal('hexa:', @metadata.namespace('hexa'))
+  end
+
+  it "allows registering property types" do
+    @metadata.register_property_type('dc', 'title', 'Boolean')
+    assert_equal('Boolean', @metadata.instance_variable_get(:@properties)[@metadata.namespace('dc')]['title'])
+  end
+
+  it "allows reading and setting properties" do
+    assert_equal('Title', @metadata.property('dc', 'title'))
+    @metadata.property('dc', 'title', 'another')
+    assert_equal('another', @metadata.property('dc', 'title'))
+    @metadata.property('dc', 'title', nil)
+    assert_nil(@metadata.property('dc', 'title'))
+    refute(@metadata.instance_variable_get(:@metadata)[@metadata.namespace('dc')].key?('title'))
+  end
+
+  it "allows reading and setting all info dictionary properties" do
+    [['title', 'dc', 'title'], ['author', 'dc', 'creator'], ['subject', 'dc', 'description'],
+     ['keywords', 'pdf', 'Keywords'], ['creator', 'xmp', 'CreatorTool'],
+     ['producer', 'pdf', 'Producer'], ['creation_date', 'xmp', 'CreateDate'],
+     ['modification_date', 'xmp', 'ModifyDate'], ['trapped', 'pdf', 'Trapped']].each do |name, ns, property|
+      @metadata.property(ns, property, 'value')
+      assert_equal('value', @metadata.send(name), name)
+      @metadata.send(name, 'modified')
+      assert_equal('modified', @metadata.property(ns, property), name)
+    end
+  end
+
+  describe "metadata writing" do
+    before do
+      @time = Time.now.floor
+      @metadata.title('Title')
+      @metadata.author('Author')
+      @metadata.subject('Subject')
+      @metadata.keywords('Keywords')
+      @metadata.creator('Creator')
+      @metadata.producer('Producer')
+      @metadata.creation_date(@time)
+      @metadata.modification_date(@time)
+      @metadata.trapped(true)
+    end
+
+    it "writes the info dictionary properties" do
+      info = @doc.trailer.info
+      @doc.write(StringIO.new, update_fields: false)
+      assert_equal('Title', info[:Title])
+      assert_equal('Author', info[:Author])
+      assert_equal('Subject', info[:Subject])
+      assert_equal('Keywords', info[:Keywords])
+      assert_equal('Creator', info[:Creator])
+      assert_match(/HexaPDF/, info[:Producer])
+      assert_same(@time, info[:CreationDate])
+      assert_same(@time, info[:ModDate])
+      assert_equal(:True, info[:Trapped])
+    end
+
+    it "uses a correctly updated modification date if set so by Document#write" do
+      info = @doc.trailer.info
+      sleep(0.1)
+      @doc.write(StringIO.new)
+      assert_same(@time, info[:CreationDate])
+      refute_same(@time, info[:ModDate])
+      assert(@time < info[:ModDate])
+    end
+
+    it "correctly handles array values for title, author, and subject for info dictionary" do
+      @metadata.title(['Title', 'Another'])
+      @metadata.author(['Author', 'Author2'])
+      @metadata.subject(['Subject', 'Another'])
+      @doc.write(StringIO.new)
+      info = @doc.trailer.info
+      assert_equal('Title', info[:Title])
+      assert_equal('Author, Author2', info[:Author])
+      assert_equal('Subject', info[:Subject])
+    end
+
+    it "writes the XMP metadata" do
+      title = HexaPDF::Document::Metadata::LocalizedString.new('Der Titel')
+      title.language = 'de'
+      @metadata.title(['Title', title])
+      @metadata.author(['Author 1', 'Author 2'])
+      @metadata.register_property_type('dc', 'other', 'URI')
+      @metadata.property('dc', 'other', 'https://test.org/example')
+      @doc.write(StringIO.new, update_fields: false)
+      metadata = <<~XMP
+      <?xpacket begin="" id=""?>
+      <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+      <rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
+      <dc:title><rdf:Alt>
+      <rdf:li xml:lang="en">Title</rdf:li>
+      <rdf:li xml:lang="de">Der Titel</rdf:li>
+      </rdf:Alt></dc:title>
+      <dc:creator><rdf:Seq>
+      <rdf:li>Author 1</rdf:li>
+      <rdf:li>Author 2</rdf:li>
+      </rdf:Seq></dc:creator>
+      <dc:description><rdf:Alt>
+      <rdf:li xml:lang="en">Subject</rdf:li>
+      </rdf:Alt></dc:description>
+      <dc:other rdf:resource="https://test.org/example" />
+      </rdf:Description>
+      <rdf:Description rdf:about="" xmlns:pdf="http://ns.adobe.com/pdf/1.3/">
+      <pdf:Keywords>Keywords</pdf:Keywords>
+      <pdf:Producer>Producer</pdf:Producer>
+      <pdf:Trapped>True</pdf:Trapped>
+      </rdf:Description>
+      <rdf:Description rdf:about="" xmlns:xmp="http://ns.adobe.com/xap/1.0/">
+      <xmp:CreatorTool>Creator</xmp:CreatorTool>
+      <xmp:CreateDate>#{@metadata.send(:xmp_date, @time)}</xmp:CreateDate>
+      <xmp:ModifyDate>#{@metadata.send(:xmp_date, @time)}</xmp:ModifyDate>
+      </rdf:Description>
+      </rdf:RDF>
+      <?xpacket end="r"?>
+      XMP
+      assert_equal(metadata, @doc.catalog[:Metadata].stream.sub(/(?<=id=")\w+/, ''))
+    end
+
+    it "respects the write settings for info dictionary and metadata stream" do
+      @metadata.write_info_dict(false)
+      @metadata.write_metadata_stream(false)
+      @doc.write(StringIO.new)
+      assert_nil(@doc.trailer.info[:Author])
+      refute(@doc.catalog.key?(:Metadata))
+    end
+  end
+end

data/test/hexapdf/test_filter.rb

@@ -18,6 +18,12 @@ describe HexaPDF::Filter do
       assert_equal(@str, collector(fib))
       assert_equal('', collector(fib))
     end
+
+    it "returns the correct length of the fiber" do
+      str = "\u{FEFF}Öl"
+      fib = @obj.source_from_proc { str }
+      assert_equal(6, fib.length)
+    end
   end
 
   describe "source_from_string" do
@@ -30,6 +36,12 @@ describe HexaPDF::Filter do
     it "returns the whole string" do
       assert_equal(@str, collector(@obj.source_from_string(@str)))
     end
+
+    it "returns the correct size of the fiber" do
+      str = "\u{FEFF}Öl"
+      fib = @obj.source_from_string(str)
+      assert_equal(6, fib.length)
+    end
   end
 
   describe "source_from_io" do

data/test/hexapdf/test_writer.rb

@@ -40,7 +40,7 @@ describe HexaPDF::Writer do
       219
       %%EOF
       3 0 obj
-      <</Producer(HexaPDF version 0.36.0)>>
+      <</Producer(HexaPDF version 0.37.0)>>
       endobj
       xref
       3 1
@@ -72,7 +72,7 @@ describe HexaPDF::Writer do
       141
       %%EOF
       6 0 obj
-      <</Producer(HexaPDF version 0.36.0)>>
+      <</Producer(HexaPDF version 0.37.0)>>
       endobj
       2 0 obj
       <</Length 10>>stream

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexapdf
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Thomas Leitner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-20 00:00:00.000000000 Z
+date: 2024-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cmdparse
@@ -358,6 +358,7 @@ files:
 - lib/hexapdf/document/fonts.rb
 - lib/hexapdf/document/images.rb
 - lib/hexapdf/document/layout.rb
+- lib/hexapdf/document/metadata.rb
 - lib/hexapdf/document/pages.rb
 - lib/hexapdf/encryption.rb
 - lib/hexapdf/encryption/aes.rb
@@ -505,6 +506,7 @@ files:
 - lib/hexapdf/type/image.rb
 - lib/hexapdf/type/info.rb
 - lib/hexapdf/type/mark_information.rb
+- lib/hexapdf/type/metadata.rb
 - lib/hexapdf/type/names.rb
 - lib/hexapdf/type/object_stream.rb
 - lib/hexapdf/type/optional_content_configuration.rb
@@ -631,6 +633,7 @@ files:
 - test/hexapdf/document/test_fonts.rb
 - test/hexapdf/document/test_images.rb
 - test/hexapdf/document/test_layout.rb
+- test/hexapdf/document/test_metadata.rb
 - test/hexapdf/document/test_pages.rb
 - test/hexapdf/encryption/common.rb
 - test/hexapdf/encryption/test_aes.rb
@@ -796,7 +799,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="