lutaml-model 0.8.0 → 0.8.2

data/bench/gate_config.rb

@@ -20,7 +20,7 @@ module GateConfig
     xmi: {
       "ea251" => {
         file: "ea-xmi-2.5.1.xmi",
-        alloc_ratio: 1.05,
+        alloc_ratio: 1.10,
         time_ratio: 1.15,
         absolute_max: 0.50,
       },
@@ -91,14 +91,7 @@ module GateConfig
       "pnas-152KB" => {
         alloc_ratio: 1.05,
         time_ratio: 1.15,
-        absolute_max: 1.0,
-      },
-    },
-    uniword: {
-      "iso690" => {
-        alloc_ratio: 1.05,
-        time_ratio: 1.15,
-        absolute_max: 60.0,
+        absolute_max: 1.5,
       },
     },
   }.freeze

data/docs/_pages/configuration.adoc

@@ -7,7 +7,27 @@ nav_order: 10
 
 == Overview
 
-Lutaml::Model uses an adapter pattern to support multiple serialization libraries. You must configure which adapters to use for each format.
+Lutaml::Model uses an adapter pattern to support multiple serialization libraries. Adapters are resolved automatically via lazy auto-detection, but can be explicitly configured when needed.
+
+== Auto-detection
+
+Lutaml::Model automatically detects available adapter gems at runtime on first use. You only need to configure adapters if:
+
+* You want to override the default choice
+* You are testing and need deterministic adapter selection
+* Your library requires a specific adapter
+
+The auto-detection order for each format:
+
+[cols="1,2",options="header"]
+|===
+| Format | Detection order
+| XML | `:nokogiri` → `:ox` → `:oga` → `:rexml`
+| TOML | `:tomlib` → `:toml_rb` (Windows: `:toml_rb` only)
+| JSON | `:standard` (always available)
+| YAML | `:standard` (always available)
+| Hash | `:standard` (always available)
+|===
 
 == Basic configuration
 
@@ -18,14 +38,24 @@ Use `Lutaml::Model::Config.configure` to set adapters:
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  config.xml_adapter_type = :nokogiri
-  config.json_adapter_type = :standard_json
-  config.yaml_adapter_type = :standard_yaml
-  config.toml_adapter_type = :toml_rb
-  config.hash_adapter_type = :standard_hash
+  config.xml_adapter = :nokogiri
+  config.json_adapter = :standard
+  config.yaml_adapter = :standard
+  config.toml_adapter = :toml_rb
+  config.hash_adapter = :standard
 end
 ----
 
+== Resolution chain
+
+When an adapter is needed for a format, `AdapterResolver` follows this chain:
+
+. **Thread-local scope override** — from `Config.with_adapter` block
+. **Explicitly configured type** — from `Config.xml_adapter_type = :nokogiri`
+. **Lazy auto-detected type** — cached after first probe
+. **Format default** — built-in default for the format
+. **Error** — `FormatAdapterNotSpecifiedError`
+
 == Available adapters
 
 === XML adapters
@@ -42,6 +72,9 @@ end
 
 | `:oga`
 | Pure Ruby. No compilation needed. Opal-compatible.
+
+| `:rexml`
+| Pure Ruby. Bundled with Ruby (default gem).
 |===
 
 === JSON adapters
@@ -50,7 +83,7 @@ end
 |===
 | Adapter | Description
 
-| `:standard_json` (default)
+| `:standard` (default, aliases: `:standard_json`)
 | Ruby standard library. No extra gems needed.
 
 | `:multi_json`
@@ -66,7 +99,7 @@ end
 |===
 | Adapter | Description
 
-| `:standard_yaml` (default)
+| `:standard` (default, aliases: `:standard_yaml`)
 | Psych (Ruby standard library). No extra gems needed.
 |===
 
@@ -85,30 +118,85 @@ end
 
 NOTE: The `:tomlib` adapter is not available on Windows due to segmentation fault issues. On Windows, `:toml_rb` is automatically used as the default.
 
-== Opal runtime compatibility
+== Per-operation adapter override
 
-Lutaml::Model supports running under https://opalrb.com[Opal] (Ruby compiled to JavaScript) with some limitations. The library detects the runtime automatically via `Lutaml::Model::RuntimeCompatibility` and adapts its behavior accordingly.
+Override the adapter for a single serialization/deserialization call using the `adapter:` option:
 
-=== Adapter defaults on Opal
+[source,ruby]
+----
+# Parse with Ox for this call only
+model = MyClass.from_xml(xml_string, adapter: :ox)
 
-[cols="1,2",options="header"]
-|===
-| Format | Behavior
-| XML | Only `:oga` is available (auto-selected). Nokogiri, Ox, and REXML require native extensions.
-| JSON | Only `:standard` is available. Oj and MultiJson require native extensions.
-| YAML | `:standard` (Psych ships with Opal's stdlib).
-| TOML | **Not available.** Both tomlib and toml-rb depend on native extensions.
-| Hash | `:standard` / `:standard_hash` (pure Ruby).
-|===
+# Serialize with REXML for this call only
+output = model.to_xml(adapter: :rexml)
+----
 
-=== Features unavailable on Opal
+This is useful for:
 
-The following features raise `NotImplementedError` when called under Opal:
+* Testing with a specific adapter without changing global configuration
+* Performance-sensitive operations using a faster adapter
+* Cross-adapter workflows (parse with one, serialize with another)
+
+== Scoped adapter context
+
+Use `Config.with_adapter` for thread-safe, block-scoped adapter overrides:
+
+[source,ruby]
+----
+# All XML operations in this block use Ox
+Lutaml::Model::Config.with_adapter(xml: :ox) do
+  model = MyClass.from_xml(data)
+  model.to_xml  # also uses Ox
+end
+# Outside the block, reverts to the configured default
+
+# Multiple formats at once
+Lutaml::Model::Config.with_adapter(xml: :nokogiri, toml: :tomlib) do
+  model = MyClass.from_xml(data)
+  toml = model.to_toml
+end
+----
+
+TIP: `with_adapter` is thread-safe — each thread has its own scope stack. Use it in tests instead of save/restore patterns:
+
+[source,ruby]
+----
+# Instead of this:
+around do |example|
+  old = Config.xml_adapter
+  Config.xml_adapter_type = :oga
+  example.run
+ensure
+  Config.xml_adapter = old
+end
+
+# Prefer this:
+around do |example|
+  Config.with_adapter(xml: :oga) { example.run }
+end
+----
 
-* `Lutaml::Model::Schema.to_xsd` — XSD schema generation requires Nokogiri
-* `Lutaml::Model::Schema.to_relaxng` — RELAX NG generation requires Nokogiri
-* `Lutaml::Model::Schema.from_xml` — XML schema compilation is not supported
-* `Lutaml::Xml::Schema::Xsd::Base#to_formatted_xml` — XSD formatted output requires the Canon gem
+== Library stacking
+
+When multiple libraries depend on lutaml-model, each can set its preferred adapter within a scoped context:
+
+[source,ruby]
+----
+# In gem "my_xml_library"
+module MyXmlLibrary
+  def self.parse(data)
+    # This gem requires Nokogiri internally
+    Config.with_adapter(xml: :nokogiri) do
+      MyModel.from_xml(data)
+    end
+  end
+end
+
+# The end-user's adapter choice is not affected
+Config.xml_adapter_type = :ox  # user prefers Ox
+result = MyXmlLibrary.parse(data)  # uses Nokogiri inside
+my_model.to_xml  # uses Ox (user's choice)
+----
 
 == Configuration with class references
 
@@ -118,8 +206,8 @@ For advanced use, specify adapter classes directly:
 ----
 require 'lutaml/model'
 require 'lutaml/xml/adapter/nokogiri_adapter'
-require 'lutaml/json/adapter/standard_adapter'
-require 'lutaml/yaml/adapter/standard_adapter'
+require 'lutaml/key_value/adapter/json/standard_adapter'
+require 'lutaml/key_value/adapter/yaml/standard_adapter'
 require 'lutaml/toml/adapter/toml_rb_adapter'
 
 Lutaml::Model::Config.configure do |config|
@@ -132,23 +220,23 @@ end
 
 == Default configuration
 
-If not configured, Lutaml::Model uses these defaults:
+If not explicitly configured, Lutaml::Model auto-detects on first use:
 
-* XML: `:nokogiri`
-* JSON: `:standard` (or `:standard_json` as an alias)
-* YAML: `:standard` (or `:standard_yaml` as an alias)
-* Hash: `:standard` (or `:standard_hash` as an alias)
+* XML: `:nokogiri` if available, else `:ox` → `:oga` → `:rexml`
+* JSON: `:standard` (alias: `:standard_json`)
+* YAML: `:standard` (alias: `:standard_yaml`)
+* Hash: `:standard` (alias: `:standard_hash`)
 * TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 == When to configure
 
 Configure adapters in one of these locations:
 
-For applications:: In an initializer or early-loading file
+For applications:: In an initializer or early-loading file (optional -- auto-detection usually sufficient)
 
-For gems:: Let end users configure adapters (document the requirement)
+For gems:: Do not configure globally. Use `Config.with_adapter` for internal adapter requirements.
 
-For testing:: In `spec_helper.rb` or test setup
+For testing:: In `spec_helper.rb` or test setup, or use `Config.with_adapter` per test.
 
 .RSpec configuration example
 [example]
@@ -159,10 +247,10 @@ For testing:: In `spec_helper.rb` or test setup
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  config.xml_adapter_type = :nokogiri
-  config.json_adapter_type = :standard_json
-  config.yaml_adapter_type = :standard_yaml
-  config.toml_adapter_type = :toml_rb
+  config.xml_adapter = :nokogiri
+  config.json_adapter = :standard
+  config.yaml_adapter = :standard
+  config.toml_adapter = :toml_rb
 end
 ----
 ====
@@ -174,6 +262,7 @@ end
 * **Nokogiri**: Most projects (default, best compatibility)
 * **Ox**: Performance-critical applications
 * **Oga**: Pure Ruby environments, Opal/JavaScript compilation
+* **REXML**: No extra gems, pure Ruby (bundled with Ruby)
 
 === Choose JSON adapter based on
 
@@ -186,7 +275,32 @@ end
 * **Tomlib**: Most projects on non-Windows (better performance)
 * **TomlRb**: Windows platforms (required due to tomlib incompatibility)
 
+== Opal runtime compatibility
+
+Lutaml::Model supports running under https://opalrb.com[Opal] (Ruby compiled to JavaScript) with some limitations. The library detects the runtime automatically via `Lutaml::Model::RuntimeCompatibility` and adapts its behavior accordingly.
+
+=== Adapter defaults on Opal
+
+[cols="1,2",options="header"]
+|===
+| Format | Behavior
+| XML | Only `:oga` is available (auto-selected). Nokogiri, Ox, and REXML require native extensions.
+| JSON | Only `:standard` is available. Oj and MultiJson require native extensions.
+| YAML | `:standard` (Psych ships with Opal's stdlib).
+| TOML | **Not available.** Both tomlib and toml-rb depend on native extensions.
+| Hash | `:standard` (pure Ruby).
+|===
+
+=== Features unavailable on Opal
+
+The following features raise `NotImplementedError` when called under Opal:
+
+* `Lutaml::Model::Schema.to_xsd` -- XSD schema generation requires Nokogiri
+* `Lutaml::Model::Schema.to_relaxng` -- RELAX NG generation requires Nokogiri
+* `Lutaml::Model::Schema.from_xml` -- XML schema compilation is not supported
+* `Lutaml::Xml::Schema::Xsd::Base#to_formatted_xml` -- XSD formatted output requires the Canon gem
+
 == See also
 
 * link:../serialization_adapters[Serialization Adapters Reference]
-* link:../references/custom_adapters[Creating Custom Adapters]
+* link:../references/custom_adapters[Creating Custom Adapters]

data/docs/_pages/serialization_adapters.adoc

@@ -41,6 +41,17 @@ different serialization libraries. Please refer to their specific sections for
 more information.
 
 
+=== Auto-detection
+
+Adapters are resolved lazily on first use. If no adapter is explicitly configured, `AdapterResolver` probes for available gems in a preferred order:
+
+* **XML**: `:nokogiri` → `:ox` → `:oga` → `:rexml`
+* **TOML**: `:tomlib` → `:toml_rb` (Windows: `:toml_rb` only)
+* **JSON/YAML/Hash**: `:standard` (always available)
+
+The detection result is cached after the first probe, so it only runs once per format.
+
+
 === Configuration
 
 ==== General
@@ -67,10 +78,10 @@ There are two ways to specify a configuration:
 
 There is a default configuration for adapters for commonly used formats:
 
-* XML: `:nokogiri`
-* YAML: `:standard` (or `:standard_yaml` as an alias)
-* JSON: `:standard` (or `:standard_json` as an alias)
-* Hash: `:standard` (or `:standard_hash` as an alias)
+* XML: `:nokogiri` (auto-detected)
+* YAML: `:standard` (alias: `:standard_yaml`)
+* JSON: `:standard` (alias: `:standard_json`)
+* Hash: `:standard` (alias: `:standard_hash`)
 * TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 
@@ -90,11 +101,11 @@ Syntax:
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  config.xml_adapter_type = :nokogiri # can be one of [:nokogiri, :ox, :oga, :rexml]
-  config.hash_adapter_type = :standard
-  config.yaml_adapter_type = :standard
-  config.json_adapter_type = :standard # can be one of [:standard, :multi_json, :oj]
-  config.toml_adapter_type = :toml_rb # can be one of [:toml_rb, :tomlib] (tomlib not available on Windows)
+  config.xml_adapter = :nokogiri # can be one of [:nokogiri, :ox, :oga, :rexml]
+  config.hash_adapter = :standard
+  config.yaml_adapter = :standard
+  config.json_adapter = :standard # can be one of [:standard, :multi_json, :oj]
+  config.toml_adapter = :toml_rb # can be one of [:toml_rb, :tomlib] (tomlib not available on Windows)
 end
 ----
 
@@ -130,6 +141,41 @@ end
 ====
 
 
+==== Per-operation adapter override
+
+Override the adapter for a single call using the `adapter:` option:
+
+[source,ruby]
+----
+# Parse with Ox for this call only
+model = MyClass.from_xml(xml_string, adapter: :ox)
+
+# Serialize with REXML for this call only
+output = model.to_xml(adapter: :rexml)
+----
+
+
+==== Scoped adapter context
+
+Use `Config.with_adapter` for thread-safe, block-scoped overrides:
+
+[source,ruby]
+----
+Lutaml::Model::Config.with_adapter(xml: :ox) do
+  model = MyClass.from_xml(data)
+  model.to_xml  # also uses Ox
+end
+# Outside the block, reverts to the configured default
+
+# Multiple formats at once
+Lutaml::Model::Config.with_adapter(xml: :nokogiri, toml: :tomlib) do
+  model = MyClass.from_xml(data)
+  toml = model.to_toml
+end
+----
+
+TIP: `with_adapter` is thread-safe -- use it in tests instead of save/restore patterns.
+
 
 === XML
 
@@ -154,6 +200,12 @@ Fast XML parser and object serializer for Ruby, implemented partially in C.
 Requires native extensions (i.e. compiled C code).
 Requires the `ox` gem.
 
+REXML::
+(optional)
+Pure Ruby XML parser, bundled as a default gem with Ruby.
+Moved from standard library to a default gem in Ruby 3.0.
+Requires the `rexml` gem (bundled with Ruby by default).
+
 
 .Using an XML adapter
 [source,ruby]
@@ -166,6 +218,8 @@ Lutaml::Model::Config.configure do |config|
   config.xml_adapter = :oga
   # or
   config.xml_adapter = :ox
+  # or
+  config.xml_adapter = :rexml
 end
 ----
 
@@ -185,7 +239,7 @@ Included in the Ruby standard library.
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  config.yaml_adapter = :standard_yaml
+  config.yaml_adapter = :standard
 end
 ----
 
@@ -215,7 +269,7 @@ Requires the `oj` gem.
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  config.json_adapter = :standard_json
+  config.json_adapter = :standard
   # or
   config.json_adapter = :multi_json
   # or
@@ -263,6 +317,3 @@ raised to indicate that the input format is malformed and cannot be parsed.
 NOTE: The `:tomlib` TOML adapter is disabled on Windows due to segmentation
 fault issues. Attempting to configure `:tomlib` on Windows will raise an
 `ArgumentError`. Use `:toml_rb` on Windows instead.
-
-
-

data/docs/index.adoc

@@ -16,7 +16,7 @@ Lutaml::Model is a Ruby library for creating information models with attributes
 == Key features
 
 * **Model-driven design** - Define models with attributes and types
-* **Multi-format serialization** - XML, JSON, YAML, TOML, Hash
+* **Multi-format serialization** - XML, JSON, YAML, TOML, Hash, YAML Stream
 * **XML namespace support** - Full W3C namespace implementation
 * **Validation** - Built-in validation with custom rules
 * **Schema generation** - Generate XSD, JSON Schema, YAML Schema
@@ -81,6 +81,8 @@ Person.from_json(json_string)
 
 Fundamental concepts, configuration, and essential features.
 
+* link:yamls_sequence.adoc[YAMLS Sequence -- Heterogeneous YAML Stream Support]
+
 === link:tutorials/index[Tutorials]
 
 Progressive, step-by-step learning from basics to advanced topics.