lutaml-lml 0.1.0

data/lib/lutaml/lml/document_builder.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class DocumentBuilder
+      # Default registry: builder keys → LML model classes.
+      # Callers needing a different mapping can pass their own registry
+      # to `new`; this constant documents the default composition.
+      DEFAULT_REGISTRY = {
+        document: ::Lutaml::Lml::Document,
+        package: ::Lutaml::Lml::Package,
+        class: ::Lutaml::Lml::UmlClass,
+        enum: ::Lutaml::Lml::Enum,
+        data_type: ::Lutaml::Lml::DataType,
+        diagram: ::Lutaml::Lml::Diagram,
+        attribute: ::Lutaml::Lml::TopElementAttribute,
+        cardinality: ::Lutaml::Lml::Cardinality,
+        association: ::Lutaml::Lml::Association,
+        operation: ::Lutaml::Lml::Operation,
+        constraint: ::Lutaml::Lml::Constraint,
+        value: ::Lutaml::Lml::Value,
+        view_import: ::Lutaml::Lml::ViewImport,
+        view_filter: ::Lutaml::Lml::ViewFilter
+      }.freeze
+
+      attr_reader :registry
+
+      def initialize(registry = DEFAULT_REGISTRY)
+        @registry = registry
+      end
+
+      FACTORY_KEYS = %i[
+        document package class enum data_type diagram view_import view_filter
+        attribute association operation constraint value cardinality
+      ].freeze
+
+      MEMBER_KEY_MAP = {
+        packages: :package,
+        classes: :class,
+        enums: :enum,
+        data_types: :data_type,
+        diagrams: :diagram,
+        view_imports: :view_import,
+        attributes: :attribute,
+        associations: :association,
+        operations: :operation,
+        constraints: :constraint,
+        values: :value
+      }.freeze
+
+      FACTORY_KEYS.each do |key|
+        define_method(:"build_#{key}") { |hash| build(key, hash) }
+      end
+
+      def build(key, hash)
+        @registry.fetch(key).new.tap { |model| set_model(model, hash) }
+      end
+
+      private
+
+      def set_model(model, hash)
+        hash = build_members(model, hash)
+        set_model_attributes(model, hash)
+      end
+
+      def set_model_attributes(model, hash)
+        hash.each do |key, value|
+          value = sanitize_definition(value) if key == :definition
+          apply_attribute(model, key, value)
+        end
+      end
+
+      def build_members(model, hash)
+        members = hash.delete(:members)
+        members.to_a.each do |member_hash|
+          add_members(model, member_hash)
+          set_model_attributes(model, member_hash)
+        end
+        hash
+      end
+
+      def sanitize_definition(value)
+        value.to_s.gsub(/\\}/, '}').gsub(/\\{/, '{')
+             .split("\n").map(&:strip).join("\n")
+      end
+
+      def apply_attribute(model, key, value)
+        return unless model.class.attributes.key?(key.to_sym)
+
+        if model.class.attributes[key.to_sym].options[:collection]
+          append_collection(model, key, value)
+        else
+          model.public_send("#{key}=", value)
+        end
+      end
+
+      def append_collection(model, key, value)
+        values = model.public_send(key).to_a
+        value.is_a?(Array) ? values.concat(value) : values << value
+        model.public_send("#{key}=", values)
+      end
+
+      def add_members(model, hash)
+        MEMBER_KEY_MAP.each do |plural_key, singular_key|
+          data = hash.delete(plural_key)
+          next if data.nil?
+
+          member = build(singular_key, data)
+          ensure_collection(model, plural_key) << member
+        end
+
+        remap_filter_keys(hash, model)
+      end
+
+      def ensure_collection(model, key)
+        model.public_send(key) || begin
+          model.public_send("#{key}=", [])
+          model.public_send(key)
+        end
+      end
+
+      def remap_filter_keys(hash, model)
+        return unless model.is_a?(Document)
+
+        if hash.key?(:show_list)
+          hash[:show_filter] = build_view_filter(hash.delete(:show_list))
+        end
+        if hash.key?(:hide_list)
+          hash[:hide_filter] = build_view_filter(hash.delete(:hide_list))
+        end
+      end
+
+      def build_view_filter(entity_names)
+        names = entity_names.is_a?(Array) ? entity_names : [entity_names]
+        ViewFilter.new(entity_names: names.map(&:to_s))
+      end
+    end
+  end
+end

data/lib/lutaml/lml/executor/adapter_helpers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class Executor
+      # Shared helpers for the I/O adapters. Both CsvAdapter and XmlAdapter
+      # need to:
+      #
+      #   - resolve a `map_to` reference to a compiled class
+      #   - look up attribute values by name in an import/export definition
+      #   - find the compiled class that an instance belongs to (for export)
+      #
+      # This module owns those three concerns so each adapter can stay
+      # focused on its format-specific I/O.
+      module AdapterHelpers
+        # Returns the compiled class referenced by the `map_to` attribute,
+        # or nil if no such attribute or no such compiled class.
+        def resolve_target_class(attributes, compiled)
+          attr = find_attribute(attributes, "map_to")
+          return nil unless attr
+
+          compiled[attr.value.to_s]
+        end
+
+        # Returns the string value of the named attribute, or nil.
+        def attribute_value(attributes, name)
+          attr = find_attribute(attributes, name)
+          attr ? attr.value.to_s : nil
+        end
+
+        # Walks an attributes collection looking for an entry whose
+        # `.name` matches `name`. Returns the attribute, or nil.
+        def find_attribute(attributes, name)
+          Array(attributes).find { |a| a.name == name }
+        end
+
+        # Returns [class_name, klass] for the first compiled class whose
+        # instances include `first_instance`, or nil if no match.
+        def find_class_for_instance(first_instance, compiled)
+          compiled.find { |_name, klass| first_instance.is_a?(klass) }
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/executor/condition_evaluator.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class Executor
+      # Evaluates collection validation conditions against instance data.
+      #
+      # Conditions are simple DSL strings like "count >= 3" or
+      # "all? { |i| i.components.count > 0 }". The evaluator parses a safe
+      # subset of forms — it never calls `eval` on arbitrary Ruby.
+      #
+      # Supported condition forms:
+      #   "count >= N"                      — collection size comparison
+      #   "count == N", "count <= N", etc.
+      #   "all? { |i| i.path OP literal }"  — every instance matches
+      #   "any? { |i| i.path OP literal }"  — at least one instance matches
+      #
+      # The block predicate supports a single comparison of an instance
+      # attribute path (e.g. `i.components.count`, `i.name`) against a
+      # literal (number, quoted string, true/false/nil) using one of
+      # `>, >=, <, <=, ==, !=`.
+      #
+      class ConditionEvaluator
+        ConditionError = Class.new(StandardError)
+
+        BLOCK_PREFIX = /\A\s*(all|any)\?/.freeze
+        BLOCK_VAR = /\A\s*\|(\w+)\|/.freeze
+        COMPARISON = /\A\s*(.+?)\s*(>=|<=|==|!=|>|<)\s*(.+?)\s*\z/.freeze
+
+        # Evaluate all validation conditions against a collection of instances.
+        # Returns an array of error strings (empty if all pass).
+        def self.evaluate(collection, instances)
+          return [] unless collection.validations&.any?
+          return [] unless collection.is_a?(Collection)
+
+          new(instances).evaluate_all(collection.validations)
+        end
+
+        def initialize(instances)
+          @instances = instances
+        end
+
+        def evaluate_all(conditions)
+          conditions.filter_map do |condition|
+            evaluate(condition)
+          rescue ConditionError => e
+            "Validation failed: #{e.message}"
+          end
+        end
+
+        private
+
+        def evaluate(condition)
+          return evaluate_block(condition) if condition.match?(/\A\s*(all|any)\?\s*\{/)
+          return evaluate_count(condition) if condition.match?(/\bcount\s*[<>=]+/)
+
+          raise ConditionError, "Unsupported condition: #{condition}"
+        end
+
+        def evaluate_count(condition)
+          match = condition.match(/\bcount\s*(>=|<=|==|>|<)\s*(\d+)/)
+          raise ConditionError, "Invalid count condition: #{condition}" unless match
+
+          operator = match[1]
+          expected = match[2].to_i
+          actual = @instances.length
+
+          compare(actual, operator, expected) ||
+            raise(ConditionError, "#{condition} (got #{actual})")
+          nil
+        end
+
+        def evaluate_block(condition)
+          quantifier, predicate = parse_block(condition)
+          raise ConditionError, "Invalid block condition: #{condition}" if quantifier.nil?
+
+          comparator = build_predicate(predicate)
+          satisfied = @instances.public_send("#{quantifier}?") do |instance|
+            comparator.call(instance)
+          end
+
+          return nil if satisfied
+
+          raise ConditionError, "#{condition} (failed for #{quantifier == "all" ? "at least one" : "all"} instance)"
+        end
+
+        def parse_block(condition)
+          stripped = condition.strip
+          prefix = stripped.match(BLOCK_PREFIX)
+          return [nil, nil] unless prefix
+
+          open_idx = stripped.index("{")
+          close_idx = stripped.rindex("}")
+          return [nil, nil] unless open_idx && close_idx && close_idx > open_idx
+
+          body = stripped[(open_idx + 1)...close_idx].strip
+          var_match = body.match(BLOCK_VAR)
+          return [nil, nil] unless var_match
+
+          predicate = body[var_match[0].length..].strip
+          [prefix[1], predicate]
+        end
+
+        # Parses a single comparison predicate "i.path OP literal" into a
+        # callable that, given an instance, returns true/false.
+        def build_predicate(predicate)
+          match = predicate.match(COMPARISON)
+          raise ConditionError, "Unsupported predicate: #{predicate}" unless match
+
+          lhs = match[1]
+          operator = match[2]
+          rhs = match[3]
+
+          getter = attribute_getter(lhs)
+          expected = parse_literal(rhs)
+
+          lambda do |instance|
+            actual = getter.call(instance)
+            compare(actual, operator, expected)
+          rescue NoMethodError
+            false
+          end
+        end
+
+        # Parses "i.attr.subattr..." into a callable on an instance.
+        def attribute_getter(path)
+          parts = path.strip.split(".")
+          raise ConditionError, "Invalid attribute path: #{path}" if parts.empty?
+
+          unless parts.first == "i"
+            raise ConditionError, "Block predicate must reference i: #{path}"
+          end
+
+          chain = parts.drop(1)
+          lambda do |instance|
+            chain.reduce(instance) { |receiver, method| receiver.public_send(method) }
+          end
+        end
+
+        # Parses a single literal value from the predicate RHS.
+        def parse_literal(token)
+          stripped = token.strip
+          case stripped
+          when /\A-?\d+\z/              then stripped.to_i
+          when /\A-?\d+\.\d+\z/         then stripped.to_f
+          when /\A".*"\z/, /\A'.*'\z/   then stripped[1..-2]
+          when "true"                   then true
+          when "false"                  then false
+          when "nil", "null"            then nil
+          else
+            raise ConditionError, "Unsupported literal: #{token}"
+          end
+        end
+
+        def compare(actual, operator, expected)
+          case operator
+          when ">=" then actual.to_f >= expected.to_f
+          when "<=" then actual.to_f <= expected.to_f
+          when "==" then actual == expected
+          when "!=" then actual != expected
+          when ">"  then actual.to_f > expected.to_f
+          when "<"  then actual.to_f < expected.to_f
+          else false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/executor/csv_adapter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Lutaml
+  module Lml
+    class Executor
+      # CSV format adapter. Reads CSV files and maps rows to hydrated
+      # compiled-class instances using column mappings from the import
+      # definition. Exports instances back to CSV.
+      #
+      # Registered for format "csv" via FormatAdapter::BUILTIN_ADAPTERS.
+      class CsvAdapter
+        extend AdapterHelpers
+
+        # Read a CSV file and map rows to compiled-class instances.
+        # Returns an array of hydrated objects.
+        #
+        # The import definition's attributes provide column mappings:
+        #   attribute name = "csv_column_header"
+        def self.import(imp, compiled:)
+          return [] unless imp.file
+          return [] unless imp.attributes&.any?
+
+          mappings = build_column_mappings(imp.attributes)
+          target_class = resolve_target_class(imp.attributes, compiled)
+          return [] unless target_class
+
+          path = imp.file
+          return [] unless File.exist?(path)
+
+          rows = CSV.read(path, headers: true)
+          rows.map { |row| build_instance(row, mappings, target_class) }
+        end
+
+        # Write instances to a CSV file.
+        def self.export(exp, instances, compiled:)
+          return if instances.empty?
+
+          path = attribute_value(exp.attributes, "file")
+          return unless path && !path.empty?
+
+          first_instance = instances.first
+          class_name, target_class = find_class_for_instance(first_instance, compiled)
+          return unless target_class
+
+          fields = target_class.attributes.keys
+          rows = instances.map do |inst|
+            fields.map { |f| extract_attribute_value(inst, f) }
+          end
+
+          File.write(path, generate_csv(fields, rows))
+        end
+
+        class << self
+          private
+
+          def build_column_mappings(attributes)
+            Array(attributes).each_with_object({}) do |attr, map|
+              next if attr.name == "map_to"
+              map[attr.name.to_sym] = attr.value.to_s
+            end
+          end
+
+          def build_instance(row, mappings, target_class)
+            attrs = mappings.each_with_object({}) do |(attr_name, col_name), hash|
+              hash[attr_name] = row[col_name]
+            end
+            target_class.new(**attrs)
+          end
+
+          def extract_attribute_value(instance, field_name)
+            instance.public_send(field_name)
+          rescue NoMethodError
+            nil
+          end
+
+          def generate_csv(headers, rows)
+            CSV.generate do |csv|
+              csv << headers
+              rows.each { |row| csv << row }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/executor/format_adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class Executor
+      # Pluggable format adapter registry. Adapters handle the actual
+      # I/O for a given format (CSV, XML, etc.).
+      #
+      # Each adapter must implement:
+      #   .import(imp, compiled:) — read external data, return array of instances
+      #   .export(exp, instances, compiled:) — write instances to external format
+      #
+      module FormatAdapter
+        class AdapterNotFoundError < StandardError; end
+
+        @adapters = {}
+
+        # Built-in adapters resolved by referencing the constant under
+        # Executor, which triggers autoload on first access. External
+        # adapters can still register via `register`.
+        BUILTIN_ADAPTERS = {
+          "csv" => :CsvAdapter,
+          "xml" => :XmlAdapter
+        }.freeze
+
+        # Register an adapter for a format name.
+        def self.register(format_name, adapter)
+          @adapters[format_name.to_s] = adapter
+        end
+
+        # Look up the adapter for a format name.
+        def self.resolve(format_name)
+          key = format_name.to_s
+          return @adapters[key] if @adapters.key?(key)
+
+          builtin = BUILTIN_ADAPTERS[key]
+          if builtin
+            adapter = Executor.const_get(builtin)
+            register(key, adapter)
+            return adapter
+          end
+
+          raise(AdapterNotFoundError,
+            "No adapter registered for format '#{format_name}'")
+        end
+
+        # Returns all registered format names.
+        def self.registered_formats
+          @adapters.keys
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/executor/xml_adapter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "moxml"
+
+module Lutaml
+  module Lml
+    class Executor
+      # XML format adapter. Reads XML files and maps elements to hydrated
+      # compiled-class instances, and writes instances back to XML.
+      #
+      # Registered for format "xml" via FormatAdapter::BUILTIN_ADAPTERS.
+      #
+      # Element-to-attribute mapping is provided by the lutaml-model XML
+      # mapping generated on each compiled class by ModelCompiler. This
+      # adapter only selects which XML elements correspond to records
+      # (via the `where` XPath from the import definition) and hands
+      # each one to `target_class.from_xml` for deserialization.
+      #
+      # Import shape (from LML `import { xml "..." { map_to X; where "/y" } }`):
+      #   - imp.file             = path to XML file
+      #   - imp.attributes       = TopElementAttribute list including:
+      #       map_to: TargetClass (compiled-class key)
+      #       where:  XPath selector for each record element
+      #
+      # Export shape (from LML `export { format xml { file "..."; root "X" } }`):
+      #   - exp.attributes       = TopElementAttribute list including:
+      #       file:      output path
+      #       root:      root tag name (defaults to compiled class name)
+      #       indent:    "true" / "false" (default true)
+      #       encoding:  encoding string (default UTF-8)
+      class XmlAdapter
+        extend AdapterHelpers
+
+        DEFAULT_ENCODING = "UTF-8"
+        DEFAULT_SELECTOR = "/*/*"
+        DEFAULT_ROOT_SUFFIX = "s"
+
+        class << self
+          # Read an XML file and map elements to compiled-class instances.
+          # Returns an array of hydrated objects.
+          def import(imp, compiled:)
+            return [] unless imp.file
+            return [] unless imp.attributes&.any?
+
+            target_class = resolve_target_class(imp.attributes, compiled)
+            return [] unless target_class
+
+            path = imp.file
+            return [] unless File.exist?(path)
+
+            doc = Moxml.parse(File.read(path))
+            selector = attribute_value(imp.attributes, "where") || DEFAULT_SELECTOR
+
+            doc.xpath(selector).map do |element|
+              target_class.from_xml(element.to_xml)
+            end
+          end
+
+          # Write instances to an XML file.
+          def export(exp, instances, compiled:)
+            return if instances.empty?
+
+            path = attribute_value(exp.attributes, "file")
+            return unless path && !path.empty?
+
+            class_name, target_class = find_class_for_instance(instances.first, compiled)
+            return unless target_class
+
+            options = export_options(exp, class_name)
+            File.write(path, build_export_xml(instances, options))
+          end
+
+          private
+
+          def export_options(exp, class_name)
+            {
+              root: attribute_value(exp.attributes, "root") || "#{class_name}#{DEFAULT_ROOT_SUFFIX}",
+              indent: attribute_value(exp.attributes, "indent") != "false",
+              encoding: attribute_value(exp.attributes, "encoding") || DEFAULT_ENCODING
+            }
+          end
+
+          # Builds the export XML by parsing each instance's `to_xml`
+          # output, then grafting its root element under a single
+          # configurable root. lutaml-model handles per-record
+          # serialization via the generated XML mapping.
+          def build_export_xml(instances, options)
+            doc = Moxml.parse("<#{options[:root]}/>")
+            root = doc.root
+
+            instances.each do |inst|
+              record_doc = Moxml.parse(inst.to_xml)
+              root.add_child(record_doc.root)
+            end
+
+            doc.to_xml(indent: options[:indent] ? 2 : 0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/executor.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    # Orchestrates instance data I/O: import external data, validate
+    # collections, and export to external formats.
+    #
+    # Format-specific I/O is delegated to registered adapters via the
+    # FormatAdapter registry. The core executor only handles the
+    # orchestration — it knows *what* to do, adapters know *how*.
+    #
+    # Usage:
+    #   compiled = ModelCompiler.new.compile(models_file)
+    #   doc = Pipeline.call(instances_file, resolve: false)
+    #   instances = Executor.run(doc, compiled: compiled)
+    #
+    class Executor
+      autoload :FormatAdapter, "lutaml/lml/executor/format_adapter"
+      autoload :AdapterHelpers, "lutaml/lml/executor/adapter_helpers"
+      autoload :CsvAdapter, "lutaml/lml/executor/csv_adapter"
+      autoload :XmlAdapter, "lutaml/lml/executor/xml_adapter"
+      autoload :ConditionEvaluator, "lutaml/lml/executor/condition_evaluator"
+
+      attr_reader :compiled
+
+      def initialize(compiled:)
+        @compiled = compiled
+      end
+
+      # Run the full import/validate/export cycle on a parsed document.
+      # Returns an array of hydrated instance objects.
+      def self.run(doc, compiled:)
+        new(compiled: compiled).run(doc)
+      end
+
+      def run(doc)
+        instances = run_imports(doc)
+        validate_collections(doc, instances)
+        run_exports(doc, instances)
+        instances
+      end
+
+      private
+
+      # --- Import ---
+
+      def run_imports(doc)
+        return [] unless doc.instances&.imports&.any?
+
+        doc.instances.imports.flat_map { |imp| import_one(imp) }
+      end
+
+      def import_one(imp)
+        adapter = FormatAdapter.resolve(imp.format_type)
+        adapter.import(imp, compiled: @compiled)
+      rescue FormatAdapter::AdapterNotFoundError
+        []
+      end
+
+      # --- Collection validation ---
+
+      def validate_collections(doc, instances)
+        return unless doc.instances&.collections
+
+        collection = doc.instances.collections
+        return unless collection.is_a?(Collection)
+
+        ConditionEvaluator.evaluate(collection, instances)
+      end
+
+      # --- Export ---
+
+      def run_exports(doc, instances)
+        return unless doc.instances&.exports&.any?
+
+        doc.instances.exports.each do |exp|
+          export_one(exp, instances)
+        end
+      end
+
+      def export_one(exp, instances)
+        adapter = FormatAdapter.resolve(exp.format_type)
+        adapter.export(exp, instances, compiled: @compiled)
+      rescue FormatAdapter::AdapterNotFoundError
+        nil
+      end
+    end
+  end
+end

data/lib/lutaml/lml/format/adapter/document.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    module Format
+      module Adapter
+        class Document < Lutaml::KeyValue::Document; end
+      end
+    end
+  end
+end