jamespath 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 71c755c55c46dffb46d63967c271a3d3f0277bc9
+  data.tar.gz: bb5008e347cfd92fda04ef9aea28a21f3da6361b
+SHA512:
+  metadata.gz: 9a467a6dcbf41838c90dfc2dbabf598525c1c6325646797215c0a0d2b5b0234559be7f2bc48b6f4f4173c4ebd6b86aba8e1e67e2fa18f9832e3edbf229baad38
+  data.tar.gz: 72f1457d53b8bdcf42193a1044ba0d34ac258baca583f3796b8192f4e41d8039cc118db8aaa963d3df9dd4c50a7eba3143bf51d1c37150d719789a9a31edd369

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+.yardopts
+.yardoc
+doc

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Loren Segal and Trevor Rowe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# Jamespath
+
+Jamespath is a library that lets you select objects from deeply nested
+structures, arrays, hashes, or JSON objects using a simple expression
+language.
+
+Think XPath, but for objects.
+
+## Installing
+
+```ruby
+$ gem install jamespath
+```
+
+Or with Bundler:
+
+```ruby
+gem 'jamespath', '~> 1.0'
+```
+
+## Usage
+
+To use Jamespath, call the {Jamespath.search} method with an expression
+and an object ot search:
+
+```ruby
+object = { foo: { bar: ['value1', 'value2', 'value3'] } }
+Jamespath.search('foo.bar[0]', object) #=> 'value1'
+```
+
+You can also {Jamespath.compile} an expression if you are performing the same
+search operation against multiple objects:
+
+```ruby
+object1 = { foo: { bar: ['value1', 'value2', 'value3'] } }
+object2 = { foo: { bar: ['value4', 'value5', 'value6'] } }
+
+expr = Jamespath.compile('foo.bar[0]')
+expr.search(object1) #=> 'value1'
+expr.search(object2) #=> 'value4'
+```
+
+## Expression Syntax
+
+See the [JMESpath][1] project for more information on the expression syntax.
+
+## License & Acknowledgements 
+
+This library was written by Loren Segal and Trevor Rowe and is licensed under
+the MIT license. The implementation is based on the [JMESpath][1] library
+written by James Sayerwinnie for the Python programming language.
+
+[1]: http://github.com/boto/jmespath

data/Rakefile

@@ -0,0 +1,6 @@
+task :default => :test
+
+desc 'Run all tests'
+task :test do
+  sh "ruby #{FileList['test/**_test.rb'].join(' ')}"
+end

data/jamespath.gemspec

@@ -0,0 +1,15 @@
+require File.join(File.dirname(__FILE__), 'lib', 'jamespath', 'version')
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jamespath'
+  spec.version       = Jamespath::VERSION
+  spec.summary       = 'Implements JMESpath declarative object searching.'
+  spec.description   = 'Like XPath, but for JSON and other structured objects.'
+  spec.authors       = ['Loren Segal', 'Trevor Rowe']
+  spec.homepage      = 'http://github.com/lsegal/jamespath'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.add_development_dependency('yard', '~> 0.0')
+  spec.add_development_dependency('rdiscount', '>= 2.1.7', '< 3.0')
+end

data/lib/jamespath.rb

@@ -0,0 +1,34 @@
+require_relative './jamespath/tokenizer'
+require_relative './jamespath/parser'
+require_relative './jamespath/vm'
+require_relative './jamespath/version'
+
+# {include:file:README.md}
+module Jamespath
+  module_function
+
+  # Searches an object with a given JMESpath expression.
+  #
+  # @param query [String] the expression to search for.
+  # @param object [Object] an object to search for the expression in.
+  # @return [Object] the object, or list of objects, that match the expression.
+  # @return [nil] if no objects matched the expression
+  # @example Searching an object
+  #   Jamespath.search('foo.bar', foo: {bar: 'result'}) #=> 'result'
+  def search(query, object)
+    compile(query).search(object)
+  end
+
+  # Compiles an expression that can be {VM#search searched}.
+  #
+  # @param query [String] the expression to search for.
+  # @return [VM] a virtual machine object that can interpret the expression.
+  # @see VM#search
+  # @example Compiling an expression
+  #   expr = Jamespath.compile('foo.bar')
+  #   expr.search(foo: {bar: 'result1'}) #=> 'result1'
+  #   expr.search(foo: {bar: 'result2'}) #=> 'result2'
+  def compile(query)
+    VM.new(Parser.new.parse(query))
+  end
+end

data/lib/jamespath/parser.rb

@@ -0,0 +1,120 @@
+require_relative 'tokenizer'
+
+module Jamespath
+  # # Grammar
+  #
+  # ```abnf
+  # expression        : sub_expression | index_expression
+  #                   | or_expression | identifier | '*'
+  #                   | multi_select_list | multi_select_hash;
+  # sub_expression    : expression '.' expression;
+  # or_expression     : expression '||' expression;
+  # index_expression  : expression bracket_specifier | bracket_specifier;
+  # multi_select_list : '[' non_branched_expr ']';
+  # multi_select_hash : '{' keyval_expr '}';
+  # keyval_expr       : identifier ':' non_branched_expr;
+  # non_branched_expr : identifier
+  #                   | non_branched_expr '.' identifier
+  #                   | non_branched_expr '[' number ']';
+  # bracket_specifier : '[' number ']' | '[' '*' ']';
+  # ```
+  class Parser
+    # Parses an expression into a set of instructions to be executed by the
+    # {VM}.
+    #
+    # @param source [String] the expression to parse
+    # @return [Array(Symbol, Object)] a set of instructions
+    # @see VM
+    def parse(source)
+      @tokens = Tokenizer.new.tokenize(source)
+      @idx = 0
+      @instructions = []
+      parse_expression
+      @instructions
+    end
+
+    protected
+
+    def parse_expression
+      next_token! do |token|
+        case token.type
+        when :asterisk
+          @instructions << [:get_key_all, nil]
+        when :identifier, :number
+          @instructions << [:get_key, token.value]
+        when :lbrace # multi_select_hash
+          parse_multi_select_hash
+        when :lbracket # list
+          parse_index_expression
+        else
+          unexpected
+        end
+
+        parse_sub_expression
+      end
+    end
+
+    def parse_sub_expression
+      next_token do |token|
+        case token.type
+        when :dot
+          parse_expression
+        when :double_pipe
+          @instructions << [:ret_if_match, nil]
+          parse_expression
+        when :lbracket
+          parse_index_expression
+        else
+          unexpected
+        end
+      end
+    end
+
+    def parse_index_expression
+      next_token! do |token|
+        case token.type
+        when :number
+          assert_next_type :rbracket
+          @instructions << [:get_idx, token.value.to_i]
+          parse_sub_expression
+        when :asterisk
+          assert_next_type :rbracket
+          @instructions << [:get_idx_all, nil]
+          parse_sub_expression
+        when :rbracket
+          @instructions << [:flatten_list, nil]
+          parse_sub_expression
+        end
+      end
+    end
+
+    private
+
+    def assert_next_type(type)
+      next_token! do |token|
+        unexpected(token) unless token.type == type
+      end
+    end
+
+    def next_token!(peek = false, &block)
+      yielded = false
+      next_token(peek) {|token| yield(token); yielded = true }
+      unexpected(nil) unless yielded
+    end
+
+    def next_token(peek = false, &block)
+      if token = @tokens[@idx]
+        @idx += 1 unless peek
+        yield(token)
+      end
+    end
+
+    def unexpected(token = @tokens[@idx-1])
+      if token
+        raise SyntaxError, "unexpected token #{token}"
+      else
+        raise SyntaxError, "unexpected end-of-input at #{@tokens.last}"
+      end
+    end
+  end
+end

data/lib/jamespath/tokenizer.rb

@@ -0,0 +1,57 @@
+require 'strscan'
+
+module Jamespath
+  class Token < Struct.new(:type, :value, :pos)
+    def inspect; "#{type}(#{value.inspect}, pos=#{pos})" end
+    alias to_s inspect
+  end
+
+  class Tokenizer
+    attr_reader :tokens
+
+    TOKENS = {
+      lbracket: /\[/,
+      rbracket: /\]/,
+      lbrace: /\{/,
+      rbrace: /\}/,
+      comma: /,/,
+      dot: /\./,
+      colon: /:/,
+      double_pipe: /\|\|/,
+      asterisk: /\*/,
+      number: /-?[0-9]+/,
+      quoted_identifier: /"([^"\\]|\\"|\\\\|\\[^"])*"/,
+      identifier: /[a-zA-Z0-9_\u007E-\uFFFF]+/
+    }
+
+    def tokenize(source)
+      @pos = 0
+      @source = source
+      @scanner = StringScanner.new(source)
+      @tokens = []
+      until @scanner.eos?
+        @tokens << next_token
+      end
+      @tokens
+    end
+
+    protected
+
+    def next_token
+      @pos += @scanner.skip(/\s+/) || 0
+      TOKENS.each do |type, re|
+        if token = @scanner.scan(re) and token.length > 0
+          pos, @pos = @pos, @pos + token.length
+          if type == :quoted_identifier
+            type = :identifier
+            token = token[1...-1].gsub(/\\"/, '"')
+          end
+
+          return Token.new(type, token, pos)
+        end
+      end
+
+      raise SyntaxError, "unexpected token at pos=#{@pos}: #{@source[@pos]}"
+    end
+  end
+end

data/lib/jamespath/version.rb

@@ -0,0 +1,3 @@
+module Jamespath
+  VERSION = '0.5.0'
+end

data/lib/jamespath/vm.rb

@@ -0,0 +1,158 @@
+module Jamespath
+  # The virtual machine that interprets compiled expressions and searches for
+  # objects. The VM implements a handful of instructions that can be used to
+  # navigate through an object structure.
+  #
+  # # VM Overview
+  #
+  # The VM iterates over the instructions attempting to navigate through
+  # the given object. As instructions are evaluated, the "object" is tracked
+  # and replaced as each selection is made. The result of a search is the
+  # object value after evaluating all instructions.
+  #
+  # The VM understands "hash-like" and "array-like" objects. "Array-like"
+  # objects are defined as any object that subclasses Array. "Hash-like"
+  # objects are defined as either Hash or Struct objects.
+  #
+  # ## Instruction list
+  #
+  # ### `:get_key <key>`
+  #
+  # Gets a "key" from the hash-like object on the stack. If the object is
+  # not hash-like, this instruction sets the object value to nil.
+  #
+  # ### `:get_idx <idx>`
+  #
+  # Gets an object at index "idx" from the array-like object on the stack.
+  # If the object is not array-like, this instruction sets the object value
+  # to nil. "idx" must be a number, but can be negative. Negative values
+  # index from the end of the array, where -1 is the last value.
+  #
+  # ### `:get_key_all`
+  #
+  # Gets all values from the hash-like object value. If the object is not
+  # hash-like, this instruction sets the object value to nil.
+  #
+  # ### `:get_idx_all`
+  #
+  # Gets all items from an array-like object. If the object is hash-like,
+  # the object is set to the keys of the hash-like structure. If the object
+  # is not array-like or hash-like, this instruction sets the object value
+  # to nil.
+  #
+  # ### `:flatten_list`
+  #
+  # Flattens a list of subarrays into a single array. If the object is not
+  # array-like, this instruction sets the object value to an empty array.
+  #
+  # ### `:ret_if_match`
+  #
+  # Breaks from parsing instructions if the object value is non-nil. If the
+  # object is nil, this instruction should reset the object value to the
+  # original object that was being searched.
+  #
+  class VM
+    # @api private
+    class ArrayGroup < Array
+      def initialize(arr) replace(arr) end
+    end
+
+    # @return [Array(Symbol, Object)] the instructions the VM executes.
+    attr_reader :instructions
+
+    # Creates a virtual machine that can evaluate a set of instructions.
+    # Use the {Parser} to turn an expression into a set of instructions.
+    #
+    # @param instructions [Array(Symbol, Object)] a list of instructions to
+    #   execute.
+    # @see Parser#parse
+    # @example VM for expression "foo.bar[-1]"
+    #   vm = VM.new [
+    #    [:get_key, 'foo'],
+    #    [:get_key, 'bar'],
+    #    [:get_idx, -1]
+    #   ]
+    #   vm.search(foo: {bar: [1, 2, 3]}) #=> 3
+    def initialize(instructions)
+      @instructions = instructions
+    end
+
+    # Searches for the compile expression against the object passed in.
+    #
+    # @param object_to_search [Object] the object to search for results.
+    # @return (see Jamespath.search)
+    def search(object_to_search)
+      object = object_to_search
+      @instructions.each do |instruction|
+        if instruction.first == :ret_if_match
+          if object
+            break # short-circuit or expression
+          else
+            object = object_to_search  # reset search
+          end
+        else
+          object = send(instruction[0], object, instruction[1])
+        end
+      end
+
+      object
+    end
+
+    protected
+
+    def get_key(object, key)
+      if struct?(object)
+        object[key]
+      elsif ArrayGroup === object
+        object = object.map {|o| get_key(o, key) }.compact
+        object.length > 0 ? ArrayGroup.new(object) : []
+      end
+    end
+
+    def get_idx(object, idx)
+      if ArrayGroup === object
+        object = object.map {|o| get_idx(o, idx) }.compact
+        object.length > 0 ? ArrayGroup.new(object) : nil
+      elsif array?(object)
+        object[idx]
+      end
+    end
+
+    def get_key_all(object, *)
+      object.respond_to?(:values) ? ArrayGroup.new(object.values) : nil
+    end
+
+    def get_idx_all(object, *)
+      if array?(object)
+        new_object = object.map do |o|
+          Array === o ? ArrayGroup.new(o) : o
+        end
+        ArrayGroup.new(new_object)
+      elsif object.respond_to?(:keys)
+        ArrayGroup.new(object.keys)
+      elsif object.respond_to?(:members)
+        ArrayGroup.new(object.members.map(&:to_s))
+      end
+    end
+
+    def flatten_list(object, *)
+      if array?(object)
+        new_object = []
+        object.each {|o| array?(o) ? (new_object += o) : new_object << o }
+        ArrayGroup.new(new_object)
+      else
+        []
+      end
+    end
+
+    private
+
+    def struct?(object)
+      Hash === object || Struct === object
+    end
+
+    def array?(object)
+      Array === object
+    end
+  end
+end