buscar 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.rvmrc

@@ -0,0 +1 @@
+rvm gemset use buscar

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+
+group :development do
+	gem 'bundler', '~> 1.0.0'
+	gem 'jeweler', '~> 1.5.1'
+	gem 'rspec', '>= 2.2.0'
+	gem 'rcov'
+	gem 'machinist', '>= 1.0.6'
+	gem 'faker', '>= 0.3.1'
+	gem 'activesupport', '>= 3.0.3'
+	gem 'actionpack', '>= 3.0.3'
+	gem 'activerecord', '>= 3.0.3'
+end

data/Gemfile.lock

@@ -0,0 +1,67 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionpack (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.6)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.3)
+    arel (2.0.6)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    faker (0.3.1)
+    git (1.2.5)
+    i18n (0.5.0)
+    jeweler (1.5.1)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    machinist (1.0.6)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.2.0)
+      rspec-core (~> 2.2)
+      rspec-expectations (~> 2.2)
+      rspec-mocks (~> 2.2)
+    rspec-core (2.2.1)
+    rspec-expectations (2.2.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.2.0)
+    tzinfo (0.3.23)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  actionpack (>= 3.0.3)
+  activerecord (>= 3.0.3)
+  activesupport (>= 3.0.3)
+  bundler (~> 1.0.0)
+  faker (>= 0.3.1)
+  jeweler (~> 1.5.1)
+  machinist (>= 1.0.6)
+  rcov
+  rspec (>= 2.2.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 jarrett
+
+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/README.markdown

@@ -0,0 +1,3 @@
+# Buscar
+
+# See TagIndex in spec/index_spec.rb for detailed usage information.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'bundler'
+begin
+	Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+	$stderr.puts e.message
+	$stderr.puts "Run `bundle install` to install missing gems"
+	exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+	gem.name = "buscar"
+	gem.summary = %Q{Searching, sorting, and pagination for Rails}
+	gem.description = %Q{Simplifies searching, sorting, and pagination of ActiveRecord models. Includes a model class and a view helper.}
+	gem.email = "jarrettcolby@gmail.com"
+	gem.homepage = "http://github.com/jarrett/buscar"
+	gem.authors = ["jarrett"]
+	gem.add_dependency "activesupport", ">= 3.0.2"
+	gem.add_dependency "activerecord", ">= 3.0.2"
+	# Strictly speaking, you don't need ActionView to use the helpers. They rely on some methods ActionView provides,
+	# but in principle, those methods could be defined by something other than ActionView. So, we make ActionView
+	# (part of ActionPack) a development dependency for the sake of the specs.
+	gem.add_development_dependency "actionpack", ">= 3.0.2"
+	gem.add_development_dependency "rspec", ">= 2.1.0"
+	gem.add_development_dependency "sqlite3-ruby", ">= 1.2.5"
+	gem.add_development_dependency "machinist", ">= 1.0.6"
+	gem.add_development_dependency "faker", ">= 0.3.1"
+	gem.add_development_dependency "webrat", ">= 0.7.2"
+	# gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settingsend
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+	test.libs << 'lib' << 'test'
+	test.pattern = 'test/**/test_*.rb'
+	test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+	test.libs << 'test'
+	test.pattern = 'test/**/test_*.rb'
+	test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+	version = File.exist?('VERSION') ? File.read('VERSION') : ""
+	
+	rdoc.rdoc_dir = 'rdoc'
+	rdoc.title = "Buscar #{version}"
+	rdoc.rdoc_files.include('README*')
+	rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/buscar.gemspec

@@ -0,0 +1,114 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{buscar}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["jarrett"]
+  s.date = %q{2010-12-07}
+  s.description = %q{Simplifies searching, sorting, and pagination of ActiveRecord models. Includes a model class and a view helper.}
+  s.email = %q{jarrettcolby@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+    ".rvmrc",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "buscar.gemspec",
+    "lib/buscar.rb",
+    "lib/buscar/helpers.rb",
+    "lib/buscar/index.rb",
+    "lib/buscar/railtie.rb",
+    "spec/blueprint.rb",
+    "spec/helpers_spec.rb",
+    "spec/index_spec.rb",
+    "spec/matchers.rb",
+    "spec/spec_helper.rb",
+    "spec/test_db.rb"
+  ]
+  s.homepage = %q{http://github.com/jarrett/buscar}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Searching, sorting, and pagination for Rails}
+  s.test_files = [
+    "spec/blueprint.rb",
+    "spec/helpers_spec.rb",
+    "spec/index_spec.rb",
+    "spec/matchers.rb",
+    "spec/spec_helper.rb",
+    "spec/test_db.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_development_dependency(%q<rspec>, [">= 2.2.0"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<machinist>, [">= 1.0.6"])
+      s.add_development_dependency(%q<faker>, [">= 0.3.1"])
+      s.add_development_dependency(%q<activesupport>, [">= 3.0.3"])
+      s.add_development_dependency(%q<actionpack>, [">= 3.0.3"])
+      s.add_development_dependency(%q<activerecord>, [">= 3.0.3"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 3.0.2"])
+      s.add_runtime_dependency(%q<activerecord>, [">= 3.0.2"])
+      s.add_development_dependency(%q<actionpack>, [">= 3.0.2"])
+      s.add_development_dependency(%q<rspec>, [">= 2.1.0"])
+      s.add_development_dependency(%q<sqlite3-ruby>, [">= 1.2.5"])
+      s.add_development_dependency(%q<machinist>, [">= 1.0.6"])
+      s.add_development_dependency(%q<faker>, [">= 0.3.1"])
+      s.add_development_dependency(%q<webrat>, [">= 0.7.2"])
+    else
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_dependency(%q<rspec>, [">= 2.2.0"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<machinist>, [">= 1.0.6"])
+      s.add_dependency(%q<faker>, [">= 0.3.1"])
+      s.add_dependency(%q<activesupport>, [">= 3.0.3"])
+      s.add_dependency(%q<actionpack>, [">= 3.0.3"])
+      s.add_dependency(%q<activerecord>, [">= 3.0.3"])
+      s.add_dependency(%q<activesupport>, [">= 3.0.2"])
+      s.add_dependency(%q<activerecord>, [">= 3.0.2"])
+      s.add_dependency(%q<actionpack>, [">= 3.0.2"])
+      s.add_dependency(%q<rspec>, [">= 2.1.0"])
+      s.add_dependency(%q<sqlite3-ruby>, [">= 1.2.5"])
+      s.add_dependency(%q<machinist>, [">= 1.0.6"])
+      s.add_dependency(%q<faker>, [">= 0.3.1"])
+      s.add_dependency(%q<webrat>, [">= 0.7.2"])
+    end
+  else
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+    s.add_dependency(%q<rspec>, [">= 2.2.0"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<machinist>, [">= 1.0.6"])
+    s.add_dependency(%q<faker>, [">= 0.3.1"])
+    s.add_dependency(%q<activesupport>, [">= 3.0.3"])
+    s.add_dependency(%q<actionpack>, [">= 3.0.3"])
+    s.add_dependency(%q<activerecord>, [">= 3.0.3"])
+    s.add_dependency(%q<activesupport>, [">= 3.0.2"])
+    s.add_dependency(%q<activerecord>, [">= 3.0.2"])
+    s.add_dependency(%q<actionpack>, [">= 3.0.2"])
+    s.add_dependency(%q<rspec>, [">= 2.1.0"])
+    s.add_dependency(%q<sqlite3-ruby>, [">= 1.2.5"])
+    s.add_dependency(%q<machinist>, [">= 1.0.6"])
+    s.add_dependency(%q<faker>, [">= 0.3.1"])
+    s.add_dependency(%q<webrat>, [">= 0.7.2"])
+  end
+end
+

data/lib/buscar.rb

@@ -0,0 +1,3 @@
+require 'buscar/index.rb'
+require 'buscar/helpers.rb'
+require 'buscar/railtie.rb'

data/lib/buscar/helpers.rb

@@ -0,0 +1,79 @@
+module Buscar
+	module Helpers
+		# Accepts an instance of Buscar::Index, which will tell it the total number of pages, the current page, and the number of records per page.
+		# Accepts a block, which is yielded each page number and must return a URL to that page.
+		def page_links(index)
+			unless block_given?
+				raise ArgumentError, 'page_links requires a block.'
+			end
+			total_pages = index.page_count
+			if total_pages > 1
+				current_page = index.page + 1
+				content_tag('ul', 'class' => 'pagination') do
+					lis = ''
+					min_page = current_page - 2
+					min_page = 1 if min_page < 1
+					max_page = current_page + 2
+					max_page = total_pages if max_page > total_pages
+					if current_page > 1
+						lis << content_tag('li', link_to('&laquo; Back'.html_safe, yield(current_page - 1)))
+					end
+					if min_page > 1
+						lis << content_tag('li', link_to('1', yield(1)))
+					end
+					if min_page > 2
+						lis << content_tag('li', '...')
+					end
+					(min_page..max_page).each do |page|
+						lis << content_tag('li') do
+							if current_page.to_i == page
+								page.to_s
+							else
+								link_to page, yield(page)
+							end
+						end
+					end
+					if max_page < total_pages - 1
+						lis << content_tag('li', '...')
+					end
+					if max_page < total_pages				
+						lis << content_tag('li', link_to(total_pages, yield(total_pages)))
+					
+					end
+					if current_page < total_pages
+						lis << content_tag('li', link_to('Next &raquo;'.html_safe, yield(current_page + 1)))
+					end
+					lis.html_safe
+				end.html_safe
+			else
+				nil
+			end
+		end
+		
+		def buscar_index_menu(index, type, options)
+			options.reverse_merge! :link_to_current => true
+			content_tag('ul', :class => "#{type}_menu") do
+				choices = ''
+				index.send("#{type}_param_options").each do |param, label_str|
+					choices << content_tag('li') do
+						label_str = param.to_s.humanize if label_str.nil?
+						if !options[:link_to_current] and index.filter_param.to_s == param.to_s
+							('<span class="selected">' + label_str + '</span>').html_safe
+						else
+							link_to label_str, yield(param)
+						end
+					end
+				end
+				choices.html_safe
+			end.html_safe
+		end
+		
+		def filter_menu(index, options = {}, &block)
+			buscar_index_menu(index, 'filter', options, &block)
+		end
+		
+		def sort_menu(index, options = {}, &block)
+			buscar_index_menu(index, 'sort', options, &block)
+		end
+	end
+end

data/lib/buscar/index.rb

@@ -0,0 +1,171 @@
+module Buscar
+	class Index
+		include Enumerable
+		
+		# Views can call this method to iterate over the current page's records. Uses
+		# the value returned by #page, which in turn uses the value of @params[:page]
+		def each
+			records_on_page(page).each do |record|
+				yield record
+			end
+		end
+		
+		def empty?
+			@records.empty?
+		end
+		
+		# Returns one of the following in descending order of preference:
+		# - params[:filter]
+		# - default_filter_option
+		# - 'none'
+		def filter_param
+			@params[:filter] || (respond_to?(:default_filter_option, true) ? default_filter_option : 'none')
+		end
+		
+		def filter_param_options
+			filter_options.collect do |opt|
+				arr = [opt[0]]
+				arr << opt[2] if opt.length == 3
+				arr
+			end
+		end
+		
+		def self.generate(*args)
+			index = new(*args)
+			index.generate!
+			index
+		end
+		
+		def generate!
+			unless respond_to?(:finder, true)
+				raise 'Subclasses of Index must define #finder, which must return something that responds to #find. For example, #finder may return an ActiveRecord::Base subclass.'
+			end
+			
+			raise "Buscar::Index#conditions is deprecated. Name your method where_clause instead." if respond_to?(:conditions, true)
+			raise "Buscar::Index#order is deprecated. Name your method order_clause instead." if respond_to?(:order, true)
+			raise "Buscar::Index#include_clause is deprecated. Name your method includes_clause instead." if respond_to?(:include, true)
+			
+			@records = finder.scoped # Get the bare relation object in case none of the modifiers are used
+			# Use each AR query modifier other than #where and #order if applicable
+			%w(having select group limit offset joins includes lock readonly from).each do |meth|
+				@records = @records.send(meth, send("#{meth}_clause".to_sym)) if respond_to?("#{meth}_clause".to_sym, true)
+			end
+			
+			chained_filters = filter
+			chained_filters = chain(chained_filters) unless chained_filters.is_a?(Chain) # filter might return a Chain or a single filtering rule. If it's a single one, we'll put it in an array.
+			@filter_procs = chained_filters.select { |f| f.is_a?(Proc) } # Procs will be triggered by the first call to #records so as not to defeat lazy loading
+			where_filters = chained_filters.select { |f| !f.is_a?(Proc) } # SQL filters can be used right away
+			where_filters.each do |filt|
+				@records = @records.where(filt)
+			end
+			
+			sort_rule = sort
+			# If sorting by a proc, do it on the first call to #records so as not to defeat lazy loading 
+			if sort_rule.is_a?(Proc)
+				@sort_proc = sort_rule
+			else
+				@records = @records.order(sort_rule)
+			end
+		end
+		
+		def initialize(params = {})
+			@params = params
+		end
+		
+		def length
+			@records.length
+		end
+		
+		def optional_params(*keys)
+			keys.inject({}) do |hash, key|
+				unless @params[key].blank?
+					hash[key] = @params[key]
+				end
+				hash
+			end
+		end
+		
+		# The current page, as determined by @params[:page]. Since we want the user to see the page array as one-based,
+		# but we use zero-based indices internally, we subtract one from the page number.
+		#
+		# Thus, the return value is a zero-based offset.
+		def page
+			(@params[:page] || @params['page'] || 1).to_i - 1
+		end
+		
+		def page_count
+			(@records.length.to_f / records_per_page).ceil
+		end
+		
+		attr_reader :params
+		
+		# page_num is zero-based for this method.
+		def records_on_page(page_num)
+			if paginate?
+				@records.slice((page_num) * records_per_page, records_per_page)
+			else
+				@records
+			end
+		end
+		
+		# Returns one of the following in descending order of preference:
+		# - params[:sort]
+		# - default_sort_option
+		# - 'none'
+		def sort_param
+			@params[:sort] || (respond_to?(:default_sort_option, true) ? default_sort_option : 'none')
+		end
+		
+		def sort_param_options
+			sort_options.collect do |opt|
+				arr = [opt[0]]
+				arr << opt[2] if opt.length == 3
+				arr
+			end
+		end
+		
+		def records
+			unless @procs_called
+				@filter_procs.each do |proc|
+					@records = @records.select(&proc)
+				end
+				@records = @records.sort_by(&@sort_proc) if @sort_proc
+				@procs_called = true
+			end
+			@records
+		end
+		
+		private
+		
+		class Chain < Array; end
+		
+		def chain(*elements)
+			Chain.new(elements)
+		end
+		
+		# Return something for #where, a Proc, or an array
+		def filter
+			if respond_to?(:filter_options, true) and (option = filter_options.assoc(filter_param))
+				option[1]
+			else
+				nil
+			end
+		end
+		
+		def paginate?
+			true
+		end
+		
+		def records_per_page
+			@params[:records_per_page] || 50
+		end
+		
+		def sort
+			if respond_to?(:sort_options, true) and (option = sort_options.assoc(sort_param))
+				option[1]
+			else
+				nil
+			end
+		end
+	end
+end