preserve 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76397ea6ad52a116d49b2d28f4e011e294e14c2f9fc6afa7e4e6ec7e397c1145
-  data.tar.gz: 3424237b322a89b4d4ccad66e226b48fe6b123be88926ce062d763e04650801b
+  metadata.gz: d5976d2703bee78f1a94fadc77405eb808730c805b248d6e8e57695c02857d65
+  data.tar.gz: 33c61bab02329c7f6ad662fff52bfec9f924067c923eaad0f2606af473bcee95
 SHA512:
-  metadata.gz: e724d2f28ff988ee39804288f889914995ce96c0597d129f168e8d1fc6572d69cfa49745a366130f0a3560bc7b2be16d91df75029e02e197cc816b6ab4843b47
-  data.tar.gz: 2f1431d6660743505520a425aaa29b7e154d75c3f1bcd6bc6f655b9bb6a6c29d048d809225326223fc4dff120aad0e99a7794deb24a5fe4706cafa1958e30516
+  metadata.gz: 7c33d635321d025fa41a3a3736bdd5621c8fa93614b14a05a139a4cea46957e2a79d104fcd208712c769c1ef348c6aa0e64976a88e6e280c674e1e60fe43fc75
+  data.tar.gz: bf1cd4bf2bed473f53204ff8bfdb0b298201d71607e78d6907d68288c72ce459919ceadf72a15a5e2cb8f518b1a0107c92fceac2d30f157008ce367175bda815

data/README.md

@@ -1,4 +1,4 @@
-# Preserve [![Gem version](https://img.shields.io/gem/v/preserve.svg)](https://rubygems.org/gems/preserve) [![Build status](https://img.shields.io/travis/pienkowb/preserve.svg)](https://travis-ci.org/pienkowb/preserve)
+# Preserve [![Gem version](https://img.shields.io/gem/v/preserve)](https://rubygems.org/gems/preserve) [![Build status](https://img.shields.io/travis/pienkowb/preserve/develop)](https://travis-ci.org/pienkowb/preserve) [![Coverage status](https://img.shields.io/coveralls/github/pienkowb/preserve/develop)](https://coveralls.io/github/pienkowb/preserve) [![Maintainability status](https://img.shields.io/codeclimate/maintainability/pienkowb/preserve)](https://codeclimate.com/github/pienkowb/preserve)
 
 Preserve is a Rails plugin which stores selected parameters in the session to make them available in subsequent requests.
 
@@ -29,12 +29,12 @@ For the sole purpose of this example, let's assume we have a Rails application w
 ```ruby
 class ParametersController < ApplicationController
   def index
-    render json: request_parameters
+    render json: parameters
   end
 
   private
 
-  def request_parameters
+  def parameters
     params.except(:controller, :action)
   end
 end
@@ -48,16 +48,16 @@ Rails.application.routes.draw do
 end
 ```
 
-Let's start the application and test its behaviour using [cURL](https://curl.haxx.se/).
-The whole concept is based on the session, so in order for this to work, the cookie engine must be enabled (hence the `-c` and `-b` options).
+Let's start the application and test its behavior using [cURL](https://curl.haxx.se/).
+The whole concept is based on the session, so in order for this to work the cookie engine must be enabled (hence the `-c` and `-b` options).
 
-In the first request, the `per_page` parameter is set to 20.
+In the first request, the `status` parameter is set to `active`.
 
 ```
-$ curl -c cookies http://localhost:3000/parameters?per_page=20
+$ curl -c cookies http://localhost:3000/parameters?status=active
 ```
 ```json
-{"per_page":"20"}
+{"status":"active"}
 ```
 
 As expected, the application returns the parameter and its value.
@@ -71,35 +71,35 @@ $ curl -b cookies http://localhost:3000/parameters
 {}
 ```
 
-Obviously, the `per_page` parameter is no longer available.
+Obviously, the `status` parameter is no longer available.
 
 Now, let's call the `preserve` macro inside the `ParametersController` class with the parameter name as an argument.
 
 ```ruby
 class ParametersController < ApplicationController
-  preserve :per_page
+  preserve :status
 
   # ...
 end
 ```
 
-Sending the same two requests again gives a different result.
+Sending the same two requests again yields a different result.
 
 ```
-$ curl -c cookies http://localhost:3000/parameters?per_page=20
+$ curl -c cookies http://localhost:3000/parameters?status=active
 ```
 ```json
-{"per_page":"20"}
+{"status":"active"}
 ```
 
 ```
 $ curl -b cookies http://localhost:3000/parameters
 ```
 ```json
-{"per_page":"20"}
+{"status":"active"}
 ```
 
-This time, the `per_page` parameter is still available when the second request is made, even though it wasn't sent particularly in that request.
+This time, the `status` parameter is still available when the second request is made, even though it wasn't sent particularly in that request.
 
 ### Multiple arguments
 
@@ -112,17 +112,17 @@ preserve :page, :per_page
 ### Action restrictions
 
 Limiting functionality provided by the gem to a certain set of controller actions can be achieved by applying the `only` (or `except`) option.
+For example:
 
 ```ruby
-preserve :per_page, only: :index
+preserve :status, only: :index
 ```
 
-It behaves exactly like the `only` option of an [Action Controller filter](https://guides.rubyonrails.org/action_controller_overview.html#filters).
-In fact, the gem sets such filter underneath, so you can make use of all its options – they will be passed to that filter.
+The behavior is exactly the same as with an [Action Controller filter](https://guides.rubyonrails.org/action_controller_overview.html#filters).
 
 ### Application-wide parameters
 
-When there's a need to store a parameter used across the whole application, the `preserve` macro should be called inside the `ApplicationController`.
+Parameters used across the whole application can be persisted by adding the `preserve` macro to the `ApplicationController`.
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -132,28 +132,46 @@ end
 
 In more complex scenarios, controller inheritance can be utilized to further adjust the scope.
 
-### Blank parameter values
+### Nested parameters
 
-Normally, when a parameter value is an empty string, it is overwritten by a value stored in the session.
-To change this behavior, you can use the `allow_blank` option.
+Storing a value of a nested parameter requires calling the `preserve` macro with an array of consecutive keys leading to that parameter in the parameters hash (similar to the [`Hash#dig`](https://apidock.com/ruby/Hash/dig) method).
+
+For example, in case of the JSON payload below:
+
+```json
+{
+  "sort": {
+    "column": "name",
+    "direction": "desc"
+  }
+}
+```
+
+The `column` parameter can be persisted with the following line:
 
 ```ruby
-  preserve :status, allow_blank: true
+preserve [:sort, :column]
 ```
 
-As a result, the parameter value would be restored from the session only when the parameter was not sent in a request.
+### Default parameter value
 
-### Setting a session key prefix
+There might be a situation where neither the parameters hash nor the session contains a parameter value.
+To provide a fallback value for such a scenario, you can use the `default` option.
+For instance:
 
-By default, parameter values are stored in the session with a key that consists of a controller name and parameter name (e.g. `users_order` for the `order` parameter in the `UsersController`).
+```ruby
+preserve :status, default: 'active'
+```
+
+Note that default values are not stored in the session, but assigned on every request instead.
+
+### Blank parameter values
 
-In most cases such combination results in a unique session key, but there might be a situation when it's necessary to add a prefix in order to avoid conflicts with a session key that is already in use.
-It can be done by passing the `prefix` option.
+Normally, when a parameter value is an empty string it is overwritten by a value stored in the session.
+To change this behavior, you can use the `allow_blank` option.
 
 ```ruby
-class UsersController < ApplicationController
-  preserve :order, prefix: 'preserved'
-end
+preserve :status, allow_blank: true
 ```
 
-From now on, the parameter will be stored in the session with the `preserved_users_order` key.
+As a result, the parameter value would be restored from the session only when the parameter was not sent in a request.

data/Rakefile

@@ -16,7 +16,7 @@ end
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Preserve'
+  rdoc.title = 'Preserve'
   rdoc.options << '--line-numbers'
   rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')

data/lib/preserve.rb

@@ -1,35 +1,12 @@
 require 'active_support'
 
-module Preserve
-  def preserve(*parameter_names)
-    options = parameter_names.extract_options!
+require 'preserve/version'
+require 'preserve/compatibility'
 
-    allow_blank = options.delete(:allow_blank)
-    prefix = options.delete(:prefix)
-
-    parameter_names.each do |name|
-      key = [prefix, controller_name, name].compact.join('_')
-      predicate = allow_blank ? :nil? : :blank?
-
-      _set_preserve_callback(options) do
-        if params[name].send(predicate)
-          params[name] = session[key] if session.key?(key)
-        else
-          session[key] = params[name]
-        end
-      end
-    end
-  end
-
-  def _set_preserve_callback(options, &block)
-    if respond_to?(:before_action)
-      before_action(options, &block)
-    else
-      before_filter(options, &block)
-    end
-  end
-end
+require 'preserve/session_key'
+require 'preserve/callback'
+require 'preserve/extension'
 
 ActiveSupport.on_load(:action_controller) do
-  extend Preserve
+  extend Preserve::Extension
 end

data/lib/preserve/callback.rb

@@ -0,0 +1,72 @@
+require 'preserve/compatibility'
+require 'preserve/session_key'
+
+module Preserve
+  class Callback
+    delegate :params, to: :controller
+    delegate :session, to: :controller
+
+    def initialize(source_class, parameter_key, options)
+      @source_class = source_class
+      @parameter_key = parameter_key
+      @options = options
+    end
+
+    def before(controller)
+      @controller = controller
+
+      if parameter_blank?
+        parameter_stored? ? restore_parameter : set_default_value
+      else
+        store_parameter
+      end
+    end
+
+    private
+
+    attr_reader :source_class
+    attr_reader :parameter_key
+    attr_reader :options
+    attr_reader :controller
+
+    def parameter_blank?
+      predicate = options[:allow_blank] ? :nil? : :blank?
+      parameter_value.__send__(predicate)
+    end
+
+    def parameter_stored?
+      session.key?(session_key)
+    end
+
+    def restore_parameter
+      self.parameter_value = session[session_key]
+    end
+
+    def set_default_value
+      self.parameter_value = options[:default] if options[:default]
+    end
+
+    def store_parameter
+      session[session_key] = parameter_value
+    end
+
+    def parameter_value
+      keys = Array(parameter_key)
+      keys.reduce(params) { |h, k| h[k] if h.is_a?(HASH_CLASS) }
+    end
+
+    def parameter_value=(value)
+      *keys, last_key = parameter_key
+
+      nested_hash = keys.reduce(params) do |hash, key|
+        hash[key] ||= HASH_CLASS.new
+      end
+
+      nested_hash[last_key] = value
+    end
+
+    def session_key
+      SessionKey.new(source_class, parameter_key).build
+    end
+  end
+end

data/lib/preserve/compatibility.rb

@@ -0,0 +1,18 @@
+require 'action_pack'
+require 'active_support/hash_with_indifferent_access'
+
+module Preserve
+  BEFORE_METHOD =
+    if ActionPack::VERSION::MAJOR >= 4
+      :before_action
+    else
+      :before_filter
+    end
+
+  HASH_CLASS =
+    if ActionPack::VERSION::MAJOR >= 4
+      ActionController::Parameters
+    else
+      ActiveSupport::HashWithIndifferentAccess
+    end
+end

data/lib/preserve/extension.rb

@@ -0,0 +1,16 @@
+require 'preserve/callback'
+require 'preserve/compatibility'
+
+module Preserve
+  module Extension
+    def preserve(*parameter_keys)
+      options = parameter_keys.extract_options!
+      filter_options = options.slice(:only, :except)
+
+      parameter_keys.each do |parameter_key|
+        callback = Callback.new(self, parameter_key, options)
+        __send__(BEFORE_METHOD, callback, filter_options)
+      end
+    end
+  end
+end

data/lib/preserve/session_key.rb

@@ -0,0 +1,27 @@
+require 'digest/sha1'
+
+module Preserve
+  class SessionKey
+    def initialize(controller_class, parameter_key)
+      @controller_class = controller_class
+      @parameter_key = parameter_key
+    end
+
+    def build
+      [:preserve, calculate_digest].join('_')
+    end
+
+    private
+
+    attr_reader :controller_class
+    attr_reader :parameter_key
+
+    def calculate_digest
+      Digest::SHA1.hexdigest(input_data)
+    end
+
+    def input_data
+      [controller_class, parameter_key.class, parameter_key].join('_')
+    end
+  end
+end

data/lib/preserve/version.rb

@@ -1,3 +1,3 @@
 module Preserve
-  VERSION = '1.0.0'.freeze
+  VERSION = '2.0.0'.freeze
 end

data/spec/dummy/common/app/controllers/admin/parameters_controller.rb

@@ -0,0 +1,7 @@
+module Admin
+  class ParametersController < ApplicationController
+    def index
+      render json: parameters
+    end
+  end
+end

data/spec/dummy/common/app/controllers/application_controller.rb

@@ -0,0 +1,7 @@
+class ApplicationController < ActionController::Base
+  private
+
+  def parameters
+    params.except(:controller, :action)
+  end
+end

data/spec/dummy/common/app/controllers/parameters_controller.rb

@@ -0,0 +1,9 @@
+class ParametersController < ApplicationController
+  def index
+    render json: parameters
+  end
+
+  def create
+    render json: parameters
+  end
+end

data/spec/dummy/common/config/routes.rb

@@ -0,0 +1,7 @@
+Rails.application.routes.draw do
+  resources :parameters, only: %i[index create]
+
+  namespace :admin do
+    resources :parameters, only: :index
+  end
+end

data/spec/dummy/rails-3/README.rdoc

@@ -0,0 +1,261 @@
+== Welcome to Rails
+
+Rails is a web-application framework that includes everything needed to create
+database-backed web applications according to the Model-View-Control pattern.
+
+This pattern splits the view (also called the presentation) into "dumb"
+templates that are primarily responsible for inserting pre-built data in between
+HTML tags. The model contains the "smart" domain objects (such as Account,
+Product, Person, Post) that holds all the business logic and knows how to
+persist themselves to a database. The controller handles the incoming requests
+(such as Save New Account, Update Product, Show Post) by manipulating the model
+and directing data to the view.
+
+In Rails, the model is handled by what's called an object-relational mapping
+layer entitled Active Record. This layer allows you to present the data from
+database rows as objects and embellish these data objects with business logic
+methods. You can read more about Active Record in
+link:files/vendor/rails/activerecord/README.html.
+
+The controller and view are handled by the Action Pack, which handles both
+layers by its two parts: Action View and Action Controller. These two layers
+are bundled in a single package due to their heavy interdependence. This is
+unlike the relationship between the Active Record and Action Pack that is much
+more separate. Each of these packages can be used independently outside of
+Rails. You can read more about Action Pack in
+link:files/vendor/rails/actionpack/README.html.
+
+
+== Getting Started
+
+1. At the command prompt, create a new Rails application:
+       <tt>rails new myapp</tt> (where <tt>myapp</tt> is the application name)
+
+2. Change directory to <tt>myapp</tt> and start the web server:
+       <tt>cd myapp; rails server</tt> (run with --help for options)
+
+3. Go to http://localhost:3000/ and you'll see:
+       "Welcome aboard: You're riding Ruby on Rails!"
+
+4. Follow the guidelines to start developing your application. You can find
+the following resources handy:
+
+* The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html
+* Ruby on Rails Tutorial Book: http://www.railstutorial.org/
+
+
+== Debugging Rails
+
+Sometimes your application goes wrong. Fortunately there are a lot of tools that
+will help you debug it and get it back on the rails.
+
+First area to check is the application log files. Have "tail -f" commands
+running on the server.log and development.log. Rails will automatically display
+debugging and runtime information to these files. Debugging info will also be
+shown in the browser on requests from 127.0.0.1.
+
+You can also log your own messages directly into the log file from your code
+using the Ruby logger class from inside your controllers. Example:
+
+  class WeblogController < ActionController::Base
+    def destroy
+      @weblog = Weblog.find(params[:id])
+      @weblog.destroy
+      logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!")
+    end
+  end
+
+The result will be a message in your log file along the lines of:
+
+  Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1!
+
+More information on how to use the logger is at http://www.ruby-doc.org/core/
+
+Also, Ruby documentation can be found at http://www.ruby-lang.org/. There are
+several books available online as well:
+
+* Programming Ruby: http://www.ruby-doc.org/docs/ProgrammingRuby/ (Pickaxe)
+* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide)
+
+These two books will bring you up to speed on the Ruby language and also on
+programming in general.
+
+
+== Debugger
+
+Debugger support is available through the debugger command when you start your
+Mongrel or WEBrick server with --debugger. This means that you can break out of
+execution at any point in the code, investigate and change the model, and then,
+resume execution! You need to install ruby-debug to run the server in debugging
+mode. With gems, use <tt>sudo gem install ruby-debug</tt>. Example:
+
+  class WeblogController < ActionController::Base
+    def index
+      @posts = Post.all
+      debugger
+    end
+  end
+
+So the controller will accept the action, run the first line, then present you
+with a IRB prompt in the server window. Here you can do things like:
+
+  >> @posts.inspect
+  => "[#<Post:0x14a6be8
+          @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>,
+       #<Post:0x14a6620
+          @attributes={"title"=>"Rails", "body"=>"Only ten..", "id"=>"2"}>]"
+  >> @posts.first.title = "hello from a debugger"
+  => "hello from a debugger"
+
+...and even better, you can examine how your runtime objects actually work:
+
+  >> f = @posts.first
+  => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
+  >> f.
+  Display all 152 possibilities? (y or n)
+
+Finally, when you're ready to resume execution, you can enter "cont".
+
+
+== Console
+
+The console is a Ruby shell, which allows you to interact with your
+application's domain model. Here you'll have all parts of the application
+configured, just like it is when the application is running. You can inspect
+domain models, change values, and save to the database. Starting the script
+without arguments will launch it in the development environment.
+
+To start the console, run <tt>rails console</tt> from the application
+directory.
+
+Options:
+
+* Passing the <tt>-s, --sandbox</tt> argument will rollback any modifications
+  made to the database.
+* Passing an environment name as an argument will load the corresponding
+  environment. Example: <tt>rails console production</tt>.
+
+To reload your controllers and models after launching the console run
+<tt>reload!</tt>
+
+More information about irb can be found at:
+link:http://www.rubycentral.org/pickaxe/irb.html
+
+
+== dbconsole
+
+You can go to the command line of your database directly through <tt>rails
+dbconsole</tt>. You would be connected to the database with the credentials
+defined in database.yml. Starting the script without arguments will connect you
+to the development database. Passing an argument will connect you to a different
+database, like <tt>rails dbconsole production</tt>. Currently works for MySQL,
+PostgreSQL and SQLite 3.
+
+== Description of Contents
+
+The default directory structure of a generated Ruby on Rails application:
+
+  |-- app
+  |   |-- assets
+  |   |   |-- images
+  |   |   |-- javascripts
+  |   |   `-- stylesheets
+  |   |-- controllers
+  |   |-- helpers
+  |   |-- mailers
+  |   |-- models
+  |   `-- views
+  |       `-- layouts
+  |-- config
+  |   |-- environments
+  |   |-- initializers
+  |   `-- locales
+  |-- db
+  |-- doc
+  |-- lib
+  |   |-- assets
+  |   `-- tasks
+  |-- log
+  |-- public
+  |-- script
+  |-- test
+  |   |-- fixtures
+  |   |-- functional
+  |   |-- integration
+  |   |-- performance
+  |   `-- unit
+  |-- tmp
+  |   `-- cache
+  |       `-- assets
+  `-- vendor
+      |-- assets
+      |   |-- javascripts
+      |   `-- stylesheets
+      `-- plugins
+
+app
+  Holds all the code that's specific to this particular application.
+
+app/assets
+  Contains subdirectories for images, stylesheets, and JavaScript files.
+
+app/controllers
+  Holds controllers that should be named like weblogs_controller.rb for
+  automated URL mapping. All controllers should descend from
+  ApplicationController which itself descends from ActionController::Base.
+
+app/models
+  Holds models that should be named like post.rb. Models descend from
+  ActiveRecord::Base by default.
+
+app/views
+  Holds the template files for the view that should be named like
+  weblogs/index.html.erb for the WeblogsController#index action. All views use
+  eRuby syntax by default.
+
+app/views/layouts
+  Holds the template files for layouts to be used with views. This models the
+  common header/footer method of wrapping views. In your views, define a layout
+  using the <tt>layout :default</tt> and create a file named default.html.erb.
+  Inside default.html.erb, call <% yield %> to render the view using this
+  layout.
+
+app/helpers
+  Holds view helpers that should be named like weblogs_helper.rb. These are
+  generated for you automatically when using generators for controllers.
+  Helpers can be used to wrap functionality for your views into methods.
+
+config
+  Configuration files for the Rails environment, the routing map, the database,
+  and other dependencies.
+
+db
+  Contains the database schema in schema.rb. db/migrate contains all the
+  sequence of Migrations for your schema.
+
+doc
+  This directory is where your application documentation will be stored when
+  generated using <tt>rake doc:app</tt>
+
+lib
+  Application specific libraries. Basically, any kind of custom code that
+  doesn't belong under controllers, models, or helpers. This directory is in
+  the load path.
+
+public
+  The directory available for the web server. Also contains the dispatchers and the
+  default HTML files. This should be set as the DOCUMENT_ROOT of your web
+  server.
+
+script
+  Helper scripts for automation and generation.
+
+test
+  Unit and functional tests along with fixtures. When using the rails generate
+  command, template test files will be generated for you and placed in this
+  directory.
+
+vendor
+  External libraries that the application depends on. Also includes the plugins
+  subdirectory. If the app has frozen rails, those gems also go here, under
+  vendor/rails/. This directory is in the load path.