nori 2.7.1 → 2.9.0

data/lib/nori/xml_utility_node.rb

@@ -92,12 +92,11 @@ class Nori
         attributes = Hash[*intermediate]
       end
 
-      # leave the type alone if we don't know what it is
-      @type = self.class.available_typecasts.include?(attributes["type"]) ? attributes.delete("type") : attributes["type"]
+      @type = bare_type(attributes)
 
       @nil_element = false
       attributes.keys.each do |key|
-        if result = /^((.*):)?nil$/.match(key)
+        if result = nil_attribute_pattern.match(key)
           @nil_element = attributes.delete(key) == "true"
           attributes.delete("xmlns:#{result[2]}") if result[1]
         end
@@ -127,59 +126,26 @@ class Nori
       @children << node
     end
 
+    # Converts the node into a hash with the node name as its single key.
+    #
+    # The value depends on the shape of the node. A node typed as "file"
+    # becomes a {StringIOFile}, unless the +:serializable+ profile is enabled.
+    # That profile returns plain data only, so a file node folds into text and
+    # attributes like any other node and the base64 content is left undecoded.
+    # A node with text content becomes a typecast scalar. Every other node
+    # folds its children into an array or a hash. Under the +:standards+
+    # profile no bare type attribute is honored ({#bare_type}), so file
+    # decoding, array folding and typecasting never happen there.
+    #
+    # @return [Hash{String => Object}] the node name mapped to its value
     def to_hash
-      if @type == "file"
-        f = StringIOFile.new((@children.first || '').unpack('m').first)
-        f.original_filename = attributes['name'] || 'untitled'
-        f.content_type = attributes['content_type'] || 'application/octet-stream'
-        return { name => f }
-      end
-
-      if @text
-        t = typecast_value(inner_html)
-        t = advanced_typecasting(t) if t.is_a?(String) && @options[:advanced_typecasting]
+      return { name => file_value } if @type == "file" && !@options[:serializable]
+      return { name => text_value } if @text
 
-        if t.is_a?(String)
-          t = StringWithAttributes.new(t)
-          t.attributes = attributes
-        end
-
-        return { name => t }
-      else
-        #change repeating groups into an array
-        groups = @children.inject({}) { |s,e| (s[e.name] ||= []) << e; s }
-
-        out = nil
-        if @type == "array"
-          out = []
-          groups.each do |k, v|
-            if v.size == 1
-              out << v.first.to_hash.entries.first.last
-            else
-              out << v.map{|e| e.to_hash[k]}
-            end
-          end
-          out = out.flatten
-
-        else # If Hash
-          out = {}
-          groups.each do |k,v|
-            if v.size == 1
-              out.merge!(v.first)
-            else
-              out.merge!( k => v.map{|e| e.to_hash[k]})
-            end
-          end
-          out.merge! prefixed_attributes unless attributes.empty?
-          out = out.empty? ? @options[:empty_tag_value] : out
-        end
-
-        if @type && out.nil?
-          { name => typecast_value(out) }
-        else
-          { name => out }
-        end
-      end
+      groups = group_children
+      value = @type == "array" ? array_value(groups) : hash_value(groups)
+      value = typecast_value(value) if @type && value.nil?
+      { name => value }
     end
 
     # Typecasts a value based upon its type. For instance, if
@@ -248,6 +214,138 @@ class Nori
     alias to_s to_html
 
     private
+
+    # The value of the bare (un-namespaced) type attribute, or nil under
+    # the +:standards+ profile. A recognized type is consumed from the
+    # attributes because typecasting replaces it with the value it
+    # describes. An unrecognized type stays visible as an ordinary
+    # attribute. The bare attribute is a Rails +Hash.from_xml+ convention
+    # rather than XML, so the +:standards+ profile never reads it and the
+    # attribute passes through as ordinary data.
+    #
+    # @param attributes [Hash{String => String}] the element's attributes
+    # @return [String, nil] the type name, or nil when there is none to honor
+    def bare_type(attributes)
+      return nil if @options[:standards]
+
+      if self.class.available_typecasts.include?(attributes["type"])
+        attributes.delete("type")
+      else
+        attributes["type"]
+      end
+    end
+
+    # The attribute forms that declare an element nil. The prefixed form
+    # is the XML Schema Instance convention (xsi:nil). The bare +nil+ form
+    # is a Rails +Hash.from_xml+ convention, so the +:standards+ profile
+    # only accepts the prefixed form.
+    #
+    # @return [Regexp] the pattern, with the prefix in capture group 2
+    def nil_attribute_pattern
+      @options[:standards] ? /^((.+):)nil$/ : /^((.*):)?nil$/
+    end
+
+    # Decodes the base64 content of a node typed as "file" into a
+    # {StringIOFile} carrying the filename and content type attributes.
+    def file_value
+      file = StringIOFile.new((@children.first || '').unpack('m').first)
+      file.original_filename = attributes['name'] || 'untitled'
+      file.content_type = attributes['content_type'] || 'application/octet-stream'
+      file
+    end
+
+    # Typecasts the text content of the node. String results are wrapped
+    # so the node's attributes stay accessible on the value.
+    def text_value
+      value = typecast_value(inner_html)
+      value = advanced_typecasting(value) if value.is_a?(String) && @options[:advanced_typecasting]
+      value.is_a?(String) ? string_with_attributes(value) : value
+    end
+
+    # Groups the child nodes by their name so repeating siblings can be
+    # folded into arrays.
+    #
+    # @return [Hash{String => Array<XMLUtilityNode>}]
+    def group_children
+      @children.inject({}) { |hash, child| (hash[child.name] ||= []) << child; hash }
+    end
+
+    # Collects the values of all child nodes for a node typed as "array".
+    def array_value(groups)
+      values = []
+      groups.each do |child_name, nodes|
+        if nodes.size == 1
+          values << nodes.first.to_hash.entries.first.last
+        else
+          values << nodes.map { |node| node.to_hash[child_name] }
+        end
+      end
+      values.flatten
+    end
+
+    # Folds the child nodes and the prefixed attributes into a hash.
+    # An empty result becomes the :empty_tag_value option.
+    def hash_value(groups)
+      return consistent_empty_value if @options[:consistent_empty_tags] && groups.empty?
+
+      value = {}
+      groups.each do |child_name, nodes|
+        if nodes.size == 1
+          value.merge!(nodes.first.to_hash)
+        else
+          value.merge!(child_name => nodes.map { |node| node.to_hash[child_name] })
+        end
+      end
+      value.merge!(prefixed_attributes) unless attributes.empty?
+      value.empty? ? @options[:empty_tag_value] : value
+    end
+
+    # Resolves an element without children and without text when the
+    # :consistent_empty_tags option is set. The element becomes the
+    # :empty_tag_value option no matter which attributes it carries.
+    # A string value keeps the attributes accessible on the value.
+    # An explicit xsi:nil="true" wins over the option and becomes nil.
+    def consistent_empty_value
+      return nil if @nil_element
+
+      value = @options[:empty_tag_value]
+      value.is_a?(String) ? string_with_attributes(value) : value
+    end
+
+    # Combines a string +value+ with the node's attributes in the shape the
+    # active output profile calls for.
+    #
+    # By default the value is a {StringWithAttributes}: a String carrying the
+    # node's attributes on {StringWithAttributes#attributes}. Under the
+    # +:serializable+ profile the value becomes plain, directly-serializable
+    # data instead, so no custom String subclass is returned.
+    #
+    # @param value [String] the typecast text content of the node
+    # @return [StringWithAttributes, Hash{String => String}, String] the value
+    #   in the configured representation
+    def string_with_attributes(value)
+      return serializable_value(value) if @options[:serializable]
+
+      string = StringWithAttributes.new(value)
+      string.attributes = attributes
+      string
+    end
+
+    # The +:serializable+ representation of a string +value+ and the node's
+    # attributes. A node with attributes maps to the XML JSON convention
+    # (+{"#text" => value}+ merged with the "@"-prefixed attributes) and a
+    # node without attributes maps to the plain String. The attribute keys go
+    # through the same prefixing and tag conversion as element-node attributes
+    # ({#prefixed_attributes}), so every node kind shares one convention.
+    #
+    # @param value [String] the typecast text content of the node
+    # @return [Hash{String => String}, String] the hash shape when the node
+    #   has attributes, otherwise the plain +value+
+    def serializable_value(value)
+      return value if attributes.empty?
+      { "#text" => value }.merge(prefixed_attributes)
+    end
+
     def try_to_convert(value, &block)
       block.call(value)
     rescue ArgumentError

data/lib/nori.rb

@@ -20,14 +20,17 @@ class Nori
       :convert_tags_to               => nil,
       :convert_attributes_to         => nil,
       :empty_tag_value               => nil,
+      :consistent_empty_tags         => false,
       :advanced_typecasting          => true,
       :convert_dashes_to_underscores => true,
       :scrub_xml                     => true,
+      :standards                     => false,
+      :serializable                  => false,
       :parser                        => :nokogiri
     }
 
     validate_options! defaults.keys, options.keys
-    @options = defaults.merge(options)
+    @options = defaults.merge(standards_defaults(options)).merge(options)
   end
 
   def find(hash, *path)
@@ -49,6 +52,29 @@ class Nori
   end
 
   private
+
+  # The defaults implied by the +:standards+ profile.
+  #
+  # The profile groups the spec-correct behaviors under a single opt-in.
+  # It turns on the XML string-value model for empty elements
+  # (+:consistent_empty_tags+ with an empty-string +:empty_tag_value+),
+  # turns off +:advanced_typecasting+ (schema-less values are text, their
+  # types are the business of a schema-aware layer) and, in the parsers,
+  # honors xml:space. These are defaults, so an explicit option passed by
+  # the caller still wins. When the profile is off the hash is empty and
+  # parsing is unchanged.
+  #
+  # @param options [Hash] the options passed to {#initialize}
+  # @return [Hash] the implied defaults, or +{}+ when the profile is off
+  def standards_defaults(options)
+    return {} unless options[:standards]
+    {
+      :consistent_empty_tags => true,
+      :empty_tag_value       => "",
+      :advanced_typecasting  => false
+    }
+  end
+
   def load_parser(parser)
     require "nori/parser/#{parser}"
     Parser.const_get PARSERS[parser]

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: nori
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: 2.9.0
 platform: ruby
 authors:
 - Daniel Harrington
 - John Nunemaker
 - Wynn Netherland
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-07-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -26,20 +25,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: stringio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: '13.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: '13.3'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -74,18 +87,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".devcontainer/devcontainer.json"
-- ".github/dependabot.yml"
-- ".github/workflows/test.yml"
-- ".gitignore"
-- ".rspec"
 - CHANGELOG.md
-- Gemfile
 - LICENSE
 - README.md
-- Rakefile
-- benchmark/benchmark.rb
-- benchmark/soap_response.xml
 - lib/nori.rb
 - lib/nori/core_ext.rb
 - lib/nori/core_ext/hash.rb
@@ -96,18 +100,11 @@ files:
 - lib/nori/string_with_attributes.rb
 - lib/nori/version.rb
 - lib/nori/xml_utility_node.rb
-- nori.gemspec
-- spec/nori/api_spec.rb
-- spec/nori/core_ext/hash_spec.rb
-- spec/nori/nori_spec.rb
-- spec/nori/string_utils_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/savonrb/nori
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -122,8 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: XML to Hash translator
 test_files: []

data/.devcontainer/devcontainer.json

@@ -1,19 +0,0 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the
-// README at: https://github.com/devcontainers/templates/tree/main/src/ruby
-{
-	"name": "Ruby",
-	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-	"image": "mcr.microsoft.com/devcontainers/ruby:0-3-bullseye"
-
-	// Features to add to the dev container. More info: https://containers.dev/features.
-	// "features": {},
-
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	// "forwardPorts": [],
-
-	// Configure tool-specific properties.
-	// "customizations": {},
-
-	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
-	// "remoteUser": "root"
-}

data/.github/dependabot.yml

@@ -1,12 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for more information:
-# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-# https://containers.dev/guide/dependabot
-
-version: 2
-updates:
- - package-ecosystem: "devcontainers"
-   directory: "/"
-   schedule:
-     interval: weekly

data/.github/workflows/test.yml

@@ -1,26 +0,0 @@
-name: CI
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    
-    strategy:
-      matrix:
-        ruby-version:
-          - '3.0'
-          - '3.1'
-          - '3.2'
-          - '3.3'
-          - 'head'
-          - jruby-9.4.5.0
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby ${{ matrix.ruby-version }}
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically        
-    - name: Run tests
-      run: bundle exec rake

data/.gitignore

@@ -1,8 +0,0 @@
-.DS_Store
-doc
-coverage
-*~
-*.gem
-.bundle
-Gemfile.lock
-/.idea

data/.rspec

@@ -1 +0,0 @@
---colour

data/Gemfile

@@ -1,6 +0,0 @@
-source 'https://rubygems.org'
-gemspec
-
-if RUBY_VERSION >= "3"
-  gem "rexml", "~> 3.2"
-end

data/Rakefile

@@ -1,12 +0,0 @@
-require "bundler/gem_tasks"
-
-desc "Benchmark Nori parsers"
-task :benchmark do
-  require "benchmark/benchmark"
-end
-
-require "rspec/core/rake_task"
-RSpec::Core::RakeTask.new
-
-task :default => :spec
-task :test => :spec

data/benchmark/benchmark.rb

@@ -1,19 +0,0 @@
-$:.push File.expand_path("../../lib", __FILE__)
-require "nori"
-
-require "benchmark"
-
-Benchmark.bm 30 do |x|
-
-  num = 500
-  xml = File.read File.expand_path("../soap_response.xml", __FILE__)
-
-  x.report "rexml parser" do
-    num.times { Nori.new(parser: :rexml).parse xml }
-  end
-
-  x.report "nokogiri parser" do
-    num.times { Nori.new(parser: :nokogiri).parse xml }
-  end
-
-end