folio-pagination 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', '>= 3.0'
+  gem 'will_paginate', '~> 3.0'
+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.gemspec

@@ -0,0 +1,27 @@
+# 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"
+  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.
+  }
+  spec.homepage      = "https://github.com/instructure/folio"
+  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/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

data/lib/folio/invalid_page.rb

@@ -0,0 +1,5 @@
+# Raised when a value passed to a Folio's paginate method is
+# non-sensical or out of bounds for that folio.
+module Folio
+  class InvalidPage < ArgumentError; end
+end

data/lib/folio/ordinal/page.rb

@@ -0,0 +1,107 @@
+require 'folio/page'
+
+# Mix in to an Enumerable to provide the same methods as Folio::Page but with
+# the following overrides:
+#
+#  * ordinal_pages is always true
+#
+#  * first_page is always 1
+#
+#  * current_page is forced to an integer
+#
+#  * 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.
+#    if next_page is set to a non-nil value, that value will be forced to an
+#    integer.
+#
+#  * 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).
+module Folio
+  module Ordinal
+    module Page
+      def ordinal_pages
+        true
+      end
+      alias :ordinal_pages? :ordinal_pages
+
+      def first_page
+        1
+      end
+
+      def last_page
+        (total_pages || next_page) ? total_pages : current_page
+      end
+
+      def current_page=(value)
+        @current_page = value.to_i
+      end
+
+      def next_page=(value)
+        @next_page = value && value.to_i
+      end
+
+      def next_page
+        if total_pages && current_page >= total_pages
+          # known number of pages and we've reached the last one. no next page
+          # (even if explicitly set)
+          nil
+        elsif total_pages || !defined?(@next_page)
+          # (1) known number of pages and we haven't reached the last one
+          #     (because we're not in the branch above), or
+          # (2) unknown number of pages, but nothing set, so we assume an
+          #     infinite stream
+          # so there's a next page, and it's the one after this one
+          current_page + 1
+        else
+          # just use what they set
+          @next_page
+        end
+      end
+
+      def previous_page
+        current_page > first_page ? current_page - 1 : nil
+      end
+
+      def out_of_bounds?
+        (current_page < first_page) || (last_page && current_page > last_page) || false
+      end
+
+      def offset
+        (current_page - 1) * per_page
+      end
+
+      class Decorator < Folio::Page::Decorator
+        include Folio::Ordinal::Page
+      end
+
+      class DecoratedArray < Decorator
+        def initialize
+          super []
+        end
+
+        def replace(array)
+          result = super
+          if total_entries.nil? and length < per_page and (current_page == 1 or length > 0)
+            self.total_entries = offset + length
+          end
+          result
+        end
+      end
+
+      def self.decorate(collection)
+        collection = Folio::Ordinal::Page::Decorator.new(collection) unless collection.is_a?(Folio::Ordinal::Page)
+        collection
+      end
+
+      def self.create
+        Folio::Ordinal::Page::DecoratedArray.new
+      end
+    end
+  end
+end

data/lib/folio/ordinal.rb

@@ -0,0 +1,33 @@
+require 'folio'
+require 'folio/ordinal/page'
+require 'folio/invalid_page'
+
+# Mix in to a source to provide the same methods as Folio, but with simpler
+# build_page and fill_page methods required on the host (some responsibility is
+# moved 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::Ordinal::Page. If what you return is not a
+#    Folio::Ordinal::Page, paginate will decorate it to be one.
+#
+#  * 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.
+#
+module Folio
+  module Ordinal
+    # decorate the page before configuring, and then validate the configured
+    # current_page before returning it
+    def configure_pagination(page, options)
+      page = super(::Folio::Ordinal::Page.decorate(page), options)
+      raise ::Folio::InvalidPage unless page.current_page.is_a?(Integer)
+      raise ::Folio::InvalidPage if page.out_of_bounds?
+      page
+    end
+
+    # otherwise acts like a normal folio
+    include ::Folio
+  end
+end

data/lib/folio/page.rb

@@ -0,0 +1,86 @@
+require 'folio/per_page'
+require 'delegate'
+
+# Mix into any Enumerable. The mixin gives you the eight attributes and
+# one method described below.
+#
+# 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.
+#
+# 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.
+module Folio
+  module Page
+    # indicates whether the page identifiers in current_page,
+    # first_page, last_page, previous_page, and next_page should be
+    # considered ordinal or not.
+    attr_accessor :ordinal_pages
+    alias :ordinal_pages? :ordinal_pages
+
+    # page identifier addressing this page within the folio.
+    attr_accessor :current_page
+
+    # number of items requested from the folio when filling the page.
+    include Folio::PerPage
+
+    # page identifier addressing the first page within the folio.
+    attr_accessor :first_page
+
+    # page identifier addressing the final page within the folio, if
+    # known.
+    def last_page=(value)
+      @last_page = value
+    end
+
+    def last_page
+      if next_page.nil?
+        current_page
+      else
+        @last_page
+      end
+    end
+
+    # page identifier addressing the immediately following page within
+    # the folio, if there is one.
+    attr_accessor :next_page
+
+    # page identifier addressing the immediately preceding page within
+    # the folio, if there is one and it is known.
+    attr_accessor :previous_page
+
+    # number of items in the folio, if known.
+    attr_accessor :total_entries
+
+    # number of pages in the folio, if known. calculated from
+    # total_entries and per_page.
+    def total_pages
+      return nil unless total_entries && per_page && per_page > 0
+      return 1 if total_entries <= 0
+      (total_entries / per_page.to_f).ceil
+    end
+
+    class Decorator < ::SimpleDelegator
+      include Folio::Page
+    end
+
+    class DecoratedArray < Decorator
+      def initialize
+        super []
+      end
+    end
+
+    def self.decorate(collection)
+      collection = Folio::Page::Decorator.new(collection) unless collection.is_a?(Folio::Page)
+      collection
+    end
+
+    def self.create
+      Folio::Page::DecoratedArray.new
+    end
+  end
+end

data/lib/folio/per_page.rb

@@ -0,0 +1,15 @@
+module Folio
+  module PerPage
+    def default_per_page
+      Folio.per_page
+    end
+
+    def per_page(*args)
+      raise ArgumentError if args.size > 1
+      @per_page = (args.first && args.first.to_i) if args.size > 0
+      @per_page ? @per_page : default_per_page
+    end
+
+    alias_method :per_page=, :per_page
+  end
+end

data/lib/folio/rails.rb

@@ -0,0 +1,35 @@
+begin
+  require 'rails'
+rescue LoadError
+  raise "folio-pagination's rails support requires rails"
+end
+
+begin
+  require 'will_paginate/railtie'
+rescue LoadError
+  raise "folio-pagination's rails support requires will_paginate"
+end
+
+module Folio
+  module WillPaginate
+    class Railtie < Rails::Railtie
+      config.action_dispatch.rescue_responses.merge!(
+        'Folio::InvalidPage' => :not_found
+      )
+
+      initializer "folio" do |app|
+        ActiveSupport.on_load :active_record do
+          require 'folio/will_paginate/active_record'
+        end
+
+        ActiveSupport.on_load :action_view do
+          require 'folio/will_paginate/view_helpers/action_view'
+        end
+
+        # don't need early access to our stuff, but will_paginate loaded
+        # theirs, so we better patch it up now rather than later
+        require 'folio/will_paginate/view_helpers'
+      end
+    end
+  end
+end

data/lib/folio/version.rb

@@ -0,0 +1,3 @@
+module Folio
+  VERSION = "0.0.2"
+end