Allowable

Filter hashes by setting allowed or forbidden values for specific keys.

Installation

Add this line to your application's Gemfile:

gem'allowable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install allowable

Usage

The gem will add four methods to Hash: #allow, #allow!, #forbid, and #forbid!

hash={one: 'one',two: 'two'}hash.forbid(one: 'one')# => { two: 'two' }hash.allow(one: 'two')# => { two: 'two' }hash.allow(one: ['one','two'])# => { one: 'one', two: 'two' }hash.forbid(one: ['one','two'])# => { two: 'two' }hash.allow!(one: 'two')# => { two: 'two' }hash.forbid!(two: 'two')# => {}hash# => {}hash.merge(one: ['one',1]).forbid(one: 'one')# => { one: ["one", 1] }hash.merge(one: ['one',1]).forbid(one: ['one',1])# => {}

Type sensitive for Hash

hash={'one'=>'one','two'=>'two'}hash.forbid(one: 'one')# => { "one" => "one", "two" => "two" }hash.forbid('one'=>'one')# => { "two" => "two" }

With Rails and strong parameters

If ActiveSupport::HashWithIndifferentAccess is defined it will receive the methods. This automatically makes them available in ActionController::Parameters for Rails 4 and 3. Rails 3 requires that you add gem 'strong_parameters' to your Gemfile in order to use strong parameters.

Starting in Rails 5, ActionController::Parameters no longer inherits from ActiveSupport::HashWithIndifferentAccess. When allowable is added to the Gemfile in a Rails 5+ project, load hooks will add the methods directly to ActionController::Parameters so you can use them with your strong parameters.

defuser_paramsparams.require(:user).permit(:email,:password,:role).forbid(role: ['sys_admin','owner'])end

Type insensitive for HashWithIndifferentAccess and ActionController::Parameters

params=ActionController::Parameters.new('one'=>'one','two'=>'two').permit(:one,:two)params.forbid(one: 'one').to_h# => { "two" => "two" }params.forbid('one'=>'one').to_h# => { "two" => "two" }

If your custom Hash-like class implements #delete and the #[] finder, you can include Allowable to mix in the methods.

classMyHashincludeAllowableend

Platform support

The core module should work with all rubies. It is tested for MRI Ruby >= 1.9.3 and JRuby 9.1.6.0

Rails compatibility is currently being tested only for versions ~> 3.2, ~> 4.2, and ~> 5.1.

Tested against:

• MRI 1.9.3
• MRI 2.0.0
• MRI 2.1.10
• MRI 2.2.2
• MRI 2.3.0
• MRI 2.3.4
• MRI 2.4.1
• JRuby 9.1.6.0
• JRuby HEAD
• MRI HEAD

Development

After checking out the repo, run bin/setup to install dependencies. The manual steps are:

$ bundle install
$ bundle exec appraisal install

Run bin/console for an IRB session with all dependencies loaded.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/msimonborg/allowable.

Steps to contribute

• Write new tests that describe the desired behavior, or catch regressions. PRs won't be approved without test coverage
• Write your code
• Run build task with bundle exec rake, make sure all tests pass and there are no Rubocop issues
• Run bundle exec appraisal rake to run tests against different Rails versions
• Add documentation to README.md if appropriate and necessary
• Commit with a descriptive message
• Submit a PR

License

The gem is available as open source under the terms of the MIT License.