leaflet 0.0.1

data/README.md

@@ -0,0 +1,37 @@
+# Leaflet
+
+A very robust light-weight paginator based on [leaf](http://github.com/c7/leaf) which is based on [will_paginate](http://github.com/mislav/will_paginate).
+
+# Design principles
+
+* Does not fiddle with Array, ActiveRecord, or anything else. It is self-contained.
+* Compatible with both [will_paginate](http://github.com/mislav/will_paginate) and [kaminari](http://github.com/amatsuda/kaminari) API.
+* Never raise an exception! Negative pages will simple become positive, out of bounds simple means to the last page, etc...
+
+# Features
+
+* Convert an Array into a Collection
+* Create a partial Collection from any data subset (something [like this](http://wiseleyb.tumblr.com/post/2896145167/willpaginate-with-redis-on-rails-3))
+* Export as JSON for transferring the collection over an API
+
+# Installation
+
+```ruby
+gem install leaflet
+```
+
+# Examples
+
+```ruby
+# Converting an Array into a paginatable Collection
+complete_collection = Leafet::Collection.new my_array
+complete_collection.paginate(page: 5, per_page: 3)    # <-- Returns an Array with the paginated subset of the original Array
+
+# Creating a custom Collection
+my_array_subset = [:d, :e, :f]  # E.g. fetched from Redis according to page and per_page
+collection = Leafet::Collection.new my_array_subset, total: 26, page:2, per_page: 3
+```
+
+# Credits
+
+Leaflet is based on [leaf](http://github.com/c7/leaf) (by Peter Hellberg) which is based on [will_paginate](http://github.com/mislav/will_paginate) by PJ Hyett, who later handed over development to Mislav Marohnić.

data/lib/leaflet/collection.rb

@@ -0,0 +1,124 @@
+require 'leaflet/configuration'
+
+module Leaflet
+  class Collection < Array
+
+    PartialCollectionCannotBePaginated = Class.new(StandardError)
+
+    # ––––––––––––––
+    # Initialization
+    # ––––––––––––––
+
+    def initialize(*args)
+      if args.size == 1
+        # An Array was passed in. "Convert" it to a Collection.
+        replace args.shift
+
+      elsif args.size == 2
+        # Someone is building a custom Paginator, let's fetch the data.
+        options = args.pop
+        records = Array(args.shift)
+        replace records
+        @current_page  = options[:page]
+        @per_page      = options[:per_page]
+        @total_entries = options[:total] || self.size
+
+      else
+        raise ArgumentError
+      end
+    end
+
+    def paginate(options = {})
+      raise PartialCollectionCannotBePaginated unless complete?
+      preliminary = self.class.new [], options.merge!(total: self.size)
+      result = self.class.new self[preliminary.offset, preliminary.per_page].to_a, options
+    end
+
+    # –––––––––––––––––––––––
+    # Public Instance Getters
+    # –––––––––––––––––––––––
+
+    def total_entries
+      Leaflet.positify {
+        @total_entries ||= self.size
+      }
+    end
+    alias :total_count :total_entries  # Kaminari
+
+    def per_page
+      Leaflet.positify(max: Leaflet.config.max_per_page) {
+        @per_page ||= Leaflet.config.default_per_page
+      }
+    end
+    alias :limit_value :per_page  # Kaminari
+
+    def current_page
+      Leaflet.positify(max: total_pages) {
+        @current_page ||= 1
+      }
+    end
+
+    # ––––––––––––––––––––
+    # Public Class Getters
+    # ––––––––––––––––––––
+
+    def offset
+      (current_page - 1) * per_page
+    end
+    alias :offset_value :offset  # Kaminari
+
+    def total_pages
+      Leaflet.positify {
+        total_entries.zero? ? 1 : (total_entries / per_page.to_f).ceil
+      }
+    end
+
+    def inspect
+      result = ['#<Collection with']
+      result << (complete? ? "#{self.size} records" : "#{self.size}/#{total_entries} records")
+      result << "on page #{current_page}/#{total_pages} (#{per_page} per page): #{self.to_a}>"
+      result.join(' ')
+    end
+
+    def previous_page
+      current_page > 1 ? (current_page - 1) : nil
+    end
+
+    def next_page
+      current_page < total_pages ? (current_page + 1) : nil
+    end
+
+    def first_page?
+      current_page == 1
+    end
+
+    def last_page?
+      current_page == total_pages
+    end
+
+    def as_json(options = {})
+      { 
+        total_entries: total_entries,
+        total_count: total_count,
+        per_page: per_page,
+        limit_value: limit_value,
+        current_page: current_page,
+        offset: offset,
+        offset_value: offset_value,
+        otal_pages: total_pages,
+        records: self.to_a
+      }
+    end
+
+    private
+
+    # ––––––––––––––––––––––
+    # Internal Class Getters
+    # ––––––––––––––––––––––
+
+    def complete?
+      self.size == total_entries
+    end
+
+  end
+end

data/lib/leaflet/configuration.rb

@@ -0,0 +1,42 @@
+require 'logger'
+
+module Leaflet
+  class Configuration
+
+    attr_writer :default_per_page, :max_per_page
+
+    def default_per_page
+      Leaflet.positify {
+        @default_per_page ||= 20
+      }
+    end
+
+    def max_per_page
+      Leaflet.positify {
+        @max_per_page ||= 30
+      }
+    end
+
+  end
+end
+
+module Leaflet
+
+  # Public: Returns the the configuration instance.
+  #
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Public: Yields the configuration instance.
+  #
+  def self.configure(&block)
+    yield config
+  end
+
+  # Public: Reset the configuration (useful for testing)
+  #
+  def self.reset!
+    @config = nil
+  end
+end

data/lib/leaflet/version.rb

@@ -0,0 +1,9 @@
+module Leaflet
+  module VERSION
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/leaflet.rb

@@ -0,0 +1,35 @@
+require 'leaflet/configuration'
+require 'leaflet/collection'
+require 'leaflet/version'
+
+module Leaflet
+
+  def self.positify(*args, &block)
+    if block_given?
+      raise(ArgumentError, "You can only pass in one options Hash in block mode, not #{args.inspect}") if args.size > 1
+      object  = block.call
+      options = args.shift || {}
+    else
+      case args.size
+      when 1
+        object  = args.shift
+        options = {}
+        raise(ArgumentError, "You forgot the brackets in your call. Try: Leaflet.positify(...) do") if object.is_a?(Hash)
+      when 2
+        object  = args.shift
+        options = args.shift
+      else
+        raise ArgumentError, "You must pass in an object and may pass in an options Hash, not #{args.inspect}"
+      end
+    end
+
+    options[:max] = positify(options[:max]) if options[:max]
+
+    return 1 unless object.respond_to?(:to_i)
+    result = object.to_i.abs > 0 ? object.to_i.abs : 1
+    result = options[:max] if options[:max] && options[:max] < result
+    result
+  end
+
+end
+

data/spec/lib/leaflet/collection_spec.rb

@@ -0,0 +1,97 @@
+require 'spec_helper'
+
+describe Leaflet::Collection do
+  let(:array) { ('a'..'e').to_a }
+
+  context 'converting an Array into a Collection' do
+    let(:collection) { Leaflet::Collection.new(array) }
+
+    describe '#current_page' do
+      it 'is the passed in parameter' do
+        collection.current_page.should == 1
+      end
+
+      it 'never gets out of bounds' do
+        collection = Leaflet::Collection.new(array, page: 99, per_page: 2)
+        collection.current_page.should == 3
+      end
+    end
+
+    describe '#per_page' do
+      it 'is the default per_page' do
+        collection.per_page.should == 20
+      end
+    end
+
+    describe '#limit_value ' do
+      it 'is an alias for per_page' do
+        collection.per_page.should == collection.per_page
+      end
+    end
+
+    describe '#total_entries' do
+      it 'corresponds to the records size' do
+        collection.total_entries.should == 5
+      end
+    end
+
+    describe '#total_count' do
+      it 'is an alias for #total_entries' do
+        collection.total_count.should == collection.total_entries
+      end
+    end
+
+    describe '#paginate' do
+      it 'returns a subset of original collection' do
+        collection.paginate(page: 1, per_page: 3).should == %w{ a b c }
+      end
+
+      it 'can be shorter than per_page if on last page' do
+        collection.paginate(page: 2, per_page: 3).should == %w{ d e }
+      end
+
+      it 'includes whole collection if per_page permits' do
+        collection.paginate(page: 1, per_page: 5).should == collection
+      end
+
+      it 'never gets out of bounds' do
+        collection.paginate(page: 4, per_page: 2).should == %w{ e }
+      end
+    end
+  end
+
+  context 'custom Collection' do
+    let(:collection) { Leaflet::Collection.new(array, total: 40, per_page: 4, page: 4) }
+
+    describe '#total_entries' do
+      it 'is the passed in parameter' do
+        collection.total_entries.should == 40
+      end
+    end
+
+    describe '#total_pages' do
+      it 'is calculated from the passed in total' do
+        collection.total_pages.should == 10
+      end
+    end
+
+    describe '#per_page' do
+      it 'is calculated from the passed in total' do
+        collection.per_page.should == 4
+      end
+    end
+
+    describe '#current_page' do
+      it 'is the passed in parameter' do
+        collection.current_page.should == 4
+      end
+    end
+
+    describe '#paginate' do
+      it 'is not possible on a non-complete collection' do
+        expect { collection.paginate }.to raise_exception(Leaflet::Collection::PartialCollectionCannotBePaginated)
+      end
+    end
+  end
+
+end

data/spec/lib/leaflet_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+describe Leaflet do
+
+  describe '.positify' do
+    it 'makes negative numbers positive' do
+      Leaflet.positify(-5).should == 5
+    end
+
+    it 'turns 0 to 1' do
+      Leaflet.positify(0).should == 1
+    end
+
+    it 'returns 1 on non Fixnumerable objects' do
+      Leaflet.positify(OpenStruct.new).should == 1
+    end
+
+    it 'chops Floats to Fixnums' do
+      Leaflet.positify(5.9).should == 5
+    end
+
+    it 'sets a ceiling' do
+      Leaflet.positify(30, max: 22).should == 22
+    end
+
+    it 'ignores the ceiling if the value is below it ' do
+      Leaflet.positify(30, max: 35).should == 30
+    end
+
+    context 'block mode' do
+      it 'makes negative numbers positive' do
+        Leaflet.positify { -5 }.should == 5
+      end
+
+      it 'sets a ceiling' do
+        Leaflet.positify(max: 25) { 30 }.should == 25
+      end
+
+      it 'ignores the ceiling if the value is below it ' do
+        Leaflet.positify(max: 35) { 30 }.should == 30
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'leaflet'

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: leaflet
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- bukowskis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A very robust, custom, light-weight paginator. Based on the leaf gem
+  which is based on the will_paginate gem.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/leaflet/collection.rb
+- lib/leaflet/configuration.rb
+- lib/leaflet/version.rb
+- lib/leaflet.rb
+- spec/lib/leaflet/collection_spec.rb
+- spec/lib/leaflet_spec.rb
+- spec/spec_helper.rb
+- README.md
+homepage: https://github.com/bukowskis/leaflet
+licenses:
+- MIT
+post_install_message: 
+rdoc_options:
+- --encoding
+- UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A very robust, custom, light-weight paginator.
+test_files: []