Hashie

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

Table of Contents

• Installation
• Stable Release
• Hash Extensions
• Logging
  • Coercion
  • Coercing Collections
  • Coercing Hashes
  • Coercing Core Types
  • Coercion Proc
    • A note on circular coercion
  • KeyConversion
  • MergeInitializer
  • MethodAccess
  • MethodAccessWithOverride
  • MethodOverridingInitializer
  • IndifferentAccess
  • IgnoreUndeclared
  • DeepMerge
  • DeepFetch
  • DeepFind
  • DeepLocate
• StrictKeyAccess
• Mash
  • KeepOriginalKeys
  • PermissiveRespondTo
  • SafeAssignment
  • SymbolizeKeys
  • DefineAccessors
• Dash
  • Potential Gotchas
  • PropertyTranslation
  • Mash and Rails 4 Strong Parameters
  • Coercion
  • PredefinedValues
• Trash
• Clash
• Rash
  • Auto-Optimized
• Mascot
• Contributing
• Copyright

Installation

Hashie is available as a RubyGem:

$ gem install hashie

Stable Release

You're reading the documentation for the next release of Hashie, which should be 5.1.1. The current stable release is 5.1.0.

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:

# Set the logger to the Rails logger
Hashie.logger = Rails.logger

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:

class Tweet < Hash
  include Hashie::Extensions::Coercion
  include Hashie::Extensions::MergeInitializer
  coerce_key :user, User
end

user_hash = { name: "Bob" }
Tweet.new(user: user_hash)
# => automatically calls User.coerce(user_hash) or
#    User.new(user_hash) if that isn't present.

Value coercions, on the other hand, will coerce values based on the type of the value being inserted. This is useful if you are trying to build a Hash-like class that is self-propagating.

class SpecialHash < Hash
  include Hashie::Extensions::Coercion
  coerce_value Hash, SpecialHash

  def initialize(hash = {})
    super
    hash.each_pair do |k,v|
      self[k] = v
    end
  end
end

Coercing Collections

class Tweet < Hash
  include Hashie::Extensions::Coercion
  coerce_key :mentions, Array[User]
  coerce_key :friends, Set[User]
end

user_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 Hashes

class Relation
  def initialize(string)
    @relation = string
  end
end

class Tweet < Hash
  include Hashie::Extensions::Coercion
  coerce_key :relations, Hash[User => Relation]
end

user_hash = { name: "Bob" }
relations_hash= { user_hash => "father", user_hash => "friend" }
tweet = Tweet.new(relations: relations_hash)
tweet.relations.map { |k,v| [k.class, v.class] } # => [[User, Relation], [User, Relation]]
tweet.relations.class # => Hash

# => automatically calls User.coerce(user_hash) on each key
#    and Relation.new on each value since Relation doesn't define the `coerce` class method

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:

class Tweet < Hash
  include Hashie::Extensions::Coercion
  coerce_key :retweeted, ->(v) do
    case v
    when String
      !!(v =~ /\A(true|t|yes|y|1)\z/i)
    when Numeric
      !v.to_i.zero?
    else
      v == true
    end
  end
end

A note on circular coercion

Since coerce_key is a class-level method, you cannot have circular coercion without the use of a proc. For example:

class CategoryHash < Hash
  include Hashie::Extensions::Coercion
  include Hashie::Extensions::MergeInitializer

  coerce_key :products, Array[ProductHash]
end

class ProductHash < Hash
  include Hashie::Extensions::Coercion
  include Hashie::Extensions::MergeInitializer

  coerce_key :categories, Array[CategoriesHash]
end

This will fail with a NameError for CategoryHash::ProductHash because ProductHash is not defined at the point that coerce_key is happening for CategoryHash.

To work around this, you can use a coercion proc. For example, you could do:

class CategoryHash < Hash
  # ...
  coerce_key :products, ->(value) do
    return value.map { |v| ProductHash.new(v) } if value.respond_to?(:map)

    ProductHash.new(value)
  end
end

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:

Hashie.symbolize_keys! hash # => Symbolizes all string keys of hash.
Hashie.symbolize_keys hash # => Returns a copy of hash with string keys symbolized.
Hashie.stringify_keys! hash # => Stringifies keys of hash.
Hashie.stringify_keys hash # => Returns a copy of hash with keys stringified.

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.

class MyHash < Hash
  include Hashie::Extensions::MethodAccess
end

h = MyHash.new
h.abc = 'def'
h.abc  # => 'def'
h.abc? # => true

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.

class MyHash < Hash
  include Hashie::Extensions::MethodAccess
end

class MyOverridingHash < Hash
  include Hashie::Extensions::MethodAccessWithOverride
end

non_overriding = MyHash.new
non_overriding.zip = 'a-dee-doo-dah'
non_overriding.zip #=> [[['zip', 'a-dee-doo-dah']]]

overriding = MyOverridingHash.new
overriding.zip = 'a-dee-doo-dah'
overriding.zip   #=> 'a-dee-doo-dah'
overriding.__zip #=> [[['zip', 'a-dee-doo-dah']]]

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.

class MyHash < Hash
end

class MyOverridingHash < Hash
  include Hashie::Extensions::MethodOverridingInitializer
end

non_overriding = MyHash.new(zip: 'a-dee-doo-dah')
non_overridin