wherewolf 0.1.0 → 0.2.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ./
   specs:
-    wherewolf (0.1.0)
+    wherewolf (0.2.0)
       arel
       parslet
 

data/README.rdoc

@@ -1,30 +1,32 @@
 = wherewolf
 
+Makes adding filtering and searching to your REST API crazy easy.
+
 == Problem
 
 Most RESTful APIs expose a "/index" endpoint that return all of objects at a given endpoint. That is fine until you need the ability to filter them.
 
 Consider the following scenario:
 
-    /companies.json Return all the companies.
+    /players.json 
 
-But what if I want only companies that are active? Most developers would simply add a query parameter like so:
+But what if I want only players that are active? Most developers would simply add a query parameter like so:
 
-    /companies.json?active=true
+    /players.json?active=true
 
-Ok, now what if you only want companies created after the first of January 2012? Maybe:
+Ok, now what if you only want players capped after the first of January 2012? Maybe:
 
-    /companies.json?created_after=2012-01-01
+    /players.json?first_cap=2012-01-01
 
 Yeah, great - but it doesn't really scale. Wouldn't if be better if we could do something like this?
 
-    /companies.json?where=active%20%3D%20true%20%26%26%20created_at%20%3E%3D%202012-01-01
+    /players.json?where=active%20%3D%20true%20%26%26%20first_cap%20%3E%3D%202012-01-01
 
-Ok, it doesn't read amazingly, but this is an API, so encoding that stuff is trivial for the client. For those of you that doesn't speak URI-coded string that is the same as:
+Ok, it doesn't read amazingly, but this is an API, so encoding that stuff is trivial for the client. For those of you that doesn't speak URI-encoded string that is the same as:
 
-    active = true && created_at >= 2012-01-01
+    active = true && first_cap >= 2012-01-01
 
-Wherewolf will take that string and converts it in to AREL, so your clients can run arbitary queries against your API.
+Wherewolf will take that string and converts it in to ARel, so your clients can run arbitary queries against your API.
 
 == Get started
 
@@ -32,29 +34,70 @@ The easiest way is to use Bundler:
 
     gem 'wherewolf'
 
-== Where we are at
+Then for every model that you want to by queryable, do this:
 
-What Works:
-    
-* &&
-* ||
-* =
-* !=
-* <
-* <=
-* >
-* >=
-* Parenthesis
-
-Need to implement:
-    
-* Aliases such for operators, such as 'and', 'or' etc
-* Allow from_query to nested (ie Player.where('first_cap < 2000-01-01').from_query('active = true')
-* More edge case testing
+    class Player < ActiveRecord::Base
+      has_query_parsing
+    end
+
+This will add the "from_query" method, which you pass your query string in to.
 
 == Example
 
+For a real-life, running example, check out: http://wherewolf.herokuapp.com/
+
     player = Player.from_query("(position = wing || position = lock) && first_cap < 1905-01-01").order('first_cap')
+    # Returns all players that play 'wing' or 'lock', and played before 1905-01-01
+
+    player = Player.from_query('name = "John Eales"')
+    # Returns all players names 'John Eales'
+
+    player = Player.from_query("first_cap >= 1905-01-01 && active = false")
+    # Returns all inactitve players that played after 1905-01-01.
+
+    player = Player.from_query("first_cap != null")
+    # Returns all players who have received their first cap (ie first_cap is NOT nil)
+    
+    player = Player.from_query('name ~= "Peter%"')
+    # Returns all players who's name starts with Peter
+
+As you can see, from_query returns an ARel object, so you chain other statements to it. Please note, though: at the moment from_query needs to be the first in the chain. 
+
+== Errors
+
+At the moment, error handling is very primitive. Just capture
+
+    Wherewolf::ParseError
+
+You can print out a simple error message like so
+
+    begin
+      Player.from_query('name ~= "Patrick%" || (position = "fail)')
+    rescue Wherewolf::ParseError => e
+      puts e.error_message
+    end
+
+Will print out
+
+    Parsing error occured at character 28
+
+You can get the character number by:
+
+    begin
+      Player.from_query('name ~= "Patrick%" || (position = "fail)')
+    rescue Wherewolf::ParseError => e
+      e.position # This value will be 28
+    end
+
+== To Do
+
+* Better error messages (Give a clue as to why parsing failed)
+* Aliases such for operators, such as 'and', 'or' etc
+* Allow single quotes around strings
+* Allow from_query to nested (ie Player.where('first_cap < 2000-01-01').from_query('active = true')
+* More edge case testing
+* Abillity to filter columns that are searchable
+* Ability to call named scopes
 
 == Contributing to wherewolf
  

data/Rakefile

@@ -18,11 +18,11 @@ Jeweler::Tasks.new do |gem|
   gem.name = "wherewolf"
   gem.homepage = "http://github.com/madpilot/wherewolf"
   gem.license = "MIT"
-  gem.summary = %Q{Query parser that converts search terms to AREL for use in APIs}
-  gem.description = %Q{Wherewolf allows you to consume search terms as strings without worrying about database injections. It parses the query and converts it into AREL. It's great for creating filterable REST APIs}
+  gem.summary = %Q{Makes filtering and searching to your REST API crazy easy.}
+  gem.description = %Q{Wherewolf allows you to consume search terms as strings without worrying about database injections. It parses the query and converts it into ARel. It's great for creating filterable REST APIs.}
   gem.email = "myles@madpilot.com.au"
   gem.authors = ["Myles Eftos"]
-  gem.version = "0.1.0"
+  gem.version = "0.2.0"
   # dependencies defined in Gemfile
 end
 Jeweler::RubygemsDotOrgTasks.new

data/lib/wherewolf.rb

@@ -1,5 +1,6 @@
 require File.join(File.dirname(__FILE__), 'wherewolf', 'parser.rb')
 require File.join(File.dirname(__FILE__), 'wherewolf', 'processor.rb')
+require File.join(File.dirname(__FILE__), 'wherewolf', 'parse_error.rb')
 
 module Wherewolf
   def self.included(base)

data/lib/wherewolf/parse_error.rb

@@ -0,0 +1,20 @@
+module Wherewolf
+  class ParseError < Parslet::ParseFailed
+    attr_reader :parent
+    def initialize(parent)
+      @parent = parent
+    end
+
+    def position
+      parent.cause.source.pos
+    end
+
+    def error_message
+      "Parsing error occured at character #{position}"
+    end
+
+    def to_s
+      error_message
+    end
+  end
+end

data/lib/wherewolf/parser.rb

@@ -10,6 +10,7 @@ module Wherewolf
     # Comparisons
     rule(:eq) { str('=') }
     rule(:not_eq) { str('!=') }
+    rule(:matches) { str('~=') }
     rule(:lt) { str('<') }
     rule(:lteq) { str('<=') }
     rule(:gt) { str('>') }
@@ -33,16 +34,17 @@ module Wherewolf
     end
     rule(:literal) { match('[a-zA-Z0-9\-_]').repeat(1) }
     rule(:identifier) { null | boolean | number | double_quote_string | literal.as(:string) }
-
+    
     # Grammar
     rule(:compare_eq) { (literal.as(:left) >> space? >> eq >> space? >> identifier.as(:right)).as(:eq) }
     rule(:compare_not_eq) { (literal.as(:left) >> space? >> not_eq >> space? >> identifier.as(:right)).as(:not_eq) }
+    rule(:compare_matches) { (literal.as(:left) >> space? >> matches >> space? >> identifier.as(:right)).as(:matches) }
     rule(:compare_lt) { (literal.as(:left) >> space? >> lt >> space? >> identifier.as(:right)).as(:lt) }
     rule(:compare_lteq) { (literal.as(:left) >> space? >> lteq >> space? >> identifier.as(:right)).as(:lteq) }
     rule(:compare_gt) { (literal.as(:left) >> space? >> gt >> space? >> identifier.as(:right)).as(:gt) }
     rule(:compare_gteq) { (literal.as(:left) >> space? >> gteq >> space? >> identifier.as(:right)).as(:gteq) }
    
-    rule(:compare) { compare_eq | compare_not_eq | compare_lteq | compare_lt | compare_gteq | compare_gt }
+    rule(:compare) { compare_eq | compare_not_eq | compare_matches | compare_lteq | compare_lt | compare_gteq | compare_gt }
 
     rule(:primary) { left_parenthesis >> space? >> or_operation >> space? >> right_parenthesis | compare }
     rule(:and_operation) { (primary.as(:left) >> space? >> and_operator >> space? >> and_operation.as(:right)).as(:and) | primary }

data/lib/wherewolf/processor.rb

@@ -8,9 +8,13 @@ module Wherewolf
     end
 
     def parse(model, query)
-      ast = Wherewolf::Parser.new.parse(query)
-      table = model.arel_table
-      model.where(process(ast, table))
+      begin
+        ast = Wherewolf::Parser.new.parse(query)
+        table = model.arel_table
+        model.where(process(ast, table))
+      rescue Parslet::ParseFailed => error
+        raise Wherewolf::ParseError, error
+      end
     end
 
     def process(ast, table)
@@ -35,6 +39,10 @@ protected
       table[ast[:left].to_sym].not_eq(parse_value(ast[:right]))
     end
 
+    def process_matches(ast, table)
+      table[ast[:left].to_sym].matches(parse_value(ast[:right]))
+    end
+
     def process_lt(ast, table)
       table[ast[:left].to_sym].lt(parse_value(ast[:right]))
     end

data/test/parse_error_test.rb

@@ -0,0 +1,9 @@
+require 'helper'
+
+class ParseErrorTest < Test::Unit::TestCase
+  context 'ParseError' do
+    should 'be a child of Parslet::ParseFailed' do
+      Wherewolf::ParseError.is_a?(Parslet::ParseFailed)
+    end
+  end
+end

data/test/parser_test.rb

@@ -76,6 +76,25 @@ class ParserTest < Test::Unit::TestCase
         end
       end
 
+      context "matches" do
+        should 'parse [op1]~=[op2]' do
+          result = @parser.parse('name~="Myles"')
+          assert_equal( { :matches => { :left => "name", :right => { :string => "Myles" } } }, result)
+        end
+        should 'parse [op1] ~=[op2]' do
+          result = @parser.parse('name ~="Myles"') 
+          assert_equal( { :matches => { :left => "name", :right => { :string => "Myles" } } }, result)
+        end
+        should 'parse [op1]~= [op2]' do
+          result = @parser.parse('name~= "Myles"') 
+          assert_equal( { :matches => { :left => "name", :right => { :string => "Myles" } } }, result)
+        end
+        should 'parse [op1] ~= [op2]' do
+          result = @parser.parse('name ~= "Myles"') 
+          assert_equal( { :matches => { :left => "name", :right => { :string => "Myles" } } }, result)
+        end
+      end
+
       context "less than" do
         should 'parse [op1]<[op2]' do
           result = @parser.parse("size<12") 

data/test/processor_test.rb

@@ -27,6 +27,40 @@ class ProcessorTest < Test::Unit::TestCase
     end
   
     context 'Parsing' do
+      context 'Error' do
+        should 'be raised is there is a parser error' do
+          assert_raise Wherewolf::ParseError do
+            Player.from_query('name ~= "Patrick%" || (position = "fail)')
+          end
+        end
+
+        should 'allow retrieval of the error position' do
+          begin
+            Player.from_query('name ~= "Patrick%" || (position = "fail)')
+          rescue Wherewolf::ParseError => e
+            assert_equal 28, e.position
+          end
+        end
+ 
+
+        should 'show a nice debug error' do
+          begin
+            Player.from_query('name ~= "Patrick%" || (position = "fail)')
+          rescue Wherewolf::ParseError => e
+            assert_equal "Parsing error occured at character 28", e.error_message
+          end
+        end
+      
+        should 'to_s should print out nice error' do
+          begin
+            Player.from_query('name ~= "Patrick%" || (position = "fail)')
+          rescue Wherewolf::ParseError => e
+            assert_equal "Parsing error occured at character 28", e.to_s
+          end
+        end
+
+      end
+
       should 'construct simple boolean statements' do
         player = Player.from_query('name = "Charlie Ellis"')
         assert_equal 1, player.count
@@ -47,6 +81,12 @@ class ProcessorTest < Test::Unit::TestCase
         assert_equal "Charlie Redwood", player[2].name
       end
 
+      should 'handle matches' do
+        player = Player.from_query('name ~= "James%"')
+        assert_equal 1, player.count
+        assert_equal "James Slipper", player.first.name
+      end
+
       should 'handle nulls' do
         player = Player.from_query("first_cap = null")
         assert_equal 1, player.count

data/wherewolf.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = "wherewolf"
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Myles Eftos"]
   s.date = "2012-10-10"
-  s.description = "Wherewolf allows you to consume search terms as strings without worrying about database injections. It parses the query and converts it into AREL. It's great for creating filterable REST APIs"
+  s.description = "Wherewolf allows you to consume search terms as strings without worrying about database injections. It parses the query and converts it into ARel. It's great for creating filterable REST APIs."
   s.email = "myles@madpilot.com.au"
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -25,10 +25,12 @@ Gem::Specification.new do |s|
     "README.rdoc",
     "Rakefile",
     "lib/wherewolf.rb",
+    "lib/wherewolf/parse_error.rb",
     "lib/wherewolf/parser.rb",
     "lib/wherewolf/processor.rb",
     "lib/wherewolf/railtie.rb",
     "test/helper.rb",
+    "test/parse_error_test.rb",
     "test/parser_test.rb",
     "test/processor_test.rb",
     "test/railtie_test.rb",
@@ -38,7 +40,7 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.15"
-  s.summary = "Query parser that converts search terms to AREL for use in APIs"
+  s.summary = "Makes filtering and searching to your REST API crazy easy."
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wherewolf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: arel
-  requirement: &70230035647040 !ruby/object:Gem::Requirement
+  requirement: &70166778516180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230035647040
+  version_requirements: *70166778516180
 - !ruby/object:Gem::Dependency
   name: parslet
-  requirement: &70230035645880 !ruby/object:Gem::Requirement
+  requirement: &70166778514340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70230035645880
+  version_requirements: *70166778514340
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &70230035645020 !ruby/object:Gem::Requirement
+  requirement: &70166778512340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035645020
+  version_requirements: *70166778512340
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70230035658520 !ruby/object:Gem::Requirement
+  requirement: &70166778511320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035658520
+  version_requirements: *70166778511320
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70230035655100 !ruby/object:Gem::Requirement
+  requirement: &70166778510520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035655100
+  version_requirements: *70166778510520
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70230035654260 !ruby/object:Gem::Requirement
+  requirement: &70166778509620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035654260
+  version_requirements: *70166778509620
 - !ruby/object:Gem::Dependency
   name: guard
-  requirement: &70230035653240 !ruby/object:Gem::Requirement
+  requirement: &70166778525100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035653240
+  version_requirements: *70166778525100
 - !ruby/object:Gem::Dependency
   name: guard-test
-  requirement: &70230035681240 !ruby/object:Gem::Requirement
+  requirement: &70166778524220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035681240
+  version_requirements: *70166778524220
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70230035677480 !ruby/object:Gem::Requirement
+  requirement: &70166778522920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035677480
+  version_requirements: *70166778522920
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70230035689500 !ruby/object:Gem::Requirement
+  requirement: &70166778521500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,10 +120,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035689500
+  version_requirements: *70166778521500
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70230035685280 !ruby/object:Gem::Requirement
+  requirement: &70166778520140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -131,10 +131,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035685280
+  version_requirements: *70166778520140
 - !ruby/object:Gem::Dependency
   name: wherewolf
-  requirement: &70230035683060 !ruby/object:Gem::Requirement
+  requirement: &70166778519320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -142,10 +142,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70230035683060
+  version_requirements: *70166778519320
 description: Wherewolf allows you to consume search terms as strings without worrying
-  about database injections. It parses the query and converts it into AREL. It's great
-  for creating filterable REST APIs
+  about database injections. It parses the query and converts it into ARel. It's great
+  for creating filterable REST APIs.
 email: myles@madpilot.com.au
 executables: []
 extensions: []
@@ -161,10 +161,12 @@ files:
 - README.rdoc
 - Rakefile
 - lib/wherewolf.rb
+- lib/wherewolf/parse_error.rb
 - lib/wherewolf/parser.rb
 - lib/wherewolf/processor.rb
 - lib/wherewolf/railtie.rb
 - test/helper.rb
+- test/parse_error_test.rb
 - test/parser_test.rb
 - test/processor_test.rb
 - test/railtie_test.rb
@@ -184,7 +186,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3955971048555964075
+      hash: -122893438368244231
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -196,5 +198,5 @@ rubyforge_project:
 rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: Query parser that converts search terms to AREL for use in APIs
+summary: Makes filtering and searching to your REST API crazy easy.
 test_files: []