jm81-paginate 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jared Morgan
+
+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.md

@@ -0,0 +1,138 @@
+Paginate
+========
+
+This paginate library assists in paginating collections and results of database
+queries. It is particularly designed for use with DataMapper and ActiveRecord, 
+and for the Merb and Rails frameworks, but can be used in many other situations.
+The library includes three sections (with more information on each below)
+
+1. Paginate modules - These are the modules that a collection (such as an Array)
+   or a model Class extends to allow the collection to call #paginate
+
+2. Paginator classes - classes in the Paginator module do the actual work.
+   Paginator::Simple is the base class.
+
+3. Helper modules - modules with helper methods for use by frameworks
+   (currently Merb only).
+
+##General Information
+
+There are many pagination libraries available for Ruby (in particular for Ruby
+ORMs). This is just one more, but with three particular design goals:
+
+1. Add *#current_page* and *pages* singleton methods to the paginated 
+   collection. The pagination libraries I've used usually return two values:
+   the collection and a total pages value. For no good reason, this bugs me.
+2. A more flexible *:page* option. The *:page* option can be negative,
+   representing number of pages from the last (-1 being the last), as occurs
+   with many Ruby objects. Also, the *paginate* method will always return a
+   page within the actual collection. Finally, the *current_page* singleton
+   method returns the actual number of the page returned, which may be different
+   from that given.
+3. Re-use as much code as possible for different situations. That is, the method
+   that calculates the current page and adds the singleton methods is shared
+   by implementations for Array, DataMapper, ActiveRecord, etc.
+
+##Examples
+
+Two examples are below, one using Paginate::Simple, one using Paginate::DM.
+See below and the documentation of the individual modules for more details.
+
+    ary = Array.new(1,2,3,4,5)
+    ary.extend(Paginate::Simple)
+    paged = ary.paginate(:page => 1, :limit => 2)
+    => [1, 2]
+    paged.current_page
+    => 1
+    paged.pages
+    => 3
+    
+    class DmModel
+      include DataMapper::Resource
+      extend Paginate::DM
+    end
+    paged = DmModel.paginate(:page => 2, :limit => 10)
+    
+Note that neither the :page nor the :limit option is required. :page defaults
+to 1, :limit defaults to *Paginate.config[:default_limit]* 
+(See **Configuration**).
+
+##Configuration
+
+Paginate has one configurable parameter (for defaults across an application):
+*default_limit*. This specifies the limit (number of records per page) to use
+if not given as an option to the *#paginate* method. By default, it is 10. To
+change:
+
+    Paginate.config[:default_limit] = 100
+
+For Merb apps, Merb plugin configuration can also be used:
+
+    Merb::Plugins.config[:paginate][:default_limit] = 100
+
+##Paginate Modules
+
+Paginate modules provide a *paginate* method to Objects that extend them. The
+actual work is done by a Paginator class.
+
+*paginate* accepts an options hash with at least two options:
+
+- *:page*: The desired page number, 1-indexed. Negative numbers represent
+  page from the last page (with -1) being the last.
+- *:limit*: represents records per page.
+
+Depending on the module, other options may be passed through to, for example, an
+*all* method. See individual modules for more details.
+
+There are currently three modules.
+
+- Paginate::Simple - for use with Arrays and similar objects.
+- Paginate::DM - extended by a class that includes DataMapper::Resource
+- Paginate::AR - extended by a class that inherits ActiveRecord::Base
+
+##Paginator Classes
+
+Paginator classes do the actual work of paginating and are called by the 
+modules. They can be used directly. The *#paginate* method in Paginators::Simple
+does all the generic work. It calls two methods, *#get_full_count*, 
+and *#get_paginated_collection* to do the implementation-specific work.
+Paginator classes should need to override only these two methods.
+
+##Custom Paginators
+
+To create an additional Paginator, create a class that inherits 
+Paginate::Paginators::Simple (or another Paginator). The key is to override
+the following methods:
+
+- *#get_paginated_collection* - This returns the paginated collection. At it's
+  disposal is the @options hash and two particular options:
+  - @options[:offset] is the zero-indexed offset of the first record of the
+    page.
+  - @options[:limit] is the number of items per page.
+  - Other options passed the #initialize method will also be available.
+
+- *#get_full_count* - Return the total number of items on all pages. The @options 
+  hash is available here, but :offset, :order and :limit options will not be 
+  included. Options such as conditions will be available.
+  
+See Paginators for examples.
+
+To use, add a paginate method to your Class or Object:
+
+    def paginate(options = {})
+      MyPaginator.new(self, options).paginate
+    end
+
+##Helper Modules
+
+There is currently a Helpers::Shared module and Helpers::Merb.
+
+###Helpers::Shared
+
+Contains one method, *#page_set*, which returns an Array of page numbers useful
+in creating page links for the collection.
+
+###Helpers::Merb
+
+In addition to including Shared, this helper includes other methods useful for
+displaying page links. See Helpers::Merb module for details.

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+gem 'rspec'
+require 'spec/rake/spectask'
+
+QBFC_ROOT = File.dirname(__FILE__)
+
+task :default => :spec
+
+desc "Run all specs in spec/unit directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', '"spec/spec.opts"']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+require 'rake/gempackagetask'
+
+require 'merb-core'
+require 'merb-core/tasks/merb'
+
+GEM_NAME = "paginate"
+GEM_VERSION = "0.1.1"
+AUTHOR = "Jared Morgan"
+EMAIL = "jmorgan@morgancreative.net"
+HOMEPAGE = "http://github.com/jm81/paginate/"
+SUMMARY = "(Yet another) Pagination for DataMapper, ActiveRecord, and Array"
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README.md", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README.md Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end

data/TODO

@@ -0,0 +1,2 @@
+TODO:
+Add your code to lib/paginate.rb

data/lib/helpers/merb.rb

@@ -0,0 +1,84 @@
+module Paginate
+  module Helpers
+    # Pagination helpers for Merb applications. See Paginate::Helpers::Shared
+    # for additional methods
+    module Merb
+      include Shared
+      
+      # A quick method for creating pagination links, using a view partial,
+      # (layouts/_page_links, by default).
+      # Arguments:
+      #
+      # - +collection+: an enumerable collection with #current_page and
+      #   #pages methods.
+      # - +partial_name+: location of the partial to use
+      # - +padding+: Maximum number of page links before and after current_page.
+      def pagination_partial(collection, partial_name = "layout/page_links", padding = 3)
+        padding ||= 3
+        partial(partial_name, :current_page => collection.current_page, :pages => collection.pages, :padding => padding)
+      end
+      
+      # Returns links for pages, given a +collection+ and optional
+      # +padding+ (see Shared#page_set). Returned html will be along the lines
+      # of:
+      # 
+      #    <div class="pageLinks">' +
+      #      <span class="pagePrevious"><a href="/list?page=4">&laquo;</a></span>
+      #      <span class="pageSpacer">...</span>
+      #      <span class="pageNumber"><a href="/list?page=3">3</a></span>
+      #      <span class="pageNumber"><a href="/list?page=4">4</a></span>
+      #      <span class="pageCurrent">5</span>
+      #      <span class="pageNumber"><a href="/list?page=6">6</a></span>
+      #      <span class="pageNumber"><a href="/list?page=7">7</a></span>
+      #      <span class="pageSpacer">...</span>
+      #      <span class="pageNext"><a href="/list?page=6">&raquo;</a></span>
+      #    </div>
+      #
+      # CSS classes are pageSpacer, pageNumber, pageDisabled, pageCurrent, 
+      # pagePrevious, and pageNext. pageLinks is the class of the enclosing div.
+      def page_links(collection, padding = 3)
+        current = collection.current_page
+        pages   = collection.pages
+        
+        tag(:div, :class => 'pageLinks') do
+          if current_page == 1
+            tag(:span, '&laquo;', :class => 'pageDisabled pagePrevious')
+          else
+            tag(:a, '&laquo;', :href => page_url(current - 1), :class => 'pagePrevious')
+          end
+          
+          page_set(current, pages, padding).each do |page|
+            case page
+            when 0
+              tag(:span, "...", :class => 'pageSpacer')
+            when current
+              tag(:span, page, :class => 'pageCurrent')
+            else
+              tag(:a, page, :href => page_url(page), :class => 'pageNumber')
+            end
+          end
+        
+          if current == pages
+            tag(:span, '&raquo;', :class => 'pageDisabled pageNext')
+          else
+            tag(:a, '&raquo;', :href => page_url(current + 1), :class => 'pageNext')
+          end
+        end
+      end
+      
+      # +page_url+ generates a URL (for page links), given a page number and
+      # optionally a path and query string. By default, the path is the path
+      # of the current request, and the query_string is also that of the
+      # current request. This allows for order and condition related fields
+      # in the query string to be used in the page link.
+      def page_url(page, path = request.path, q = request.query_string)
+        # Remove any current reference to page in the query string
+        q.to_s.gsub!(/page=(\d+)(&?)/, '') 
+        # Assemble new link
+        link = "#{path}?page=#{page}&#{q}"
+        link = link[0..-2] if link[-1..-1] == '&' # Strip trailing ampersand
+        link
+      end      
+    end
+  end
+end

data/lib/helpers/shared.rb

@@ -0,0 +1,43 @@
+module Paginate
+  module Helpers
+    # Shared helper methods included in other Helper modules.
+    module Shared
+      # +page_set+ returns an Array of page numbers that can be used by a view 
+      # for displaying page links. It includes the first page, the current page,
+      # with up to +padding+ pages before and after, and the last page. If pages
+      # are skipped between any of these groups, 0 stands in for them, as an
+      # indicator to the view that, for example, elipses might be used here.
+      # For example:
+      # 
+      #    page_set(3, 10, 3)
+      #    => [1, 2, 3, 4, 5, 6, 0, 10] TODO test this in particular
+      # 
+      # The 0 at index 6 is an indication that there are skipped pages.
+      def page_set(current_page, pages, padding = 3)
+        
+        # Determine first and last page in group around current page
+        first = [1, current_page - padding].max
+        last = [pages, current_page + padding].min
+        
+        # Determine if an additional "First page" is needed and whether any
+        # pages are skipped between it and the first around the current page
+        leader = case first
+          when 1 then []  # First not needed
+          when 2 then [1] # First needed, but none skipped
+          else [1, 0]     # First needed, some skipped
+        end
+
+        # Determine if an additional "Last page" is needed and whether any
+        # pages are skipped between the last around the current page and it.
+        footer = case last
+          when pages then []          # Last not needed
+          when pages - 1 then [pages] # Last needed, but none skipped
+          else [0, pages]             # Last needed, some skipped
+        end
+        
+        # Join Arrays together
+        leader + (first..last).to_a + footer
+      end
+    end
+  end
+end

data/lib/paginate.rb

@@ -0,0 +1,32 @@
+module Paginate
+  DEFAULTS = {
+    :default_limit => 10
+  }
+  
+  class << self
+    # Paginate::config method returns Hash that can be edited.
+    def config
+      @config ||= DEFAULTS
+    end
+  end
+end
+
+if defined?(Merb::Plugins)
+  # Make config accessible through Merb's Merb::Plugins.config hash
+  Merb::Plugins.config[:paginate] = Paginate.config
+end
+
+# Require Paginators
+%w{ simple orm }.each do |file|
+  require File.dirname(__FILE__) + '/paginators/' + file
+end
+
+# Require Paginate Modules
+%w{ simple dm ar }.each do |file|
+  require File.dirname(__FILE__) + '/paginate/' + file
+end
+
+# Require Helper Modules
+%w{ shared merb }.each do |file|
+  require File.dirname(__FILE__) + '/helpers/' + file
+end

data/lib/paginate/ar.rb

@@ -0,0 +1,33 @@
+module Paginate
+  
+  # .pagination method for ActiveRecord models.  
+  module AR
+    
+    # Implementation of .paginate for ActiveRecord.
+    #
+    # To make available to your model:
+    # class MyModel < ActiveRecord::Base
+    #   extend Paginate::AR
+    #   ...
+    # end
+    # 
+    # Accepts same options as ActiveRecord::Base.all, plus:
+    # - +page+: The desired page number, 1-indexed. Negative numbers represent
+    #   page from the last page (with -1) being the last.
+    #
+    # The +limit+ option should also be specified and represents records per
+    # page. Any +offset+ option will be overriden.
+    #
+    # Returns the records for the given page number, with other options 
+    # processed by +all+. In addition, two methods are added to the result:
+    # - +pages+: The total number of pages that the given options would produce.
+    # - +current_page+: The number of the current page (as actually returned).
+    #   This is never a negative number even if given.
+    # If the +page+ option is zero, or less than (-1 * pages) or greater than 
+    # the total pages, it will be recalculated to return either page 1 or the 
+    # last page, respectively.
+    def paginate(options = {})
+      Paginators::ORM.new(self, options).paginate
+    end
+  end
+end

data/lib/paginate/dm.rb

@@ -0,0 +1,35 @@
+module Paginate
+  
+  # .pagination method for DataMapper models.  
+  module DM
+    
+    # Implementation of .paginate for DataMapper.
+    # (This is loosely based on http://github.com/lholden/dm-is-paginated)
+    #
+    # To make available to your model:
+    # class MyModel
+    #   include DataMapper::Resource
+    #   extend Paginate::DM
+    #   ...
+    # end
+    # 
+    # Accepts same options as DataMapper::Resource.all, plus:
+    # - +page+: The desired page number, 1-indexed. Negative numbers represent
+    #   page from the last page (with -1) being the last.
+    #
+    # The +limit+ option should also be specified and represents records per
+    # page. Any +offset+ option will be overriden.
+    #
+    # Returns the records for the given page number, with other options 
+    # processed by +all+. In addition, two methods are added to the result:
+    # - +pages+: The total number of pages that the given options would produce.
+    # - +current_page+: The number of the current page (as actually returned).
+    #   This is never a negative number even if given.
+    # If the +page+ option is zero, or less than (-1 * pages) or greater than 
+    # the total pages, it will be recalculated to return either page 1 or the 
+    # last page, respectively.
+    def paginate(options = {})
+      Paginators::ORM.new(self, options).paginate
+    end
+  end
+end

data/lib/paginate/simple.rb

@@ -0,0 +1,32 @@
+module Paginate
+  
+  # .pagination method for Arrays and similar objects.
+  module Simple
+    
+    # Implementation of .paginate for Arrays and similar objects (must respond
+    # to +length+ and +[](start_index, length)+.
+    #
+    # To make available to all Arrays:
+    # Array.include(Paginate::Simple)
+    # 
+    # For a single Array:
+    # array.extend(Paginate::Simple)
+    # 
+    # Accepts two options:
+    # - +page+: The desired page number, 1-indexed. Negative numbers represent
+    #   page from the last page (with -1) being the last.
+    #- +limit+: represents records per page.
+    #
+    # Returns a slice of the Array with records for the given page number.
+    # Two methods are added to the result:
+    # - +pages+: The total number of pages that the given options would produce.
+    # - +current_page+: The number of the current page (as actually returned).
+    #   This is never a negative number even if given.
+    # If the +page+ option is zero, or less than (-1 * pages) or greater than 
+    # the total pages, it will be recalculated to return either page 1 or the 
+    # last page, respectively.
+    def paginate(options = {})
+      Paginators::Simple.new(self, options).paginate
+    end
+  end
+end

data/lib/paginators/orm.rb

@@ -0,0 +1,17 @@
+module Paginate
+  module Paginators
+    class ORM < Simple
+      private
+      
+      # Return the total number of records based on the given conditions.
+      def get_full_count
+        model.count(:id, @options)
+      end
+  
+      # Return the records for the given page.
+      def get_paginated_collection
+        model.all(@options)
+      end
+    end
+  end
+end

data/lib/paginators/simple.rb

@@ -0,0 +1,84 @@
+module Paginate
+  module Paginators
+    # This is for use by +Array+ and similar objects.
+    class Simple
+      # full_collection is an +Array+ (or any Object that responds to +length+
+      # and +[](start_index, length)+, such as +LazyArray+. #paginate will
+      # return the appropriate slice of that Object.
+      # options include:
+      # - +page+: The desired page (may be negative)
+      # - +limit+: Number of items per page.
+      # Other options are ignored.
+      # See README for more details. (TODO)
+      def initialize(full_collection, options = {})
+        @full_collection = full_collection
+        @options = options
+      end
+      
+      # Perform the pagination. Returns the records for the given page, with
+      # singleton methods:
+      # - +current_page+: The number of the current page.
+      # - +pages+: The total number of pages of records.
+      #
+      # See the documents for the module that your class extends for more details.
+      #
+      # Descendents classes should not need to override this method, but rather
+      # + get_full_count+ and +get_paginated_collection+ private methods.
+      def paginate
+        page = @options.delete(:page).to_i
+        limit = @options[:limit] ? @options[:limit].to_i : Paginate.config[:default_limit]
+        order = @options[:order]
+        
+        # Remove some options before calling +count+ that are not applicable.
+        # order and limit are needed later and have been saved above.
+        [:offset, :limit, :order].each do |key|
+          @options.delete(key)
+        end
+        
+        # Determine total number of pages and set offset option.
+        pages = (get_full_count.to_f / limit).ceil
+        page = (pages + 1 + page) if page < 0 # Negative page
+        page = pages if page > pages # page should not be more than total pages
+        page = 1 if page < 1 # Minimum is 1 even if 0 records.
+        pages = 1 if pages < 1 # Minimum is 1 even if 0 records.
+        @options[:offset] = ((page - 1) * limit)
+        
+        # Add limit and order back into options, from above.
+        @options[:limit] = limit
+        @options[:order] = order if order
+        
+        # Call +all+.
+        collection = get_paginated_collection
+  
+        # Create +pages+ and +current_page+ methods for collection, for use by
+        # pagination links.
+        collection.instance_variable_set(:@pages, pages)
+        collection.instance_variable_set(:@current_page, page)
+        def collection.pages; @pages; end
+        def collection.current_page; @current_page; end
+        
+        return collection
+      end
+      
+      private
+      
+      # Alias for @full_collection because that's what the @full_collection
+      # usually is for ORM class
+      def model
+        @full_collection
+      end
+      
+      # Return the total number of items/records based on the given conditions.
+      # This may be overriden by inherited classes.
+      def get_full_count
+        @full_collection.length
+      end
+  
+      # Return the records for the given page.
+      # This may be overriden by inherited classes.
+      def get_paginated_collection
+        @full_collection[@options[:offset], @options[:limit]]
+      end
+    end
+  end
+end

data/spec/fixtures/ar.rb

@@ -0,0 +1,7 @@
+module Paginate
+  module Fixtures   
+    class ArModel < ActiveRecord::Base
+      extend Paginate::AR
+    end
+  end
+end

data/spec/fixtures/dm.rb

@@ -0,0 +1,13 @@
+DataMapper.setup(:default, 'sqlite3::memory:')
+
+module Paginate
+  module Fixtures
+    class DmModel
+      include DataMapper::Resource
+      extend Paginate::DM
+      
+      property :id,      Serial
+      property :name,    String
+    end
+  end
+end

data/spec/helpers/merb_spec.rb

@@ -0,0 +1,57 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Paginate::Helpers::Merb do
+  before(:all) do
+    @klass = Class.new
+    @klass.__send__(:include, Paginate::Helpers::Merb)
+    @object = @klass.new
+  end
+  
+  it 'should include #page_set method from Shared' do
+    @object.page_set(5, 10, 2).should ==
+      [1,0,3,4,5,6,7,0,10]
+  end
+
+  # Being lazy and just using a mock here.
+  describe '#pagination_partial' do
+    it 'should call partial' do
+      collection = (1..50).to_a
+      collection.extend(Paginate::Simple)
+      collection = collection.paginate(:page => 5, :limit => 5)
+      vars = {
+        :current_page => 5,
+        :pages => 10,
+        :padding => 4
+      }
+      
+      @object.should_receive(:partial).with('partial_name', vars)
+      @object.pagination_partial(collection, 'partial_name', 4)
+    end
+  end
+    
+  describe '#page_url' do
+    it 'should add page query option' do
+      @object.page_url(5, 'path', '').should ==
+        'path?page=5'
+    end
+
+    it 'should leave other query options' do
+      @object.page_url(5, 'path', 'limit=10&something=text').should ==
+        'path?page=5&limit=10&something=text'
+    end
+    
+    it 'should remove existing page option' do
+      # middle
+      @object.page_url(5, 'path', 'limit=10&page=10&something=text').should ==
+        'path?page=5&limit=10&something=text'
+      
+      # start
+      @object.page_url(5, 'path', 'page=10&limit=10&something=text').should ==
+        'path?page=5&limit=10&something=text'
+      
+      # end
+      @object.page_url(5, 'path', 'limit=10&something=text&page=10').should ==
+        'path?page=5&limit=10&something=text'
+    end
+  end
+end

data/spec/helpers/shared_spec.rb

@@ -0,0 +1,61 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Paginate::Helpers::Shared do
+  before(:all) do
+    @klass = Class.new
+    @klass.__send__(:include, Paginate::Helpers::Shared)
+    @object = @klass.new
+  end
+  
+  describe '#page_set' do
+    it 'should pad around current page' do
+      @object.page_set(5, 10, 2).should ==
+        [1,0,3,4,5,6,7,0,10]
+
+      @object.page_set(5, 10, 1).should ==
+        [1,0,4,5,6,0,10]
+
+      @object.page_set(5, 10, 0).should ==
+        [1,0,5,0,10]
+    end
+    
+    it 'should default padding to 3' do
+      @object.page_set(10, 20).should ==
+        [1,0,7,8,9,10,11,12,13,0,20]
+    end
+    
+    it 'should not repeat first page' do
+      @object.page_set(2, 10, 2).should ==
+        [1,2,3,4,0,10]
+
+      @object.page_set(1, 10, 2).should ==
+        [1,2,3,0,10]
+    end
+    
+    it 'should not repeat last page' do
+      @object.page_set(9, 10, 2).should ==
+        [1,0,7,8,9,10]
+
+      @object.page_set(10, 10, 2).should ==
+        [1,0,8,9,10]
+    end
+    
+    it 'should include 0 when pages skipped' do
+      @object.page_set(5, 10, 2).should ==
+        [1,0,3,4,5,6,7,0,10]
+    end
+    
+    it 'should not include 0 when padding is next to first or last' do
+      @object.page_set(3, 10, 2).should ==
+        [1,2,3,4,5,0,10]
+
+      @object.page_set(8, 10, 2).should ==
+        [1,0,6,7,8,9,10]
+    end
+    
+    it 'should just return [1] if only 1 page' do
+      @object.page_set(1, 1, 3).should ==
+        [1]
+    end
+  end
+end

data/spec/paginate/ar_spec.rb

@@ -0,0 +1,55 @@
+require 'active_record'
+
+# Setup AR connection, schema
+ActiveRecord::Base.establish_connection(
+  :adapter => "sqlite3",
+  :dbfile  => ":memory:"
+)
+
+ActiveRecord::Schema.define do
+  create_table :ar_models do |table|
+    table.column :name, :string
+  end
+end
+
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../fixtures/ar'
+
+describe 'Paginate::AR' do 
+  before(:each) do
+    @model = Paginate::Fixtures::ArModel
+    @model.destroy_all
+    1.upto(50) do |i|
+      @model.create(:name => "Person #{i}")
+    end
+  end
+  
+  def paginated(options = {})
+    @model.paginate(options)
+  end
+
+  def paginated_collected(options = {})
+    @model.paginate(options).collect {|r| r.name}
+  end
+  
+  def destroy_all
+    @model.destroy_all
+  end
+  
+  describe '#paginate' do
+    it_should_behave_like "all paginate methods"
+    it_should_behave_like "ORM paginate methods"
+    
+    it 'should order per options passed' do
+      paginated_collected(:limit => 3, :page => 1, :order => 'id desc').should ==
+        ["Person 50", "Person 49", "Person 48"]
+    end
+    
+    it 'should accept conditions (representative of options to .all)' do
+      collection = paginated(:limit => 3, :page => 1, :conditions => ['name like ?', 'Person 3%'])
+      collection.collect {|r| r.name}.should ==
+        ["Person 3", "Person 30", "Person 31"]
+      collection.pages.should == 4
+    end
+  end
+end

data/spec/paginate/config_spec.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe "Paginate.config" do
+  before(:each) do
+    # Force to default state
+    Paginate.instance_variable_set(:@config, nil)
+  end
+  
+  after(:all) do
+    # Force to default state for other specs
+    Paginate.instance_variable_set(:@config, nil)
+  end
+  
+  it 'should initialize with DEFAULTS' do
+    Paginate.config.should == Paginate::DEFAULTS
+  end
+  
+  it 'should be writable' do
+    Paginate.config[:default_limit] = 1
+    Paginate.instance_variable_get(:@config)[:default_limit].should == 1
+  end
+  
+  describe ':default_limit' do
+    it 'should be used as default limit' do
+      Paginate.config[:default_limit] = 3
+      ary = (1..20).collect {|i| 'Item #{i}'}
+      ary.extend(Paginate::Simple)
+      ary.paginate.length.should == 3
+    end
+  end
+end

data/spec/paginate/dm_spec.rb

@@ -0,0 +1,47 @@
+require 'dm-core'
+require 'dm-aggregates'
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../fixtures/dm'
+
+describe Paginate::DM do
+  before(:all) do
+    @model = Paginate::Fixtures::DmModel
+    @model.auto_migrate!
+  end
+  
+  before(:each) do
+    @model.all.destroy!
+    1.upto(50) do |i|
+      @model.create(:name => "Person #{i}")
+    end
+  end
+  
+  def paginated(options = {})
+    @model.paginate(options)
+  end
+
+  def paginated_collected(options = {})
+    @model.paginate(options).collect {|r| r.name}
+  end
+  
+  def destroy_all
+    @model.all.destroy!
+  end
+  
+  describe '#paginate' do
+    it_should_behave_like "all paginate methods"
+    it_should_behave_like "ORM paginate methods"
+        
+    it 'should order per options passed' do
+      paginated_collected(:limit => 3, :page => 1, :order => [:id.desc]).should ==
+        ["Person 50", "Person 49", "Person 48"]
+    end
+    
+    it 'should accept conditions (representative of options to .all)' do
+      collection = paginated(:limit => 3, :page => 1, :name.like => 'Person 3%')
+      collection.collect {|r| r.name}.should ==
+        ["Person 3", "Person 30", "Person 31"]
+      collection.pages.should == 4
+    end
+  end
+end

data/spec/paginate/simple_spec.rb

@@ -0,0 +1,27 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Paginate::Simple do
+  before(:each) do
+    @full_collection = []
+    1.upto(50) do |i|
+      @full_collection << "Person #{i}"
+    end
+    @full_collection.extend(Paginate::Simple)
+  end
+
+  def paginated(options = {})
+    @full_collection.paginate(options)
+  end
+  
+  def paginated_collected(options = {})
+    paginated(options)
+  end
+  
+  def destroy_all
+    50.times { @full_collection.pop }
+  end
+  
+  describe '#paginate' do
+    it_should_behave_like "all paginate methods"
+  end
+end

data/spec/paginators/orm_spec.rb

@@ -0,0 +1,49 @@
+require 'dm-core'
+require 'dm-aggregates'
+require File.dirname(__FILE__) + '/../spec_helper'
+require File.dirname(__FILE__) + '/../fixtures/dm'
+
+describe Paginate::Paginators::ORM do 
+  Model = Paginate::Fixtures::DmModel
+  before(:all) do
+    Model.auto_migrate!
+  end
+  
+  before(:each) do
+    Model.all.destroy!
+    1.upto(50) do |i|
+      Model.create(:name => "Person #{i}")
+    end
+    @model = Model
+    @klass = Paginate::Paginators::ORM
+  end
+  
+  def paginated(options = {})
+    @klass.new(Model, options).paginate
+  end
+
+  def paginated_collected(options = {})
+    paginated(options).collect {|r| r.name}
+  end
+  
+  def destroy_all
+    Model.all.destroy!
+  end
+  
+  describe '#paginate' do
+    it_should_behave_like "all paginate methods"
+    it_should_behave_like "ORM paginate methods"
+        
+    it 'should order per options passed' do
+      paginated_collected(:limit => 3, :page => 1, :order => [:id.desc]).should ==
+        ["Person 50", "Person 49", "Person 48"]
+    end
+    
+    it 'should accept conditions (representative of options to .all)' do
+      collection = paginated(:limit => 3, :page => 1, :name.like => 'Person 3%')
+      collection.collect {|r| r.name}.should ==
+        ["Person 3", "Person 30", "Person 31"]
+      collection.pages.should == 4
+    end
+  end
+end

data/spec/paginators/simple_spec.rb

@@ -0,0 +1,37 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Paginate::Paginators::Simple do 
+  # No instance variables are expected by the shared specs, only a +paginated+
+  # and a +destroy_all+ method.
+  before(:each) do
+    @full_collection = []
+    1.upto(50) do |i|
+      @full_collection << "Person #{i}"
+    end
+    @klass = Paginate::Paginators::Simple
+  end
+  
+  # paginated is called by shared specs to get a paginated result for the
+  # collection.
+  def paginated(options = {})
+    @klass.new(@full_collection, options).paginate
+  end
+  
+  # paginated_collected returns results in a standard format: It should just 
+  # return an Array of Strings, such as:
+  # ["Person 1", "Person 2"], so #collect may be needed in more complex
+  # classes.
+  def paginated_collected(options = {})
+    paginated(options)
+  end
+  
+  # destroy_all is called to make @full_collection an empty set. This may mean
+  # that all records need to be deleted in, for example, an ORM Paginator.
+  def destroy_all
+    @full_collection = []
+  end
+  
+  describe '#paginate' do
+    it_should_behave_like "all paginate methods"
+  end
+end

data/spec/shared.rb

@@ -0,0 +1,155 @@
+# Specs shared by Paginator classes and Paginate modules. These test that the 
+# Paginator (directly or via a module) returns the right results based on 
+# +page+ and +limit+ options.
+#
+# +paginated+, +paginated_collected+ and +destroy_all+ methods are expected
+# by specs. A +@model+ instance variable is expected for "ORM paginate methods".
+# See simple_spec.rb for examples.
+#
+# +paginated+ is called by shared specs to get a paginated result for the
+# collection. 
+#
+# +paginated_collected+ calls paginate, but returns an Array of Strings. If all 
+# results were returned, it should return an Array of
+# ["Person 1", "Person 2", ..., "Person 50"] (50 records total). #collect may be
+# needed in more complex classes. For example:
+#
+#   @klass.paginate(@full_collection, options).collect {|r| r.name}
+#   Model.paginate(options).collect {|r| r.name}
+#
+# +destroy_all+ is called to make the full collection an empty set. This may 
+# mean that all records need to be deleted in, for example, an ORM Paginator.
+
+shared_examples_for "all paginate methods" do
+  describe ':page option' do
+    it 'should return correct results per page (correct offset, limit)' do
+      paginated_collected(:page => 1, :limit => 5).should ==
+        ["Person 1", "Person 2", "Person 3", "Person 4", "Person 5"]      
+            
+      paginated_collected(:page => 2, :limit => 5).should ==
+        ["Person 6", "Person 7", "Person 8", "Person 9", "Person 10"]
+    end
+    
+    it 'should return page 1 if options[:page] == 0' do
+      paginated_collected(:page => 0, :limit => 3).should ==
+        ["Person 1", "Person 2", "Person 3"]
+    end
+    
+    it 'should return page 1 if options[:page] not set' do
+      paginated_collected(:limit => 3, :page => -50).should ==
+        ["Person 1", "Person 2", "Person 3"]
+    end
+    
+    it 'should return last page if options[:page] > total pages' do
+      paginated_collected(:limit => 5, :page => 11).should ==
+        ["Person 46", "Person 47", "Person 48", "Person 49", "Person 50"]
+  
+      paginated_collected(:limit => 5, :page => 20).should ==
+        ["Person 46", "Person 47", "Person 48", "Person 49", "Person 50"]
+    end
+    
+    it 'should return last page for page == -1' do
+      paginated_collected(:limit => 5, :page => -1).should ==
+        ["Person 46", "Person 47", "Person 48", "Person 49", "Person 50"]
+        
+      paginated_collected(:limit => 3, :page => -1).should ==
+        ["Person 49", "Person 50"]
+    end
+    
+    it 'should return page from last for negative options[:page]' do
+      paginated_collected(:limit => 3, :page => -2).should ==
+        ["Person 46", "Person 47", "Person 48"]
+      
+      paginated_collected(:limit => 3, :page => -3).should ==
+        ["Person 43", "Person 44", "Person 45"]
+    end
+    
+    it 'should return first page for very negative options[:page] values' do
+      paginated_collected(:limit => 3, :page => -50).should ==
+        ["Person 1", "Person 2", "Person 3"]
+    end
+    
+    it 'should have at least one result on the last page' do
+      paginated(:limit => 5, :page => 10).should_not be_empty
+      
+      collection = paginated(:limit => 5, :page => 11)
+      collection.should_not be_empty
+      collection.current_page.should == 10
+    end
+    
+    it 'should default limit to config[:default_limit]' do
+      paginated().length.should == Paginate.config[:default_limit]
+    end
+  end
+
+  describe '#current_page' do
+    it 'should be added to collection' do
+      collection = paginated(:limit => 10)
+      # collection.methods.should include("current_page")
+      # Not sure why the above won't work. #singleton_methods doesn't either.
+      collection.current_page.should be_kind_of(Integer)
+    end
+    
+    it 'should be the number of the current page' do
+      paginated(:limit => 10, :page => 2).current_page.should == 2
+      paginated(:limit => 10, :page => 5).current_page.should == 5
+    end
+    
+    it 'should be 1 if there are no results' do
+      destroy_all
+      paginated(:limit => 10).current_page.should == 1
+    end
+    
+    it 'should be >= 1 and <= #pages (ie actual page, not given page)' do
+      paginated(:limit => 10, :page => -100).current_page.should == 1
+      paginated(:limit => 10, :page => 100).current_page.should == 5
+      paginated(:limit => 10, :page => -1).current_page.should == 5
+      paginated(:limit => 10, :page => 0).current_page.should == 1
+    end
+  end
+  
+  describe '#pages' do
+    it 'should be added to collection' do
+      collection = paginated(:limit => 10)
+      # collection.methods.should include("pages")
+      # Not sure why the above won't work. #singleton_methods doesn't either.
+      collection.pages.should be_kind_of(Integer)
+    end
+    
+    it 'should be the total number of pages for the collection' do
+      paginated(:limit => 10).pages.should == 5
+      paginated(:limit => 49).pages.should == 2
+      paginated(:limit => 50).pages.should == 1
+    end
+    
+    it 'should be 1 if there are no results' do
+      destroy_all
+      paginated(:limit => 10).pages.should == 1
+    end
+  end
+end
+
+# These specs are specific to ORM classes/modules, testing that +all+ receives
+# the correct options.
+#
+# A +@model+ instance variable is expected.
+shared_examples_for "ORM paginate methods" do
+  it "should set limit and offset options" do
+    limit = 10
+    
+    @model.should_receive(:all).with(:offset => 0, :limit => limit)
+    paginated(:page => 1, :limit => limit)
+    
+    @model.should_receive(:all).with(:offset => 0, :limit => limit + 1)
+    paginated(:page => 1, :limit => limit + 1)
+    
+    @model.should_receive(:all).with(:offset => 0, :limit => limit + 2)
+    paginated(:limit => limit + 2)
+    
+    @model.should_receive(:all).with(:offset => limit, :limit => limit)
+    paginated(:page => 2, :limit => limit)
+
+    @model.should_receive(:all).with(:offset => 40, :limit => limit)
+    paginated(:page => -1, :limit => limit)
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,6 @@
+--colour
+--format
+progress
+--loadby
+mtime
+--reverse

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require "rubygems"
+require "spec"
+
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')
+require 'paginate'
+require File.join(File.dirname(__FILE__), 'shared')

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: jm81-paginate
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Jared Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-22 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: (Yet another) Pagination for DataMapper, ActiveRecord, and Array
+email: jmorgan@morgancreative.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+- LICENSE
+- TODO
+files: 
+- LICENSE
+- README.md
+- Rakefile
+- TODO
+- lib/helpers
+- lib/helpers/merb.rb
+- lib/helpers/shared.rb
+- lib/paginate
+- lib/paginate/ar.rb
+- lib/paginate/dm.rb
+- lib/paginate/simple.rb
+- lib/paginate.rb
+- lib/paginators
+- lib/paginators/orm.rb
+- lib/paginators/simple.rb
+- spec/fixtures
+- spec/fixtures/ar.rb
+- spec/fixtures/dm.rb
+- spec/helpers
+- spec/helpers/merb_spec.rb
+- spec/helpers/shared_spec.rb
+- spec/paginate
+- spec/paginate/ar_spec.rb
+- spec/paginate/config_spec.rb
+- spec/paginate/dm_spec.rb
+- spec/paginate/simple_spec.rb
+- spec/paginators
+- spec/paginators/orm_spec.rb
+- spec/paginators/simple_spec.rb
+- spec/shared.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/jm81/paginate/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: (Yet another) Pagination for DataMapper, ActiveRecord, and Array
+test_files: []
+