HashMiner
Ever experienced the pain of working with deeply nested hashes in Ruby?
HashMiner expands the base Hash class in Ruby to provide helpful methods to traverse and manipulate your Hash Object regardless of complexity.
The following gives a flavour of how HashMiner can help solve headaches when working with complex hashes:
require 'hash_miner'
hash = { my: { super: { duper: { deeply: 'nested hash' } } } }
# Deleting a key #
# Without HashMiner
hash[:my][:super].delete(:duper) # => {:deeply=>"nested hash"}
# With HashMiner
hash.deep_remove(key: :duper) # => {:my=>{:super=>{}}}
# Updating a key #
# Without HashMiner
hash[:my][:super][:duper][:deeply] = 'modified nested hash' # => "modified nested hash"
# With HashMiner
hash.deep_update(key: :deeply, value: 'modified nested hash') # => {:my=>{:super=>{:duper=>{:deeply=>"modified nested hash"}}}}
# Checking a key exists #
# Without HashMiner
hash[:my][:super][:duper][:deeply] # => "nested hash"
# With HashMiner
hash.deep_find(key: :deeply) # => ["nested hash"]
Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add hash_miner
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install hash_miner
Usage
- HashMiner methods have no side-effects
Methods available
deep_update
- Updates all values that match the given key
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: :nasty } } }
nasty_hash.deep_update(key: :nasty, value: :complicated_hash) # => {:my=>{:pretty=>[{:nasty=>:complicated_hash}, nil], :is=>{:pretty=>:nasty}}}
# Errors on uniqueness
nasty_hash.deep_update(key: :pretty, value: :super_duper) # => throws KeyNotUniqueError
nasty_hash.deep_update(key: :pretty, value: :super_duper, error_on_uniqueness: false) # => {:my=>{:pretty=>:super_duper, :is=>{:pretty=>:super_duper}}}
# Errors on missing
nasty_hash.deep_update(key: :huh, value: :where_am_i) # => throws KeyNotFoundError
nasty_hash.deep_update(key: :pretty, value: :super_duper, error_on_missing: false) # => {:my=>{:pretty=>[{:nasty=>:hash}, nil], :is=>{:pretty=>:nasty}}, :huh=>:where_am_i}
# Pass through parent flag for scoping
nasty_hash.deep_update(key: :pretty, value: :super_duper, error_on_uniqueness: false, parent: :is) # => {:my=>{:pretty=>[{:nasty=>:hash}, nil], :is=>{:pretty=>:super_duper}}}
deep_remove
- Removes all values that match the given key
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: :nasty } } }
nasty_hash.deep_remove(key: :nasty) # => {:my=>{:pretty=>[{}, nil], :is=>{:pretty=>:nasty}}}
# Errors on uniqueness
nasty_hash.deep_remove(key: :pretty) # => throws KeyNotUniqueError
nasty_hash.deep_remove(key: :pretty, error_on_uniqueness: false) # => {:my=>{:is=>{}}}
# Pass through parent flag for scoping
nasty_hash.deep_remove(key: :pretty, error_on_uniqueness: false, parent: :is) # => { my: { pretty: [{ nasty: :hash }, nil], is: { } } }
deep_find
- Returns all values that match the given key
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: :nasty } } }
nasty_hash.deep_find(key: :nasty) # => [:hash]
nasty_hash.deep_find(key: :pretty) # => [{:nasty=>:hash}, nil, :nasty]
# Pass through parent flag for scoping
nasty_hash.deep_find(key: :pretty, parent: :is) # => [:nasty]
deep_compact
- Removes nil and empty values from Hash
- Will not remove values within an Array i.e
[nil, {}]
will remain
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: {}, nasty: nil } } }
nasty_hash.deep_compact # => {:my=>{:pretty=>[{:nasty=>:hash}, nil]}}
deep_count
- Returns a count for the given key
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: :nasty } } }
nasty_hash.deep_count(key: :pretty) # => 2
nasty_hash.deep_count(key: :nasty) # => 1
deep_contains?
- Returns
true|false
depending on if given is found
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: :nasty } } }
nasty_hash.deep_contains?(key: :nasty) # => true
nasty_hash.deep_contains?(key: :super_nasty) # => false
Scoping
HashMiner supports partial updating of a hash based on the parent key.
Supported methods:
deep_find
deep_update
deep_remove
Pass through a parent
key to any of these methods as either an Array
|String
|Symbol
require 'hash_miner'
nasty_hash = { my: { pretty: [{ nasty: :hash }, nil], is: { pretty: :nasty } } }
nasty_hash.deep_find(key: :pretty, parent: :is) # => [:nasty]
nasty_hash.deep_find(key: :pretty, parent: [:is]) # => [:nasty]
nasty_hash.deep_find(key: :pretty, parent: [:my, :is]) # => [{:nasty=>:hash}, nil, :nasty]
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
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 the created tag, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hash_miner.
License
The gem is available as open source under the terms of the MIT License.