paginator 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+== 1.0.0 / 2006-10-23
+
+* Initial release

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+bin/paginator
+lib/paginator.rb
+test/test_paginator.rb

data/README.txt

@@ -0,0 +1,80 @@
+paginator
+    by Bruce Williams
+    http://codefluency.com
+
+== DESCRIPTION:
+  
+Paginator is a simple pagination class that provides a generic interface suitable
+for use in any Ruby program.
+
+== FEATURES/PROBLEMS:
+  
+Paginator doesn't make any assumptions as to how data is retrieved; you just
+have to provide it with the total number of objects and a way to pull a specific
+set of objects based on the offset and number of objects per page.
+
+== SYNOPSIS:
+
+=== In a Rails Application
+
+  # In your controller
+  PER_PAGE = 20
+  @pager = Paginator.new(Foo.count, PER_PAGE) do |offset, per_page|
+    Foo.find(:all, :limit => per_page, :offset => offset)
+  end
+  @page = @pager.page(params[:page])
+
+  # In your view
+  <% @page.items.each do |foo| %>
+    <%# Show something for each item %>
+  <% end %>
+  <%= @page.number %>
+  <%= link_to("Prev", foos_url(:page => @page.prev.number)) if @page.prev? %>
+  <%= link_to("Next", foos_url(:page => @page.next.number)) if @page.next? %>
+
+=== Anything else
+
+  bunch_o_data = (1..60).to_a
+  PER_PAGE = 10
+	pager = Paginator.new(bunch_o_data.size, PER_PAGE) do |offset, per_page|
+	  bunch_o_data[offset,per_page]
+	end
+	pager.each do |page|
+	  puts "Page ##{page.number}"
+	  page.each do |item|
+	    puts item
+    end
+	end
+
+== REQUIREMENTS:
+
+None.
+
+== INSTALL:
+
+No special instructions.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2006 Bruce Williams (http://codefluency.com)
+
+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/Rakefile

@@ -0,0 +1,19 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/paginator.rb'
+
+Hoe.new('paginator', Paginator::VERSION) do |p|
+  p.rubyforge_name = 'paginator'
+  p.summary = 'A generic paginator object for use in any Ruby program'
+  p.description =<<EOD
+Paginator doesn't make any assumptions as to how data is retrieved; you just
+have to provide it with the total number of objects and a way to pull a specific
+set of objects based on the offset and number of objects per page.  
+EOD
+  p.url = "http://paginator.rubyforge.org"
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+end
+
+# vim: syntax=Ruby

data/lib/paginator.rb

@@ -0,0 +1,107 @@
+require 'forwardable'
+
+class Paginator
+  
+  VERSION = '1.0.0'
+
+  class ArgumentError < ::ArgumentError; end
+  class MissingCountError < ArgumentError; end
+  class MissingSelectError < ArgumentError; end  
+  
+  attr_reader :per_page  
+  
+  # Instantiate a new Paginator object
+  #
+  # Provide:
+  # * A total count of the number of objects to paginate
+  # * The number of objects in each page
+  # * A block that returns the array of items
+  #   * The block is passed the item offset 
+  #     (and the number of items to show per page, for
+  #     convenience)
+  def initialize(count, per_page, &select)
+    @count, @per_page = count, per_page
+    unless select
+      raise MissingSelectError, "Must provide block to select data for each page"
+    end
+    @select = select
+  end
+  
+  # Total number of pages
+  def number_of_pages
+    (@count / @per_page) + (@count % @per_page > 0 ? 1 : 0)
+  end
+  
+  # First page object
+  def first
+    page 1
+  end
+  
+  # Last page object
+  def last
+    page number_of_pages
+  end
+  
+  # Iterate through pages
+  def each
+    1.upto(number_of_pages) do |number|
+      yield page(number)
+    end
+  end
+  
+  # Retrieve page object by number
+  def page(number)
+    Page.new(self, number, lambda{ @select.call((number - 1) * @per_page, @per_page) })
+  end
+  
+  # Page object
+  #
+  # Retrieves items for a page and provides metadata about the position
+  # of the page in the paginator
+  class Page
+    
+    extend Forwardable
+    def_delegator :@pager, :first, :first
+    def_delegator :@pager, :last, :last
+    def_delegator :items, :each
+        
+    attr_reader :number, :pager
+    
+    def initialize(pager, number, select) #:nodoc:
+      @pager, @number = pager, number
+      @select = select
+    end
+    
+    # Retrieve the items for this page
+    # * Caches
+    def items
+      @items ||= @select.call
+    end
+    
+    # Checks to see if there's a page before this one
+    def prev?
+      @number > 1
+    end
+    
+    # Get previous page (if possible)
+    def prev
+      @pager.page(@number - 1) if prev?
+    end
+    
+    # Checks to see if there's a page after this one
+    def next?
+      @number < @pager.number_of_pages
+    end
+    
+    # Get next page (if possible)
+    def next
+      @pager.page(@number + 1) if next?
+    end
+    
+    def ==(other) #:nodoc:
+      @pager == other.pager && self.number == other.number
+    end
+    
+  end
+  
+end

data/test/test_paginator.rb

@@ -0,0 +1,76 @@
+require 'test/unit'
+require 'paginator'
+
+class PaginatorTest < Test::Unit::TestCase
+
+  PER_PAGE = 10
+
+  def setup
+    @data = (0..43).to_a
+    @pager = Paginator.new(@data.size, PER_PAGE) do |offset,per_page|
+      @data[offset,per_page]
+    end
+  end
+  
+  def test_initializing_paginator_raises_exception
+    assert_raises(Paginator::MissingSelectError) do
+      @pager = Paginator.new(@data.size, PER_PAGE)
+    end
+  end  
+  
+  def test_can_get_last_page_from_page_object
+    assert_equal @pager.last, @pager.page(2).last
+  end
+  
+  def test_can_get_first_page_from_page_object
+    assert_equal @pager.first, @pager.page(2).first    
+  end
+
+  def test_does_not_exceed_per_page
+    @pager.each do |page|
+      assert page.items.size <= PER_PAGE
+    end
+  end
+  
+  def test_only_last_page_has_less_items
+    @pager.each do |page|
+      if page != @pager.last
+        assert page.items.size <= PER_PAGE
+      else
+        assert page.items.size < PER_PAGE
+      end
+    end    
+  end
+  
+  def test_returns_correct_first_page
+    assert_equal @pager.page(1).number, @pager.first.number
+  end
+  
+  def test_returns_correct_last_page
+    assert_equal @pager.page(5).number, @pager.last.number
+  end
+  
+  def test_last_page_has_no_next_page
+    assert !@pager.last.next?
+    assert !@pager.last.next
+  end
+
+  def test_first_page_has_no_prev_page
+    assert !@pager.first.prev?
+    assert !@pager.first.prev
+  end
+  
+  def test_each
+    @pager.each do |page|
+      assert page
+      page.each do |item|
+        assert item
+      end
+    end
+  end
+  
+  def test_number_of_pages
+    assert_equal 5, @pager.number_of_pages
+  end
+
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: paginator
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-10-23 00:00:00 -06:00
+summary: A generic paginator object for use in any Ruby program
+require_paths: 
+- lib
+- test
+email: ryand-ruby@zenspider.com
+homepage: http://paginator.rubyforge.org
+rubyforge_project: paginator
+description: Paginator doesn't make any assumptions as to how data is retrieved; you just have to provide it with the total number of objects and a way to pull a specific set of objects based on the offset and number of objects per page.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Ryan Davis
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- bin/paginator
+- lib/paginator.rb
+- test/test_paginator.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- paginator
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.2
+    version: