lutaml-model 0.3.25 → 0.3.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 923c122ff4459f02c1949dc88ee8df94b93db6ce23c00c9da2159f6b376da3a0
-  data.tar.gz: aa537363d67a5383cdbd280cfa9ddee0a3c5de0cb151b79b2e195a030bc0061d
+  metadata.gz: e00c3fab326d719d8341687a8411797d60ccaf54820380ba7a2dacead6a89792
+  data.tar.gz: e46c1dd3d50f6b2bea7da738d94ace488655205deb049170057490f6d1526bf8
 SHA512:
-  metadata.gz: a0da4f4a87c8fe4a3951d302df5797594675f83616ea52b4582f417683d4f55076c57ad3d6f3018119c0a6021497bf6832b150ebf695d1fa8d4304da2040b641
-  data.tar.gz: 0d4d6d783728b53d453c23e2cfcfcd08d9eac83d94b4652d3bdee95c19d9d9bf68e233dea6d29d9478d4214271dd800be93b8f8e11a59cf9f9cd46d744dd2002
+  metadata.gz: ab260d59203839c5fd9b1aa670501c1953c741fe75f0f7ab7261795c54cd19ed6de9807f9b8252c83ce9eee8cf2e6a9116087066e464ca1f35b8b46e29082351
+  data.tar.gz: c579a87612ce8e249edcca0c79f0ee2550d40af899e31ee2405ffdd48509e584df449c19bb3489a6871cdf4dfc08c4bc51f482422ea9a7d91f02d706d653cac6

data/.rubocop_todo.yml

@@ -73,7 +73,7 @@ Metrics/MethodLength:
 # Offense count: 7
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 13
+  Max: 14
 
 # Offense count: 23
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.

data/README.adoc

@@ -543,8 +543,15 @@ end
 ====
 
 
+=== Attribute value validation
+
+==== General
+
+There are several mechanisms to validate attribute values in Lutaml::Model.
+
+
 [[attribute-enumeration]]
-=== Attribute as an enumeration
+==== Values of an enumeration
 
 An attribute can be defined as an enumeration by using the `values` directive.
 
@@ -641,6 +648,44 @@ acceptance of the newly updated component.
 ====
 
 
+==== String values restricted to patterns
+
+An attribute that accepts a string value accepts value validation using regular
+expressions.
+
+Syntax:
+
+[source,ruby]
+----
+attribute :name_of_attribute, :string, pattern: /regex/
+----
+
+.Using the `pattern` option to restrict the value of an attribute
+[example]
+====
+In this example, the `color` attribute takes hex color values such as `#ccddee`.
+
+A regular expression can be used to validate values assigned to the attribute.
+In this case, it is `/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/`.
+
+[source,ruby]
+----
+class Glaze < Lutaml::Model::Serializable
+  attribute :color, :string, pattern: /\A#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})\z/
+end
+----
+
+[source,ruby]
+----
+> Glaze.new(color: '#ff0000').color
+> # "#ff0000"
+> Glaze.new(color: '#ff000').color
+> # Lutaml::Model::InvalidValueError: Invalid value for attribute 'color'
+----
+====
+
+
+
 === Attribute value default and rendering defaults
 
 Specify default values for attributes using the `default` option.
@@ -771,7 +816,8 @@ class Person < Lutaml::Model::Serializable
 end
 ----
 
-For the following xml
+For the following XML snippet:
+
 [source,xml]
 ----
 <Person>
@@ -1144,6 +1190,80 @@ end
 ====
 
 
+==== CDATA nodes
+
+CDATA is an XML feature that allows the inclusion of text that may contain
+characters that are unescaped in XML.
+
+While CDATA is not preferred in XML, it is sometimes necessary to handle CDATA
+nodes for both input and output.
+
+NOTE: The W3C XML Recommendation explicitly encourages escaping characters over
+usage of CDATA.
+
+Lutaml::Model supports the handling of CDATA nodes in XML in the following
+behavior:
+
+. When an attribute contains a CDATA node with no text:
+** On reading: The node (CDATA or text) is read as its value.
+** On writing: The value is written as its native type.
+
+. When an XML mapping sets `cdata: true` on `map_element` or `map_content`:
+** On reading: The node (CDATA or text) is read as its value.
+** On writing: The value is written as a CDATA node.
+
+. When an XML mapping sets `cdata: false` on `map_element` or `map_content`:
+** On reading: The node (CDATA or text) is read as its value.
+** On writing: The value is written as a text node (string).
+
+
+Syntax:
+
+[source,ruby]
+----
+xml do
+  map_content to: :name_of_attribute, cdata: (true | false)
+  map_element :name, to: :name, cdata: (true | false)
+end
+----
+
+.Using `cdata` to map CDATA content
+[example]
+====
+The following class will parse the XML snippet below:
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+  attribute :title, :string
+  attribute :note, :string
+
+  xml do
+    root 'example'
+    map_element :name, to: :name, cdata: true
+    map_content to: :description, cdata: true
+    map_element :title, to: :title, cdata: false
+    map_element :note, to: :note, cdata: false
+  end
+end
+----
+
+[source,xml]
+----
+<example><name><![CDATA[John]]></name><![CDATA[here is the description]]><title><![CDATA[Lutaml]]></title><note>Careful</note></example>
+----
+
+[source,ruby]
+----
+> Example.from_xml(xml)
+> #<Example:0x0000000104ac7240 @name="John" @description="here is the description" @title="Lutaml" @note="Careful">
+> Example.new(name: "John", description: "here is the description", title: "Lutaml", note: "Careful").to_xml
+> #<example><name><![CDATA[John]]></name><![CDATA[here is the description]]><title>Lutaml</title><note>Careful</note></example>
+----
+====
+
 
 ==== Example for mapping
 
@@ -1182,6 +1302,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]]

data/lib/lutaml/model/attribute.rb

@@ -9,6 +9,7 @@ module Lutaml
         delegate
         collection
         values
+        pattern
       ].freeze
 
       def initialize(name, type, options = {})
@@ -87,23 +88,12 @@ module Lutaml
         cast_value(value)
       end
 
-      def enum_values
-        @options.key?(:values) ? @options[:values] : []
+      def pattern
+        options[:pattern]
       end
 
-      # Check if the value to be assigned is valid for the attribute
-      #
-      # Currently there are 2 validations
-      #   1. Value should be from the values list if they are defined
-      #      e.g values: ["foo", "bar"] is set then any other value for this
-      #          attribute will raise `Lutaml::Model::InvalidValueError`
-      #
-      #   2. Value count should be between the collection range if defined
-      #      e.g if collection: 0..5 is set then the value greater then 5
-      #          will raise `Lutaml::Model::CollectionCountOutOfRangeError`
-      def validate_value!(value)
-        valid_value!(value)
-        valid_collection!(value)
+      def enum_values
+        @options.key?(:values) ? @options[:values] : []
       end
 
       def valid_value!(value)
@@ -123,14 +113,32 @@ module Lutaml
         options[:values].include?(value)
       end
 
-      def validate_value!(value)
-        # return true if none of the validations are present
-        return true if enum_values.empty? && singular?
+      def valid_pattern!(value)
+        return true unless type == Lutaml::Model::Type::String
+        return true unless pattern
+
+        unless pattern.match?(value)
+          raise Lutaml::Model::PatternNotMatchedError.new(name, pattern, value)
+        end
 
+        true
+      end
+
+      # Check if the value to be assigned is valid for the attribute
+      #
+      # Currently there are 2 validations
+      #   1. Value should be from the values list if they are defined
+      #      e.g values: ["foo", "bar"] is set then any other value for this
+      #          attribute will raise `Lutaml::Model::InvalidValueError`
+      #
+      #   2. Value count should be between the collection range if defined
+      #      e.g if collection: 0..5 is set then the value greater then 5
+      #          will raise `Lutaml::Model::CollectionCountOutOfRangeError`
+      def validate_value!(value)
         # Use the default value if the value is nil
         value = default if value.nil?
 
-        valid_value!(value) && valid_collection!(value)
+        valid_value!(value) && valid_collection!(value) && valid_pattern!(value)
       end
 
       def validate_collection_range
@@ -229,6 +237,13 @@ module Lutaml
           raise StandardError,
                 "Invalid options given for `#{name}` #{invalid_opts}"
         end
+
+        if options.key?(:pattern) && type != Lutaml::Model::Type::String
+          raise StandardError,
+                "Invalid option `pattern` given for `#{name}`, `pattern` is only allowed for :string type"
+        end
+
+        true
       end
 
       def validate_type!(type)

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

@@ -0,0 +1,17 @@
+module Lutaml
+  module Model
+    class PatternNotMatchedError < Error
+      def initialize(attr_name, pattern, value)
+        @attr_name = attr_name
+        @pattern = pattern
+        @value = value
+
+        super()
+      end
+
+      def to_s
+        "#{@attr_name}: \"#{@value}\" does not match #{@pattern.inspect}"
+      end
+    end
+  end
+end

data/lib/lutaml/model/error.rb

@@ -7,6 +7,7 @@ end
 
 require_relative "error/invalid_value_error"
 require_relative "error/incorrect_mapping_argument_error"
+require_relative "error/pattern_not_matched_error"
 require_relative "error/unknown_adapter_type_error"
 require_relative "error/collection_count_out_of_range_error"
 require_relative "error/validation_error"

data/lib/lutaml/model/mapping_hash.rb

@@ -28,6 +28,14 @@ module Lutaml
         @item_order = order
       end
 
+      def text
+        self["#cdata-section"] || self["text"]
+      end
+
+      def text?
+        key?("#cdata-section") || key?("text")
+      end
+
       def ordered?
         @ordered
       end

data/lib/lutaml/model/serialize.rb

@@ -343,7 +343,7 @@ module Lutaml
             value = if rule.raw_mapping?
                       doc.node.inner_xml
                     elsif rule.content_mapping?
-                      doc["text"]
+                      doc[rule.content_key]
                     elsif doc.key_exist?(rule.namespaced_name(options[:default_namespace]))
                       doc.fetch(rule.namespaced_name(options[:default_namespace]))
                     else
@@ -399,12 +399,12 @@ module Lutaml
 
           value = if value.is_a?(Array)
                     value.map do |v|
-                      text_hash?(attr, v) ? v["text"] : v
+                      text_hash?(attr, v) ? v.text : v
                     end
                   elsif attr&.raw? && value
                     value.node.children.map(&:to_xml).join
                   elsif text_hash?(attr, value)
-                    value["text"]
+                    value.text
                   else
                     value
                   end
@@ -428,7 +428,7 @@ module Lutaml
 
         def text_hash?(attr, value)
           return false unless value.is_a?(Hash)
-          return value.keys == ["text"] unless attr
+          return value.one? && value.text? unless attr
 
           !(attr.type <= Serialize) && attr.type != Lutaml::Model::Type::Hash
         end

data/lib/lutaml/model/validation.rb

@@ -8,7 +8,8 @@ module Lutaml
           begin
             attr.validate_value!(value)
           rescue Lutaml::Model::InvalidValueError,
-                 Lutaml::Model::CollectionCountOutOfRangeError => e
+                 Lutaml::Model::CollectionCountOutOfRangeError,
+                 PatternNotMatchedError => e
             errors << e
           end
         end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.3.25"
+    VERSION = "0.3.27"
   end
 end

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

@@ -51,7 +51,9 @@ module Lutaml
             end
           end
 
-          def add_text(element, text)
+          def add_text(element, text, cdata: false)
+            return add_cdata(element, text) if cdata
+
             if element.is_a?(self.class)
               element = element.xml.parent
             end
@@ -60,6 +62,10 @@ module Lutaml
             element.add_child(text_node)
           end
 
+          def add_cdata(element, value)
+            element.cdata(value)
+          end
+
           def add_namespace_prefix(prefix)
             xml[prefix] if prefix
 

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

@@ -66,10 +66,16 @@ module Lutaml
             xml.text(text)
           end
 
-          def add_text(element, text)
+          def add_text(element, text, cdata: false)
+            return element.cdata(text) if cdata
+
             element << text
           end
 
+          def add_cdata(element, value)
+            element.cdata(value)
+          end
+
           # Add XML namespace to document
           #
           # Ox doesn't support XML namespaces so we only save the

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 = {})
@@ -74,10 +81,12 @@ module Lutaml
               value = attribute_value_for(element, element_rule)
 
               if element_rule == xml_mapping.content_mapping
+                next if element_rule.cdata && name == "text"
+
                 text = xml_mapping.content_mapping.serialize(element)
                 text = text[curr_index] if text.is_a?(Array)
 
-                next prefixed_xml.text(text) if element.mixed?
+                next prefixed_xml.add_text(xml, text, cdata: element_rule.cdata) if element.mixed?
 
                 content << text
               elsif !value.nil? || element_rule.render_nil?

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)
@@ -56,15 +63,15 @@ module Lutaml
                                                        mapper_class: mapper_class)
               value = attribute_value_for(element, element_rule)
 
+              next if element_rule == xml_mapping.content_mapping && element_rule.cdata && name == "text"
+
               if element_rule == xml_mapping.content_mapping
                 text = element.send(xml_mapping.content_mapping.to)
                 text = text[curr_index] if text.is_a?(Array)
 
-                if element.mixed?
-                  el.add_text(el, text)
-                else
-                  content << text
-                end
+                next el.add_text(el, text, cdata: element_rule.cdata) if element.mixed?
+
+                content << text
               elsif !value.nil? || element_rule.render_nil?
                 value = value[curr_index] if attribute_def.collection?
 
@@ -88,10 +95,13 @@ module Lutaml
 
       class OxElement < XmlElement
         def initialize(node, root_node: nil)
-          if node.is_a?(String)
+          case node
+          when String
             super("text", {}, [], node, parent_document: root_node)
-          elsif node.is_a?(Ox::Comment)
+          when Ox::Comment
             super("comment", {}, [], node.value, parent_document: root_node)
+          when Ox::CData
+            super("#cdata-section", {}, [], node.value, parent_document: root_node)
           else
             namespace_attributes(node.attributes).each do |(name, value)|
               if root_node

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
@@ -152,16 +152,16 @@ module Lutaml
             )
           elsif rule.prefix_set?
             xml.create_and_add_element(rule.name, prefix: prefix) do
-              add_value(xml, value, attribute)
+              add_value(xml, value, attribute, cdata: rule.cdata)
             end
           else
             xml.create_and_add_element(rule.name) do
-              add_value(xml, value, attribute)
+              add_value(xml, value, attribute, cdata: rule.cdata)
             end
           end
         end
 
-        def add_value(xml, value, attribute)
+        def add_value(xml, value, attribute, cdata: false)
           if !value.nil?
             serialized_value = attribute.type.serialize(value)
 
@@ -172,7 +172,7 @@ module Lutaml
                 end
               end
             else
-              xml.add_text(xml, serialized_value)
+              xml.add_text(xml, serialized_value, cdata: cdata)
             end
           end
         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
@@ -244,7 +245,7 @@ module Lutaml
           value = attribute_value_for(element, rule)
           return unless render_element?(rule, element, value)
 
-          xml.add_text(xml, value)
+          xml.add_text(xml, value, cdata: rule.cdata)
         end
 
         def process_content_mapping(element, content_rule, xml)
@@ -261,7 +262,7 @@ module Lutaml
             text = content_rule.serialize(element)
             text = text.join if text.is_a?(Array)
 
-            xml.add_text(xml, text)
+            xml.add_text(xml, text, cdata: content_rule.cdata)
           end
         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
                     {}