lutaml-model 0.8.17 → 0.8.19

data/lib/lutaml/model/schema/rng_compiler/rng_helpers.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module RngCompiler
+        # RNG-specific helpers used by ElementVisitor, DefineClassifier, and
+        # ValueTypeResolver. Centralising these here avoids the three-way
+        # semantic drift the first refactor introduced (e.g. inconsistent
+        # `pure_value_choice?` implementations).
+        module RngHelpers
+          module_function
+
+          # True if the compiled define renders as a value type (RestrictedType
+          # or UnionType) rather than its own Serializable class. Single
+          # source of truth — used by ElementVisitor and ValueTypeResolver.
+          def simple_type?(klass)
+            klass.is_a?(Definitions::RestrictedType) ||
+              klass.is_a?(Definitions::UnionType)
+          end
+
+          # True iff `klass` is a fragment model (no rooted xml element).
+          def fragment_model?(klass)
+            klass.is_a?(Definitions::Model) && klass.xml_root.kind == :fragment
+          end
+
+          # Returns the only element of a collection, or nil if the
+          # collection is empty or has more than one element. Treats nil as
+          # an empty collection.
+          def single(collection)
+            arr = Array(collection)
+            arr.size == 1 ? arr.first : nil
+          end
+
+          # An RNG node has structural content when any of its element /
+          # ref / attribute / choice / group / optional / repetition
+          # children are populated.
+          def structural_content?(node)
+            node && present_children?(node, STRUCTURAL_CHILD_NAMES)
+          end
+
+          # True iff any of `attrs` is a populated array-child of `node`.
+          def present_children?(node, attrs)
+            attrs.any? do |attr|
+              node.respond_to?(attr) && Array(node.public_send(attr)).any?
+            end
+          end
+
+          # True when `node` has branching structure that needs its own
+          # class. Pure value-choices and `<ref>`s to simple types are NOT
+          # branching — they're typed leaves.
+          def branching_structural?(node)
+            return false unless node
+
+            non_leaf = STRUCTURAL_CHILD_NAMES - %i[choice ref]
+            return true if present_children?(node, non_leaf)
+
+            return false unless node.respond_to?(:choice)
+
+            Array(node.choice).any? { |c| !pure_value_choice?(c) }
+          end
+
+          # True iff `choice` is a <choice> consisting purely of <value>
+          # alternatives (no <element>, <ref>, <data>, or <text>). A <text>
+          # alternative subsumes the literals, so `text | "x"` is a plain
+          # string, not an enum restricted to "x".
+          def pure_value_choice?(choice)
+            return false unless choice
+            return false unless choice.respond_to?(:value) && Array(choice.value).any?
+            return false if choice.respond_to?(:text) && Utils.present?(choice.text)
+
+            !present_children?(choice, %i[element ref data])
+          end
+
+          # True iff `choice` is a union: at least 2 <data> alternatives
+          # and no other content.
+          def pure_union_choice?(choice)
+            return false unless choice
+            return false unless choice.respond_to?(:data) && Array(choice.data).size >= 2
+
+            !present_children?(choice, %i[element ref value])
+          end
+
+          # Build a Definitions::Facet from an RNG <data>'s <param> children.
+          def facet_from_data(data)
+            facet = Definitions::Facet.new
+            Array(data.param).each do |param|
+              apply_param(facet, param.name, param.value.to_s)
+            end
+            facet
+          end
+
+          # Build a Definitions::Facet from an array of <value> elements.
+          def facet_from_values(values)
+            Definitions::Facet.new(
+              enumerations: Array(values).map(&:value),
+            )
+          end
+
+          # Snake_case symbol used as the registry key for a generated
+          # simple-type/union-type/namespace class.
+          def type_symbol(class_name)
+            Utils.snake_case(class_name).to_sym
+          end
+
+          # A class name derived from base_name that does not collide with an
+          # existing key in `classes` (appends 2, 3, ... on collision).
+          def unique_class_name(classes, base_name)
+            return base_name unless classes.key?(base_name)
+
+            counter = 2
+            counter += 1 while classes.key?("#{base_name}#{counter}")
+            "#{base_name}#{counter}"
+          end
+
+          # Maps an RNG/XSD base symbol to its Ruby parent class string,
+          # defaulting to the string type when unknown.
+          def parent_class_for(base_symbol)
+            Lutaml::Model::Type::TYPE_CODES.fetch(
+              base_symbol, Lutaml::Model::Type::TYPE_CODES[:string]
+            ).to_s
+          end
+
+          def apply_param(facet, name, value)
+            case name
+            when "minInclusive" then facet.min_inclusive = numeric_or_string(value)
+            when "maxInclusive" then facet.max_inclusive = numeric_or_string(value)
+            when "minExclusive" then facet.min_exclusive = numeric_or_string(value)
+            when "maxExclusive" then facet.max_exclusive = numeric_or_string(value)
+            when "minLength"    then facet.min_length = value.to_i
+            when "maxLength"    then facet.max_length = value.to_i
+            when "length"       then facet.length = value.to_i
+            when "pattern"      then facet.pattern = value
+            end
+          end
+
+          def numeric_or_string(value)
+            return value.to_i if /\A-?\d+\z/.match?(value)
+            return value.to_f if /\A-?\d+\.\d+\z/.match?(value)
+
+            value
+          end
+
+          STRUCTURAL_CHILD_NAMES = %i[
+            element ref attribute choice group
+            optional zeroOrMore oneOrMore
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/rng_compiler/value_type_resolver.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module RngCompiler
+        # Resolves the value-shape of an element or attribute container into a
+        # Symbol (built-in / registered type) or nil if the container has
+        # structural content needing its own class.
+        #
+        # Patterns handled:
+        #   <element><text/></element>                              -> :string
+        #   <element><data type="X"/></element>                     -> mapped primitive
+        #   <element><data ...><param ...>/></data></element>       -> anonymous RestrictedType (returns its registry symbol)
+        #   <element><choice><value>...</value></choice></element>  -> anonymous RestrictedType (enum) (returns its registry symbol)
+        #   <element><ref name="StFoo"/></element>                  -> :st_foo (if simple)
+        #
+        # When an anonymous RestrictedType is needed, the resolver *builds* it
+        # (pure) and asks the supplied `register_class` callback to register
+        # it. Build and register are separate methods so unit testing can
+        # exercise the pure logic without side effects.
+        class ValueTypeResolver
+          def initialize(defines, classes, compile_define:, register_class:)
+            @defines = defines
+            @classes = classes
+            @compile_define = compile_define
+            @register_class = register_class
+          end
+
+          # Returns the resolved type symbol, or nil if `container` needs
+          # its own class. May register an anonymous RestrictedType as a
+          # side effect (delegated to the register_class callback).
+          def resolve(container)
+            return nil if RngHelpers.branching_structural?(container)
+
+            type_from_inline_simple(container) || primitive_or_ref(container)
+          end
+
+          private
+
+          def type_from_inline_simple(container)
+            simple = build_anonymous_simple_type(container)
+            return nil unless simple
+
+            @register_class.call(simple)
+            RngHelpers.type_symbol(simple.class_name)
+          end
+
+          def build_anonymous_simple_type(container)
+            anonymous_from_data(container) || anonymous_from_enum_choice(container)
+          end
+
+          def anonymous_from_data(container)
+            data = RngHelpers.single(container.data)
+            return nil unless data && Array(data.param).any?
+
+            base = RngCompiler::DATA_TYPE_MAP.fetch(
+              data.type, RngCompiler::DEFAULT_DATA_TYPE
+            )
+            anonymous_restricted_type(container, base, RngHelpers.facet_from_data(data))
+          end
+
+          def anonymous_from_enum_choice(container)
+            choice = RngHelpers.single(container.choice)
+            return nil unless choice && RngHelpers.pure_value_choice?(choice)
+
+            anonymous_restricted_type(container, :string, RngHelpers.facet_from_values(choice.value))
+          end
+
+          def anonymous_restricted_type(container, base, facet)
+            Definitions::RestrictedType.new(
+              class_name: RngHelpers.unique_class_name(
+                @classes, "#{Utils.camel_case(container.attr_name.to_s)}Type"
+              ),
+              parent_class: RngHelpers.parent_class_for(base),
+              facets: facet,
+            )
+          end
+
+          def primitive_or_ref(container)
+            primitive = detect_primitive_type(container)
+            return primitive if primitive
+
+            ref_to_simple_type_symbol(container)
+          end
+
+          def ref_to_simple_type_symbol(container)
+            ref = RngHelpers.single(container.ref)
+            return nil unless ref
+
+            target = @defines[ref.name]
+            return nil unless target
+
+            target_class = @compile_define.call(target)
+            return RngHelpers.type_symbol(target_class.class_name) if RngHelpers.simple_type?(target_class)
+
+            nil
+          end
+
+          def detect_primitive_type(child)
+            return nil if RngHelpers.structural_content?(child)
+
+            primitive_from_data(child) || primitive_from_text(child) || primitive_from_value(child)
+          end
+
+          def primitive_from_data(child)
+            return nil unless child.data
+
+            RngCompiler::DATA_TYPE_MAP.fetch(child.data.type, RngCompiler::DEFAULT_DATA_TYPE)
+          end
+
+          def primitive_from_text(child)
+            :string if Utils.present?(child.text)
+          end
+
+          def primitive_from_value(child)
+            # <element><choice><value>a</value>...</choice></element> falls
+            # through to this path as :string with no constraint emitted.
+            :string if Array(child.value).any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/rng_compiler.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Lutaml
+  module Model
+    module Schema
+      # Compiles a parsed RNG grammar into Lutaml::Model::Serializable Ruby
+      # source. Mirrors XmlCompiler in API, options, and output format.
+      #
+      # Requires the `rng` gem (https://github.com/lutaml/rng) at runtime --
+      # that gem provides the Rng::Grammar parsing model. lutaml-model itself
+      # has no dependency on it. Registration of Schema.from_relaxng is done
+      # in lib/lutaml/xml.rb (alongside Schema.from_xml and Schema.to_relaxng).
+      #
+      # Entry point: Lutaml::Model::Schema::RngCompiler.to_models(rng, options)
+      module RngCompiler
+        extend self
+
+        autoload :MemberCollector,   "#{__dir__}/rng_compiler/member_collector"
+        autoload :ElementVisitor,    "#{__dir__}/rng_compiler/element_visitor"
+        autoload :DefineClassifier,  "#{__dir__}/rng_compiler/define_classifier"
+        autoload :ValueTypeResolver, "#{__dir__}/rng_compiler/value_type_resolver"
+        autoload :RngHelpers,        "#{__dir__}/rng_compiler/rng_helpers"
+
+        # Map RNG <data type="..."/> values to Lutaml::Model attribute type
+        # symbols. Mirrors Lutaml::Xml::Schema::RelaxngSchema.get_relaxng_type
+        # so RNG-generate + compile-back is a round-trip.
+        DATA_TYPE_MAP = {
+          "string" => :string,
+          "integer" => :integer,
+          "int" => :integer,
+          "long" => :integer,
+          "boolean" => :boolean,
+          "float" => :float,
+          "double" => :float,
+          "decimal" => :decimal,
+          "date" => :date,
+          "dateTime" => :date_time,
+          "time" => :time,
+        }.freeze
+
+        DEFAULT_DATA_TYPE = :string
+
+        def to_models(rng, options = {})
+          require_rng_parser!
+
+          opts = normalize_options(options)
+          output = compile(rng, opts)
+
+          dispatch_output(output, normalize_options(opts))
+        end
+
+        def compile(rng, options = {})
+          require_rng_parser!
+
+          opts = normalize_options(options)
+          grammar = parse_grammar(rng, opts)
+          classes, namespaces = compile_grammar(grammar)
+
+          entries =
+            classes.map { |name, spec| CompiledOutput::Entry.new(name, spec, :model) } +
+            namespaces.map { |name, spec| CompiledOutput::Entry.new(name, spec, :namespace) }
+
+          CompiledOutput.new(
+            entries: entries,
+            module_namespace: opts[:module_namespace],
+            register_id: opts[:register_id],
+          )
+        end
+
+        private
+
+        def require_rng_parser!
+          return if defined?(::Rng::Grammar)
+
+          raise "RNG schema compilation requires the rng gem. " \
+                "Add `gem \"rng\"` to your Gemfile."
+        end
+
+        def normalize_options(options)
+          opts = options.dup
+          opts[:indent]      ||= 2
+          opts[:register_id] ||= :default
+          opts
+        end
+
+        def parse_grammar(rng, options)
+          return rng if rng.is_a?(::Rng::Grammar)
+
+          if options[:location]
+            ::Rng.parse(rng, location: options[:location], resolve_external: true)
+          else
+            ::Rng::Grammar.from_xml(rng)
+          end
+        end
+
+        def dispatch_output(output, options)
+          if options[:create_files]
+            dir = options.fetch(
+              :output_dir,
+              options.fetch(:default_output_dir, "rng_models_#{Time.now.to_i}"),
+            )
+            FileWriter.write(output, dir)
+            true
+          elsif options[:load_classes]
+            ClassLoader.load(output)
+            output.sources
+          else
+            output.sources
+          end
+        end
+
+        # Returns [classes_hash, namespaces_hash]. `classes` holds
+        # Definitions::Model / Definitions::RestrictedType / Definitions::UnionType.
+        # `namespaces` holds Definitions::Namespace.
+        def compile_grammar(grammar)
+          defines = grammar.define.to_h { |d| [d.name, d] }
+          classes = {}
+          namespaces = {}
+          registrar = ->(uri) { register_namespace(namespaces, uri) }
+
+          default_uri = grammar_default_ns(grammar)
+          visitor = ElementVisitor.new(
+            defines, classes,
+            default_namespace_class: default_uri && registrar.call(default_uri),
+            register_namespace: registrar
+          )
+
+          grammar.start.each do |start|
+            visitor.compile_element(start.element) if start.element
+            Array(start.ref).each do |ref|
+              target = defines[ref.name]
+              visitor.compile_define(target) if target
+            end
+          end
+
+          # Sweep: compile any <define> not reachable from <start>.
+          grammar.define.each { |define| visitor.compile_define(define) }
+
+          finalize_models(classes)
+
+          [classes, namespaces]
+        end
+
+        def grammar_default_ns(grammar)
+          uri = grammar.respond_to?(:ns) ? grammar.ns : nil
+          uri if uri.is_a?(String) && !uri.empty?
+        end
+
+        # Build-or-find the namespace for `uri`; returns its class_name.
+        # RNG/RNC name-prefixed elements are namespace-qualified, so descendant
+        # elements inherit the namespace via element_form_default :qualified.
+        def register_namespace(namespaces, uri)
+          existing = namespaces.values.find { |ns| ns.uri == uri }
+          return existing.class_name if existing
+
+          # Distinct URIs can map to the same generated class name AND prefix
+          # (e.g. both `urn:a` and `urn:b` -> "DefaultNamespace"/"ns"); uniquify
+          # both so one namespace does not silently overwrite the other or
+          # collide with its prefix at serialization.
+          class_name = RngHelpers.unique_class_name(
+            namespaces, NamespaceNaming.class_name_for(uri)
+          )
+          ns = Definitions::Namespace.new(
+            class_name: class_name,
+            uri: uri,
+            prefix_default: unique_prefix(namespaces, NamespaceNaming.prefix_for(uri)),
+            element_form_default: :qualified,
+          )
+          namespaces[class_name] = ns
+          class_name
+        end
+
+        # A prefix that does not collide with an already-registered namespace's
+        # prefix (appends 2, 3, ... on collision).
+        def unique_prefix(namespaces, base)
+          taken = namespaces.values.map(&:prefix_default)
+          return base unless taken.include?(base)
+
+          counter = 2
+          counter += 1 while taken.include?("#{base}#{counter}")
+          "#{base}#{counter}"
+        end
+
+        # Set `required_files` so each generated file requires its
+        # dependencies: a Model requires its imports/class_ref types/namespace;
+        # a namespaced RestrictedType requires its namespace class.
+        def finalize_models(classes)
+          classes.each_value do |spec|
+            case spec
+            when Definitions::Model
+              spec.required_files =
+                Renderers::RequiredFilesCalculator.class_names_for_rng(spec)
+                  .map { |dep| require_relative_line(dep) }
+            when Definitions::RestrictedType
+              next unless spec.namespace_class_name
+
+              spec.required_files = namespaced_type_requires(spec)
+            end
+          end
+        end
+
+        # A namespaced RestrictedType requires its namespace class and, when it
+        # subclasses another generated type (a bare name, not a Lutaml built-in),
+        # that parent too.
+        def namespaced_type_requires(spec)
+          deps = [spec.namespace_class_name]
+          parent = spec.parent_class
+          deps << parent if parent && !parent.include?("::")
+          deps.map { |dep| require_relative_line(dep) }
+        end
+
+        def require_relative_line(class_name)
+          %(require_relative "#{Utils.snake_case(class_name)}")
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/templates.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Lutaml
+  module Model
+    module Schema
+      # Templates that are *actually* shared between schema compilers
+      # (XSD, RNG, future formats). Single-consumer templates live in
+      # the renderer that uses them — putting them here would just be
+      # relocation, not deduplication.
+      #
+      # Each constant is an `ERB.new(...)` evaluated via
+      # `TEMPLATE.result(binding)` from a renderer that exposes the
+      # required hook methods (documented above each template).
+      module Templates
+        # ----------------------------------------------------------------
+        # Single shape for any Lutaml::Model::Serializable subclass
+        # generated by ANY schema compiler. There is no per-format
+        # variant — adding a new xml directive here propagates to every
+        # compiler that uses this template. Consumed by:
+        #   - Lutaml::Model::Schema::Renderers::Model
+        #     (renders XSD complex types / groups and RNG generated classes)
+        #
+        # Required binding methods (renderer must expose all of these,
+        # returning "" / nil / false for inapplicable sections):
+        #
+        #   from ClassBoilerplate:
+        #     module_opening, module_closing,
+        #     registration_methods, registration_execution,
+        #     boilerplate_indent_str
+        #
+        #   identity / parent:
+        #     rendered_class_name                 String — CamelCase
+        #     serializable_class_parent           String — e.g. "Lutaml::Model::Serializable"
+        #
+        #   header:
+        #     serializable_class_required_files   String — `require_relative` lines or ""
+        #     serializable_class_documentation    String — doc comment block or ""
+        #
+        #   body — attribute declarations:
+        #     serializable_class_attributes       String — `attribute :foo, :bar` lines
+        #     serializable_class_imports          String — `import_model :foo` lines or ""
+        #
+        #   body — xml block:
+        #     xml_root_directive_line             String or nil — `element "X"` /
+        #                                         `type_name "X"` / nil to skip
+        #     xml_namespace_line                  String or nil — `namespace ClassName` / nil
+        #     xml_mixed_content?                  Boolean — emit `mixed_content`
+        #     xml_text_content?                   Boolean — emit `map_content to: :content`
+        #     xml_attribute_mappings              String — `map_element`/`map_attribute` lines
+        #     xml_extra_mappings                  String — extra mapping lines or ""
+        #                                         (e.g. XSD's simple_content tail)
+        # ----------------------------------------------------------------
+        SERIALIZABLE_CLASS = ERB.new(<<~TMPL, trim_mode: "-")
+          # frozen_string_literal: true
+
+          require "lutaml/model"
+          <%= serializable_class_required_files -%>
+          <%= module_opening -%>
+          <%= serializable_class_documentation -%>
+          class <%= rendered_class_name %> < <%= serializable_class_parent %>
+          <%= serializable_class_attributes -%>
+          <%= serializable_class_imports -%>
+          <%= "\n" if serializable_class_attributes.length.positive? || serializable_class_imports.length.positive? -%>
+          <%= boilerplate_indent_str %>xml do
+          <%- if xml_root_directive_line -%>
+          <%= boilerplate_indent_str * 2 %><%= xml_root_directive_line %>
+          <%- end -%>
+          <%- if xml_namespace_line -%>
+          <%= boilerplate_indent_str * 2 %><%= xml_namespace_line %>
+          <%- end -%>
+          <%- if xml_mixed_content? -%>
+          <%= boilerplate_indent_str * 2 %>mixed_content
+          <%- end -%>
+          <%- if xml_text_content? -%>
+          <%= boilerplate_indent_str * 2 %>map_content to: :content
+          <%- end -%>
+          <%= xml_attribute_mappings -%>
+          <%= xml_extra_mappings -%>
+          <%= boilerplate_indent_str %>end
+          <%= registration_methods -%>
+          end
+          <%= module_closing -%>
+          <%= registration_execution -%>
+        TMPL
+
+        # XmlNamespace subclass. Consumed by:
+        #   - Lutaml::Model::Schema::Renderers::Namespace
+        # Binding: module_opening, module_closing, class_name, uri, prefix_default.
+        XML_NAMESPACE = ERB.new(<<~TMPL, trim_mode: "-")
+          # frozen_string_literal: true
+
+          require "lutaml/model"
+
+          <%= module_opening -%>
+          # Namespace: <%= uri %>
+          class <%= class_name %> < Lutaml::Xml::W3c::XmlNamespace
+            uri <%= uri.inspect %>
+            prefix_default <%= prefix_default.inspect %>
+          <%- if element_form_default_line -%>
+            <%= element_form_default_line %>
+          <%- end -%>
+          end
+          <%= module_closing -%>
+        TMPL
+
+        # Restricted simple-type subclass (cast method that mutates options
+        # with facets then delegates to super). Consumed by:
+        #   - Lutaml::Model::Schema::Renderers::RestrictedType
+        # Binding: module_opening, module_closing, registration_methods,
+        # registration_execution, rendered_class_name, parent_class,
+        # xml_namespace_line, restricted_simple_type_required_files,
+        # restricted_simple_type_cast_body, boilerplate_indent_str.
+        RESTRICTED_SIMPLE_TYPE = ERB.new(<<~TMPL, trim_mode: "-")
+          # frozen_string_literal: true
+          require "lutaml/model"
+          <%= restricted_simple_type_required_files -%>
+          <%= module_opening -%>
+          class <%= rendered_class_name %><%= " < \#{parent_class}" if parent_class %>
+          <%- if xml_namespace_line -%>
+          <%= boilerplate_indent_str %>xml do
+          <%= boilerplate_indent_str * 2 %><%= xml_namespace_line %>
+          <%= boilerplate_indent_str %>end
+          <%- end -%>
+          <%= boilerplate_indent_str %>def self.cast(value, options = {})
+          <%= boilerplate_indent_str * 2 %>return if value.nil?
+
+          <%= restricted_simple_type_cast_body -%>
+          <%= boilerplate_indent_str * 2 %>value = super(value, options)
+          <%= boilerplate_indent_str * 2 %>value
+          <%= boilerplate_indent_str %>end
+          <%= registration_methods -%>
+          end
+          <%= module_closing -%>
+          <%= registration_execution -%>
+        TMPL
+
+        # Lutaml::Model::Type::Value union subclass. Consumed by:
+        #   - Lutaml::Model::Schema::Renderers::Union
+        # `union_cast_body` selects the cast strategy from the spec
+        # (XSD: `||`-chained resolve_type; RNG: each+rescue).
+        UNION_TYPE = ERB.new(<<~TMPL, trim_mode: "-")
+          # frozen_string_literal: true
+          require "lutaml/model"
+          <%= union_required_files -%>
+          <%= module_opening -%>
+          class <%= rendered_class_name %> < Lutaml::Model::Type::Value
+          <%= boilerplate_indent_str %>def self.cast(value, options = {})
+          <%= boilerplate_indent_str * 2 %>return if value.nil?
+
+          <%= union_cast_body -%>
+          <%= boilerplate_indent_str %>end
+          <%= registration_methods -%>
+          end
+          <%= module_closing -%>
+          <%= registration_execution -%>
+        TMPL
+      end
+    end
+  end
+end