lutaml-model 0.8.99 → 0.8.101

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41d8d37a85f86f8d8f30d632c36526fe311ba0156f01a096a15717627f29ec72
-  data.tar.gz: f15221cd4017756a1045502f77b588df6ae8f3e62ff39b38ac10c8d6f4a68115
+  metadata.gz: 70de43228d2b233faab386c9016139160f2b75e9f76c27386de22104df2820f5
+  data.tar.gz: 78b4591ba8eec19bbc7fde9a1fd2d298c58094b1198352f2323067406d39b5aa
 SHA512:
-  metadata.gz: 509fc9f6462f37013113fdcb7a582ca70e9ce0ff021b51c780f9afdd66c03ec2c62213bd0c76a680dc993db138182b7260ed821757b37946b2b61941e2b9b066
-  data.tar.gz: e01bb47f5085c77f6ce840f31ac4f9f243271846267f1083c2c099cfae7f2ced2979f73a61a3a44ea0b0d609b9176a6e8d64e8841994c794382fd0a16c0880f2
+  metadata.gz: f1d54790ba8f6d44834134ef283b3d146002e3ca4f2e25f0fb99e84bd442878d6470d50f6da81f36a8e4165e93c07e2e3a6de2cffeb981f45b40d849a6be1037
+  data.tar.gz: 4d358cd375296cdb737fa12300076a4154f38aa22ce940cbcb7483453691152d4cbfd25fef88131fe1150105868eb9a1d56fa193028f3bd51eff7eb853d43c09

data/docs/_guides/schema-generation.adoc

@@ -901,3 +901,28 @@ The generated schema will include validation constraints:
   </define>
 </grammar>
 ----
+
+== Documentation metadata (desc)
+
+Models and attributes carry documentation strings through `desc` —
+set on the model class or on any `attribute` declaration, read back
+by documentation and schema tooling. Serialization is never affected
+by it.
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  desc "This is a title."
+
+  attribute :type, :string, desc: "This attribute is used for..."
+end
+
+Title.desc # => "This is a title."
+Title.attributes[:type].desc # => "This attribute is used for..."
+----
+
+Subclasses inherit the nearest ancestor's class description; an
+explicit `desc` overrides it. A consumer override-free `desc` value
+does not change any generated schema today — wiring `desc` into the
+generated `description` fields is deliberate product scope, not a
+free rider on this option.

data/lib/lutaml/model/attribute.rb

@@ -46,6 +46,7 @@ module Lutaml
         signed
         min_length
         max_length
+        desc
       ].freeze
 
       # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
@@ -641,6 +642,12 @@ instance_object = nil)
         options[:pattern]
       end
 
+      # Documentation metadata (#356): the `:desc` attribute option,
+      # consumed by documentation and schema tooling.
+      def desc
+        options[:desc]
+      end
+
       # Performance: Frozen empty array to reduce allocations
       EMPTY_VALUES_ARRAY = [].freeze
 

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -505,6 +505,22 @@ module Lutaml
           end
         end
 
+        # Class-level documentation metadata (#356): `desc "text"` on
+        # the model class; a zero-argument call reads it back.
+        # Subclasses inherit the nearest ancestor's description — an
+        # explicit `desc` overrides. Consumed by documentation and
+        # schema tooling; the serialization paths never read it.
+        def desc(text = nil)
+          return @lutaml_desc = text if text
+
+          return @lutaml_desc if defined?(@lutaml_desc)
+
+          if superclass.is_a?(::Class) &&
+              superclass < ::Lutaml::Model::Serializable
+            superclass.desc
+          end
+        end
+
         # Define an attribute for the model
         #
         # @param name [Symbol] The attribute name

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.99"
+    VERSION = "0.8.101"
   end
 end

data/lib/lutaml/xml/leptris/plan_serializer.rb

@@ -240,7 +240,7 @@ module Lutaml
               when :raw
                 Array(value).each { |raw| element.add_child(raw.to_s) }
               when :content, :content_deferred
-                Array(value).each { |run| element.add_child(doc.create_text_node(run.to_s)) }
+                Array(value).each { |run| append_text(element, run.to_s, doc) }
               end
             end
           end
@@ -426,10 +426,33 @@ module Lutaml
           def add_leaf(element, name, value, doc, attrs: nil)
             child = element.create_child(name)
             attrs&.each { |k, v| child[k.to_s] = v.to_s }
-            child.add_child(doc.create_text_node(value.to_s)) unless value.nil?
+            append_text(child, value.to_s, doc) unless value.nil?
             child
           end
 
+          # Text attach: the address face (leptris#408 adoption,
+          # leptris 1.9.334) passes raw node addresses — the pointer
+          # face mints an FFI::Pointer wrapper per fresh node, the
+          # last per-row Ruby-side allocation on the DOM build. Same
+          # semantics and status contract; probe-gated because a
+          # numerically newer lockstep can publish without the face.
+          def append_text(parent, text, doc)
+            node = doc.create_text_node(text)
+            if Leptris.text_attach_addr_compatible?
+              status = ::Leptris::XML::FFI.leptris_element_add_child_addr(
+                parent.c_address, node.c_address
+              )
+              unless status.zero?
+                raise ::Leptris::XML::Error,
+                  "text attach failed (status=#{status})"
+              end
+
+              node
+            else
+              parent.add_child(node)
+            end
+          end
+
           def value_of(instance, attr, delegate)
             if delegate
               target = instance.public_send(delegate)

data/lib/lutaml/xml/leptris.rb

@@ -97,6 +97,19 @@ module Lutaml
         spec && spec.version >= Gem::Version.new(MIN_LEPTRIS_NS_UNQUALIFIED_VERSION)
       end
 
+      # The address-based text attach (leptris#408, binding 1.9.334):
+      # leptris_element_add_child_addr skips the per-node FFI pointer
+      # mint. Capability-probed, not version-gated — the FFI face is
+      # attached or it is not, and a lockstep can publish without it.
+      @text_attach_addr = nil
+      def self.text_attach_addr_compatible?
+        return @text_attach_addr unless @text_attach_addr.nil?
+
+        @text_attach_addr =
+          !!(defined?(::Leptris::XML::FFI) &&
+            ::Leptris::XML::FFI.respond_to?(:leptris_element_add_child_addr))
+      end
+
       autoload :PlanCompiler, "lutaml/xml/leptris/plan_compiler"
       autoload :PlanHydrator, "lutaml/xml/leptris/plan_hydrator"
       autoload :PlanOrder, "lutaml/xml/leptris/plan_order"

data/lutaml-model.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
 
   # required for liquid
-  spec.add_dependency "base64"
+  spec.add_dependency "base64", ">= 0.1.1"
   spec.add_dependency "bigdecimal"
   spec.add_dependency "canon"
   spec.add_dependency "concurrent-ruby"
@@ -44,7 +44,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "moxml", "~> 0.5.84"
   spec.add_dependency "ostruct"
   spec.add_dependency "rubyzip", "~> 3.7"
-  spec.add_dependency "thor"
+  spec.add_dependency "thor", "~> 1.4"
 
   spec.metadata["rubygems_mfa_required"] = "true"
 end

data/spec/lutaml/model/desc_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+RSpec.describe "Documentation metadata (desc)" do
+  let(:widget_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      desc "A widget."
+
+      attribute :name, :string, desc: "The widget name."
+      attribute :size, :integer
+    end
+  end
+
+  it "stores and reads the class-level description" do
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "returns nil when no description is set" do
+    plain = Class.new(Lutaml::Model::Serializable)
+    expect(plain.desc).to be_nil
+  end
+
+  it "inherits the description on subclasses" do
+    child = Class.new(widget_class)
+    expect(child.desc).to eq("A widget.")
+  end
+
+  it "lets a subclass override the description" do
+    child = Class.new(widget_class) do
+      desc "A special widget."
+    end
+    expect(child.desc).to eq("A special widget.")
+  end
+
+  it "does not leak an override back to the superclass" do
+    Class.new(widget_class) { desc "Child only." }
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "stores the attribute-level description" do
+    expect(widget_class.attributes[:name].desc).to eq("The widget name.")
+    expect(widget_class.attributes[:size].desc).to be_nil
+  end
+
+  it "keeps serialization untouched" do
+    widget = widget_class.new(name: "w", size: 3)
+    expect(widget.to_hash).to eq("name" => "w", "size" => 3)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.99
+  version: 0.8.101
 platform: ruby
 authors:
 - Ribose Inc.
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
@@ -132,16 +132,16 @@ dependencies:
   name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.4'
 description: 'LutaML creating data models in Ruby
 
   '
@@ -1742,6 +1742,7 @@ files:
 - spec/lutaml/model/deferred_type_no_materialize_spec.rb
 - spec/lutaml/model/delegation_spec.rb
 - spec/lutaml/model/derived_attribute_serialization_spec.rb
+- spec/lutaml/model/desc_spec.rb
 - spec/lutaml/model/dynamic_attribute_spec.rb
 - spec/lutaml/model/encoding_spec.rb
 - spec/lutaml/model/enum_spec.rb