lutaml-model 0.3.26 → 0.3.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dc709174fab4f4df2214f08b536e0b1aded39f0c9f48a18eb5a4a53da3fc4b6
-  data.tar.gz: 9eea83160b8210f84d4b2f9baf2ab577ca91d2a737eaf98b175d52385e6fb5d3
+  metadata.gz: 7fbf76c4bb8fbe07fdaed6235a5e8edcd98dc17ace1d322d0e9a36c7c4a59aef
+  data.tar.gz: f63bf29850309ab1250e2713e62fd6ef624ad5c13a824dc6e7822dec77f75369
 SHA512:
-  metadata.gz: 1e75326adeb9b8804f1bcc99104707edc3656e870d16c8af22e07e32ead9f4d78cd87eb372ebb834f2a5d942d58819e0fd3800e23a8099cf951360765223cd25
-  data.tar.gz: ecc145fb2d9250cf855243c7b9cf468919f2530eed03039bd6c7a521fa534327a1a67c5348237b3d5959e20fa0fc2b2cadc87e57139f451610cd2d7d695f251b
+  metadata.gz: 58b261437656342dc5894e25dcde477f680e72b6eebd0ae6771a5d97f0212442ae5dab446d0e182f5a4a712516b8781a0849bdcb1fa2ee1fbc831ecf9dc33695
+  data.tar.gz: 0af5c64461b6e9f5ab6d67b18ebe81e19db49123b4241b201c786b1632b567290ab55288f7047e01e3c5938316d7e93b8aca511f6f4a3f3759f1d4575fe758ae

data/README.adoc

@@ -874,6 +874,7 @@ class Example < Lutaml::Model::Serializable
 end
 ----
 
+
 === XML
 
 ==== Setting root element name
@@ -1302,6 +1303,69 @@ end
 ====
 
 
+==== Encoding Options in XmlAdapter
+
+XmlAdapter supports the encoding in the following ways:
+
+. When encoding is not passed in to_xml:
+** Default encoding is UTF-8.
+
+. When encoding is explicitly passed nil:
+** Encoding will be nil, show the HexCode(Nokogiri) or ASCII-8bit(Ox).
+
+. When encoding is passed with some option:
+** Encoding option will be selected as passed.
+
+
+Syntax:
+
+[source,ruby]
+----
+Example.new(description: " ∑ is my ∏ moniker µ.").to_xml
+Example.new(description: " ∑ is my ∏ moniker µ.").to_xml(encoding: nil)
+Example.new(description: " ∑ is my ∏ moniker µ.").to_xml(encoding: "ASCII")
+----
+
+[example]
+====
+The following class will parse the XML snippet below:
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+  attribute :value, :integer
+
+  xml do
+    root 'example'
+    map_element 'name', to: :name
+    map_content to: :description
+  end
+end
+----
+
+[source,xml]
+----
+<example><name>John &#x0026; Doe</name> &#x2211; is my &#x220F; moniker &#xB5;.</example>
+----
+
+[source,ruby]
+----
+> Example.from_xml(xml)
+> #<Example:0x0000000104ac7240 @name="John & Doe", @description=" ∑ is my ∏ moniker µ.">
+> Example.new(name: "John & Doe", description: " ∑ is my ∏ moniker µ.").to_xml
+> #<example><name>John &amp; Doe</name> ∑ is my ∏ moniker µ.</example>
+
+> Example.new(name: "John & Doe", description: " ∑ is my ∏ moniker µ.").to_xml(encoding: nil)
+> #<example><name>John &amp; Doe</name> &#x2211; is my &#x220F; moniker &#xB5;.</example>
+
+> Example.new(name: "John & Doe", description: " ∑ is my ∏ moniker µ.").to_xml(encoding: "ASCII")
+> #<example><name>John &amp; Doe</name> &#8721; is my &#8719; moniker &#181;.</example>
+----
+====
+
+
 ==== Namespaces
 
 [[root-namespace]]
@@ -1726,7 +1790,7 @@ https://www.w3.org/TR/xmlschema-1/#xsi_schemaLocation[W3C XML standard].
 Key-value data models like JSON, YAML, and TOML all share a similar structure
 where data is stored as key-value pairs.
 
-Lutaml::Model works with these formats in a similar way.
+`Lutaml::Model` works with these formats in a similar way.
 
 ==== Mapping
 
@@ -1736,12 +1800,85 @@ Syntax:
 
 [source,ruby]
 ----
-json | yaml | toml do
+json | yaml | toml | key_value do
   map 'key_value_model_attribute_name', to: :name_of_attribute
 end
 ----
 
-.Using the `map` method to define key-value mappings
+
+==== Unified mapping
+
+The `key_value` method is a streamlined way to map all attributes for
+serialization into key-value formats including JSON, YAML, and TOML.
+
+If there is no definite differentiation between the key value formats, the
+`key_value` method simplifies defining mappings and improves code readability.
+
+
+.Using the `map` method to define the same mappings across all key-value formats
+[example]
+====
+This example shows how to define a key-value data model with the `key_value`
+method which maps the same attributes across all key-value formats.
+
+[source,ruby]
+----
+class CeramicModel < Lutaml::Model::Serializable
+  attribute :color, :string
+  attribute :glaze, :string
+  attribute :description, :string
+
+  key_value do
+    map :color, to: color
+    map :glz, to: :glaze
+    map :desc, to: :description
+  end
+
+  # Equivalent to the JSON, YAML, and TOML mappings.
+  #
+  # json and yaml and toml do
+  #   map :id, to: color
+  #   map :name, to: :full_name
+  #   map :status, to: :current_status
+  # end
+end
+----
+
+[source,json]
+----
+{
+  "color": "Navy Blue",
+  "glz": "Clear",
+  "desc": "A ceramic with a navy blue color and clear glaze."
+}
+----
+
+[source,yaml]
+----
+color: Navy Blue
+glz: Clear
+desc: A ceramic with a navy blue color and clear glaze.
+----
+
+[source,ruby]
+----
+> CeramicModel.from_json(json)
+> #<CeramicModel:0x0000000104ac7240 @color="Navy Blue", @glaze="Clear", @description="A ceramic with a navy blue color and clear glaze.">
+> CeramicModel.new(color: "Navy Blue", glaze: "Clear", description: "A ceramic with a navy blue color and clear glaze.").to_json
+> #{"color"=>"Navy Blue", "glz"=>"Clear", "desc"=>"A ceramic with a navy blue color and clear glaze."}
+----
+====
+
+==== Specific format mappings
+
+Specific key value formats can be mapping independently of other formats, including:
+
+* `json` for the JSON format
+* `yaml` for the YAML format
+* `toml` for the TOML format
+
+
+.Using the `map` method to define key-value mappings per format
 [example]
 ====
 [source,ruby]

data/lib/lutaml/model/config.rb

@@ -9,6 +9,7 @@ module Lutaml
       attr_accessor :xml_adapter, :toml_adapter
 
       AVAILABLE_FORMATS = %i[xml json yaml toml].freeze
+      KEY_VALUE_FORMATS = AVAILABLE_FORMATS - %i[xml]
 
       def configure
         yield self

data/lib/lutaml/model/serialize.rb

@@ -151,6 +151,13 @@ module Lutaml
           end
         end
 
+        def key_value(&block)
+          Lutaml::Model::Config::KEY_VALUE_FORMATS.each do |format|
+            mappings[format] ||= KeyValueMapping.new
+            mappings[format].instance_eval(&block)
+          end
+        end
+
         def hash_representation(instance, format, options = {})
           only = options[:only]
           except = options[:except]

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.3.26"
+    VERSION = "0.3.28"
   end
 end

data/lib/lutaml/model/xml_adapter/nokogiri_adapter.rb

@@ -13,7 +13,15 @@ module Lutaml
         end
 
         def to_xml(options = {})
-          builder = Builder::Nokogiri.build(encoding: "UTF-8") do |xml|
+          builder_options = {}
+
+          if options.key?(:encoding)
+            builder_options[:encoding] = options[:encoding] unless options[:encoding].nil?
+          else
+            builder_options[:encoding] = "UTF-8"
+          end
+
+          builder = Builder::Nokogiri.build(builder_options) do |xml|
             if root.is_a?(Lutaml::Model::XmlAdapter::NokogiriElement)
               root.build_xml(xml)
             else
@@ -35,12 +43,11 @@ module Lutaml
 
         def prefix_xml(xml, mapping, options)
           if options.key?(:namespace_prefix)
-            options[:namespace_prefix] ? xml[options[:namespace_prefix]] : xml
+            xml[options[:namespace_prefix]] if options[:namespace_prefix]
           elsif mapping.namespace_prefix
             xml[mapping.namespace_prefix]
-          else
-            xml
           end
+          xml
         end
 
         def build_ordered_element(xml, element, options = {})

data/lib/lutaml/model/xml_adapter/ox_adapter.rb

@@ -14,8 +14,15 @@ module Lutaml
 
         def to_xml(options = {})
           builder = Builder::Ox.build
-          builder.xml.instruct(:xml, encoding: options[:encoding] || "UTF-8", version: options[:version])
+          builder_options = { version: options[:version] }
 
+          if options.key?(:encoding)
+            builder_options[:encoding] = options[:encoding] unless options[:encoding].nil?
+          else
+            builder_options[:encoding] = "UTF-8"
+          end
+
+          builder.xml.instruct(:xml, builder_options)
           if @root.is_a?(Lutaml::Model::XmlAdapter::OxElement)
             @root.build_xml(builder)
           elsif ordered?(@root, options)

data/lib/lutaml/model/xml_adapter/xml_document.rb

@@ -66,7 +66,7 @@ module Lutaml
           options[:tag_name] = rule.name
 
           options[:mapper_class] = attribute&.type if attribute
-          options[:namespace_set] = set_namespace?(rule)
+          options[:set_namespace] = set_namespace?(rule)
 
           options
         end
@@ -185,6 +185,7 @@ module Lutaml
           attributes = options[:xml_attributes] ||= {}
           attributes = build_attributes(element,
                                         xml_mapping, options).merge(attributes)&.compact
+
           if element.respond_to?(:schema_location) && element.schema_location
             attributes.merge!(element.schema_location.to_xml_attributes)
           end
@@ -275,7 +276,7 @@ module Lutaml
         end
 
         def set_namespace?(rule)
-          rule.nil? || !rule.namespace_set? || !rule.namespace.nil?
+          rule.nil? || !rule.namespace_set?
         end
 
         def render_element?(rule, element, value)
@@ -336,7 +337,7 @@ module Lutaml
         end
 
         def build_attributes(element, xml_mapping, options = {})
-          attrs = if options.fetch(:namespace_set, true)
+          attrs = if options.fetch(:set_namespace, true)
                     namespace_attributes(xml_mapping)
                   else
                     {}

data/spec/lutaml/model/delegation_spec.rb

@@ -148,11 +148,11 @@ RSpec.describe Delegation do
   end
 
   it "provides XML declaration with UTF-8 encoding" \
-     "if encoding: true option provided" do
+     "if encoding: 'UTF-8' option provided" do
     xml_data = delegation.to_xml(
       pretty: true,
       declaration: true,
-      encoding: true,
+      encoding: "UTF-8",
     )
     expect(xml_data).to include('<?xml version="1.0" encoding="UTF-8"?>')
   end

data/spec/lutaml/model/mixed_content_spec.rb

@@ -170,6 +170,15 @@ module MixedContentSpec
       map_element :value, to: :value
     end
   end
+
+  class HexCode < Lutaml::Model::Serializable
+    attribute :content, :string
+
+    xml do
+      root "HexCode"
+      map_content to: :content
+    end
+  end
 end
 
 RSpec.describe "MixedContent" do
@@ -449,7 +458,7 @@ RSpec.describe "MixedContent" do
 
         it "serializes special char mixed content correctly" do
           parsed = MixedContentSpec::SpecialCharContentWithMixedTrue.from_xml(xml)
-          serialized = parsed.to_xml
+          serialized = parsed.to_xml(encoding: "UTF-8")
 
           expect(serialized).to include(expected_xml)
         end
@@ -608,10 +617,68 @@ RSpec.describe "MixedContent" do
         end
       end
     end
+
+    context "when special char used as full entities, it persist as entities if no encoding provided" do
+      let(:xml) do
+        <<~XML
+          <HexCode>
+            &#x2211;computer security&#x220F; type of &#x200B; operation specified &#xB5; by an access right
+          </HexCode>
+        XML
+      end
+
+      describe ".from_xml" do
+        let(:expected_content) { "∑computer security∏ type of ​ operation specified µ by an access right" }
+
+        it "deserializes special char mixed content correctly" do
+          parsed = MixedContentSpec::HexCode.from_xml(xml)
+
+          expect(parsed.content.strip).to eq(expected_content)
+        end
+      end
+
+      describe ".to_xml" do
+        context "when default encoding xml" do
+          let(:expected_default_encoding_xml) { "∑computer security∏ type of ​ operation specified µ by an access right" }
+
+          it "serializes special char mixed content correctly with default encoding: UTF-8" do
+            parsed = MixedContentSpec::HexCode.from_xml(xml)
+            serialized = parsed.to_xml
+
+            expect(serialized.strip).to include(expected_default_encoding_xml)
+          end
+        end
+
+        context "when encoding: nil xml" do
+          let(:expected_encoding_nil_nokogiri_xml) { "&#x2211;computer security&#x220F; type of &#x200B; operation specified &#xB5; by an access right" }
+          let(:expected_encoding_nil_ox_xml) { "\xE2\x88\x91computer security\xE2\x88\x8F type of \xE2\x80\x8B operation specified \xC2\xB5 by an access right" }
+
+          it "serializes special char mixed content correctly with encoding: nil to get hexcode" do
+            parsed = MixedContentSpec::HexCode.from_xml(xml)
+            serialized = parsed.to_xml(encoding: nil)
+
+            if adapter_class == Lutaml::Model::XmlAdapter::OxAdapter
+              expected_output = expected_encoding_nil_ox_xml
+              expected_output.force_encoding("ASCII-8BIT")
+            else
+              expected_output = expected_encoding_nil_nokogiri_xml
+            end
+
+            expect(serialized.strip).to include(expected_output)
+          end
+        end
+      end
+    end
   end
 
   describe Lutaml::Model::XmlAdapter::NokogiriAdapter do
     it_behaves_like "mixed content behavior", described_class
+
+    it "raises error when serializes special char content with false encoding: 'ABC'" do
+      parsed = MixedContentSpec::HexCode.from_xml("<HexCode>&#x2211;computer security</HexCode>")
+
+      expect { parsed.to_xml(encoding: "ABC") }.to raise_error(StandardError, "unknown encoding name - ABC")
+    end
   end
 
   describe Lutaml::Model::XmlAdapter::OxAdapter do

data/spec/lutaml/model/serializable_spec.rb

@@ -25,6 +25,18 @@ module SerializeableSpec
     end
   end
 
+  class KeyValueMapper < Lutaml::Model::Serializable
+    attribute :first_name, :string
+    attribute :last_name, :string
+    attribute :age, :integer
+
+    key_value do
+      map :first_name, to: :first_name
+      map :last_name, to: :last_name
+      map :age, to: :age
+    end
+  end
+
   ### XML root mapping
 
   class RecordDate < Lutaml::Model::Serializable
@@ -207,6 +219,22 @@ RSpec.describe Lutaml::Model::Serializable do
     end
   end
 
+  describe "#key_value" do
+    let(:model) { SerializeableSpec::KeyValueMapper }
+
+    Lutaml::Model::Config::KEY_VALUE_FORMATS.each do |format|
+      it "defines 3 mappings for #{format}" do
+        expect(model.mappings_for(format).mappings.count).to eq(3)
+      end
+
+      it "defines mappings correctly for #{format}" do
+        defined_mappings = model.mappings_for(format).mappings.map(&:name)
+
+        expect(defined_mappings).to eq(%i[first_name last_name age])
+      end
+    end
+  end
+
   describe "XML root name override" do
     it "uses root name defined at the component class" do
       record_date = SerializeableSpec::RecordDate.new(content: "2021-01-01")

data/spec/lutaml/model/xml_mapping_spec.rb

@@ -127,6 +127,17 @@ module XmlMapping
     end
   end
 
+  class OverrideDefaultNamespacePrefix < Lutaml::Model::Serializable
+    attribute :same_element_name, SameNameDifferentNamespace
+
+    xml do
+      root "OverrideDefaultNamespacePrefix"
+      map_element :SameElementName, to: :same_element_name,
+                                    namespace: "http://www.omg.org/spec/XMI/20131001",
+                                    prefix: "abc"
+    end
+  end
+
   class SchemaLocationOrdered < Lutaml::Model::Serializable
     attribute :content, :string
     attribute :second, SchemaLocationOrdered
@@ -220,6 +231,30 @@ module XmlMapping
                                       prefix: nil
     end
   end
+
+  class Documentation < Lutaml::Model::Serializable
+    attribute :content, :string
+
+    xml do
+      root "documentation", mixed: true
+      namespace "http://www.w3.org/2001/XMLSchema", "xsd"
+
+      map_content to: :content
+    end
+  end
+
+  class Schema < Lutaml::Model::Serializable
+    attribute :documentation, Documentation, collection: true
+
+    xml do
+      root "schema"
+      namespace "http://www.w3.org/2001/XMLSchema", "xsd"
+
+      map_element :documentation, to: :documentation,
+                                  namespace: "http://www.w3.org/2001/XMLSchema",
+                                  prefix: "xsd"
+    end
+  end
 end
 
 RSpec.describe Lutaml::Model::XmlMapping do
@@ -245,6 +280,25 @@ RSpec.describe Lutaml::Model::XmlMapping do
     end
   end
 
+  context "overriding child namespace prefix" do
+    let(:input_xml) do
+      <<~XML
+        <OverrideDefaultNamespacePrefix xmlns:abc="http://www.omg.org/spec/XMI/20131001" xmlns:GML="http://www.sparxsystems.com/profiles/GML/1.0" xmlns:CityGML="http://www.sparxsystems.com/profiles/CityGML/1.0">
+          <abc:SameElementName App="hello">
+            <GML:ApplicationSchema>GML App</GML:ApplicationSchema>
+            <CityGML:ApplicationSchema>CityGML App</CityGML:ApplicationSchema>
+            <abc:ApplicationSchema>App</abc:ApplicationSchema>
+          </abc:SameElementName>
+        </OverrideDefaultNamespacePrefix>
+      XML
+    end
+
+    it "expect to round-trips" do
+      parsed = XmlMapping::OverrideDefaultNamespacePrefix.from_xml(input_xml)
+      expect(parsed.to_xml).to be_equivalent_to(input_xml)
+    end
+  end
+
   context "with same name elements" do
     let(:input_xml) do
       <<~XML
@@ -859,5 +913,19 @@ RSpec.describe Lutaml::Model::XmlMapping do
         expect(XmlMapping::SpecialCharContentWithMapAll.from_xml(xml).to_xml).to eq(expected_xml)
       end
     end
+
+    context "when mixed content is true and child is content_mapping" do
+      let(:xml) do
+        <<~XML
+          <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+            <xsd:documentation>asdf</xsd:documentation>
+          </xsd:schema>
+        XML
+      end
+
+      it "round-trips xml" do
+        expect(XmlMapping::Schema.from_xml(xml).to_xml).to be_equivalent_to(xml)
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.3.26
+  version: 0.3.28
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-11-12 00:00:00.000000000 Z
+date: 2024-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor