johnbender-rquery 0.1.2 → 0.2.0

data/README.markdown

@@ -3,14 +3,28 @@ RQuery
 
 RQuery is a small DSL inspired by RSpec for building text queries in languages like SQL. It is meant to be concise, easy to read, and expressive about what the query will be asking for.
 
-Currently only the ActiveRecord extension is implemented with a Sqlite adapter. Mysql should follow shortly, and then support for Grove + JSON queries to Mnesia.
+Currently only the ActiveRecord extension is implemented with a Sqlite adapter. Mysql should be trivial to implement, and I'm hoping to get to supporting my own project Grove.
 
 ActiveRecord
 ------------
 
-RQuery can extend ActiveRecord to provide the `where` method. `where` accepts a single optional argument and a block that represents the query statements
+###Setup/Config and Symbols vs Block parameters
 
-###Example compared with `find`
+In you're rails environment file simply require rquery. The default adapter is the included Sqlite adapter but you can created and set your own with
+
+    RQuery.adapter = class 
+
+You can view both Sql and Sqlite in the adapters directory if you are interested in writing your own (mysql?). As a side note it would be nice at some point to decide the adapter based on the db chosen for a given environment.
+
+Also, you can choose to use symbols as the attribute names in the block or you can use an option block argument to represent an ActiveRecord object. To use the symbols make sure to add the following to your environment.rb
+
+    RQuery.use_symbols
+
+Using the block parameter instead has two benefits. 1: you won't be poluting the Symbol objects with my hackery, and 2: RQuery will tell you when you are attempting use an attribute for the object that doesn't exist. Examples of both below.
+
+###Examples
+
+RQuery extend ActiveRecord to provide the `where` method. `where` accepts a single optional argument and a block that represents the query statements
 
 In a given UsersController your `show` action might find the User like so:
 
@@ -20,6 +34,9 @@ Using RQuery:
 
     @user = User.where { :id.is == params[:id] }
 
+Or
+
+    @user = User.where { |user| user.id.is == params[:id] }
 
 In the above case, RQuery doesn't provide much of an improvement over the traditional `find` method, but as the query becomes more complex its expressiveness begins to shine through:
 
@@ -33,23 +50,23 @@ RQuery:
 
 Or:
 
-    @users = User.where do 
-        :age.between 10..20 
+    @users = User.where do |user|
+        user.age.between 10..20 
     end
 
 Both the `from` and `between` methods accept argument lists `10,20` or an array `[10,20]`. 
 
-
 ###Other Examples 
 
 RQuery supports most of the common SQL operations: =, <>, >, <, >=, <=  as well as in, like (see below for specifics), and between. `:column.is_not` works for `.in`, `.between`, `.contains`, and `==`. All operations are anded as of the current version.
 
 Operators:
 
-    @obj = ActiveRecordObject.where do
-        :foo.is > 2      
-        :foo.is_not == 4 
+    @obj = ActiveRecordObject.where do |obj|
+        obj.foo.is > 2      
+        obj.foo.is_not == 4 
     end 
+
     #=> conditions array: ["foo > ? and foo <> ?", 2, 4]
 
 Contains:
@@ -62,8 +79,8 @@ Contains:
 
 In:
 
-   @obj = ActiveRecordObject.where do
-        :foo.in "bar", "baz", "bak"
+   @obj = ActiveRecordObject.where do |obj|
+        obj.foo.in "bar", "baz", "bak"
     end
     #=> conditions array: ["foo in (?)", ["bar", "baz", "bak"]]
     #using the default sqlite adapter
@@ -81,6 +98,36 @@ is equivalent to the find call:
 
     @obj = ActiveRecordObject.find(:first, conditions => ["foo = ?", "bar"])
 
+###Complex queries
+
+RQuery supports relatively complex queries including | and & operation groupings. All operations need to be on the same line and in parens and either the | operator or the & operator can be used on a singel line
+
+    User.where do |user|
+        (mock.age.is > 20) | (mock.age.in 16,18)
+    end
+
+In the following example the & takes precedence and will be grouped with the contains "Alice" which will be or'd with the contains "George" 
+
+    #=> name contains "George" or (name contains "Alice and age from 20 to 30)
+    User.where do |user|
+        (user.name.contains "George") | (user.name.contains "Alice") & (use.age.from 20..30)
+    end
+
+To correct the above to the more intuitive version add parens to force precedence of the contains operations 
+    
+    #=> (name contains "George" or name contains "Alice) and age from 20 to 30
+    User.where do |user|
+        ((user.name.contains "George") | (user.name.contains "Alice")) & (use.age.from 20..30)
+    end
+
+In this sutation it would be cleaner and easier to just move the and'd statement down a line as all seperate lines are and'd and lines have precedence from top to bottom
+    
+    User.where do |user|
+        (user.name.contains "George") | (user.name.contains "Alice")
+        use.age.from 20..30
+    end
+
+
 
 
 

data/examples/user.rb

@@ -0,0 +1,49 @@
+#All operations need to be on the same line and in parens
+#either the | operator or the & operator can be used on a singel line
+User.where do |user|
+  (mock.age.is > 20) | (mock.age.in 16,18)
+end
+
+#the & takes precedence here and will be grouped with the contains "Alice" which will be 
+#or'd with the contains "George" 
+#=> name contains "George" or (name contains "Alice and age from 20 to 30)
+User.where do |user|
+  (user.name.contains "George") | (user.name.contains "Alice") & (use.age.from 20..30)
+end
+
+#to correct the above to the more intuitive version add parens to force precedence of the
+#contains operations 
+#=> (name contains "George" or name contains "Alice) and age from 20 to 30
+User.where do |user|
+ ((user.name.contains "George") | (user.name.contains "Alice")) & (use.age.from 20..30)
+end
+
+#in this sutation it would be cleaner and easier to just move the and'd statement down
+#a line as all seperate lines are and'd and lines have precedence from top to bottom
+#additionaly operations on seperate lines don't need parens
+User.where do |user|
+ (user.name.contains "George") | (user.name.contains "Alice")
+ use.age.from 20..30
+end
+
+#should you attempt to use and attribute that doesn't exist for a given model
+#rquery will tell you before it's sent to the db
+User.where do |user|
+  user.ssn.is == 123-45-6789
+end
+# RQuery::AttributeNotFoundError: The field 'ssn' doesn't exist for this object
+# 	from /Users/johnbender/Projects/rquery/lib/rquery/attribute_collection.rb:28:in `method_missing'
+# 	from (irb):24
+# 	from /Users/johnbender/Projects/rquery/lib/rquery/active_record/base.rb:16:in `where'
+# 	from /Users/johnbender/Projects/rquery/lib/rquery/active_record/base.rb:11:in `synchronize'
+# 	from /Users/johnbender/Projects/rquery/lib/rquery/active_record/base.rb:11:in `where'
+# 	from (irb):23
+
+#environment config
+RQuery.use_symbols
+
+#example of using symbols, you can see more at the RQuery page on my site.
+User.where do |user|
+ (:name.contains "George") | (:name.contains "Alice")
+ :age.from 20..30
+end

data/lib/rquery/active_record/base.rb

@@ -1,35 +1,37 @@
 module RQuery
-    module ActiveRecord
-        @@where_mutex = Mutex.new
-        def where(*args, &block)
+  module ActiveRecord
+    @@where_mutex = Mutex.new
+    def where(*args, &block)
 
-            #establish scope for conditions
-            conditions = nil
+      #establish scope for conditions
+      conditions = nil
 
-            #make sure only one thread at a time is altering the class
-            #variables inside RQuery::Serializers::Operations
-            @@where_mutex.synchronize do
+      #make sure only one thread at a time is altering the class
+      #variables inside RQuery::Serializers::Operations
+      @@where_mutex.synchronize do
 
-                #yielding the block will alter the Operations class
-                yield
+        #Passes a new AttributeCollection object to the block
+        #if RQuery.use_symbols has been called it may not be used
+        #but otherwise will take the form attr_coll_object.attribute.is ...
+        yield(RQuery::AttributeCollection.new(self.new.attribute_names))
 
-                #record altered conditions and values
-                conditions = ::RQuery::Serializers::Operations.conditions
+        #record altered conditions and values
+        conditions = ::RQuery::Serializers::Operations.conditions
 
-                #clear the alterations
-                ::RQuery::Serializers::Operations.clear
-            end
+        #clear the alterations
+        RQuery::Serializers::Operations.clear
+      end
 
-            #limit the records returned (:first, :all, :last)
-            limit = args.first ? args.first : :all
+      #limit the records returned (:first, :all, :last)
+      limit = args.first ? args.first : :all
 
-            #call find with the conditions and values provided by the block
-            find(limit, :conditions => conditions)
-        end
+      #call find with the conditions and values provided by the block
+      find(limit, :conditions => conditions)
     end
+  end
 end
 
 #extend ActiveRecord::Base with the where method 
 if Object.const_defined?(:ActiveRecord)
-    ActiveRecord::Base.send :extend, RQuery::ActiveRecord
+  ActiveRecord::Base.send :extend, RQuery::ActiveRecord
 end

data/lib/rquery/adapters/sql.rb

@@ -31,9 +31,13 @@ module RQuery
                 def contains
                     "like '%' + ? + '%'"
                 end
+                
+                def and_group(ops)
+                  "(#{ops.join(" and ")})"
+                end
 
-                def join(ops)
-                    ops.join(" and ")
+                def or_group(ops)
+                  "(#{ops.join(" or ")})"
                 end
 
                 [:>, :>=, :<, :<=].each do |operator|
@@ -41,6 +45,8 @@ module RQuery
                         "#{operator} ?"
                     end
                 end
+
+                alias :join :and_group
             end
         end
     end

data/lib/rquery/attribute.rb

@@ -0,0 +1,14 @@
+module RQuery
+  class Attribute
+    #adds is, is_not, between, in, contains, and from (alias)
+    include RQuery::Declarations
+
+    #define name for the Declarations included methods
+    #as it needs to be different than the default
+    attr_accessor :name
+
+    def initialize(field_name)
+      @name = field_name
+    end
+  end
+end

data/lib/rquery/attribute_collection.rb

@@ -0,0 +1,35 @@
+module RQuery
+  class AttributeCollection
+
+    def initialize(fields)
+      @fields = fields.map{ |x| x.to_s }
+    end
+    
+    #if the field was added upon initialization its a valid call
+    #otherwise report to the user it is invalid. Reports errors at the ruby level
+    #instead of the data store level with something like "column doesn't exist"
+    #
+    #example
+    #
+    # >> user = RQuery::FieldCollection.new([:age, :name])
+    # => #<RQuery::FieldCollection:0x1a2c21c @fields=[:age, :name]>
+    # >> user.age
+    # => #<RQuery::Field:0x1a2b240 @name=:age>
+    # >> user.name
+    # => #<RQuery::Field:0x1a2a390 @name=:name>
+    # >> user.weight
+    # ArgumentError: The field 'weight' doesn't exist for this object
+    # 	from /Users/johnbender/Projects/rquery/lib/rquery/where_clause.rb:20:in `method_missing'
+    # 	from (irb):5
+    def method_missing(symbol, *args)
+      if @fields.include?(symbol.to_s)
+        Attribute.new(symbol)
+      else
+        raise AttributeNotFoundError, "The field '#{symbol.to_s}' doesn't exist for this object" 
+      end
+    end
+
+  end
+
+  class AttributeNotFoundError < ArgumentError; end
+end

data/lib/rquery/declarations.rb

@@ -1,39 +1,34 @@
-
 module RQuery
-    module Declarations
-        def is
-            ::RQuery::Serializers::IsOperations.add_operation(self)
-            ::RQuery::Serializers::IsOperations.prefix = nil
-            ::RQuery::Serializers::IsOperations
-        end
-
-        def is_not
-            ::RQuery::Serializers::IsNotOperations.add_operation(self)
-            ::RQuery::Serializers::IsNotOperations.prefix = "not_"
-            ::RQuery::Serializers::IsNotOperations
-        end
-
-        def in(*args)
-            ::RQuery::Serializers::IsOperations.add_operation(self)
-            ::RQuery::Serializers::IsOperations.prefix = nil
-            ::RQuery::Serializers::IsOperations.in(*args)
-        end
-
-        def between(*args)
-            ::RQuery::Serializers::IsOperations.add_operation(self)
-            ::RQuery::Serializers::IsOperations.prefix = nil
-            ::RQuery::Serializers::IsOperations.between(*args)
-        end
-
-        def contains(val)
-            ::RQuery::Serializers::IsOperations.add_operation(self)
-            ::RQuery::Serializers::IsOperations.prefix = nil
-            ::RQuery::Serializers::IsOperations.contains(val)
-        end
-
-        alias :from :between
+  module Declarations
+    #Allows the methods below to be included in 
+    #the Field class and the Symbol class but remain
+    #the same in implementation
+    #!name is redefined as an attr_accessor in the Field class!
+    def name
+      self.to_s if @name == nil
+    end
+    
+    def is
+      Serializers::IsOperations.add_operation(name)
+      Serializers::IsOperations.prefix = nil
+      Serializers::IsOperations
+    end
+    
+    def is_not
+      Serializers::IsNotOperations.add_operation(name)
+      Serializers::IsNotOperations.prefix = "not_"
+      Serializers::IsNotOperations
     end
+    
+    [:in, :between, :contains].each do |m|
+      define_method(m) do |*args|
+        Serializers::IsOperations.add_operation(name)
+        Serializers::IsOperations.prefix = nil
+        Serializers::IsOperations.send(m, *args)
+      end
+    end
+    
+    alias :from :between
+  end
 end
 
-Symbol.send :include, RQuery::Declarations
-

data/lib/rquery/serializers.rb

@@ -1,110 +1,184 @@
 module RQuery
-    module Serializers
-        class Operations
+  module Serializers
+    #The Operations serializer, handles the limiting factors imposed
+    #by a given query. The methods in this class apply to both is and is_not
+    #operations. An example in sql would look like:
+    #
+    #where foo = bar and foo > 2
+    #
+    #This class is a gateway to the selected RQuery.adapter methods.
+    #Calls to methods here, will be passed on to the selected adapter 
+    class Operations
+      
+      @@prefix = nil
+      @@ops = []
+      @@values = []
+      
+      class << self
+        def prefix=(val)
+          @@prefix = val
+        end
         
-            @@prefix = nil
-            @@ops = []
-            @@values = []
-
-            class << self
-                def prefix=(val)
-                    @@prefix = val
-                end
-
-                def to_s
-                    RQuery.adapter.join(@@ops)
-                end
-
-                def conditions
-                    [to_s] + @@values
-                end
-
-                def add_operation(val)
-                    @@ops << val.to_s
-                end
-
-                def clear
-                    @@ops.clear
-                    @@values.clear
-                end
-
-                def in(*args)
-                    #flatten our args to prevent having to check for an array first arg
-                    args.flatten!
-                    
-                    #if a range (or anything else that responds to :first) is passed as the first argument 
-                    #use it alone, otherwise use the args array 
-                    #examples:
-                    #ruby => args.flatten! => stored values
-                    #:id.between 1..100 => [1..100] => 1..100
-                    #:id.between [1, 2, 3] => [1, 2, 3] => [1, 2, 3]
-                    #:id.between 1, 2 => [1, 2] => [1, 2] 
-                    #
-                    @@values << (args.first.respond_to?(:first) ? args.first : args)
-                    @@ops[@@ops.length-1] += " #{RQuery.adapter.send("#{@@prefix}in")}"
-                end
-
-                def between(*args)
-                    #flatten our args to prevent having to check for an array first arg
-                    args.flatten!
-                    
-                    #if a range is passed use its first/last element 
-                    #otherwise use the first and last element of the flattened args array
-                    #examples:
-                    #ruby => args.flatten! => stored values
-                    #:id.between 1..100 => [1..100] => 1 100
-                    #:id.between [1, 2, 3] => [1, 2, 3] => 1 3
-                    #:id.between 1, 2 => [1, 2] => 1 2 
-                    #
-                    @@values += args.first.respond_to?(:first) ? [args.first.first, args.first.last] : [args.first, args.last]
-                    
-                    #store the operation string
-                    #example:
-                    #:id.between 1..100 "id between ? and ?"
-                    #
-                    @@ops[@@ops.length-1] += " #{RQuery.adapter.send("#{@@prefix}between")}"
-                end
-
-                def contains(str)
-                    @@values << str
-                    @@ops[@@ops.length-1] += " #{RQuery.adapter.send("#{@@prefix}contains")}"
-                end
-
-                #allows for is.from
-                #examples:
-                #
-                #:id.is.from 1,2
-                #:is.is.from 2..10
-                alias :from :between
-
-            end
-
+        def to_s
+          RQuery.adapter.join(@@ops)
         end
-
-        class IsOperations < Operations
-
-            #define the normal operators for is to call the adapter for the equivelant sql
-            class << self
-                [:==, :>, :>=, :<, :<=].each do |operator|                    
-                    define_method(operator) do |val|
-                        @@values << val
-                        @@ops[@@ops.length-1] += " #{RQuery.adapter.send(operator)}"
-                    end
-                end
-            end
+        
+        #return a conditions array for use with ActiveRecord.find
+        def conditions
+          [to_s] + @@values
+        end
+        
+        #add and operation to the @@ops array which will be popped
+        #and pushed depending on the operations sequence and arrangement
+        def add_operation(val)
+          @@ops << val.to_s
         end
 
-        class IsNotOperations < Operations
-
-            #define the == value for is_not to call the adapter for the equivelant sql
-            class << self
-                define_method(:==) do |val|
-                    @@values << val
-                    @@ops[@@ops.length-1] += " #{RQuery.adapter.send(:neq)}"
-                end
+        #clean out the Operations singleton class variables
+        def clear
+          @@ops.clear
+          @@values.clear
+        end
+        
+        #grouping is done by using the | and & operators between multiple operations
+        #objects on a single line.
+        #
+        #This works because each operation ie (user.age.is == 2) is
+        #evaluated before these two operators thus pushing
+        #the equivelant operation string onto the @@ops array (ie 'age = ?'). 
+        #When an operation is evaluated it returns the Operations class which can be compared
+        #using the aforementioned operators. Those operators call the group method
+        #popping the last two arguments off the stack and dealing with them in one of two ways
+        #
+        #1. if the second object popped is a string both objects should be
+        #   added to a new OperationGroup which is then put back onto the stack
+        #
+        #2. if the second object popped is an OperationGroup the firest belongs to this group as
+        #   well (it was on the same line). It is added to the OperationGroup and put back on the
+        #   stack
+        def group(type)
+          second_op, first_op = @@ops.pop, @@ops.pop
+          
+          #if the previous operation on the stack is an Operation Group we need to add to it
+          if first_op.class == RQuery::Serializers::OperationsGroup
+            if first_op.type == type
+              first_op.ops << second_op
+              @@ops << first_op
+            else
+              @@ops << OperationsGroup.new(first_op.to_s, second_op, type)
             end
+          else
+            @@ops << OperationsGroup.new(first_op, second_op, type)
+          end
+        end
+        
+        #used to group operations for anding on a single line
+        #example with sqlite adapter
+        #(user.age.in [1,2,3]) | (user.name.contains "foo")
+        #=>(age in (?) and name like '%' || 'foo' || '%')
+        def &(second)
+          self.group(:and)
+          self
+        end
+        
+        def |(second)
+          self.group(:or)
+          self
+        end
 
+        def in(*args)
+          #flatten our args to prevent having to check for an array first arg
+          args.flatten!
+          
+          #if a range is passed as the first argument 
+          #use it alone, otherwise use the args array 
+          #examples:
+          #ruby => args.flatten! => stored values
+          #:id.between 1..100 => [1..100] => 1..100
+          #:id.between [1, 2, 3] => [1, 2, 3] => [1, 2, 3]
+          #:id.between 1, 2 => [1, 2] => [1, 2] 
+          @@values << (args.first.class == Range ? args.first : args)
+          @@ops[@@ops.length-1] += " #{RQuery.adapter.send("#{@@prefix}in")}"
+          self
+        end
+        
+        def between(*args)
+          #flatten our args to prevent having to check for an array first arg
+          args.flatten!
+          
+          #if a range is passed use its first/last element 
+          #otherwise use the first and last element of the flattened args array
+          #examples:
+          #ruby => args.flatten! => stored values
+          #:id.between 1..100 => [1..100] => 1 100
+          #:id.between [1, 2, 3] => [1, 2, 3] => 1 3
+          #:id.between 1, 2 => [1, 2] => 1 2 
+          #
+          @@values += (args.first.class == Range ? [args.first.first, args.first.last] : [args.first, args.last])
+          @@ops[@@ops.length-1] += " #{RQuery.adapter.send("#{@@prefix}between")}"
+          self
+        end
+        
+        def contains(str)
+          @@values << str
+          @@ops[@@ops.length-1] += " #{RQuery.adapter.send("#{@@prefix}contains")}"
+          self
         end
+        
+        #allows for is.from
+        #examples:
+        #
+        #:id.is.from 1,2
+        #:is.is.from 2..10
+        alias :from :between
+      end
+    end
     
+    class OperationsGroup
+      attr_accessor :ops, :type
+      
+      def initialize(left, right, type)
+        @ops = Array.new
+        @ops << left
+        @ops << right
+        @type = type
+      end
+      
+      def to_s
+        RQuery.adapter.send("#{type.to_s}_group", @ops)
+      end
+    end
+    
+    #The IsOpertaions serializer defines only methods that apply to the .is operator
+    #that is added to the Symbol class in the Declarations module.
+    class IsOperations < Operations
+      #define the normal operators for is to call the adapter for the equivelant sql
+      class << self
+        [:==, :>, :>=, :<, :<=].each do |operator|                    
+          define_method(operator) do |val|
+            @@values << val
+            @@ops[@@ops.length-1] += " #{RQuery.adapter.send(operator)}"
+            self
+          end
+        end
+      end
+
     end
+    
+    #The IsNotOperations serializer defines only methods that apply to the .is_not operator
+    #that is added to the symbol class in the declarations module. Specifically, == as 
+    #ruby does not allow for the overloading of !=
+    class IsNotOperations < Operations      
+      #define the == value for is_not to call the adapter for the equivelant sql
+      class << self
+        def ==(val) 
+          @@values << val
+          @@ops[@@ops.length-1] += " #{RQuery.adapter.send(:neq)}"
+          self
+        end
+      end
+
+    end  
+
+  end
 end