will_paginate 2.3.17 → 3.0.pre

data/lib/will_paginate/collection.rb

@@ -1,5 +1,3 @@
-require 'will_paginate/per_page'
-
 module WillPaginate
   # = Invalid page number error
   # This is an ArgumentError raised in case a page was requested that is either
@@ -19,24 +17,8 @@ module WillPaginate
   # 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
-    # a value bigger than this would result in invalid SQL queries
-    BIGINT = 9223372036854775807
-
-    def self.validate(page_value, per_page_value)
-      page = page_value.to_i
-      raise self.new(page_value, page) if page < 1
-      per_page = per_page_value.to_i
-      offset = (page - 1) * per_page
-      raise self, "invalid offset: #{offset.inspect}" if offset < 0 or offset > BIGINT
-      [page, per_page]
-    end
-
-    def initialize(value, page_num = nil)
-      if page_num
-        super "#{value.inspect} given as value, which translates to '#{page_num}' as page number"
-      else
-        super value
-      end
+    def initialize(page, page_num) #:nodoc:
+      super "#{page.inspect} given as value, which translates to '#{page_num}' as page number"
     end
   end
   
@@ -51,10 +33,12 @@ 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 this library and do:
+  # make your plugin/gem dependant on the "will_paginate" gem:
   #
+  #   gem 'will_paginate'
   #   require 'will_paginate/collection'
-  #   # WillPaginate::Collection is now available for use
+  #   
+  #   # now use WillPaginate::Collection directly or subclass it
   class Collection < Array
     attr_reader :current_page, :per_page, :total_entries, :total_pages
 
@@ -62,8 +46,12 @@ 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 = WillPaginate.per_page, total = nil)
-      @current_page, @per_page = InvalidPage.validate(page, per_page)
+    def initialize(page, per_page, total = nil)
+      @current_page = page.to_i
+      raise InvalidPage.new(page, @current_page) if @current_page < 1
+      @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
 
@@ -94,7 +82,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)
+    def self.create(page, per_page, total = nil, &block)
       pager = new(page, per_page, total)
       yield pager
       pager
@@ -110,7 +98,7 @@ 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
-    # side by side with records in the view: simply start with offset + 1.
+    # besides your records: simply start with offset + 1.
     def offset
       (current_page - 1) * per_page
     end
@@ -124,8 +112,7 @@ 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

@@ -12,6 +12,8 @@ class Array
   end
 end
 
+## everything below copied from ActiveSupport so we don't depend on it ##
+
 unless Hash.instance_methods.include_method? :except
   Hash.class_eval do
     # Returns a new hash without the given keys.
@@ -41,3 +43,27 @@ unless Hash.instance_methods.include_method? :slice
     end
   end
 end
+
+unless String.instance_methods.include_method? :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.instance_methods.include_method? :underscore
+  String.class_eval do
+    def underscore
+      self.to_s.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+  end
+end

data/lib/will_paginate/deprecation.rb

@@ -0,0 +1,50 @@
+# borrowed from ActiveSupport::Deprecation
+module WillPaginate
+  module Deprecation
+    def self.debug() @debug; end
+    def self.debug=(value) @debug = value; end
+    self.debug = false
+
+    # Choose the default warn behavior according to Rails.env.
+    # Ignore deprecation warnings in production.
+    BEHAVIORS = {
+      'test'        => Proc.new { |message, callstack|
+                         $stderr.puts(message)
+                         $stderr.puts callstack.join("\n  ") if debug
+                       },
+      'development' => Proc.new { |message, callstack|
+                         logger = defined?(::RAILS_DEFAULT_LOGGER) ? ::RAILS_DEFAULT_LOGGER : Logger.new($stderr)
+                         logger.warn message
+                         logger.debug callstack.join("\n  ") if debug
+                       }
+    }
+
+    def self.warn(message, callstack = caller)
+      if behavior
+        message = 'WillPaginate: ' + message.strip.gsub(/\s+/, ' ')
+        behavior.call(message, callstack)
+      end
+    end
+
+    def self.default_behavior
+      if defined?(::Rails)
+        BEHAVIORS[::Rails.env.to_s]
+      else
+        BEHAVIORS['test']
+      end
+    end
+
+    # Behavior is a block that takes a message argument.
+    def self.behavior() @behavior; end
+    def self.behavior=(value) @behavior = value; end
+    self.behavior = default_behavior
+
+    def self.silence
+      old_behavior = self.behavior
+      self.behavior = nil
+      yield
+    ensure
+      self.behavior = old_behavior
+    end
+  end
+end

data/lib/will_paginate/finders.rb

@@ -0,0 +1,9 @@
+require 'will_paginate/core_ext'
+
+module WillPaginate
+  # Database logic for different ORMs
+  #
+  # See WillPaginate::Finders::Base
+  module Finders
+  end
+end

data/lib/will_paginate/finders/active_record.rb

@@ -0,0 +1,158 @@
+require 'will_paginate/finders/base'
+require 'active_record'
+
+module WillPaginate::Finders
+  # = Paginating finders for ActiveRecord models
+  # 
+  # WillPaginate adds +paginate+, +per_page+ and other methods to
+  # ActiveRecord::Base class methods and associations. It also hooks into
+  # +method_missing+ to intercept pagination calls to dynamic finders such as
+  # +paginate_by_user_id+ and translate them to ordinary finders
+  # (+find_all_by_user_id+ in this case).
+  # 
+  # In short, paginating finders are equivalent to ActiveRecord finders; the
+  # only difference is that we start with "paginate" instead of "find" and
+  # that <tt>:page</tt> is required parameter:
+  #
+  #   @posts = Post.paginate :all, :page => params[:page], :order => 'created_at DESC'
+  # 
+  # In paginating finders, "all" is implicit. There is no sense in paginating
+  # a single record, right? So, you can drop the <tt>:all</tt> argument:
+  # 
+  #   Post.paginate(...)              =>  Post.find :all
+  #   Post.paginate_all_by_something  =>  Post.find_all_by_something
+  #   Post.paginate_by_something      =>  Post.find_all_by_something
+  #
+  module ActiveRecord
+    include WillPaginate::Finders::Base
+    
+    # In Rails, this is automatically called to mix-in pagination functionality to ActiveRecord.
+    def self.enable!
+      ::ActiveRecord::Base.class_eval do
+        extend ActiveRecord
+      end
+
+      # support pagination on associations and scopes
+      [::ActiveRecord::Relation, ::ActiveRecord::Associations::AssociationCollection].each do |klass|
+        klass.send(:include, ActiveRecord)
+      end
+    end
+    
+    # Wraps +find_by_sql+ by simply adding LIMIT and OFFSET to your SQL string
+    # based on the params otherwise used by paginating finds: +page+ and
+    # +per_page+.
+    #
+    # Example:
+    # 
+    #   @developers = Developer.paginate_by_sql ['select * from developers where salary > ?', 80000],
+    #                          :page => params[:page], :per_page => 3
+    #
+    # A query for counting rows will automatically be generated if you don't
+    # supply <tt>:total_entries</tt>. If you experience problems with this
+    # generated SQL, you might want to perform the count manually in your
+    # application.
+    # 
+    def paginate_by_sql(sql, options)
+      WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
+        query = sanitize_sql(sql.dup)
+        original_query = query.dup
+        # add limit, offset
+        query << " LIMIT #{pager.per_page} OFFSET #{pager.offset}"
+        # perfom the find
+        pager.replace find_by_sql(query)
+        
+        unless pager.total_entries
+          count_query = original_query.sub /\bORDER\s+BY\s+[\w`,\s]+$/mi, ''
+          count_query = "SELECT COUNT(*) FROM (#{count_query})"
+          
+          unless ['oracle', 'oci'].include?(self.connection.adapter_name.downcase)
+            count_query << ' AS count_table'
+          end
+          # perform the count query
+          pager.total_entries = count_by_sql(count_query)
+        end
+      end
+    end
+
+  protected
+
+    def wp_query(options, pager, args, &block) #:nodoc:
+      finder = (options.delete(:finder) || 'find').to_s
+      find_options = options.except(:count).update(:offset => pager.offset, :limit => pager.per_page) 
+
+      if finder == 'find'
+        if Array === args.first and !pager.total_entries
+          pager.total_entries = args.first.size
+        end
+        args << :all if args.empty?
+      end
+      
+      args << find_options
+      pager.replace send(finder, *args, &block)
+      
+      unless pager.total_entries
+        # magic counting
+        pager.total_entries = wp_count(options, args, finder) 
+      end
+    end
+
+    # Does the not-so-trivial job of finding out the total number of entries
+    # in the database. It relies on the ActiveRecord +count+ method.
+    def wp_count(options, args, finder) #:nodoc:
+      # find out if we are in a model or an association proxy
+      klass = (@owner and @reflection) ? @reflection.klass : self
+      count_options = wp_parse_count_options(options, klass)
+
+      # we may have to scope ...
+      counter = Proc.new { count(count_options) }
+
+      count = if finder.index('find_') == 0 and klass.respond_to?(scoper = finder.sub('find', 'with'))
+                # scope_out adds a 'with_finder' method which acts like with_scope, if it's present
+                # then execute the count with the scoping provided by the with_finder
+                send(scoper, &counter)
+              elsif finder =~ /^find_(all_by|by)_([_a-zA-Z]\w*)$/
+                # extract conditions from calls like "paginate_by_foo_and_bar"
+                attribute_names = $2.split('_and_')
+                conditions = construct_attributes_from_arguments(attribute_names, args)
+                with_scope(:find => { :conditions => conditions }, &counter)
+              else
+                counter.call
+              end
+
+      count.respond_to?(:length) ? count.length : count
+    end
+    
+    def wp_parse_count_options(options, klass) #:nodoc:
+      excludees = [:count, :order, :limit, :offset, :readonly]
+      
+      # Use :select from scope if it isn't already present.
+      # FIXME: this triggers extra queries when going through associations
+      # if options[:select].blank? && current_scoped_methods && current_scoped_methods.select_values.present?
+      #   options[:select] = current_scoped_methods.select_values.join(", ")
+      # end
+      
+      if options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
+        # Remove quoting and check for table_name.*-like statement.
+        if options[:select].gsub('`', '') =~ /\w+\.\*/
+          options[:select] = "DISTINCT #{klass.table_name}.#{klass.primary_key}"
+        end
+      else
+        excludees << :select
+      end
+      
+      # count expects (almost) the same options as find
+      count_options = options.except *excludees
+
+      # merge the hash found in :count
+      # this allows you to specify :select, :order, or anything else just for the count query
+      count_options.update options[:count] if options[:count]
+      
+      # forget about includes if they are irrelevant when counting
+      if count_options[:include] and count_options[:conditions].blank? and count_options[:group].blank?
+        count_options.delete :include
+      end
+      
+      count_options
+    end
+  end
+end

data/lib/will_paginate/finders/active_resource.rb

@@ -0,0 +1,51 @@
+require 'will_paginate/finders/base'
+require 'active_resource'
+
+module WillPaginate::Finders
+  # Paginate your ActiveResource models.
+  # 
+  #   @posts = Post.paginate :all, :params => {
+  #              :page => params[:page], :order => 'created_at DESC'
+  #            }
+  # 
+  module ActiveResource
+    include WillPaginate::Finders::Base
+    
+  protected
+  
+    def wp_query(options, pager, args, &block) #:nodoc:
+      unless args.empty? or args.first == :all
+        raise ArgumentError, "finder arguments other than :all are not supported for pagination (#{args.inspect} given)"
+      end
+      params = (options[:params] ||= {})
+      params[:page] = pager.current_page
+      params[:per_page] = pager.per_page
+      
+      pager.replace find_every(options, &block)
+    end
+    
+    # Takes the format that Hash.from_xml produces out of an unknown type
+    # (produced by WillPaginate::Collection#to_xml_with_collection_type), 
+    # parses it into a WillPaginate::Collection,
+    # and forwards the result to the former +instantiate_collection+ method.
+    # It only does this for hashes that have a :type => "collection".
+    def instantiate_collection_with_collection(collection, prefix_options = {}) #:nodoc:
+      if collection.is_a?(Hash) && collection["type"] == "collection"
+        collectables = collection.values.find{ |c| c.is_a?(Hash) || c.is_a?(Array) }
+        collectables = [collectables].compact unless collectables.kind_of?(Array)
+        instantiated_collection = WillPaginate::Collection.create(collection["current_page"], collection["per_page"], collection["total_entries"]) do |pager|
+          pager.replace instantiate_collection_without_collection(collectables, prefix_options)
+        end
+      else
+        instantiate_collection_without_collection(collection, prefix_options)
+      end
+    end
+  end
+end
+
+ActiveResource::Base.class_eval do
+  extend WillPaginate::Finders::ActiveResource
+  class << self
+    # alias_method_chain :instantiate_collection, :collection
+  end
+end

data/lib/will_paginate/finders/base.rb

@@ -0,0 +1,112 @@
+require 'will_paginate/core_ext'
+
+module WillPaginate
+  module Finders
+    # = Database-agnostic finder module
+    # 
+    # Out of the box, will_paginate supports hooking in several ORMs to
+    # provide paginating finders based on their API. As of this writing, the
+    # supported libraries are:
+    #
+    # * ActiveRecord
+    # * DataMapper
+    # * Sequel
+    #
+    # It's easy to write your own adapter for anything that can load data with
+    # explicit limit and offset settings. DataMapper adapter is a nice and
+    # compact example of writing an adapter to bring the +paginate+ method to
+    # DataMapper models.
+    #
+    # == The importance of SQL's <tt>ORDER BY</tt>
+    #
+    # In most ORMs, <tt>:order</tt> parameter specifies columns for the
+    # <tt>ORDER BY</tt> clause in SQL. It is important to have it, since
+    # pagination only makes sense with ordered sets. Without the order clause,
+    # databases aren't required to do consistent ordering when performing
+    # <tt>SELECT</tt> queries.
+    # 
+    # Ordering by a field for which many records share the same value (e.g.
+    # "status") can still result in incorrect ordering with some databases (MS
+    # SQL and Postgres for instance). With these databases it's recommend that
+    # you order by primary key as well. That is, instead of ordering by
+    # "status DESC", use the alternative "status DESC, id DESC" and this will
+    # yield consistent results.
+    #
+    # Therefore, make sure you are doing ordering on a column that makes the
+    # most sense in the current context. Make that obvious to the user, also.
+    # For perfomance reasons you will also want to add an index to that column.
+    module Base
+      def per_page
+        @per_page ||= 30
+      end
+      
+      def per_page=(limit)
+        @per_page = limit.to_i
+      end
+      
+      # This is the main paginating finder.
+      #
+      # == Special parameters for paginating finders
+      # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
+      # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 30 if not overridden)
+      # * <tt>:total_entries</tt> -- use only if you manually count total entries
+      # * <tt>:count</tt> -- additional options that are passed on to +count+
+      # * <tt>:finder</tt> -- name of the finder method to use (default: "find")
+      #
+      # All other options (+conditions+, +order+, ...) are forwarded to +find+
+      # and +count+ calls.
+      def paginate(*args, &block)
+        options = args.pop
+        page, per_page, total_entries = wp_parse_options(options)
+
+        WillPaginate::Collection.create(page, per_page, total_entries) do |pager|
+          query_options = options.except :page, :per_page, :total_entries
+          wp_query(query_options, pager, args, &block)
+        end
+      end
+
+      # Iterates through all records by loading one page at a time. This is useful
+      # for migrations or any other use case where you don't want to load all the
+      # records in memory at once.
+      #
+      # It uses +paginate+ internally; therefore it accepts all of its options.
+      # You can specify a starting page with <tt>:page</tt> (default is 1). Default
+      # <tt>:order</tt> is <tt>"id"</tt>, override if necessary.
+      #
+      # {Jamis Buck describes this}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
+      # and also uses a more efficient way for MySQL.
+      def paginated_each(options = {}, &block)
+        options = { :order => 'id', :page => 1 }.merge options
+        options[:page] = options[:page].to_i
+        options[:total_entries] = 0 # skip the individual count queries
+        total = 0
+        
+        begin 
+          collection = paginate(options)
+          total += collection.each(&block).size
+          options[:page] += 1
+        end until collection.size < collection.per_page
+        
+        total
+      end
+      
+      protected
+        
+        def wp_parse_options(options) #:nodoc:
+          raise ArgumentError, 'parameter hash expected' unless Hash === options
+          raise ArgumentError, ':page parameter required' unless options.key? :page
+          
+          if options[:count] and options[:total_entries]
+            raise ArgumentError, ':count and :total_entries are mutually exclusive'
+          end
+
+          page     = options[:page] || 1
+          per_page = options[:per_page] || self.per_page
+          total    = options[:total_entries]
+          
+          return [page, per_page, total]
+        end
+        
+    end
+  end
+end