lutaml-model 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa60d5495804e6bfc0203ba1a237f38b89b9626d036beeb2be8ca7aebb22426f
-  data.tar.gz: 63d8d18127bee85cfaa73973f57554bc56385805dfeea1dad343c552277089d6
+  metadata.gz: b1472bd6c2746013aba5d315d47dc5e484cfa54f6f537ab5d613b81f4f63109e
+  data.tar.gz: 45c48daa9b4a0f7b98d04bb8174f6cfe298c59564b714b866f838b7d2bf6464b
 SHA512:
-  metadata.gz: 322a29941e7685a6e118d083f1b6e11ce6b8abc1cacb5508dd501f874c5ea3f2dc6f0e6719ce4895deb31c877319a3afe0e20d0820a81b8fd60d9fe59c408472
-  data.tar.gz: ce087acefc221ed41180658b8c40d4cff5c0196c208647b9d1c5d0d39799849860abf80b981fe753b30a1176ca8633ed696440beeddef5a4493c1e829340f250
+  metadata.gz: 94f772a0efbc35332c95fb55729c8d781d4168ff61784af79d2f09388c93263144b378d8485e578f43aeb0386b2c02d4769285c782dffaa2c5d4dd6f0f34fa70
+  data.tar.gz: 4dd7279a62a8835e1f7c908590cc653d693f9a0225a388eda89bfa02cdcc7fb9a934bbf8d273f57d93d9764c86b867ae42a7aab2a87a4322c89698fa207343d0

data/.rubocop_todo.yml

@@ -1,14 +1,14 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-12-03 11:13:42 UTC using RuboCop version 1.66.1.
+# on 2025-01-07 08:52:47 UTC using RuboCop version 1.69.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 224
+# Offense count: 292
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
+# Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
@@ -31,7 +31,7 @@ Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/model/type/float.rb'
 
-# Offense count: 37
+# Offense count: 40
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
@@ -42,18 +42,20 @@ Metrics/AbcSize:
     - 'lib/lutaml/model/schema/xsd_schema.rb'
     - 'lib/lutaml/model/serialize.rb'
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
+    - 'lib/lutaml/model/xml_adapter/oga/element.rb'
+    - 'lib/lutaml/model/xml_adapter/oga_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
     - 'lib/lutaml/model/xml_mapping.rb'
     - 'lib/lutaml/model/xml_mapping_rule.rb'
 
-# Offense count: 6
+# Offense count: 9
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 46
 
-# Offense count: 28
+# Offense count: 32
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
@@ -61,21 +63,23 @@ Metrics/CyclomaticComplexity:
     - 'lib/lutaml/model/comparable_model.rb'
     - 'lib/lutaml/model/serialize.rb'
     - 'lib/lutaml/model/type/integer.rb'
+    - 'lib/lutaml/model/xml_adapter/builder/oga.rb'
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
+    - 'lib/lutaml/model/xml_adapter/oga_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
 
-# Offense count: 54
+# Offense count: 63
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 46
+  Max: 44
 
 # Offense count: 7
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 14
+  Max: 15
 
-# Offense count: 25
+# Offense count: 30
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
@@ -83,10 +87,19 @@ Metrics/PerceivedComplexity:
     - 'lib/lutaml/model/comparable_model.rb'
     - 'lib/lutaml/model/serialize.rb'
     - 'lib/lutaml/model/type/integer.rb'
+    - 'lib/lutaml/model/xml_adapter/builder/oga.rb'
+    - 'lib/lutaml/model/xml_adapter/builder/ox.rb'
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
+    - 'lib/lutaml/model/xml_adapter/oga_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
 
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/MapCompact:
+  Exclude:
+    - 'lib/lutaml/model/serialize.rb'
+
 # Offense count: 8
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
@@ -105,7 +118,7 @@ RSpec/DescribedClass:
   Exclude:
     - 'spec/lutaml/model/xml_mapping_spec.rb'
 
-# Offense count: 133
+# Offense count: 139
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 54
@@ -135,7 +148,7 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
     - 'spec/lutaml/model/xml_adapter_spec.rb'
 
-# Offense count: 157
+# Offense count: 172
 RSpec/MultipleExpectations:
   Max: 14
 
@@ -144,23 +157,19 @@ RSpec/MultipleExpectations:
 RSpec/MultipleMemoizedHelpers:
   Max: 9
 
-# Offense count: 15
+# Offense count: 24
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
 
-# Offense count: 13
+# Offense count: 9
 RSpec/PendingWithoutReason:
   Exclude:
-    - 'spec/lutaml/model/mixed_content_spec.rb'
     - 'spec/lutaml/model/type/date_time_spec.rb'
     - 'spec/lutaml/model/type/integer_spec.rb'
     - 'spec/lutaml/model/type/time_spec.rb'
     - 'spec/lutaml/model/type/time_without_date_spec.rb'
     - 'spec/lutaml/model/validation_spec.rb'
-    - 'spec/lutaml/model/xml_adapter/oga_adapter_spec.rb'
-    - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
-    - 'spec/lutaml/model/xml_adapter_spec.rb'
 
 # Offense count: 1
 RSpec/RemoveConst:
@@ -209,3 +218,10 @@ Style/MissingRespondToMissing:
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/lutaml/model/comparable_model.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: Mode.
+Style/StringConcatenation:
+  Exclude:
+    - 'spec/lutaml/model/xml_mapping_spec.rb'

data/README.adoc

@@ -2131,6 +2131,121 @@ end
 
 === Advanced attribute mapping
 
+==== Multiple mappings to single attribute
+
+The mapping methods support multiple names mapping to a single attribute using
+an array of names.
+
+Syntax:
+
+[source,ruby]
+----
+json | yaml | toml | key_value do
+  map ["name1", "name2"], to: :attribute_name
+end
+
+xml do
+  map_element ["name1", "name2"], to: :attribute_name
+  map_attribute ["attr1", "attr2"], to: :attribute_name
+end
+----
+
+When serializing, the first element in the array of mapped names is always used
+as the output name.
+
+
+.Using multiple names to map to a single attribute
+[example]
+====
+[source,ruby]
+----
+class CustomModel < Lutaml::Model::Serializable
+  attribute :full_name, Lutaml::Model::Type::String
+  attribute :color, Lutaml::Model::Type::String
+  attribute :id, Lutaml::Model::Type::String
+
+  json do
+    map ["name", "custom_name"], with: { to: :name_to_json, from: :name_from_json }
+    map ["color", "shade"], with: { to: :color_to_json, from: :color_from_json }
+  end
+
+  xml do
+    root "CustomModel"
+    map_element ["name", "custom-name"], with: { to: :name_to_xml, from: :name_from_xml }
+    map_element ["color", "shade"], with: { to: :color_to_xml, from: :color_from_xml }
+    map_attribute ["id", "identifier"], to: :id
+  end
+
+  # Custom methods for JSON
+  def name_to_json(model, doc)
+    doc["name"] = "JSON Model: #{model.full_name}"
+  end
+
+  def name_from_json(model, value)
+    model.full_name = value&.sub(/^JSON Model: /, "")
+  end
+
+  def color_to_json(model, doc)
+    doc["color"] = model.color.upcase
+  end
+
+  def color_from_json(model, value)
+    model.color = value&.downcase
+  end
+
+  # Custom methods for XML
+  def name_to_xml(model, parent, doc)
+    el = doc.create_element("name")
+    doc.add_text(el, "XML Model: #{model.full_name}")
+    doc.add_element(parent, el)
+  end
+
+  def name_from_xml(model, value)
+    model.full_name = value.sub(/^XML Model: /, "")
+  end
+
+  def color_to_xml(model, parent, doc)
+    el = doc.create_element("color")
+    doc.add_text(el, model.color.upcase)
+    doc.add_element(parent, el)
+  end
+
+  def color_from_xml(model, value)
+    model.color = value.downcase
+  end
+end
+----
+
+For JSON:
+[source,json]
+----
+{
+  "custom_name": "JSON Model: Vase",
+  "shade": "BLUE",
+  "identifier": "123"
+}
+----
+
+For XML:
+[source,xml]
+----
+<CustomModel id="123">
+  <name>XML Model: Vase</name>
+  <color>BLUE</color>
+</CustomModel>
+----
+
+[source,ruby]
+----
+> model = CustomModel.from_json(json)
+> model.full_name
+> # "Vase"
+> model.color
+> # "blue"
+----
+====
+
+
 ==== Attribute mapping delegation
 
 Delegate attribute mappings to nested objects using the `delegate` option.
@@ -2641,6 +2756,13 @@ klin.validate
 Lutaml::Model uses an adapter pattern to support multiple libraries for each
 serialization format.
 
+Lutaml::Model supports the following serialization formats:
+
+* XML (https://www.w3.org/TR/xmlschema-1/[W3C XML Schema (Second Edition)], XML 1.0)
+* YAML (https://yaml.org/[YAML version 1.2])
+* JSON (https://www.ecma-international.org/publications-and-standards/standards/ecma-404/[ECMA-404 The JSON Data Interchange Standard], unofficial link: https://www.json.org[JSON])
+* TOML (https://toml.io/en[TOML version 1.0])
+
 You will need to specify the configuration for the adapter you want to use. The
 easiest way is to copy and paste the following configuration into your code.
 
@@ -2684,9 +2806,25 @@ NOTE: By default `yaml_adapter_type` and `json_adapter_type` are set to
 
 Lutaml::Model supports the following XML adapters:
 
-* Nokogiri (default)
-* Oga (optional, plain Ruby suitable for Opal/JS)
-* Ox (optional)
+Nokogiri::
+(default)
+Popular `libxml` based XML parser for Ruby.
+Requires native extensions (i.e. compiled C code).
+Requires the `nokogiri` gem.
+
+Oga::
+(optional)
+Pure Ruby XML parser.
+Does not require native extensions and is suitable for
+https://opalrb.com[Opal] (Ruby on JavaScript).
+Requires the `oga` gem.
+
+Ox::
+(optional)
+Fast XML parser and object serializer for Ruby, implemented partially in C.
+Requires native extensions (i.e. compiled C code).
+Requires the `ox` gem.
+
 
 .Using the Nokogiri XML adapter
 [source,ruby]
@@ -2726,7 +2864,10 @@ end
 
 Lutaml::Model supports only one YAML adapter.
 
-* YAML (default)
+YAML::
+(default)
+The Psych YAML parser and emitter for Ruby.
+Included in the Ruby standard library.
 
 .Using the YAML adapter
 [source,ruby]
@@ -2745,8 +2886,15 @@ end
 
 Lutaml::Model supports the following JSON adapters:
 
-* JSON (default)
-* MultiJson (optional)
+JSON::
+(default)
+The standard JSON library for Ruby.
+Included in the Ruby standard library.
+
+MultiJson::
+(optional)
+A gem that provides a common interface to multiple JSON libraries.
+Requires the `multi_json` gem.
 
 .Using the JSON adapter
 [source,ruby]
@@ -2774,8 +2922,18 @@ end
 
 Lutaml::Model supports the following TOML adapters:
 
-* Toml-rb (default)
-* Tomlib (optional)
+Toml-rb::
+(default)
+A TOML parser and serializer for Ruby that is compatible with the TOML v1.0.0
+specification.
+Requires the `toml-rb` gem.
+
+Tomlib::
+(optional)
+Toml-rb fork that is compatible with the TOML v1.0.0 specification, but with
+additional features.
+Requires the `tomlib` gem.
+
 
 .Using the Toml-rb adapter
 [source,ruby]

data/lib/lutaml/model/key_value_mapping.rb

@@ -19,7 +19,6 @@ module Lutaml
         child_mappings: nil
       )
         validate!(name, to, with)
-
         @mappings << KeyValueMappingRule.new(
           name,
           to: to,

data/lib/lutaml/model/key_value_mapping_rule.rb

@@ -12,7 +12,8 @@ module Lutaml
         render_default: false,
         with: {},
         delegate: nil,
-        child_mappings: nil
+        child_mappings: nil,
+        id: nil
       )
         super(
           name,
@@ -21,6 +22,7 @@ module Lutaml
           render_default: render_default,
           with: with,
           delegate: delegate,
+          id: id
         )
 
         @child_mappings = child_mappings

data/lib/lutaml/model/mapping_rule.rb

@@ -16,7 +16,8 @@ module Lutaml
         render_default: false,
         with: {},
         attribute: false,
-        delegate: nil
+        delegate: nil,
+        id: nil
       )
         @name = name
         @to = to
@@ -25,6 +26,7 @@ module Lutaml
         @custom_methods = with
         @attribute = attribute
         @delegate = delegate
+        @id = id
       end
 
       alias from name
@@ -42,6 +44,8 @@ module Lutaml
         if delegate
           model.public_send(delegate).public_send(to)
         else
+          return if to.nil?
+
           model.public_send(to)
         end
       end
@@ -56,7 +60,7 @@ module Lutaml
 
       def deserialize(model, value, attributes, mapper_class = nil)
         if custom_methods[:from]
-          mapper_class.new.send(custom_methods[:from], model, value)
+          mapper_class.new.send(custom_methods[:from], model, value) unless value.nil?
         elsif delegate
           if model.public_send(delegate).nil?
             model.public_send(:"#{delegate}=", attributes[delegate].type.new)
@@ -68,6 +72,14 @@ module Lutaml
         end
       end
 
+      def using_custom_methods?
+        !custom_methods.empty?
+      end
+
+      def multiple_mappings?
+        name.is_a?(Array)
+      end
+
       def deep_dup
         raise NotImplementedError, "Subclasses must implement `deep_dup`."
       end

data/lib/lutaml/model/serialize.rb

@@ -21,6 +21,7 @@ module Lutaml
 
       def self.included(base)
         base.extend(ClassMethods)
+        base.initialize_attrs(base)
       end
 
       module ClassMethods
@@ -28,14 +29,18 @@ module Lutaml
 
         def inherited(subclass)
           super
+          subclass.initialize_attrs(self)
+        end
 
-          @mappings ||= {}
-          @attributes ||= {}
+        def included(base)
+          base.extend(ClassMethods)
+          base.initialize_attrs(self)
+        end
 
-          subclass.instance_variable_set(:@attributes,
-                                         Utils.deep_dup(@attributes))
-          subclass.instance_variable_set(:@mappings, Utils.deep_dup(@mappings))
-          subclass.instance_variable_set(:@model, subclass)
+        def initialize_attrs(source_class)
+          @mappings = Utils.deep_dup(source_class.instance_variable_get(:@mappings)) || {}
+          @attributes = Utils.deep_dup(source_class.instance_variable_get(:@attributes)) || {}
+          instance_variable_set(:@model, self)
         end
 
         def model(klass = nil)
@@ -264,15 +269,18 @@ module Lutaml
 
             value = instance.send(name)
 
-            next if Utils.blank?(value) && !rule.render_nil
-
             attribute = attributes[name]
 
-            hash[rule.from.to_s] = if rule.child_mappings
-                                     generate_hash_from_child_mappings(value, rule.child_mappings)
-                                   else
-                                     attribute.serialize(value, format, options)
-                                   end
+            value = if rule.child_mappings
+                      generate_hash_from_child_mappings(value, rule.child_mappings)
+                    else
+                      attribute.serialize(value, format, options)
+                    end
+
+            next if Utils.blank?(value) && !rule.render_nil
+
+            rule_from_name = rule.multiple_mappings? ? rule.from.first.to_s : rule.from.to_s
+            hash[rule_from_name] = value
           end
         end
 
@@ -282,39 +290,14 @@ module Lutaml
           return if value.nil? && !rule.render_nil
 
           attribute = instance.send(rule.delegate).class.attributes[name]
-          hash[rule.from.to_s] = attribute.serialize(value, format)
+          rule_from_name = rule.multiple_mappings? ? rule.from.first.to_s : rule.from.to_s
+          hash[rule_from_name] = attribute.serialize(value, format)
         end
 
         def mappings_for(format)
           mappings[format] || default_mappings(format)
         end
 
-        def attr_value(attrs, name, attr_rule)
-          value = if attrs.key?(name.to_sym)
-                    attrs[name.to_sym]
-                  elsif attrs.key?(name.to_s)
-                    attrs[name.to_s]
-                  else
-                    attr_rule.default
-                  end
-
-          if attr_rule.collection? || value.is_a?(Array)
-            (value || []).map do |v|
-              if v.is_a?(Hash)
-                attr_rule.type.new(v)
-              else
-                # TODO: This code is problematic because Type.cast does not know
-                # about all the types.
-                Lutaml::Model::Type.cast(v, attr_rule.type)
-              end
-            end
-          else
-            # TODO: This code is problematic because Type.cast does not know
-            # about all the types.
-            Lutaml::Model::Type.cast(value, attr_rule.type)
-          end
-        end
-
         def default_mappings(format)
           klass = format == :xml ? XmlMapping : KeyValueMapping
 
@@ -413,8 +396,7 @@ module Lutaml
           mappings = mappings_for(:xml).mappings
 
           if doc.is_a?(Array)
-            raise "May be `collection: true` is" \
-                  "missing for #{self} in #{options[:caller_class]}"
+            raise "May be `collection: true` is missing for #{self} in #{options[:caller_class]}"
           end
 
           if instance.respond_to?(:ordered=) && doc.is_a?(Lutaml::Model::MappingHash)
@@ -438,17 +420,18 @@ module Lutaml
 
             attr = attribute_for_rule(rule)
 
+            namespaced_names = rule.namespaced_names(options[:default_namespace])
+
             value = if rule.raw_mapping?
                       doc.node.inner_xml
                     elsif rule.content_mapping?
                       doc[rule.content_key]
-                    elsif doc.key_exist?(rule.namespaced_name(options[:default_namespace]))
-                      doc.fetch(rule.namespaced_name(options[:default_namespace]))
+                    elsif key = (namespaced_names & doc.keys).first
+                      doc[key]
                     else
                       defaults_used << rule.to
                       attr&.default || rule.to_value_for(instance)
                     end
-
             value = normalize_xml_value(value, rule, attr, options)
             rule.deserialize(instance, value, attributes, self)
           end
@@ -467,13 +450,19 @@ module Lutaml
 
             attr = attribute_for_rule(rule)
 
-            value = if doc.key?(rule.name.to_s) || doc.key?(rule.name.to_sym)
-                      doc[rule.name.to_s] || doc[rule.name.to_sym]
-                    else
-                      attr&.default
-                    end
+            names = rule.multiple_mappings? ? rule.name : [rule.name]
+
+            value = names.collect do |rule_name|
+              if doc.key?(rule_name.to_s)
+                doc[rule_name.to_s]
+              elsif doc.key?(rule_name.to_sym)
+                doc[rule_name.to_sym]
+              else
+                attr&.default
+              end
+            end.compact.first
 
-            if rule.custom_methods[:from]
+            if rule.using_custom_methods?
               if Utils.present?(value)
                 value = new.send(rule.custom_methods[:from], instance, value)
               end
@@ -567,7 +556,7 @@ module Lutaml
 
         self.class.attributes.each do |name, attr|
           value = if attrs.key?(name) || attrs.key?(name.to_s)
-                    self.class.attr_value(attrs, name, attr)
+                    attr_value(attrs, name, attr)
                   else
                     using_default_for(name)
                     attr.default
@@ -584,6 +573,32 @@ module Lutaml
         end
       end
 
+      def attr_value(attrs, name, attr_rule)
+        value = if attrs.key?(name.to_sym)
+                  attrs[name.to_sym]
+                elsif attrs.key?(name.to_s)
+                  attrs[name.to_s]
+                else
+                  attr_rule.default
+                end
+
+        if attr_rule.collection? || value.is_a?(Array)
+          (value || []).map do |v|
+            if v.is_a?(Hash)
+              attr_rule.type.new(v)
+            else
+              # TODO: This code is problematic because Type.cast does not know
+              # about all the types.
+              Lutaml::Model::Type.cast(v, attr_rule.type)
+            end
+          end
+        else
+          # TODO: This code is problematic because Type.cast does not know
+          # about all the types.
+          Lutaml::Model::Type.cast(value, attr_rule.type)
+        end
+      end
+
       def using_default_for(attribute_name)
         @using_default[attribute_name] = true
       end

data/lib/lutaml/model/type/decimal.rb

@@ -36,6 +36,11 @@ module Lutaml
             raise TypeNotEnabledError.new("Decimal", value)
           end
         end
+
+        # Override to avoid serializing ruby object in YAML
+        def to_yaml
+          value&.to_s("F")
+        end
       end
     end
   end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/lutaml/model/xml_adapter/builder/nokogiri.rb

@@ -39,6 +39,7 @@ module Lutaml
           )
             add_namespace_prefix(prefix)
 
+            element_name = element_name.first if element_name.is_a?(Array)
             element_name = "#{element_name}_" if respond_to?(element_name)
 
             if block_given?