agnostic-will_paginate 3.0.0

data/lib/will_paginate/array.rb

@@ -0,0 +1,33 @@
+require 'will_paginate/collection'
+
+class Array
+  # Paginates a static array (extracting a subset of it). The result is a
+  # WillPaginate::Collection instance, which is an array with a few more
+  # properties about its paginated state.
+  #
+  # Parameters:
+  # * <tt>:page</tt> - current page, defaults to 1
+  # * <tt>:per_page</tt> - limit of items per page, defaults to 30
+  # * <tt>:total_entries</tt> - total number of items in the array, defaults to
+  #   <tt>array.length</tt> (obviously)
+  #
+  # Example:
+  #   arr = ['a', 'b', 'c', 'd', 'e']
+  #   paged = arr.paginate(:per_page => 2)      #->  ['a', 'b']
+  #   paged.total_entries                       #->  5
+  #   arr.paginate(:page => 2, :per_page => 2)  #->  ['c', 'd']
+  #   arr.paginate(:page => 3, :per_page => 2)  #->  ['e']
+  #
+  # This method was originally {suggested by Desi
+  # 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|
+      pager.replace self[pager.offset, pager.per_page].to_a
+    end
+  end
+end

data/lib/will_paginate/collection.rb

@@ -0,0 +1,145 @@
+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
+  # some extra properties. Those properties are used by view helpers to generate
+  # correct page links.
+  #
+  # WillPaginate::Collection also assists in rolling out your own pagination
+  # solutions: see +create+.
+  # 
+  # 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:
+  #
+  #   gem 'will_paginate'
+  #   require 'will_paginate/collection'
+  #   
+  #   # now use WillPaginate::Collection directly or subclass it
+  class Collection < Array
+    attr_reader :current_page, :per_page, :total_entries, :total_pages
+
+    # Arguments to the constructor are the current page number, per-page limit
+    # 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
+      @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
+
+    # Just like +new+, but yields the object after instantiation and returns it
+    # afterwards. This is very useful for manual pagination:
+    #
+    #   @entries = WillPaginate::Collection.create(1, 10) do |pager|
+    #     result = Post.find(:all, :limit => pager.per_page, :offset => pager.offset)
+    #     # inject the result array into the paginated collection:
+    #     pager.replace(result)
+    #
+    #     unless pager.total_entries
+    #       # the pager didn't manage to guess the total count, do it manually
+    #       pager.total_entries = Post.count
+    #     end
+    #   end
+    #
+    # The possibilities with this are endless. For another example, here is how
+    # WillPaginate used to define pagination for Array instances:
+    #
+    #   Array.class_eval do
+    #     def paginate(page = 1, per_page = 15)
+    #       WillPaginate::Collection.create(page, per_page, size) do |pager|
+    #         pager.replace self[pager.offset, pager.per_page].to_a
+    #       end
+    #     end
+    #   end
+    #
+    # 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)
+      pager = new(page, per_page, total)
+      yield pager
+      pager
+    end
+
+    # Helper method that is true when someone tries to fetch a page with a
+    # larger number than the last page. Can be used in combination with flashes
+    # and redirecting.
+    def out_of_bounds?
+      current_page > total_pages
+    end
+
+    # 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.
+    def offset
+      (current_page - 1) * per_page
+    end
+
+    # current_page - 1 or nil if there is no previous page
+    def previous_page
+      current_page > 1 ? (current_page - 1) : nil
+    end
+
+    # current_page + 1 or nil if there is no next page
+    def next_page
+      current_page < total_pages ? (current_page + 1) : nil
+    end
+
+    def total_entries=(number)
+      @total_entries = number.to_i
+      @total_pages   = (@total_entries / per_page.to_f).ceil
+    end
+
+    # This is a magic wrapper for the original Array#replace method. It serves
+    # for populating the paginated collection after initialization.
+    #
+    # Why magic? Because it tries to guess the total number of entries judging
+    # by the size of given array. If it is shorter than +per_page+ limit, then we
+    # know we're on the last page. This trick is very useful for avoiding
+    # unnecessary hits to the database to do the counting after we fetched the
+    # data for the current page.
+    #
+    # However, after using +replace+ you should always test the value of
+    # +total_entries+ and set it to a proper value if it's +nil+. See the example
+    # in +create+.
+    def replace(array)
+      result = super
+      
+      # The collection is shorter then page limit? Rejoice, because
+      # then we know that we are on the last page!
+      if total_entries.nil? and length < per_page and (current_page == 1 or length > 0)
+        self.total_entries = offset + length
+      end
+
+      result
+    end
+  end
+end

data/lib/will_paginate/core_ext.rb

@@ -0,0 +1,69 @@
+require 'set'
+require 'will_paginate/array'
+
+# helper to check for method existance in ruby 1.8- and 1.9-compatible way
+# because `methods`, `instance_methods` and others return strings in 1.8 and symbols in 1.9
+#
+#   ['foo', 'bar'].include_method?(:foo) # => true
+class Array
+  def include_method?(name)
+    name = name.to_sym
+    !!(find { |item| item.to_sym == name })
+  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.
+    def except(*keys)
+      rejected = Set.new(respond_to?(:convert_key) ? keys.map { |key| convert_key(key) } : keys)
+      reject { |key,| rejected.include?(key) }
+    end
+ 
+    # Replaces the hash without only the given keys.
+    def except!(*keys)
+      replace(except(*keys))
+    end
+  end
+end
+
+unless Hash.instance_methods.include_method? :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.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_ENV)
+        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,192 @@
+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
+    
+    # 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
+        add_limit! query, :offset => pager.offset, :limit => pager.per_page
+        # 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
+
+    def respond_to?(method, include_priv = false) #:nodoc:
+      super(method.to_s.sub(/^paginate/, 'find'), include_priv)
+    end
+
+  protected
+    
+    def method_missing_with_paginate(method, *args, &block) #:nodoc:
+      # did somebody tried to paginate? if not, let them be
+      unless method.to_s.index('paginate') == 0
+        return method_missing_without_paginate(method, *args, &block) 
+      end
+      
+      # paginate finders are really just find_* with limit and offset
+      finder = method.to_s.sub('paginate', 'find')
+      finder.sub!('find', 'find_all') if finder.index('find_by_') == 0
+      
+      options = args.pop
+      raise ArgumentError, 'parameter hash expected' unless options.respond_to? :symbolize_keys
+      options = options.dup
+      options[:finder] = finder
+      args << options
+      
+      paginate(*args, &block)
+    end
+
+    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]
+      
+      unless ::ActiveRecord::Calculations::CALCULATIONS_OPTIONS.include?(:from)
+        # :from parameter wasn't supported in count() before this change
+        excludees << :from
+      end
+      
+      # Use :select from scope if it isn't already present.
+      options[:select] = scope(:find, :select) unless options[:select]
+      
+      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 (Rails 2.1)
+      if count_options[:include] and
+          klass.private_methods.include_method?(:references_eager_loaded_tables?) and
+          !klass.send(:references_eager_loaded_tables?, count_options)
+        count_options.delete :include
+      end
+      
+      count_options
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  extend WillPaginate::Finders::ActiveRecord
+  class << self
+    alias_method_chain :method_missing, :paginate
+  end
+end
+
+# support pagination on associations
+a = ActiveRecord::Associations
+returning([ a::AssociationCollection ]) { |classes|
+  # detect http://dev.rubyonrails.org/changeset/9230
+  unless a::HasManyThroughAssociation.superclass == a::HasManyAssociation
+    classes << a::HasManyThroughAssociation
+  end
+}.each do |klass|
+  klass.send :include, WillPaginate::Finders::ActiveRecord
+  klass.class_eval { alias_method_chain :method_missing, :paginate }
+end