lutaml-model 0.8.100 → 0.8.119

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bd54a574eb02eec487d980543835abb2bec61c12104d6eea6b898a516fb301f
-  data.tar.gz: ffc5d3ed5b0c6df7140839064baec52624a034b2d1c5cfdc764dc4ee78c199ce
+  metadata.gz: 8df481bfb5303c05153a8bda8eaa4996157a6060d34d70dd8eb835e461aff9f5
+  data.tar.gz: a23f93de4f89b1a2b7925833786e9d0337ec5e94ec172723f5b2b70f78347d3c
 SHA512:
-  metadata.gz: 191c5ee654cc6863a6f8d865448f0fbb29c31f7d602e3ab2a356148fdca7117b254aa497bb1ebdd80da1c80f495cf46c5f1029897cf87e7423a7409747e4e97c
-  data.tar.gz: 4b55a05f437df7e0c85c7545d2042990572c70a4d64b42d9ae3ee44950ca6875cd640c2089cd9620951264180556e2e3776e7b32028b1b1d9962cbdaad739ecb
+  metadata.gz: adbc819876bf696f60009c53042dba835e5e557f32057f1aba4f58da56831c15f347d35dcf0160536a877f29f2d17ba59aadb8b1ac38b7fa9572b2d12d6c6dd2
+  data.tar.gz: 9af887394f9b2e241f299cb8eabcc3e0202ec51dba5129477a16cb85234105f51c7198fc44b9c20c916fa89a1356918c4752bbd73afa8f83a5a49ffd3032f08d

data/Gemfile

@@ -44,11 +44,12 @@ gem "rexml"
 # Native engines stay development-only: every adapter detects and
 # degrades gracefully at runtime (safe requires + prefer-if-available).
 # yeptris ships no Windows prebuilt platform gem.
-# leptris floor: the plan hydrator's one-crossing snapshot
-# (leptris_plan_value_children_snapshot) landed in 1.9.273.0; older
-# gems fall back to accessor enumeration at runtime, but CI and dev
-# resolve the snapshot-capable line.
-gem "leptris", ">= 1.9.273.0"
+# leptris floor: the single capability line for the plan fast path
+# (see Lutaml::Xml::Leptris::MIN_LEPTRIS_VERSION) — child snapshots,
+# exact-URI attribute rows, nested-attribute capture, wildcard rows,
+# walk-side ns retention and leniency, :unqualified rows, and the
+# address-based text attach all ride it.
+gem "leptris", ">= 1.9.351.1"
 gem "teptris"
 gem "yeptris" unless Gem.win_platform?
 # TODO: revert rng branch to main when lutaml/rng#32 is merged

data/lib/compat/opal/lutaml_model_boot.rb

@@ -382,6 +382,7 @@ require "lutaml/xml/error/namespace_mismatch_error"
 require "lutaml/xml/error/schema_validation_error"
 require "lutaml/xml/error/xml_configuration_error"
 require "lutaml/xml/error/xml_error"
+require "lutaml/xml/leptris/native_emission"
 require "lutaml/xml/leptris/plan_compiler"
 require "lutaml/xml/leptris/plan_hydrator"
 require "lutaml/xml/leptris/plan_order"

data/lib/lutaml/json/adapter/yeptris_adapter.rb

@@ -26,6 +26,34 @@ module Lutaml
         end
         private_class_method :require_engine
 
+        # True where the yeptris engine loads (libyeptris present for
+        # this platform) AND answers a probe parse. A require alone
+        # does not prove the engine: a half-initialized Yeptris
+        # constant (the poison-process state the gem documents)
+        # passes const_defined? and require while every parse fails,
+        # and the native parse error then surfaces on valid input.
+        # Idempotent; a missing or broken install reports false
+        # instead of raising, so optional-engine callers (detection)
+        # can gate on it and fall back to the standard lane.
+        def self.available?
+          require_engine
+          native_ready?
+        rescue LoadError
+          false
+        end
+
+        def self.native_ready?
+          return @native_ready unless @native_ready.nil?
+
+          @native_ready = begin
+            ::Yeptris::JSON.load('{"native_probe": 1}')
+            true
+          rescue ::Yeptris::Error, LoadError, NoMemoryError
+            false
+          end
+        end
+        private_class_method :native_ready?
+
         # The parse-error contract is the standard adapter's: invalid
         # input raises JSON::ParserError regardless of the engine, so
         # consumers' rescue ladders (and this gem's own

data/lib/lutaml/key_value/transform.rb

@@ -687,6 +687,10 @@ partition = nil)
         # attribute is not a collection, so this guard defers exactly that case
         # to `.validate` while leaving declared ranges checked at parse. A mapped
         # PORO has no `.validate` to defer into, so it keeps the eager check.
+        # singular_tolerance: :first on the KV lane (#971): collapse an
+        # over-ingested collection before the writer stores it whole.
+        value = value.first if attr.tolerates_singular_overflow?(value)
+
         if attr.collection? || !instance.is_a?(Lutaml::Model::Serialize)
           attr.valid_collection!(value, context)
         end

data/lib/lutaml/key_value/transformation.rb

@@ -1031,6 +1031,16 @@ child_mappings, options)
                               rule.attribute_type < Lutaml::Model::Serialize
                           end
 
+        if is_nested_model && !value.is_a?(Lutaml::Model::Serialize)
+          # The KV mirror of the XML lane's #971 collapse: a tolerated
+          # singular attribute holding an over-assigned collection
+          # serializes its leading value instead of raising.
+          attr = if model_class.respond_to?(:attributes)
+                   model_class.attributes[rule.attribute_name.to_sym]
+                 end
+          value = value.first if attr&.tolerates_singular_overflow?(value)
+        end
+
         if is_nested_model
           # Validate that value matches the expected type
           # There are three valid cases:

data/lib/lutaml/model/adapter_resolver.rb

@@ -387,13 +387,21 @@ module Lutaml
         end
 
         # Native key-value engine preference: yeptris (libyeptris C11)
-        # when its gem is in the bundle, else the format's standard
-        # adapter. Opt-in by bundle contents — nothing is required of
-        # consumers that do not add yeptris.
+        # when its gem is in the bundle AND the native engine answers a
+        # probe, else the format's standard adapter. Opt-in by bundle
+        # contents — nothing is required of consumers that do not add
+        # yeptris. The probe matters because a half-initialized Yeptris
+        # constant (the poison-process state the gem documents) passes
+        # const_defined? and require while every parse fails; without
+        # it the lane selection flips with process load order and the
+        # failure surfaces as a native parse error on valid input
+        # instead of a clean standard-lane parse (#978).
         def detect_yeptris_kv_adapter(format)
-          return metadata.dig(format, :default) if Lutaml::Model.opal?
+          default = metadata.dig(format, :default)
+          return default if Lutaml::Model.opal?
+          return default unless Utils.safe_load("yeptris", :Yeptris)
 
-          Utils.safe_load("yeptris", :Yeptris) ? :yeptris : metadata.dig(format, :default)
+          load_adapter(format, :yeptris).available? ? :yeptris : default
         end
 
         # Detect available XML adapter.

data/lib/lutaml/model/attribute.rb

@@ -5,6 +5,20 @@ module Lutaml
     class Attribute
       attr_reader :name, :options
 
+      # Format scalars a mapped-model attribute may be handed in the
+      # key-value lanes (#978). Adapter element nodes and other object
+      # forms belong to the mapping lane and must not divert.
+      SCALAR_CAST_TYPES = [
+        ::String,
+        ::Numeric,
+        ::Symbol,
+        ::Time,
+        ::Date,
+        ::DateTime,
+        ::TrueClass,
+        ::FalseClass,
+      ].freeze
+
       include CollectionHandler
       include DeepDupable
       include RestrictionValidation
@@ -47,6 +61,7 @@ module Lutaml
         min_length
         max_length
         desc
+        singular_tolerance
       ].freeze
 
       # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
@@ -389,12 +404,34 @@ module Lutaml
 
       def cast_value(value, register)
         if list_like?(value)
-          build_collection(cast_items(value, register), register: register)
+          items = cast_items(value, register)
         elsif coerce_to_collection?(value)
-          build_collection(cast_items([value], register), register: register)
+          items = cast_items([value], register)
         else
-          cast_element(value, register)
+          return cast_element(value, register)
         end
+        # cast_items already returns a fresh array, so the plain-Array
+        # collection needs no re-wrap — build_collection's
+        # collection_class.new would copy it again.
+        assert_flat_collection_items!(items)
+        return items if !custom_collection? && collection_class == ::Array
+
+        build_collection(items, register: register)
+      end
+
+      # Fail loudly on nested arrays. A collection's declared element
+      # type never admits an Array as an item; the legacy
+      # build_collection flatten silently absorbed mis-spliced builder
+      # output (expressir#506 surfaced it three frames away in a
+      # formatter). The error must land at the assignment boundary.
+      def assert_flat_collection_items!(items)
+        return unless items.any?(::Array)
+
+        raise TypeError,
+              "collection '#{name}': item " \
+              "#{items.index { |item| item.is_a?(::Array) }} is an Array " \
+              "where the declared element type is expected; nested arrays " \
+              "are not flattened — splice list results before assignment"
       end
 
       # Plain Arrays count as list input. On singular attributes
@@ -805,6 +842,17 @@ instance_object = nil)
         end
       end
 
+      # Singular-overflow tolerance (#971): ingest can hand a singular
+      # attribute a collection — relaton's upstream documents carry
+      # multiple <formattedref> elements per bibitem. With
+      # singular_tolerance: :first the leading value is kept instead of
+      # raising CollectionTrueMissingError; the default stays strict.
+      def tolerates_singular_overflow?(value)
+        !collection? && @options[:singular_tolerance] == :first &&
+          collection_instance?(value) &&
+          !value_policy.whole_value?(unresolved_type)
+      end
+
       def valid_collection!(value, caller)
         if collection_instance?(value) && !collection? &&
             !value_policy.whole_value?(unresolved_type)
@@ -943,6 +991,26 @@ instance_object = nil)
         end
 
         klass = resolve_polymorphic_class(resolved_type, value, options)
+        # A scalar handed to a mapped-model attribute crashed
+        # apply_mappings with an internal NoMethodError (key? on
+        # String, #978). A type declaring its own .cast owns scalar
+        # construction; base-cast identity types fall through to the
+        # legacy conversion chain, whose parse error names the token.
+        # Non-scalar input (adapter elements, hashes, arrays) rides
+        # the mapping lane untouched.
+        if serializable_type?(register) && !value.nil? &&
+            SCALAR_CAST_TYPES.any? { |type| value.is_a?(type) } &&
+            klass.respond_to?(:cast) &&
+            klass.method(:cast).owner == klass.singleton_class
+          casted = klass.cast(value)
+          return casted if casted.is_a?(klass)
+
+          raise Lutaml::Model::IncorrectModelError,
+                "attribute '#{name}': the #{format} input for type " \
+                "#{klass} is a #{value.class}, and #{klass}.cast did " \
+                "not build one (received #{casted.class})"
+        end
+
         if can_serialize?(klass, value, format, options)
           propagated = Serialize::DeserializationContext.propagate(options)
           klass.apply_mappings(value, format,
@@ -1019,6 +1087,12 @@ instance_object = nil)
                "Use map_element \"name\", to: :#{name}, raw: :content instead."
         end
         @validations = @options[:validations]
+        tolerance = @options[:singular_tolerance]
+        unless tolerance.nil? || tolerance == :first
+          raise ArgumentError,
+                "Invalid singular_tolerance: #{tolerance.inspect} for " \
+                "attribute '#{name}'. Supported: :first"
+        end
         set_default_for_collection if collection?
       end
 

data/lib/lutaml/model/cached_type_resolver.rb

@@ -59,14 +59,14 @@ module Lutaml
       # updates so recursive type resolution can populate related keys.
       #
       # @param name [Symbol, String, Class] The type name or class to resolve
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context
       # @return [Class] The resolved type class
       # @raise [UnknownTypeError] If type cannot be resolved
       def resolve(name, context, materialize: true)
         return @delegate.resolve(name, context, materialize: false) unless materialize
 
         cache_key = if name.is_a?(Class)
-                      [context.id, name]
+                      [context_id_for(context), name]
                     else
                       build_cache_key(name, context)
                     end
@@ -79,11 +79,11 @@ module Lutaml
       # Check if a type can be resolved, using cache if available.
       #
       # @param name [Symbol, String, Class] The type name or class to check
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context
       # @return [Boolean] true if type can be resolved
       def resolvable?(name, context)
         cache_key = if name.is_a?(Class)
-                      [context.id, name]
+                      [context_id_for(context), name]
                     else
                       build_cache_key(name, context)
                     end
@@ -137,10 +137,17 @@ module Lutaml
       # Uses array for faster comparison than string concatenation.
       #
       # @param name [Symbol, String] The type name
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context
       # @return [Array] The cache key (faster than string)
       def build_cache_key(name, context)
-        [context.id, name.to_sym]
+        [context_id_for(context), name.to_sym]
+      end
+
+      # A nil context (e.g. a register ID that has no registered type
+      # context) is a legitimate "no namespace" resolution; the cache
+      # key just forgoes the namespace slot.
+      def context_id_for(context)
+        context&.id
       end
     end
   end

data/lib/lutaml/model/configuration.rb

@@ -19,6 +19,12 @@ module Lutaml
       # compilable XML models (Leptris::XML::Descriptor walk). Opt-in
       # while the full semantics audit completes.
       attr_accessor :xml_plan_fast_path
+      # Ordered/mixed-content models on the plan path: opt-in. The
+      # per-node ordered hydration is FASTER than the interpretive
+      # lane on time but allocates above the downstream budget gates
+      # (niso pnas ratio 1.25); it ships dark until the allocation
+      # diet lands.
+      attr_accessor :xml_plan_ordered_path
       # #909: when false, XML deserialization skips the per-instance
       # element_order/attribute_order summaries — read-only consumers of
       # large documents never serialize back and should not pay for
@@ -31,6 +37,13 @@ module Lutaml
         @conversion_cache = nil
         @configured = false
         @xml_plan_fast_path = true
+        # On by default since the engine fix: leptris#1743 (the
+        # exponential flatten on diamond-shared plan graphs) shipped in
+        # 1.9.366.2's identity-memo flatten_plan — the ISO_13849 corpus
+        # that hung for 28+ CPU-min now parses in ~8s warm. The floor
+        # bump (MIN_LEPTRIS_VERSION = 1.9.366.2) keeps consumers on
+        # memo-less engines off this lane.
+        @xml_plan_ordered_path = true
         @element_order_tracking = true
       end
 

data/lib/lutaml/model/serialize/builder.rb

@@ -84,6 +84,26 @@ module Lutaml
           @__order_tracking__ ? true : false
         end
 
+        # Whether any writer setter ran on this instance. Parsed
+        # instances start pristine — every set element value is covered
+        # by the parse-built element_order, so ordered serialization
+        # can skip order reconciliation; the first writer-set marks the
+        # instance and reconciliation engages (writer-added values sit
+        # outside the parse order).
+        # @return [Boolean]
+        def mutated_after_parse?
+          @__mutated_after_parse__ ? true : false
+        end
+
+        # Construction-time reset: hydration routes every attribute
+        # through the generated writers (which mark mutations); a
+        # freshly built instance is definitionally not
+        # mutated-after-parse.
+        # @return [void]
+        def clear_mutated_after_parse!
+          @__mutated_after_parse__ = false
+        end
+
         # Record a singular attribute mutation in element_order.
         #
         # No-op unless order tracking is enabled (i.e. the instance was
@@ -102,6 +122,7 @@ module Lutaml
         #   content for content-mapped attributes, ignored otherwise
         # @return [Object] the passed value
         def record_mutation(attribute_name, value = nil)
+          @__mutated_after_parse__ = true
           return value unless @__order_tracking__
 
           track_order(attribute_name, value, nil)
@@ -122,6 +143,7 @@ module Lutaml
         # @param value [Object, nil] The value assigned to the collection
         # @return [Object] the passed value
         def record_mutation_collection(attribute_name, value)
+          @__mutated_after_parse__ = true
           return value unless @__order_tracking__
           return value if value.nil? || Lutaml::Model::Utils.uninitialized?(value)
 

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -138,19 +138,37 @@ module Lutaml
           register = Lutaml::Model::Config.default_register
           plan = Lutaml::Xml::Leptris::PlanCompiler.compile(self, register)
           return nil unless plan
-          return nil unless Lutaml::Xml::Leptris::PlanCompiler.engine_walk_safe?(plan)
 
-          root = ::Leptris::XML.parse(data.to_s).root
+          # strict: the from_xml contract raises on malformed input —
+          # the FFI lane parses leniently by default and would answer a
+          # best-effort tree where every other adapter raises. The
+          # kwarg spellings vary by engine vintage (strict: landed
+          # after 1.9.353, recover: on 1.9.344+), so probe the resolved
+          # parse method and pass the strictest spelling it accepts.
+          root = ::Leptris::XML.parse(data.to_s, **leptris_strict_kwargs).root
           return nil if root.nil?
           return nil unless root.name == plan[:tree][:name]
 
           Lutaml::Xml::Leptris::PlanHydrator.call(self, plan,
                                          plan[:descriptor].walk(root),
-                                         node: root)
+                                         node: root,
+                                         declaration_plan_mode:
+                                           options.fetch(
+                                             :import_declaration_plan, :eager
+                                           ))
         rescue ::Leptris::XML::ParseError => e
           raise Lutaml::Model::InvalidFormatError.new(:xml, e.message)
         end
 
+        def leptris_strict_kwargs
+          params = ::Leptris::XML.method(:parse).parameters
+            .map { |_, key| key }
+          kwargs = {}
+          kwargs[:recover] = false if params.include?(:recover)
+          kwargs[:strict] = true if params.include?(:strict)
+          kwargs
+        end
+
         # Get list of error types that can be raised during format parsing.
         # Core errors are always included; format-specific errors come from
         # FormatRegistry registrations.

data/lib/lutaml/model/serialize/initialization.rb

@@ -223,6 +223,7 @@ module Lutaml
           # Clear memoized attribute merge (see .attributes)
           @merged_attributes_cache = nil
           @instantiate_writers = nil
+          @instantiate_attr_pairs = nil
 
           # Clear per-Attribute type caches (stale entries from GC'd TypeContext objects)
           class_attributes.each_value(&:clear_type_cache)
@@ -402,7 +403,10 @@ module Lutaml
           attrs_by = attributes(register_id)
           writers = instantiate_writers(register_id)
           given = 0
-          attrs_by.each do |name, attr|
+          # Memoized pair array: Hash#each mints a [name, attr] pair
+          # per attribute per instance (~5 allocs/instance on
+          # hydration-heavy corpora); Array#each reuses its elements.
+          instantiate_attr_pairs(register_id).each do |name, attr|
             next if attr.derived?
 
             # Symbol keys hit directly (native-extension callers);
@@ -455,6 +459,7 @@ module Lutaml
             unknown = attrs.keys.find { |k| !known.include?(k.to_sym) }
             raise Error, "unknown attribute '#{unknown}' for #{self}"
           end
+          instance.clear_mutated_after_parse!
           instance
         end
 
@@ -467,6 +472,14 @@ module Lutaml
             end
         end
 
+        # [name, attr] pairs in attributes order — instantiate's loop
+        # iterates this instead of the attributes Hash so the per-call
+        # pair array disappears (see the instantiate comment).
+        def instantiate_attr_pairs(register_id = nil)
+          (@instantiate_attr_pairs ||= {})[register_id] ||=
+            attributes(register_id).to_a.freeze
+        end
+
         # Define register-specific attribute methods on the class itself.
         #
         # Called once per (class, register) combination. Replaces per-instance

data/lib/lutaml/model/type_resolver.rb

@@ -44,7 +44,9 @@ module Lutaml
       # 5. Raise UnknownTypeError if not found anywhere
       #
       # @param name [Symbol, String, Class] The type name or class to resolve
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context (nil means
+      #   no primary registry and no fallbacks — an id registered in the
+      #   Register namespace but not as a type context)
       # @return [Class] The resolved type class
       # @raise [UnknownTypeError] If type cannot be resolved
       #
@@ -66,11 +68,11 @@ module Lutaml
         type_name = name.to_sym
 
         # 1. Check primary registry
-        type = context.lookup_local(type_name)
+        type = context&.lookup_local(type_name)
         return apply_substitutions(type, context) if type
 
         # 2. Check fallback contexts in order
-        if context.has_fallbacks?
+        if context&.has_fallbacks?
           context.fallback_contexts.each do |fallback_context|
             type = resolve_from_fallback(type_name, fallback_context)
             return apply_substitutions(type, context) if type
@@ -97,8 +99,8 @@ module Lutaml
         # 5. Type not found - raise error
         raise UnknownTypeError.new(
           type_name,
-          context_id: context.id,
-          available_types: available_type_names(context),
+          context_id: context&.id,
+          available_types: context ? available_type_names(context) : [],
         )
       end
 

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.100"
+    VERSION = "0.8.119"
   end
 end

data/lib/lutaml/xml/adapter/leptris_adapter.rb

@@ -9,6 +9,7 @@ module Lutaml
         MOXML_ADAPTER = Moxml::Adapter::Leptris
         BUILDER_CLASS = Builder::Leptris
         PARSED_ELEMENT_CLASS = Lutaml::Xml::LeptrisElement
+        PARSE_ERROR_CLASS = Moxml::ParseError
       end
     end
   end

data/lib/lutaml/xml/adapter/xml_parser.rb

@@ -20,10 +20,9 @@ module Lutaml
           raw_xml = xml
           xml = normalize_xml_for_parse(xml)
           parsed = parse_with_moxml(xml, parse_encoding)
-          assert_no_truncated_recovered_parse!(parsed)
           root_element = parsed.root
 
-          raise_empty_document_error if root_element.nil?
+          raise_empty_document_error(parsed.parse_errors) if root_element.nil?
 
           root = self::PARSED_ELEMENT_CLASS.new(root_element)
           doc_pis = extract_document_processing_instructions(parsed)
@@ -31,31 +30,6 @@ module Lutaml
           new(root, parse_encoding, **parse_document_options(raw_xml))
         end
 
-        # Recover-mode parsing must never masquerade input truncation as
-        # success.
-        #
-        # moxml releases before 0.5.84 parsed Nokogiri documents without
-        # XML_PARSE_HUGE, so libxml2 capped its input buffer at 10 MB;
-        # longer documents tripped a fatal "Resource limit exceeded:
-        # Buffer size limit exceeded, try XML_PARSE_HUGE" error mid-input.
-        # In recover mode Nokogiri records that error on the document and
-        # returns the partial tree, so every node past the limit silently
-        # vanishes (lutaml-model#871). A resource-limit fatal means the
-        # engine stopped early with input left — refuse to deserialize the
-        # partial document instead of dropping trailing content without a
-        # trace.
-        #
-        # moxml 0.5.84 and later always pass XML_PARSE_HUGE, so the
-        # Nokogiri path no longer truncates and this guard stays silent;
-        # it remains for older moxml releases and for any other adapter
-        # that reports the resource-limit family.
-        #
-        # Other recover-mode fatals (e.g. an XML declaration after leading
-        # whitespace) do not drop content and keep the long-standing
-        # recover behavior; only the resource-limit family is truncating.
-        TRUNCATION_FATAL_MARKER =
-          /Resource limit exceeded|Buffer size limit exceeded/
-
         private
 
         def normalize_xml_for_parse(xml)
@@ -88,23 +62,6 @@ module Lutaml
           end
         end
 
-        def assert_no_truncated_recovered_parse!(parsed)
-          errors = parsed.parse_errors
-          return if errors.nil? || errors.empty?
-
-          fatal = errors.find do |message|
-            message.match?(TRUNCATION_FATAL_MARKER)
-          end
-          return if fatal.nil?
-
-          raise Lutaml::Model::InvalidFormatError.new(
-            :xml,
-            "the XML engine reported a fatal resource limit and recovered " \
-            "with a truncated document; refusing to deserialize " \
-            "partial input (#{fatal})",
-          )
-        end
-
         def parse_document_options(xml)
           {
             doctype: extract_doctype_from_xml(xml),
@@ -112,8 +69,11 @@ module Lutaml
           }
         end
 
-        def raise_empty_document_error
+        def raise_empty_document_error(parse_errors = nil)
           message = self::EMPTY_DOCUMENT_ERROR_MESSAGE
+          if parse_errors && !parse_errors.empty?
+            message += " (the XML engine reported: #{parse_errors.join('; ')})"
+          end
 
           case self::EMPTY_DOCUMENT_ERROR_TYPE
           when :parse_exception