lutaml-model 0.3.10 → 0.3.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5140f93f22f4b05222edc408aeca50552082e447b71fddd724b34ba9e6b82d55
-  data.tar.gz: 0aa44a3c72b65cca0ed2b7411614d8cdb0c44b4e8293e183935cb45ba7818d7c
+  metadata.gz: 5b36d07a850d4736c0634735a198f05dd34c49b906cd1265b3dd49266931eb22
+  data.tar.gz: cefd0559ad4010ecd2ab0a547ab87493b4958a480f6cb19ab317c248836b8f75
 SHA512:
-  metadata.gz: 69e4d0d0a3a5bd19e11a43fd33e03566ca035d18cf948a0a2fc5abe5f880489e4a6ad347d8118a04c35c8c95be5b7eb29ca93d426643c7790ab045db2b34721c
-  data.tar.gz: df1699ba6647f53f97735d0986b92bf8f76d6bf44430117406100b257f5934ac4a7baa6a4243bb8384db277ecb975bf64efe2f1a16b293739b245150e800cb15
+  metadata.gz: 83fac7632d0eec4f5bd4339132b36d267877932cf34839eac6dbdefd0cd0e551988b73b3cd379b856af0df351e42694c157342efd8baba67e283e71d34b88171
+  data.tar.gz: 6befe6bfce13fb6175a04f8e0ac81794304d3c56c51feea343334c501346cba517db1f89ab3387ea3300e546d160d24af264048e9762c85debc4063300d57025

data/.rubocop_todo.yml

@@ -1,25 +1,18 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-09-10 23:53:08 UTC using RuboCop version 1.66.1.
+# on 2024-10-23 12:15:48 UTC using RuboCop version 1.66.1.
 # 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: 88
+# Offense count: 139
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/lutaml/model/schema_location.rb'
-
 # Offense count: 11
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -37,12 +30,13 @@ Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
 
-# Offense count: 31
+# Offense count: 37
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
     - 'lib/lutaml/model/comparable_model.rb'
+    - 'lib/lutaml/model/mapping_rule.rb'
     - 'lib/lutaml/model/schema/relaxng_schema.rb'
     - 'lib/lutaml/model/schema/xsd_schema.rb'
     - 'lib/lutaml/model/serialize.rb'
@@ -50,14 +44,15 @@ Metrics/AbcSize:
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
+    - 'lib/lutaml/model/xml_mapping_rule.rb'
 
 # Offense count: 6
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 42
+  Max: 47
 
-# Offense count: 25
+# Offense count: 27
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
@@ -69,17 +64,17 @@ Metrics/CyclomaticComplexity:
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
 
-# Offense count: 39
+# Offense count: 50
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 49
+  Max: 51
 
 # Offense count: 4
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 9
+  Max: 12
 
-# Offense count: 21
+# Offense count: 22
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
@@ -90,7 +85,7 @@ Metrics/PerceivedComplexity:
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
 
-# Offense count: 7
+# Offense count: 8
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
@@ -99,11 +94,12 @@ RSpec/ContextWording:
     - 'spec/lutaml/model/xml_adapter/oga_adapter_spec.rb'
     - 'spec/lutaml/model/xml_adapter/ox_adapter_spec.rb'
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
+    - 'spec/lutaml/model/xml_mapping_spec.rb'
 
-# Offense count: 101
+# Offense count: 109
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 57
+  Max: 54
 
 # Offense count: 2
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
@@ -129,11 +125,11 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
     - 'spec/lutaml/model/xml_adapter_spec.rb'
 
-# Offense count: 88
+# Offense count: 119
 RSpec/MultipleExpectations:
-  Max: 11
+  Max: 14
 
-# Offense count: 17
+# Offense count: 18
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 9
@@ -147,18 +143,24 @@ RSpec/PendingWithoutReason:
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
     - 'spec/lutaml/model/xml_adapter_spec.rb'
 
+# Offense count: 1
+RSpec/RemoveConst:
+  Exclude:
+    - 'spec/lutaml/model/type/decimal_spec.rb'
+
 # Offense count: 2
 RSpec/RepeatedExampleGroupDescription:
   Exclude:
     - 'spec/lutaml/model/collection_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: Include, CustomTransform, IgnoreMethods, IgnoreMetadata.
 # Include: **/*_spec.rb
 RSpec/SpecFilePathFormat:
   Exclude:
     - '**/spec/routing/**/*'
     - 'spec/lutaml/model/collection_spec.rb'
+    - 'spec/lutaml/model/type/decimal_spec.rb'
 
 # Offense count: 1
 Security/CompoundHash:

data/Gemfile

@@ -5,6 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in lutaml-model.gemspec
 gemspec
 
+gem "bigdecimal"
 gem "equivalent-xml"
 gem "multi_json"
 gem "nokogiri"

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2024, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -145,6 +145,8 @@ same class and all their attributes are equal.
 
 === Supported attribute value types
 
+==== General types
+
 Lutaml::Model supports the following attribute types, they can be
 referred by a string, a symbol, or their class constant.
 
@@ -166,12 +168,11 @@ attribute :name_of_attribute, {symbol | string | class}
 | `DateTime` | `:date_time` | `Lutaml::Model::Type::DateTime` | `::DateTime`
 | `TimeWithoutDate` | `:time_without_date` | `Lutaml::Model::Type::TimeWithoutDate` | `::Time`
 | `Boolean` | `:boolean` | `Lutaml::Model::Type::Boolean` | `Boolean`
-| `Decimal` | `:decimal` | `Lutaml::Model::Type::Decimal` | `::BigDecimal`
+| `Decimal` (optional) | `:decimal` | `Lutaml::Model::Type::Decimal` | `::BigDecimal`
 | `Hash` | `:hash` | `Lutaml::Model::Type::Hash` | `::Hash`
 
 |===
 
-
 .Defining attributes with supported types via symbol, string and class
 [example]
 ====
@@ -198,6 +199,23 @@ end
 ----
 ====
 
+==== (optional) Decimal type
+
+The `BigDecimal` class is no longer part of the standard Ruby library from Ruby
+3.4 onwards, hence the `Decimal` type is only enabled when the `bigdecimal`
+library is loaded.
+
+This means that the following code needs to be run before using (and parsing)
+the `Decimal` type:
+
+[source,ruby]
+----
+require 'bigdecimal'
+----
+
+If the `bigdecimal` library is not loaded, usage of the `Decimal` type will
+raise a `Lutaml::Model::TypeNotSupportedError`.
+
 
 === Attribute as a collection
 
@@ -405,6 +423,51 @@ end
 ----
 ====
 
+=== Attribute as raw string
+
+An attribute can be set to read the value as raw string for XML, by using the `raw: true` option.
+
+Syntax:
+
+[source,ruby]
+----
+attribute :name_of_attribute, :string, raw: true
+----
+
+.Using the `raw` option to read raw value for an XML attribute
+[example]
+====
+[source,ruby]
+----
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string, raw: true
+end
+----
+
+For the following xml
+[source,xml]
+----
+<Person>
+  <name>John Doe</name>
+  <description>
+    A <b>fictional person</b> commonly used as a <i>placeholder name</i>.
+  </description>
+</Person>
+----
+
+[source,ruby]
+----
+> Person.from_xml(xml)
+> # <Person:0x0000000107a3ca70
+    @description="\n    A <b>fictional person</b> commonly used as a <i>placeholder name</i>.\n  ",
+    @element_order=["text", "name", "text", "description", "text"],
+    @name="John Doe",
+    @ordered=nil,
+    @validate_on_set=false>
+----
+====
+
 == Serialization model mappings
 
 === General
@@ -594,7 +657,7 @@ end
 
 [source,xml]
 ----
-<example value=12><name>John Doe</name></example>
+<example value="12"><name>John Doe</name></example>
 ----
 
 [source,ruby]
@@ -604,6 +667,37 @@ end
 > Example.new(value: 12).to_xml
 > #<example value="12"></example>
 ----
+
+The map_attribute method does not inherit the root element's namespace. If you need to specify a namespace for an attribute,
+you must explicitly declare the namespace and prefix in the map_attribute method.
+[example]
+====
+The following class will parse the XML snippet below:
+
+[source,ruby]
+----
+class Attribute < Lutaml::Model::Serializable
+  attribute :value, :integer
+
+  xml do
+    root 'example'
+    map_attribute 'value', to: :value, namespace: "http://www.tech.co/XMI", prefix: "xl"
+  end
+end
+----
+
+[source,xml]
+----
+<example xl:value="20" xmlns:xl="http://www.tech.co/XMI"></example>
+----
+
+[source,ruby]
+----
+> Attribute.from_xml(xml)
+> #<Attribute:0x0000000109436db8 @value=20>
+> Attribute.new(value: 20).to_xml
+> #<example xmlns:xl=\"http://www.tech.co/XMI\" xl:value=\"20\"/>
+----
 ====
 
 
@@ -680,7 +774,7 @@ end
 
 [source,xml]
 ----
-<example value=12><name>John Doe</name> is my moniker.</example>
+<example value="12"><name>John Doe</name> is my moniker.</example>
 ----
 
 [source,ruby]
@@ -989,7 +1083,7 @@ end
 
 TODO: How to create mixed content from `#new`?
 
-
+[[xml-schema-location]]
 ==== Automatic support of `xsi:schemaLocation`
 
 The
@@ -1444,9 +1538,14 @@ NOTE: The corresponding keyword used by Shale is `receiver:` instead of
 
 ==== Attribute serialization with custom methods
 
+===== General
+
 Define custom methods for specific attribute mappings using the `with:` key for
 each serialization mapping block for `from` and `to`.
 
+
+===== XML serialization with custom methods
+
 Syntax:
 
 .XML serialization with custom methods
@@ -1468,6 +1567,81 @@ xml do
 end
 ----
 
+.Using the `with:` key to define custom serialization methods for XML
+[example]
+====
+The following class will parse the XML snippet below:
+
+[source,ruby]
+----
+class CustomCeramic < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :size, :integer
+  attribute :description, :string
+
+  xml do
+    map_element "Name", to: :name, with: { to: :name_to_xml, from: :name_from_xml }
+    map_attribute "Size", to: :size, with: { to: :size_to_xml, from: :size_from_xml }
+    map_content with: { to: :description_to_xml, from: :description_from_xml }
+  end
+
+  def name_to_xml(model, parent, doc)
+    el = doc.create_element("Name")
+    doc.add_text(el, "XML Masterpiece: #{model.name}")
+    doc.add_element(parent, el)
+  end
+
+  def name_from_xml(model, value)
+    model.name = value.sub(/^XML Masterpiece: /, "")
+  end
+
+  def size_to_xml(model, parent, doc)
+    doc.add_attribute(parent, "Size", model.size + 3)
+  end
+
+  def size_from_xml(model, value)
+    model.size = value.to_i - 3
+  end
+
+  def description_to_xml(model, parent, doc)
+    doc.add_text(parent, "XML Description: #{model.description}")
+  end
+
+  def description_from_xml(model, value)
+    model.description = value.join.strip.sub(/^XML Description: /, "")
+  end
+end
+----
+
+[source,xml]
+----
+<CustomCeramic Size="15">
+  <Name>XML Masterpiece: Vase</Name>
+  XML Description: A beautiful ceramic vase
+</CustomCeramic>
+----
+
+[source,ruby]
+----
+> CustomCeramic.from_xml(xml)
+> #<CustomCeramic:0x0000000108d0e1f8
+   @element_order=["text", "Name", "text", "Size", "text"],
+   @name="Masterpiece: Vase",
+   @ordered=nil,
+   @size=12,
+   @description="A beautiful ceramic vase",
+   @validate_on_set=false>
+> puts CustomCeramic.new(name: "Vase", size: 12, description: "A beautiful vase").to_xml
+# <CustomCeramic Size="15">
+#   <Name>XML Masterpiece: Vase</Name>
+#   XML Description: A beautiful vase
+# </CustomCeramic>
+----
+====
+
+
+===== Key-value data model serialization with custom methods
+
 .Key-value data model serialization with custom methods
 [source,ruby]
 ----
@@ -1524,7 +1698,7 @@ end
 
 
 [[attribute-extraction]]
-==== Attribute extraction
+==== Attribute extraction (for key-value data models only)
 
 NOTE: This feature is for key-value data model serialization only.
 
@@ -1992,9 +2166,9 @@ differences in implementation.
 |
 
 | Value types
-| `Lutaml::Model::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `DateTime`, `Time`, `Hash`.
+| `Lutaml::Model::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `DateTime`, `Time`, `Decimal`, `Hash`.
 | `Shale::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `Time`.
-| Lutaml::Model supports the additional value types `DateTime` and `Hash`.
+| Lutaml::Model supports additional value types `Decimal`, `DateTime` and `Hash`.
 
 | Configuration
 | `Lutaml::Model::Config`
@@ -2011,6 +2185,11 @@ differences in implementation.
 | XML, YAML, JSON, TOML, CSV
 | Lutaml::Model does not support CSV.
 
+| Validation
+| Supports collection range, fixed values, and custom validation
+| Requires implementation
+|
+
 | Adapter support
 | XML (Nokogiri, Ox, Oga), YAML, JSON (JSON, MultiJson), TOML (Toml-rb, Tomlib)
 | XML (Nokogiri, Ox), YAML, JSON (JSON, MultiJson), TOML (Toml-rb, Tomlib), CSV
@@ -2042,6 +2221,12 @@ namespace from the root element.
 | No.
 |
 
+| Support for `xsi:schemaLocation`
+| Yes. Automatically supports the <<xml-schema-location,`xsi:schemaLocation`>>
+attribute for every element.
+| Requires manual specification on every XML element that uses it.
+|
+
 4+h| Attribute features
 
 | Attribute delegation
@@ -2061,7 +2246,6 @@ data models.
 | No.
 | Lutaml::Model supports attribute extraction from key-value data models.
 
-
 |===
 
 
@@ -2114,25 +2298,26 @@ Actions:
 
 === Step 2: Replace value type definitions
 
-Value types in `Lutaml::Model` are under the `Lutaml::Model::Type` module.
+Value types in `Lutaml::Model` are under the `Lutaml::Model::Type` module,
+or use the LutaML type symbols.
 
 [source,ruby]
 ----
 class Example < Lutaml::Model::Serializable
-  attribute :length, Lutaml::Model::Type::Integer
-  attribute :description, Lutaml::Model::Type::String
+  attribute :length, :integer
+  attribute :description, :string
 end
 ----
 
 [NOTE]
 ====
-`Lutaml::Model` also supports specifying predefined value types as strings or
+`Lutaml::Model` supports specifying predefined value types as strings or
 symbols, which is not supported by Shale.
 
 [source,ruby]
 ----
 class Example < Lutaml::Model::Serializable
-  attribute :length, :integer
+  attribute :length, Lutaml::Model::Type::Integer
   attribute :description, "String"
 end
 ----
@@ -2369,6 +2554,6 @@ allowing you to shape and structure your data into useful forms.
 == License and Copyright
 
 This project is licensed under the BSD 2-clause License.
-See the LICENSE file for details.
+See the link:LICENSE.md[] file for details.
 
 Copyright Ribose.

data/lib/lutaml/model/attribute.rb

@@ -7,6 +7,7 @@ module Lutaml
         @name = name
         @type = cast_type(type)
         @options = options
+        @raw = !!options[:raw]
 
         if collection?
           validate_collection_range
@@ -14,6 +15,10 @@ module Lutaml
         end
       end
 
+      def delegate
+        @options[:delegate]
+      end
+
       def cast_type(type)
         case type
         when Class
@@ -27,6 +32,16 @@ module Lutaml
         raise ArgumentError, "Unknown Lutaml::Model::Type: #{type}"
       end
 
+      def cast_value(value)
+        return type.cast(value) unless value.is_a?(Array)
+
+        value.map { |v| type.cast(v) }
+      end
+
+      def setter
+        :"#{@name}="
+      end
+
       def collection?
         options[:collection] || false
       end
@@ -35,10 +50,20 @@ module Lutaml
         !collection?
       end
 
-      def default
-        return options[:default].call if options[:default].is_a?(Proc)
+      def raw?
+        @raw
+      end
 
-        options[:default]
+      def default
+        value = if delegate
+                  type.attributes[to].default
+                elsif options[:default].is_a?(Proc)
+                  options[:default].call
+                else
+                  options[:default]
+                end
+
+        cast_value(value)
       end
 
       def render_nil?

data/lib/lutaml/model/error/incorrect_mapping_argument_error.rb

@@ -0,0 +1,6 @@
+module Lutaml
+  module Model
+    class IncorrectMappingArgumentsError < Error
+    end
+  end
+end

data/lib/lutaml/model/error/type_not_enabled_error.rb

@@ -0,0 +1,9 @@
+module Lutaml
+  module Model
+    class TypeNotEnabledError < Error
+      def initialize(type_name, value)
+        super("#{type_name} type is not enabled. Value: #{value}")
+      end
+    end
+  end
+end

data/lib/lutaml/model/error.rb

@@ -6,6 +6,8 @@ module Lutaml
 end
 
 require_relative "error/invalid_value_error"
+require_relative "error/incorrect_mapping_argument_error"
 require_relative "error/unknown_adapter_type_error"
 require_relative "error/collection_count_out_of_range_error"
 require_relative "error/validation_error"
+require_relative "error/type_not_enabled_error"

data/lib/lutaml/model/json_adapter/standard_json_adapter.rb

@@ -6,8 +6,7 @@ module Lutaml
     module JsonAdapter
       class StandardJsonAdapter < JsonDocument
         def self.parse(json)
-          attributes = JSON.parse(json, create_additions: false)
-          new(attributes)
+          JSON.parse(json, create_additions: false)
         end
 
         def to_json(*args)

data/lib/lutaml/model/key_value_mapping.rb

@@ -11,12 +11,14 @@ module Lutaml
 
       def map(
         name,
-        to:,
+        to: nil,
         render_nil: false,
         with: {},
         delegate: nil,
         child_mappings: nil
       )
+        validate!(name, to, with)
+
         @mappings << KeyValueMappingRule.new(
           name,
           to: to,
@@ -28,6 +30,28 @@ module Lutaml
       end
 
       alias map_element map
+
+      def validate!(key, to, with)
+        if to.nil? && with.empty?
+          msg = ":to or :with argument is required for mapping '#{key}'"
+          raise IncorrectMappingArgumentsError.new(msg)
+        end
+
+        if !with.empty? && (with[:from].nil? || with[:to].nil?)
+          msg = ":with argument for mapping '#{key}' requires :to and :from keys"
+          raise IncorrectMappingArgumentsError.new(msg)
+        end
+      end
+
+      def deep_dup
+        self.class.new.tap do |new_mapping|
+          new_mapping.instance_variable_set(:@mappings, duplicate_mappings)
+        end
+      end
+
+      def duplicate_mappings
+        @mappings.map(&:deep_dup)
+      end
     end
   end
 end