expressir 2.4.31-arm-linux → 2.4.36-arm-linux

data/lib/expressir/p21/builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # Turns a {Grammar} capture tree into a {Population}.
+    module Builder
+      module_function
+
+      def build(tree)
+        header = build_header(tree[:header_section])
+        instances = build_instances(tree[:data_section])
+        Population.new(header: header, instances: instances)
+      end
+
+      def build_header(section)
+        Array(section[:header_entity]).each_with_object({}) do |entry, hash|
+          record = entry[:simple_record]
+          hash[record_keyword(record)] = record_params(record)
+        end
+      end
+
+      def build_instances(section)
+        list = section[:instance_list]
+        entries = list.is_a?(Array) ? list : [list]
+        entries.each_with_object({}) do |entry, hash|
+          if (complex = entry[:complex_entity_instance])
+            hash[instance_id(complex)] = build_complex(complex)
+          elsif (simple = entry[:simple_entity_instance])
+            record = simple[:simple_record]
+            hash[instance_id(simple)] = Record.new(record_keyword(record),
+                                                   record_params(record))
+          end
+        end
+      end
+
+      def instance_id(body)
+        "##{body[:entity_instance_name].to_s.delete_prefix('#')}"
+      end
+
+      def build_complex(body)
+        subs = body[:subsuper_record]
+        subs = [subs] unless subs.is_a?(Array)
+        records = subs.map do |sub|
+          record = sub[:simple_record]
+          Record.new(record_keyword(record), record_params(record))
+        end
+        ComplexRecord.new(records)
+      end
+
+      def record_keyword(record)
+        record[:keyword].to_s.delete_prefix("!")
+      end
+
+      # A parameter_list capture is a hash when there is a single parameter
+      # and an array of {parameter: ...} entries otherwise.
+      def parameter_list_values(capture)
+        return [] if capture.nil?
+
+        entries = capture.is_a?(Array) ? capture : [capture]
+        entries.map { |entry| build_value(entry[:parameter]) }
+      end
+
+      def record_params(record)
+        parameter_list_values(record[:parameter_list])
+      end
+
+      def build_value(param)
+        if (typed = param[:typed_parameter])
+          TypedValue.new(typed[:keyword].to_s.delete_prefix("!"),
+                         parameter_list_values(typed[:parameter_list]))
+        elsif param[:parameter_list]
+          parameter_list_values(param[:parameter_list])
+        elsif param[:entity_instance_name]
+          "##{param[:entity_instance_name].to_s.delete_prefix('#')}"
+        elsif param[:number_literal]
+          text = param[:number_literal].to_s
+          text.match?(/[.Ee]/) ? text.to_f : text.to_i
+        elsif param[:enumeration]
+          Enumeration.new(param[:enumeration].to_s.delete_prefix(".").delete_suffix("."))
+        elsif param[:binary_literal]
+          Binary.new(param[:binary_literal].to_s.delete_prefix('"').delete_suffix('"'))
+        elsif param[:string_literal]
+          param[:string_literal].to_s[1..-2].gsub("''", "'")
+        elsif param[:unset]
+          :unset
+        elsif param[:derived]
+          :derived
+        end
+      end
+    end
+  end
+end

data/lib/expressir/p21/grammar.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "parsanol"
+
+module Expressir
+  module P21
+    # ISO 10303-21 exchange-structure grammar (TODO.eengine/06 step 1).
+    # Parses the HEADER section and the DATA section's instance list
+    # into a capture tree; {Expressir::P21::PopulationBuilder} turns
+    # the tree into a {Expressir::P21::Population}.
+    #
+    # Reference: ISO 10303-21 exchange structure grammar
+    # (`~/src/mn/iso-10303-detached-docs/sources/iso-10303-21*/`);
+    # scope ladder in TODO.eengine/06 — the supported subset is the
+    # header FILE_* entities plus simple/complex data instances with
+    # lists, typed parameters, references, enumerations, binaries,
+    # strings, unset ($) and derived (*).
+    class Grammar < Parsanol::Parser
+      root(:exchange_structure)
+
+      rule(:comment) { str("/*") >> (str("*/").absent? >> any).repeat >> str("*/") }
+      rule(:ws?) { (match[" \t\r\n"] | comment).repeat }
+      rule(:ws1) { (match[" \t\r\n"] | comment).repeat(1) }
+      rule(:keyword) { match["!"].maybe >> match["A-Za-z0-9_"].repeat(1) }
+      rule(:entity_instance_name) { str("#") >> match["0-9"].repeat(1) }
+
+      rule(:string_literal) do
+        # ISO 10303-21: doubled quotes are escaped quotes
+        str("'") >> ((str("'").absent? >> any) | str("''")).repeat >> str("'")
+      end
+      rule(:binary_literal) { str('"') >> match["0-9A-Fa-f"].repeat >> str('"') }
+      rule(:enumeration) { str(".") >> match["A-Za-z0-9_"].repeat(1) >> str(".") }
+      rule(:unset) { str("$") }
+      rule(:derived) { str("*") }
+
+      rule(:parameter_list) do
+        str("(") >> ws? >>
+          (parameter.as(:parameter) >>
+            (str(",") >> ws? >> parameter.as(:parameter)).repeat).maybe >>
+          str(")") >> ws?
+      end
+
+      rule(:typed_parameter) do
+        keyword.as(:keyword) >> ws? >> parameter_list.as(:parameter_list)
+      end
+      rule(:list_parameter) { parameter_list }
+
+      rule(:number_literal) do
+        match["+-"].maybe >> match["0-9"].repeat(1) >>
+          (str(".") >> match["0-9"].repeat(1)).maybe >>
+          (match["Ee"] >> match["+-"].maybe >> match["0-9"].repeat(1)).maybe
+      end
+
+      rule(:parameter) do
+        typed_parameter.as(:typed_parameter) |
+          list_parameter.as(:parameter_list) |
+          entity_instance_name.as(:entity_instance_name) |
+          number_literal.as(:number_literal) |
+          enumeration.as(:enumeration) |
+          binary_literal.as(:binary_literal) |
+          string_literal.as(:string_literal) |
+          unset.as(:unset) | derived.as(:derived)
+      end
+
+      rule(:simple_record) do
+        keyword.as(:keyword) >> ws? >> parameter_list.as(:parameter_list)
+      end
+
+      rule(:subsuper_record) do
+        str("(") >> ws? >> simple_record.as(:simple_record).repeat(1) >>
+          str(")") >> ws?
+      end
+
+      rule(:simple_entity_instance) do
+        (entity_instance_name.as(:entity_instance_name) >> ws? >>
+          str("=") >> ws? >> simple_record.as(:simple_record) >>
+          str(";") >> ws?).as(:simple_entity_instance)
+      end
+      rule(:complex_entity_instance) do
+        (entity_instance_name.as(:entity_instance_name) >> ws? >>
+          str("=") >> ws? >> subsuper_record.as(:subsuper_record) >>
+          str(";") >> ws?).as(:complex_entity_instance)
+      end
+      rule(:entity_instance) { complex_entity_instance | simple_entity_instance }
+
+      rule(:header_entity) do
+        simple_record.as(:simple_record) >> str(";") >> ws?
+      end
+      rule(:header_section) do
+        str("HEADER;") >> ws? >> header_entity.repeat(1).as(:header_entity) >>
+          str("ENDSEC;") >> ws?
+      end
+      rule(:data_section) do
+        str("DATA;") >> ws? >>
+          (str("(") >> ws? >> parameter >> str(");") >> ws?).maybe >>
+          entity_instance.repeat.as(:instance_list) >>
+          str("ENDSEC;") >> ws?
+      end
+      rule(:exchange_structure) do
+        ws? >> str("ISO-10303-21;") >> ws? >>
+          header_section.as(:header_section) >>
+          data_section.as(:data_section) >>
+          str("END-ISO-10303-21;") >> ws?
+      end
+    end
+  end
+end

data/lib/expressir/p21/parser.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # Facade: parse an ISO 10303-21 exchange structure into a
+    # {Population} (TODO.eengine/06 step 1).
+    module Parser
+      module_function
+
+      def parse(source)
+        tree = Grammar.new.parse(source)
+        Builder.build(tree)
+      end
+    end
+  end
+end

data/lib/expressir/p21/population.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # A parsed ISO 10303-21 exchange structure (TODO.eengine/06).
+    # `header`   — Hash: keyword => parameters (Array of values).
+    # `instances`— Hash: "#id" => Record.
+    #
+    # Values: String (string literal), Integer (reference id, keyed as
+    # "#id" in instances), Expressir::P21::Enumeration,
+    # Expressir::P21::Binary, Expressir::P21::TypedValue,
+    # Expressir::P21::ComplexRecord, :unset, :derived, or nested
+    # Arrays for lists.
+    class Population
+      attr_reader :header, :instances
+
+      def initialize(header: {}, instances: {})
+        @header = header
+        @instances = instances
+      end
+    end
+
+    # A data-section instance: `#12 = KEYWORD(param, ...) ;`
+    Record = Struct.new(:keyword, :params)
+
+    # `#21 = (A(...) B(...))` — complex entity instance.
+    ComplexRecord = Struct.new(:records)
+
+    TypedValue = Struct.new(:keyword, :value)
+
+    Enumeration = Struct.new(:name)
+
+    Binary = Struct.new(:hex)
+  end
+end

data/lib/expressir/p21/validator.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Expressir
+  module P21
+    # Validates a {Population} against a loaded schema
+    # (TODO.eengine/06 step 2). Single-schema scope: instance keywords
+    # must be declared in the given schema; USE/REFERENCE visibility is
+    # a later ladder step.
+    #
+    # Mapping follows ISO 10303-21 clause 12: derived attributes are
+    # not mapped (a supertype attribute redeclared as DERIVED keeps its
+    # slot, valued `*`), inverse attributes are not mapped, and the
+    # value order is supertype attributes first.
+    module Validator
+      Note = Struct.new(:id, :severity, :instance, :message, keyword_init: true)
+
+      module_function
+
+      # `short_names` maps exchange-structure short names (ISO 10303-21,
+      # clause 12.3) to schema entity names, e.g. {"CPT" => "cartesian_point"}.
+      def validate(population, schema, short_names: nil)
+        short_names = short_names&.transform_keys(&:downcase)
+        notes = []
+        check_file_schema(notes, population, schema)
+        population.instances.each do |id, instance|
+          if instance.is_a?(ComplexRecord)
+            check_complex(notes, schema, population, id, instance, short_names)
+          else
+            check_simple(notes, schema, population, id, instance, short_names)
+          end
+        end
+        notes
+      end
+
+      def errors(notes)
+        notes.select { |note| note.severity == :error }
+      end
+
+      def warnings(notes)
+        notes.select { |note| note.severity == :warning }
+      end
+
+      def valid?(notes)
+        errors(notes).empty?
+      end
+
+      def note!(notes, id, severity, instance, message)
+        notes << Note.new(id: id, severity: severity, instance: instance,
+                          message: message)
+      end
+
+      def check_file_schema(notes, population, schema)
+        declared = Array(population.header["FILE_SCHEMA"]).flatten.first
+        return unless declared && schema.id
+        return if declared.downcase == schema.id.downcase
+
+        note!(notes, :p21_schema_mismatch, :warning, nil,
+              "FILE_SCHEMA '#{declared}' does not match schema '#{schema.id}'")
+      end
+
+      def check_simple(notes, schema, population, id, record, short_names)
+        entity = find_entity(schema, record.keyword, short_names)
+        unless entity
+          note!(notes, :p21_unknown_entity, :error, id,
+                "#{record.keyword} is not declared in schema '#{schema.id}'")
+          return
+        end
+
+        check_params(notes, schema, population, id, record.params,
+                     mapped_slots(entity))
+      end
+
+      def check_complex(notes, schema, population, id, complex, short_names)
+        pairs = complex.records.filter_map do |record|
+          entity = find_entity(schema, record.keyword, short_names)
+          unless entity
+            note!(notes, :p21_unknown_entity, :error, id,
+                  "#{record.keyword} is not declared in schema '#{schema.id}'")
+            next nil
+          end
+
+          [record, entity]
+        end
+        return if pairs.empty?
+
+        check_clique(notes, id, pairs.map { |_, entity| entity })
+        pairs.each do |record, entity|
+          slots = explicit_attributes(entity).map { |attr| [attr, false] }
+          check_params(notes, schema, population, id, record.params, slots)
+        end
+      end
+
+      # A complex instance's records must form a valid supertype graph
+      # path: they share at least one common supertype.
+      def check_clique(notes, id, entities)
+        common = closure_keys(entities.first)
+        entities.drop(1).each { |entity| common &= closure_keys(entity) }
+        return unless common.empty?
+
+        note!(notes, :p21_complex_clique, :error, id,
+              "#{id}: complex records share no common supertype")
+      end
+
+      def closure_keys(entity)
+        keys = entity.supertype_closure.filter_map { |e| e.id&.downcase }
+        keys << entity.id&.downcase
+      end
+
+      # Part 21 value order: supertype attributes first; an attribute
+      # redeclared as DERIVED in the entity keeps its inherited slot,
+      # valued `*` (12.2.6).
+      def mapped_slots(entity)
+        own_derived_keys = own_derived_attributes(entity)
+          .filter_map { |attr| attr.id&.downcase }
+        inherited = entity.supertype_closure.flat_map do |supertype|
+          explicit_attributes(supertype)
+        end
+        inherited.map do |attr|
+          [attr, own_derived_keys.include?(attr.id&.downcase)]
+        end + explicit_attributes(entity).map { |attr| [attr, false] }
+      end
+
+      def check_params(notes, schema, population, id, params, slots)
+        if params.size != slots.size
+          note!(notes, :p21_arity_mismatch, :error, id,
+                "#{id}: #{params.size} values for #{slots.size} mapped attributes")
+        end
+
+        slots.zip(params).each do |(attr, derived_slot), value|
+          next if value.nil?
+
+          if derived_slot
+            next if value == :derived
+
+            note!(notes, :p21_derived_slot, :error, id,
+                  "#{id}: attribute '#{attr.id}' redeclared DERIVED must be '*'")
+            next
+          end
+
+          check_value(notes, schema, population, id, attr, value)
+        end
+      end
+
+      def check_value(notes, schema, population, id, attr, value)
+        case value
+        when String
+          return unless value.match?(/\A#\d+\z/)
+
+          return if population.instances.key?(value)
+
+          note!(notes, :p21_unknown_reference, :error, id,
+                "#{id}: reference #{value} has no instance")
+        when :derived
+          note!(notes, :p21_derived_value, :error, id,
+                "#{id}: '*' outside a derived slot")
+        when TypedValue
+          return if find_entity(schema, value.keyword) || find_type(schema, value.keyword)
+
+          note!(notes, :p21_unknown_typed_keyword, :error, id,
+                "#{id}: typed parameter '#{value.keyword}' does not resolve")
+        when Enumeration
+          items = enumeration_items(schema, attr)
+          return unless items
+
+          names = items.filter_map { |item| item.id&.downcase }
+          return if names.include?(value.name.downcase)
+
+          note!(notes, :p21_enum_value, :error, id,
+                "#{id}: .#{value.name}. is not in attribute '#{attr.id}' enumeration")
+        when Array
+          value.each { |item| check_value(notes, schema, population, id, attr, item) }
+        end
+      end
+
+      def explicit_attributes(entity)
+        Array(entity.attributes)
+          .select { |attr| attr.instance_of?(Model::Declarations::Attribute) }
+      end
+
+      def own_derived_attributes(entity)
+        Array(entity.attributes)
+          .select { |attr| attr.instance_of?(Model::Declarations::DerivedAttribute) }
+      end
+
+      def find_entity(schema, keyword, short_names = nil)
+        key = keyword.downcase
+        Array(schema.entities).find { |entity| entity.id&.downcase == key } ||
+          resolve_short_name(schema, key, short_names)
+      end
+
+      def resolve_short_name(schema, key, short_names)
+        return nil unless short_names.is_a?(Hash) && short_names[key]
+
+        find_entity(schema, short_names[key], nil)
+      end
+
+      def find_type(schema, keyword)
+        Array(schema.types).find { |type| type.id&.downcase == keyword.downcase }
+      end
+
+      def enumeration_items(schema, attr)
+        type = attr&.type
+        return Array(type.items) if type.is_a?(Model::DataTypes::Enumeration)
+
+        return nil unless type.is_a?(Model::References::SimpleReference)
+
+        declaration = find_type(schema, type.id.to_s)
+        underlying = declaration&.underlying_type
+        underlying.is_a?(Model::DataTypes::Enumeration) ? Array(underlying.items) : nil
+      end
+    end
+  end
+end

data/lib/expressir/p21.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Expressir
+  # ISO 10303-21 exchange-structure support (TODO.eengine/06).
+  module P21
+    autoload :Population, "#{__dir__}/p21/population"
+    autoload :Record, "#{__dir__}/p21/population"
+    autoload :ComplexRecord, "#{__dir__}/p21/population"
+    autoload :TypedValue, "#{__dir__}/p21/population"
+    autoload :Enumeration, "#{__dir__}/p21/population"
+    autoload :Binary, "#{__dir__}/p21/population"
+    autoload :Grammar, "#{__dir__}/p21/grammar"
+    autoload :Builder, "#{__dir__}/p21/builder"
+    autoload :Validator, "#{__dir__}/p21/validator"
+    autoload :Parser, "#{__dir__}/p21/parser"
+  end
+end

data/lib/expressir/reference/grammar_crosswalk.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Expressir
+  module Reference
+    # Rule-by-rule cross-walk between the parsanol grammar and the
+    # ISO 10303-11 Annex A/B productions. The mapping data is generated
+    # by `rake reference:crosswalk`; the spec fails when a grammar rule
+    # has no row or the rendered guide is stale.
+    class GrammarCrosswalk
+      DATA_PATH = File.expand_path("grammar_crosswalk.yml", __dir__)
+      GRAMMAR_RULE = /rule\(:(\w+)/
+      PRODUCTION_STATUSES = %w[aligned decomposed].freeze
+
+      class << self
+        def data
+          @data ||= YAML.load_file(DATA_PATH)
+        end
+
+        def grammar_path
+          Expressir.root_path.join(data.dig("source", "grammar"))
+        end
+
+        def grammar_rules
+          File.read(grammar_path).scan(GRAMMAR_RULE).flatten.uniq.sort
+        end
+
+        def rows
+          data["rules"]
+        end
+
+        def annex_without_rule
+          data["annex_without_rule"]
+        end
+
+        def statuses
+          data["statuses"]
+        end
+
+        # Returns the list of inconsistencies; empty means in sync.
+        def validate
+          errors = []
+          declared = rows.map { |row| row["rule"] }
+          missing = grammar_rules - declared
+          unknown = declared - grammar_rules
+          duplicates = declared.tally.select { |_, count| count > 1 }.keys
+          errors << "grammar rules without a cross-walk row: #{missing.join(', ')}" if missing.any?
+          errors << "cross-walk rows without a grammar rule: #{unknown.join(', ')}" if unknown.any?
+          errors << "duplicate cross-walk rows: #{duplicates.join(', ')}" if duplicates.any?
+
+          rows.each do |row|
+            status = row["status"]
+            unless statuses.key?(status)
+              errors << "#{row['rule']}: unknown status '#{status}'"
+            end
+            if PRODUCTION_STATUSES.include?(status) && !row["production"]
+              errors << "#{row['rule']}: #{status} row needs a production"
+            end
+          end
+          errors
+        end
+
+        def render_adoc
+          lines = [
+            "= Grammar cross-walk",
+            "",
+            "// Generated by `rake reference:crosswalk` from",
+            "// #{data.dig('source', 'grammar')} and the Annex A snapshot.",
+            "// Do not edit by hand; the reference spec fails when this file is stale.",
+            "",
+            "== Purpose",
+            "",
+            "Every parsanol grammar rule is mapped to the ISO 10303-11:2004",
+            "Annex A production it implements. Divergences from the standard",
+            "grammar are classified with one of these statuses:",
+            "",
+            *statuses.map { |name, description| "* `#{name}` — #{description}" },
+            "",
+            "== Rules",
+            "",
+            '[cols="2,3,1,4", options="header"]',
+            "|===",
+            "| Parsanol rule | Annex A production | Status | Note",
+            "",
+            *rows.map { |row| rule_row(row) },
+            "|===",
+            "",
+            "== Annex A productions without a dedicated rule",
+            "",
+            "These productions are handled by supporting code rather than a",
+            "grammar rule:",
+            "",
+            '[cols="3,1,5", options="header"]',
+            "|===",
+            "| Annex A production | Status | Handled by",
+            "",
+            *annex_without_rule.map { |row| annex_row(row) },
+            "|===",
+            "",
+          ]
+          lines.join("\n")
+        end
+
+        private
+
+        def rule_row(row)
+          note = row["literal"] ? "literal `#{row['literal']}`" : row["note"]
+          "| `#{row['rule']}` | #{cell(row['production'])} | #{row['status']} | #{cell(note)}"
+        end
+
+        def annex_row(row)
+          "| `#{row['production']}` | #{row['status']} | #{cell(row['note'])}"
+        end
+
+        def cell(text)
+          text.to_s.gsub("|", "\\|")
+        end
+      end
+    end
+  end
+end