taylorbarstow-simple_pagination 0.1.0

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 1

data/lib/simple_pagination.rb

@@ -0,0 +1,3 @@
+%w(page page_collection).each do |f|
+  require File.join(File.dirname(__FILE__), 'simple_pagination', f)
+end

data/lib/simple_pagination/page.rb

@@ -0,0 +1,59 @@
+module SimplePagination
+  class Page
+    def initialize(number, collection)
+      @number, @collection = number, collection
+    end
+    
+    ##
+    # The zero-based offset of the first record in this page
+    def offset
+      (@number-1) * @collection.page_size + 1
+    end
+
+    ##
+    # The one-based page number for this page
+    def number
+      @number
+    end
+
+    ##
+    # The Page object after this page (or +nil+ if +self.last?+)
+    def next
+      @collection[number + 1]
+    end
+
+    ##
+    # The Page object before this page (or +nil+ if +self.first?+)
+    def prev
+      @collection[number - 1]
+    end
+
+    ##
+    # Test if this is the first page in the collection
+    def first?
+      number == 1
+    end
+
+    ## 
+    # Test if this is the last page in the collection
+    def last?
+      number == @collection.length
+    end
+
+    ##
+    # Test if this is the current page.
+    def current?
+      self === @collection.current
+    end
+
+    ##
+    # Generate a "window" of pages around (and including) this page. +n+
+    # is the number of pages to show (defaults to 10).  For example, if this is
+    # page 8 and you ask for window(10) you will get an array of Page objects
+    # representing the following pages:  4, 5, 6, 7, 8, 9, 10, 11, 12, 13
+    def window(n=10)
+      start = [1, [number-(n/2)+1, @collection.length-n+1].min].max
+      (start..start+n-1).collect {|i| @collection[i]}.compact
+    end
+  end
+end

data/lib/simple_pagination/page_collection.rb

@@ -0,0 +1,68 @@
+module SimplePagination
+  class PageCollection
+    ##
+    # Create a new PageCollection object.  The following options are available.
+    # [:current_offset] The zero-based offset of the first record in the current page of results
+    # [:current_page]   The one-based offset of the current page of results
+    # [:total]          The total number of results across all pages
+    # [:page_size]      The page size
+    #
+    # You can choose between :current_offset and :current_page based on your
+    # needs.  Same goes for :total_records and :total_pages.  :page_size
+    # is required.
+    #
+    # A typical use of this class would be to define a <tt>pages</tt> method on your
+    # result set class which returns an instance of PageCollection. (So you can 
+    # do, e.g., <tt>my_result_set.pages.current</tt> and so on.)
+    def initialize(options={})
+      check_options(options)
+      @pages, @page_size = {}, options[:page_size]
+      @length = options[:total_pages] || options[:total_records] / @page_size
+      @current_page = options[:current_page] || (options[:current_offset]/@page_size)+1
+    end
+    
+    ##
+    # A Page object representing the page at a given page number (one-based).
+    def [](i)
+      @pages[i] ||= Page.new(i, self) unless out_of_bounds?(i)
+    end
+    
+    ##
+    # A Page object representing the current page in the collection.
+    def current
+      self[@current_page]
+    end
+    
+    ##
+    # A Page object representing the first page in the collection.
+    def first
+      self[1]
+    end
+
+    ##
+    # A Page object representing the last page in the collection.
+    def last
+      self[length]
+    end
+
+    ##
+    # The number of pages in the collection.
+    attr_reader :length
+
+    ## 
+    # The number of records shown on each page in the collection.
+    attr_reader :page_size
+    
+  private
+  
+    def check_options(options)
+      raise ArgumentError, "requires :current_offset or :current_page" unless options[:current_offset] || options[:current_page]
+      raise ArgumentError, "requires :page_size" unless options[:page_size]
+      raise ArgumentError, "requires :total" unless options[:total_pages] or options[:total_records]
+    end
+    
+    def out_of_bounds?(i)
+      i > length || i < 1
+    end
+  end
+end

data/test/simple_pagination/page_collection_test.rb

@@ -0,0 +1,99 @@
+require File.join(File.dirname(__FILE__), '..', 'test_helper.rb')
+
+class PageCollectionTest < Test::Unit::TestCase
+  include SimplePagination
+  
+  context "creating a new instance" do
+    should "require :current_offset or :current_page" do
+      args = {:page_size => 10, :total_records => 100}
+      assert_raise(ArgumentError) {PageCollection.new(args)}
+      assert_nothing_raised {PageCollection.new(args.merge(:current_offset => 0))}
+      assert_nothing_raised {PageCollection.new(args.merge(:current_page => 1))}
+    end
+    
+    should "require :total_records or :total_pages" do
+      args = {:page_size => 10, :current_page => 1}
+      assert_raise(ArgumentError) {PageCollection.new(args)}
+      assert_nothing_raised {PageCollection.new(args.merge(:total_pages => 10))}
+      assert_nothing_raised {PageCollection.new(args.merge(:total_records => 10))}
+    end
+    
+    should "require :page_size" do
+      args = {:total_records => 100, :current_offset => 0}
+      assert_raise(ArgumentError) {PageCollection.new(args)}
+      assert_nothing_raised {PageCollection.new(args.merge(:page_size => 10))}
+    end
+  end
+  
+  context "accessors" do
+    setup do
+      @collection = PageCollection.new(:total_pages => 10, :page_size => 10, :current_offset => 0)
+    end
+    
+    should "provide page_size accessor" do
+      assert_equal 10, @collection.page_size
+    end
+    
+    should "provide length accessor" do
+      assert_equal 10, @collection.length
+    end
+    
+    should "calculate length when given :total_records" do
+      c = PageCollection.new(:total_records => 113, :page_size => 3, :current_offset => 0)
+      assert_equal 37, c.length
+    end
+  end
+  
+  context "accessing a specific page" do
+    setup do
+      @collection = PageCollection.new(:total_pages => 10, :page_size => 10, :current_page=>1)
+    end
+
+    should "create and return a new Page instance" do
+      p = Page.new(1, @collection)
+      Page.expects(:new).with(1, @collection).returns(p)
+      assert_same p, @collection[1]
+    end
+    
+    should "return the same Page across multiple invocations" do
+      assert_same @collection[3], @collection[3]
+      assert_not_same @collection[3], @collection[4]
+    end
+    
+    context "when the page is out of bounds" do
+      should "return nil" do
+        assert_equal nil, @collection[100]
+        assert_equal nil, @collection[0]
+        assert_equal nil, @collection[-1]
+      end
+    end
+  end
+  
+  context "accessing named pages" do
+    setup do
+      @collection = PageCollection.new(:total_pages => 10, :page_size => 10, :current_page=>1)
+    end
+    
+    should "access current page" do
+      (1..3).each do |i|
+        c = PageCollection.new(:total_pages => 10, :page_size => 10, :current_page=>i)
+        c.expects(:[]).with(i)
+        c.current
+      end
+    end
+    
+    should "access first page" do
+      @collection.expects(:[]).with(1)
+      @collection.first
+    end
+    
+    should "access last page" do
+      @collection.expects(:[]).with(10)
+      @collection.last
+      
+      c = PageCollection.new(:total_records => 113, :page_size => 3, :current_page => 1)
+      c.expects(:[]).with(37)
+      c.last
+    end
+  end
+end

data/test/simple_pagination/page_test.rb

@@ -0,0 +1,108 @@
+require File.join(File.dirname(__FILE__), '..', 'test_helper.rb')
+
+class PageTest < Test::Unit::TestCase
+  include SimplePagination
+
+  def assert_page_window(expected, actual) 
+    actual.each {|page| assert_instance_of Page, page}
+    assert_equal expected, actual.collect {|page| page.number}
+  end
+  
+  context "accessors" do
+    setup do
+      @collection = PageCollection.new(:current_page => 1, :total_pages => 10, :page_size => 10)
+      @page = Page.new(5, @collection)
+    end
+    
+    should "provide accessor for page number" do
+      assert_equal 5, @page.number
+    end
+    
+    should "provide accessor for first record offset" do
+      assert_equal 41, @page.offset
+    end
+  end
+  
+  context "next/previous page" do
+    setup do
+      @collection = PageCollection.new(:current_page => 1, :total_pages => 10, :page_size => 10)
+    end
+    
+    should "provide previous page using PageCollection#[]" do
+      @collection.expects(:[]).with(2)
+      Page.new(3, @collection).prev
+      
+      @collection.expects(:[]).with(4)
+      Page.new(5, @collection).prev
+    end
+    
+    should "provide next page using PageCollection#[]" do
+      @collection.expects(:[]).with(2)
+      Page.new(1, @collection).next
+      
+      @collection.expects(:[]).with(4)
+      Page.new(3, @collection).next
+    end
+  end
+  
+  context "named page tests" do
+    setup do
+      @collection = PageCollection.new(:current_page => 1, :total_pages => 10, :page_size => 10)
+    end
+    
+    should "identify last page" do
+      assert @collection[10].last?
+    end
+    
+    should "not identify non last page as last" do
+      (1..9).each {|i| assert !@collection[i].last?}
+    end
+    
+    should "identify first page" do
+      assert @collection[1].first?
+    end
+    
+    should "not identify non first page as first" do
+      (2..10).each {|i| assert !@collection[i].first?}
+    end
+    
+    should "identify current page" do
+      assert @collection[1].current?
+    end
+    
+    should "not identify non current page as current" do
+      (2..10).each {|i| assert !@collection[i].current?}
+    end
+  end
+  
+  context "generating a page window" do
+    setup do
+      @collection = PageCollection.new(:current_page => 1, :page_size => 10, :total_pages => 50)
+    end
+    
+    should "generate page window of the requested size" do
+      assert_equal 10, @collection[10].window(10).length
+      assert_equal 5, @collection[10].window(5).length
+    end
+    
+    should "generate page window when near beginning" do
+      (1..5).each do |i|
+        assert_page_window (1..10).to_a, @collection[i].window(10)
+      end
+    end
+    
+    should "generate page window when in middle" do
+      assert_page_window (20..29).to_a, @collection[24].window(10)
+    end
+    
+    should "generate page window when near end" do
+      (46..50).each do |i|
+        assert_page_window (41..50).to_a, @collection[i].window(10)
+      end
+    end
+    
+    should "generate page window when requesting window larger than # of pages" do
+      assert_page_window (1..50).to_a, @collection[1].window(100)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'simple_pagination')

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: taylorbarstow-simple_pagination
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Taylor Barstow
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-11 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A simple, standalone pagination gem for non-ActiveRecord data.
+email: taylorbarstow@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- VERSION.yml
+- lib/simple_pagination
+- lib/simple_pagination/page.rb
+- lib/simple_pagination/page_collection.rb
+- lib/simple_pagination.rb
+- test/simple_pagination
+- test/simple_pagination/page_collection_test.rb
+- test/simple_pagination/page_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/taylorbarstow/simple_pagination
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+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: A simple, standalone pagination gem non-ActiveRecord data.
+test_files: []
+