enumpath 0.1.0

data/lib/enumpath/operator/recursive_descent.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Operator
+    # Implements JSONPath recursive descent operator syntax. See {file:README.md#label-Recursive+descent+operator} for
+    # syntax and examples
+    class RecursiveDescent < Base
+      OPERATOR = '..'
+
+      class << self
+        # Simple test of whether the operator matches the {Enumpath::Operator::RecursiveDescent::OPERATOR} constant
+        #
+        # @param operator (see Enumpath::Operator::Base.detect?)
+        # @return (see Enumpath::Operator::Base.detect?)
+        def detect?(operator)
+          !!(operator == OPERATOR)
+        end
+      end
+
+      # Yields to the block once for the enumerable itself, and once for every direct member of the enumerable that is
+      # also an enumerable
+      #
+      # @param (see Enumpath::Operator::Base#apply)
+      # @yield (see Enumpath::Operator::Base#apply)
+      # @yieldparam remaining_path [Array] remaining_path for the enumerable itself, or the recursive descent
+      #   operator plus remaining_path for each direct enumerable member
+      # @yieldparam enum [Enumerable] enum for the enumerable itself, or the direct enumerable member for each direct
+      #   enumerable member
+      # @yieldparam resolved_path [Array] resolved_path for the enumerable itself, or resolved_path plus the key for
+      #   each direct enumerable member
+      def apply(remaining_path, enum, resolved_path, &block)
+        Enumpath.log('Applying remaining path recursively to enum') { { 'remaining path': remaining_path } }
+        yield(remaining_path, enum, resolved_path)
+        keys(enum).each do |key|
+          value = Enumpath::Resolver::Simple.resolve(key, enum)
+          if recursable?(value)
+            Enumpath.log('Applying remaining path recursively to key') do
+              { key: key, 'remaining path': ['..'] + remaining_path }
+            end
+            yield(['..'] + remaining_path, value, resolved_path + [key])
+          end
+        end
+      end
+
+      private
+
+      def recursable?(value)
+        value.is_a?(Enumerable)
+      end
+    end
+  end
+end

data/lib/enumpath/operator/slice.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Operator
+    # Implements JSONPath array slice operator syntax. See {file:README.md#label-Slice+operator} for syntax and examples
+    class Slice < Base
+      OPERATOR_REGEX = /^(-?[0-9]*):(-?[0-9]*):?(-?[0-9]*)$/
+
+      class << self
+        # Whether the operator matches {Enumpath::Operator::Slice::OPERATOR_REGEX}
+        #
+        # @param operator (see Enumpath::Operator::Base.detect?)
+        # @return (see Enumpath::Operator::Base.detect?)
+        def detect?(operator)
+          !!(operator =~ OPERATOR_REGEX)
+        end
+      end
+
+      # Yields to the block once for each member of the local enumerable whose index is included by position between
+      # _start_ and up to (but not including) _end_. If _step_ is included then only every _step_ member is included,
+      # starting with the first.
+      #
+      # @param (see Enumpath::Operator::Base#apply)
+      # @yield (see Enumpath::Operator::Base#apply)
+      # @yieldparam remaining_path [Array] the included index plus remaining_path
+      # @yieldparam enum [Enumerable] enum
+      # @yieldparam resolved_path [Array] resolved_path
+      def apply(remaining_path, enum, resolved_path, &block)
+        _match, start, length, step = OPERATOR_REGEX.match(operator).to_a
+        max_length = enum.size
+        slices(start, length, step, max_length).each do |index|
+          Enumpath.log('Applying slice') { { slice: index } }
+          yield([index.to_s] + remaining_path, enum, resolved_path)
+        end
+      end
+
+      private
+
+      def slices(start, length, step, max_length)
+        start = slice_start(start, max_length)
+        length = slice_length(length, max_length)
+        step = slice_step(step)
+        (start...length).step(step)
+      end
+
+      def slice_start(start, max_length)
+        start = start.empty? ? 0 : start.to_i
+        start.negative? ? [0, start + max_length].max : [max_length, start].min
+      end
+
+      def slice_length(length, max_length)
+        length = length.empty? ? max_length : length.to_i
+        length.negative? ? [0, length + max_length].max : [max_length, length].min
+      end
+
+      def slice_step(step)
+        step.empty? ? 1 : step.to_i
+      end
+    end
+  end
+end

data/lib/enumpath/operator/subscript_expression.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Operator
+    # Implements JSONPath subscript expressions operator syntax. See
+    # {file:README.md#label-Subscript+expressions+operator} for syntax and examples
+    class SubscriptExpression < Base
+      ARITHMETIC_OPERATOR_REGEX = /(\+|-|\*\*|\*|\/|%)/
+      OPERATOR_REGEX = /^\((.*)\)$/
+
+      class << self
+        # Whether the operator matches {Enumpath::Operator::SubscriptExpression::OPERATOR_REGEX}
+        #
+        # @param operator (see Enumpath::Operator::Base.detect?)
+        # @return (see Enumpath::Operator::Base.detect?)
+        def detect?(operator)
+          !!(operator =~ OPERATOR_REGEX)
+        end
+      end
+
+      # Yields to the block once if the subscript expression evaluates to a member of the enumerable
+      #
+      # @param (see Enumpath::Operator::Base#apply)
+      # @yield (see Enumpath::Operator::Base#apply)
+      # @yieldparam remaining_path [Array] remaining_path
+      # @yieldparam enum [Enumerable] the member of the enumerable at the value of the subscript expression
+      # @yieldparam resolved_path [Array] resolved_path plus the value of the subscript expression
+      def apply(remaining_path, enum, resolved_path, &block)
+        Enumpath.log('Applying subscript expression') { { expression: operator, to: enum } }
+
+        _match, unpacked_operator = OPERATOR_REGEX.match(operator).to_a
+        result = evaluate(unpacked_operator, enum)
+
+        value = Enumpath::Resolver::Simple.resolve(result, enum)
+        if !value.nil?
+          Enumpath.log('Applying subscript') { { 'enum at subscript': value } }
+          yield(remaining_path, value, resolved_path + [result.to_s])
+        end
+      end
+
+      private
+
+      def evaluate(unpacked_operator, enum)
+        property, operator, operand = unpacked_operator.split(ARITHMETIC_OPERATOR_REGEX).map(&:strip)
+        test(operator, operand, resolve(property, enum))
+      end
+
+      def resolve(property, enum)
+        return enum if property == '@'
+        value = Enumpath::Resolver::Simple.resolve(property.gsub(/^@\./, ''), enum)
+        value = Enumpath::Resolver::Property.resolve(property.gsub(/^@\./, ''), enum) if value.nil?
+        value
+      end
+
+      def test(operator, operand, value)
+        if operator.nil? || operand.nil?
+          Enumpath.log('Simple subscript') { { subscript: value } }
+          value
+        else
+          # Evaluate expression using operator
+          typecast_operand = variable_typecaster(operand)
+          result = value.public_send(operator.to_sym, typecast_operand)
+          Enumpath.log('Evaluated subscript') do
+            { value: value, operator: operator, operand: typecast_operand, result: result }
+          end
+          result
+        end
+      rescue NoMethodError
+        Enumpath.log('Subscript could not be evaluated') { { subscript: nil } }
+        nil
+      end
+
+      def variable_typecaster(variable)
+        if variable =~ /\A('|").+\1\z/ || variable =~ /^:.+/
+          # It quacks like a string or symbol
+          variable.gsub(/\A(:|('|"))|('|")\z/, '')
+        else
+          # Otherwise treat it as a number. Note that we only care about whole numbers in this case
+          variable.to_i
+        end
+      end
+    end
+  end
+end

data/lib/enumpath/operator/union.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# TODO: Investigate supporting anchored paths (`$.foo.bar...`, `@.foo.bar...`)
+
+module Enumpath
+  module Operator
+    # Implements JSONPath union operator syntax. See {file:README.md#label-Union+operator} for syntax and examples
+    class Union < Base
+      OPERATOR = /,/
+      CONSTRAINTS = /^,|,$/
+      SPLIT_REGEX = /,/
+
+      # The operator consists of
+      # a set of names or indices. Any member of the local enumerable that can
+      # be found at any of the keys or indices is yielded to the block.
+
+      class << self
+        # Whether the operator matches {Enumpath::Operator::Union::OPERATOR} and does not match
+        # {Enumpath::Operator::Union::CONSTRAINTS}
+        #
+        # @param operator (see Enumpath::Operator::Base.detect?)
+        # @return (see Enumpath::Operator::Base.detect?)
+        def detect?(operator)
+          operator.scan(',').any? && operator.scan(CONSTRAINTS).none?
+        end
+      end
+
+      # Yields to the block once for every union member
+      #
+      # @param (see Enumpath::Operator::Base#apply)
+      # @yield (see Enumpath::Operator::Base#apply)
+      # @yieldparam remaining_path [Array] the union member plus remaining_path
+      # @yieldparam enum [Enumerable] enum
+      # @yieldparam resolved_path [Array] resolved_path
+      def apply(remaining_path, enum, resolved_path, &block)
+        parts = operator.split(SPLIT_REGEX).map { |part| part.strip.gsub(/^['"]|['"]$/, '') }
+        Enumpath.log('Applying union parts') { { parts: parts } }
+        parts.each { |part| yield([part] + remaining_path, enum, resolved_path) }
+      end
+    end
+  end
+end

data/lib/enumpath/operator/wildcard.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Operator
+    # Implements JSONPath wildcard operator syntax. See {file:README.md#label-Wildcard+operator} for syntax and examples
+    class Wildcard < Base
+      OPERATOR = '*'
+
+      class << self
+        # Simple test of whether the operator matches the {Enumpath::Operator::Wildcard::OPERATOR} constant
+        #
+        # @param operator (see Enumpath::Operator::Base.detect?)
+        # @return (see Enumpath::Operator::Base.detect?)
+        def detect?(operator)
+          operator == OPERATOR
+        end
+      end
+
+      # Yields to the block once for every direct member of the enumerable
+      #
+      # @param (see Enumpath::Operator::Base#apply)
+      # @yield (see Enumpath::Operator::Base#apply)
+      # @yieldparam remaining_path [Array] the key of the given member plus remaining_path
+      # @yieldparam enum [Enumerable] enum
+      # @yieldparam resolved_path [Array] resolved_path
+      def apply(remaining_path, enum, resolved_path, &block)
+        keys = keys(enum)
+        Enumpath.log('Applying wildcard to keys') { { keys: keys } }
+        keys.each { |key| yield([key.to_s] + remaining_path, enum, resolved_path) }
+      end
+    end
+  end
+end

data/lib/enumpath/path.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'enumpath/path/normalized_path'
+
+module Enumpath
+  # A mechanism for applying path expressions to enumerables and tracking results
+  class Path
+    # @return [Enumpath::Path::NormalizedPath] the normalized path
+    attr_reader :path
+
+    # @return [Enumpath::Results] the current results array
+    attr_reader :results
+
+    # @param path [String, Array<String>] the path expression to apply to the enumerable
+    # @param result_type (see Enumpath::Results#initialize)
+    def initialize(path, result_type: nil)
+      @path = path
+      normalize!
+      @results = Enumpath::Results.new(result_type: result_type)
+    end
+
+    # Apply the path expression against an enumerable
+    #
+    # @note Calling this method resets the previous results array
+    #
+    # @param enum [Enumerable] the enumerable to apply the path to
+    # @return [Enumpath::Results] an array of resolved values or paths
+    def apply(enum)
+      results.clear
+      trace(@path.dup, enum)
+      results
+    end
+
+    private
+
+    # Applies the next normalized path segment to enumerable and keeps track of resolved path segments. This method
+    # recursively yields to itself via each Operator subclass's {#apply} method. If there are no remaining path
+    # segments then it stores a new result in the results array effectively ending processing on that branch of the
+    # original enumerator.
+    #
+    # @param path_segments [Array] an array containing the normalized path segments to be resolved
+    # @param enum [Enumerable] the object to apply the next normalized path segment to
+    # @param resolved_path [Array] an array containing the static path segments that have been resolved so far
+    # @param nesting_level [Integer] used to set the indentation level for {Enumpath::Logger}
+    # @return [void]
+    def trace(path_segments, enum, resolved_path = [], nesting_level = 0)
+      Enumpath.logger.level = nesting_level
+      if path_segments.any?
+        Enumpath.log("Applying") { { operator: path_segments, to: enum } }
+        segment = path_segments.first
+        remaining_path = path_segments[1..-1]
+        operator = Enumpath::Operator.detect(segment, enum)
+        operator&.apply(remaining_path, enum, resolved_path) do |s, e, c|
+          trace(s, e, c, nesting_level + 1)
+        end
+      else
+        Enumpath.log('Storing') { { resolved_path: resolved_path, enum: enum } }
+        results.store(resolved_path, enum)
+      end
+      Enumpath.logger.level = nesting_level
+    end
+
+    private
+
+    def cache
+      @cache ||= Enumpath.path_cache
+    end
+
+    def normalize!
+      @path = cache.get_or_set(@path) { Enumpath::Path::NormalizedPath.new(@path) }
+    end
+  end
+end

data/lib/enumpath/path/normalized_path.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Enumpath
+  class Path
+    # A utility for automatically normalizing string path expressions
+    class NormalizedPath < Array
+      FILTER_EXPRESSION_REGEX = /[\['](\??\(.*?\))[\]']/
+      INDEX_NOTATION_REGEX = /#([0-9]+)/
+
+      # @param path (see Enumpath::Path#initialize)
+      def initialize(path)
+        super(normalize(path))
+      end
+
+      private
+
+      def normalize(path)
+        return path if path.is_a?(Array)
+        normalized_path = path.dup
+        normalized_path, filter_expressions = remove_filter_expressions(normalized_path)
+        normalized_path.gsub!(/'?\.'?|\['?/, ';')    # Replace "'?.'?" or "['?" with ";"
+        normalized_path.gsub!(/;;;|;;/, ';..;')      # Replace ";;;" or ";;" with ";..;"
+        normalized_path.gsub!(/;\z|'?\]|'\z/, '')    # Replace ";$" or "'?]" or "'$" with ""
+        normalized_path = restore_filter_expressions(normalized_path, filter_expressions)
+        normalized_path.gsub!(/\A\$(;|\z)/, '')      # Remove root operator
+        normalized_path = normalized_path.split(';') # Split into segment parts
+        normalized_path.reject! do |segment|         # Get rid of any blank segments
+          segment.nil? || segment.size == 0
+        end
+        Enumpath.log('Path normalized') { { original: path, normalized: normalized_path } }
+        normalized_path
+      end
+
+      # Move filter expressions (`[?(expr)]`) to the temporary array and replace with an index notation
+      def remove_filter_expressions(path)
+        filter_expressions = []
+        stripped_path = path.gsub(FILTER_EXPRESSION_REGEX) do
+          filter_expressions << $1
+          "[##{filter_expressions.size - 1}]"
+        end
+        [stripped_path, filter_expressions]
+      end
+
+      # Replace index notations with their corresponding filter expressions (`?(expr)`) from the temporary array
+      def restore_filter_expressions(path_expression, filter_expressions)
+        path_expression.gsub(INDEX_NOTATION_REGEX) { filter_expressions[$1.to_i] }
+      end
+    end
+  end
+end

data/lib/enumpath/resolver/property.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Resolver
+    # A utility for resolving a string as a property of an object
+    class Property
+      class << self
+        # Attempts to resolve a string as a property of an object. In this context a property is a public method that
+        # expects no arguments.
+        #
+        # @param property [String] the name of the property to attempt to resolve
+        # @param object [Object] the object to resolve the property against
+        # @return the resolved property value, or nil if it could not be resolved
+        def resolve(property, object)
+          # TODO: return if Enumpath.disable_property_resolver
+          object.public_send(property.to_s.to_sym)
+        rescue ArgumentError, NoMethodError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/enumpath/resolver/simple.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Resolver
+    # A utility for resolving a string as an index, key, or member of an enumerable
+    class Simple
+      NUMERIC_INDEX_TEST = /\A\-?(?:0|[1-9][0-9]*)\z/
+
+      class << self
+        # Attempts to resolve a string as an index, key, or member of an enumerable
+        #
+        # @param variable [String] the value to attempt to resolve
+        # @param enum [Enumerable] the enumerable to resolve the value against
+        # @return the resolved value, or nil if it could not be resolved
+        def resolve(variable, enum)
+          variable = variable.to_s
+          value = rescued_dig(enum, variable.to_i) if variable =~ NUMERIC_INDEX_TEST
+          value = rescued_dig(enum, variable) if value.nil?
+          value = rescued_dig(enum, variable.to_sym) if value.nil?
+          value
+        end
+
+        private
+
+        def rescued_dig(enum, typecast_variable)
+          enum.dig(typecast_variable)
+        rescue NoMethodError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end