Project

hash_miner

0.0
The project is in a healthy, maintained state
Additional Hash methods to help navigate the tricky world of nested Hashes.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

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.