rbpath 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 31a72727369862168d205513377ef7f776ba1657
+  data.tar.gz: 8a67e07605cd5e5ef79f273fe31779e2eca9d6e6
+SHA512:
+  metadata.gz: 6be6653406797068a4afb74d5d4adad456fd98f576929c4c337149290288f079a54ad78ac3e7d567e776147abc2b22d8c5cfda107bcac4b9a6cd67f6fcb7d419
+  data.tar.gz: 100d805624f2ef1b0e24f4fc39361d3358ee1c77cc4c760726f701d407db3712f6a79af35847b7c303dd0942debc184aa5685093e02746fec3481228430d465b

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in jrel.gemspec
+gemspec
+
+gem 'pry'
+gem 'growl'
+gem 'guard'
+gem 'hirb'
+gem 'guard-minitest'

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+notification :growl
+
+guard :minitest do
+  watch(%r{^test/test_(.*)\.rb})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb})     { |m| "test/test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb})      { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Alex Skryl
+
+MIT License
+
+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,351 @@
+# RbPath
+
+RbPath is a small library for finding and retrieving data in large Ruby
+collections (Arrays/Hashes) and object graphs, similar to XPath and CSS
+selectors. You might use it over XPath or something similar because it's
+super lightweight and may do exactly what you need without the complex
+semantics of XPath or CSS selectors. It also makes operations such as regular
+expression filtering much easier to use.
+
+
+## Table of contents
+
+ - [Installation](#installation)
+ - [Usage](#usage)
+ - [Queries](#queries)
+  - [Literals](#literals)
+  - [Wildcards](#wildcards)
+  - [Logic Expressions](#logic-expressions)
+  - [Regex Matching](#regex-matching)
+  - [Gotchas](#gotchas)
+ - [Working with JSON/YAML/XML](#working-with-jsonyamlxml)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rbpath'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rbpath
+
+## Usage
+
+### Direct
+
+You can use the query engine directly through the Query class.
+
+```ruby
+require 'rbpath'
+
+h = {...}
+
+RbPath::Query.new(...).query(h)
+```
+
+### Object Mixin
+
+You can add the query interface to an existing instance of a Hash or Array.
+
+```ruby
+require 'rbpath'
+
+h = {...}
+h.extend RbPath
+
+h.query(...)
+```
+
+### Class Mixin
+
+You can make your own objects queryable by using the RbPath mixin.
+
+```ruby
+require 'rbpath'
+
+class Person < Struct.new(:first, :middle, :last, :age, :relatives)
+  include RbPath
+
+  rbpath :first, :middle, :last, :age, :relatives
+end
+
+p = Person.new('john', 'michael', 'doe', 21, [relative1,...])
+
+p.query(...)
+```
+
+Notice that the rbpath attributes must be explicitly listed.
+
+## Queries
+
+Queries are similar to XPath expressions. They are used to navigate and find
+information in tree-like data structures.
+
+```ruby
+class Employee < Struct.new(:first, :last, :position)
+  include RbPath
+  rbpath :first, :last, :position
+end
+
+data = {
+  illinois: {
+    chicago: {
+      inventory: {
+        bakery: { white: 220, whole_wheat: 150, multigrain: 72, rye: 27 },
+        fish:   { salmon: 110, tuna: 115, flounder: 22, catfish: 90, cod: 15 },
+        meat:   { ribeye: 23, pork_chop: 19, pork_loin: 12, beef_brisket: 30 }},
+      employees: [
+        Employee.new("John", "Sansk",   "General Manager"),
+        Employee.new("Gene", "Pollack", "Warehouse Manager"),
+        Employee.new("Luke", "Sanders", "Director")],
+      address: '101 Big St',
+      services: [:pharmacy, :bakery, :groceries, :kids_corner, :pet_grooming]
+    },
+    springfield: {
+      inventory: {
+        fish:   { salmon: 101, trout: 97, snapper: 172, catfish: 17, cod: 93 },
+        meat:   { ribeye: 13, chuck_roast: 82, flank_steak: 73, beef_brisket: 30 }},
+      employees: [
+        Employee.new("Kerry",  "Adams",  "General Manager"),
+        Employee.new("Sherry", "Nerst",  "Warehouse Manager"),
+        Employee.new("Kate",   "Holmes", "Director")],
+      address: '220 Small St',
+      services: [:groceries, :kids_corner]
+    }
+  }
+}
+
+data.extend RbPath
+```
+
+The sample data above represents a chain of grocery stores and their employees.
+We will see how RbPath can extract useful information from this set of data.
+
+
+### Literals
+
+The result of a *query* call will always be a list values that satisfy it, or
+an empty list if no matching values were found. There is also an analagous
+*pquery* interface which, instead of returning the values themselves, will
+return the paths to the values (or an empty list). Calling *path_values* on the
+result of *pquery* is the same as calling *query* directly.
+
+To make the examples more concise, only results from the *pquery* call will be
+provided in later examples.
+
+```ruby
+# Xpath: /illinois/chicago
+
+> data.query("illinois chicago")
+=> [{inventory: {...}, employees: [...], address: "...", services: [...]}]
+
+> data.pquery("illinois chicago")
+=> [['illinois','chicago']]
+
+> data.path_values( data.pquery("illinois chicago") )
+=> [{inventory: {...}, employees: [...], address: "...", services: [...]}]
+
+# Xpath: /california/san_francisco
+
+> data.query("california san_francisco")
+=> []
+
+> data.pquery("california san_francisco")
+=> []
+```
+
+Notice that the elements are seperated by **spaces** instead of slashes, and rbpath
+queries are **absolute** by default.
+
+Because the access semantics for Ruby collections (Arrays vs Hashes vs Objects)
+are inherently different, queries into Arrays will have numerical indices
+while queries into Hashes and RbPath objects will usually have string
+indices, much like in XPath.
+
+``` ruby
+# Xpath: /illinois/chicago/services[1]
+
+> data.pquery("illinois chicago services 0")
+=> [['illinois','chicago','services','0']]
+```
+
+Results to absolute queries aren't very interesting though, since they only
+return a single match. Other queries can return multiple matching paths.
+
+### Wildcards
+
+The star in the query below represents a **wildcard** match. It allows us to
+match more than one value at a particular depth in the tree.
+
+```ruby
+# XPath: /illinois/*/employees
+
+> data.pquery("illinois * employees")
+=> [['illinois','chicago','employees'],
+      ['illinois','springfield','employees']]
+```
+
+Wildcards can also be span across multiple levels of the tree, in case you
+don't know how deep your value lives. These **multi-level wildcards** will reach
+across 0 or more depth levels.
+
+```ruby
+# XPath: //illinois
+
+> data.pquery("** illinois")
+=> [['illinois']]
+
+# XPath: //employees
+
+> data.pquery("** employees")
+=> [['illinois','employees'],
+      ['illinois','chicago','employees'],
+      ['illinois','springfield','employees']]
+
+```
+
+Notice that paths of differnt lengths may be returned in the resulting set when
+using multi-level wildcards.
+
+### Logic Expressions
+
+In addiction to wildcards, there is another, more restrictive, way to match
+several paths at once using **AND** and **NOR** expressions.
+
+```ruby
+# XPath: /illinois/chicago/inventory/*/salmon | /illinois/chicago/inventory/*/pork_chop
+
+> data.pquery("illinois chicago inventory * (salmon,pork_chop)")
+=> [['illinois','chicago','inventory','fish','salmon'],
+      ['illinois','chicago','inventory','meat','pork_chop']]
+```
+
+The above query will select all the inventory paths in the chicago store that
+match 'salmon' **AND** 'pork_chop' for any of the departments. We can also
+achieve the opposite effect by using a **NOR** expression and specifying  a
+list of values to avoid matching.
+
+```ruby
+# XPath: /illinois/chicago/inventory/fish[not(contains(salmon)) and not(contains(tuna))]
+
+> data.pquery("illinois chicago inventory fish [salmon,tuna]")
+=> [['illinois','chicago','inventory','fish','flounder'],
+      ['illinois','chicago','inventory','fish','catfish'],
+      ['illinois','chicago','inventory','fish','cod']]
+```
+
+This query gives us all the fish in the chicago store which **do not match**
+'salmon' or 'tuna'.
+
+### Regex Matching
+
+It's not always enough to be able to filter on an exact field/key name.
+Sometimes you only know part of the name or you want to match all the names
+that match a certain pattern. This is where regular expressions come in handy.
+
+You can include plain old ruby regexes in your quries by splitting the query up
+into multiple arguments. In this case the query will will still be processed as
+though it was continuous.
+
+```ruby
+> data.pquery("illinois chicago inventory meat", /(pork.*|beef.*)/)
+=> [['illinois','chicago','inventory','meat','pork_chop'],
+      ['illinois','chicago','inventory','meat','pork_loin'],
+      ['illinois','chicago','inventory','meat','beef_brisket']]
+
+> data.pquery("illinois", /(chi.*|spr.*)/, "inventory *")
+=> [['illinois','chicago','inventory','bakery'],
+      ['illinois','chicago','inventory','fish'],
+      ['illinois','chicago','inventory','meat'],
+      ['illinois','springfield','inventory','fish'],
+      ['illinois','springfield','inventory','meat']]
+```
+
+XPath 1.0 doesn't actually support regular expressions, but it does provide some
+[specialized functions](http://www.w3.org/TR/xpath/#function-starts-with) for
+partially matching element names such as *starts-with()* and *contains()*.
+
+### Gotchas
+
+Sometimes you may need to find strings with spaces or things which are not
+strings at all. Here is how you do that.
+
+Single quote your string or use a regex matcher when your filter string
+contains spaces.
+
+```ruby
+> data.pquery("* * employees * position 'General Manager'")
+=> [['illinois','chicago','employees','0','position','General Manager'],
+      ['illinois','chicago','employees','0','position','General Manager']]
+
+> data.pquery("* * employees 0 position", /General Manager/)
+=> [['illinois','chicago','employees','0','position','General Manager'],
+      ['illinois','chicago','employees','0','position','General Manager']]
+```
+
+Split up queries that use non-String filters into multiple arguments, just like
+we did with regular expressions.
+
+```ruby
+> data.pquery("* * inventory * *", 30)
+=> [['illinois','chicago','inventory','meat','beef_brisket',30],
+      ['illinois','springfield','inventory','meat','beef_brisket',30]]
+```
+
+## Working With JSON/YAML/XML
+
+You can use the **rq** command (which is installed with the gem) from your
+shell to query JSON, YAML and XML files using the RbPath engine, but you
+will not be able to match regular expressions or non-string values due to the
+limitations of the query parser.
+
+```bash
+Usage: rq [OPTIONS] QUERY
+    -f, --file  [FILE]       File to parse
+    -t, --type  [TYPE]       File format
+    -p, --paths              Paths only
+    -h, --help               Show usage
+```
+
+- If you don't supply the *file* option then data will be read from STDIN.
+- The *paths* option will mimic the *pquery* interface shown in the examples.
+
+```bash
+# read from a file
+$ rq -f data.json '** john **'
+
+# read from STDIN
+$ curl http://myservice.com/api/1.json | rq -t json '** john **'
+```
+
+### XML
+
+The [xml-simple](http://rubygems.org/gems/xml-simple) gem is used to convert
+xml files to Ruby hashes prior to processing, so it must be installed if you
+want to query XML files.
+
+```bash
+gem install xml-simple
+```
+
+### Pretty Printer
+
+Installing the [hirb](http://rubygems.org/gems/hirb) gem will tabularize
+certain types of output, making it much easier to read.
+
+```bash
+gem install hirb
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/TODO.md

@@ -0,0 +1,7 @@
+# TODO
+- explain leaf vs path value matching in readme
+- paths should be returned with array indices as integers
+- handle nil and false keys/values properly
+- deep_stringify_all is too costly
+- test all README examples
+- add rq tests

data/bin/rq

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+GC.disable # short lived process doesn't need gc
+
+lib = "#{File.expand_path(File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__)}/../../lib"
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require 'optparse'
+require 'rbpath'
+require 'pp'
+
+begin
+  require 'hirb'
+rescue LoadError
+end
+
+options = {}
+optparse = OptionParser.new do |opts|
+  opts.banner = "Usage: rq [OPTIONS] QUERY"
+
+  opts.on("-f", "--file [FILE]",  "File to parse") { |opt| options[:file]  = opt }
+  opts.on("-t", "--type [TYPE]",  "File format")   { |opt| options[:type]  = opt }
+  opts.on("-p", "--paths",        "Paths only")    { |opt| options[:paths] = true}
+  opts.on("-h", "--help", "Show usage")            { puts opts; exit }
+end
+
+begin
+  optparse.parse!(ARGV)
+  query      = ARGV.shift.to_s
+  file, type = options.values_at(:file, :type)
+  content    = (file && File.read(file)) || ARGF.read
+  extension  = type || (file && File.extname(file)[1..-1]) || 'json'
+
+  raise OptionParser::MissingArgument unless query
+
+  data = \
+    case extension
+    when 'yml', 'yaml'
+      require 'yaml'
+      YAML.load(content)
+    when 'jsn', 'json'
+      require 'json'
+      JSON.parse(content)
+    when 'xml'
+      require 'xmlsimple'
+      XmlSimple.xml_in(content, 'ForceArray' => false)
+    end
+
+rescue LoadError
+    puts "You are probably missing the 'xml-simple' gem, install it by running 'gem install xml-simple' and try again."
+    exit
+rescue OptionParser::MissingArgument
+    puts optparse.help
+    exit
+rescue Exception => e
+    puts "Error: #{e}"
+    exit
+end
+
+result = RbPath::Query.new(query).send(options[:paths] ? :pquery : :query, data)
+
+if options[:paths]
+  defined?(Hirb)
+  puts(Hirb::Helpers::AutoTable.render(result))
+else puts result.map(&:pretty_inspect)
+end

data/lib/rbpath.rb

@@ -0,0 +1,17 @@
+require "rbpath/version"
+
+module RbPath
+  autoload :Query, 'rbpath/query'
+  autoload :Utils, 'rbpath/utils'
+  autoload :ObjectMixin, 'rbpath/object_mixin'
+  autoload :ClassMixin,  'rbpath/class_mixin'
+
+  def self.included(klass)
+    klass.send(:include, RbPath::ObjectMixin)
+    klass.extend RbPath::ClassMixin
+  end
+
+  def self.extended(obj)
+    obj.singleton_class.send(:include, RbPath::ObjectMixin)
+  end
+end

data/lib/rbpath/class_mixin.rb

@@ -0,0 +1,11 @@
+module RbPath::ClassMixin
+
+  def rbpath(*fields)
+    @_rbpath_fields_ = fields.map(&:to_s)
+  end
+
+  def rbpath_fields
+    @_rbpath_fields_
+  end
+
+end

data/lib/rbpath/object_mixin.rb

@@ -0,0 +1,26 @@
+module RbPath::ObjectMixin
+
+  def query(*query)
+    RbPath::Query.new(*query).query(self)
+  end
+
+  def pquery(*query)
+    RbPath::Query.new(*query).pquery(self)
+  end
+
+  def path_values(paths)
+    RbPath::Query.new(*query).values_at(self, paths)
+  end
+
+  # The object's class may not have the ClassMixin if a singleton object
+  # was extended:
+  #
+  # h = { a: 1, b: 2}
+  # h.extend RbPath
+  #
+  def rbpath_fields
+    self.class.respond_to?(:rbpath_fields) ?
+      self.class.rbpath_fields : nil
+  end
+
+end

data/lib/rbpath/query.rb

@@ -0,0 +1,105 @@
+class RbPath::Query
+  include RbPath::Utils
+
+  # takes a string query or a pre-parsed query list
+  #
+  def initialize(*query)
+    @query = parse_query_list(query)
+  end
+
+  # Parsing rules:
+  # - query keys are seperated by spaces, keys with spaces must be single quoted
+  # - brackets group keys into an NOR group
+  # - parens group keys into a OR group
+  # - valid keys names consist of [chars|nums|spaces|-|_|.], anything else can
+  #   be used as a seperator inside the parens/brackets
+  #
+  def parse_string_query(query)
+    query.scan(/(\([^\)]+\)|\[[^\]]+\]|'[^']+'|[^\s]+)/)
+         .flatten
+         .map { |keys| { multi: /\*\*/ === keys[0..1],
+                         neg:  /[\[\*]/ === keys[0],
+                         keys: keys.scan(/[\w\d\s\-\_\.]+/) }}
+  end
+
+  def parse_query_list(query)
+    query.flat_map do |part|
+      case part
+      when String, Symbol
+        parse_string_query(part.to_s)
+      when Regexp
+        {multi: false, neg: false, keys: [], regexp: part}
+      else {multi: false, neg: false, keys: [part]}
+      end
+    end
+  end
+
+  def query(data)
+    data = deep_stringify_all(data)
+    do_query(data, @query, [[]]).map(&:flatten)
+                                .map { |path| get_value(data, path) }
+  end
+
+  def pquery(data)
+    do_query(deep_stringify_all(data), @query, [[]]).map(&:flatten)
+  end
+
+  def values_at(data, paths)
+    paths.map {|path| get_value(deep_stringify_all(data), path) }
+  end
+
+private
+
+  def do_query(data, query, valid_paths)
+    matcher, *rest = *query
+
+    if query.empty? || valid_paths.empty?
+      valid_paths
+    elsif matcher[:multi]
+       do_query(data, rest, valid_paths) +
+         do_query(data, query, match(data, matcher, valid_paths))
+    else
+      do_query(data, rest, match(data, matcher, valid_paths))
+    end
+  end
+
+  def match(data, matcher, valid_paths)
+    neg, keys, rgx = matcher.values_at(:neg, :keys, :regexp)
+
+    valid_paths.flat_map { |path| children = if rgx
+                                      all_keys(data, path).grep(rgx)
+                                    elsif neg
+                                      (all_keys(data, path) - keys)
+                                    else keys; end
+                                  [path].product(children).map(&:flatten) } \
+               .select   { |path| get_value(data, path) }
+  end
+
+  def all_keys(data, path)
+    value = get_value(data, path)
+
+    case value
+    when Hash  then value.keys
+    when Array then (0...value.size).map(&:to_s)
+    when RbPath
+      value.rbpath_fields
+    else [value]
+    end
+  end
+
+  def get_value(data, path)
+    return data if path.empty?
+    key, *rest = *path
+
+    case data
+    when Hash
+      get_value(data[key], rest)
+    when Array
+      get_value(data[Integer(key)], rest) rescue nil
+    when RbPath
+      get_value(data.send(key), rest) if data.respond_to?(key)
+    when key
+      rest.empty? ? data : nil
+    end
+  end
+end

data/lib/rbpath/utils.rb

@@ -0,0 +1,20 @@
+module RbPath::Utils
+  def deep_transform_all(obj, &block)
+    case obj
+    when Hash
+      Hash[ obj.map { |k,v| [deep_transform_all(k, &block),
+                             deep_transform_all(v, &block)] }]
+    when Array
+      obj.map { |i| deep_transform_all(i, &block) }
+    else block[obj]
+    end
+  end
+
+  def deep_stringify_all(obj)
+    deep_transform_all(obj) { |obj| obj.is_a?(Symbol) ? obj.to_s : obj }
+  end
+
+  def deep_symbolize_all(obj)
+    deep_transform_all(obj) { |obj| obj.is_a?(String) ? obj.to_sym : obj }
+  end
+end

data/lib/rbpath/version.rb

@@ -0,0 +1,3 @@
+module RbPath
+  VERSION = "0.2.3"
+end

data/rbpath.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rbpath/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rbpath"
+  spec.version       = RbPath::VERSION
+  spec.authors       = ["Alex Skryl"]
+  spec.email         = ["rut216@gmail.com"]
+  spec.description   = %q{A lightweight library for running XPath like queries on Ruby collections and object graphs.}
+  spec.summary       = %q{A lightweight library for running XPath like queries on Ruby collections and object graphs}
+  spec.homepage      = "http://github.com/skryl/rbpath"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/test/data/test_data.rb

@@ -0,0 +1,48 @@
+require_relative '../test_helper'
+
+module TestData
+  class Employee < Struct.new(:first, :last, :position)
+    include RbPath
+    rbpath :first, :last, :position
+  end
+
+  STORE_DATA =
+    {
+      illinois: {
+        employees: [
+          Employee.new("Kerry",  "Adams",  "District Manager")],
+        chicago: {
+          inventory: {
+            apples: { granny_smith: 150, gala: 200, cameo: 150, honeycrisp: 75 },
+            bread:  { white: 220, whole_wheat: 150, multigrain: 72, rye: 27 },
+            fish:   { salmon: 110, tuna: 115, flounder: 22, catfish: 90, cod: 15 },
+            meat:   { ribeye: 23, pork_chop: 19, pork_loin: 12, beef_brisket: 30 },
+            nuts:   { brazil: 200, pecan: 173, almond: 37, cashew: 12, chestnut: 70 },
+            shrimp: { arctic: 120, fresh_water: 20, atlantic: 72 } },
+          employees: [
+            Employee.new("John", "Sansk", "General Manager"),
+            Employee.new("Sam", "Bogert", "Checkout Manager"),
+            Employee.new("Gene", "Pollack", "Warehouse Manager"),
+            Employee.new("Shane", "Leson", "Human Resources") ],
+          address: '101 Big St',
+          services: [:pharmacy, :groceries, :salon, :kids_corner, :pet_grooming]
+        },
+        springfield: {
+          inventory: {
+            apples: { golden_delicious: 220, fuji: 110, cameo: 101, honeycrisp: 75 },
+            bread:  { white: 220, whole_wheat: 150, multigrain: 72, rye: 27 },
+            fish:   { salmon: 101, trout: 97, snapper: 172, catfish: 17, cod: 93 },
+            meat:   { ribeye: 13, chuck_roast: 82, flank_steak: 73, beef_brisket: 30 },
+            nuts:   { mixed: 211, pistachio: 75, almond: 370, cashew: 121, trail_mix: 92},
+            shrimp: { uncooked: 252, fresh_water: 72, atlantic: 93 } },
+          employees: [
+            Employee.new("Kerry",  "Adams",  "General Manager"),
+            Employee.new("Jack", "Lenere", "Checkout Manager"),
+            Employee.new("Sherry", "Nerst", "Warehouse Manager"),
+            Employee.new("Ken", "Beson", "Human Resources") ],
+          address: '220 Small St',
+          services: [:groceries, :kids_corner]
+        }
+      }
+    }
+end

data/test/extensions/match_array.rb

@@ -0,0 +1,57 @@
+module MiniTest::Assertions
+
+  class MatchArray
+    def initialize(expected, actual)
+      @expected = expected
+      @actual = actual
+    end
+
+    def match()
+      return result, message
+    end
+
+    def result()
+      return false unless @actual.respond_to? :to_ary
+      @extra_items = difference_between_arrays(@actual, @expected)
+      @missing_items = difference_between_arrays(@expected, @actual)
+      @extra_items.empty? & @missing_items.empty?
+    end
+
+    def message()
+      if @actual.respond_to? :to_ary
+        message = "expected collection contained: #{safe_sort(@expected).inspect}\n"
+        message += "actual collection contained: #{safe_sort(@actual).inspect}\n"
+        message += "the missing elements were: #{safe_sort(@missing_items).inspect}\n" unless @missing_items.empty?
+        message += "the extra elements were: #{safe_sort(@extra_items).inspect}\n" unless @extra_items.empty?
+      else
+        message = "expected an array, actual collection was #{@actual.inspect}"
+      end
+
+      message
+    end
+
+    private
+
+    def safe_sort(array)
+      array.sort rescue array
+    end
+
+    def difference_between_arrays(array_1, array_2)
+      difference = array_1.to_ary.dup
+      array_2.to_ary.each do |element|
+        if index = difference.index(element)
+          difference.delete_at(index)
+        end
+      end
+      difference
+    end
+  end # MatchArray
+
+  def assert_match_array(expected, actual)
+    result, message = MatchArray.new(expected, actual).match
+    assert result, message
+  end
+
+end # MiniTest::Assertions
+
+Array.infect_an_assertion :assert_match_array, :must_match_array

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.require(:default)
+
+require 'json'
+require 'yaml'
+require 'set'
+require 'minitest/autorun'
+require 'minitest/pride'
+
+# extend minitest to support out of order array matches
+#
+require_relative 'extensions/match_array'

data/test/test_query.rb

@@ -0,0 +1,360 @@
+require_relative 'test_helper'
+require_relative 'data/test_data'
+
+describe RbPath::Query do
+  before do
+    @store_data = TestData::STORE_DATA
+  end
+
+  describe 'query parsing' do
+
+    describe "single string queries" do
+
+      it 'should identify a single key' do
+        RbPath::Query.new("some_key").instance_variable_get('@query').must_equal \
+          [{multi: false, neg: false, keys: ['some_key']}]
+      end
+
+      it 'should identify a list of keys' do
+        RbPath::Query.new("one two three").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: false, keys: ['two']},
+            {multi: false, neg: false, keys: ['three']} ]
+      end
+
+      it 'should identify list of keys with quoted spaces' do
+        RbPath::Query.new("one 'two and a half' three").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: false, keys: ['two and a half']},
+            {multi: false, neg: false, keys: ['three']} ]
+      end
+
+      it 'should identify ORed keys in a list' do
+        RbPath::Query.new("one (two,three,four) ('twenty two','forty three')").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: false, keys: ['two','three','four']},
+            {multi: false, neg: false, keys: ['twenty two', 'forty three']} ]
+      end
+
+      it 'should identify NORed keys in a list' do
+        RbPath::Query.new("one [two,three,four] ['fifty five','sixty six']").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: true,  keys: ['two','three','four']},
+            {multi: false, neg: true, keys: ['fifty five', 'sixty six']} ]
+      end
+
+      it 'should identify splats' do
+        RbPath::Query.new("one [] (two,three) * four").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: true,  keys: []},
+            {multi: false, neg: false, keys: ['two', 'three']},
+            {multi: false, neg: true,  keys: []},
+            {multi: false, neg: false, keys: ['four']} ]
+      end
+
+      it 'should identify multi-splats' do
+        RbPath::Query.new("one [] (two,three) ** four").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: true,  keys: []},
+            {multi: false, neg: false, keys: ['two', 'three']},
+            {multi: true,  neg: true,  keys: []},
+            {multi: false, neg: false, keys: ['four']} ]
+      end
+
+      it 'should just work' do
+        RbPath::Query.new("one [] ('twenty two',three) * () four [five,'sixty five'] 'seventy two' *").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: true,  keys: []},
+            {multi: false, neg: false, keys: ['twenty two', 'three']},
+            {multi: false, neg: true,  keys: []},
+            {multi: false, neg: false, keys: []},
+            {multi: false, neg: false, keys: ['four']},
+            {multi: false, neg: true,  keys: ['five', 'sixty five']},
+            {multi: false, neg: false, keys: ['seventy two']},
+            {multi: false, neg: true,  keys: []} ]
+      end
+    end
+
+    describe "multipart queries" do
+
+      it 'should accept a multipart query and convert symbols to strings' do
+        RbPath::Query.new(:one, 'two', :three).instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: false, keys: ['two']},
+            {multi: false, neg: false, keys: ['three']} ]
+      end
+
+      it 'should not convert other objects to strings in a multipart query' do
+        RbPath::Query.new(:one, 2, 'three', nil).instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: false, keys: [2]},
+            {multi: false, neg: false, keys: ['three']},
+            {multi: false, neg: false, keys: [nil]} ]
+      end
+
+      it 'should seperately parse all parts of a multipart query' do
+        RbPath::Query.new("one (two,three)", :four, "[five,six] seven", "'eighty nine'").instance_variable_get('@query').must_equal \
+          [ {multi: false, neg: false, keys: ['one']},
+            {multi: false, neg: false, keys: ['two','three']},
+            {multi: false, neg: false, keys: ['four']},
+            {multi: false, neg: true,  keys: ['five','six']},
+            {multi: false, neg: false, keys: ['seven']},
+            {multi: false, neg: false, keys: ['eighty nine']} ]
+      end
+    end
+  end
+
+  describe 'query engine' do
+
+    describe 'literal queries' do
+
+      it 'should work on hashes and their leaf values' do
+        RbPath::Query.new("illinois chicago inventory apples gala", 200).pquery(@store_data).must_match_array \
+          [['illinois', 'chicago', 'inventory', 'apples', 'gala', 200]]
+      end
+
+      it 'should work on arrays and their leaf values' do
+        RbPath::Query.new("illinois chicago services 0 pharmacy").pquery(@store_data).must_match_array \
+          [['illinois', 'chicago', 'services', '0', 'pharmacy']]
+      end
+
+      it 'should work on rbpath objects and their leaf values' do
+        RbPath::Query.new("illinois chicago employees 0 last Sansk").pquery(@store_data).must_match_array \
+          [['illinois', 'chicago', 'employees', '0', 'last', 'Sansk']]
+      end
+
+      # leaf values should not be included in the main query if they are not strings
+      #
+      it 'should not match stringified leaf values' do
+        RbPath::Query.new("illinois chicago inventory apples gala 200").pquery(@store_data).must_match_array []
+      end
+
+    end
+
+    describe 'splat queries' do
+
+      it 'should work on leaf values' do
+        RbPath::Query.new("illinois chicago inventory apples gala *").pquery(@store_data).must_match_array \
+          [['illinois', 'chicago', 'inventory', 'apples', 'gala', 200]]
+      end
+
+      it 'should work on hashes' do
+        RbPath::Query.new("* * *").pquery(@store_data).must_match_array \
+          [["illinois", "employees", "0"],
+           ["illinois", "chicago", "inventory"],
+           ["illinois", "chicago", "employees"],
+           ["illinois", "chicago", "address"],
+           ["illinois", "chicago", "services"],
+           ["illinois", "springfield", "inventory"],
+           ["illinois", "springfield", "employees"],
+           ["illinois", "springfield", "address"],
+           ["illinois", "springfield", "services"]]
+      end
+
+
+      it 'should work on arrays' do
+        RbPath::Query.new("* chicago services *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0"],
+           ["illinois", "chicago", "services", "1"],
+           ["illinois", "chicago", "services", "2"],
+           ["illinois", "chicago", "services", "3"],
+           ["illinois", "chicago", "services", "4"]]
+      end
+
+      it 'should work on rbpath objects' do
+        RbPath::Query.new("* chicago employees 0 *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "employees", "0", "first"],
+           ["illinois", "chicago", "employees", "0", "last"],
+           ["illinois", "chicago", "employees", "0", "position"]]
+      end
+
+    end
+
+    describe 'OR queries' do
+
+      it 'should work on hashes' do
+        RbPath::Query.new("illinois chicago (services,employees) *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0"],
+           ["illinois", "chicago", "services", "1"],
+           ["illinois", "chicago", "services", "2"],
+           ["illinois", "chicago", "services", "3"],
+           ["illinois", "chicago", "services", "4"],
+           ["illinois", "chicago", "employees", "0"],
+           ["illinois", "chicago", "employees", "1"],
+           ["illinois", "chicago", "employees", "2"],
+           ["illinois", "chicago", "employees", "3"]]
+      end
+
+      it 'should work on arrays' do
+        RbPath::Query.new("illinois chicago services (0,1) *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0", "pharmacy"],
+           ["illinois", "chicago", "services", "1", "groceries"]]
+      end
+
+      it 'should work on rbpath objects' do
+        RbPath::Query.new("illinois chicago employees * (first,last) *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "employees", "0", "first", "John"],
+           ["illinois", "chicago", "employees", "0", "last", "Sansk"],
+           ["illinois", "chicago", "employees", "1", "first", "Sam"],
+           ["illinois", "chicago", "employees", "1", "last", "Bogert"],
+           ["illinois", "chicago", "employees", "2", "first", "Gene"],
+           ["illinois", "chicago", "employees", "2", "last", "Pollack"],
+           ["illinois", "chicago", "employees", "3", "first", "Shane"],
+           ["illinois", "chicago", "employees", "3", "last", "Leson"]]
+      end
+    end
+
+    describe 'NOR queries' do
+
+      it 'should work on hashes' do
+        RbPath::Query.new("illinois chicago [inventory,address] *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0"],
+           ["illinois", "chicago", "services", "1"],
+           ["illinois", "chicago", "services", "2"],
+           ["illinois", "chicago", "services", "3"],
+           ["illinois", "chicago", "services", "4"],
+           ["illinois", "chicago", "employees", "0"],
+           ["illinois", "chicago", "employees", "1"],
+           ["illinois", "chicago", "employees", "2"],
+           ["illinois", "chicago", "employees", "3"]]
+      end
+
+      it 'should work on arrays' do
+        RbPath::Query.new("illinois chicago services [2,3,4] *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0", "pharmacy"],
+           ["illinois", "chicago", "services", "1", "groceries"]]
+      end
+
+      it 'should work on rbpath objects' do
+        RbPath::Query.new("illinois chicago employees * [position] *").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "employees", "0", "first", "John"],
+           ["illinois", "chicago", "employees", "0", "last", "Sansk"],
+           ["illinois", "chicago", "employees", "1", "first", "Sam"],
+           ["illinois", "chicago", "employees", "1", "last", "Bogert"],
+           ["illinois", "chicago", "employees", "2", "first", "Gene"],
+           ["illinois", "chicago", "employees", "2", "last", "Pollack"],
+           ["illinois", "chicago", "employees", "3", "first", "Shane"],
+           ["illinois", "chicago", "employees", "3", "last", "Leson"]]
+      end
+    end
+
+    describe 'REGEX queries' do
+
+      it 'should work on hashes' do
+        RbPath::Query.new("illinois chicago inventory meat", /(pork.*|beef.*)/).pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "inventory", "meat", "pork_chop"],
+           ["illinois", "chicago", "inventory", "meat", "pork_loin"],
+           ["illinois", "chicago", "inventory", "meat", "beef_brisket"]]
+      end
+
+      it 'should work on arrays' do
+        RbPath::Query.new("illinois chicago services", /[01]/, "*").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0", "pharmacy"],
+           ["illinois", "chicago", "services", "1", "groceries"]]
+      end
+
+      it 'should work on rbpath objects' do
+        RbPath::Query.new("illinois chicago employees *", /(first|last)/, /(Gene|Pollack)/).pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "employees", "2", "first", "Gene"],
+           ["illinois", "chicago", "employees", "2", "last", "Pollack"]]
+      end
+    end
+
+    describe 'Multilevel wildcard queries' do
+      it 'should match no elements' do
+        RbPath::Query.new("** illinois").pquery(@store_data).must_match_array \
+          [["illinois"]]
+      end
+
+      it 'should match leaf nodes' do
+        RbPath::Query.new("illinois chicago services 0 pharmacy **").pquery(@store_data).must_match_array \
+          [['illinois','chicago','services','0','pharmacy']]
+      end
+
+      it 'should match with multiple multi-wildcards' do
+        RbPath::Query.new("** chicago ** pharmacy").pquery(@store_data).must_match_array \
+          [['illinois','chicago','services','0','pharmacy']]
+      end
+
+      it 'should work on hashes' do
+        RbPath::Query.new("**", /(pork.*|beef.*)/).pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "inventory", "meat", "pork_chop"],
+           ["illinois", "chicago", "inventory", "meat", "pork_loin"],
+           ["illinois", "chicago", "inventory", "meat", "beef_brisket"],
+           ["illinois", "springfield", "inventory", "meat", "beef_brisket"]]
+      end
+
+      it 'should work on arrays' do
+        RbPath::Query.new("** services", /[01]/, "*").pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "services", "0", "pharmacy"],
+           ["illinois", "chicago", "services", "1", "groceries"],
+           ["illinois", "springfield", "services", "0", "groceries"],
+           ["illinois", "springfield", "services", "1", "kids_corner"]]
+      end
+
+      it 'should work on rbpath objects' do
+        RbPath::Query.new("**", /(first|last)/, /(Gene|Pollack)/).pquery(@store_data).must_match_array \
+          [["illinois", "chicago", "employees", "2", "first", "Gene"],
+           ["illinois", "chicago", "employees", "2", "last", "Pollack"]]
+      end
+    end
+  end
+
+  describe 'classes which include the RbPath mixin' do
+
+    before do
+      @employee = TestData::Employee.new('Alex', 'Skryl', 'CEO')
+      @employee_class = TestData::Employee.dup
+    end
+
+    it 'should be rbpath' do
+      @employee.must_be_kind_of(RbPath)
+    end
+
+    it 'should return its rbpath fields' do
+      @employee.rbpath_fields.must_equal ['first', 'last', 'position']
+      @employee.class.rbpath_fields.must_equal ['first', 'last', 'position']
+    end
+
+    it 'should be able to set rbpath fields' do
+      @employee_class.class_eval do
+        rbpath :one, :two, :three
+      end
+      @employee_class.rbpath_fields.must_equal ['one', 'two', 'three']
+      @employee_class.new.rbpath_fields.must_equal ['one', 'two', 'three']
+    end
+
+    it 'should have instances that are able to query themselves' do
+      @employee.must_respond_to(:pquery)
+      @employee.pquery("first *").must_equal [['first', 'Alex']]
+    end
+
+    it 'should have instances that are able to fetch values' do
+      @employee.must_respond_to(:path_values)
+      @employee.path_values([['first','Alex']]).must_equal ['Alex']
+    end
+  end
+
+  describe 'singletons which extend the RbPath mixin' do
+
+    before do
+      @hash = {first: 'Alex', last: 'Skryl', age: '100', address: '101 blah st'}
+      @hash.extend RbPath
+    end
+
+    it 'should be able to query itself' do
+      @hash.must_respond_to(:query)
+      @hash.pquery("first *").must_equal [['first', 'Alex']]
+    end
+
+    it 'should have instances that are able to fetch values' do
+      @hash.must_respond_to(:path_values)
+      @hash.path_values([['first','Alex']]).must_equal ['Alex']
+    end
+
+    it 'should have no rbpath fields' do
+      @hash.rbpath_fields.must_equal nil
+    end
+  end
+
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: rbpath
+version: !ruby/object:Gem::Version
+  version: 0.2.3
+platform: ruby
+authors:
+- Alex Skryl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A lightweight library for running XPath like queries on Ruby collections
+  and object graphs.
+email:
+- rut216@gmail.com
+executables:
+- rq
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO.md
+- bin/rq
+- lib/rbpath.rb
+- lib/rbpath/class_mixin.rb
+- lib/rbpath/object_mixin.rb
+- lib/rbpath/query.rb
+- lib/rbpath/utils.rb
+- lib/rbpath/version.rb
+- rbpath.gemspec
+- test/data/data.json
+- test/data/data.yaml
+- test/data/test_data.rb
+- test/extensions/match_array.rb
+- test/test_helper.rb
+- test/test_query.rb
+homepage: http://github.com/skryl/rbpath
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: A lightweight library for running XPath like queries on Ruby collections
+  and object graphs
+test_files:
+- test/data/data.json
+- test/data/data.yaml
+- test/data/test_data.rb
+- test/extensions/match_array.rb
+- test/test_helper.rb
+- test/test_query.rb