activerecord_finder 0.1.0

data/README.md

@@ -0,0 +1,95 @@
+Arel Finders
+============
+
+The problem with ActiveRecord today is that there is no way to
+construct queries outside "attribute = value" or using "OR" operator.
+The solutions so far are not so easy to do, and usualy involves creating
+fragments of SQL in string form.
+
+But we have Arel. So, this must be solved, right?
+
+Unfortunately, no. Arel's API is quite dificult to use, and its API is quite
+inconsistent and changes over time, resulting in difficult code to mantain.
+
+## ActiveRecord::Finder
+
+So, the solution was to create an object, an "adapter-kind" of object.
+ActiveRecord::Finder is a kind of object that contains all attributes
+from a table, and allows you to `OR` or `AND` queries.
+
+```ruby
+finder = ActiveRecord::Finder.new(Arel::Table.new(:users))
+query = finder.age > 10 | finder.name == "Foo"
+query.arel.to_sql
+#Returns: users.age > 10 OR users.name = 'Foo'
+```
+
+But it is kind of tedious to do this everytime you want to search for users,
+so you can use ActiveRecord::Base#restrict with a block to construct your queries.
+
+## ActiveRecord's Finders
+
+Integrating with ActiveRecord, it is possible to use `restrict` to find records on a ActiveRecord object. The syntax is quite simple:
+
+```ruby
+User.restrict { |f| f.age > 18 }
+#or
+User.restrict { age > 18 }
+```
+
+ANDs work on the same way, too:
+
+```ruby
+User.restrict { age > 18 & age < 20 }
+``` 
+
+### All finders, so far:
+
+```ruby
+#WHERE NOT (users.age < 10)
+User.restrict { !(age < 10) }
+
+#Comparission
+User.restrict { age == 20 }
+User.restrict { age >= 20 }
+User.restrict { age <= 20 }
+User.restrict { age != 20 }
+User.restrict { age > 20 }
+User.restrict { age < 20 }
+
+#IN
+User.restrict { age.in?([10, 20, 30]) }
+
+#LIKE
+User.restrict { name =~ "Foo%" }
+User.restrict { name !~ "Foo%" }
+
+#AND, and OR
+User.restrict { (name == "Foo") & (age < 20) }
+User.restrict { (name == "Foo") | (age < 30) }
+User.restrict do 
+  ( (name == "Foo") & (age < 20) ) |
+  ( (name == "Bar") | (age > 20) )
+end
+```
+
+Plase note that because of operator precedence in Ruby, we must add a parenthesis over the comparission before using `&` or `|`.
+
+## Constructing Queries
+
+To avoid "merging" ActiveRecord::Relation's, there is a specific syntax to construct a complex query on ActiveRecord::Finder.
+
+```ruby
+def search(name_to_search, params = {})
+  query = User.new_finder { name == name_to_search }
+  query = query & User.new_finder { age > params[:age] } if params.include?(:age)
+  query = query | User.new_finder { age <= 10 } if params[:include_all_childs]
+  User.restrict(query)
+end
+```
+
+### Using "joins"
+
+To be simple, the `Finder` simply has the attributes from the table that it was created. So, to be able to find a record using attributes from one of the joined tables, it is possible to use `ActiveRecord::Base#merge` 
+
+##

data/lib/activerecord_finder/comparator.rb

@@ -0,0 +1,34 @@
+module ActiveRecordFinder
+  class Comparator
+    def initialize(finder, field)
+      @finder = finder
+      @field = field
+    end
+
+    def self.convert_to_arel(operation, arel_method)
+      define_method(operation) do |other|
+        arel_clause =  @field.send(arel_method, other)
+        Finder.new(@finder.table, arel_clause)
+      end
+    end
+
+    def nil?
+      self == nil
+    end
+
+    def in?(other)
+      other = other.arel if other.respond_to?(:arel)
+      arel_clause =  @field.in(other)
+      Finder.new(@finder.table, arel_clause)
+    end
+
+    convert_to_arel :==, :eq
+    convert_to_arel '!=', :not_eq
+    convert_to_arel :>, :gt
+    convert_to_arel :>=, :gteq
+    convert_to_arel :<, :lt
+    convert_to_arel :<=, :lteq
+    convert_to_arel :=~, :matches
+    convert_to_arel '!~', :does_not_match
+  end
+end

data/lib/activerecord_finder/finder.rb

@@ -0,0 +1,34 @@
+module ActiveRecordFinder
+  class Finder
+    attr_reader :table, :arel
+
+    def initialize(arel_table, operation=nil)
+      @table = arel_table
+      @arel = operation
+      @table.columns.each { |a| define_attribute_method a }
+    end
+
+    def define_attribute_method(arel_attribute)
+      singleton_class.send :define_method, arel_attribute.name do
+        Comparator.new(self, arel_attribute)
+      end
+    end
+    private :define_attribute_method
+
+    def |(other)
+      other = other.arel if other.respond_to?(:arel)
+      Finder.new(table, arel.or(other))
+    end
+
+    def &(other)
+      other = other.arel if other.respond_to?(:arel)
+      Finder.new(table, arel.and(other))
+    end
+
+    def !@
+      Finder.new(table, Arel::Nodes::Not.new(arel))
+    end
+
+    undef_method :==
+  end
+end

data/lib/activerecord_finder/where.rb

@@ -0,0 +1,22 @@
+module ActiveRecordFinder
+  module Where
+    def restrict(finder = nil, &block)
+      raise ArgumentError, 'wrong number of arguments (0 for 1)' if block.nil? && finder.nil?
+      if block
+        where(new_finder(&block).arel)
+      else
+        where(finder.arel)
+      end
+    end
+    alias :condition :restrict
+
+    def new_finder(&block)
+      activerecord_finder = ActiveRecordFinder::Finder.new(arel_table)
+      if block.arity == 1
+        block.call(activerecord_finder)
+      else
+        activerecord_finder.instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/activerecord_finder.rb

@@ -0,0 +1,5 @@
+require_relative "activerecord_finder/finder"
+require_relative "activerecord_finder/comparator"
+require_relative "activerecord_finder/where"
+
+ActiveRecord::Base.extend ActiveRecordFinder::Where

data/spec/activerecord_finder/comparator_spec.rb

@@ -0,0 +1,44 @@
+require_relative "../helper"
+
+describe ActiveRecordFinder::Comparator do
+  subject { ActiveRecordFinder::Comparator.new(finder, table[:name]) }
+  let(:finder) { ActiveRecordFinder::Finder.new(table) }
+  let(:table) { Person.arel_table }
+
+  it 'should be able to find by equality' do
+    (subject == 'foo').should be_a_kind_of(ActiveRecordFinder::Finder)
+    (subject == 'foo').arel.should be_equivalent_to(table[:name].eq('foo'))
+  end
+
+  it 'should be able to find by inequality' do
+    (subject != 'foo').arel.should be_equivalent_to(table[:name].not_eq('foo'))
+  end
+
+  it 'should be able to verify if an attribute is nil' do
+    (subject.nil?).arel.should be_equivalent_to(table[:name].eq(nil))
+  end
+
+  it 'should be able to find by greater than' do
+    (subject > 'foo').arel.should be_equivalent_to table[:name].gt('foo')
+    (subject >= 'foo').arel.should be_equivalent_to table[:name].gteq('foo')
+  end
+
+  it 'should be able to find by lower than' do
+    (subject < 'foo').arel.should be_equivalent_to table[:name].lt('foo')
+    (subject <= 'foo').arel.should be_equivalent_to table[:name].lteq('foo')
+  end
+
+  it 'finds with IN' do
+    subject.in?(['foo']).arel.should be_equivalent_to table[:name].in(['foo'])
+  end
+
+  it 'finds with subselects' do
+    result = subject.in?(Person.where(age: 10))
+    result.arel.to_sql.should match(/select/i)
+  end
+
+  it 'should be able to find with LIKE' do
+    (subject =~ 'foo').arel.should be_equivalent_to table[:name].matches('foo')
+    (subject !~ 'foo').arel.should be_equivalent_to table[:name].does_not_match('foo')
+  end
+end

data/spec/activerecord_finder/finder_spec.rb

@@ -0,0 +1,32 @@
+require_relative "../helper"
+
+describe ActiveRecordFinder::Finder do
+  subject { ActiveRecordFinder::Finder.new(table) }
+  let(:table) { Person.arel_table }
+
+  it 'should return a empty arel if not being able to convert' do
+    subject.arel.should be_nil
+  end
+
+  it 'should not calculate equality' do
+    proc { subject == subject }.should raise_error(NoMethodError)
+    proc { subject != subject }.should raise_error(NoMethodError)
+  end
+
+  it 'should be able to "or" two conditions' do
+    c1 = table[:id].eq(1)
+    c2 = table[:name].eq(2)
+    ((subject.id == 1) | (subject.name == 2)).arel.should be_equivalent_to c1.or(c2)
+  end
+
+  it 'should be able to "and" two conditions' do
+    c1 = table[:id].eq(1)
+    c2 = table[:name].eq(2)
+    ((subject.id == 1) & (subject.name == 2)).arel.should be_equivalent_to c1.and(c2)
+  end
+
+  it 'should be able to negate the find' do
+    result = subject.name == 'foo'
+    (!result).arel.should be_equivalent_to Arel::Nodes::Not.new(table[:name].eq('foo'))
+  end
+end

data/spec/activerecord_finder/where_spec.rb

@@ -0,0 +1,38 @@
+require_relative "../helper"
+
+describe ActiveRecordFinder::Where do
+  let!(:bar) { Person.create! :name => 'Bar', :age => 17 }
+  let!(:seventeen) { Person.create! :name => 'Foo', :age => 17 }
+  let!(:eighteen) { Person.create! :name => 'Foo', :age => 18 }
+
+  after do
+    Person.delete_all
+  end
+
+  it 'finds using a block with one parameter' do
+    result = Person.restrict { |p| (p.name == 'Foo') & (p.age > 17) }
+    result.should == [eighteen]
+  end
+
+  it 'finds using a block with no parameters' do
+    result = Person.restrict { (name == 'Foo') & (age > 17) }
+    result.should == [eighteen]
+  end
+
+  it 'concatenates conditions' do
+    finder1 = Person.new_finder { age == 17 }
+    finder2 = Person.new_finder { name == "Foo" }
+    result = Person.restrict(finder1 & finder2)
+    result.should == [seventeen]
+  end
+
+  it 'concatenates arel conditions' do
+    pending
+    finder1 = Person.where(name: "Foo").arel
+    finder2 = Person.new_finder { age == 17 }
+    result = Person.where((finder2 & finder1).arel)
+    result.should == [seventeen]
+    result = Person.where((finder1 & finder2).arel)
+    result.should == [seventeen]
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: activerecord_finder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Maurício Szabo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: 
+email: mauricio.szabo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- lib/activerecord_finder/where.rb
+- lib/activerecord_finder/finder.rb
+- lib/activerecord_finder/comparator.rb
+- lib/activerecord_finder.rb
+- README.md
+- spec/activerecord_finder/finder_spec.rb
+- spec/activerecord_finder/comparator_spec.rb
+- spec/activerecord_finder/where_spec.rb
+homepage: http://github.com/mauricioszabo/arel_operators
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Better finder syntax (|, &, >=, <=) for ActiveRecord.
+test_files:
+- spec/activerecord_finder/finder_spec.rb
+- spec/activerecord_finder/comparator_spec.rb
+- spec/activerecord_finder/where_spec.rb
+has_rdoc: true