lutaml-path 0.1.0 → 0.1.1

data/lib/lutaml/path/abstract_path.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Path
+    # Common supertype for parsed paths. Holds only whether the path is
+    # absolute.
+    #
+    # It deliberately declares neither match? nor segments: InstancePath
+    # cannot honour match? under parse-only, and the two subclasses hold
+    # genuinely different element types (PathSegment answers match?; Step,
+    # which can carry a filter, must not).
+    class AbstractPath
+      attr_reader :absolute
+
+      def initialize(absolute: false)
+        @absolute = absolute
+      end
+
+      def absolute?
+        @absolute
+      end
+    end
+  end
+end

data/lib/lutaml/path/condition.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "path_segment"
+
+module Lutaml
+  module Path
+    # The filter-condition AST.
+    #
+    # Parse-only: these nodes carry structure and render themselves, and
+    # evaluate nothing. They are Structs because there is no behaviour to
+    # justify hand-written classes, and Struct supplies value equality for
+    # free. Data.define would also freeze them, but it is Ruby 3.2+ and this
+    # gem supports 3.0.
+    #
+    # Every node freezes itself, along with any collection or string it owns:
+    # a parsed AST must be immutable, and Struct otherwise hands out public
+    # setters. Freezing the Struct alone is shallow -- `names << "x"` would
+    # still mutate, and would silently invalidate the Struct's own hash.
+    module Condition
+      # A dotted left-hand side: "role.type" -> ["role", "type"].
+      AttributeRef = Struct.new(:names) do
+        def initialize(*) = super.tap { names.each(&:freeze).freeze and freeze }
+
+        # Re-escapes BOTH the dot and the backslash the transformer unescaped.
+        # Escaping only the dot is incomplete: a name ending in a backslash
+        # would render as "a\.b" and re-parse as the single name "a.b".
+        def to_s
+          names.map { |n| n.gsub(/([\\.])/) { "\\#{::Regexp.last_match(1)}" } }.join(".")
+        end
+      end
+
+      # A right-hand literal. `source` is the unescaped lexeme and is never
+      # coerced: pattern? must read it directly so a numeric never reaches
+      # String#match?.
+      Value = Struct.new(:source, :type) do
+        def initialize(*) = super.tap { source.freeze and freeze }
+
+        def pattern?
+          type == :string && source.match?(PathSegment::GLOB_CHARS)
+        end
+
+        # Re-escapes BOTH the quote and the backslash the transformer
+        # unescaped. Escaping only the quote is incomplete: a value ending in a
+        # backslash would render as 'abc\' and its trailing escape would eat
+        # the closing quote.
+        def to_s
+          return source if type == :number
+
+          "'#{source.gsub(/(['\\])/) { "\\#{::Regexp.last_match(1)}" }}'"
+        end
+      end
+
+      Comparison = Struct.new(:lhs, :op, :rhs) do
+        def initialize(*) = super.tap { op.freeze and freeze }
+
+        def to_s = "#{lhs}#{op}#{rhs}"
+      end
+
+      # `literals`, not `values`: a member named `values` would shadow
+      # Struct#values, which returns the member list.
+      Membership = Struct.new(:lhs, :literals) do
+        def initialize(*) = super.tap { literals.freeze and freeze }
+
+        def to_s = "#{lhs} in (#{literals.join(",")})"
+      end
+
+      # `exists` carries no operand, so there is no member to declare. Written
+      # as a plain class rather than a zero-member Struct, which Ruby permits
+      # only from 3.3 while this gem supports >= 3.0.
+      class Existence
+        def initialize = freeze
+
+        def to_s = "exists"
+
+        # instance_of?, not is_a?: exact-class equality is what the Struct gave,
+        # and hash is keyed on the class, so is_a? would make a subclass compare
+        # asymmetrically against a differing hash.
+        def ==(other) = other.instance_of?(self.class)
+        alias eql? ==
+
+        def hash = self.class.hash
+      end
+
+      # && and || are structurally identical, so one type carries both.
+      # to_s ALWAYS parenthesises: parse(p.to_s) == p asserts TREE equality,
+      # and explicit parens make re-association impossible on a re-parse.
+      BinaryOperation = Struct.new(:operator, :left, :right) do
+        def initialize(*) = super.tap { operator.freeze and freeze }
+
+        def to_s = "(#{left} #{operator} #{right})"
+      end
+
+      Negation = Struct.new(:operand) do
+        def initialize(*) = super.tap { freeze }
+
+        def to_s = "!#{operand}"
+      end
+    end
+  end
+end

data/lib/lutaml/path/condition_evaluator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Path
+    # Evaluates Condition AST nodes against a context object. The
+    # condition classes are parse-only by design; this module is the
+    # evaluation half, wired to the same name-resolution the instance
+    # traversal uses.
+    module ConditionEvaluator
+      module_function
+
+      def evaluate(condition, object)
+        case condition
+        when Condition::Comparison then compare(condition, object)
+        when Condition::Membership then membership(condition, object)
+        when Condition::Existence then true
+        when Condition::Negation then !evaluate(condition.operand, object)
+        when Condition::BinaryOperation then evaluate_binary(condition, object)
+        end
+      end
+
+      def evaluate_binary(condition, object)
+        left = evaluate(condition.left, object)
+        right = evaluate(condition.right, object)
+        condition.operator == "&&" ? left && right : left || right
+      end
+
+      def compare(condition, object)
+        actual = read_path(object, condition.lhs)
+        expected = condition.rhs
+        case condition.op
+        when "=" then values_equal(actual, expected)
+        when "!=" then !values_equal(actual, expected)
+        else ordered(actual, condition.op, expected)
+        end
+      end
+
+      def membership(condition, object)
+        actual = read_path(object, condition.lhs)
+        condition.literals.any? { |literal| values_equal(actual, literal) }
+      end
+
+      def values_equal(actual, value)
+        return false if actual.nil?
+
+        value.pattern? ? value_match?(value, actual) : values_coerced_equal(actual, value)
+      end
+
+      def value_match?(value, actual)
+        File.fnmatch(value.source, actual.to_s, File::FNM_EXTGLOB)
+      end
+
+      def values_coerced_equal(actual, value)
+        pair = numeric_pair(actual, value)
+        pair ? pair[0] == pair[1] : actual.to_s == value.source
+      end
+
+      def ordered(actual, operator, value)
+        return false if actual.nil?
+
+        pair = numeric_pair(actual, value)
+        if pair
+          actual = pair[0]
+          value = pair[1]
+        end
+        actual.to_s.public_send(ruby_operator(operator), value.to_s)
+      end
+
+      def ruby_operator(operator)
+        { "=" => :==, "!=" => :"!=", ">=" => :>=, "<=" => :<=, ">" => :>, "<" => :< }.fetch(operator)
+      end
+
+      def numeric_pair(actual, value)
+        numeric(actual) && numeric(value) ? [numeric(actual), numeric(value)] : nil
+      end
+
+      # Accepts both AST literals (Value structs) and raw data values.
+      def numeric(value)
+        raw = value.respond_to?(:source) ? value.source : value
+        Float(raw)
+      rescue ::ArgumentError, ::TypeError
+        nil
+      end
+
+      def read_path(object, attribute_ref)
+        context = [object]
+        attribute_ref.names.each do |name|
+          context = context.flat_map { |node| exact_children(node, name) }
+        end
+        return nil if context.empty?
+
+        context.first
+      end
+
+      def exact_children(node, name)
+        entries(node).filter_map do |child_name, value|
+          next if value.nil?
+          next unless child_name.to_s == name
+
+          value.is_a?(::Enumerable) && !value.is_a?(::Hash) && !value.is_a?(::String) ? value.to_a : value
+        end.flatten(1)
+      end
+
+      def entries(node)
+        Resolver.entries(node)
+      end
+    end
+  end
+end

data/lib/lutaml/path/element_path.rb

@@ -1,24 +1,82 @@
 # frozen_string_literal: true
 
+require_relative "abstract_path"
+
 module Lutaml
   module Path
-    class ElementPath
-      attr_reader :segments, :absolute
+    class ElementPath < AbstractPath
+      attr_reader :segments
 
       def initialize(segments, absolute: false)
+        super(absolute: absolute)
         @segments = Array(segments)
-        @absolute = absolute
       end
 
-      def absolute?
-        @absolute
+      def to_s
+        "#{absolute? ? "::" : ""}#{segments.join("::")}"
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) &&
+          absolute? == other.absolute? &&
+          segments == other.segments
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, absolute?, segments].hash
       end
 
       def match?(path_segments)
-        return false if absolute? && path_segments.length != segments.length
-        return false if path_segments.length < segments.length
+        reachable = terminal_row(path_segments.length)
+
+        segments.reverse_each do |segment|
+          reachable = advance(segment, path_segments, reachable)
+        end
+
+        reachable[0]
+      end
+
+      private
+
+      # Row for a fully-consumed pattern: an absolute pattern must have consumed
+      # the whole candidate; a relative pattern matches a prefix, so any trailing
+      # candidate segments are allowed.
+      def terminal_row(path_length)
+        Array.new(path_length + 1) do |path_index|
+          absolute? ? path_index == path_length : true
+        end
+      end
+
+      # Fold one pattern segment (walking right to left) into the reachability
+      # row. reachable[i] answers "can the rest of the pattern match path[i..]?".
+      def advance(segment, path_segments, reachable)
+        if segment.deep_wildcard?
+          deep_wildcard_row(path_segments.length, reachable)
+        else
+          segment_row(segment, path_segments, reachable)
+        end
+      end
+
+      # A `**` reaches i by consuming zero (the rest of the pattern reaches i) or
+      # one more segment (the same `**` reaches i + 1).
+      def deep_wildcard_row(path_length, reachable)
+        row = Array.new(path_length + 1)
+        row[path_length] = reachable[path_length]
+        (path_length - 1).downto(0) { |i| row[i] = reachable[i] || row[i + 1] }
+        row
+      end
 
-        segments.zip(path_segments).all? { |seg, path_seg| seg.match?(path_seg) }
+      # A normal segment reaches i only by matching path[i] and having the rest
+      # of the pattern reach i + 1.
+      def segment_row(segment, path_segments, reachable)
+        path_length = path_segments.length
+        row = Array.new(path_length + 1)
+        row[path_length] = false
+        (path_length - 1).downto(0) do |i|
+          row[i] = segment.match?(path_segments[i]) && reachable[i + 1]
+        end
+        row
       end
     end
   end

data/lib/lutaml/path/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Path
+    class ParseError < StandardError; end
+
+    # Raised when a path parses but the operation asked of it is not
+    # implemented. A StandardError, unlike Ruby's NotImplementedError, which
+    # descends from ScriptError and so escapes `rescue => e`.
+    class ResolutionError < StandardError; end
+  end
+end

data/lib/lutaml/path/instance_path.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "abstract_path"
+require_relative "errors"
+
+module Lutaml
+  module Path
+    # A parsed instance-data path: a base (the "::" anchor) plus dot-separated
+    # attribute navigation, with optional filter conditions on any step.
+    #
+    # Parse-only. It carries structure and renders itself; resolving it against
+    # real model data is out of scope, so match? raises rather than lying by
+    # matching on names and silently ignoring the conditions.
+    class InstancePath < AbstractPath
+      attr_reader :base_steps, :attribute_steps
+
+      def initialize(base_steps:, attribute_steps: [], absolute: false)
+        super(absolute: absolute)
+        @base_steps = Array(base_steps)
+        @attribute_steps = Array(attribute_steps)
+      end
+
+      def steps
+        base_steps + attribute_steps
+      end
+
+      def conditions
+        steps.filter_map(&:condition)
+      end
+
+      def match?(_path_segments)
+        raise ResolutionError,
+              "instance paths are parsed but not resolved: #{self}. " \
+              "If you meant a literal dot in an element name, escape it: a\\.b"
+      end
+
+      # Resolves this path against model instance data: a
+      # lutaml-model Serializable instance, a hash, or collections
+      # thereof. Plain single-segment paths resolve to a single value;
+      # filters, wildcards, and collections return arrays.
+      def resolve(root)
+        Resolver.resolve(root, self)
+      end
+
+      def to_s
+        "#{absolute? ? "::" : ""}#{base_steps.join("::")}" \
+          "#{attribute_steps.map { |s| ".#{s}" }.join}"
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) &&
+          absolute? == other.absolute? &&
+          base_steps == other.base_steps &&
+          attribute_steps == other.attribute_steps
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, absolute?, base_steps, attribute_steps].hash
+      end
+    end
+  end
+end

data/lib/lutaml/path/parser.rb

@@ -6,39 +6,190 @@ require "parslet"
 module Lutaml
   module Path
     class Parser < Parslet::Parser
-      rule(:space) { match('\s').repeat }
+      rule(:sp) { match('\s').repeat }
+      rule(:sp?) { sp.maybe }
 
       rule(:escaped_separator) { str("\\") >> str("::") }
+      rule(:escaped_dot) { str("\\") >> str(".") }
       rule(:separator) { str("::") }
+      rule(:dot) { str(".") }
 
-      # Character rules
-      rule(:glob_char) { match('[*?\[{]') }
+      # Character rules. A "." now terminates a segment, so it is excluded
+      # here; "\." escapes it, mirroring how "\::" escapes the separator.
       rule(:regular_char) do
-        (separator.absent? >> str("\\").absent? >> any) |
-          escaped_separator
+        (separator.absent? >> dot.absent? >> str("\\").absent? >> any) |
+          escaped_separator | escaped_dot
       end
 
-      # Single segment can contain any regular chars or glob chars
+      # --- filter conditions ------------------------------------------------
+      # Single quotes only: every value in the README is single-quoted. "\'"
+      # escapes a quote and "\\" escapes a backslash -- both are needed, or a
+      # value ending in a backslash renders as 'abc\' and its trailing escape
+      # eats the closing quote. Any OTHER backslash is left intact so a future
+      # evaluator's fnmatch still receives "\*" as a literal asterisk.
+      rule(:quoted_string) do
+        str("'") >> (
+          (str("\\") >> (str("'") | str("\\"))) | (str("'").absent? >> any)
+        ).repeat.as(:string) >> str("'")
+      end
+
+      rule(:number) { match("[0-9]").repeat(1).as(:number) }
+      rule(:literal) { quoted_string | number }
+
+      rule(:ident_char) { match('[^\s\[\]().,=!<>&|\']') }
+      rule(:attribute_ref) do
+        (ident_char.repeat(1) >> (dot >> ident_char.repeat(1)).repeat).as(:attref)
+      end
+
+      # Maximal munch: "!=" before "!", ">=" before ">".
+      #
+      # Defined once and shared with sniff_op. The sniff exists so a typo'd
+      # filter fails loudly rather than degrading to a character set; an
+      # operator added here but forgotten there would produce exactly the
+      # silent degradation the sniff was built to prevent.
+      rule(:cmp_lexeme) do
+        str("!=") | str(">=") | str("<=") | str("=") | str("<") | str(">")
+      end
+
+      rule(:cmp_op) { cmp_lexeme.as(:op) }
+
+      # Like `and`, `exists` needs a token boundary: without it
+      # "existsand b='2'" silently parses as `(exists and b='2')`.
+      # `in` needs none — membership must proceed to "(" to match at all.
+      rule(:existence) { str("exists").as(:exists) >> ident_char.absent? }
+
+      rule(:membership) do
+        attribute_ref.as(:lhs) >> sp >> str("in") >> sp? >>
+          str("(") >> sp? >>
+          (literal.as(:v) >> (sp? >> str(",") >> sp? >> literal.as(:v)).repeat).as(:literals) >>
+          sp? >> str(")")
+      end
+
+      rule(:comparison) do
+        attribute_ref.as(:lhs) >> sp? >> cmp_op >> sp? >> literal.as(:rhs)
+      end
+
+      # Most specific first, bare keyword last. If `existence` led, "exists"
+      # would be consumed as the keyword and an attribute actually named
+      # "exists" could never be compared -- while "in" and "and" could, which
+      # is a silent asymmetry. Ordering this way, "[exists]" still resolves:
+      # comparison finds no operator, membership finds no "in", existence wins.
+      rule(:predicate) { membership | comparison | existence }
+
+      # Boolean layering encodes precedence: ! tightest, then comparison,
+      # then &&, then ||. or_expr must sit ABOVE and_expr so || becomes the
+      # root of "a || b && c". README never states precedence; this is the
+      # conventional order and is documented in the README by this PR.
+      rule(:group) { str("(") >> sp? >> or_expr >> sp? >> str(")") }
+      rule(:primary) { group | predicate }
+      rule(:not_expr) { (str("!") >> sp? >> not_expr).as(:not) | primary }
+
+      # `and` needs the same token boundary the sniff uses, or "android='2'"
+      # silently parses as `and` + the attribute "roid" rather than raising.
+      rule(:and_op) { str("&&") | (str("and") >> ident_char.absent?) }
+
+      rule(:and_expr) do
+        (not_expr.as(:left) >> sp? >> and_op.as(:operator) >>
+          sp? >> and_expr.as(:right)).as(:binary) | not_expr
+      end
+
+      rule(:or_expr) do
+        (and_expr.as(:left) >> sp? >> str("||").as(:operator) >>
+          sp? >> or_expr.as(:right)).as(:binary) | and_expr
+      end
+
+      rule(:condition) { or_expr }
+
+      # --- the bracket rule (operator-sniff) --------------------------------
+      # "[" opens a FILTER iff (1) it is at offset > 0 in its segment,
+      # (2) its matching "]" -- found quote-aware -- terminates the segment,
+      # and (3) its body contains a condition operator. Otherwise "[" is an
+      # ordinary glob character set belonging to the name.
+      rule(:seg_end) { separator | dot | any.absent? }
+
+      # The sniff is TOKEN-aware: it tokenises with ident_char, the same
+      # alphabet attribute_ref uses, so an identifier is one token wherever it
+      # appears and a word operator only counts when no ident_char follows it.
+      # Otherwise ordinary character sets are wrongly claimed as filters and
+      # rejected -- "[print]" and "[min]" would match on their inner "in",
+      # "[standard]" on "and", "[coexists]" on "exists".
+      rule(:sniff_word) { ident_char.repeat(1) }
+      rule(:sniff_atom) { quoted_string | sniff_word | (str("]").absent? >> any) }
+      # Comparisons and the and-family reuse the grammar's own rules, so they
+      # cannot drift out of sync. "||" is one fixed token. "in" and "exists"
+      # stay spelled out: the grammar bounds "in" by the "(" that must follow
+      # it rather than by a character lookahead, and `existence` captures the
+      # word it matches, so neither reads back cleanly as a bare matcher.
+      rule(:sniff_op) do
+        cmp_lexeme | and_op | str("||") |
+          ((str("in") | str("exists")) >> ident_char.absent?)
+      end
+
+      rule(:filter_ahead) do
+        str("[") >>
+          (str("]").absent? >> sniff_op.absent? >> sniff_atom).repeat >>
+          sniff_op >> sniff_atom.repeat >>
+          str("]") >> seg_end.present?
+      end
+
+      # Once the sniff fires the filter MUST parse: no fallback, so a typo'd
+      # filter fails loudly instead of silently becoming a character set.
+      rule(:filter) do
+        filter_ahead.present? >>
+          str("[") >> sp? >> condition.as(:condition) >> sp? >> str("]")
+      end
+
+      # A bracket group the sniff has not claimed is consumed WHOLE, so a "."
+      # or "::" inside a character set is literal rather than a separator:
+      # "Class[.]" and "Class[a.b]" stay single-segment charsets. regular_char
+      # still accepts "[" so an unbalanced "x[" remains a name.
+      rule(:charset_group) { str("[") >> (str("]").absent? >> any).repeat >> str("]") }
+      rule(:name_atom) { charset_group | regular_char }
+
+      # The first character ALWAYS belongs to the name -- clause 1 ("a [ at
+      # offset 0 is always a charset") encoded literally. Only later positions
+      # may stop at a filter. Both halves are load-bearing: without the
+      # filter_ahead.absent? guard the name swallows the whole filter and every
+      # filter parses as a charset; without the leading unconditional name_atom
+      # filter_ahead fires at offset 0 too and "pkg::[exists]" raises.
       rule(:segment_content) do
-        (glob_char | regular_char).repeat(1).as(:content) >>
-          glob_char.present?.maybe.as(:is_pattern)
+        (name_atom >> (filter_ahead.absent? >> name_atom).repeat).as(:content)
       end
 
       rule(:segment) do
-        segment_content.as(:segment)
+        (segment_content >> filter.maybe).as(:segment)
       end
 
       rule(:segments) do
         (separator >> segment).repeat.as(:more_segments)
       end
 
-      # Full path expression - either absolute or relative
+      # The attribute part. "::" never follows "." (verified: zero README
+      # examples), so the namespace part is consumed first, then this.
+      rule(:attributes) do
+        (dot >> segment).repeat.as(:attrs)
+      end
+
+      # Full path expression. `absolute` is ALWAYS emitted (nil when relative)
+      # so the transform sees one stable key set: Parslet matches a hash on its
+      # exact keys, and a second root rule would have to be duplicated for
+      # every key added later.
       rule(:path_expr) do
-        ((separator.as(:absolute) >> segment.as(:first_segment) >> segments) |
-         (segment.as(:first_segment) >> segments))
+        separator.maybe.as(:absolute) >>
+          segment.as(:first_segment) >>
+          segments >>
+          attributes
+      end
+
+      # Neither leading separator may be escaped. README:212-218 forbids BOTH
+      # "\::Rectangle::Shape" and "\.width.length". Guard position 0 of the
+      # input; a real leading "::" is fine, so absolute paths and
+      # later-segment escapes are unaffected.
+      rule(:path) do
+        escaped_separator.absent? >> escaped_dot.absent? >> path_expr
       end
 
-      root(:path_expr)
+      root(:path)
     end
   end
 end

data/lib/lutaml/path/path_segment.rb

@@ -3,22 +3,48 @@
 module Lutaml
   module Path
     class PathSegment
-      attr_reader :name, :pattern
+      GLOB_CHARS = /[*?\[{]/
 
-      def initialize(name, is_pattern: false)
-        @name = name.gsub('\::', "::")
-        @pattern = is_pattern
+      attr_reader :name, :source
+
+      # Deliberately no `\[` unescape: a backslash before a glob character
+      # must survive into fnmatch's own escaper, which is what makes a literal
+      # "[" expressible. Unescaping it here would turn "Foo\[A-Z]" back into a
+      # character set.
+      def initialize(name)
+        @source = name
+        @name = name.gsub('\::', "::").gsub('\.', ".")
+        @pattern = @name.match?(GLOB_CHARS)
       end
 
       def pattern?
         @pattern
       end
 
+      def deep_wildcard?
+        name == "**"
+      end
+
       def match?(segment)
-        return File.fnmatch(name, segment) if pattern?
+        return File.fnmatch(name, segment, File::FNM_EXTGLOB) if pattern?
 
         name == segment
       end
+
+      # Renders the RAW source, so escapes survive a round-trip: "core\::t"
+      # must render back as "core\::t", not as the unescaped "core::t".
+      def to_s
+        @source
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && name == other.name
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, name].hash
+      end
     end
   end
 end