pagy 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60384daf0fd49d4815f49d4ab0bf65840835bb42f7c9c38979fae883f9e0c4c5
-  data.tar.gz: 4aaa58eba02a590254ecf82d80f750aa4cd0b3bf7da1d745f92d8a7125c19fc9
+  metadata.gz: a984f9eb44e5f2d637f92e5b5317edbff0691c2b2d4e89d8bf02f2e1a11939b8
+  data.tar.gz: 01dc6a1f9ca9bba43400f00a645a47c02cf4aa11868705193a9b4c33a50e1811
 SHA512:
-  metadata.gz: 3006bd929cce65f58b5d0fd4c512e791fc939de6661055359c918f035f981645ce705d3d5e02f55aa7c43816d309000ee10991c54b89144768f986f6e6f18c0d
-  data.tar.gz: 4ad8a43b6138a671e84e074155e60f80713cd68a41f71fab6ac69d5a88bc5a48fbac0b49cb0a9b50e6c15b416c72373ceafe01e9bc841f9fe2b72965deb9dfaa
+  metadata.gz: b2ed0782436c442bb3127598cb1f8b8aaeb7afaf373836933e61a93b834bc91125a1f44fb34fad18b362a989c59b2c1ba3683483cf2098b36657be75420f3fc3
+  data.tar.gz: e7399e4568cf8fbfa537a4a193c928d0810ce47ea4d5c877765d5669d077618e7ab1e715d9892c7bf51e8e827a06b897afef12d417c2994f7be6f65c69cd7fe1

data/README.md

@@ -1,30 +1,92 @@
 # Pagy
 
-Dead simple pagination in pure ruby. Easy, fast and very light. No restrictions imposed: use it with any MVC framework, any ORM, any DB type, any templating system or none at all. Use the built-in templates or create yours the way you want.
+Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison. 
 
-## Alpha Version!
+### Benchmarks
 
-This gem is still missing documentation. TBD... soon ;).
+The best way to quickly get an idea about its features is comparing it to the other well known gems.
 
-## Installation
+The values shown in the charts below have been recorded while each gem was producing the exact same output: same environment conditions, same task, just different gems _(see the complete [Gems Comparison](http://ddnexus.github.io/pagination-comparison/gems.html))_
 
-Add this line to your application's Gemfile:
+#### Pagy is a lot faster
+
+![IPS Chart](images/ips-chart.png)
+
+#### Pagy uses a lot less memory
+
+![Memory Chart](images/memory-chart.png)
+
+#### Pagy is a lot simpler
+
+![Objects Chart](images/objects-chart.png)
+
+#### Pagy is a lot more efficient
+
+![Efficiency Table](images/efficiency-table.png)
+
+_The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#efficiency-ratio) is calculated out of speed (IPS) and Memory (Kb): it shows how well each gem uses any Kb of memory it allocates/consumes._ 
+
+#### Pagy does not suffer the typical limitations of the other gems:
+
+- it works with collections/scopes that already used `limit` and `offset`
+- it works with both helpers or templates (your choice)
+- it raises real `Pagy::OutOfRangeError` exceptions that you can rescue from
+- it does not impose any difficult-to-override logic or output
+
+### Features
+
+#### Straightforward code
+
+- Pagy is just ~120 lines of simple ruby, organized in 3 flat modules very easy to understand and use
+- it produces its own HTML, URLs, pluralization and interpolation with its own specialized and fast code
+- 100% of its methods are public API, accessible and overridable **right where you use them** (no need of monkey patching or subclassing)
+
+#### Totally agnostic
+
+- it doesn't need to know anything about your models, ORM or Storage, so it doesn't add any code to them
+- it works with all kind of collections, even pre-paginated, records, Arrays, JSON data... and just whatever you can count
+- it works with all Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box 
+- it works with any possible non-Rack envoronment by just overriding one or two one-liner methods
+
+#### Simple Usage
+
+You can use pagy in a quite familiar way: 
+
+Paginate your collection in some controller:
 
 ```ruby
-gem 'pagy'
+@pagy, @records = pagy(Product.some_scope)
+```
+
+Render the navigation links with a super-fast helper in some view:
+
+```HTML+ERB
+<%= pagy_nav(@pagy) %>
+```
+
+Or - if you prefer - render the navigation links with a template:
+
+```HTML+ERB
+<%= render 'pagy/nav', locals: {pagy: @pagy} %>
 ```
 
-And then execute:
+## Support, Comments and Feature Requests
+
+[![Join the chat at https://gitter.im/ruby-pagy/Lobby](https://badges.gitter.im/ruby-pagy/Lobby.svg)](https://gitter.im/ruby-pagy/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-    $ bundle
+## Useful Links
 
-Or install it yourself as:
+- [Documentation](https://ddnexus.github.io/pagy/index)
+- [Pagination Comparison App](http://github.com/ddnexus/pagination-comparison)
 
-    $ gem install pagy
+## Help Wanted
 
-## Contributing
+Pagy is a fresh project and your help would be great. If you like it, you have a few options to contribute:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ddnexus/pagy.
+- write a tutorial or a post or even just a tweet (pagy is young and needs to be known)
+- write a "How To" topic (the documentation is covering the basics and there is a lot of space for additions)
+- submit a pull request to make pagy even faster, save more memory or improve its usability
+- create an issue if anything should be improved/fixed
 
 ## License
 

data/lib/locales/pagy.yml

@@ -1,17 +1,10 @@
-# Pagy uses an internal I18n-like :pagy_t helper that lookup
-# into this file at Pagy.root.join('locale', 'pagy.yml')
-# If you want to customize it you should set:
-# Pagy::Opts.i18n_file = 'path/to/your/file.yaml'
-
-# If you need to use this method with pluralization different than english
-# (i.e. not 'zero', 'one', 'other' plurals) then you should define the
-# Pagy::Opts.i18n_plurals proc to return the plural key based on the passed count.
+# Standard pagy dictionary
 
 en:
   pagy:
     nav:
-      prev: "‹ Prev"
-      next: "Next ›"
+      prev: "‹ Prev"
+      next: "Next ›"
       gap: "…"
     info:
       single_page:
@@ -19,7 +12,7 @@ en:
         one: "Displaying <b>1</b> %{item_name}"
         other: "Displaying <b>all %{count}</b> %{item_name}"
       multiple_pages: "Displaying %{item_name} <b>%{from}-%{to}</b> of <b>%{count}</b> in total"
-      item:
+      item_name:
         zero: "items"
         one: "item"
         other: "items"

data/lib/pagy.rb

@@ -1,61 +1,57 @@
-require 'pathname'
-require 'ostruct'
+# See Pagy API documentation: https://ddnexus.github.io/pagy/api/pagy
 
-# This class takes a few integers (such as collection-count, page-number,
-# items-per-page-limit, etc.), does some simple aritmetic and creates a very
-# small object (~3k) with all is needed for pagination and navigation.
-# Notice that it doesn't actually do any pagination, nor navigation... that is
-# done with a few helpers in the Pagy::Backend and Pagy::Frontend modules.
+require 'pathname'
 
-class Pagy ; VERSION = '0.4.2'
+class Pagy ; VERSION = '0.5.0'
 
   autoload :Backend,  'pagy/backend'
   autoload :Frontend, 'pagy/frontend'
 
   class OutOfRangeError < StandardError; end
 
-  # root pathname to get the path of pagy files like templates or locales
+  # root pathname to get the path of pagy files like templates or dictionaries
   def self.root; Pathname.new(__FILE__).dirname end
 
-  # default options
-  # limit:         max items per page: it gets adjusted for the last page,
-  #                so it will pull the right items if the collection was pre-limit(ed)
-  # offset:        the initial offset of the whole collection before pagination
-  #                set it only if the collection was pre-offset(ted): it gets added to the final offset
-  # initial/final: max pages to show from the first/last page
-  # before/after:  max pages before/after the current page
-  Opts = OpenStruct.new(limit:20, offset:0, initial:1, before:4, after:4, final:1)
+  # default core vars
+  VARS = { items:20, outset:0, initial:1, before:4, after:4, final:1 }
+
+  # default I18n vars
+  I18N = { file: Pagy.root.join('locales', 'pagy.yml').to_s, plurals: -> (c) {c==0 && 'zero' || c==1 && 'one' || 'other'} }
 
-  attr_reader :count, :page, :limit, :opts, :pages, :last, :offset, :from, :to, :prev, :next, :series
+
+  attr_reader :count, :page, :items, :vars, :pages, :last, :offset, :from, :to, :prev, :next
 
   # merge and validate the options, do some simple aritmetic and set the instance variables
-  def initialize(opts)
-    @opts        = Opts.to_h.merge!(opts)                                 # global opts + instance opts (bang faster)
-    @opts[:page] = (@opts[:page]||1).to_i                                 # set page to 1 if nil
-    [:count, :limit, :offset, :initial, :before, :page, :after, :final].each do |k|
-      @opts[k] >= 0 rescue nil || raise(ArgumentError, "expected #{k} >= 0; got #{@opts[k].inspect}")
-      instance_variable_set(:"@#{k}", @opts.delete(k))                    # set all the metrics variables
+  def initialize(vars)
+    @vars        = VARS.merge(vars)                                       # default vars + instance vars
+    @vars[:page] = (@vars[:page]||1).to_i                                 # set page to 1 if nil
+    {count:0, items:1, outset:0, initial:0, before:0, page:1, after:0, final:0}.each do |k,min|
+      @vars[k] >= min rescue nil || raise(ArgumentError, "expected :#{k} >= #{min}; got #{@vars[k].inspect}")
+      instance_variable_set(:"@#{k}", @vars.delete(k))                    # set all the core variables
     end
-    @pages   = @last = [(@count.to_f / @limit).ceil, 1].max               # cardinal and ordinal meanings
+    @pages  = @last = [(@count.to_f / @items).ceil, 1].max                # cardinal and ordinal meanings
     (1..@last).cover?(@page) || raise(OutOfRangeError, "expected :page in 1..#{@last}; got #{@page.inspect}")
-    @offset += @limit * (@page - 1)                                       # initial offset + offset for pagination
-    @limit   = @count % @limit if @page == @last                          # adjust limit for last page (for pre-limit(ed) collections)
-    @from    = @count == 0 ? 0 : @offset+1                                # page begins from item
-    @to      = @offset + @limit                                           # page ends to item
-    @prev    = (@page-1 unless @page == 1)                                # nil if no prev page
-    @next    = (@page+1 unless @page == @last)                            # nil if no next page
-    @series  = []                                                         # e.g. [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-    all      = (0..@last+1)                                               # page range with boundaries
-    around   = ([@page-@before, 1].max .. [@page+@after, @last].min).to_a # before..after pages
-    row      = (all.first(@initial+1) | around | all.last(@final+1)).sort # row of pages with boundaries
-    row.each_cons(2) do |a, b|                                            # loop in consecutive pairs
-      if    a+1 == b ; @series.push(a)                                    # no gap     -> no additions
-      elsif a+2 == b ; @series.push(a, a+1)                               # 1 page gap -> fill with missing page
-      else             @series.push(a, :gap)                              # n page gap -> add :gap
-      end                                                                 # skip the end-boundary (last+1)
+    @offset = @items * (@page - 1) + @outset                              # pagination offset + outset (initial offset)
+    @items  = @count % @items if @page == @last                           # adjust items for last page
+    @from   = @count == 0 ? 0 : @offset+1 - @outset                       # page begins from item
+    @to     = @offset + @items - @outset                                  # page ends to item
+    @prev   = (@page-1 unless @page == 1)                                 # nil if no prev page
+    @next   = (@page+1 unless @page == @last)                             # nil if no next page
+  end
+
+  # return the array of page numbers and :gap items e.g. [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+  def series
+    @series ||= [].tap do |series|
+      [*0..@initial, *@page-@before..@page+@after, *@last-@final+1..@last+1].sort!.each_cons(2) do |a, b|
+        if    a<0 || a==b || a>@last                                      # skip out of range and duplicates
+        elsif a+1 == b; series.push(a)                                    # no gap     -> no additions
+        elsif a+2 == b; series.push(a, a+1)                               # 1 page gap -> fill with missing page
+        else            series.push(a, :gap)                              # n page gap -> add :gap
+        end                                                               # skip the end boundary (last+1)
+      end
+      series.shift                                                        # remove the start boundary (0)
+      series[series.index(@page)] = @page.to_s                            # convert the current page to String
     end
-    @series.shift                                                         # remove the start-boundary (0)
-    @series[@series.index(@page)] = @page.to_s                            # convert the current page to String
   end
 
 end

data/lib/pagy/backend.rb

@@ -1,42 +1,24 @@
-class Pagy
-
-  # Including this module (usually in your controller) is handy but totally optional.
-  # It basically just encapsulates a couple of verbose statements in one single slick
-  # #pagy method, but it does not add any functionality on its own.
-  #
-  # Using the module allows you to have a predefined method and a few sub-methods
-  # (i.e. methods called only by the predefined method) handy if you need to override
-  # some aspect of the predefined #pagy method.
-  #
-  # However, you can just explicitly write your own pagy method in just a couple of
-  # lines, specially if you need to override two or more methods. For example:
-  #
-  # def pagy(scope, opts={})
-  #   pagy = Pagy.new scope.count, page: params[:page], **opts
-  #   return pagy, scope.offset(pagy.offset).limit(pagy.limit)
-  # end
+# See Pagy::Backend API documentation: https://ddnexus.github.io/pagy/api/backend
 
+class Pagy
   module Backend ; private         # the whole module is private so no problem with including it in a controller
 
-    def pagy(obj, opts={})
-      pagy = Pagy.new(count: pagy_get_count(obj), page: pagy_get_page, i18n_key: pagy_get_i18n_key(obj), **opts)
-      return pagy, pagy_get_items(obj, pagy)
+    # return pagy object and items
+    def pagy(collection, vars=nil)
+      pagy = Pagy.new(vars ? pagy_get_vars(collection).merge!(vars) : pagy_get_vars(collection))   # conditional merge is faster and saves memory
+      return pagy, pagy_get_items(collection, pagy)
     end
 
-    def pagy_get_count(obj)
-      obj.count
+    # sub-method called only by #pagy: here for easy customization of variables by overriding
+    def pagy_get_vars(collection)
+      # return the variables to initialize the pagy object
+      { count: collection.count, page: params[:page] }
     end
 
-    def pagy_get_page
-      params[:page]
-    end
-
-    def pagy_get_i18n_key(obj) end
-
-    # this should work with ActiveRecord, Sequel, Mongoid...
-    # override it if obj does not implement it that way
-    def pagy_get_items(obj, pagy)
-      obj.offset(pagy.offset).limit(pagy.limit)
+    # sub-method called only by #pagy: here for easy customization of record-extraction by overriding
+    def pagy_get_items(collection, pagy)
+      # this should work with ActiveRecord, Sequel, Mongoid...
+      collection.offset(pagy.offset).limit(pagy.items)
     end
 
   end

data/lib/pagy/frontend.rb

@@ -1,165 +1,100 @@
+# See Pagy::Frontend API documentation: https://ddnexus.github.io/pagy/api/frontend
+
+# this file will get autoloaded, so environment constants like ::I18n will be already set
 require 'yaml'
 class Pagy
 
-  # This module supplies a few methods to deal with the navigation aspect of the pagination.
-  # You will usually include it in some helper module, eventually overriding the #pagy_url_for
-  # in order to fit its behavior with your app needs (e.g.: removing and adding some param or
-  # allowing fancy routes, etc.)
-  #
   # All the code here has been optimized for performance: it may not look very pretty
   # (as most code dealing with many long strings), but its performance makes it very sexy! ;)
   module Frontend
 
     # Generic pagination: it returns the html with the series of links to the pages
-    def pagy_nav(pagy, opts=nil)
-      opts = opts ? pagy.opts.merge(opts) : pagy.opts
-      link = pagy_link_proc(pagy)
-      tags = []
+    def pagy_nav(pagy)
+      tags = []; link = pagy_link_proc(pagy)
 
       tags << (pagy.prev ? %(<span class="page prev">#{link.call pagy.prev, pagy_t('pagy.nav.prev'.freeze), 'aria-label="previous"'.freeze}</span>)
                          : %(<span class="page prev disabled">#{pagy_t('pagy.nav.prev'.freeze)}</span>))
       pagy.series.each do |item|  # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-        tags << case item
-                  when Integer; %(<span class="page">#{link.call item}</span>)                    # page link
-                  when String ; %(<span class="page active">#{item}</span>)                       # current page
-                  when :gap   ; %(<span class="page gap">#{pagy_t('pagy.nav.gap'.freeze)}</span>) # page gap
+        tags << if    item.is_a?(Integer); %(<span class="page">#{link.call item}</span>)                    # page link
+                elsif item.is_a?(String) ; %(<span class="page active">#{item}</span>)                       # current page
+                elsif item == :gap       ; %(<span class="page gap">#{pagy_t('pagy.nav.gap'.freeze)}</span>) # page gap
                 end
       end
       tags << (pagy.next ? %(<span class="page next">#{link.call pagy.next, pagy_t('pagy.nav.next'.freeze), 'aria-label="next"'.freeze}</span>)
                          : %(<span class="page next disabled">#{pagy_t('pagy.nav.next'.freeze)}</span>))
-      %(<nav class="#{opts[:class]||'pagination'.freeze}" role="navigation" aria-label="pager">#{tags.join(opts[:separator]||' '.freeze)}</nav>)
+      %(<nav class="pagination" role="navigation" aria-label="pager">#{tags.join(' '.freeze)}</nav>)
     end
 
 
     # Pagination for bootstrap: it returns the html with the series of links to the pages
-    def pagy_nav_bootstrap(pagy, opts=nil)
-      opts = opts ? pagy.opts.merge(opts) : pagy.opts
-      link = pagy_link_proc(pagy, 'class="page-link"'.freeze)
-      tags = []
+    def pagy_nav_bootstrap(pagy)
+      tags = []; link = pagy_link_proc(pagy, 'class="page-link"'.freeze)
 
       tags << (pagy.prev ? %(<li class="page-item prev">#{link.call pagy.prev, pagy_t('pagy.nav.prev'.freeze), 'aria-label="previous"'.freeze}</li>)
                          : %(<li class="page-item prev disabled"><a href="#" class="page-link">#{pagy_t('pagy.nav.prev'.freeze)}</a></li>))
       pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-        tags << case item
-                  when Integer; %(<li class="page-item">#{link.call item}</li>)                                                               # page link
-                  when String ; %(<li class="page-item active">#{link.call item}</li>)                                                        # active page
-                  when :gap   ; %(<li class="page-item gap disabled"><a href="#" class="page-link">#{pagy_t('pagy.nav.gap'.freeze)}</a></li>) # page gap
+        tags << if    item.is_a?(Integer); %(<li class="page-item">#{link.call item}</li>)                                                               # page link
+                elsif item.is_a?(String) ; %(<li class="page-item active">#{link.call item}</li>)                                                        # active page
+                elsif item == :gap       ; %(<li class="page-item gap disabled"><a href="#" class="page-link">#{pagy_t('pagy.nav.gap'.freeze)}</a></li>) # page gap
                 end
       end
       tags << (pagy.next ? %(<li class="page-item next">#{link.call pagy.next, pagy_t('pagy.nav.next'.freeze), 'aria-label="next"'.freeze}</li>)
                          : %(<li class="page-item next disabled"><a href="#" class="page-link">#{pagy_t('pagy.nav.next'.freeze)}</a></li>))
-      %(<nav class="#{opts[:class]||'pagination'.freeze}" role="navigation" aria-label="pager"><ul class="pagination">#{tags.join}</ul></nav>)
+      %(<nav class="pagination" role="navigation" aria-label="pager"><ul class="pagination">#{tags.join}</ul></nav>)
     end
 
 
     # return examples: "Displaying items 41-60 of 324 in total"  or "Displaying Products 41-60 of 324 in total"
-    def pagy_info(pagy, vars=nil)
-      name = vars && vars[:item_name] || pagy_t(pagy.opts[:i18n_key] || 'pagy.info.item'.freeze, count: pagy.count)
-      name = pagy_t('pagy.info.item'.freeze, count: pagy.count) if name.start_with?('translation missing:'.freeze)
+    def pagy_info(pagy)
+      name = pagy_t(pagy.vars[:item_path] || 'pagy.info.item_name'.freeze, count: pagy.count)
       key  = pagy.pages == 1 ? 'single_page'.freeze : 'multiple_pages'.freeze
-      pagy_t "pagy.info.#{key}", item_name: name, count: pagy.count, from: pagy.from, to: pagy.to
+      pagy_t("pagy.info.#{key}", item_name: name, count: pagy.count, from: pagy.from, to: pagy.to)
     end
 
 
     # this works with all Rack-based frameworks (Sinatra, Padrino, Rails, ...)
     def pagy_url_for(n)
       url    = File.join(request.script_name.to_s, request.path_info)
-      params = request.GET.merge('page' => n.to_s)
-      url << '?' << Rack::Utils.build_nested_query(params)
+      params = request.GET.merge('page'.freeze => n.to_s)
+      url << '?' << Rack::Utils.build_nested_query(pagy_get_params(params))
     end
 
 
-    # The :pagy_t method is the internal implementation of I18n.t, used when I18n is missing or
-    # not needed (for example when your application is a single-locale app, e.g. only 'en', or only 'fr'...).
-    #
-    # It implements only the very basic functionality of the I18n.t method
-    # but it's still good enough for the limited Pagy's needs and it is faster.
-    #
-    # You can still use this method with a pluralization different than English
-    # (i.e. not 'zero', 'one', 'other' plurals). In that case you should define the
-    # Pagy::Opts.i18n_plurals proc to return the plural key based on the passed count.
-    #
-    # If you need full I18n functionality, you should override this method with something like:
-    #    def pagy_t(*a); I18n.t(*a) end
-    # and add your translations to the I18n usual locales files
-
-    hash = YAML.load_file Opts.i18n_file || Pagy.root.join('locales', 'pagy.yml')
-    I18N = hash[hash.keys.first].freeze
-
-    # Similar to I18n.t for interpolation and pluralization, with the following constraints:
-    # - the path/keys option is supported only in dot-separated string or symbol format
-    # - the :scope and :default options are not supported
-    # - no exception are raised: the errors are returned as translated strings
-    def pagy_t(path, vars={})
-      value = I18N.dig(*path.to_s.split('.'.freeze))
-      if value.is_a?(Hash)
-        vars.has_key?(:count) or return value
-        plural = (Opts.i18n_plurals ||= -> (c) {c==0 && 'zero' || c==1 && 'one' || 'other'}).call(vars[:count])
-        value.has_key?(plural) or return %(invalid pluralization data: "#{path}" cannot be used with count: #{vars[:count]}; key "#{plural}" is missing.)
-        value = value[plural]
-      end
-      value or return %(translation missing: "#{path}")
-      sprintf value, Hash.new{|h,k| "%{#{k}}"}.merge!(vars)    # interpolation
-    end
-
+    # sub-method called only by #pagy_url_for: here for easy customization of params by overriding
+    def pagy_get_params(p) p end
 
-    # NOTICE: This method is used internally, so you need to know about it only if you
-    # are going to override a *_nav helper or a template AND change the link tags.
-    #
-    # You call this method in order to get a proc that you will call to produce the page links.
-    # The reasaon it is a 2 step process instead of a single method call is performance.
-    #
-    # Call the method to get the proc (once):
-    #   link = pagy_link_proc( pagy [, extra_attributes_string ])
-    #
-    # Call the proc to get the links (multiple times):
-    #   link.call( page_number [, label [, extra_attributes_string ]])
-    #
-    # You can pass extra attribute strings to get inserted in the link tags at many different levels.
-    # Depending by the scope you want your attributes to be added, (from wide to narrow) you can:
-    #
-    # 1. For all pagy objects: set the global option :link_extra:
-    #
-    #     Pagy::Opts.extra_link = 'data-remote="true"'
-    #     link.call(page_number=2)
-    #     #=> <a href="...?page=2" data-remote="true">2</a>
-    #
-    # 2. For one pagy object: pass a :link_extra option to a pagy constructor (Pagy.new or pagy controller method):
-    #
-    #     @pagy, @records = pagy(my_scope, extra_link: 'data-remote="true"')
-    #     link.call(page_number)
-    #     #=> <a href="...?page=2" data-remote="true">2</a>
-    #
-    # 3. For one pagy_nav render: pass a :link_extra option to a *_nav method:
-    #
-    #      pagy_nav(@pagy,  extra_link: 'data-remote="true"')   #
-    #      link.call(page_number)
-    #      #=> <a href="...?page=2" data-remote="true">2</a>
-    #
-    # 4. For all the calls to the returned pagy_link_proc: pass an extra attributes string when you get the proc:
-    #
-    #      link = pagy_link_proc(pagy, 'class="page-link"')
-    #      link.call(page_number)
-    #      #=> <a href="...?page=2" data-remote="true" class="page-link">2</a>
-    #
-    # 5. For a single link.call: pass an extra attributes string  when you call the proc:
-    #
-    #      link.call(page_number, 'aria-label="my-label"')
-    #      #=> <a href="...?page=2" data-remote="true" class="page-link" aria-label="my-label">2</a>
-    #
-    # WARNING: since we use only strings for performance, the attribute strings get concatenated, not merged!
-    # Be careful not to pass the same attribute at different levels multiple times. That would generate a duplicated
-    # attribute which is illegal html (although handled by all mayor browsers by ignoring all the duplicates but the first)
 
     MARKER = "-pagy-#{'pagy'.hash}-".freeze
 
-    def pagy_link_proc(pagy, lx=''.freeze)  # link extra
-      p_prev, p_next, p_lx = pagy.prev, pagy.next, pagy.opts[:link_extra]
+    # returns a specialized proc to generate the HTML links
+    def pagy_link_proc(pagy, lx=''.freeze)  # "lx" means "link extra"
+      p_prev, p_next, p_lx = pagy.prev, pagy.next, pagy.vars[:link_extra]
       a, b = %(<a href="#{pagy_url_for(MARKER)}"#{p_lx ? %( #{p_lx}) : ''.freeze}#{lx.empty? ? lx : %( #{lx})}).split(MARKER)
       -> (n, text=n, x=''.freeze) { "#{a}#{n}#{b}#{ if    n == p_prev ; ' rel="prev"'.freeze
                                                     elsif n == p_next ; ' rel="next"'.freeze
-                                                    else                           ''.freeze
-                                                    end }#{x.empty? ? x : %( #{x})}>#{text}</a>" }
+                                                    else                           ''.freeze end }#{x.empty? ? x : %( #{x})}>#{text}</a>" }
+    end
+
+
+    # define #pagy_t depending on I18N[:gem] and I18n
+    if I18N[:gem] || I18N[:gem].nil? && defined?(I18n)
+      I18n.load_path << I18N[:file]
+      def pagy_t(*a); I18n.t(*a) end
+    else
+      # load data from the first locale in the file
+      I18N_DATA = YAML.load_file(I18N[:file]).first[1].freeze
+      # Similar to I18n.t for interpolation and pluralization but without translation
+      # Use only for single-language apps: it is specialized for pagy and 5x faster than I18n.t
+      def pagy_t(path, vars={})
+        value = I18N_DATA.dig(*path.to_s.split('.'.freeze)) or return %(translation missing: "#{path}")
+        if value.is_a?(Hash)
+          vars.key?(:count) or return value
+          plural = I18N[:plurals].call(vars[:count])
+          value.key?(plural) or return %(invalid pluralization data: "#{path}" cannot be used with count: #{vars[:count]}; key "#{plural}" is missing.)
+          value = value[plural] or return %(translation missing: "#{path}")
+        end
+        sprintf value, Hash.new{|h,k| "%{#{k}}"}.merge!(vars)    # interpolation
+      end
     end
 
   end

data/lib/templates/nav.html.erb

@@ -0,0 +1,22 @@
+<%#
+  This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
+  calls with the actual strings ("&lsaquo; Prev", "Next &rsaquo;", "&hellip;").
+
+  The link variable is set to a proc that returns the link tag.
+  Usage: link.call( page_number [, text [, extra_attributes_string ]])
+-%>
+<% link = pagy_link_proc(pagy) -%>
+<%#                            -%><nav aria-label="pager" class="pagination" role="navigation">
+<% if pagy.prev                -%>  <span class="page prev"><%== link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'aria-label="previous"') %></span>
+<% else                        -%>  <span class="page prev disabled"><%== pagy_t('pagy.nav.prev') %></span>
+<% end                         -%>
+<% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
+<%   if    item.is_a?(Integer) -%>  <span class="page"><%== link.call(item) %></span>
+<%   elsif item.is_a?(String)  -%>  <span class="page current"><%= item %></span>
+<%   elsif item == :gap        -%>  <span class="page gap"><%== pagy_t('pagy.nav.gap') %></span>
+<%   end                       -%>
+<% end                         -%>
+<% if pagy.next                -%>  <span class="page next"><%== link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"') %></span>
+<% else                        -%>  <span class="page next disabled"><%== pagy_t('pagy.nav.next') %></span>
+<% end                         -%>
+<%#                            -%></nav>

data/lib/templates/{default.html.haml → nav.html.haml}

@@ -13,18 +13,16 @@
   - else
     %span.page.prev.disabled!= pagy_t('pagy.nav.prev')
 
-  - pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-    - case item
+  - pagy.series.each do |item|       # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+    - if item.is_a?(Integer)         # page link
+      %span.page
+        != link.call(item)
 
-      - when Integer           # page link
-        %span.page
-          != link.call(item)
+    - elsif item.is_a?(String)       # current page
+      %span.page.current= item
 
-      - when String            # current page
-        %span.page.current= item
-
-      - when :gap              # page gap
-        %span.page.gap!= pagy_t('pagy.nav.gap')
+    - elsif item == :gap             # page gap
+      %span.page.gap!= pagy_t('pagy.nav.gap')
 
   - if pagy.next
     %span.page.next!= link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"')

data/lib/templates/{default.html.slim → nav.html.slim}

@@ -13,16 +13,15 @@ nav.pagination role="navigation" aria-label="pager"
   - else
     span.page.prev.disabled ==> pagy_t('pagy.nav.prev')
 
-  - pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-    - case item
-      - when Integer           # page link
-        span.page ==> link.call(item)
+  - pagy.series.each do |item|        # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+    - if item.is_a?(Integer)          # page link
+      span.page ==> link.call(item)
 
-      - when String            # current page
-        span.page.current ==> item
+    - elsif item.is_a?(String)        # current page
+      span.page.current ==> item
 
-      - when :gap              # page gap
-        span.page.gap ==> pagy_t('pagy.nav.gap')
+    - elsif item == :gap              # page gap
+      span.page.gap ==> pagy_t('pagy.nav.gap')
 
   - if pagy.next
     span.page.next == link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"')

data/lib/templates/nav_bootstrap.html.erb

@@ -0,0 +1,24 @@
+<%#
+  This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
+  calls with the actual strings ("&lsaquo; Prev", "Next &rsaquo;", "&hellip;").
+
+  The link variable is set to a proc that returns the link tag.
+  Usage: link.call( page_number [, text [, extra_attributes_string ]])
+-%>
+<% link = pagy_link_proc(pagy, 'class="page-link"') -%>
+<%#                            -%><nav aria-label="pager"  class="pagination" role="navigation">
+<%#                            -%>  <ul class="pagination">
+<% if pagy.prev                -%>    <li class="page-item prev"><%== link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'aria-label="previous"') %></li>
+<% else                        -%>    <li class="page-item prev disabled"><a href="#" class="page-link"><%== pagy_t('pagy.nav.prev') %></a></li>
+<% end                         -%>
+<% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
+<%   if    item.is_a?(Integer) -%>    <li class="page-item"><%== link.call(item) %></li>
+<%   elsif item.is_a?(String)  -%>    <li class="page-item active"><%== link.call(item) %></li>
+<%   elsif item == :gap        -%>    <li class="page-item disabled gap"><a href="#" class="page-link"><%== pagy_t('pagy.nav.gap') %></a></li>
+<%   end                       -%>
+<% end                         -%>
+<% if pagy.next                -%>    <li class="page-item next"><%== link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"') %></li>
+<% else                        -%>    <li class="page-item next disabled"><a href="#" class="page-link"><%== pagy_t('pagy.nav.next') %></a></li>
+<% end                         -%>
+<%#                            -%>  </ul>
+<%#                            -%></nav>

data/lib/templates/{bootstrap.html.haml → nav_bootstrap.html.haml}

@@ -16,17 +16,16 @@
       %li.page-item.prev.disabled
         %a.page-link{:href => '#'}!= pagy_t('pagy.nav.prev')
 
-    - pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-      - case item
-        - when Integer           # page link
-          %li.page-item!= link.call(item)
+    - pagy.series.each do |item|                      # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      - if item.is_a?(Integer)                        # page link
+        %li.page-item!= link.call(item)
 
-        - when String            # current page
-          %li.page-item.active!= link.call(item)
+      - elsif item.is_a?(String)                      # current page
+        %li.page-item.active!= link.call(item)
 
-        - when :gap              # page gap
-          %li.page-item.disabled.gap
-            %a.page-link{:href => "#"}!= pagy_t('pagy.nav.gap')
+      - elsif item == :gap                            # page gap
+        %li.page-item.disabled.gap
+          %a.page-link{:href => "#"}!= pagy_t('pagy.nav.gap')
 
     - if pagy.next
       %li.page-item.next!= link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"')

data/lib/templates/{bootstrap.html.slim → nav_bootstrap.html.slim}

@@ -16,18 +16,16 @@ nav.pagination role="navigation" aria-label="pager"
       li.page-item.prev.disabled
         a.page-link href="#" == pagy_t('pagy.nav.prev')
 
-    - pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
-      - case item
+    - pagy.series.each do |item|                 # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
+      - if item.is_a?(Integer)                   # page link
+        li.page-item == link.call(item)
 
-        - when Integer           # page link
-          li.page-item == link.call(item)
+      - elsif item.is_a?(String)                 # current page
+        li.page-item.active == link.call(item)
 
-        - when String            # current page
-          li.page-item.active == link.call(item)
-
-        - when :gap              # page gap
-          li.page-item.disabled.gap
-            a.page-link href="#" == pagy_t('pagy.nav.gap')
+      - elsif item == :gap                       # page gap
+        li.page-item.disabled.gap
+          a.page-link href="#" == pagy_t('pagy.nav.gap')
 
     - if pagy.next
       li.page-item.next == link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"')

data/pagy.gemspec

@@ -11,14 +11,14 @@ Gem::Specification.new do |s|
   s.email         = ['dd.nexus@gmail.com']
   s.date          = Date.today.to_s
 
-  s.summary       = %q{Because pagination should not suck!}
-  s.description   = %q{Dead simple pagination in pure ruby. Easy, fast and very light. No restrictions imposed: use it with any MVC framework, any ORM, any DB type, any templating system or none at all. Use the built-in templates or create yours the way you want.}
+  s.summary       = 'The Ultimate Pagination Ruby Gem'
+  s.description   = 'Agnostic pagination in plain ruby: it works with any framework, ORM and DB type, with all kinds of collections, even pre-paginated, scopes, Arrays, JSON data... and just whatever you can count. Easy to use and customize, very fast and very light.'
   s.homepage      = 'https://github.com/ddnexus/pagy'
   s.license       = 'MIT'
   s.require_paths = ['lib']
 
-  s.files         = `git ls-files -z`.split("\x0")
-                                     .reject{|f| f.start_with? '.', 'test', 'Gemfile', 'Rakefile' }
+  s.files         = `git ls-files -z`.split("\x0").select{|f| f.start_with?('lib', 'pagy.gemspec', 'LICENSE', 'README', 'images') }
+
 
   s.add_development_dependency 'bundler',  '~> 1.16'
   s.add_development_dependency 'rake',     '~> 10.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-19 00:00:00.000000000 Z
+date: 2018-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,9 +122,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 'Dead simple pagination in pure ruby. Easy, fast and very light. No restrictions
-  imposed: use it with any MVC framework, any ORM, any DB type, any templating system
-  or none at all. Use the built-in templates or create yours the way you want.'
+description: 'Agnostic pagination in plain ruby: it works with any framework, ORM
+  and DB type, with all kinds of collections, even pre-paginated, scopes, Arrays,
+  JSON data... and just whatever you can count. Easy to use and customize, very fast
+  and very light.'
 email:
 - dd.nexus@gmail.com
 executables: []
@@ -133,16 +134,20 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- images/efficiency-table.png
+- images/ips-chart.png
+- images/memory-chart.png
+- images/objects-chart.png
 - lib/locales/pagy.yml
 - lib/pagy.rb
 - lib/pagy/backend.rb
 - lib/pagy/frontend.rb
-- lib/templates/bootstrap.html.erb
-- lib/templates/bootstrap.html.haml
-- lib/templates/bootstrap.html.slim
-- lib/templates/default.html.erb
-- lib/templates/default.html.haml
-- lib/templates/default.html.slim
+- lib/templates/nav.html.erb
+- lib/templates/nav.html.haml
+- lib/templates/nav.html.slim
+- lib/templates/nav_bootstrap.html.erb
+- lib/templates/nav_bootstrap.html.haml
+- lib/templates/nav_bootstrap.html.slim
 - pagy.gemspec
 homepage: https://github.com/ddnexus/pagy
 licenses:
@@ -167,5 +172,5 @@ rubyforge_project:
 rubygems_version: 2.7.4
 signing_key: 
 specification_version: 4
-summary: Because pagination should not suck!
+summary: The Ultimate Pagination Ruby Gem
 test_files: []

data/lib/templates/bootstrap.html.erb

@@ -1,28 +0,0 @@
-<%#
-  This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
-  calls with the actual strings ("&lsaquo; Prev", "Next &rsaquo;", "&hellip;").
-
-  The link variable is set to a proc that returns the link tag.
-  Usage: link.call( page_number [, text [, extra_attributes_string ]])
--%>
-<% link = pagy_link_proc(pagy, 'class="page-link"') -%>
-<%#               -%><nav aria-label="pager"  class="pagination" role="navigation">
-<%#               -%>  <ul class="pagination">
-<% if pagy.prev   -%>    <li class="page-item prev"><%== link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'aria-label="previous"') %></li>
-<% else           -%>    <li class="page-item prev disabled"><a href="#" class="page-link"><%== pagy_t('pagy.nav.prev') %></a></li>
-<% end            -%>
-<% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
-<%   case item
-     when Integer -%>
-<%#               -%>    <li class="page-item"><%== link.call(item) %></li>
-<%   when String  -%>
-<%#               -%>    <li class="page-item active"><%== link.call(item) %></li>
-<%   when :gap    -%>
-<%#               -%>    <li class="page-item disabled gap"><a href="#" class="page-link"><%== pagy_t('pagy.nav.gap') %></a></li>
-<%   end          -%>
-<% end            -%>
-<% if pagy.next   -%>    <li class="page-item next"><%== link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"') %></li>
-<% else           -%>    <li class="page-item next disabled"><a href="#" class="page-link"><%== pagy_t('pagy.nav.next') %></a></li>
-<% end            -%>
-<%#               -%>  </ul>
-<%#               -%></nav>

data/lib/templates/default.html.erb

@@ -1,26 +0,0 @@
-<%#
-  This template is i18n-ready: if you don't use i18n, then you can replace the pagy_t
-  calls with the actual strings ("&lsaquo; Prev", "Next &rsaquo;", "&hellip;").
-
-  The link variable is set to a proc that returns the link tag.
-  Usage: link.call( page_number [, text [, extra_attributes_string ]])
--%>
-<% link = pagy_link_proc(pagy) -%>
-<%#               -%><nav aria-label="pager" class="pagination" role="navigation">
-<% if pagy.prev   -%>  <span class="page prev"><%== link.call(pagy.prev, pagy_t('pagy.nav.prev'), 'aria-label="previous"') %></span>
-<% else           -%>  <span class="page prev disabled"><%== pagy_t('pagy.nav.prev') %></span>
-<% end            -%>
-<% pagy.series.each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36] -%>
-<%   case item
-     when Integer -%>
-<%#               -%>  <span class="page"><%== link.call(item) %></span>
-<%   when String  -%>
-<%#               -%>  <span class="page current"><%= item %></span>
-<%   when :gap    -%>
-<%#               -%>  <span class="page gap"><%== pagy_t('pagy.nav.gap') %></span>
-<%   end          -%>
-<% end            -%>
-<% if pagy.next   -%>  <span class="page next"><%== link.call(pagy.next, pagy_t('pagy.nav.next'), 'aria-label="next"') %></span>
-<% else           -%>  <span class="page next disabled"><%== pagy_t('pagy.nav.next') %></span>
-<% end            -%>
-<%#               -%></nav>