hexapdf 0.26.2 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f7ff4db8b6417cf6f0101a2e72e2481571a40c9542713be82753376d58c047c
-  data.tar.gz: 0b62a42fe5b91bdd8f11c4c31105e560cd4cf2f27259a86b9fd07db2f2280d6e
+  metadata.gz: 874e09b094ea4e793d1d123cfbaded6d1cc5ba93af3b57587e9faf402786a30f
+  data.tar.gz: c1eed6a778936cd360b4f1878a18abc3e5727c1f36b5eab4838a9a72817dff7b
 SHA512:
-  metadata.gz: 0ef60dd2da6c1c233768e564c5afb9330fb07065a33f293a2fbca6c71b8948d2ab754b2c9383ed4a84400e944e98f6c5a3638bf0c970c2b819eb53a0e024a2ca
-  data.tar.gz: 9c0190529f0d25d9ec655bef27d25054b9bfb5dc2ec980742807e73e0eb953550033f5362249cad1ec83ff8e78a1f1ad91785614cecdbaed113ad6365a77ade5
+  metadata.gz: b66a7587a239acbeb9ebbb20f851b2fa7738c5a4c2f8a95ae7ae3d7419b84ae37b5d1fb48a6b7023bff0df3e1728c395b5351c9c42c05707fabd5a1722e2b88a
+  data.tar.gz: 62ac7d070bb8ae3426685af497a047096dd32dc16a102baa961512652222b388198561776fc1227be69bdd0713183d91fa25e411262eec34a29227aae9723d5c

data/CHANGELOG.md

@@ -1,3 +1,117 @@
+## 0.28.0 - 2022-12-30
+
+### Added
+
+* [HexaPDF::Type::AcroForm::AppearanceGenerator#create_push_button_appearances]
+  to allow customizing the behaviour
+* [HexaPDF::Parser#linearized?] for determining whether a document is linearized
+* Information on linearization to `hexapdf info` output
+* Support for `AFNumber_Format` Javascript method to the form field appearance
+  generator
+* Support for using fully embedded, simple TrueType fonts for drawing operations
+
+### Changed
+
+* **Breaking change**: `HexaPDF::Revision#reset_objects` has been removed
+* **Breaking change**: Method signature of [HexaPDF::Importer::for] has been
+  changed
+* **Breaking change**: [HexaPDF::Type::AcroForm::Field#each_widget] now has the
+  default value of the argument `direct_only` set to `true` instead of `false`
+* [HexaPDF::Revision#each_modified_object] to allow deleting the modified
+  objects from the active objects' container
+* [HexaPDF::Revision#each_modified_object] to allow ignoring added object and
+  cross-reference stream objects
+* [HexaPDF::Revisions::from_io] to merge the two revisions of a linearized PDF
+* [HexaPDF::Importer] and [HexaPDF::Document#import] to make working with them
+  easier by allowing the import of arbitrary objects
+* `HexaPDF::Type::AcroForm::Form#perform_validation` to combine fields with the
+  same name
+
+### Fixed
+
+* [HexaPDF::Type::AcroForm::AppearanceGenerator#create_check_box_appearances] to
+  correctly handle a field value of `nil`
+* Return value of `#type` method for all AcroForm field classes
+* [HexaPDF::Type::Page#flatten_annotations] to work correctly in case no
+  annotations are on the page
+* [HexaPDF::Type::AcroForm::ButtonField#create_appearances] to avoid creating
+  appearances in case of as-yet unresolved references to existing appearances
+* [HexaPDF::Type::AcroForm::TextField#create_appearances] to avoid creating
+  appearances in case of pre-existing ones
+* `HexaPDF::Tokenizer#parse_number` to treat invalid indirect object references
+  with an object number of 0 as null values
+* [HexaPDF::Type::AcroForm::AppearanceGenerator] to handle empty appearance
+  characteristics dictionary marker style strings
+* Writing of encrypted files containing two or more revisions
+* Generation of object streams to never allow storing the catalog object to
+  avoid problems with certain viewers
+* `HexaPDF::Type::Outline#perform_validation` to not show validation error when
+  `/Count` is zero
+* Writing of documents with two or more revisions in non-incremental mode when
+  `optimize: true` is used and the original document used cross-reference tables
+* [HexaPDF::Type::AcroForm::AppearanceGenerator] to take a widget's rotation
+  value into account
+* [HexaPDF::Type::Page#flatten_annotations] to correctly flatten all
+  annotations, including ones with custom rotations
+* [HexaPDF::Type::Page#rotate] to also rotate annotations
+
+
+## 0.27.0 - 2022-11-18
+
+### Added
+
+* Support for timestamp signatures through the
+  [HexaPDF::Document::Signatures::TimestampHandler]
+* [HexaPDF::Document::Destinations#resolve] for resolving destination values
+* [HexaPDF::Document::Destinations::Destination#value] to return the destination
+  array
+* Support for verifying document timestamp signatures
+* [HexaPDF::Document::Signatures::DefaultHandler#signature_size] to support
+  setting custom signature sizes
+* [HexaPDF::Document::Signatures::DefaultHandler#external_signing] to support
+  signing via custom mechanisms
+* [HexaPDF::Document::Signatures::embed_signature] to enable asynchronous
+  external signing
+
+### Changed
+
+* **Breaking change**: The crop box is now used instead of the media box in most
+  cases to be in line with the specification
+* [HexaPDF::Document::Signatures::DefaultHandler] to allow setting the used
+  signature method
+* **Breaking change**: [HexaPDF::Document::Signatures::DefaultHandler#sign]
+  needs to accept the IO object and the byte range instead of just the data
+* **Breaking change**: Enhanced support for outline items with new methods
+  `#level` and `#destination_page` as well as changes to `#add` and `#each_item`
+* **Breaking change**: Removed `#filter_name` and `#sub_filter_name` from
+  [HexaPDF::Document::Signatures::DefaultHandler]
+* `HexaPDF::Type::Resources#perform_validation` to not add a default procedure
+  set since this feature is deprecated
+
+### Fixed
+
+* [HexaPDF::Document::Destinations::Destination::new] to also accept a hash
+* [HexaPDF::Type::Catalog] auto-conversion of /Outlines to correct class
+* [HexaPDF::Type::AcroForm::Form#flatten] to return the unflattened form fields
+  instead of the widgets
+* [HexaPDF::Writer#write_incremental] to set the /Version in the catalog
+  dictionary when necessary
+* [HexaPDF::Importer#import] to always return an imported object with the same
+  class as the argument
+* [HexaPDF::Type::OutlineItem] to always be an indirect object
+* `HexaPDF::Tokenizer#parse_number` to handle references correctly in all cases
+* [HexaPDF::Type::Page#rotate] to correctly flatten all page boxes
+* [HexaPDF::Document::Signatures#add] to raise an error if the reserved space
+  for the signature is not enough
+* `HexaPDF::Type::AcroForm::Form#perform_validation` to fix broken /Parent
+  entries and to remove invalid objects from the field hierarchy
+* `HexaPDF::Type::OutlineItem#perform_validation` bug where a missing /Count key
+  was deemed invalid
+* [HexaPDF::Revisions::from_io] to use the correct /Prev offset when revisions
+  have been merged
+* Handling of indirect objects with invalid values for more situations
+
+
 ## 0.26.2 - 2022-10-22
 
 ### Added
@@ -180,7 +294,7 @@
 ### Added
 
 - [HexaPDF::Composer#create_stamp] for creating a form Xobject
-- [HexaPDF::Revision#reset_objects] for deleting all live loaded and added
+- `HexaPDF::Revision#reset_objects` for deleting all live loaded and added
   objects
 - Support for removing or flattening annotations to the `hexapdf modify` command
 - Option to CLI command `hexapdf form` to allow generation of a template file

data/README.md

@@ -91,7 +91,7 @@ with example graphics and PDF files and tightly integrated into the rest of the
 ## Requirements and Installation
 
 Since HexaPDF is written in Ruby, a working Ruby installation is needed - see the
-[official installation documentation][rbinstall] for details. Note that you need Ruby version 2.5 or
+[official installation documentation][rbinstall] for details. Note that you need Ruby version 2.6 or
 higher as prior versions are not supported!
 
 HexaPDF works on all Ruby implementations that are CRuby compatible, e.g. TruffleRuby, and on any

data/examples/013-text_layouter_shapes.rb

@@ -73,14 +73,14 @@ canvas.circle(0, circle_top - radius, radius).stroke
 # Center: full circle
 layouter.style.align = :justify
 result = layouter.fit(items, circle, radius * 2)
-result.draw(canvas, page.box(:media).width / 2.0 - radius, circle_top)
-canvas.circle(page.box(:media).width / 2.0, circle_top - radius, radius).stroke
+result.draw(canvas, page.box.width / 2.0 - radius, circle_top)
+canvas.circle(page.box.width / 2.0, circle_top - radius, radius).stroke
 
 # Right: left half circle
 layouter.style.align = :right
 result = layouter.fit(items, left_half_circle, radius * 2)
-result.draw(canvas, page.box(:media).width - radius, circle_top)
-canvas.circle(page.box(:media).width, circle_top - radius, radius).stroke
+result.draw(canvas, page.box.width - radius, circle_top)
+canvas.circle(page.box.width, circle_top - radius, radius).stroke
 
 
 ########################################################################
@@ -115,7 +115,7 @@ canvas.polyline(0, diamond_top, diamond_width, diamond_top - diamond_width,
 # Center: full diamond
 layouter.style.align = :justify
 result = layouter.fit(items, full_diamond, 2 * diamond_width)
-left = page.box(:media).width / 2.0 - diamond_width
+left = page.box.width / 2.0 - diamond_width
 result.draw(canvas, left, diamond_top)
 canvas.polyline(left + diamond_width, diamond_top,
                 left + 2 * diamond_width, diamond_top - diamond_width,
@@ -125,7 +125,7 @@ canvas.polyline(left + diamond_width, diamond_top,
 # Right: left half diamond
 layouter.style.align = :right
 result = layouter.fit(items, left_half_diamond, 2 * diamond_width)
-middle = page.box(:media).width
+middle = page.box.width
 result.draw(canvas, middle - diamond_width, diamond_top)
 canvas.polyline(middle, diamond_top,
                 middle - diamond_width, diamond_top - diamond_width,
@@ -144,7 +144,7 @@ sine_wave = lambda do |height, line_height|
 end
 layouter.style.align = :justify
 result = layouter.fit(items, sine_wave, sine_wave_height)
-middle = page.box(:media).width / 2.0
+middle = page.box.width / 2.0
 result.draw(canvas, middle - (sine_wave_height + 100) / 2, sine_wave_top)
 
 ########################################################################
@@ -170,7 +170,7 @@ end
 layouter.style.align = :justify
 result = layouter.fit(items, house, 200)
 
-middle = page.box(:media).width / 2.0
+middle = page.box.width / 2.0
 result.draw(canvas, middle - (outer_width / 2), house_top)
 
 doc.write("text_layouter_shapes.pdf", optimize: true)

data/examples/016-frame_automatic_box_placement.rb

@@ -20,11 +20,11 @@ include HexaPDF::Layout
 
 doc = HexaPDF::Document.new
 page = doc.pages.add
-media_box = page.box(:media)
+page_box = page.box
 canvas = page.canvas
 
-frame = Frame.new(media_box.left + 20, media_box.bottom + 20,
-                  media_box.width - 40, media_box.height - 40)
+frame = Frame.new(page_box.left + 20, page_box.bottom + 20,
+                  page_box.width - 40, page_box.height - 40)
 
 box_counter = 1
 draw_box = lambda do |**args|

data/examples/017-frame_text_flow.rb

@@ -20,9 +20,9 @@ include HexaPDF::Utils::GraphicsHelpers
 doc = HexaPDF::Document.new
 
 page = doc.pages.add
-media_box = page.box(:media)
-frame = Frame.new(media_box.left + 20, media_box.bottom + 20,
-                  media_box.width - 40, media_box.height - 40)
+page_box = page.box
+frame = Frame.new(page_box.left + 20, page_box.bottom + 20,
+                  page_box.width - 40, page_box.height - 40)
 
 boxes = []
 boxes << doc.layout.image_box(File.join(__dir__, 'machupicchu.jpg'),

data/examples/019-acro_form.rb

@@ -6,6 +6,9 @@
 # This example show-cases how to create the various form field types and their
 # possible standard appearances.
 #
+# Note the 'number format' text field which uses a JavaScript function for
+# formatting a number.
+#
 # Usage:
 # : `ruby acro_form.rb`
 #
@@ -42,13 +45,21 @@ rb = form.create_radio_button("Radio")
 end
 rb.field_value = :button0
 
-canvas.text("Text fields", at: [50, 450])
+canvas.text("Text fields", at: [50, 480])
 
-canvas.text("Single line", at: [70, 420])
+canvas.text("Single line", at: [70, 450])
 tx = form.create_text_field("Single Line", font_size: 16)
-widget = tx.create_widget(page, Rect: [200, 415, 500, 435])
+widget = tx.create_widget(page, Rect: [200, 445, 500, 465])
 tx.field_value = "A sample test string!"
 
+canvas.text("Number format", at: [70, 420])
+tx = form.create_text_field("Number format", font_size: 16)
+widget = tx.create_widget(page, Rect: [200, 415, 500, 435])
+widget[:AA] = {
+  F: {S: :JavaScript, JS: 'AFNumber_Format(2, 2, 0, 0, "EUR ", true);'},
+}
+tx.field_value = "123456,789"
+
 canvas.text("Multiline", at: [70, 390])
 tx = form.create_multiline_text_field("Multiline", font_size: 0, align: :right)
 widget = tx.create_widget(page, Rect: [200, 325, 500, 405])

data/examples/020-column_box.rb

@@ -15,9 +15,9 @@ require 'hexapdf'
 
 doc = HexaPDF::Document.new
 page = doc.pages.add
-media_box = page.box(:media)
-frame = HexaPDF::Layout::Frame.new(media_box.left + 20, media_box.bottom + 20,
-                                   media_box.width - 40, media_box.height - 40)
+page_box = page.box
+frame = HexaPDF::Layout::Frame.new(page_box.left + 20, page_box.bottom + 20,
+                                   page_box.width - 40, page_box.height - 40)
 
 boxes = []
 5.times do

data/examples/023-images.rb

@@ -0,0 +1,30 @@
+# # Images
+#
+# This example shows how to embed images into a PDF document, directly on a
+# page's canvas and through the high-level [HexaPDF::Composer].
+#
+# Usage:
+# : `ruby images.rb`
+#
+
+require 'hexapdf'
+
+file = File.join(__dir__, 'machupicchu.jpg')
+
+doc = HexaPDF::Document.new
+# Image only added to PDF once though used multiple times
+canvas = doc.pages.add.canvas
+canvas.image(file, at: [100, 500]) # auto-size based on image size
+canvas.image(file, at: [100, 300], width: 100) # height based on w/h ratio
+canvas.image(file, at: [300, 300], height: 100) # width based on w/h ratio
+canvas.image(file, at: [100, 100], width: 300, height: 100)
+
+HexaPDF::Composer.create('images.pdf') do |composer|
+  composer.image(file) # fill current rectangular region
+  composer.image(file, width: 100)  # height based on w/h ratio
+  composer.image(file, height: 100) # width based on w/h ratio
+  composer.image(file, width: 300, height: 100)
+
+  # Add the page created above as second page
+  composer.document.pages << composer.document.import(doc.pages[0])
+end

data/lib/hexapdf/cli/info.rb

@@ -131,6 +131,10 @@ module HexaPDF
             output_line("Encrypted", "yes (no or wrong password given)")
           end
 
+          if doc.revisions.parser.linearized?
+            output_line("Linearized", "yes")
+          end
+
           signatures = doc.signatures.to_a
           unless signatures.empty?
             nr_sigs = signatures.count
@@ -186,7 +190,7 @@ module HexaPDF
       end
 
       def output_line(header, text) #:nodoc:
-        puts(("#{header}:").ljust(COLUMN_WIDTH) << text.to_s)
+        puts("#{header}:".ljust(COLUMN_WIDTH) << text.to_s)
       end
 
     end

data/lib/hexapdf/cli/inspect.rb

@@ -335,9 +335,9 @@ module HexaPDF
       # - The signature dictionary if this revision was signed
       # - The byte offset from the start of the file to the end of the revision
       def revision_information
-        signatures = @doc.signatures.map do |sig|
+        signatures = @doc.signatures.to_h do |sig|
           [@doc.revisions.find {|rev| rev.object(sig) == sig }, sig]
-        end.to_h
+        end
         io = @doc.revisions.parser.io
 
         startxrefs = @doc.revisions.map {|rev| rev.trailer[:Prev] }

data/lib/hexapdf/cli/split.rb

@@ -114,7 +114,7 @@ module HexaPDF
         end
 
         doc.pages.each do |page|
-          out = out_files[page_size_name(page.box(:media).value)]
+          out = out_files[page_size_name(page.box.value)]
           out.pages.add(out.import(page))
         end
 
@@ -125,18 +125,18 @@ module HexaPDF
         end
       end
 
-      # Tries to retrieve a page size name based on the media box. If this is not possible, the
+      # Tries to retrieve a page size name based on the given page box. If this is not possible, the
       # returned page size name consists of width x height.
-      def page_size_name(media_box)
+      def page_size_name(box)
         @page_name_cache ||= {}
-        return @page_name_cache[media_box] if @page_name_cache.key?(media_box)
+        return @page_name_cache[box] if @page_name_cache.key?(box)
 
-        paper_size = HexaPDF::Type::Page::PAPER_SIZE.find do |_name, box|
-          box.each_with_index.all? {|entry, index| (entry - media_box[index]).abs < 5 }
+        paper_size = HexaPDF::Type::Page::PAPER_SIZE.find do |_name, paper_box|
+          paper_box.each_with_index.all? {|entry, index| (entry - paper_box[index]).abs < 5 }
         end
 
-        @page_name_cache[media_box] =
-          paper_size ? paper_size[0] : sprintf("%.0fx%.0f", *media_box.values_at(2, 3))
+        @page_name_cache[box] =
+          paper_size ? paper_size[0] : sprintf("%.0fx%.0f", *box.values_at(2, 3))
       end
 
     end

data/lib/hexapdf/cli/watermark.rb

@@ -95,8 +95,8 @@ module HexaPDF
           doc.pages.each do |page|
             index = indices.next
             xobject = xobject_map[index] ||= doc.import(watermark.pages[index].to_form_xobject)
-            pw = page.box(:media).width.to_f
-            ph = page.box(:media).height.to_f
+            pw = page.box.width.to_f
+            ph = page.box.height.to_f
             xw = xobject.width.to_f
             xh = xobject.height.to_f
             canvas = page.canvas(type: @type)

data/lib/hexapdf/configuration.rb

@@ -422,8 +422,7 @@ module HexaPDF
                       'encryption.filter_map' => {
                         Standard: 'HexaPDF::Encryption::StandardSecurityHandler',
                       },
-                      'encryption.sub_filter_map' => {
-                      },
+                      'encryption.sub_filter_map' => {},
                       'filter.map' => {
                         ASCIIHexDecode: 'HexaPDF::Filter::ASCIIHexDecode',
                         AHx: 'HexaPDF::Filter::ASCIIHexDecode',
@@ -488,11 +487,13 @@ module HexaPDF
                       },
                       'signature.signing_handler' => {
                         default: 'HexaPDF::Document::Signatures::DefaultHandler',
+                        timestamp: 'HexaPDF::Document::Signatures::TimestampHandler',
                       },
                       'signature.sub_filter_map' => {
                         'adbe.x509.rsa_sha1': 'HexaPDF::Type::Signature::AdbeX509RsaSha1',
                         'adbe.pkcs7.detached': 'HexaPDF::Type::Signature::AdbePkcs7Detached',
                         'ETSI.CAdES.detached': 'HexaPDF::Type::Signature::AdbePkcs7Detached',
+                        'ETSI.RFC3161': 'HexaPDF::Type::Signature::AdbePkcs7Detached',
                       },
                       'task.map' => {
                         optimize: 'HexaPDF::Task::Optimize',

data/lib/hexapdf/content/canvas.rb

@@ -1626,17 +1626,22 @@ module HexaPDF
         end
         return obj if obj.width == 0 || obj.height == 0
 
+        left, bottom = *at
         width, height = calculate_dimensions(obj.width, obj.height,
                                              rwidth: width, rheight: height)
         if obj[:Subtype] != :Image
           width /= obj.box.width.to_f
           height /= obj.box.height.to_f
-          at[0] -= obj.box.left
-          at[1] -= obj.box.bottom
+          left -= obj.box.left
+          bottom -= obj.box.bottom
         end
 
-        transform(width, 0, 0, height, at[0], at[1]) do
+        if left == 0 && bottom == 0 && width == 1 && height == 1
           invoke1(:Do, resources.add_xobject(obj))
+        else
+          transform(width, 0, 0, height, left, bottom) do
+            invoke1(:Do, resources.add_xobject(obj))
+          end
         end
 
         obj

data/lib/hexapdf/dictionary.rb

@@ -108,11 +108,7 @@ module HexaPDF
     # The ancestor classes are also searched for such a field entry if none is found for the
     # current class.
     def self.field(name)
-      if defined?(@fields) && @fields.key?(name)
-        @fields[name]
-      elsif superclass.respond_to?(:field)
-        superclass.field(name)
-      end
+      @fields&.[](name) || superclass.field(name)
     end
 
     # :call-seq:
@@ -259,22 +255,13 @@ module HexaPDF
       end
     end
 
-    # Iterates over all currently set fields and those that are required.
-    def each_set_key_or_required_field #:yields: name, field
-      value.keys.each {|name| yield(name, self.class.field(name)) }
-      self.class.each_field do |name, field|
-        yield(name, field) if field.required? && !value.key?(name)
-      end
-    end
-
     # Performs validation tasks based on the currently set keys and defined fields.
     def perform_validation(&block)
       super
-      each_set_key_or_required_field do |name, field|
-        obj = key?(name) ? self[name] : nil
+      self.class.each_field do |name, field|
+        next unless field.required? || value.key?(name)
 
-        # The checks below need a valid field definition
-        next if field.nil?
+        obj = key?(name) ? self[name] : nil
 
         # Check that required fields are set
         if field.required? && obj.nil?

data/lib/hexapdf/document/destinations.rb

@@ -107,8 +107,7 @@ module HexaPDF
       #     not changing it from the current value.
       class Destination
 
-        # :nodoc:
-        TYPE_MAPPING = {
+        TYPE_MAPPING = { #:nodoc:
           XYZ: :xyz,
           Fit: :fit_page,
           FitH: :fit_page_horizontal,
@@ -119,8 +118,7 @@ module HexaPDF
           FitBV: :fit_bounding_box_vertical,
         }
 
-        # :nodoc:
-        REVERSE_TYPE_MAPPING = Hash[*TYPE_MAPPING.flatten.reverse]
+        REVERSE_TYPE_MAPPING = Hash[*TYPE_MAPPING.flatten.reverse] #:nodoc:
 
         # Returns +true+ if the destination is valid.
         def self.valid?(destination)
@@ -132,7 +130,11 @@ module HexaPDF
         # Creates a new Destination for the given +destination+ which may be an explicit destination
         # array or a dictionary with a /D entry (as allowed for a named destination).
         def initialize(destination)
-          @destination = (destination.kind_of?(HexaPDF::Dictionary) ? destination[:D] : destination)
+          @destination = if destination.kind_of?(HexaPDF::Dictionary) || destination.kind_of?(Hash)
+                           destination[:D]
+                         else
+                           destination
+                         end
         end
 
         # Returns +true+ if the destination references a destination in a remote document.
@@ -212,6 +214,11 @@ module HexaPDF
           self.class.valid?(@destination)
         end
 
+        # Returns the wrapped destination array.
+        def value
+          @destination
+        end
+
       end
 
       include Enumerable
@@ -447,6 +454,36 @@ module HexaPDF
         destinations.delete_entry(name)
       end
 
+      # :call-seq:
+      #   destinations.resolve(string_name)    -> destination or nil
+      #   destinations.resolve(symbol_name)    -> destination or nil
+      #   destinations.resolve(dest_array)     -> destination or nil
+      #
+      # Resolves the given value to a valid destination object, if possible, or otherwise returns
+      # +nil+.
+      #
+      # * If the given value is a string, it is treated as a destination name and looked up in the
+      #   destination name tree.
+      #
+      # * If the given value is a symbol, it is treated as an old-style destination name and looked
+      #   up in the destination dictionary.
+      #
+      # * If the given value is an array, it is treated as a destination array itself.
+      def resolve(value)
+        result = case value
+                 when String
+                   destinations.find_entry(value)
+                 when PDFArray
+                   value.value
+                 when Array
+                   value
+                 when Symbol
+                   @document.catalog[:Dests]&.[](value)
+                 end
+        result = Destination.new(result) if result
+        result&.valid? ? result : nil
+      end
+
       # :call-seq:
       #   destinations[name]    -> destination
       #