multi_xml 0.7.2 → 0.8.0

data/sig/multi_xml.rbs

@@ -0,0 +1,227 @@
+# Type signatures for MultiXml
+
+# Recursive type alias for parsed XML values
+# XML parsing produces nested structures of hashes, arrays, and primitive values
+type MultiXml::xmlValue = String
+                        | Integer
+                        | Float
+                        | bool
+                        | Symbol
+                        | Time
+                        | Date
+                        | BigDecimal
+                        | StringIO
+                        | nil
+                        | Array[MultiXml::xmlValue]
+                        | Hash[String, MultiXml::xmlValue]
+                        | Hash[Symbol, MultiXml::xmlValue]
+
+# Type for hash with string keys used internally during parsing
+type MultiXml::xmlHash = Hash[String, MultiXml::xmlValue]
+
+# Interface for parser modules
+interface MultiXml::_Parser
+  def parse: (StringIO io) -> MultiXml::xmlHash?
+  def parse_error: () -> singleton(Exception)
+end
+
+module MultiXml
+  VERSION: Gem::Version
+
+  TEXT_CONTENT_KEY: String
+
+  RUBY_TYPE_TO_XML: Hash[String, String]
+
+  DISALLOWED_TYPES: Array[String]
+
+  FALSE_BOOLEAN_VALUES: Set[String]
+
+  DEFAULT_OPTIONS: Hash[Symbol, bool | Array[String]]
+
+  # Array of [library_name, parser_symbol] pairs
+  PARSER_PREFERENCE: Array[Array[String | Symbol]]
+
+  PARSE_DATETIME: ^(String) -> Time
+
+  # Lambda for creating file-like StringIO from base64 content
+  # Uses untyped for content because unpack1 returns various types
+  # Uses untyped for entity because hash values are xmlValue but we access specific String keys
+  FILE_CONVERTER: ^(untyped, untyped) -> StringIO
+
+  # Type converters keyed by XML type attribute string
+  # Uses untyped key because hash["type"] returns xmlValue, and Hash#[] with non-String returns nil
+  TYPE_CONVERTERS: Hash[untyped, Proc | Method]
+
+  LOADED_PARSER_CHECKS: Hash[Symbol, Symbol]
+
+  self.@parser: Module
+
+  extend Helpers
+
+  # Public API: Get the current XML parser module
+  def self.parser: () -> Module
+
+  # Public API: Set the XML parser to use
+  def self.parser=: (Symbol | String | Module new_parser) -> Module
+
+  # Public API: Parse XML into a Ruby Hash
+  # Uses untyped for options because values vary by key (:parser, :symbolize_keys, :disallowed_types, :typecast_xml_value)
+  def self.parse: (String | StringIO xml, ?Hash[Symbol, untyped] options) -> xmlHash
+
+  private
+
+  # Resolve a parser specification (Symbol, String, or Module) to a parser
+  def self.resolve_parser: (Symbol | String | Module spec) -> Module
+
+  # Load a parser module by name
+  def self.load_parser: (Symbol | String name) -> Module
+
+  # Convert snake_case to CamelCase
+  def self.camelize: (String name) -> String
+
+  # Detect the best available parser
+  def self.detect_parser: () -> (Symbol | String)
+
+  # Find an already-loaded parser library
+  def self.find_loaded_parser: () -> Symbol?
+
+  # Try to find an available parser by requiring libraries
+  def self.find_available_parser: () -> (String | Symbol | nil)
+
+  # Attempt to require a library, returning success/failure
+  # Kernel#require accepts String; library may be Symbol from PARSER_PREFERENCE (coerced at runtime)
+  def self.try_require: (untyped library) -> bool
+
+  # Raise NoParserError - never returns
+  def self.raise_no_parser_error: () -> bot
+
+  # Convert String to StringIO, pass through IO-like objects
+  # Uses respond_to?(:read) duck typing - returns input unchanged if IO-like
+  def self.normalize_input: (String | StringIO xml) -> untyped
+
+  # Parse with error handling and key normalization
+  # xml_parser implements _Parser interface; original_input uses respond_to? duck typing
+  def self.parse_with_error_handling: (StringIO io, untyped original_input, untyped xml_parser) -> xmlHash
+
+  module Helpers
+    # Recursively convert all hash keys to symbols
+    # Uses case/when type dispatch - Steep can't track flow narrowing
+    def self?.symbolize_keys: (untyped data) -> untyped
+
+    # Recursively convert dashes in hash keys to underscores
+    # Uses case/when type dispatch - Steep can't track flow narrowing
+    def self?.undasherize_keys: (untyped data) -> untyped
+
+    # Recursively typecast XML values based on type attributes
+    # Uses case/when type dispatch - Steep can't track flow narrowing
+    def self?.typecast_xml_value: (untyped value, ?Array[String] disallowed_types) -> xmlValue
+
+    # Typecast array elements and unwrap single-element arrays
+    def self?.typecast_array: (Array[xmlValue] array, Array[String] disallowed_types) -> xmlValue
+
+    # Typecast a hash based on its type attribute
+    def self?.typecast_hash: (xmlHash hash, Array[String] disallowed_types) -> xmlValue
+
+    # Check if a type is in the disallowed list
+    # Uses is_a?(Hash) guard then include? - Steep can't narrow xmlValue to String
+    def self?.disallowed_type?: (untyped type, Array[String] disallowed_types) -> boolish
+
+    # Convert a hash based on its type and content
+    def self?.convert_hash: (xmlHash hash, xmlValue type, Array[String] disallowed_types) -> xmlValue
+
+    # Typecast all child values in a hash
+    def self?.typecast_children: (xmlHash hash, Array[String] disallowed_types) -> (xmlHash | StringIO)
+
+    # Extract array entries from element with type="array"
+    def self?.extract_array_entries: (xmlHash hash, Array[String] disallowed_types) -> Array[xmlValue]
+
+    # Find array or hash entries in a hash, excluding the type key
+    # Returns xmlValue subset (Array or Hash) - uses is_a? that Steep can't narrow
+    def self?.find_array_entries: (xmlHash hash) -> untyped
+
+    # Wrap hash in array if needed and typecast all entries
+    def self?.wrap_and_typecast: (Array[xmlValue] | xmlHash entries, Array[String] disallowed_types) -> Array[xmlValue]
+
+    # Convert text content using type converters
+    # hash["type"] is xmlValue, used as Hash key - Steep requires String
+    def self?.convert_text_content: (xmlHash hash) -> xmlValue
+
+    # Unwrap value if hash has no other significant keys
+    def self?.unwrap_if_simple: (xmlHash hash, xmlValue value) -> (xmlValue | xmlHash)
+
+    # Check if a hash represents an empty value
+    def self?.empty_value?: (xmlHash hash, xmlValue type) -> bool
+
+    private
+
+    # Recursively transform hash keys using a block
+    # Block receives key (String) and returns transformed key
+    # Uses untyped because &:to_sym Proc type narrowing not supported by Steep
+    def self?.transform_keys: (untyped data) { (untyped) -> untyped } -> untyped
+
+    # Unwrap a file object from the result hash if present
+    def self?.unwrap_file_if_present: (xmlHash result) -> (xmlHash | StringIO)
+
+    # Apply a type converter to content
+    # Content is xmlValue (from hash.fetch) but typically String in practice
+    def self?.apply_converter: (xmlHash hash, untyped content, Proc | Method converter) -> xmlValue
+  end
+
+  module FileLike
+    DEFAULT_FILENAME: String
+
+    DEFAULT_CONTENT_TYPE: String
+
+    @original_filename: String?
+
+    @content_type: String?
+
+    attr_writer original_filename: String?
+
+    attr_writer content_type: String?
+
+    def original_filename: () -> String
+
+    def content_type: () -> String
+  end
+
+  # Represents a StringIO that has been extended with FileLike
+  # Used for file type conversions in XML parsing
+  class FileIO < StringIO
+    include FileLike
+  end
+
+  class ParseError < StandardError
+    @xml: String?
+
+    @cause: Exception?
+
+    attr_reader xml: String?
+
+    attr_reader cause: Exception?
+
+    # Message can be String (normal) or Exception (from parser errors), or nil for default
+    def initialize: (?(String | Exception | nil) message, ?xml: String?, ?cause: Exception?) -> void
+  end
+
+  class NoParserError < StandardError
+  end
+
+  class DisallowedTypeError < StandardError
+    @type: String
+
+    attr_reader type: String
+
+    def initialize: (String type) -> void
+  end
+
+  # Parsers module - parser implementations depend on optional external gems
+  module Parsers
+  end
+end
+
+# Stub for Psych::SyntaxError which is part of the yaml library
+module Psych
+  class SyntaxError < ::StandardError
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multi_xml
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Erik Berlin
@@ -13,22 +13,29 @@ dependencies:
   name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 email:
 - sferik@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".mutant.yml"
 - ".rspec"
 - ".rubocop.yml"
 - ".yardopts"
@@ -38,14 +45,23 @@ files:
 - LICENSE.md
 - README.md
 - Rakefile
+- Steepfile
 - lib/multi_xml.rb
+- lib/multi_xml/constants.rb
+- lib/multi_xml/errors.rb
+- lib/multi_xml/file_like.rb
+- lib/multi_xml/helpers.rb
+- lib/multi_xml/parsers/dom_parser.rb
 - lib/multi_xml/parsers/libxml.rb
-- lib/multi_xml/parsers/libxml2_parser.rb
+- lib/multi_xml/parsers/libxml_sax.rb
 - lib/multi_xml/parsers/nokogiri.rb
+- lib/multi_xml/parsers/nokogiri_sax.rb
 - lib/multi_xml/parsers/oga.rb
 - lib/multi_xml/parsers/ox.rb
 - lib/multi_xml/parsers/rexml.rb
+- lib/multi_xml/parsers/sax_handler.rb
 - lib/multi_xml/version.rb
+- sig/multi_xml.rbs
 homepage: https://github.com/sferik/multi_xml
 licenses:
 - MIT
@@ -72,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Provides swappable XML backends utilizing LibXML, Nokogiri, Ox, or REXML.
 test_files: []

data/lib/multi_xml/parsers/libxml2_parser.rb

@@ -1,70 +0,0 @@
-module MultiXml
-  module Parsers
-    module Libxml2Parser # :nodoc:
-      # Convert XML document to hash
-      #
-      # node::
-      #   The XML node object to convert to a hash.
-      #
-      # hash::
-      #   Hash to merge the converted element into.
-      def node_to_hash(node, hash = {}) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
-        node_hash = {MultiXml::CONTENT_ROOT => ""}
-
-        name = node_name(node)
-
-        # Insert node hash into parent hash correctly.
-        case hash[name]
-        when Array
-          hash[name] << node_hash
-        when Hash
-          hash[name] = [hash[name], node_hash]
-        when NilClass
-          hash[name] = node_hash
-        end
-
-        # Handle child elements
-        each_child(node) do |c|
-          if c.element?
-            node_to_hash(c, node_hash)
-          elsif c.text? || c.cdata?
-            node_hash[MultiXml::CONTENT_ROOT] += c.content
-          end
-        end
-
-        # Remove content node if it is empty
-        node_hash.delete(MultiXml::CONTENT_ROOT) if node_hash[MultiXml::CONTENT_ROOT].strip.empty?
-
-        # Handle attributes
-        each_attr(node) do |a|
-          key = node_name(a)
-          v = node_hash[key]
-          node_hash[key] = ((v) ? [a.value, v] : a.value)
-        end
-
-        hash
-      end
-
-      # Parse an XML Document IO into a simple hash.
-      # xml::
-      #   XML Document IO to parse
-      def parse(_)
-        raise(NotImplementedError, "inheritor should define #{__method__}")
-      end
-
-      private
-
-      def each_child(*)
-        raise(NotImplementedError, "inheritor should define #{__method__}")
-      end
-
-      def each_attr(*)
-        raise(NotImplementedError, "inheritor should define #{__method__}")
-      end
-
-      def node_name(*)
-        raise(NotImplementedError, "inheritor should define #{__method__}")
-      end
-    end
-  end
-end