will_paginate 3.0.pre4 → 3.0.0

data/README.md

@@ -0,0 +1,61 @@
+# will_paginate
+
+will_paginate is a pagination library that integrates with Ruby on Rails, Sinatra, Merb, DataMapper and Sequel.
+
+Installation:
+
+``` ruby
+## Gemfile for Rails 3, Sinatra, and Merb
+gem 'will_paginate', '~> 3.0.pre4'
+```
+
+See [installation instructions][install] on the wiki for more info.
+
+
+## Basic will_paginate use
+
+``` ruby
+## perform a paginated query:
+@posts = Post.paginate(:page => params[:page])
+
+# or, use an explicit "per page" limit:
+Post.paginate(:page => params[:page], :per_page => 30)
+
+## render page links in the view:
+<%= will_paginate @posts %>
+```
+
+And that's it! You're done. You just need to add some CSS styles to [make those pagination links prettier][css].
+
+You can customize the default "per_page" value:
+
+``` ruby
+# for the Post model
+class Post
+  self.per_page = 10
+end
+
+# set per_page globally
+WillPaginate.per_page = 10
+```
+
+New in Active Record 3:
+
+``` ruby
+# paginate in Active Record now returns a Relation
+Post.where(:published => true).paginate(:page => params[:page]).order('id DESC')
+
+# the new, shorter page() method
+Post.page(params[:page]).order('created_at DESC')
+```
+
+See [the wiki][wiki] for more documentation. [Ask on the group][group] if you have usage questions. [Report bugs][issues] on GitHub.
+
+Happy paginating.
+
+
+[wiki]: https://github.com/mislav/will_paginate/wiki
+[install]: https://github.com/mislav/will_paginate/wiki/Installation "will_paginate installation"
+[group]: http://groups.google.com/group/will_paginate "will_paginate discussion and support group"
+[issues]: https://github.com/mislav/will_paginate/issues
+[css]: http://mislav.uniqpath.com/will_paginate/

data/Rakefile

@@ -1,42 +1,25 @@
-require 'rake/rdoctask'
-require 'rspec/core/rake_task'
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+  # no spec tasks
+else
+  task :default => :spec
 
-task :default => :spec
-
-desc 'Run ALL OF the specs'
-RSpec::Core::RakeTask.new(:spec) do |t|
-  # t.ruby_opts = '-w'
-end
-
-namespace :spec do
-  desc "Run Rails specs"
-  RSpec::Core::RakeTask.new(:rails) do |t|
-    t.pattern = %w'spec/finders/active_record_spec.rb spec/view_helpers/action_view_spec.rb'
+  desc 'Run ALL OF the specs'
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    # t.ruby_opts = '-w'
+    t.pattern = 'spec/finders/active_record_spec.rb' if ENV['DB'] and ENV['DB'] != 'sqlite3'
   end
-end
 
-desc 'Generate RDoc documentation for the will_paginate plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG.rdoc').
-    include('lib/**/*.rb').
-    exclude('lib/will_paginate/finders/active_record/named_scope*').
-    exclude('lib/will_paginate/finders/sequel.rb').
-    exclude('lib/will_paginate/view_helpers/merb.rb').
-    exclude('lib/will_paginate/deprecation.rb').
-    exclude('lib/will_paginate/core_ext.rb').
-    exclude('lib/will_paginate/version.rb')
-  
-  rdoc.main = "README.rdoc" # page to start on
-  rdoc.title = "will_paginate documentation"
-  
-  rdoc.rdoc_dir = 'doc' # rdoc output folder
-  rdoc.options << '--inline-source' << '--charset=UTF-8'
-  rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
+  namespace :spec do
+    desc "Run Rails specs"
+    RSpec::Core::RakeTask.new(:rails) do |t|
+      t.pattern = %w'spec/finders/active_record_spec.rb spec/view_helpers/action_view_spec.rb'
+    end
+  end
 end
 
-task :website do
-  Dir.chdir('website') do
-    %x(haml index.haml index.html)
-    %x(sass pagination.sass pagination.css)
-  end
+desc 'Run specs against both Rails 3.1 and Rails 3.0'
+task :rails3 do |variable|
+  system 'bundle exec rake spec && BUNDLE_GEMFILE=Gemfile.rails3.0 bundle exec rake spec:rails'
 end

data/lib/will_paginate.rb

@@ -1,23 +1,25 @@
-require 'will_paginate/deprecation'
-
-# = You *will* paginate!
-#
-# First read about WillPaginate::Finders::Base, then see
-# WillPaginate::ViewHelpers. The magical array you're handling in-between is
-# WillPaginate::Collection.
-#
-# Happy paginating!
+# You will paginate!
 module WillPaginate
 end
 
-if defined?(::Rails::Railtie)
+if defined?(Rails::Railtie)
   require 'will_paginate/railtie'
+elsif defined?(Rails::Initializer)
+  raise "will_paginate 3.0 is not compatible with Rails 2.3 or older"
 end
 
-if defined?(::Merb::Plugins)
+if defined?(Merb::AbstractController)
   require 'will_paginate/view_helpers/merb'
-  # auto-load the right ORM adapter
-  if adapter = { :datamapper => 'data_mapper', :activerecord => 'active_record', :sequel => 'sequel' }[Merb.orm]
-    require "will_paginate/finders/#{adapter}"
+
+  Merb::BootLoader.before_app_loads do
+    adapters = { :datamapper => 'data_mapper', :activerecord => 'active_record', :sequel => 'sequel' }
+    # auto-load the right ORM adapter
+    if adapter = adapters[Merb.orm]
+      require "will_paginate/#{adapter}"
+    end
   end
 end
+
+if defined?(Sinatra) and Sinatra.respond_to? :register
+  require 'will_paginate/view_helpers/sinatra'
+end

data/lib/will_paginate/{finders/active_record.rb → active_record.rb}

@@ -1,7 +1,9 @@
-require 'will_paginate/finders/base'
+require 'will_paginate/per_page'
+require 'will_paginate/page_number'
+require 'will_paginate/collection'
 require 'active_record'
 
-module WillPaginate::Finders
+module WillPaginate
   # = Paginating finders for ActiveRecord models
   # 
   # WillPaginate adds +paginate+, +per_page+ and other methods to
@@ -14,23 +16,6 @@ module WillPaginate::Finders
   #   @posts = Post.paginate :all, :page => params[:page], :order => 'created_at DESC'
   #
   module ActiveRecord
-    # In Rails, this is automatically called to mix-in pagination functionality to ActiveRecord.
-    def self.enable!
-      ::ActiveRecord::Base.extend Base
-      ::ActiveRecord::Base.extend ActiveRecord::Pagination
-      ::ActiveRecord::Base.extend ActiveRecord::BaseMethods
-
-      klasses = [::ActiveRecord::Relation]
-      if defined? ::ActiveRecord::Associations::CollectionProxy
-        klasses << ::ActiveRecord::Associations::CollectionProxy
-      else
-        klasses << ::ActiveRecord::Associations::AssociationCollection
-      end
-
-      # support pagination on associations and scopes
-      klasses.each { |klass| klass.send(:include, ActiveRecord::Pagination) }
-    end
-
     # makes a Relation look like WillPaginate::Collection
     module RelationMethods
       attr_accessor :current_page
@@ -46,7 +31,7 @@ module WillPaginate::Finders
       def limit(num)
         rel = super
         if rel.current_page
-          rel.offset((rel.current_page-1) * rel.limit_value)
+          rel.offset rel.current_page.to_offset(rel.limit_value).to_i
         else
           rel
         end
@@ -63,16 +48,27 @@ module WillPaginate::Finders
           if loaded? and size < limit_value and (current_page == 1 or size > 0)
             offset_value + size
           else
-            excluded = [:order, :limit, :offset]
-            excluded << :includes unless eager_loading?
-            rel = self.except(*excluded)
-            # TODO: hack. decide whether to keep
-            rel = rel.apply_finder_options(@wp_count_options) if defined? @wp_count_options
-            rel.count
+            @total_entries_queried = true
+            result = count
+            result = result.size if result.respond_to?(:size) and !result.is_a?(Integer)
+            result
           end
         end
       end
 
+      def count
+        if limit_value
+          excluded = [:order, :limit, :offset]
+          excluded << :includes unless eager_loading?
+          rel = self.except(*excluded)
+          # TODO: hack. decide whether to keep
+          rel = rel.apply_finder_options(@wp_count_options) if defined? @wp_count_options
+          rel.count
+        else
+          super
+        end
+      end
+
       # workaround for Active Record 3.0
       def size
         if !loaded? and limit_value
@@ -82,6 +78,15 @@ module WillPaginate::Finders
         end
       end
 
+      # overloaded to be pagination-aware
+      def empty?
+        if !loaded? and offset_value
+          count <= offset_value
+        else
+          super
+        end
+      end
+
       def total_pages
         (total_entries / limit_value.to_f).ceil
       end
@@ -89,7 +94,8 @@ module WillPaginate::Finders
       def clone
         other = super
         other.current_page = current_page unless other.current_page
-        other.total_entries = nil
+        other.total_entries = nil if defined? @total_entries_queried
+        other.wp_count_options = @wp_count_options if defined? @wp_count_options
         other
       end
 
@@ -106,20 +112,26 @@ module WillPaginate::Finders
 
     module Pagination
       def paginate(options)
-        pagenum, per_page, total = wp_parse_options(options)
-        count_options = options[:count]
-        options = options.except(:page, :per_page, :total_entries, :count)
-        rel = limit(per_page).page(pagenum)
+        options  = options.dup
+        pagenum  = options.fetch(:page) { raise ArgumentError, ":page parameter required" }
+        per_page = options.delete(:per_page) || self.per_page
+        total    = options.delete(:total_entries)
+
+        count_options = options.delete(:count)
+        options.delete(:page)
+
+        rel = limit(per_page.to_i).page(pagenum)
         rel = rel.apply_finder_options(options) if options.any?
         rel.wp_count_options = count_options    if count_options
+        rel.total_entries = total.to_i          unless total.blank?
         rel
       end
 
       def page(num)
-        pagenum = num.nil? ? 1 : num.to_i
-        raise ::WillPaginate::InvalidPage, num, pagenum if pagenum < 1
         rel = scoped.extending(RelationMethods)
-        rel = rel.offset((pagenum-1) * (rel.limit_value || per_page))
+        pagenum = ::WillPaginate::PageNumber(num.nil? ? 1 : num)
+        per_page = rel.limit_value || self.per_page
+        rel = rel.offset(pagenum.to_offset(per_page).to_i)
         rel = rel.limit(per_page) unless rel.limit_value
         rel.current_page = pagenum
         rel
@@ -142,7 +154,11 @@ module WillPaginate::Finders
       # application.
       # 
       def paginate_by_sql(sql, options)
-        WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
+        pagenum  = options.fetch(:page) { raise ArgumentError, ":page parameter required" }
+        per_page = options[:per_page] || self.per_page
+        total    = options[:total_entries]
+
+        WillPaginate::Collection.create(pagenum, per_page, total) do |pager|
           query = sanitize_sql(sql.dup)
           original_query = query.dup
           # add limit, offset
@@ -163,5 +179,20 @@ module WillPaginate::Finders
         end
       end
     end
+
+    # mix everything into Active Record
+    ::ActiveRecord::Base.extend PerPage
+    ::ActiveRecord::Base.extend Pagination
+    ::ActiveRecord::Base.extend BaseMethods
+
+    klasses = [::ActiveRecord::Relation]
+    if defined? ::ActiveRecord::Associations::CollectionProxy
+      klasses << ::ActiveRecord::Associations::CollectionProxy
+    else
+      klasses << ::ActiveRecord::Associations::AssociationCollection
+    end
+
+    # support pagination on associations and scopes
+    klasses.each { |klass| klass.send(:include, Pagination) }
   end
 end

data/lib/will_paginate/array.rb

@@ -22,11 +22,11 @@ class Array
   # McAdam}[http://www.desimcadam.com/archives/8] and later proved to be the
   # most useful method of will_paginate library.
   def paginate(options = {})
-    raise ArgumentError, "parameter hash expected (got #{options.inspect})" unless Hash === options
-    
-    WillPaginate::Collection.create options[:page] || 1,
-                                    options[:per_page] || 30,
-                                    options[:total_entries] || self.length do |pager|
+    page     = options[:page] || 1
+    per_page = options[:per_page] || WillPaginate.per_page
+    total    = options[:total_entries] || self.length
+
+    WillPaginate::Collection.create(page, per_page, total) do |pager|
       pager.replace self[pager.offset, pager.per_page].to_a
     end
   end

data/lib/will_paginate/collection.rb

@@ -1,27 +1,7 @@
+require 'will_paginate/per_page'
+require 'will_paginate/page_number'
+
 module WillPaginate
-  # = Invalid page number error
-  # This is an ArgumentError raised in case a page was requested that is either
-  # zero or negative number. You should decide how do deal with such errors in
-  # the controller.
-  #
-  # If you're using Rails 2, then this error will automatically get handled like
-  # 404 Not Found. The hook is in "will_paginate.rb":
-  #
-  #   ActionController::Base.rescue_responses['WillPaginate::InvalidPage'] = :not_found
-  #
-  # If you don't like this, use your preffered method of rescuing exceptions in
-  # public from your controllers to handle this differently. The +rescue_from+
-  # method is a nice addition to Rails 2.
-  #
-  # This error is *not* raised when a page further than the last page is
-  # requested. Use <tt>WillPaginate::Collection#out_of_bounds?</tt> method to
-  # check for those cases and manually deal with them as you see fit.
-  class InvalidPage < ArgumentError
-    def initialize(page, page_num) #:nodoc:
-      super "#{page.inspect} given as value, which translates to '#{page_num}' as page number"
-    end
-  end
-  
   # = The key to pagination
   # Arrays returned from paginating finds are, in fact, instances of this little
   # class. You may think of WillPaginate::Collection as an ordinary array with
@@ -33,12 +13,10 @@ module WillPaginate
   # 
   # If you are writing a library that provides a collection which you would like
   # to conform to this API, you don't have to copy these methods over; simply
-  # make your plugin/gem dependant on the "will_paginate" gem:
+  # make your plugin/gem dependant on this library and do:
   #
-  #   gem 'will_paginate'
   #   require 'will_paginate/collection'
-  #   
-  #   # now use WillPaginate::Collection directly or subclass it
+  #   # WillPaginate::Collection is now available for use
   class Collection < Array
     attr_reader :current_page, :per_page, :total_entries, :total_pages
 
@@ -46,12 +24,9 @@ module WillPaginate
     # and the total number of entries. The last argument is optional because it
     # is best to do lazy counting; in other words, count *conditionally* after
     # populating the collection using the +replace+ method.
-    def initialize(page, per_page, total = nil)
-      @current_page = page.to_i
-      raise InvalidPage.new(page, @current_page) if @current_page < 1
+    def initialize(page, per_page = WillPaginate.per_page, total = nil)
+      @current_page = WillPaginate::PageNumber(page)
       @per_page = per_page.to_i
-      raise ArgumentError, "`per_page` setting cannot be less than 1 (#{@per_page} given)" if @per_page < 1
-      
       self.total_entries = total if total
     end
 
@@ -82,7 +57,7 @@ module WillPaginate
     #
     # The Array#paginate API has since then changed, but this still serves as a
     # fine example of WillPaginate::Collection usage.
-    def self.create(page, per_page, total = nil, &block)
+    def self.create(page, per_page, total = nil)
       pager = new(page, per_page, total)
       yield pager
       pager
@@ -98,9 +73,9 @@ module WillPaginate
     # Current offset of the paginated collection. If we're on the first page,
     # it is always 0. If we're on the 2nd page and there are 30 entries per page,
     # the offset is 30. This property is useful if you want to render ordinals
-    # besides your records: simply start with offset + 1.
+    # side by side with records in the view: simply start with offset + 1.
     def offset
-      (current_page - 1) * per_page
+      @current_page.to_offset(per_page).to_i
     end
 
     # current_page - 1 or nil if there is no previous page
@@ -112,7 +87,8 @@ module WillPaginate
     def next_page
       current_page < total_pages ? (current_page + 1) : nil
     end
-
+    
+    # sets the <tt>total_entries</tt> property and calculates <tt>total_pages</tt>
     def total_entries=(number)
       @total_entries = number.to_i
       @total_pages   = (@total_entries / per_page.to_f).ceil

data/lib/will_paginate/core_ext.rb

@@ -1,5 +1,4 @@
 require 'set'
-require 'will_paginate/array'
 
 # copied from ActiveSupport so we don't depend on it
 
@@ -18,33 +17,6 @@ unless Hash.method_defined? :except
   end
 end
 
-unless Hash.method_defined? :slice
-  Hash.class_eval do
-    # Returns a new hash with only the given keys.
-    def slice(*keys)
-      allowed = Set.new(respond_to?(:convert_key) ? keys.map { |key| convert_key(key) } : keys)
-      reject { |key,| !allowed.include?(key) }
-    end
-
-    # Replaces the hash with only the given keys.
-    def slice!(*keys)
-      replace(slice(*keys))
-    end
-  end
-end
-
-unless String.method_defined? :constantize
-  String.class_eval do
-    def constantize
-      unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ self
-        raise NameError, "#{self.inspect} is not a valid constant name!"
-      end
-
-      Object.module_eval("::#{$1}", __FILE__, __LINE__)
-    end
-  end
-end
-
 unless String.method_defined? :underscore
   String.class_eval do
     def underscore