will_paginate 2.2.2 → 2.3.11

data/lib/will_paginate/collection.rb

@@ -33,12 +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 the "will_paginate" gem:
+  # make your plugin/gem dependant on the "mislav-will_paginate" gem:
   #
-  #   gem 'will_paginate'
+  #   gem 'mislav-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
 
@@ -82,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, &block)
+    def self.create(page, per_page, total = nil)
       pager = new(page, per_page, total)
       yield pager
       pager
@@ -98,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
-    # 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
     end
@@ -112,7 +112,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,7 +1,18 @@
 require 'set'
 require 'will_paginate/array'
 
-unless Hash.instance_methods.include? 'except'
+# 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
+
+unless Hash.instance_methods.include_method? :except
   Hash.class_eval do
     # Returns a new hash without the given keys.
     def except(*keys)
@@ -16,7 +27,7 @@ unless Hash.instance_methods.include? 'except'
   end
 end
 
-unless Hash.instance_methods.include? 'slice'
+unless Hash.instance_methods.include_method? :slice
   Hash.class_eval do
     # Returns a new hash with only the given keys.
     def slice(*keys)

data/lib/will_paginate/finder.rb

@@ -61,7 +61,7 @@ module WillPaginate
       #
       # All other options (+conditions+, +order+, ...) are forwarded to +find+
       # and +count+ calls.
-      def paginate(*args, &block)
+      def paginate(*args)
         options = args.pop
         page, per_page, total_entries = wp_parse_options(options)
         finder = (options[:finder] || 'find').to_s
@@ -79,7 +79,7 @@ module WillPaginate
           
           args << find_options
           # @options_from_last_find = nil
-          pager.replace send(finder, *args, &block)
+          pager.replace(send(finder, *args) { |*a| yield(*a) if block_given? })
           
           # magic counting for user convenience:
           pager.total_entries = wp_count(count_options, args, finder) unless pager.total_entries
@@ -94,9 +94,9 @@ module WillPaginate
       # You can specify a starting page with <tt>:page</tt> (default is 1). Default
       # <tt>:order</tt> is <tt>"id"</tt>, override if necessary.
       #
-      # See http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord where
-      # Jamis Buck describes this and also uses a more efficient way for MySQL.
-      def paginated_each(options = {}, &block)
+      # See {Faking Cursors in ActiveRecord}[http://weblog.jamisbuck.org/2007/4/6/faking-cursors-in-activerecord]
+      # where Jamis Buck describes this and a more efficient way for MySQL.
+      def paginated_each(options = {})
         options = { :order => 'id', :page => 1 }.merge options
         options[:page] = options[:page].to_i
         options[:total_entries] = 0 # skip the individual count queries
@@ -104,7 +104,10 @@ module WillPaginate
         
         begin 
           collection = paginate(options)
-          total += collection.each(&block).size
+          with_exclusive_scope(:find => {}) do
+            # using exclusive scope so that the block is yielded in scope-free context
+            total += collection.each { |item| yield item }.size
+          end
           options[:page] += 1
         end until collection.size < collection.per_page
         
@@ -127,7 +130,7 @@ module WillPaginate
       # 
       def paginate_by_sql(sql, options)
         WillPaginate::Collection.create(*wp_parse_options(options)) do |pager|
-          query = sanitize_sql(sql)
+          query = sanitize_sql(sql.dup)
           original_query = query.dup
           # add limit, offset
           add_limit! query, :offset => pager.offset, :limit => pager.per_page
@@ -138,7 +141,7 @@ module WillPaginate
             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)
+            unless self.connection.adapter_name =~ /^(oracle|oci$)/i
               count_query << ' AS count_table'
             end
             # perform the count query
@@ -158,10 +161,14 @@ module WillPaginate
 
     protected
       
-      def method_missing_with_paginate(method, *args, &block) #:nodoc:
+      def method_missing_with_paginate(method, *args) #: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) 
+          if block_given?
+            return method_missing_without_paginate(method, *args) { |*a| yield(*a) }
+          else
+            return method_missing_without_paginate(method, *args) 
+          end
         end
         
         # paginate finders are really just find_* with limit and offset
@@ -174,16 +181,30 @@ module WillPaginate
         options[:finder] = finder
         args << options
         
-        paginate(*args, &block)
+        paginate(*args) { |*a| yield(*a) if block_given? }
       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)
         excludees = [:count, :order, :limit, :offset, :readonly]
-        unless options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
+        excludees << :from unless ActiveRecord::Calculations::CALCULATIONS_OPTIONS.include?(:from)
+
+        # we may be in a model or an association proxy
+        klass = (@owner and @reflection) ? @reflection.klass : self
+
+        # 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 # only exclude the select param if it doesn't begin with DISTINCT
         end
+
         # count expects (almost) the same options as find
         count_options = options.except *excludees
 
@@ -191,19 +212,23 @@ module WillPaginate
         # 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
+
         # we may have to scope ...
         counter = Proc.new { count(count_options) }
 
-        # we may be in a model or an association proxy!
-        klass = (@owner and @reflection) ? @reflection.klass : self
-
         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 match = /^find_(all_by|by)_([_a-zA-Z]\w*)$/.match(finder)
+                elsif finder =~ /^find_(all_by|by)_([_a-zA-Z]\w*)$/
                   # extract conditions from calls like "paginate_by_foo_and_bar"
-                  attribute_names = extract_attribute_names_from_match(match)
+                  attribute_names = $2.split('_and_')
                   conditions = construct_attributes_from_arguments(attribute_names, args)
                   with_scope(:find => { :conditions => conditions }, &counter)
                 else

data/lib/will_paginate/named_scope.rb

@@ -1,27 +1,22 @@
-## stolen from: http://dev.rubyonrails.org/browser/trunk/activerecord/lib/active_record/named_scope.rb?rev=9084
-
 module WillPaginate
   # This is a feature backported from Rails 2.1 because of its usefullness not only with will_paginate,
   # but in other aspects when managing complex conditions that you want to be reusable.
   module NamedScope
     # All subclasses of ActiveRecord::Base have two named_scopes:
     # * <tt>all</tt>, which is similar to a <tt>find(:all)</tt> query, and
-    # * <tt>scoped</tt>, which allows for the creation of anonymous scopes, on the fly:
-    #
-    #   Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)
+    # * <tt>scoped</tt>, which allows for the creation of anonymous scopes, on the fly: <tt>Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)</tt>
     #
     # These anonymous scopes tend to be useful when procedurally generating complex queries, where passing
     # intermediate values (scopes) around as first-class objects is convenient.
     def self.included(base)
       base.class_eval do
         extend ClassMethods
-        named_scope :all
         named_scope :scoped, lambda { |scope| scope }
       end
     end
 
     module ClassMethods
-      def scopes #:nodoc:
+      def scopes
         read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {})
       end
 
@@ -46,7 +41,7 @@ module WillPaginate
       # Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments
       # for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>.
       #
-      # All scopes are available as class methods on the ActiveRecord descendent upon which the scopes were defined. But they are also available to
+      # All scopes are available as class methods on the ActiveRecord::Base descendent upon which the scopes were defined. But they are also available to
       # <tt>has_many</tt> associations. If,
       #
       #   class Person < ActiveRecord::Base
@@ -76,14 +71,27 @@ module WillPaginate
       #     end
       #   end
       #
-      def named_scope(name, options = {}, &block)
+      #
+      # For testing complex named scopes, you can examine the scoping options using the
+      # <tt>proxy_options</tt> method on the proxy itself.
+      #
+      #   class Shirt < ActiveRecord::Base
+      #     named_scope :colored, lambda { |color|
+      #       { :conditions => { :color => color } }
+      #     }
+      #   end
+      #
+      #   expected_options = { :conditions => { :colored => 'red' } }
+      #   assert_equal expected_options, Shirt.colored('red').proxy_options
+      def named_scope(name, options = {})
+        name = name.to_sym
         scopes[name] = lambda do |parent_scope, *args|
           Scope.new(parent_scope, case options
             when Hash
               options
             when Proc
               options.call(*args)
-          end, &block)
+          end) { |*a| yield(*a) if block_given? }
         end
         (class << self; self end).instance_eval do
           define_method name do |*args|
@@ -93,14 +101,20 @@ module WillPaginate
       end
     end
     
-    class Scope #:nodoc:
+    class Scope
       attr_reader :proxy_scope, :proxy_options
-      [].methods.each { |m| delegate m, :to => :proxy_found unless m =~ /(^__|^nil\?|^send|class|extend|find|count|sum|average|maximum|minimum|paginate)/ }
+
+      [].methods.each do |m|
+        unless m =~ /(^__|^nil\?|^send|^object_id$|class|extend|^find$|count|sum|average|maximum|minimum|paginate|first|last|empty\?|respond_to\?)/
+          delegate m, :to => :proxy_found
+        end
+      end
+
       delegate :scopes, :with_scope, :to => :proxy_scope
 
-      def initialize(proxy_scope, options, &block)
+      def initialize(proxy_scope, options)
         [options[:extend]].flatten.each { |extension| extend extension } if options[:extend]
-        extend Module.new(&block) if block_given?
+        extend Module.new { |*args| yield(*args) } if block_given?
         @proxy_scope, @proxy_options = proxy_scope, options.except(:extend)
       end
 
@@ -108,18 +122,42 @@ module WillPaginate
         load_found; self
       end
 
+      def first(*args)
+        if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash))
+          proxy_found.first(*args)
+        else
+          find(:first, *args)
+        end
+      end
+
+      def last(*args)
+        if args.first.kind_of?(Integer) || (@found && !args.first.kind_of?(Hash))
+          proxy_found.last(*args)
+        else
+          find(:last, *args)
+        end
+      end
+
+      def empty?
+        @found ? @found.empty? : count.zero?
+      end
+
+      def respond_to?(method, include_private = false)
+        super || @proxy_scope.respond_to?(method, include_private)
+      end
+
       protected
       def proxy_found
         @found || load_found
       end
 
       private
-      def method_missing(method, *args, &block)
+      def method_missing(method, *args)
         if scopes.include?(method)
           scopes[method].call(self, *args)
         else
           with_scope :find => proxy_options do
-            proxy_scope.send(method, *args, &block)
+            proxy_scope.send(method, *args) { |*a| yield(*a) if block_given? }
           end
         end
       end

data/lib/will_paginate/named_scope_patch.rb

@@ -1,9 +1,7 @@
-## based on http://dev.rubyonrails.org/changeset/9084
-
 ActiveRecord::Associations::AssociationProxy.class_eval do
   protected
-  def with_scope(*args, &block)
-    @reflection.klass.send :with_scope, *args, &block
+  def with_scope(*args)
+    @reflection.klass.send(:with_scope, *args) { |*a| yield(*a) if block_given? }
   end
 end
 
@@ -12,11 +10,11 @@ end
   klass.class_eval do
     protected
     alias :method_missing_without_scopes :method_missing_without_paginate
-    def method_missing_without_paginate(method, *args, &block)
+    def method_missing_without_paginate(method, *args)
       if @reflection.klass.scopes.include?(method)
-        @reflection.klass.scopes[method].call(self, *args, &block)
+        @reflection.klass.scopes[method].call(self, *args) { |*a| yield(*a) if block_given? }
       else
-        method_missing_without_scopes(method, *args, &block)
+        method_missing_without_scopes(method, *args) { |*a| yield(*a) if block_given? }
       end
     end
   end
@@ -25,14 +23,14 @@ end
 # Rails 1.2.6
 ActiveRecord::Associations::HasAndBelongsToManyAssociation.class_eval do
   protected
-  def method_missing(method, *args, &block)
+  def method_missing(method, *args)
     if @target.respond_to?(method) || (!@reflection.klass.respond_to?(method) && Class.respond_to?(method))
       super
     elsif @reflection.klass.scopes.include?(method)
       @reflection.klass.scopes[method].call(self, *args)
     else
       @reflection.klass.with_scope(:find => { :conditions => @finder_sql, :joins => @join_sql, :readonly => false }) do
-        @reflection.klass.send(method, *args, &block)
+        @reflection.klass.send(method, *args) { |*a| yield(*a) if block_given? }
       end
     end
   end

data/lib/will_paginate/version.rb

@@ -1,8 +1,8 @@
-module WillPaginate #:nodoc:
-  module VERSION #:nodoc:
+module WillPaginate
+  module VERSION
     MAJOR = 2
-    MINOR = 2
-    TINY  = 2
+    MINOR = 3
+    TINY  = 11
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/will_paginate/view_helpers.rb

@@ -3,35 +3,36 @@ require 'will_paginate/core_ext'
 module WillPaginate
   # = Will Paginate view helpers
   #
-  # Currently there is only one view helper: +will_paginate+. It renders the
+  # The main view helper, #will_paginate, renders
   # pagination links for the given collection. The helper itself is lightweight
-  # and serves only as a wrapper around link renderer instantiation; the
+  # and serves only as a wrapper around LinkRenderer instantiation; the
   # renderer then does all the hard work of generating the HTML.
   # 
   # == Global options for helpers
   #
   # Options for pagination helpers are optional and get their default values from the
-  # WillPaginate::ViewHelpers.pagination_options hash. You can write to this hash to
+  # <tt>WillPaginate::ViewHelpers.pagination_options</tt> hash. You can write to this hash to
   # override default options on the global level:
   #
-  #   WillPaginate::ViewHelpers.pagination_options[:prev_label] = 'Previous page'
+  #   WillPaginate::ViewHelpers.pagination_options[:previous_label] = 'Previous page'
   #
-  # By putting this into your environment.rb you can easily translate link texts to previous
+  # By putting this into "config/initializers/will_paginate.rb" (or simply environment.rb in
+  # older versions of Rails) you can easily translate link texts to previous
   # and next pages, as well as override some other defaults to your liking.
   module ViewHelpers
     # default options that can be overridden on the global level
     @@pagination_options = {
-      :class        => 'pagination',
-      :prev_label   => '&laquo; Previous',
-      :next_label   => 'Next &raquo;',
-      :inner_window => 4, # links around the current page
-      :outer_window => 1, # links around beginning and end
-      :separator    => ' ', # single space is friendly to spiders and non-graphic browsers
-      :param_name   => :page,
-      :params       => nil,
-      :renderer     => 'WillPaginate::LinkRenderer',
-      :page_links   => true,
-      :container    => true
+      :class          => 'pagination',
+      :previous_label => '&laquo; Previous',
+      :next_label     => 'Next &raquo;',
+      :inner_window   => 4, # links around the current page
+      :outer_window   => 1, # links around beginning and end
+      :separator      => ' ', # single space is friendly to spiders and non-graphic browsers
+      :param_name     => :page,
+      :params         => nil,
+      :renderer       => 'WillPaginate::LinkRenderer',
+      :page_links     => true,
+      :container      => true
     }
     mattr_reader :pagination_options
 
@@ -40,31 +41,37 @@ module WillPaginate
     # rendering the pagination in that case...
     # 
     # ==== Options
-    # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
-    # * <tt>:prev_label</tt> -- default: "« Previous"
+    # Display options:
+    # * <tt>:previous_label</tt> -- default: "« Previous" (this parameter is called <tt>:prev_label</tt> in versions <b>2.3.2</b> and older!)
     # * <tt>:next_label</tt> -- default: "Next »"
+    # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
     # * <tt>:inner_window</tt> -- how many links are shown around the current page (default: 4)
     # * <tt>:outer_window</tt> -- how many links are around the first and the last page (default: 1)
     # * <tt>:separator</tt> -- string separator for page HTML elements (default: single space)
-    # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
-    # * <tt>:params</tt> -- additional parameters when generating pagination links
-    #   (eg. <tt>:controller => "foo", :action => nil</tt>)
-    # * <tt>:renderer</tt> -- class name of the link renderer (default: WillPaginate::LinkRenderer)
-    # * <tt>:page_links</tt> -- when false, only previous/next links are rendered (default: true)
+    # 
+    # HTML options:
+    # * <tt>:class</tt> -- CSS class name for the generated DIV (default: "pagination")
     # * <tt>:container</tt> -- toggles rendering of the DIV container for pagination links, set to
     #   false only when you are rendering your own pagination markup (default: true)
-    # * <tt>:id</tt> -- HTML ID for the container (default: nil). Pass +true+ to have the ID automatically
-    #   generated from the class name of objects in collection: for example, paginating
+    # * <tt>:id</tt> -- HTML ID for the container (default: nil). Pass +true+ to have the ID
+    #   automatically generated from the class name of objects in collection: for example, paginating
     #   ArticleComment models would yield an ID of "article_comments_pagination".
     #
-    # All options beside listed ones are passed as HTML attributes to the container
+    # Advanced options:
+    # * <tt>:param_name</tt> -- parameter name for page number in URLs (default: <tt>:page</tt>)
+    # * <tt>:params</tt> -- additional parameters when generating pagination links
+    #   (eg. <tt>:controller => "foo", :action => nil</tt>)
+    # * <tt>:renderer</tt> -- class name, class or instance of a link renderer (default:
+    #   <tt>WillPaginate::LinkRenderer</tt>)
+    #
+    # All options not recognized by will_paginate will become HTML attributes on the container
     # element for pagination links (the DIV). For example:
     # 
-    #   <%= will_paginate @posts, :id => 'wp_posts' %>
+    #   <%= will_paginate @posts, :style => 'font-size: small' %>
     #
     # ... will result in:
     #
-    #   <div class="pagination" id="wp_posts"> ... </div>
+    #   <div class="pagination" style="font-size: small"> ... </div>
     #
     # ==== Using the helper without arguments
     # If the helper is called without passing in the collection object, it will
@@ -91,10 +98,22 @@ module WillPaginate
       return nil unless WillPaginate::ViewHelpers.total_pages_for_collection(collection) > 1
       
       options = options.symbolize_keys.reverse_merge WillPaginate::ViewHelpers.pagination_options
-      # create the renderer instance
-      renderer_class = options[:renderer].to_s.constantize
-      renderer = renderer_class.new collection, options, self
+      if options[:prev_label]
+        WillPaginate::Deprecation::warn(":prev_label view parameter is now :previous_label; the old name has been deprecated", caller)
+        options[:previous_label] = options.delete(:prev_label)
+      end
+      
+      # get the renderer instance
+      renderer = case options[:renderer]
+      when String
+        options[:renderer].to_s.constantize.new
+      when Class
+        options[:renderer].new
+      else
+        options[:renderer]
+      end
       # render HTML for pagination
+      renderer.prepare collection, options, self
       renderer.to_html
     end
     
@@ -122,24 +141,41 @@ module WillPaginate
     # blocks of pagination links sharing the same ID (which is invalid HTML).
     def paginated_section(*args, &block)
       pagination = will_paginate(*args).to_s
-      content = pagination + capture(&block) + pagination
-      concat content, block.binding
+      
+      unless ActionView::Base.respond_to? :erb_variable
+        concat pagination
+        yield
+        concat pagination
+      else
+        content = pagination + capture(&block) + pagination
+        concat(content, block.binding)
+      end
     end
 
     # Renders a helpful message with numbers of displayed vs. total entries.
     # You can use this as a blueprint for your own, similar helpers.
     #
     #   <%= page_entries_info @posts %>
-    #   #-> Displaying entries 6 - 10 of 26 in total
-    def page_entries_info(collection)
+    #   #-> Displaying posts 6 - 10 of 26 in total
+    #
+    # By default, the message will use the humanized class name of objects
+    # in collection: for instance, "project types" for ProjectType models.
+    # Override this with the <tt>:entry_name</tt> parameter:
+    #
+    #   <%= page_entries_info @posts, :entry_name => 'item' %>
+    #   #-> Displaying items 6 - 10 of 26 in total
+    def page_entries_info(collection, options = {})
+      entry_name = options[:entry_name] ||
+        (collection.empty?? 'entry' : collection.first.class.name.underscore.sub('_', ' '))
+      
       if collection.total_pages < 2
         case collection.size
-        when 0; 'No entries found'
-        when 1; 'Displaying <b>1</b> entry'
-        else;   "Displaying <b>all #{collection.size}</b> entries"
+        when 0; "No #{entry_name.pluralize} found"
+        when 1; "Displaying <b>1</b> #{entry_name}"
+        else;   "Displaying <b>all #{collection.size}</b> #{entry_name.pluralize}"
         end
       else
-        %{Displaying entries <b>%d&nbsp;-&nbsp;%d</b> of <b>%d</b> in total} % [
+        %{Displaying #{entry_name.pluralize} <b>%d&nbsp;-&nbsp;%d</b> of <b>%d</b> in total} % [
           collection.offset + 1,
           collection.offset + collection.length,
           collection.total_entries
@@ -149,12 +185,11 @@ module WillPaginate
 
     def self.total_pages_for_collection(collection) #:nodoc:
       if collection.respond_to?('page_count') and !collection.respond_to?('total_pages')
-        WillPaginate::Deprecation.warn <<-MSG
+        WillPaginate::Deprecation.warn %{
           You are using a paginated collection of class #{collection.class.name}
           which conforms to the old API of WillPaginate::Collection by using
           `page_count`, while the current method name is `total_pages`. Please
-          upgrade yours or 3rd-party code that provides the paginated collection.
-        MSG
+          upgrade yours or 3rd-party code that provides the paginated collection}, caller
         class << collection
           def total_pages; page_count; end
         end
@@ -164,16 +199,29 @@ module WillPaginate
   end
 
   # This class does the heavy lifting of actually building the pagination
-  # links. It is used by +will_paginate+ helper internally.
+  # links. It is used by the <tt>will_paginate</tt> helper internally.
   class LinkRenderer
+
+    # The gap in page links is represented by:
+    #
+    #   <span class="gap">&hellip;</span>
+    attr_accessor :gap_marker
+    
+    def initialize
+      @gap_marker = '<span class="gap">&hellip;</span>'
+    end
+    
     # * +collection+ is a WillPaginate::Collection instance or any other object
     #   that conforms to that API
     # * +options+ are forwarded from +will_paginate+ view helper
     # * +template+ is the reference to the template being rendered
-    def initialize(collection, options, template)
+    def prepare(collection, options, template)
       @collection = collection
       @options    = options
       @template   = template
+
+      # reset values in case we're re-using this instance
+      @total_pages = @param_name = @url_string = nil
     end
 
     # Process it! This method returns the complete HTML string which contains
@@ -182,8 +230,8 @@ module WillPaginate
     def to_html
       links = @options[:page_links] ? windowed_links : []
       # previous/next buttons
-      links.unshift page_link_or_span(@collection.previous_page, %w(disabled prev_page), @options[:prev_label])
-      links.push    page_link_or_span(@collection.next_page,     %w(disabled next_page), @options[:next_label])
+      links.unshift page_link_or_span(@collection.previous_page, 'disabled prev_page', @options[:previous_label])
+      links.push    page_link_or_span(@collection.next_page,     'disabled next_page', @options[:next_label])
       
       html = links.join(@options[:separator])
       @options[:container] ? @template.content_tag(:div, html, html_attributes) : html
@@ -203,13 +251,6 @@ module WillPaginate
     
   protected
 
-    # The gap in page links is represented by:
-    #
-    #   <span class="gap">&hellip;</span>
-    def gap_marker
-      '<span class="gap">&hellip;</span>'
-    end
-    
     # Collects link items for visible page numbers.
     def windowed_links
       prev = nil
@@ -252,38 +293,60 @@ module WillPaginate
     
     def page_link_or_span(page, span_class, text = nil)
       text ||= page.to_s
-      classnames = Array[*span_class]
       
       if page and page != current_page
-        @template.link_to text, url_for(page), :rel => rel_value(page), :class => classnames[1]
+        classnames = span_class && span_class.index(' ') && span_class.split(' ', 2).last
+        page_link page, text, :rel => rel_value(page), :class => classnames
       else
-        @template.content_tag :span, text, :class => classnames.join(' ')
+        page_span page, text, :class => span_class
       end
     end
 
+    def page_link(page, text, attributes = {})
+      @template.link_to text, url_for(page), attributes
+    end
+
+    def page_span(page, text, attributes = {})
+      @template.content_tag :span, text, attributes
+    end
+
     # Returns URL params for +page_link_or_span+, taking the current GET params
     # and <tt>:params</tt> option into account.
     def url_for(page)
-      unless @url_string
-        @url_params = { :escape => false }
+      page_one = page == 1
+      unless @url_string and !page_one
+        @url_params = {}
         # page links should preserve GET parameters
         stringified_merge @url_params, @template.params if @template.request.get?
         stringified_merge @url_params, @options[:params] if @options[:params]
         
-        if param_name.index(/[^\w-]/)
-          page_param = (defined?(CGIMethods) ? CGIMethods : ActionController::AbstractRequest).
-            parse_query_parameters("#{param_name}=#{page}")
+        if complex = param_name.index(/[^\w-]/)
+          page_param = parse_query_parameters("#{param_name}=#{page}")
           
           stringified_merge @url_params, page_param
         else
-          @url_params[param_name] = page
+          @url_params[param_name] = page_one ? 1 : 2
         end
 
         url = @template.url_for(@url_params)
-        @url_string = url.sub(%r!([?&/]#{CGI.escape param_name}[=/])#{page}!, '\1@')
-        return url
+        return url if page_one
+        
+        if complex
+          @url_string = url.sub(%r!((?:\?|&amp;)#{CGI.escape param_name}=)#{page}!, "\\1\0")
+          return url
+        else
+          @url_string = url
+          @url_params[param_name] = 3
+          @template.url_for(@url_params).split(//).each_with_index do |char, i|
+            if char == '3' and url[i, 1] == '2'
+              @url_string[i] = "\0"
+              break
+            end
+          end
+        end
       end
-      @url_string.sub '@', page.to_s
+      # finally!
+      @url_string.sub "\0", page.to_s
     end
 
   private
@@ -308,20 +371,33 @@ module WillPaginate
       @param_name ||= @options[:param_name].to_s
     end
 
+    # Recursively merge into target hash by using stringified keys from the other one
     def stringified_merge(target, other)
       other.each do |key, value|
-        key = key.to_s
+        key = key.to_s # this line is what it's all about!
         existing = target[key]
 
-        if value.is_a?(Hash)
-          target[key] = existing = {} if existing.nil?
-          if existing.is_a?(Hash)
-            stringified_merge(existing, value)
-            return
-          end
+        if value.is_a?(Hash) and (existing.is_a?(Hash) or existing.nil?)
+          stringified_merge(existing || (target[key] = {}), value)
+        else
+          target[key] = value
         end
-        
-        target[key] = value
+      end
+    end
+
+    def parse_query_parameters(params)
+      if defined? Rack::Utils
+        # For Rails > 2.3
+        Rack::Utils.parse_nested_query(params)
+      elsif defined?(ActionController::AbstractRequest)
+        ActionController::AbstractRequest.parse_query_parameters(params)
+      elsif defined?(ActionController::UrlEncodedPairParser)
+        # For Rails > 2.2
+        ActionController::UrlEncodedPairParser.parse_query_parameters(params)
+      elsif defined?(CGIMethods)
+        CGIMethods.parse_query_parameters(params)
+      else
+        raise "unsupported ActionPack version"
       end
     end
   end