multi_xml 0.6.0 → 0.9.1

data/sig/multi_xml.rbs

@@ -0,0 +1,304 @@
+# 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: ((IO | StringIO) io) -> MultiXML::xmlHash?
+           | ((IO | StringIO) io, ?namespaces: Symbol) -> MultiXML::xmlHash?
+  def parse_error: () -> singleton(Exception)
+end
+
+module MultiXML
+  extend Options
+
+  type parse_options_input = Hash[Symbol, untyped] | ^() -> Hash[Symbol, untyped] | ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  VERSION: Gem::Version
+
+  TEXT_CONTENT_KEY: String
+
+  RUBY_TYPE_TO_XML: Hash[String, String]
+
+  DISALLOWED_TYPES: Array[String]
+
+  FALSE_BOOLEAN_VALUES: Set[String]
+
+  NAMESPACE_MODES: Array[Symbol]
+
+  DEFAULT_OPTIONS: Hash[Symbol, bool | Array[String] | Symbol]
+
+  # Array of [library_name, parser_symbol] pairs
+  PARSER_PREFERENCE: Array[Array[String | Symbol]]
+
+  PARSE_DATETIME: ^(String) -> Time
+
+  ISO_WEEK_DATE: Regexp
+
+  # 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]
+
+  DEPRECATION_WARNINGS_SHOWN: Set[Symbol]
+
+  self.@parser: Module
+
+  extend Helpers
+
+  module Concurrency
+    MUTEXES: Hash[Symbol, Thread::Mutex]
+
+    def self.synchronize: [T] (Symbol name) { () -> T } -> T
+  end
+
+  module Options
+    EMPTY_OPTIONS: Hash[Symbol, untyped]
+
+    def parse_options=: (parse_options_input options) -> parse_options_input
+
+    def parse_options: (*untyped args) -> Hash[Symbol, untyped]
+  end
+
+  module Parser
+    def parse_error: () -> Class
+  end
+
+  module ParserResolution
+    LOADED_PARSER_CHECKS: Hash[Symbol, Symbol]
+  end
+
+  module ParseSupport
+  end
+
+  # Emit a deprecation warning at most once per process
+  def self.warn_deprecation_once: (Symbol key, String message) -> void
+
+  # 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
+
+  def self.parse_iso_week_datetime: (String string) -> Time
+  # Public API: Execute a block with a temporarily-swapped parser
+  def self.with_parser: [T] (Symbol | String | Module new_parser) { () -> T } -> T
+  # Deprecated alias for `parse`
+  def self.load: (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
+
+  # Validate that a parser satisfies the contract
+  def self.validate_parser!: (Module parser) -> 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: ((IO | StringIO) io, untyped original_input, untyped xml_parser, Symbol namespaces) -> xmlHash
+
+  # Dispatch to parsers that may or may not accept `namespaces:`
+  def self.parse_with_namespaces_compatibility: ((IO | StringIO) io, untyped xml_parser, Symbol namespaces) -> xmlHash?
+
+  # Validate the :namespaces option value
+  def self.validate_namespaces_mode: (untyped mode) -> Symbol
+
+  # Resolve which parser this parse call should use, honoring the :parser option
+  def self.resolve_parse_parser: (Hash[Symbol, untyped] options) -> Module
+
+  # Check whether a parser accepts the `namespaces:` keyword
+  def self.parser_supports_namespaces_keyword?: (untyped xml_parser) -> bool
+
+  # Apply typecasting and key-symbolization as configured
+  def self.apply_postprocessing: (xmlHash result, Hash[Symbol, untyped] options) -> xmlHash
+
+  module OptionsNormalization
+    # Translate the deprecated :symbolize_keys option to :symbolize_names
+    def self.normalize_symbolize_option: (Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+  end
+
+  # Define a deprecated alias that delegates to a new method name
+  def self.deprecate_alias: (Symbol name, Symbol replacement) -> Symbol
+
+  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 ParserLoadError < ArgumentError
+    def initialize: (?(String | nil) message, ?cause: Exception?) -> void
+
+    def self.build: (Exception original_exception) -> ParserLoadError
+  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
+
+# Backward-compatible alias for the legacy MultiXml constant name
+module MultiXml
+  def self.method_missing: (Symbol name, *untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped
+
+  def self.respond_to_missing?: ((Symbol | String) name, bool include_private) -> bool
+
+  def self.const_missing: (Symbol name) -> untyped
+end

metadata

@@ -1,54 +1,88 @@
 --- !ruby/object:Gem::Specification
 name: multi_xml
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.9.1
 platform: ruby
 authors:
-- Erik Michaels-Ober
-autorequire: 
-bindir: bin
+- Erik Berlin
+bindir: exe
 cert_chain: []
-date: 2016-12-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
+        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: '1.0'
-description: Provides swappable XML backends utilizing LibXML, Nokogiri, Ox, or REXML.
-email: sferik@gmail.com
+        version: '5'
+email:
+- sferik@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".mutant.yml"
+- ".rspec"
+- ".rubocop.yml"
 - ".yardopts"
 - CHANGELOG.md
 - CONTRIBUTING.md
+- Gemfile
 - LICENSE.md
 - README.md
+- Rakefile
+- Steepfile
+- benchmark.rb
+- benchmark/overall_parser_benchmark.rb
 - lib/multi_xml.rb
+- lib/multi_xml/concurrency.rb
+- lib/multi_xml/constants.rb
+- lib/multi_xml/deprecated.rb
+- lib/multi_xml/errors.rb
+- lib/multi_xml/file_like.rb
+- lib/multi_xml/helpers.rb
+- lib/multi_xml/options.rb
+- lib/multi_xml/options_normalization.rb
+- lib/multi_xml/parse_support.rb
+- lib/multi_xml/parser.rb
+- lib/multi_xml/parser_resolution.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
-- multi_xml.gemspec
+- sig/multi_xml.rbs
 homepage: https://github.com/sferik/multi_xml
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/sferik/multi_xml/issues
+  changelog_uri: https://github.com/sferik/multi_xml/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/multi_xml/
+  funding_uri: https://github.com/sponsors/sferik
+  homepage_uri: https://github.com/sferik/multi_xml
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/sferik/multi_xml
 rdoc_options: []
 require_paths:
 - lib
@@ -56,16 +90,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.5
+      version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2
-signing_key: 
+rubygems_version: 4.0.11
 specification_version: 4
-summary: A generic swappable back-end for XML parsing
+summary: Provides swappable XML backends utilizing LibXML, Nokogiri, Ox, or REXML.
 test_files: []

data/lib/multi_xml/parsers/libxml2_parser.rb

@@ -1,72 +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 AbcSize, CyclomaticComplexity, MethodLength, PerceivedComplexity
-        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
-        if node_hash[MultiXml::CONTENT_ROOT].strip.empty?
-          node_hash.delete(MultiXml::CONTENT_ROOT)
-        end
-
-        # 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.new("inheritor should define #{__method__}"))
-      end
-
-    private
-
-      def each_child(*)
-        raise(NotImplementedError.new("inheritor should define #{__method__}"))
-      end
-
-      def each_attr(*)
-        raise(NotImplementedError.new("inheritor should define #{__method__}"))
-      end
-
-      def node_name(*)
-        raise(NotImplementedError.new("inheritor should define #{__method__}"))
-      end
-    end
-  end
-end

data/multi_xml.gemspec

@@ -1,19 +0,0 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'multi_xml/version'
-
-Gem::Specification.new do |spec|
-  spec.add_development_dependency 'bundler', '~> 1.0'
-  spec.author = 'Erik Michaels-Ober'
-  spec.description = 'Provides swappable XML backends utilizing LibXML, Nokogiri, Ox, or REXML.'
-  spec.email = 'sferik@gmail.com'
-  spec.files = %w(.yardopts CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md multi_xml.gemspec) + Dir['lib/**/*.rb']
-  spec.homepage = 'https://github.com/sferik/multi_xml'
-  spec.licenses = ['MIT']
-  spec.name = 'multi_xml'
-  spec.require_paths = ['lib']
-  spec.required_rubygems_version = '>= 1.3.5'
-  spec.summary = 'A generic swappable back-end for XML parsing'
-  spec.version = MultiXml::Version
-end