enumpath 0.1.0

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--no-private', '-', 'LICENSE']
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "enumpath"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/enumpath.gemspec

@@ -0,0 +1,32 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "enumpath/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "enumpath"
+  spec.version       = Enumpath::VERSION
+  spec.authors       = ["Chris Bloom"]
+  spec.email         = ["chrisbloom7@gmail.com"]
+
+  spec.summary       = "A JSONPath-compatible library for navigating Ruby objects using path expressions"
+  spec.homepage      = "https://github.com/youearnedit/enumpath"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.require_paths = ["lib"]
+
+  # Enumerable#dig was added in Ruby 2.3.0
+  spec.required_ruby_version = '>= 2.3.0'
+
+  spec.add_dependency "to_regexp", "~> 0.2.1"
+  spec.add_dependency "mini_cache", "~> 1.1.0"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "null-logger", "~> 0.1"
+  spec.add_development_dependency "pry-byebug", "~> 3.6"
+  spec.add_development_dependency "rake", "~> 12.3"
+  spec.add_development_dependency "rspec-benchmark", "~> 0.3.0"
+  spec.add_development_dependency "rspec", "~> 3.8"
+end

data/lib/enumpath.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'mini_cache'
+require "enumpath/logger"
+require "enumpath/operator"
+require "enumpath/path"
+require "enumpath/results"
+require "enumpath/resolver/simple"
+require "enumpath/resolver/property"
+require "enumpath/version"
+
+# A JSONPath-compatible library for navigating Ruby objects using path expressions
+module Enumpath
+  @verbose = false
+
+  class << self
+    # Whether verbose mode is enabled. When enabled, the {Enumpath::Logger} will print
+    # information to the logging stream to assist in debugging path expressions.
+    # Defaults to false
+    #
+    # @return [true,false]
+    attr_accessor :verbose
+
+    # Resolve a path expression against an enumerable
+    #
+    # @param path (see Enumpath::Path#initialize)
+    # @param enum (see Enumpath::Path#apply)
+    # @param options [optional, Hash]
+    # @option options [Symbol] :result_type (:value) The type of results to return, `:value` or `:path`
+    # @option options [true, false] :verbose (false) Whether to enable additional output for debugging
+    # @return (see Enumpath::Path#apply)
+    def apply(path, enum, options = {})
+      logger.level = 0
+      @verbose = options.delete(:verbose) || false
+      Enumpath::Path.new(path, result_type: options.delete(:result_type)).apply(enum)
+    end
+
+    # The {Enumpath::Logger} instance to use with verbose mode
+    #
+    # @private
+    # @return [Enumpath::Logger]
+    def logger
+      @logger ||= Enumpath::Logger.new
+    end
+
+    # A shortcut to {Enumpath::logger.log}
+    #
+    # @private
+    # @see Enumpath::Logger#log
+    def log(title)
+      block_given? ? logger.log(title, &Proc.new) : logger.log(title)
+    end
+
+    # A lightweight in-memory cache for caching normalized path expressions
+    #
+    # @private
+    # @return [MiniCache::Store]
+    def path_cache
+      @path_cache ||= MiniCache::Store.new
+    end
+  end
+end

data/lib/enumpath/logger.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Enumpath
+  # A logger for providing debugging information while evaluating path expressions
+  # @private
+  class Logger
+    PAD = "  "
+
+    SEPARATOR = '--------------------------------------'
+
+    # @return [Integer] the indentation level to apply to log messages
+    attr_accessor :level
+
+    # @return [::Logger, #<<] a {::Logger}-compatible logger instance
+    attr_accessor :logger
+
+    # @param logdev [String, IO] The log device. See Ruby's {::Logger.new} documentation.
+    def initialize(logdev = STDOUT)
+      @logger = ::Logger.new(logdev)
+      @level = 0
+      @padding = {}
+    end
+
+    # Generates a log message for debugging. Returns fast if {Enumpath.verbose} is false. Accepts an optional block
+    # which must contain a single hash, the contents of which will be added to the log message, and which are lazily
+    # evaluated only if {Enumpath.verbose} is true.
+    #
+    # @param title [String] the title of this log message
+    # @yield A lazily evaluated hash of key/value pairs to include in the log message
+    def log(title)
+      return unless Enumpath.verbose
+      append_log "#{padding}#{SEPARATOR}\n"
+      append_log "#{padding}Enumpath: #{title}\n"
+      if block_given?
+        append_log "#{padding}#{SEPARATOR}\n"
+        vars = yield
+        return unless vars.is_a?(Hash)
+        label_size = vars.keys.map(&:size).max
+        vars.each do |label, value|
+          append_log "#{padding}#{label.to_s.ljust(label_size)}: #{massaged_value(value)}\n"
+        end
+      end
+    end
+
+    private
+
+    def append_log(message)
+      logger << message
+    end
+
+    def massaged_value(value)
+      if value.is_a?(Enumerable)
+        enum_for_log(value)
+      elsif value.is_a?(TrueClass)
+        'True'
+      elsif value.is_a?(FalseClass)
+        'False'
+      elsif value.nil?
+        'Nil'
+      else
+        value.to_s
+      end
+    end
+
+    def enum_for_log(enum, length = 50)
+      json = enum.inspect
+      "#{json[0...length]}#{json.length > length ? '...' : ''}"
+    end
+
+    def padding
+      PAD * level.to_i
+    end
+  end
+end

data/lib/enumpath/operator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'enumpath/operator/base'
+require 'enumpath/operator/child'
+require 'enumpath/operator/filter_expression'
+require 'enumpath/operator/recursive_descent'
+require 'enumpath/operator/subscript_expression'
+require 'enumpath/operator/slice'
+require 'enumpath/operator/union'
+require 'enumpath/operator/wildcard'
+
+module Enumpath
+  # Namespace for classes that represent path expression operators
+  module Operator
+    ROOT = '$'
+
+    class << self
+      # Infer the type of operator and return an instance of its Enumpath::Operator subclass
+      #
+      # @param operator [String] the operator to infer type on
+      # @param enum [Enumerable] the enumerable to assist in detecting child operators
+      # @return an instance of a subclass of Enumpath::Operator based on what was detected, or nil if nothing was
+      #   detected
+      def detect(operator, enum)
+        if Enumpath::Operator::Child.detect?(operator, enum)
+          Enumpath.log('Child operator detected')
+          Enumpath::Operator::Child.new(operator)
+        elsif Enumpath::Operator::Wildcard.detect?(operator)
+          Enumpath.log('Wildcard operator detected')
+          Enumpath::Operator::Wildcard.new(operator)
+        elsif Enumpath::Operator::RecursiveDescent.detect?(operator)
+          Enumpath.log('Recursive Descent operator detected')
+          Enumpath::Operator::RecursiveDescent.new(operator)
+        elsif Enumpath::Operator::Union.detect?(operator)
+          Enumpath.log('Union operator detected')
+          Enumpath::Operator::Union.new(operator)
+        elsif Enumpath::Operator::SubscriptExpression.detect?(operator)
+          Enumpath.log('Subscript Expression operator detected')
+          Enumpath::Operator::SubscriptExpression.new(operator)
+        elsif Enumpath::Operator::FilterExpression.detect?(operator)
+          Enumpath.log('Filter Expression operator detected')
+          Enumpath::Operator::FilterExpression.new(operator)
+        elsif Enumpath::Operator::Slice.detect?(operator)
+          Enumpath.log('Slice operator detected')
+          Enumpath::Operator::Slice.new(operator)
+        else
+          Enumpath.log('Not a valid operator for enum')
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/enumpath/operator/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Operator
+    # Abstract base class for Operator definitions. Provides some helper methods for each operator and defines the
+    # basic factory methods that must be implemented.
+    #
+    # @abstract Subclass and override {.detect?} and {#apply} to implement a new path expression operator.
+    class Base
+      class << self
+        # Provides an interface for determining if a given string represents the operator class
+        #
+        # @abstract Override in each path expression operator subclass
+        #
+        # @param operator [String] the the full, normalized operator to test
+        # @param enum [Enumerable] an enum that can be used to assist in detection. Not all subclasses require an enum
+        #   for detection.
+        # @return [true, false] whether the operator param appears to represent the operator class
+        def detect?(operator, enum = nil)
+          raise NotImplementedError
+        end
+      end
+
+      # @return [String] the full, normalized operator
+      attr_reader :operator
+
+      # Initializes an operator class with an operator string
+      #
+      # @param operator [String] the the full, normalized operator
+      def initialize(operator)
+        @operator = operator
+      end
+
+      # Provides an interface for applying the operator to a given enumerable and yielding that result back to the
+      # caller with updated arguments
+      #
+      # @abstract Override in each path expression operator subclass
+      #
+      # @param remaining_path [Array] an array containing the normalized path segments yet to be resolved
+      # @param enum [Enumerable] the object to apply the operator to
+      # @param resolved_path [Array] an array containing the static path segments that have been resolved
+      #
+      # @yield A block that will be called if the operator is applied successfully. If the operator cannot or should
+      #   not be applied then the block is not yielded.
+      #
+      # @yieldparam remaining_path [Array] the new remaining_path after applying the operator
+      # @yieldparam enum [Enumerable] the new enum after applying the operator
+      # @yieldparam resolved_path [Array] the new resolved_path after applying the operator
+      # @yieldreturn [void]
+      def apply(remaining_path, enum, resolved_path, &block)
+        raise NotImplementedError
+      end
+
+      # An alias to {#operator}, used by {Enumpath::Logger}
+      #
+      # @private
+      # @return [String] the operator the class was initialized with
+      def to_s
+        operator
+      end
+
+      private
+
+      # Returns a set of keys, member names, or indices for a given enumerable. Useful for operators that need to
+      # iterate over each member of an enumerable. If the object is an array then it will return an array of indexes.
+      # If the object can be converted to a hash (Hash, Struct, or anything responding to {#to_h}) then it will be
+      # forced to a hash and the hash keys will be returned. For all other objects, an empty array will be returned.
+      #
+      # @param enum [Enumerable] the object to detect keys, member names, or indices on.
+      # @return [Array] a set of keys, member names, or indices for the object, or an empty set if they could not be
+      #   determined.
+      def keys(enum)
+        # Arrays
+        return (0...enum.length).to_a if enum.is_a?(Array)
+
+        # Other Enumerables
+        return enum.to_h.keys if enum.respond_to?(:to_h)
+
+        # Fallback
+        []
+      end
+    end
+  end
+end

data/lib/enumpath/operator/child.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Enumpath
+  module Operator
+    # Implements JSONPath child operator syntax. See {file:README.md#label-Child+operator} for syntax and examples.
+    class Child < Base
+      class << self
+        # Checks to see if an operator is valid as a child operator. It is considered valid if the enumerable contains
+        # an index, key, member, or property that responds to child.
+        #
+        # @param operator (see Enumpath::Operator::Base.detect?)
+        # @return (see Enumpath::Operator::Base.detect?)
+        def detect?(operator, enum)
+          !Enumpath::Resolver::Simple.resolve(operator, enum).nil? ||
+            !Enumpath::Resolver::Property.resolve(operator, enum).nil?
+        end
+      end
+
+      # Resolves a child operator against an enumerable. If the child operator matches a index, key, member, or
+      # property of the enumerable it is yielded to the block.
+      #
+      # @param (see Enumpath::Operator::Base#apply)
+      # @yield (see Enumpath::Operator::Base#apply)
+      # @yieldparam remaining_path [Array] remaining_path
+      # @yieldparam enum [Enumerable] the resolved value of the enumerable
+      # @yieldparam resolved_path [Array] resolved_path plus the child operator
+      def apply(remaining_path, enum, resolved_path, &block)
+        value = Enumpath::Resolver::Simple.resolve(operator, enum)
+        value = Enumpath::Resolver::Property.resolve(operator, enum) if value.nil?
+        yield(remaining_path, value, resolved_path + [operator]) if !value.nil?
+      end
+    end
+  end
+end

data/lib/enumpath/operator/filter_expression.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'to_regexp'
+
+module Enumpath
+  module Operator
+    # Implements JSONPath filter expression operator syntax. See {file:README.md#label-Filter+expression+operator} for
+    # syntax and examples
+    class FilterExpression < Base
+      COMPARISON_OPERATOR_REGEX = /(==|!=|>=|<=|<=>|>|<|=~|!~)/
+      LOGICAL_OPERATORS_REGEX = /(&&)|(\|\|)/
+      OPERATOR_REGEX = /^\?\((.*)\)$/
+
+      class << self
+        # Whether the operator matches {Enumpath::Operator::FilterExpression::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 enumerable that passes the filter expression
+      #
+      # @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 that passed the filter
+      # @yieldparam resolved_path [Array] resolved_path plus the key for each member of the enumerable that passed
+      #   the filter
+      def apply(remaining_path, enum, resolved_path, &block)
+        Enumpath.log('Evaluating filter expression') { { expression: operator, to: enum } }
+
+        _match, unpacked_operator = OPERATOR_REGEX.match(operator).to_a
+        expressions = unpacked_operator.split(LOGICAL_OPERATORS_REGEX).map(&:strip)
+
+        keys(enum).each do |key|
+          value = Enumpath::Resolver::Simple.resolve(key, enum)
+          Enumpath.log('Applying filter to key') { { key: key, enum: value } }
+          if pass?(expressions.dup, value)
+            Enumpath.log('Applying filtered key') { { 'filtered key': key, 'filtered enum': value } }
+            yield(remaining_path, value, resolved_path + [key.to_s])
+          end
+        end
+      end
+
+      private
+
+      def pass?(expressions, enum)
+        running_result = evaluate(expressions.shift, enum)
+        Enumpath.log('Initial result') { { result: running_result } }
+        while expressions.any? do
+          logical_operator, expression = expressions.shift(2)
+          running_result = evaluate(expression, enum, logical_operator, running_result)
+          Enumpath.log('Running result') { { result: running_result } }
+        end
+        running_result
+      end
+
+      def evaluate(expression, enum, logical_operator = nil, running_result = nil)
+        property, operator, operand = expression.split(COMPARISON_OPERATOR_REGEX).map(&:strip)
+        value = resolve(property, enum)
+        expression_result = test(operator, operand, value)
+        Enumpath.log('Evaluated filter') do
+          { property => value, operator: operator, operand: operand, result: expression_result,
+            logical_operator: logical_operator }.compact
+        end
+        if logical_operator == '&&'
+          Enumpath.log('&&=')
+          running_result &&= expression_result
+        elsif logical_operator == '||'
+          Enumpath.log('||=')
+          running_result ||= expression_result
+        else
+          expression_result
+        end
+      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)
+        return !!value if operator.nil? || operand.nil?
+        typecast_operand = variable_typecaster(operand)
+        !!value.public_send(operator.to_sym, typecast_operand)
+      rescue NoMethodError
+        Enumpath.log('Filter could not be evaluated!')
+        false
+      end
+
+      def variable_typecaster(variable)
+        if variable =~ /\A('|").+\1\z/
+          # It quacks like a string
+          variable.gsub(/\A('|")|('|")\z/, '')
+        elsif variable =~ /^:.+/
+          # It quacks like a symbol
+          variable.gsub(/\A:/, '').to_sym
+        elsif variable =~ /true|false|nil/i
+          # It quacks like an unquoted boolean operator
+          variable == 'true' ? true : false
+        elsif regexp = variable.to_regexp(literal: false, detect: false)
+          # It quacks like a regex
+          regexp
+        else
+          # Otherwise treat it as a number
+          variable.to_f
+        end
+      end
+    end
+  end
+end