activerecord-multiconditions 0.1.0

data/CHANGELOG

@@ -0,0 +1,5 @@
+= Changelog
+
+== Release 0.1.0
+
+  * Initial public release.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2008 Simone Carletti <weppos@weppos.net>
+
+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/Manifest

@@ -0,0 +1,13 @@
+CHANGELOG
+lib/multi_conditions.rb
+MIT-LICENSE
+Rakefile
+README
+setup.rb
+test/db/test.sqlite3
+test/helper.rb
+test/helper_database.rb
+test/test_all.rb
+test/unit/multi_conditions_test.rb
+TODO
+Manifest

data/README

@@ -0,0 +1,189 @@
+= ActiveRecord::MultiConditions
+
+MultiConditions is a simple ActiveRecord plugin for storing ActiveRecord query conditions and make complex queries painless.
+
+
+== Overview
+
+This plugin doesn't replace ActiveRecord#with_scope method,
+nor the basic :condition usage but extends it with the ability
+of storing illimitate conditions in multiple step.
+
+  conditions = MultiConditions.new
+  # ... do some elaboration
+  conditions.append_condition(['active = ? AND query LIKE ?', true, '%foo']
+  # ... other elaboration
+  conditions.append_condition(['name = ?', 'aname']
+  
+  conditions.to_conditions
+  # => "active = true AND query LIKE '%foo' AND name = 'aname'"
+
+
+== Dependencies
+
+* Ruby 1.8.6
+* ActiveRecord 2.0 (or greater)
+
+If you want to run the test suite:
+
+* sqlite3-ruby
+
+
+== Source
+
+MultiConditions source code is managed via GIT and hosted at GitHub: http://github.com/weppos/activerecord-multiconditions/.
+
+
+== Download and Installation
+
+Installing ActiveRecord MultiConditions as a GEM is probably the best and easiest way. You must have {RubyGems}[http://rubyforge.org/projects/rubygems/] installed for the following instruction to work:
+
+    $ sudo gem install activerecord-multiconditions
+
+To install the library manually grab the source code from the website, navigate to the root library directory and enter:
+
+    $ sudo ruby setup.rb
+
+If you need the latest development version you can download the source code from the GIT repositories listed above. Beware that the code might not as stable as the official release.
+
+
+== Usage
+
+First, don't forget to require the library.
+
+    gem 'activerecord-multiconditions'
+    require 'multi_conditions'
+
+Now +MultiConditions+ object is automatically available as subclass of any ActiveRecord object.
+
+    class Task < ActiveRecord::Base; end
+    
+    multiconditions = Task::Multiconditions.new
+    # => new instance
+
+=== Create a new instance
+
+As stated by the Important section above, you first need a valid ActiveRecord model
+to create a MultiConditions instance.
+Because MultiConditions helps you to deal with ActiveRecord queries,
+it's easy to understand why you *MUST* establish a valid database connection 
+and have at least one table (mapped with a Model) to query.
+
+If you use ActiveRecord from Rails, this is just a matter of creating a new Model.
+
+    # create the Task model
+    class Task < ActiveRecord::Base
+    end
+
+Now MultiConditions is automatically available within your Task namespace.
+You can use it in whatever class method, for example:
+
+    class Task < ActiveRecord::Base
+      
+      def complex_search()
+        c = MultiConditions.new(:foo => 'bar')
+        Task.find(:all, c.to_conditions)
+      end
+
+    end
+
+But you can also create a new instance from an other library, class or model.
+Just remember to initialize MultiConditions from its own namespace.
+
+    class Foo
+      class << self
+        def my_cool_conditions
+          Task::MultiConditions.new(:foo => 1).to_conditions
+        end
+      end
+    end
+
+    Foo.my_cool_conditions
+    # => 'foo = 1'
+
+=== Appending conditions
+
+You can append new conditions calling
+
+* #append_condition
+* #prepend_condition
+
+and passing the conditions you want to append or prepend.
+See Condition Types section to lean more about supported objects.
+
+  conditions = MultiConditions.new
+  conditions.append_condition(['active = ? AND query LIKE ?', true, '%foo']
+  conditions.prepend_condition(['name = ?', 'aname']
+  
+  conditions.to_conditions
+  # => "name = 'aname' AND active = true AND query LIKE '%foo'"
+    
+
+=== Condition types
+
+The MultiConditions object accepts any type of conditions supported by ActiveRecord,
+including Strings, Arrays and Hashes, and merges them alltogether
+just before sending the final :condition value to ActiveRecord search method.
+
+  conditions = MultiConditions.new
+  conditions.append_conditions(:foo => 1, :bar => 2)
+  conditions.append_conditions('active = 1')
+  conditions.append_conditions(['name LIKE ?', '%foo'])
+  
+  conditions.to_conditions
+  # => 'foo = 1 AND :bar = 2 AND active = 1 AND name LIKE '%foo'
+  
+See ActiveRecord::Base#find documentation for more conditions examples.
+
+
+
+== Important
+
+Once loaded, this library become part of ActiveRecord package and
+creates its own namespace at ActiveRecord::Base::MultiConditions.
+
+  require 'multi_conditions'
+
+For various reason, you cannot initialize a new ActiveRecord::Base::MultiConditions
+but you *MUST* initialize a MultiConditions instance from a Model.
+
+  # The wrong way
+  # raises Message: <"undefined method `abstract_class?' for Object:Class">
+  ActiveRecord::Base::MultiConditions.new
+  
+  # The right way
+  class Model < ActiveRecord::Base
+  
+    def a_method()
+      c = MultiConditions.new
+      find(:all, :conditions => c.to_conditions)
+    end
+  
+  end
+
+
+== Author
+
+* {Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
+
+If you like this software, please {recommend me}[http://www.workingwithrails.com/person/11967-simone-carletti] at Working with Rails.
+
+
+== Website and Project Home
+
+* {Project Homepage}[http://code.simonecarletti.com/activerecord-multiconditions]
+* {At GitHub}[http://github.com/weppos/activerecord-multiconditions/]
+
+
+== FeedBack and Bug reports
+
+Feel free to email {Simone Carletti}[mailto:weppos@weppos.net] 
+with any questions or feedback.
+
+Please submit your bug reports to the Redmine installation for MultiConditions
+available at http://code.simonecarletti.com/activerecord-multiconditions.
+
+
+== Changelog
+
+See CHANGELOG file.

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'echoe'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/lib")
+require 'multi_conditions'
+
+
+# Common package properties
+PKG_NAME    = ENV['PKG_NAME'] || ActiveRecord::Base::MultiConditions::GEM
+PKG_VERSION = ENV['PKG_VERSION'] || ActiveRecord::Base::MultiConditions::VERSION
+PKG_SUMMARY = "An ActiveRecord plugin for dealing with complex search :conditions."
+PKG_FILES   = FileList.new("{lib,test}/**/*.rb") do |fl|
+  fl.exclude 'TODO'
+  fl.include %w(README.rdoc README CHANGELOG MIT-LICENSE)
+  fl.include %w(Rakefile setup.rb)
+end
+RUBYFORGE_PROJECT = 'activerecord-multiconditions'
+
+if ENV['SNAPSHOT'].to_i == 1
+  PKG_VERSION << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+end
+
+
+Echoe.new(PKG_NAME, PKG_VERSION) do |p|
+  p.author = "Simone Carletti"
+  p.email = "weppos@weppos.net"
+  p.summary     = PKG_SUMMARY
+  p.description = <<-EOF
+    MultiConditions is a simple ActiveRecord plugin \
+    for storing ActiveRecord query conditions and make complex queries painless.
+    EOF
+  p.url = "http://code.simonecarletti.com/activerecord-multiconditions"
+  
+  p.version = PKG_VERSION
+  p.changes = ''
+  
+  p.dependencies = ['activerecord >=2.0.0']
+  p.rcov_options = ["-xRakefile"]
+  
+  p.need_zip = true
+  p.include_rakefile = true
+  
+  p.project = RUBYFORGE_PROJECT
+  
+  p.rdoc_pattern = /^(lib|CHANGELOG|MIT\-LICENSE|README)/
+end
+
+
+begin 
+  require 'code_statistics'
+  desc "Show library's code statistics"
+  task :stats do
+    CodeStatistics.new(["MultiConditions", "lib"], 
+                       ["Tests", "test"]).to_s
+  end
+rescue LoadError
+  puts "CodeStatistics (Rails) is not available"
+end

data/TODO

@@ -0,0 +1,9 @@
+= TODO
+
+* improve tests in order to use real queries instead of simple statements
+
+* add tests for different ActiveRecord versions
+
+* ... more
+
+* configure a Redmine installation to store TODO list! :)

data/activerecord-multiconditions.gemspec

@@ -0,0 +1,90 @@
+
+# Gem::Specification for Activerecord-multiconditions-0.1.0
+# Originally generated by Echoe
+
+Gem::Specification.new do |s|
+  s.name = %q{activerecord-multiconditions}
+  s.version = "0.1.0"
+
+  s.specification_version = 2 if s.respond_to? :specification_version=
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Simone Carletti"]
+  s.date = %q{2008-06-10}
+  s.description = %q{MultiConditions is a simple ActiveRecord plugin     for storing ActiveRecord query conditions and make complex queries painless.}
+  s.email = %q{weppos@weppos.net}
+  s.extra_rdoc_files = ["CHANGELOG", "lib/multi_conditions.rb", "MIT-LICENSE", "README"]
+  s.files = ["CHANGELOG", "lib/multi_conditions.rb", "MIT-LICENSE", "Rakefile", "README", "setup.rb", "test/db/test.sqlite3", "test/helper.rb", "test/helper_database.rb", "test/test_all.rb", "test/unit/multi_conditions_test.rb", "TODO", "Manifest", "activerecord-multiconditions.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://code.simonecarletti.com/activerecord-multiconditions}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Activerecord-multiconditions", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{activerecord-multiconditions}
+  s.rubygems_version = %q{1.1.1}
+  s.summary = %q{An ActiveRecord plugin for dealing with complex search :conditions.}
+  s.test_files = ["test/test_all.rb"]
+
+  s.add_dependency(%q<activerecord>, [">= 2.0.0"])
+end
+
+
+# # Original Rakefile source (requires the Echoe gem):
+# 
+# require 'rubygems'
+# require 'echoe'
+# 
+# $LOAD_PATH.unshift(File.dirname(__FILE__) + "/lib")
+# require 'multi_conditions'
+# 
+# 
+# # Common package properties
+# PKG_NAME    = ENV['PKG_NAME'] || ActiveRecord::Base::MultiConditions::GEM
+# PKG_VERSION = ENV['PKG_VERSION'] || ActiveRecord::Base::MultiConditions::VERSION
+# PKG_SUMMARY = "An ActiveRecord plugin for dealing with complex search :conditions."
+# PKG_FILES   = FileList.new("{lib,test}/**/*.rb") do |fl|
+#   fl.exclude 'TODO'
+#   fl.include %w(README.rdoc README CHANGELOG MIT-LICENSE)
+#   fl.include %w(Rakefile setup.rb)
+# end
+# RUBYFORGE_PROJECT = 'activerecord-multiconditions'
+# 
+# if ENV['SNAPSHOT'].to_i == 1
+#   PKG_VERSION << "." << Time.now.utc.strftime("%Y%m%d%H%M%S")
+# end
+# 
+# 
+# Echoe.new(PKG_NAME, PKG_VERSION) do |p|
+#   p.author = "Simone Carletti"
+#   p.email = "weppos@weppos.net"
+#   p.summary     = PKG_SUMMARY
+#   p.description = <<-EOF
+#     MultiConditions is a simple ActiveRecord plugin \
+#     for storing ActiveRecord query conditions and make complex queries painless.
+#     EOF
+#   p.url = "http://code.simonecarletti.com/activerecord-multiconditions"
+#   
+#   p.version = PKG_VERSION
+#   p.changes = ''
+#   
+#   p.dependencies = ['activerecord >=2.0.0']
+#   p.rcov_options = ["-xRakefile"]
+#   
+#   p.need_zip = true
+#   p.include_rakefile = true
+#   
+#   p.project = RUBYFORGE_PROJECT
+#   
+#   p.rdoc_pattern = /^(lib|CHANGELOG|MIT\-LICENSE|README)/
+# end
+# 
+# 
+# begin 
+#   require 'code_statistics'
+#   desc "Show library's code statistics"
+#   task :stats do
+#     CodeStatistics.new(["MultiConditions", "lib"], 
+#                        ["Tests", "test"]).to_s
+#   end
+# rescue LoadError
+#   puts "CodeStatistics (Rails) is not available"
+# end

data/lib/multi_conditions.rb

@@ -0,0 +1,167 @@
+# 
+# = ActiveRecord::MultiConditions
+#
+# An ActiveRecord plugin for dealing with complex search :conditions.
+# 
+#
+# Category::   ActiveRecord
+# Package::    ActiveRecord::MultiConditions
+# Author::     Simone Carletti <weppos@weppos.net>
+#
+#--
+# SVN: $Id$
+#++
+
+
+module ActiveRecord
+  class Base
+
+    #
+    # = ActiveRecord::MultiConditions
+    # 
+    # MultiConditions is a simple ActiveRecord plugin for storing ActiveRecord 
+    # query and make complex queries painless.
+    # 
+    # This plugin doesn't replace ActiveRecord#with_scope method,
+    # nor the basic :condition usage but extends it with the ability
+    # of storing illimitate conditions in multiple step.
+    # 
+    #   conditions = MultiConditions.new
+    #   # ... do some elaboration
+    #   conditions.append_condition(['active = ? AND query LIKE ?', true, '%foo']
+    #   # ... other elaboration
+    #   conditions.append_condition(['name = ?', 'aname']
+    #   
+    #   conditions.to_conditions
+    #   # => "active = true AND query LIKE '%foo' AND name = 'aname'"
+    # 
+    # The MultiConditions object accepts any type of conditions supported by ActiveRecord,
+    # including Strings, Arrays and Hashes, and merges them alltogether
+    # just before sending the final :condition value to ActiveRecord search method.
+    # 
+    #   conditions = MultiConditions.new
+    #   conditions.append_conditions(:foo => 1, :bar => 2)
+    #   conditions.append_conditions('active = 1')
+    #   conditions.append_conditions(['name LIKE ?', '%foo'])
+    #   
+    #   conditions.to_conditions
+    #   # => 'foo = 1 AND :bar = 2 AND active = 1 AND name LIKE '%foo'
+    #   
+    # See ActiveRecord::Base#find documentation for more conditions examples.
+    # 
+    # 
+    # == Important
+    # 
+    # Once loaded, this library become part of ActiveRecord package and
+    # creates its own namespace at ActiveRecord::Base::MultiConditions.
+    # 
+    # For various reason, you cannot initialize a new ActiveRecord::Base::MultiConditions
+    # but you *MUST* initialize a MultiConditions instance from a Model.
+    # 
+    #   # The wrong way
+    #   # raises Message: <"undefined method `abstract_class?' for Object:Class">
+    #   ActiveRecord::Base::MultiConditions.new
+    #   
+    #   # The right way
+    #   class Model < ActiveRecord::Base
+    #   
+    #     def a_method()
+    #       c = MultiConditions.new
+    #       find(:all, :conditions => c.to_conditions)
+    #     end
+    #   
+    #   end
+    #   
+    #
+    class MultiConditions
+
+      module Version #:nodoc:
+        MAJOR = 0
+        MINOR = 1
+        TINY = 0
+
+        STRING = [MAJOR, MINOR, TINY].join('.')
+      end
+
+      NAME            = 'ActiveRecord::MultiConditions'
+      GEM             = 'activerecord-multiconditions'
+      AUTHOR          = 'Simone Carletti <weppos@weppos.net>'
+      VERSION         = defined?(Version) ? Version::STRING : nil
+      STATUS          = 'alpha'
+      BUILD           = ''.match(/(\d+)/).to_a.first
+
+
+      # Conditions collection
+      attr_reader :conditions
+
+      # 
+      # Creates a new MultiConditions instance and initializes it with +conditions+.
+      # 
+      #   # empty instance
+      #   c = MultiConditions.new
+      # 
+      #   # new instance with a first value
+      #   c = MultiConditions.new(['condition = ?', 'value'])
+      # 
+      #   # initialization with block
+      #   c = MultiConditions.new do |condition|
+      #     condition.append_condition('foo = 1')
+      #     condition.append_condition('bar = 2')
+      #     condition.append_condition(:baz => 3)
+      #   end
+      #
+      def initialize(condition = nil, &block) # :yields: self
+        @conditions = []
+        append_condition(condition)
+        yield(self) if block_given?
+        self
+      end
+
+      # 
+      # Appends a new condition at the end of condition list.
+      # 
+      def append_condition(condition)
+        @conditions.push(prepare_condition(condition))    unless condition.nil?
+      end
+
+      # 
+      # Prepends a new condition at the beginning of condition list.
+      # 
+      def prepend_condition(condition)
+        @conditions.unshift(prepare_condition(condition)) unless condition.nil?
+      end
+
+      # 
+      # Returns a :conditions suitable representation of this object
+      # 
+      #   c = MultiConditions.new do |condition|
+      #     condition.append_condition('foo = 1')
+      #     condition.append_condition('bar = 2')
+      #     condition.append_condition(:baz => 3)
+      #   end
+      #   
+      #   c.to_conditions
+      #   # => 'foo = 1 AND bar = 2 AND baz = 3'
+      #   
+      #   # Example usage
+      #   find(:all, :conditions => c.to_conditions)
+      #
+      def to_conditions
+        @conditions.join(' AND ')
+      end
+      alias :to_s :to_conditions
+
+
+      protected
+
+        # normalize conditions to be stored
+        # for now use active record :sanitize_sql_for_conditions
+        # instead of dealing with custom methods.
+        def prepare_condition(condition)
+          Task.send(:sanitize_sql_for_conditions, condition)
+        end
+
+    end
+
+  end
+end