pagy 3.8.2 → 9.4.0

data/lib/pagy/b64.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  # Cheap Base64 specialized methods to avoid dependencies
+  module B64
+    module_function
+
+    def encode(bin)
+      [bin].pack('m0')
+    end
+
+    def decode(str)
+      str.unpack1('m0')
+    end
+
+    def urlsafe_encode(bin)
+      str = encode(bin)
+      str.chomp!('==') or str.chomp!('=')
+      str.tr!('+/', '-_')
+      str
+    end
+
+    def urlsafe_decode(str)
+      if !str.end_with?('=') && str.length % 4 != 0
+        str = str.ljust((str.length + 3) & ~3, '=')
+        str.tr!('-_', '+/')
+      else
+        str = str.tr('-_', '+/')
+      end
+      decode(str)
+    end
+  end
+end

data/lib/pagy/backend.rb

@@ -1,33 +1,44 @@
-# See Pagy::Backend API documentation: https://ddnexus.github.io/pagy/api/backend
-# encoding: utf-8
+# See Pagy::Backend API documentation: https://ddnexus.github.io/pagy/docs/api/backend
 # frozen_string_literal: true
 
 class Pagy
-  # Defines a few generic methods to paginate an ORM collection out of the box,
-  # or any collection by overriding pagy_get_items and/or pagy_get_vars in your controller
-
+  # Define a few generic methods to paginate a collection out of the box,
+  # or any collection by overriding any of the `pagy_*` methods in your controller.
   # See also the extras if you need specialized methods to paginate Arrays or other collections
+  module Backend
+    private
 
-  module Backend ; private         # the whole module is private so no problem with including it in a controller
-
-    # Return Pagy object and items
-    def pagy(collection, vars={})
-      pagy = Pagy.new(pagy_get_vars(collection, vars))
-      return pagy, pagy_get_items(collection, pagy)
+    # Return Pagy object and paginated results
+    def pagy(collection, **vars)
+      vars[:count] ||= pagy_get_count(collection, vars)
+      vars[:limit] ||= pagy_get_limit(vars)
+      vars[:page]  ||= pagy_get_page(vars)
+      pagy = Pagy.new(**vars)
+      [pagy, pagy_get_items(collection, pagy)]
     end
 
-    # Sub-method called only by #pagy: here for easy customization of variables by overriding
-    def pagy_get_vars(collection, vars)
-      vars[:count] ||= (c = collection.count(:all)).is_a?(Hash) ? c.size : c
-      vars[:page]  ||= params[ vars[:page_param] || VARS[:page_param] ]
-      vars
+    # Get the count from the collection
+    def pagy_get_count(collection, vars)
+      count_args = vars[:count_args] || DEFAULT[:count_args]
+      (count     = collection.count(*count_args)).is_a?(Hash) ? count.size : count
     end
 
-    # Sub-method called only by #pagy: here for easy customization of record-extraction by overriding
+    # Sub-method called only by #pagy: here for easy customization of fetching by overriding
+    # You may need to override this method for collections without offset|limit
     def pagy_get_items(collection, pagy)
-      # This should work with ActiveRecord, Sequel, Mongoid...
-      collection.offset(pagy.offset).limit(pagy.items)
+      collection.offset(pagy.offset).limit(pagy.limit)
     end
 
+    # Override for limit extra
+    def pagy_get_limit(_vars)
+      DEFAULT[:limit]
+    end
+
+    # Get the page integer from the params
+    # Overridable by the jsonapi extra
+    def pagy_get_page(vars, force_integer: true)
+      page = params[vars[:page_param] || DEFAULT[:page_param]]
+      force_integer ? (page || 1).to_i : page
+    end
   end
 end

data/lib/pagy/calendar/day.rb

@@ -0,0 +1,41 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Day unit subclass
+    class Day < Unit
+      DEFAULT = { size:   31,   # rubocop:disable Style/MutableConstant
+                  ends: false,
+                  order:  :asc,
+                  format: '%d' }
+
+      protected
+
+      # Set up the calendar variables
+      def assign_unit_vars
+        super
+        @initial = @starting.beginning_of_day
+        @final   = @ending.tomorrow.beginning_of_day
+        @last    = page_offset(@initial, @final)
+        @from    = starting_time_for(@page)
+        @to      = @from.tomorrow
+      end
+
+      # Starting time for the page
+      def starting_time_for(page)
+        @initial.days_since(time_offset_for(page))
+      end
+
+      def page_offset_at(time)
+        page_offset(@initial, time.beginning_of_day)
+      end
+
+      private
+
+      def page_offset(time_a, time_b)  # remove in 6.0
+        (time_b.time - time_a.time).to_i / 1.day
+      end
+    end
+  end
+end

data/lib/pagy/calendar/month.rb

@@ -0,0 +1,42 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Month unit subclass
+    class Month < Unit
+      DEFAULT = { size: 12,   # rubocop:disable Style/MutableConstant
+                  ends: false,
+                  order: :asc,
+                  format: '%b' }
+
+      protected
+
+      # Set up the calendar variables
+      def assign_unit_vars
+        super
+        @initial = @starting.beginning_of_month
+        @final   = @ending.next_month.beginning_of_month
+        @last    = (months_in(@final) - months_in(@initial))
+        @from    = starting_time_for(@page)
+        @to      = @from.next_month
+      end
+
+      # Starting time for the page
+      def starting_time_for(page)
+        @initial.months_since(time_offset_for(page))
+      end
+
+      def page_offset_at(time)
+        months_in(time.beginning_of_month) - months_in(@initial)
+      end
+
+      private
+
+      # Number of months in time
+      def months_in(time)
+        (time.year * 12) + time.month
+      end
+    end
+  end
+end

data/lib/pagy/calendar/quarter.rb

@@ -0,0 +1,49 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Quarter unit subclass
+    class Quarter < Unit
+      DEFAULT = { size:   4,      # rubocop:disable Style/MutableConstant
+                  ends: false,
+                  order:  :asc,
+                  format: 'Q%q' } # '%q' token
+
+      # The label for any page, with the substitution of the '%q' token
+      def label_for(page, opts = {})
+        starting_time = starting_time_for(page.to_i)  # page could be a string
+        opts[:format] = (opts[:format] || @vars[:format]).gsub('%q') { (starting_time.month / 3.0).ceil }
+        localize(starting_time, opts)
+      end
+
+      protected
+
+      # Set up the calendar variables
+      def assign_unit_vars
+        super
+        @initial = @starting.beginning_of_quarter
+        @final   = @ending.next_quarter.beginning_of_quarter
+        @last    = (months_in(@final) - months_in(@initial)) / 3
+        @from    = starting_time_for(@page)
+        @to      = @from.next_quarter
+      end
+
+      # Starting time for the page
+      def starting_time_for(page)
+        @initial.months_since(time_offset_for(page) * 3)
+      end
+
+      def page_offset_at(time)
+        (months_in(time.beginning_of_quarter) - months_in(@initial)) / 3
+      end
+
+      private
+
+      # Number of months in time
+      def months_in(time)
+        (time.year * 12) + time.month
+      end
+    end
+  end
+end

data/lib/pagy/calendar/unit.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/time'
+require 'active_support/core_ext/date_and_time/calculations'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/integer/time'
+
+class Pagy # :nodoc:
+  class Calendar < Hash # :nodoc:
+    # Base class for time units subclasses (Year, Quarter, Month, Week, Day)
+    class Unit < Pagy
+      attr_reader :order, :from, :to
+
+      # Merge and validate the options, do some simple arithmetic and set a few instance variables
+      def initialize(**vars)    # rubocop:disable Lint/MissingSuper
+        raise InternalError, 'Pagy::Calendar::Unit is a base class; use one of its subclasses' \
+            if instance_of?(Pagy::Calendar::Unit)
+
+        assign_vars({ **Pagy::DEFAULT, **self.class::DEFAULT }, vars)
+        assign_and_check(page: 1)
+        assign_unit_vars
+        check_overflow
+        assign_prev_and_next
+      end
+
+      # The label for the current page (it can pass along the I18n gem opts when it's used with the i18n extra)
+      def label(opts = {})
+        label_for(@page, opts)
+      end
+
+      # The label for any page (it can pass along the I18n gem opts when it's used with the i18n extra)
+      def label_for(page, opts = {})
+        opts[:format] ||= @vars[:format]
+        localize(starting_time_for(page.to_i), opts)  # page could be a string
+      end
+
+      protected
+
+      # The page that includes time
+      # In case of out of range time, the :fit_time option avoids the outOfRangeError
+      # and returns the closest page to the passed time argument (first or last page)
+      def page_at(time, **opts)
+        fit_time  = time
+        fit_final = @final - 1
+        unless time.between?(@initial, fit_final)
+          raise OutOfRangeError.new(self, :time, "between #{@initial} and #{fit_final}", time) unless opts[:fit_time]
+
+          if time < @final
+            fit_time = @initial
+            ordinal  = 'first'
+          else
+            fit_time = fit_final
+            ordinal  = 'last'
+          end
+          warn "Pagy::Calendar#page_at: Rescued #{time} out of range by returning the #{ordinal} page."
+        end
+        offset = page_offset_at(fit_time)   # offset starts from 0
+        @order == :asc ? offset + 1 : @last - offset
+      end
+
+      # Base class method for the setup of the unit variables (subclasses must implement it and call super)
+      def assign_unit_vars
+        raise VariableError.new(self, :format, 'to be a strftime format', @vars[:format]) unless @vars[:format].is_a?(String)
+        raise VariableError.new(self, :order, 'to be in [:asc, :desc]', @order) \
+        unless %i[asc desc].include?(@order = @vars[:order])
+
+        @starting, @ending = @vars[:period]
+        raise VariableError.new(self, :period, 'to be a an Array of min and max TimeWithZone instances', @vars[:period]) \
+        unless @starting.is_a?(ActiveSupport::TimeWithZone) \
+        && @ending.is_a?(ActiveSupport::TimeWithZone) && @starting <= @ending
+      end
+
+      # Apply the strftime format to the time (overridden by the i18n extra when localization is required)
+      def localize(time, opts)
+        time.strftime(opts[:format])
+      end
+
+      # Number of time units to offset from the @initial time, in order to get the ordered starting time for the page.
+      # Used in starting_time_for(page) where page starts from 1 (e.g. page to starting_time means subtracting 1)
+      def time_offset_for(page)
+        @order == :asc ? page - 1 : @last - page
+      end
+
+      # Period of the active page (used internally for nested units)
+      def active_period
+        [[@starting, @from].max, [@to - 1, @ending].min] # -1 sec: include only last unit day
+      end
+
+      # :nocov:
+      # This method must be implemented by the unit subclass
+      def starting_time_for(*)
+        raise NoMethodError, 'the starting_time_for method must be implemented by the unit subclass'
+      end
+
+      # This method must be implemented by the unit subclass
+      def page_offset_at(*)
+        raise NoMethodError, 'the page_offset_at method must be implemented by the unit subclass'
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/pagy/calendar/week.rb

@@ -0,0 +1,39 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Week unit subclass
+    class Week < Unit
+      DEFAULT  = { order:  :asc,      # rubocop:disable Style/MutableConstant
+                   format: '%Y-%W' }
+
+      protected
+
+      # Set up the calendar variables
+      def assign_unit_vars
+        super
+        @initial = @starting.beginning_of_week
+        @final   = @ending.next_week.beginning_of_week
+        @last    = page_offset(@initial, @final)
+        @from    = starting_time_for(@page)
+        @to      = @from.next_week
+      end
+
+      # Starting time for the page
+      def starting_time_for(page)
+        @initial.weeks_since(time_offset_for(page))
+      end
+
+      def page_offset_at(time)
+        page_offset(@initial, time.beginning_of_week)
+      end
+
+      private
+
+      def page_offset(time_a, time_b)  # remove in 6.0
+        (time_b.time - time_a.time).to_i / 1.week
+      end
+    end
+  end
+end

data/lib/pagy/calendar/year.rb

@@ -0,0 +1,35 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  class Calendar # :nodoc:
+    # Year unit subclass
+    class Year < Unit
+      DEFAULT = { size:   10,   # rubocop:disable Style/MutableConstant
+                  ends: false,
+                  order:  :asc,
+                  format: '%Y' }
+
+      protected
+
+      # Set up the calendar variables
+      def assign_unit_vars
+        super
+        @initial = @starting.beginning_of_year
+        @final   = @ending.next_year.beginning_of_year
+        @last    = @final.year - @initial.year
+        @from    = starting_time_for(@page)
+        @to      = @from.next_year
+      end
+
+      # Starting time for the page
+      def starting_time_for(page)
+        @initial.years_since(time_offset_for(page))
+      end
+
+      def page_offset_at(time)
+        time.beginning_of_year.year - @initial.year
+      end
+    end
+  end
+end

data/lib/pagy/calendar.rb

@@ -0,0 +1,84 @@
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
+# frozen_string_literal: true
+
+require_relative '../pagy'
+require_relative 'calendar/unit'
+
+class Pagy # :nodoc:
+  # Calendar class
+  class Calendar < Hash
+    # Specific out of range error
+    class OutOfRangeError < VariableError; end
+
+    # List of units in desc order of duration. It can be used for custom units.
+    UNITS = %i[year quarter month week day]  # rubocop:disable Style/MutableConstant
+
+    class << self
+      private
+
+      # Create a unit subclass instance by using the unit name (internal use)
+      def create(unit, **vars)
+        raise InternalError, "unit must be in #{UNITS.inspect}; got #{unit}" unless UNITS.include?(unit)
+
+        name    = unit.to_s
+        name[0] = name[0].capitalize
+        Object.const_get("Pagy::Calendar::#{name}").new(**vars)
+      end
+
+      # Return calendar, from, to
+      def init(...)
+        new.send(:init, ...)
+      end
+    end
+
+    # Return the current time of the smallest time unit shown
+    def showtime
+      self[@units.last].from
+    end
+
+    private
+
+    # Create the calendar
+    def init(conf, period, params)
+      @conf  = Marshal.load(Marshal.dump(conf))  # store a copy
+      @units = Calendar::UNITS & @conf.keys # get the units in time length desc order
+      raise ArgumentError, 'no calendar unit found in pagy_calendar @configuration' if @units.empty?
+
+      @period     = period
+      @params     = params
+      @page_param = conf[:pagy][:page_param] || DEFAULT[:page_param]
+      # set all the :page_param vars for later deletion
+      @units.each { |unit| conf[unit][:page_param] = :"#{unit}_#{@page_param}" }
+      calendar = {}
+      object   = nil
+      @units.each_with_index do |unit, index|
+        params_to_delete    = @units[(index + 1), @units.size].map { |sub| conf[sub][:page_param] } + [@page_param]
+        conf[unit][:params] = ->(up) { up.except(*params_to_delete.map(&:to_s)) }
+        conf[unit][:period] = object&.send(:active_period) || @period
+        conf[unit][:page]   = @params[:"#{unit}_#{@page_param}"] # requested page
+        # :nocov:
+        conf[unit][:counts] = yield(unit, conf[unit][:period]) if block_given?  # nocov doesn't need to fail block_given?
+        # :nocov:
+        calendar[unit]      = object \
+                            = Calendar.send(:create, unit, **conf[unit])
+      end
+      [replace(calendar), object.from, object.to]
+    end
+
+    # Return the calendar object at time
+    def calendar_at(time, **opts)
+      conf        = Marshal.load(Marshal.dump(@conf))
+      page_params = {}
+      @units.inject(nil) do |object, unit|
+        conf[unit][:period] = object&.send(:active_period) || @period
+        conf[unit][:page]   = page_params[:"#{unit}_#{@page_param}"] \
+                            = Calendar.send(:create, unit, **conf[unit]).send(:page_at, time, **opts)
+        conf[unit][:params] ||= {}
+        conf[unit][:params].merge!(page_params)
+        Calendar.send(:create, unit, **conf[unit])
+      end
+    end
+  end
+  # Require the subclass files in UNITS (no custom unit at this point yet)
+  Calendar::UNITS.each { |unit| require "pagy/calendar/#{unit}" }
+end

data/lib/pagy/console.rb

@@ -0,0 +1,23 @@
+# See Pagy::Console API documentation: https://ddnexus.github.io/pagy/docs/api/console
+# frozen_string_literal: true
+
+require_relative '../pagy'  # so you can require just the extra in the console
+require_relative 'extras/standalone'
+
+class Pagy
+  # Provide a ready to use pagy environment when included in irb/rails console
+  module Console
+    # Include Backend, Frontend and set the default URL
+    def self.included(main)
+      main.include(Backend)
+      main.include(Frontend)
+      DEFAULT[:url] = 'http://www.example.com/subdir'
+    end
+
+    # Require the extras passed as arguments
+    def pagy_extras(*extras)
+      extras.each { |extra| require "pagy/extras/#{extra}" }
+      puts "Required extras: #{extras.map(&:inspect).join(', ')}"
+    end
+  end
+end

data/lib/pagy/countless.rb

@@ -1,33 +1,38 @@
-# encoding: utf-8
+# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/countless
 # frozen_string_literal: true
 
-require 'pagy'
-
-class Pagy
-
+class Pagy # :nodoc:
+  # No need to know the count to paginate
   class Countless < Pagy
-
     # Merge and validate the options, do some simple arithmetic and set a few instance variables
-    def initialize(vars={})
-      @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == '' })      # default vars + cleaned vars (can be overridden)
-      { items:1, outset:0, page:1 }.each do |k,min|                     # validate instance variables
-        (@vars[k] && instance_variable_set(:"@#{k}", @vars[k].to_i) >= min) \
-         or raise(VariableError.new(self), "expected :#{k} >= #{min}; got #{@vars[k].inspect}")
-      end
-      @offset = @items * (@page - 1) + @outset                          # pagination offset + outset (initial offset)
+    def initialize(**vars) # rubocop:disable Lint/MissingSuper
+      assign_vars(DEFAULT, vars)
+      assign_and_check(page: 1, outset: 0)
+      assign_limit
+      assign_offset
     end
 
-    # Finalize the instance variables based on the fetched items
-    def finalize(fetched)
-      fetched == 0 && @page > 1 and raise(OverflowError.new(self), "page #{@page} got no items")
-      @pages = @last = (fetched > @items ? @page + 1 : @page)         # set the @pages and @last
-      @items = fetched if fetched < @items && fetched > 0             # adjust items for last non-empty page
-      @from  = fetched == 0 ? 0 : @offset+1 - @outset                 # page begins from item
-      @to    = fetched == 0 ? 0 : @offset + @items - @outset          # page ends to item
-      @prev  = (@page-1 unless @page == 1)                            # nil if no prev page
-      @next  = @page == @last ? (1 if @vars[:cycle]) : @page+1        # nil if no next page, 1 if :cycle
+    # Finalize the instance variables based on the fetched size
+    def finalize(fetched_size)
+      raise OverflowError.new(self, :page, "to be < #{@page}", @page) if fetched_size.zero? && @page > 1
+
+      @last = fetched_size > @limit ? @page + 1 : @page
+      @last = @vars[:max_pages] if @vars[:max_pages] && @last > @vars[:max_pages]
+      check_overflow
+      @in   = [fetched_size, @limit].min
+      @from = @in.zero? ? 0 : @offset - @outset + 1
+      @to   = @offset - @outset + @in
+      assign_prev_and_next
       self
     end
+  end
 
+  module SeriesOverride # :nodoc:
+    # Override the original series.
+    # Return nil if :countless_minimal is enabled
+    def series(**)
+      super unless @vars[:countless_minimal]
+    end
   end
+  prepend SeriesOverride
 end

data/lib/pagy/exceptions.rb

@@ -1,22 +1,25 @@
-class Pagy
+# frozen_string_literal: true
 
+class Pagy
+  # Generic variable error
   class VariableError < ArgumentError
-    attr_reader :pagy
-
-    def initialize(pagy)
-      @pagy = pagy
-    end
+    attr_reader :pagy, :variable, :value
 
-    def variable
-      message =~ /expected :([\w]+)/
-      $1.to_sym if $1
-    end
-
-    def value
-      pagy.vars[variable]
+    # Set the variables and prepare the message
+    def initialize(pagy, variable, description, value)
+      @pagy     = pagy
+      @variable = variable
+      @value    = value
+      super("expected :#{@variable} #{description}; got #{@value.inspect}")
     end
   end
 
+  # Specific overflow error
   class OverflowError < VariableError; end
 
+  # I18n configuration error
+  class I18nError < StandardError; end
+
+  # Generic internal error
+  class InternalError < StandardError; end
 end

data/lib/pagy/extras/arel.rb

@@ -1,21 +1,18 @@
-# See the Pagy documentation: https://ddnexus.github.io/pagy/extras/arel
-# encoding: utf-8
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/arel
 # frozen_string_literal: true
 
-class Pagy
-  module Backend ; private
+class Pagy # :nodoc:
+  # Better performance of grouped ActiveRecord collections
+  module ArelExtra
+    private
 
-    def pagy_arel(collection, vars={})
-      pagy = Pagy.new(pagy_arel_get_vars(collection, vars))
-      return pagy, pagy_get_items(collection, pagy)
-    end
-
-    def pagy_arel_get_vars(collection, vars)
+    # Return Pagy object and paginated collection/results
+    def pagy_arel(collection, **vars)
       vars[:count] ||= pagy_arel_count(collection)
-      vars[:page]  ||= params[ vars[:page_param] || VARS[:page_param] ]
-      vars
+      pagy(collection, **vars)
     end
 
+    # Count using Arel when grouping
     def pagy_arel_count(collection)
       if collection.group_values.empty?
         # COUNT(*)
@@ -23,9 +20,9 @@ class Pagy
       else
         # COUNT(*) OVER ()
         sql = Arel.star.count.over(Arel::Nodes::Grouping.new([]))
-        collection.unscope(:order).limit(1).pluck(sql).first.to_i
+        collection.unscope(:order).pick(sql).to_i
       end
     end
-
   end
+  Backend.prepend ArelExtra
 end