lutaml-model 0.3.5 → 0.3.7

data/README.adoc

@@ -13,16 +13,13 @@ objects to and from various formats such as JSON, XML, YAML, and TOML. It uses
 an adapter pattern to support multiple libraries for each format, providing
 flexibility and extensibility for your data modeling needs.
 
-The name "LutaML" comes from the Latin word for clay, "Lutum", and "ML"
-for Markup Language. Just as clay can be molded and modeled into beautiful and
-practical end products, the Lutaml::Model gem is used for data modeling,
-allowing you to shape and structure your data into useful forms.
-
+NOTE: Lutaml::Model is designed to be mostly compatible with the data modeling
+API of https://www.shalerb.org[Shale], an impressive Ruby data modeller.
+Lutaml::Model is meant to address advanced needs not currently addressed by
+Shale.
 
-NOTE: Lutaml::Model is designed to be compatible with the
-https://www.shalerb.org[Shale] data modeling API. Shale is an amazing Ruby data
-modeller. Lutaml::Model is meant to address needs that are not currently
-addressed by Shale.
+NOTE: Instructions on how to migrate from Shale to Lutaml::Model are provided in
+<<migrate-from-shale>>.
 
 
 == Data modeling in a nutshell
@@ -80,6 +77,7 @@ There are two ways to define a data model in Lutaml::Model:
 * Inheriting from the `Lutaml::Model::Serializable` class
 * Including the `Lutaml::Model::Serialize` module
 
+[[define-through-inheritance]]
 ==== Definition through inheritance
 
 The simplest way to define a model is to create a class that inherits from
@@ -98,6 +96,7 @@ class Kiln < Lutaml::Model::Serializable
 end
 ----
 
+[[define-through-inclusion]]
 ==== Definition through inclusion
 
 If the model class already has a super class that it inherits from, the model
@@ -169,12 +168,6 @@ attribute :name_of_attribute, {symbol | string | class}
 | `Boolean` | `:boolean` | `Lutaml::Model::Type::Boolean` | `Boolean`
 | `Decimal` | `:decimal` | `Lutaml::Model::Type::Decimal` | `::BigDecimal`
 | `Hash` | `:hash` | `Lutaml::Model::Type::Hash` | `::Hash`
-| `Uuid` | `:uuid` | `Lutaml::Model::Type::Uuid` | `::String`
-| `Symbol` | `:symbol` | `Lutaml::Model::Type::Symbol` | `Symbol`
-| `Binary` | `:binary` | `Lutaml::Model::Type::Binary` | `Binary`
-| `Url` | `:url` | `Lutaml::Model::Type::Url` | `::URI`
-| `IpAddress` | `:ip_address` | `Lutaml::Model::Type::IpAddress` | `::IPAddr`
-| `Json` | `:json` | `Lutaml::Model::Type::Json` | `::JSON`
 
 |===
 
@@ -238,6 +231,7 @@ end
 ----
 ====
 
+[[attribute-enumeration]]
 === Attribute as an enumeration
 
 An attribute can be defined as an enumeration by using the `values` directive.
@@ -777,6 +771,7 @@ end
 ----
 ====
 
+[[namespace-inherit]]
 ===== Namespace with `inherit` option
 
 The `inherit` option is used at the element level to inherit the namespace from
@@ -838,7 +833,7 @@ end
 ----
 ====
 
-
+[[mixed-content]]
 ==== Mixed content
 
 ===== General
@@ -859,6 +854,8 @@ To map this to Lutaml::Model we can use the `mixed` option in either way:
 * when defining the model;
 * when referencing the model.
 
+NOTE: This feature is not supported by Shale.
+
 
 ===== Specifying the `mixed` option at `root`
 
@@ -1071,7 +1068,7 @@ end
 ----
 ====
 
-
+[[separate-serialization-model]]
 === Separate serialization model
 
 The `Serialize` module can be used to define only serialization mappings for a
@@ -1283,6 +1280,9 @@ end
 ----
 ====
 
+NOTE: The corresponding keyword used by Shale is `receiver:` instead of
+`delegate:`.
+
 
 ==== Attribute serialization with custom methods
 
@@ -1338,11 +1338,11 @@ class CustomCeramic < Lutaml::Model::Serializable
   end
 
   def name_to_json(model, value)
-    "Masterpiece: #{value}"
+    doc["name"] = "Masterpiece: #{value}"
   end
 
   def name_from_json(model, doc)
-    doc['name'].sub(/^Masterpiece: /, '')
+    model.name = value.sub(/^JSON Masterpiece: /, '')
   end
 end
 ----
@@ -1365,7 +1365,7 @@ end
 ====
 
 
-
+[[attribute-extraction]]
 ==== Attribute extraction
 
 NOTE: This feature is for key-value data model serialization only.
@@ -1561,7 +1561,7 @@ serialization format.
 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.
 
-The default configuration is as follows:
+The configuration is as follows:
 
 [source,ruby]
 ----
@@ -1579,6 +1579,21 @@ Lutaml::Model::Config.configure do |config|
 end
 ----
 
+You can also provide the adapter type by using symbols like 
+
+[source,ruby]
+----
+require 'lutaml/model'
+
+Lutaml::Model::Config.configure do |config|
+  config.xml_adapter_type = :nokogiri # can be one of [:nokogiri, :ox, :oga]
+  config.yaml_adapter_type = :standard_yaml
+  config.json_adapter_type = :standard_json # can be one of [:standard_json, :multi_json]
+  config.toml_adapter_type = :toml_rb # can be one of [:toml_rb, :tomlib]
+end
+----
+
+NOTE: By default `yaml_adapter_type` and `json_adapter_type` are set to `:standard_yaml` and `:standard_json` respectively.
 
 === XML
 
@@ -1699,6 +1714,400 @@ Lutaml::Model::Config.configure do |config|
 end
 ----
 
+
+== Comparison with Shale
+
+Lutaml::Model is a serialization library that is similar to Shale, but with some
+differences in implementation.
+
+[cols="a,a,a,a",options="header"]
+|===
+| Feature | Lutaml::Model | Shale | Notes
+
+| Data model definition
+|
+3 types:
+
+* <<define-through-inheritance,Inherit from `Lutaml::Model::Serializable`>>
+* <<define-through-inclusion,Include `Lutaml::Model::Serialize`>>
+* <<separate-serialization-model,Separate serialization model class>>
+|
+2 types:
+
+* Inherit from `Shale::Mapper`
+* Custom model class
+|
+
+| Value types
+| `Lutaml::Model::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `DateTime`, `Time`, `Hash`.
+| `Shale::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `Time`.
+| Lutaml::Model supports the additional value types `DateTime` and `Hash`.
+
+| Configuration
+| `Lutaml::Model::Config`
+| `Shale.{type}_adapter`
+| Lutaml::Model uses a configuration block to set the serialization adapters.
+
+| Custom serialization methods
+| `:with`, on individual attributes
+| `:using`, on entire object/document
+| Lutaml::Model uses the `:with` keyword for custom serialization methods.
+
+| Serialization formats
+| XML, YAML, JSON, TOML
+| XML, YAML, JSON, TOML, CSV
+| Lutaml::Model does not support CSV.
+
+| 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
+| Lutaml::Model does not support CSV.
+
+4+h| XML features
+
+| XML mixed content support
+| Yes. Supports the following kind of XML through <<mixed-content,mixed content>> support.
+
+[source,xml]
+----
+<description>My name is
+<bold>John Doe</bold>,
+and I'm <i>28</i>
+years old</description>
+----
+| No. Shale's `map_content` only supports the first text node.
+|
+
+| XML namespace inheritance
+| Yes. Supports the <<namespace-inherit,`inherit`>> option to inherit the
+namespace from the root element.
+| No.
+|
+
+4+h| Attribute features
+
+| Attribute delegation
+| `:delegate` option to delegate attribute mappings to a model.
+| `:receiver` option to delegate attribute mappings to a model.
+|
+
+| Enumerations
+| Yes. Supports enumerations as value types through the
+<<attribute-enumeration,`values:` option>>.
+| No.
+| Lutaml::Model supports enumerations as value types.
+
+| Attribute extraction
+| Yes. Supports <<attribute-extraction,attribute extraction>> from key-value
+data models.
+| No.
+| Lutaml::Model supports attribute extraction from key-value data models.
+
+
+|===
+
+
+[[migrate-from-shale]]
+== Migration steps from Shale
+
+The following sections provide a guide for migrating from Shale to Lutaml::Model.
+
+=== Step 1: Replace inheritance class
+
+`Lutaml::Model` uses `Lutaml::Model::Serializable` as the base inheritance class.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  # ...
+end
+----
+
+[NOTE]
+====
+`Lutaml::Model` also supports an inclusion method as in the following example,
+which is not supported by Shale. This is useful for cases where you want to
+include the serialization methods in a class that already inherits from another
+class.
+
+[source,ruby]
+----
+class Example
+  include Lutaml::Model::Serialize
+  # ...
+end
+----
+====
+
+Shale uses `Shale::Mapper` as the base inheritance class.
+
+[source,ruby]
+----
+class Example < Shale::Mapper
+  # ...
+end
+----
+
+Actions:
+
+* Replace mentions of `Shale::Mapper` with `Lutaml::Model::Serializable`.
+* Potentially replace inheritance with inclusion for suitable cases.
+
+
+=== Step 2: Replace value type definitions
+
+Value types in `Lutaml::Model` are under the `Lutaml::Model::Type` module.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :length, Lutaml::Model::Type::Integer
+  attribute :description, Lutaml::Model::Type::String
+end
+----
+
+[NOTE]
+====
+`Lutaml::Model` also 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 :description, "String"
+end
+----
+====
+
+Value types in Shale are under the `Shale::Type` module.
+
+[source,ruby]
+----
+class Example < Shale::Mapper
+  attribute :length, Shale::Type::Integer
+  attribute :description, Shale::Type::String
+end
+----
+
+Action:
+
+* Replace mentions of `Shale::Type` with `Lutaml::Model::Type`.
+* Potentially replace value type definitions with strings or symbols.
+
+
+=== Step 3: Configure serialization adapters
+
+`Lutaml::Model` uses a configuration block to set the serialization adapters.
+
+[source,ruby]
+----
+require 'lutaml/model/xml_adapter/nokogiri_adapter'
+Lutaml::Model::Config.configure do |config|
+  config.xml_adapter = Lutaml::Model::XmlAdapter::NokogiriAdapter
+end
+----
+
+The equivalent for Shale is this:
+
+[source,ruby]
+----
+require 'shale/adapter/nokogiri'
+Shale.xml_adapter = Shale::Adapter::Nokogiri
+----
+
+
+Here are places that this code may reside at:
+
+* If your code is a standalone Ruby script, this code will be present in your code.
+* If your code is organized in a Ruby gem, this code will be specified somewhere referenced by `lib/your_gem_name.rb`.
+* If your code contains tests or specs, they will be in the test setup file, e.g. RSpec `spec/spec_helper.rb`.
+
+Actions:
+
+* Replace the Shale configuration block with the `Lutaml::Model::Config`
+configuration block.
+
+* Replace the Shale adapter with the `Lutaml::Model` adapter.
+
+
+
+=== Step 4: Rewrite custom serialization methods
+
+There is an implementation difference between Lutaml::Model and Shale for custom
+serialization methods.
+
+Custom serialization methods in `Lutaml::Model` map to individual attributes.
+
+For custom serialization methods, Lutaml::Model uses the `:with` keyword
+instead of the `:using` keyword used by Shale.
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :size, :integer
+  attribute :color, :string
+  attribute :description, :string
+
+  json do
+    map "name", to: :name, with: { to: :name_to_json, from: :name_from_json }
+    map "size", to: :size
+    map "color", to: :color,
+                 with: { to: :color_to_json, from: :color_from_json }
+    map "description", to: :description,
+                       with: { to: :description_to_json, from: :description_from_json }
+  end
+
+  xml do
+    root "CustomSerialization"
+    map_element "Name", to: :name,
+                        with: { to: :name_to_xml, from: :name_from_xml }
+    map_attribute "Size", to: :size
+    map_element "Color", to: :color,
+                         with: { to: :color_to_xml, from: :color_from_xml }
+    map_content to: :description,
+                with: { to: :description_to_xml,
+                        from: :description_from_xml }
+  end
+
+  def name_to_json(model, doc)
+    doc["name"] = "JSON Masterpiece: #{model.name}"
+  end
+
+  def name_from_json(model, value)
+    model.name = value.sub(/^JSON Masterpiece: /, "")
+  end
+
+  def color_to_json(model, doc)
+    doc["color"] = model.color.upcase
+  end
+
+  def color_from_json(model, value)
+    model.color = value.downcase
+  end
+
+  def description_to_json(model, doc)
+    doc["description"] = "JSON Description: #{model.description}"
+  end
+
+  def description_from_json(model, value)
+    model.description = value.sub(/^JSON Description: /, "")
+  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 color_to_xml(model, parent, doc)
+    color_element = doc.create_element("Color")
+    doc.add_text(color_element, model.color.upcase)
+    doc.add_element(parent, color_element)
+  end
+
+  def color_from_xml(model, value)
+    model.color = value.downcase
+  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
+----
+
+Custom serialization methods in Shale do not map to specific attributes, but
+allow the user to specify where the data goes.
+
+[source,ruby]
+----
+class Example < Shale::Mapper
+  attribute :name, Shale::Type::String
+  attribute :size, Shale::Type::Integer
+  attribute :color, Shale::Type::String
+  attribute :description, Shale::Type::String
+
+  json do
+    map "name", using: { from: :name_from_json, to: :name_to_json }
+    map "size", to: :size
+    map "color", using: { from: :color_from_json, to: :color_to_json }
+    map "description", to: :description, using: { from: :description_from_json, to: :description_to_json }
+  end
+
+  xml do
+    root "CustomSerialization"
+    map_element "Name", using: { from: :name_from_xml, to: :name_to_xml }
+    map_attribute "Size", to: :size
+    map_element "Color", using: { from: :color_from_xml, to: :color_to_xml }
+    map_content to: :description, using: { from: :description_from_xml, to: :description_to_xml }
+  end
+
+  def name_to_json(model, doc)
+    doc['name'] = "JSON Masterpiece: #{model.name}"
+  end
+
+  def name_from_json(model, value)
+    model.name = value.sub(/^JSON Masterpiece: /, "")
+  end
+
+  def color_to_json(model, doc)
+    doc['color'] = model.color.upcase
+  end
+
+  def color_from_json(model, doc)
+    model.color = doc['color'].downcase
+  end
+
+  def description_to_json(model, doc)
+    doc['description'] = "JSON Description: #{model.description}"
+  end
+
+  def description_from_json(model, doc)
+    model.description = doc['description'].sub(/^JSON Description: /, "")
+  end
+
+  def name_from_xml(model, node)
+    model.name = node.text.sub(/^XML Masterpiece: /, "")
+  end
+
+  def name_to_xml(model, parent, doc)
+    name_element = doc.create_element('Name')
+    doc.add_text(name_element, model.street.to_s)
+    doc.add_element(parent, name_element)
+  end
+end
+----
+
+NOTE: There are cases where the Shale implementation of custom methods work
+differently from the Lutaml::Model implementation. In these cases, you will need
+to adjust the custom methods accordingly.
+
+Actions:
+
+* Replace the `using` keyword with the `with` keyword.
+* Adjust the custom methods.
+
+
+== About LutaML
+
+The name "LutaML" is pronounced as "Looh-tah-mel".
+
+The name "LutaML" comes from the Latin word for clay, "Lutum", and "ML"
+for "Markup Language". Just as clay can be molded and modeled into beautiful and
+practical end products, the Lutaml::Model gem is used for data modeling,
+allowing you to shape and structure your data into useful forms.
+
+
+
 == License and Copyright
 
 This project is licensed under the BSD 2-clause License.

data/lib/lutaml/model/attribute.rb

@@ -40,6 +40,33 @@ module Lutaml
       def render_nil?
         options.fetch(:render_nil, false)
       end
+
+      def serialize(value, format, options = {})
+        if value.is_a?(Array)
+          value.map do |v|
+            serialize(v, format, options)
+          end
+        elsif type <= Serialize
+          type.hash_representation(value, format, options)
+        else
+          type.serialize(value)
+        end
+      end
+
+      def cast(value, format, options = {})
+        value ||= [] if collection?
+        instance = options[:instance]
+
+        if value.is_a?(Array)
+          value.map do |v|
+            cast(v, format, instance: instance)
+          end
+        elsif type <= Serialize
+          type.apply_mappings(value, format, options)
+        else
+          Lutaml::Model::Type.cast(value, type)
+        end
+      end
     end
   end
 end

data/lib/lutaml/model/config.rb

@@ -3,11 +3,92 @@ module Lutaml
     module Config
       extend self
 
-      attr_accessor :xml_adapter, :json_adapter, :yaml_adapter, :toml_adapter
+      # Default values are set for these so the readers are defined below
+      attr_writer :json_adapter, :yaml_adapter
+
+      attr_accessor :xml_adapter, :toml_adapter
+
+      AVAILABLE_FORMATS = %i[xml json yaml toml].freeze
 
       def configure
         yield self
       end
+
+      # This will generate the following methods
+      #
+      # xml_adapter_type=
+      #   @params:
+      #     one of [:nokogiri, :ox, :oga]
+      #   @example
+      #     Lutaml::Model::Config.xml_adapter = :nokogiri
+      #
+      # json_adapter_type=
+      #   @params:
+      #     one of [:standard_json, :multi_json]
+      #     if not set, :standard_json will be used by default
+      #   @example
+      #     Lutaml::Model::Config.json_adapter = :standard_json
+      #
+      # yaml_adapter_type=
+      #   @params:
+      #     one of [:standard_yaml]
+      #     if not set, :standard_yaml will be used by default
+      #   @example
+      #     Lutaml::Model::Config.yaml_adapter = :standard_yaml
+      #
+      # toml_adapter_type=
+      #   @params
+      #     one of [:tomlib, :toml_rb]
+      #   @example
+      #     Lutaml::Model::Config.toml_adapter = :tomlib
+      AVAILABLE_FORMATS.each do |adapter_name|
+        define_method(:"#{adapter_name}_adapter_type=") do |type_name|
+          adapter = "#{adapter_name}_adapter"
+          type = "#{type_name}_adapter"
+
+          begin
+            adapter_file = File.join(adapter, type)
+            require_relative adapter_file
+          rescue LoadError
+            raise(
+              Lutaml::Model::UnknownAdapterTypeError.new(
+                adapter_name,
+                type_name,
+              ),
+              cause: nil,
+            )
+          end
+
+          instance_variable_set(
+            :"@#{adapter}",
+            Lutaml::Model.const_get(to_class_name(adapter))
+                         .const_get(to_class_name(type)),
+          )
+        end
+      end
+
+      # Return JSON adapter. By default StandardJsonAdapter is used
+      #
+      # @example
+      #   Lutaml::Model::Config.json_adapter
+      #   # => Lutaml::Model::YamlAdapter::StandardJsonAdapter
+      def json_adapter
+        @json_adapter || Lutaml::Model::JsonAdapter::StandardJsonAdapter
+      end
+
+      # Return YAML adapter. By default StandardYamlAdapter is used
+      #
+      # @example
+      #   Lutaml::Model::Config.yaml_adapter
+      #   # => Lutaml::Model::YamlAdapter::StandardYamlAdapter
+      def yaml_adapter
+        @yaml_adapter || Lutaml::Model::YamlAdapter::StandardYamlAdapter
+      end
+
+      # @api private
+      def to_class_name(str)
+        str.to_s.split("_").map(&:capitalize).join
+      end
     end
   end
 end

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

@@ -0,0 +1,16 @@
+module Lutaml
+  module Model
+    class UnknownAdapterTypeError < Error
+      def initialize(adapter_name, type_name)
+        @adapter_name = adapter_name
+        @type_name = type_name
+
+        super()
+      end
+
+      def to_s
+        "Unknown type: `#{@type_name}` for `#{@adapter_name}` adapter"
+      end
+    end
+  end
+end

data/lib/lutaml/model/error.rb

@@ -6,3 +6,4 @@ module Lutaml
 end
 
 require_relative "error/invalid_value_error"
+require_relative "error/unknown_adapter_type_error"