passed instance variables are not deleted from the vars hash

docs/api/pagy.md

@@ -51,19 +51,26 @@ Pagy::VARS[:my_option] = 'my option'
 
 This method returns the `pathname` of the `pagy/lib` root dir. It is useful to get the absolute path of template, locale and javascript files installed with the gem.
 
-### Pagy.new
+### Pagy.new(vars)
 
 _Notice_: If you use the `Pagy::Backend` its `pagy` method will instantiate and return the Pagy object for you.
 
-The `Pagy.new` method accepts a single hash of variables that will be merged with the `Pagy::Vars` hash and will be used to create the object. The only mandatory variable is the `:count` of the collection to paginate: all the other variables are optional and have sensible defaults. Of course you will also have to pass the `page` or you will always get the default page number 1.
+The `Pagy.new` method accepts a single hash of variables that will be merged with the `Pagy::Vars` hash and will be used to create the object.
 
-All the variables not explicitly in the list of core-variables (the non-core variables) passed/merged to the new method will be kept in the object, passed around with it and accessible through the `pagy.vars` hash.
+### Variables
 
-**Notice**: Pagy replaces the blank values of the passed variables with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
+All the variables passed to the new method will be merged with the `Pagy::VARS` hash and will be kept in the object, passed around with it and accessible through the `pagy.vars` hash.
 
-### Core Variables
+They can be set globally by using the `Pagy::VARS` hash or passed to the `Pagy.new` method and are accessible through the `vars` reader.
 
-These are the core-variables (i.e. instance variables that define the pagination object itself) consumed by the `new` method. They are all integers:
+**Notice**: Pagy replaces the blank values of the passed variables with their default values coming from the `Pagy::VARS` hash. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.
+
+### Instance Variables
+
+A few variables are particularly important for the calculation of the pagination, and therefore are validated and used to initialize a few instance variables.
+
+The only mandatory instance variable to be passed is the `:count` of the collection to paginate: all the other variables are optional and have sensible defaults. Of course you will also have to pass the `page` or you will always get the default page number 1.
+They are all integers:
 
 | Variable | Description | Default |
 | --------- | ---------------------------------------------------------------------------------------------- | ------- |
@@ -72,28 +79,26 @@ These are the core-variables (i.e. instance variables that define the pagination
 | `:items` | the _requested_ number of items for the page | `20` |
 | `:outset` | the initial offset of the collection to paginate: pass it only if the collection had an offset | `0` |
 
-### Non-core Variables
-
-These are the non-core variables: as for the core-variables they can be set globally by using the `Pagy::VARS` hash or passed to the `Pagy.new` method, but they don't become instance variables. Instead they are items of the `@vars` instance variable hash and are accessible through the `vars` reader.
+### Other Variables
 
 | Variable | Description | Default |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
 | `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. (see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |
 | `:page_param` | the name of the page param name used in the url. (see [Customizing the page param](../how-to.md#customizing-the-page-param) | `:page` |
 | `:params` | the arbitrary param hash to add to the url. (see [Customizing the params](../how-to.md#customizing-the-params) | `{}` |
-| `:anchor` | the arbitrary anchor string (including the "#") to add to the url. (see [Customizing the page param](../how-to.md#customizing-the-params) | `""` |
-| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links | `""` |
-| `:item_path` | the dictionary path used by the `pagy_info` method to lookup the item/model name | `""` |
+| `:anchor` | the arbitrary anchor string (including the "#") to add to the url. (see [Customizing the page param](../how-to.md#customizing-the-params) | `""`  |
+| `:link_extra` | the extra attributes string (formatted as a valid HTML attribute/value pairs) added to the page links | `""`  |
+| `:item_path` | the dictionary path used by the `pagy_info` method to lookup the item/model name | `""`  |
 
-There is no specific default nor validation for non-core variables.
+There is no specific validation for non-instance variables.
 
 ### Attribute Readers
 
 Pagy exposes all the instance variables needed for the pagination through a few attribute readers. They all return integers (or `nil`), except the `vars` hash:
 
 | Reader | Description |
 | -------- | ------------------------------------------------------------------------------------------------------------------ |
-| `count` | the untouched `:count` variable |
+| `count` | the collection `:count`   |
 | `page` | the current page number |
 | `items` | the _actual_ number of items in the current page (can be less than the requested `:items` variable) |
 | `pages` | the number of total pages in the collection (same as `last` but with cardinal meaning) |
@@ -103,7 +108,7 @@ Pagy exposes all the instance variables needed for the pagination through a few
 | `to` | the collection-position of the last item in the page (`:outset` excluded) |
 | `prev` | the previous page number or `nil` if there is no previous page |
 | `next` | the next page number or `nil` if there is no next page |
-| `vars` | the non-core variables hash |
+| `vars` | the variables hash  |
 
 ### series(...)
 

lib/pagy.rb

@@ -16,9 +16,9 @@ def self.root; Pathname.new(__FILE__).dirname end
 
  # Merge and validate the options, do some simple aritmetic and set the instance variables
  def initialize(vars)
- @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == ''.freeze }) # default vars + cleaned instance vars
- { count:0, items:1, outset:0, page:1 }.each do |k,min| # validate core variables
- (@vars[k] && instance_variable_set(:"@#{k}", @vars.delete(k).to_i) >= min) \
+ @vars = VARS.merge(vars.delete_if{|_,v| v.nil? || v == ''.freeze }) # default vars + cleaned vars
+ { count:0, 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(ArgumentError, "expected :#{k} >= #{min}; got #{instance_variable_get(:"@#{k}").inspect}")
  end
  @pages = @last = [(@count.to_f / @items).ceil, 1].max # cardinal and ordinal meanings

lib/pagy/extras/initializer_example.rb

@@ -32,10 +32,10 @@
 # All the Pagy::VARS here are set for all the Pagy instances but can be
 # overridden by just passing them to Pagy.new or the #pagy controller method
 
-# Core variables (See https://ddnexus.github.io/pagy/api/pagy#core-variables)
+# Instance variables (See https://ddnexus.github.io/pagy/api/pagy#instance-variables)
 # Pagy::VARS[:items] = 20 # default
 
-# Non Core Variables (See https://ddnexus.github.io/pagy/api/pagy#non-core-variables)
+# Other Variables (See https://ddnexus.github.io/pagy/api/pagy#other-variables)
 # Pagy::VARS[:size] = [1,4,4,1] # default
 # Pagy::VARS[:page_param] = :page # default
 # Pagy::VARS[:params] = {} # default