record_filter 0.9.12

data/.gitignore

@@ -0,0 +1,9 @@
+coverage
+perf
+pkg
+rdoc
+*.gem
+*.swp
+tmp
+_site
+

data/CHANGELOG

@@ -0,0 +1,232 @@
+= 0.9.9
+
+* Fixed a bug where distinct wasn't being applied when chaining with has_many
+:through associations.
+
+= 0.9.8
+
+* BREAKING CHANGE: changed the 'limit' method so that the limit is always the
+first argument, with an optional offset as the second argument. This makes the
+functionality much clearer by avoiding obnoxious argument swapping.
+
+* BREAKING CHANGE: changed the arguments to the 'join' method so that it
+takes a class and an options hash. The options hash can contain a :join_type
+and an :alias, allowing only the arguments that the client wants to use to be
+specified. This will break existing code where the join type was passed as
+the second argument.
+
+* BREAKING CHANGE: changed the arguments to the 'having' method so that it
+takes an association name and an options hash. The options hash takes
+:join_type and :alias. This will break existing code where the join_type was
+passed as the first argument to the method. The alias is a new option that
+allows you to alias joins, which lets you join in the same association twice.
+
+* Added a distinct method to force queries to be distinct.
+
+= 0.9.7
+
+* Fix a bug where explicit joins would not honor different aliases if joining
+the same class twice.
+
+= 0.9.6
+
+* Build the alias for explicit join tables correctly for multi-word class
+names.
+
+* Set params[:readonly] to false by default. Not sure why we need to do that.
+
+* If nil is passed as the argument to a comparison operator, don't fail with a
+lack of bind variables, just do what AR does and compare against NULL.
+
+* Add ability to order on columns in tables that were explicitly joined.
+
+= 0.9.5
+
+* Added 'and' and 'or' methods to the DSL::Restriction class so that you can do
+things like with(:expired_at).gt(Time.now).or.is_null
+
+= 0.9.4
+
+* Stop forcing order to take a real column name and let it accept a string
+
+* Added an offset method to the DSL so that we can do offsets separately from
+limits
+
+* Some small performance improvements
+
+* Added a test to make sure that the IN restriction can take a range
+
+* Changed the default rake task to run db:spec:prepare first
+
+* Added metric_fu for code quality metrics tests
+
+* Refactored a bunch of code to improve the metric numbers
+
+= 0.9.3
+
+* Fix a bug when using class_name on belongs_to associations without
+foreign_key
+
+= 0.9.2
+
+* Ruby 1.9 compatability
+
+= 0.9.1
+
+* Change group_by so that it will not throw an exception for missing column
+names, since we want to be able to group by arbitrary things.
+
+= 0.9.0 
+
+* Added a github pages page with a quick intro.
+
+* Add tests for working with default scopes.
+
+* de-hackify the default aliases for explicit joins.
+
+* Fix a bug where strings wouldn't work as the names of associations in
+implicit joins.
+
+* Improve the README
+
+* Fix a bug when combining joins across multiple named filters that introduce
+the same join.
+
+= 0.8.0
+
+* Raise an exception when calling order with something that isn't :asc or
+:desc
+
+* Use hanna for spiffy rdocs.
+
+* Raise an exception when attempting to add a named filter to a class if there
+is already an existing filter with the same name.
+
+* Documentation. 
+
+* Refactored the custom DSL subclass creation code into a DSLFactory class.
+
+* Added a (fairly simple) performance test.
+
+* Get source_type option working for has_many.
+
+* Correct hard-coded primary key columns.
+
+= 0.6.0
+
+* 100% test coverage. That's right, 100%.
+
+* Added fixes for various options on AR associations.
+
+* Support calling named filters from within joins in filters.
+
+* Stop using _inheritable_attribute for accessing the named filters and just recurse for
+them.
+
+* Change the tests for named filters to use anonymous classes so that we're
+sure we're starting from a blank slate.
+
+* Make the API work correctly for anonymous classes.
+
+* Correctly handle the case where nil or [] is passed as an argument to the IN
+restriction.
+
+* Added is_not_null as a nicer version of is_null.not
+
+= 0.2.0 
+
+* Changed the available join types to inner, left and right.
+
+* Fix a bug where we used the wrong type in polymorphic association joins.
+
+* Use with_scope when chaining filters, named_filters, and AR associations in
+order to keep the filter data instead of passing the query parameters directly
+and combining them in order to make this work correctly with AR.
+
+* Fix a bug when calling .filter in a chain of associations and named filters.
+
+* Don't include conditions unless there are actually conditions specified.
+
+* Fix a bug where the first and last methods would fail.
+
+* Delegate array methods through to the result of the filter.
+
+* Add proxy_options to mimic the API of named_scope for getting the options
+that result from a given query.
+
+* Support chaining with AR associations... (i.e. Blog.posts.published)
+
+* Support has_many and has_one :through
+
+= 0.1.4
+
+* Join on both the id and type for polymorphic joins.
+
+* Fix a bug where we were using the incorrect table names in joins and
+ordering with joins.
+
+* Change != to the SQL standard <>.
+
+* Fix invalid SQL generated by not_all and not_any.
+
+* Detect count/size/length queries and do the appropriate distinct clause for
+those count queries.
+
+* Do DISTINCT searches for queries that involve specific types of joins.
+
+* Allow passing a join type as the first argument to having.
+
+* Restructured the explicit join API
+
+* Raise exceptions when doing an explicit join using columns that don't exist.
+
+* Allow explicit joins on values: left_join(:class_name, :table_alias, :rcol
+=> 'Post'...)
+
+* Added a filter_class method to the DSL for getting the class that is being
+filtered.
+
+* Added custom join feature: left_join(:table_name, :table_alias, :rcol =>
+:lcol...)
+
+* Changed custom exceptions to subclass StandardError and not crash the entire
+app when throwing one (thanks RailsEnvy).
+
+= 0.1.3
+
+* Fixed a bug in filter.rb when trying to chain to named_scopes or things that
+are otherwise not named_filters.
+
+* Made a named_filters accessor for getting the list of filters that apply to
+a particular class.
+
+* Added none_of and not_all_of conjunctions.
+
+* Changed the between restriction to take either a range, a tuple, or two
+values.
+
+* Support multiple joins in one having statement through having(:posts =>
+:comments)
+
+* Added a CHANGELOG
+
+= 0.1.2
+
+* Add LIKE and NOT LIKE restrictions
+
+* Replace active record objects with their ids if passed as the value for a
+resriction.
+
+= 0.1.1
+
+* Add group_by
+
+* Raise informative exceptions when columns or associations are not found for
+a given filter
+
+* Alias is_null restriction to nil and null
+
+* Alias comparison restrictions to gt, lt, lte, gte
+
+* Add greater_than_or_equal_to and less_than_or_equal_to restrictions.
+

data/README.rdoc

@@ -0,0 +1,354 @@
+= record_filter
+
+record_filter is a DSL for specifying ActiveRecord queries in pure Ruby.
+It has support for filters created on the fly and for named filters that are associated with object types.
+record_filter has the following top-level features:
+
+* Pure ruby API eliminates the need for hard-coded SQL in most cases.
+* Works seamlessly with existing ActiveRecord APIs, including named scopes.
+* Supports creation of ad-hoc filters as well as named filters that can be associated with object types.
+* Allows chaining of filters with each other and with named scopes to create complex queries.
+* Takes advantage of the associations in your ActiveRecord objects for a clean implicit join API.
+
+== Documentation
+
+The complete RDoc documentation is available at http://aub.github.com/record_filter/rdoc/. This page is
+intended to be a getting started guide that should cover the most common uses.
+
+== Installation
+
+  gem install aub-record_filter --source=http://gems.github.com
+
+In Rails, you'll need to add this to your config/environment.rb file:
+
+  config.gem 'aub-record_filter', :lib => 'record_filter', :source => 'http://gems.github.com'
+
+== Using Filters
+
+Given a Blog model having a has_many relationship with a Post model, a simple 
+filter with conditions and joins might look like this.
+
+  Blog.filter do
+    with(:created_at).greater_than(1.day.ago)
+    having(:posts).with(:permalink, nil)
+  end
+
+This could be expressed in ActiveRecord as:
+
+  Blog.all(
+    :joins => :posts, 
+    :conditions => {
+      :posts => {:permalink => nil},
+      :created_at => 1.day.ago..Time.now
+    }
+  )
+
+and it returns the same result, a list of Blog objects that are the result of the query. This
+type of filter is designed to be created on the fly, but if you have a filter that you would like
+to use in more than one place, it can be added to a class as a named filter. The following example
+creates the same filter as above and executes it:
+
+  class Blog < ActiveRecord::Base
+    named_filter(:new_with_unlinked_posts) do
+      with(:created_at).greater_than(1.day.ago)
+      having(:posts).with(:permalink, nil)
+    end
+  end
+
+  Blog.new_with_unlinked_posts
+
+This returns the same result as the example above but with the advantages that it is
+easily reusable and that it can be combined with other named filters to produce a more
+complex query:
+
+  class Post < ActiveRecord::Base
+    named_filter(:title_is_monkeys) { with(:title, 'monkeys') }
+    named_filter(:permalink_is_donkeys) { with(:permalink, 'donkeys') }
+  end
+
+  Post.title_is_monkeys.permalink_is_donkeys
+
+This example will return all of the posts that meet both animal-related conditions. 
+There is no limit to the number of filters that can be combined, and because record_filter works 
+seamlessly with named scopes, they can also be combined in this way as well. 
+
+Named filters can also be customized by taking any number of arguments. The example above can
+be replicated with the following filter:
+
+  class Post < ActiveRecord::Base
+    named_filter(:with_title_and_permalink) do |title, permalink|
+      with(:title, title)
+      with(:permalink, permalink)
+    end
+  end
+
+  Post.with_title_and_permalink('monkeys', 'donkeys')
+
+Named filters can also be called from other named filters and will be invoked on the correct
+model even if called from a join.
+
+  class Comment < ActiveRecord::Base
+    named_filter(:offensive) { with(:offensive, true) }
+  end
+
+  class Post < ActiveRecord::Base
+    named_filter(:using_other_filter) do
+      having(:comments) do
+        offensive
+      end
+    end
+  end
+
+  Post.using_other_filter
+
+== Specifying Filters
+
+record_filter supports all of the SQL query abstractions provided by ActiveRecord, specifically:
+
+* Conditions
+* Boolean operations
+* Joins
+* Limits
+* Offsets
+* Ordering
+* Grouping
+
+The following example shows the use of each of these techniques:
+
+  Post.filter do
+    any_of do
+      with(:permalink).is_null
+      having(:comments) do
+        with(:offensive, true)
+      end
+    end
+    limit(100, 10)
+    order(:created_at, :desc)
+    group_by(:comments => :offensive)
+  end
+
+=== Conditions
+
+Conditions are specified using the 'with' function, which takes as its first argument
+the name of the column to restrict. If a second argument is given, it will automatically
+be used as the value in an equality condition. The 'with' function will return a Restriction
+object that has methods to specify a number of different conditions and to negate them:
+
+  with(:permalink, 'aardvarks')            # ['permalink = ?', 'aardvarks']
+  with(:permalink).equal_to('sheep')       # ['permalink = ?', 'sheep']
+  with(:permalink).not.equal_to('cats')    # ['permailnk <> ?', 'cats']
+
+  with(:permalink, nil)                    # ['permalink IS NULL']
+  with(:permalink).is_null                 # ['permalink IS NULL']
+  with(:permalink, nil).not                # ['permalink IS NOT NULL']
+  with(:permalink).is_not_null             # ['permalink IS NOT NULL']
+
+The following condition types are supported through the Restriction API:
+
+* Equality
+* Comparisons (> >= < <=)
+* Between
+* In
+* Is null
+* Like
+* Negation of all of the above
+
+And here are some examples. See the RDoc page for 
+{DSL::Restriction}[http://aub.github.com/record_filter/rdoc/classes/RecordFilter/DSL/Restriction.html] 
+for more details on how to use them.
+
+  with(:featured_at).greater_than(Time.now)  # ['featured_at > ?', Time.now]
+
+  with(:price).lte(1000)                     # ['price <= ?', 1000]
+
+  with(:created_at).between(time_a..time_b)  # ['created_at BETWEEN ? AND ?', time_a, time_b]
+
+  with(:id).in([1, 2, 3])                    # ['id in (?)', [1, 2, 3]]
+
+  with(:id).not_in([4, 5, 6])                # ['id NOT IN (?)', [4, 5, 6]]
+
+  with(:content).like('%easy%')              # ['content LIKE ?', '%easy%']
+
+  with(:content).not.like('%hard%')          # ['content NOT LIKE ?', '%hard%']
+
+The comparison operators (greater_than, less_than, greater_than_or_equal_to and less_than_or_equal_to)
+are aliased to their short forms (gt, lt, gte and lte).
+
+It is also possible to specify multiple conditions on a single line using the 'and' and 'or' methods,
+eliminating the need to use a conjunction block in many common cases.
+
+  with(:expired_at).gt(Time.now).or.is_null  # ['expired_at > ? OR expired_at IS NULL', Time.now]
+
+  with(:id).gt(100).and.lt(1000)             # ['id > ? AND id < ?', 100, 1000]
+
+=== Boolean Operations
+
+Conditions can be combined with boolean operators using the methods all_of, any_of, none_of
+and not_all_of. These methods take a block where any conditions they contain will be combined
+using AND, OR and NOT to create the correct clause. The block can also contain any number of
+joins or other boolean operations. The default operator is all_of.
+
+  Post.filter do
+    with(:id, 4)
+    with(:permalink, 'ack')
+  end
+
+  # ['id = ? AND permalink = ?', 4, 'ack']
+
+  Post.filter do
+    any_of do
+      with(:id, 3)
+      with(:permalink, 'booya')
+    end
+  end
+
+  # ['id = ? OR permalink = ?', 3, 'booya']
+
+  Post.filter do
+    none_of do
+      with(:id, 2)
+      with(:permalink, 'ouch')
+    end
+  end
+
+  # ['NOT (id = ? OR permalink = ?)', 2, 'ouch']
+
+  Post.filter do
+    not_all_of do
+      with(:id, 1)
+      with(:permalink, 'bonobo')
+    end
+  end
+
+  # ['NOT (id = ? AND permalink = ?)', 1, 'bonobo']
+
+=== Joins
+
+Joins in record_filter come in two varieties. Using the information in ActiveRecord associations,
+it is possible to perform most joins easily using the 'having' method, which requires no specification
+of the columns to use for the join. In cases where an association does not apply, it is also possible
+to create an explicit join that can include both the columns to combine as well as restrictions on
+the columns in the join table.
+
+In a filter for a Post model that has_many comments, the following two examples are equivalent:
+
+  having(:comments)
+
+  join(Comment, :join_type => :inner) do
+    on(:id => :post_id)
+  end
+
+With an explicit join, any number of columns can be matched in this way, and both join types
+accept a block in which any number of conditions, boolean operations, or other joins can be
+added. Explicit joins also allow conditions to be set on columns of the table being joined:
+
+  having(:comments).with(:offensive, true)
+
+  having(:comments) do
+    with(:created_at).greater_than(2.days.ago)
+  end
+
+  join(Comment, :join_type => :inner) do
+    on(:id => :commentable_id)
+    on(:commentable_type).equal_to('Post')
+    with(:created_at).less_than(1.year.ago)
+  end
+
+With implicit joins, it is also possible to use a hash as the association name, in which case
+multiple joins can be created with one statement. If the comment model has_one Author, this 
+example will join both tables and add a condition on the author.
+
+  having(:comments => :author).with(:name, 'Bob')
+
+For both join types, an options hash can be provided as the second argument for passing the join
+type and/or an alias to use for the joined table. The join type defaults to :inner, and the alias
+defaults to a unique name for identifying the table. Using aliases allows you to join to a given table
+twice with two different names. How about a contrived example? Awesome.
+
+  Blog.filter do
+    having(:posts, :join_type => :left, :alias => 'posts_1').with(:title, 'a')
+    having(:posts, :alias => 'posts_2').with(:title, 'b')
+  end
+
+  # SELECT DISTINCT "blogs".* FROM "blogs" 
+  #   LEFT OUTER JOIN "posts" AS posts_1 ON "blogs".id = posts_1.blog_id 
+  #   INNER JOIN "posts" AS posts_2 ON "blogs".id = posts_2.blog_id 
+  #   WHERE ((posts_1.title = 'a') AND (posts_2.title = 'b'))
+
+=== Limits and Offsets
+
+These are specified using the 'limit' method, which takes two arguments, the limit and the
+offset. The offset is optional. For specifying only offsets, the 'offset' method is also available.
+
+  limit(100, 10)   # :limit => 100, :offset => 100
+  limit(100)       # :limit => 100
+  offset(10)       # :offset => 10
+
+=== Ordering
+
+Ordering is done through the 'order' method, which accepts arguments for the column and direction.
+The column can either be passed as the name of a column in the class that is being filtered or as
+a hash that represents a path through the joined associations to the correct column. The direction argument
+should be either :asc or :desc and defaults to :asc if not given. Multiple calls to 'order' are
+allowed and will be applied in the order in which they were given.
+
+  Post.filter do
+    having(:comments).with(:offensive, true)
+    order(:created_at, :desc)
+    order(:comments => :id)
+  end
+
+  # :order => "'posts'.created_at DESC posts__comments.id ASC"
+
+=== Grouping
+
+Grouping is specified with the 'group_by' method, which accepts either the name of a column in the
+class that is being filtered or a hash that represents a path through the joined associations. If
+there are multiple calls to 'group_by' they will be combined in the final result, maintaining the
+order in which they were given.
+
+  Post.filter do
+    having(:comments).with(:created_at).greater_than(1.hour.ago)
+    group_by(:permalink)
+    group_by(:comments => :offensive)
+  end
+
+  # :group => "'posts'.permalink, posts__comments.offensive'
+
+=== Distinct
+
+Filters that include outer joins are automatically made distinct by record_filter. For filters that
+use inner joins, use the 'distinct' method in the DSL to force the select to be distinct.
+
+  Blog.filter do
+    with(:created_at).greater_than(1.day.ago)
+    having(:posts).with(:permalink, nil)
+    distinct
+  end
+  
+  # :select => "DISTINCT 'blogs'.*"
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008-2009 Aubrey Holland, Mat Brown
+
+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/Rakefile

@@ -0,0 +1,92 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+
+FileList['tasks/**/*.rake'].each { |file| load file }
+
+task :default => ["db:spec:prepare", :spec]
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'record_filter'
+    gemspec.summary = 'An ActiveRecord query API for replacing SQL with awesome'
+    gemspec.email = 'aubreyholland@gmail.com'
+    gemspec.homepage = 'http://github.com/aub/record_filter'
+    gemspec.add_dependency 'activerecord'
+    gemspec.add_development_dependency 'rspec'
+    gemspec.rubyforge_project = 'record-filter'
+    gemspec.description = 'RecordFilter is a Pure-ruby criteria API for building complex queries in ActiveRecord. It supports queries that are built on the fly as well as named filters that can be added to objects and chained to create complex queries. It also gets rid of the nasty hard-coded SQL that shows up in most ActiveRecord code with a clean API that makes queries simple and intuitive to build.'
+    gemspec.authors = ['Aubrey Holland', 'Mat Brown']
+  end
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = 'rdoc'
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+# Try to use hanna to create spiffier docs.
+begin
+  require 'hanna/rdoctask'
+rescue LoadError
+  require 'rake/rdoctask'
+end
+
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "record_filter #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.options << '--webcvs=http://github.com/aub/record_filter/tree/master/'
+end
+
+begin
+  require 'ruby-prof/task'
+
+  RubyProf::ProfileTask.new do |t|
+    t.test_files = FileList['test/performance_test.rb']
+    t.output_dir = 'perf'
+    t.printer = :graph_html
+    t.min_percent = 5
+  end
+rescue LoadError
+  puts 'Ruby-prof not available. Profiling tests are disabled.'
+end
+
+begin
+  require 'metric_fu'
+  MetricFu::Configuration.run do |config|
+    #define which metrics you want to use
+    config.metrics  = [:churn, :flog, :flay, :reek, :roodi, :rcov] # :saikuro, :stats
+    config.flay     = { :dirs_to_flay => ['lib']  } 
+    config.flog     = { :dirs_to_flog => ['lib']  }
+    config.reek     = { :dirs_to_reek => ['lib']  }
+    config.roodi    = { :dirs_to_roodi => ['lib'] }
+    config.saikuro  = { :output_directory => 'scratch_directory/saikuro', 
+                        :input_directory => ['lib'],
+                        :cyclo => "",
+                        :filter_cyclo => "0",
+                        :warn_cyclo => "5",
+                        :error_cyclo => "7",
+                        :formater => "text"} #this needs to be set to "text"
+    config.churn    = { :start_date => "1 year ago", :minimum_churn_count => 10}
+    config.rcov     = { :test_files => ['spec/**/*_spec.rb'],
+                        :rcov_opts => ["--sort coverage", 
+                                       "--no-html", 
+                                       "--text-coverage",
+                                       "--no-color",
+                                       "--profile",
+                                       "--exclude spec"]}
+  end
+rescue LoadError
+  puts 'Install metric_fu for code quality metric tests.'
+end
+

data/TODO

@@ -0,0 +1,3 @@
+* Add ability to do custom selects.
+* Add hooks for custom SQL in general.
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 9
+:patch: 12
+:major: 0