Hashie

Hashie is a growing collection of tools that extend Hashes and make them more useful.

Installation

Hashie is available as a RubyGem:

$ gem install hashie

Upgrading

You're reading the documentation for the stable release of Hashie, 3.6.0. Please read UPGRADING when upgrading from a previous version.

Hash Extensions

The library is broken up into a number of atomically includable Hash extension modules as described below. This provides maximum flexibility for users to mix and match functionality while maintaining feature parity with earlier versions of Hashie.

Any of the extensions listed below can be mixed into a class by include-ing Hashie::Extensions::ExtensionName.

Logging

Hashie has a built-in logger that you can override. By default, it logs to STDOUT but can be replaced by any Logger class. The logger is accessible on the Hashie module, as shown below:

Coercion

Coercions allow you to set up "coercion rules" based either on the key or the value type to massage data as it's being inserted into the Hash. Key coercions might be used, for example, in lightweight data modeling applications such as an API client:

Coercing Collections

classTweet<HashincludeHashie::Extensions::Coercioncoerce_key:mentions,Array[User]coerce_key:friends,Set[User]enduser_hash={name:"Bob"}mentions_hash=[user_hash,user_hash]friends_hash=[user_hash]tweet=Tweet.new(mentions:mentions_hash,friends:friends_hash)# => automatically calls User.coerce(user_hash) or
# User.new(user_hash) if that isn't present on each element of the array
tweet.mentions.map(&:class)# => [User, User]
tweet.friends.class# => Set

Coercing Core Types

Hashie handles coercion to the following by using standard conversion methods:

type

method

Integer

#to_i

Float

#to_f

Complex

#to_c

Rational

#to_r

String

#to_s

Symbol

#to_sym

Note: The standard Ruby conversion methods are less strict than you may assume. For example, :foo.to_i raises an error but "foo".to_i returns 0.

You can also use coerce from the following supertypes with coerce_value:

Integer

Numeric

Hashie does not have built-in support for coercing boolean values, since Ruby does not have a built-in boolean type or standard method for coercing to a boolean. You can coerce to booleans using a custom proc.

Coercion Proc

You can use a custom coercion proc on either #coerce_key or #coerce_value. This is useful for coercing to booleans or other simple types without creating a new class and coerce method. For example:

KeyConversion

The KeyConversion extension gives you the convenience methods of symbolize_keys and stringify_keys along with their bang counterparts. You can also include just stringify or just symbolize with Hashie::Extensions::StringifyKeys or Hashie::Extensions::SymbolizeKeys.

Hashie also has a utility method for converting keys on a Hash without a mixin:

MergeInitializer

The MergeInitializer extension simply makes it possible to initialize a Hash subclass with another Hash, giving you a quick short-hand.

MethodAccess

The MethodAccess extension allows you to quickly build method-based reading, writing, and querying into your Hash descendant. It can also be included as individual modules, i.e. Hashie::Extensions::MethodReader, Hashie::Extensions::MethodWriter and Hashie::Extensions::MethodQuery.

MethodAccessWithOverride

The MethodAccessWithOverride extension is like the MethodAccess extension, except that it allows you to override Hash methods. It aliases any overridden method with two leading underscores. To include only this overriding functionality, you can include the single module Hashie::Extensions::MethodOverridingWriter.

MethodOverridingInitializer

The MethodOverridingInitializer extension will override hash methods if you pass in a normal hash to the constructor. It aliases any overridden method with two leading underscores. To include only this initializing functionality, you can include the single module Hashie::Extensions::MethodOverridingInitializer.

DeepFetch

This extension can be mixed in to provide for safe and concise retrieval of deeply nested hash values. In the event that the requested key does not exist a block can be provided and its value will be returned.

Though this is a hash extension, it conveniently allows for arrays to be present in the nested structure. This feature makes the extension particularly useful for working with JSON API responses.

DeepLocate

This extension can be mixed in to provide a depth first search based search for enumerables matching a given comparator callable.

It returns all enumerables which contain at least one element, for which the given comparator returns true.

Because the container objects are returned, the result elements can be modified in place. This way, one can perform modifications on deeply nested hashes without the need to know the exact paths.

books=[{title:"Ruby for beginners",pages:120},{title:"CSS for intermediates",pages:80},{title:"Collection of ruby books",books:[{title:"Ruby for the rest of us",pages:576}]}]books.extend(Hashie::Extensions::DeepLocate)# for ruby 1.9 leave *no* space between the lambda rocket and the braces
# http://ruby-journal.com/becareful-with-space-in-lambda-hash-rocket-syntax-between-ruby-1-dot-9-and-2-dot-0/
books.deep_locate->(key,value,object){key==:title&&value.include?("Ruby")}# => [{:title=>"Ruby for beginners", :pages=>120}, {:title=>"Ruby for the rest of us", :pages=>576}]
books.deep_locate->(key,value,object){key==:pages&&value<=120}# => [{:title=>"Ruby for beginners", :pages=>120}, {:title=>"CSS for intermediates", :pages=>80}]

StrictKeyAccess

This extension can be mixed in to allow a Hash to raise an error when attempting to extract a value using a non-existent key.

Mash

Mash is an extended Hash that gives simple pseudo-object functionality that can be built from hashes and easily extended. It is intended to give the user easier access to the objects within the Mash through a property-like syntax, while still retaining all Hash functionality.

Note: The ? method will return false if a key has been set to false or nil. In order to check if a key has been set at all, use the mash.key?('some_key') method instead.

How does Mash handle conflicts with pre-existing methods?

Please note that a Mash will not override methods through the use of the property-like syntax. This can lead to confusion if you expect to be able to access a Mash value through the property-like syntax for a key that conflicts with a method name. However, it protects users of your library from the unexpected behavior of those methods being overridden behind the scenes.

Example:

Since Mash gives you the ability to set arbitrary keys that then act as methods, Hashie logs when there is a conflict between a key and a pre-existing method. You can set the logger that this logs message to via the global Hashie logger:

How does the wrapping of Mash sub-Hashes work?

Mash duplicates any sub-Hashes that you add to it and wraps them in a Mash. This allows for infinite chaining of nested Hashes within a Mash without modifying the object(s) that are passed into the Mash. When you subclass Mash, the subclass wraps any sub-Hashes in its own class. This preserves any extensions that you mixed into the Mash subclass and allows them to work within the sub-Hashes, in addition to the main containing Mash.

Mash Extension: KeepOriginalKeys

This extension can be mixed into a Mash to keep the form of any keys passed directly into the Mash. By default, Mash converts keys to strings to give indifferent access. This extension still allows indifferent access, but keeps the form of the keys to eliminate confusion when you're not expecting the keys to change.

Mash Extension: SafeAssignment

This extension can be mixed into a Mash to guard the attempted overwriting of methods by property setters. When mixed in, the Mash will raise an ArgumentError if you attempt to write a property with the same name as an existing method.

There is a major benefit and coupled with a major trade-off to this decision (at least on older Rubies). As a benefit, by using symbols as keys, you will be able to use the implicit conversion of a Mash via the #to_hash method to destructure (or splat) the contents of a Mash out to a block. This can be handy for doing iterations through the Mash's keys and values, as follows:

symbol_mash=SymbolizedMash.new(id:123,name:'Rey')symbol_mash.eachdo|key,value|# key is :id, then :name
# value is 123, then 'Rey'
end

However, on Rubies less than 2.0, this means that every key you send to the Mash will generate a symbol. Since symbols are not garbage-collected on older versions of Ruby, this can cause a slow memory leak when using a symbolized Mash with data generated from user input.

Dash

Dash is an extended Hash that has a discrete set of defined properties and only those properties may be set on the hash. Additionally, you can set defaults for each property. You can also flag a property as required. Required properties will raise an exception if unset. Another option is message for required properties, which allow you to add custom messages for required property.

You can also conditionally require certain properties by passing a Proc or Symbol. If a Proc is provided, it will be run in the context of the Dash instance. If a Symbol is provided, the value returned for the property or method of the same name will be evaluated. The property will be required if the result of the conditional is truthy.

Potential gotchas

Because Dashes are subclasses of the built-in Ruby Hash class, the double-splat operator takes the Dash as-is without any conversion. This can lead to strange behavior when you use the double-splat operator on a Dash as the first part of a keyword list or built Hash. For example:

Mash and Rails 4 Strong Parameters

Dash Extension: Coercion.

If you want to use Hashie::Extensions::Coercion together with Dash then
you may probably want to use Hashie::Extensions::Dash::Coercion instead.
This extension automatically includes Hashie::Extensions::Coercion
and also adds a convenient :coerce option to property so you can define coercion in one line
instead of using property and coerce_key separate: