folio-pagination-legacy 0.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'guard-minitest'
+end
+
+group :will_paginate do
+  gem 'rails', '~> 2.3.6'
+  gem 'will_paginate', '~> 2.3'
+end
+
+group :test do
+  gem 'sqlite3'
+end

data/Guardfile

@@ -0,0 +1,5 @@
+guard :minitest do
+  watch(%r{^test/(.*)_test\.rb})
+  watch(%r{^lib/(.*)\.rb}) { |m| "test/#{m[1]}_test.rb" }
+  watch(%r{^test/test_helper\.rb}) { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Instructure, Inc.
+
+MIT License
+
+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,235 @@
+# Folio
+
+`Folio` is a library for pagination. It's meant to be nearly compatible
+with `WillPaginate`, but with broader -- yet more well-defined --
+semantics to allow for sources whose page identifiers are non-ordinal
+(i.e. a page identifier of `3` does not necessarily indicate the third
+page).
+
+[![Build Status](https://travis-ci.org/instructure/folio.png?branch=master)](https://travis-ci.org/instructure/folio)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'folio-pagination'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install folio-pagination
+
+## Usage
+
+The core `Folio` interface is defined by two mixins. Mixing `Folio` into
+a source of items creates a "folio" and provides pagination on that
+folio. Mixing `Folio::Page` into a subset of items from a folio creates
+a "page" with additional properties relating it to the folio and the
+other pages in the folio.
+
+`Folio` also provides some basic implementations, both standalone and by
+mixing these modules in to familiar classes.
+
+### Pages
+
+You can mix `Folio::Page` into any `Enumerable`. The mixin gives you
+eight attributes and one method:
+
+ * `ordinal_pages?` indicates whether the page identifiers in
+   `current_page`, `first_page`, `last_page`, `previous_page`, and
+   `next_page` should be considered ordinal or not.
+
+ * `current_page` is the page identifier addressing this page within the
+   folio.
+
+ * `per_page` is the number of items requested from the folio when
+   filling this page.
+
+ * `first_page` is the page identifier addressing the first page within
+   the folio.
+
+ * `last_page` is the page identifier addressing the final page within
+   the folio, if known.
+
+ * `next_page` is the page identifier addressing the immediately
+   following page within the folio, if there is one.
+
+ * `previous_page` is the page identifier addressing the immediately
+   preceding page within the folio, if there is one and it is known.
+
+ * `total_entries` is the number of items in the folio, if known.
+
+ * `total_pages` if the number of pages in the folio, if known. It is
+   calculated from `total_entries` and `per_page`.
+
+`ordinal_pages?`, `first_page`, and `last_page` are common to all pages
+created by a folio and are configured, as available, when the folio
+creates a blank page in its `build_page` method (see below).
+
+`current_page`, `per_page`, and `total_entries` control the filling of a
+page and are configured from parameters to the folio's `paginate`
+method.
+
+`next_page` and `previous_page` are configured, as available, when the
+folio fills the configured page in its `fill_page` method (see below).
+
+### Folios
+
+You can mix `Folio` into any class implementing two methods:
+
+ * `build_page` is responsible for instantiating a `Folio::Page` and
+   configuring its `ordinal_pages?`, `first_page`, and `last_page`
+   attributes.
+
+ * `fill_page` will receive a `Folio::Page` with the `ordinal_pages?`,
+   `first_page`, `last_page`, `current_page`, `per_page`, and
+   `total_entries` attributes configured, and should populate the page
+   with the corresponding items from the folio. It should also set
+   appropriate values for the `next_page` and `previous_page` attributes
+   on the page. If the value provided in the page's `current_page`
+   cannot be interpreted as addressing a page in the folio,
+   `Folio::InvalidPage` should be raised.
+
+In return, `Folio` provides a `paginate` method and `per_page`
+attributes for both the folio class and for individual folio instances.
+
+The `paginate` method coordinates the page creation, configuration, and
+population. It takes three parameters: `page`, `per_page`, and
+`total_entries`, each optional.
+
+ * `page` configures the page's `current_page`, defaulting to the page's
+   `first_page`.
+
+ * `per_page` configures the page's `per_page`, defaulting to the
+   folio's `per_page` attribute.
+
+ * `total_entries` configures the page's `total_entries`, if present.
+   otherwise, if the folio implements a `count` method, the page's
+   `total_entries` will be set from that method.
+
+NOTE: providing a `total_entries` parameter of nil will still bypass the
+`count` method, leaving `total_entries` nil. This is useful when the
+count would be too expensive and you'd rather just leave the number of
+entries unknown.
+
+The `per_page` attribute added to the folio instance will default to the
+`per_page` attribute from the folio class when unset. The `per_page`
+class attribute added to the folio class will default to global
+`Folio.per_page` when unset.
+
+### Ordinal Pages and Folios
+
+A typical use case for pagination deals with ordinal page identifiers;
+e.g. "1" means the first page, "2" means the second page, etc.
+
+As a matter of convenience for these use cases, additional mixins of
+`Folio::Ordinal` and `Folio::Ordinal::Page` are provided.
+
+Mixing `Folio::Ordinal::Page` into an `Enumerable` provides the same
+methods as `Folio::Page` but with the following overrides:
+
+ * `ordinal_pages` is always true
+
+ * `first_page` is always 1
+
+ * `previous_page` is always either `current_page-1` or nil, depending
+   on how `current_page` relates to `first_page`.
+
+ * `next_page` can only be set if `total_pages` is unknown. if
+   `total_pages` is known, `next_page` will be either `current_page+1`
+   or nil, depending on how `current_page` relates to `last_page`. if
+   `total_pages` is unknown and `next_page` is unset (vs. explicitly set
+   to nil), it will default to `current_page+1`.
+
+ * `last_page` is deterministic: always `total_pages` if `total_pages`
+   is known, `current_page` if `total_pages` is unknown and `next_page`
+   is nil, nil otherwise (indicating the page sequence continues until
+   `next_page` is nil).
+
+Similarly, mixing `Folio::Ordinal` into a source provides the same
+methods as `Folio`, but simplifies your `build_page` and `fill_page`
+methods by moving some responsibility into the `paginate` method.
+
+ * `build_page` no longer needs to configure `ordinal_page?`, `first_page`,
+   or `last_page` on the instantiated page. Instead, just instantiate
+   and return a `Folio::Page` or `Folio::Ordinal::Page`. If what you
+   return is not a `Folio::Ordinal::Page`, `paginate` will decorate it
+   to be one. Then `ordinal_page?`, `first_page`, and `last_page` are
+   handled for you, as described above.
+
+ * `fill_page` no longer needs to configure `next_page` and
+   `previous_page`; the ordinal page will handle them. (Note that if
+   necessary, you can still set `next_page` explicitly to nil.) Also,
+   `paginate` will now perform ordinal bounds checking for you, so you
+   can focus entirely on populating the page.
+
+### Decorations and `create`
+
+Often times you just want to take a simple collection, such as an
+array, and have it act like a page. One way would be to subclass
+`Array` and mixin `Folio::Page`, then instantiate the subclass.
+
+Alternately, you can just call `Folio::Page.decorate(collection)`. This
+will decorate the collection instance in a delegate that mixes in
+`Folio::Page` for you. So, for example, a simple `build_page` method
+could just be:
+
+```
+  def build_page
+    Folio::Page.decorate([])
+  end
+```
+
+For the common case where a new empty array is what you intend to
+decorate, you can simply call `Folio::Page.create`.
+
+`Folio::Page::Ordinal.decorate(collection)` and
+`Folio::Page::Ordinal.create` are also available, respectively, for the
+ordinal case. `decorate` will assume the passed in collection lacks any
+pagination and will include `Folio::Page` along with
+`Folio::Page::Ordinal`.
+
+### Enumerable Extension
+
+If you require `folio/core_ext/enumerable`, all `Enumerable`s will be
+extended with `Folio::Ordinal` and naive `build_page` and `fill_page`
+methods.
+
+`build_page` will simply return a basic ordinal page as from
+`Folio::Page::Ordinal.create`. `fill_page` then selects an appropriate
+range of items from the folio using standard `Enumerable` methods, then
+calls `replace` on the page (it's a decorated array) with this subset.
+
+This lets you do things like:
+
+```
+require 'folio/core_ext/enumerable'
+
+natural_numbers = Enumerator.new do |enum|
+  n = 0
+  loop{ enum.yield(n += 1) }
+end
+page = natural_numbers.paginate(page: 3, per_page: 5, total_entries: nil)
+
+page.ordinal_pages?  #=> true
+page.per_page        #=> 5
+page.first_page      #=> 1
+page.previous_page   #=> 2
+page.current_page    #=> 3
+page.next_page       #=> 4
+page.last_page       #=> nil
+page.total_entries   #=> nil
+page.total_pages     #=> nil
+page                 #=> [11, 12, 13, 14, 15]
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/folio-pagination-legacy.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'folio/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "folio-pagination-legacy"
+  spec.version       = Folio::VERSION
+  spec.authors       = ["Jacob Fugal"]
+  spec.email         = ["jacob@instructure.com"]
+  spec.description   = %q{A pagination library.}
+  spec.summary       = %q{
+    Folio is a library for pagination. It's meant to be nearly compatible
+    with WillPaginate, but with broader -- yet more well-defined -- semantics
+    to allow for sources whose page identifiers are non-ordinal.
+
+    This version of the gem is for legacy Rails 2.3 support. If you're running
+    Rails 3 or newer, you want the folio-pagination gem.
+  }
+  spec.homepage      = "https://github.com/instructure/folio/tree/legacy"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/folio-pagination-legacy.rb

@@ -0,0 +1,3 @@
+# convenience so that you can require by the gem name and get the same effect
+# as requiring the canonical 'folio'.
+require 'folio'

data/lib/folio.rb

@@ -0,0 +1,84 @@
+require "folio/version"
+require "folio/per_page"
+
+# Mix into any class implementing the following two methods:
+#
+# +build_page+: Responsible for instantiating a Folio::Page and
+# configuring its ordinal_pages?, first_page, and last_page attributes;
+# those values being common to any page returned from the folio.
+#
+# +fill_page+: Receives a Folio::Page with the ordinal_pages?,
+# first_page, last_page, current_page, per_page, and total_entries
+# attributes configured, and populates the page with the corresponding
+# items from the folio. Also sets appropriate values for the next_page
+# and previous_page attributes on the page. If the value provided in the
+# page's current_page cannot be interpreted as addressing a page in the
+# folio, raises Folio::InvalidPage.
+#
+# In return, `Folio` provides a the paginate method and per_page
+# attributes described below.
+module Folio
+  # Returns a page worth of items from the folio in a Folio::Page.
+  # accepts the following parameters:
+  #
+  # +page+: a page identifier addressing which page of the folio to
+  # return. if not present, the first page will be returned. will raise
+  # Folio::InvalidPage if the provided value cannot be used to address a
+  # page.
+  #
+  # +per_page+: number of items to attempt to include in the page. if
+  # not present, defaults to the folio's per_page value. should only
+  # include fewer items if the end of the folio is reached.
+  #
+  # +total_entries+: pre-calculated value for the total number of items
+  # in the folio. may be nil, indicating the returned page should have
+  # total_entries nil.
+  #
+  # if the folio implements a count method and the total_entries
+  # parameter is not supplied, the page's total_entries will be set from
+  # the count method.
+  def paginate(options={})
+    page = self.build_page
+    page = self.configure_pagination(page, options)
+    page = self.fill_page(page)
+    page
+  end
+
+  def configure_pagination(page, options)
+    current_page = options.fetch(:page) { nil }
+    current_page = page.first_page if current_page.nil?
+    page.current_page = current_page
+    page.per_page = options.fetch(:per_page) { self.per_page }
+    page.total_entries = options.fetch(:total_entries) { self.respond_to?(:count) ? self.count : nil }
+    page
+  end
+
+  def default_per_page
+    self.class.per_page
+  end
+
+  include ::Folio::PerPage
+
+  # this funny pattern is so that if a module (e.g. Folio::Ordinal)
+  # includes this module, it won't get the per_page attribute, but will
+  # still be able to bestow that attribute on any class that includes
+  # *it*.
+  module PerPageIncluder
+    def included(klass)
+      if klass.is_a?(Class)
+        klass.extend ::Folio::PerPage
+      else
+        klass.extend ::Folio::PerPageIncluder
+      end
+    end
+  end
+
+  extend PerPageIncluder
+  extend PerPage
+  per_page(30)
+end
+
+# load the other commonly used portions of the gem
+require "folio/page"
+require "folio/ordinal"
+require "folio/ordinal/page"

data/lib/folio/core_ext/enumerable.rb

@@ -0,0 +1,51 @@
+require 'folio/ordinal'
+require 'delegate'
+
+module Folio
+  module Enumerable
+    class Decorator < ::SimpleDelegator
+      # just fill a typical ordinal page
+      def build_page
+        ::Folio::Ordinal::Page.create
+      end
+
+      # fill by taking the appropriate slice out of the enumerable. if
+      # the slice is empty and it's not the first page, it's invalid
+      def fill_page(page)
+        slice = self.each_slice(page.per_page).first(page.current_page)[page.current_page-1] || []
+        raise ::Folio::InvalidPage if slice.empty? && page.current_page != page.first_page
+        page.replace slice
+        page
+      end
+
+      # things that already included Enumerable won't have extended the
+      # PerPage, so the instance's default default_per_page method looking
+      # at self.class.per_page won't work. point it back at
+      # Folio.per_page
+      def default_per_page
+        Folio.per_page
+      end
+
+      include ::Folio::Ordinal
+
+      METHODS = self.instance_methods - SimpleDelegator.instance_methods
+    end
+  end
+end
+
+# Extends any Enumerable to act like a Folio::Ordinal. Important: the
+# source Enumerable is still not a Folio::Ordinal (it's not in the
+# ancestors list). Instead, any Enumerable can be decorated via its new
+# `pagination_decorated` method, and all folio methods are forwarded to
+# that decorated version.
+module Enumerable
+  def pagination_decorated
+    @pagination_decorated ||= Folio::Enumerable::Decorator.new(self)
+  end
+
+  Folio::Enumerable::Decorator::METHODS.each do |method|
+    define_method(method) do |*args|
+      pagination_decorated.send(method, *args)
+    end
+  end
+end