Ishin

Ishin converts Ruby objects into their Hash representations. It works with plain old classes, extended classes, classes with mixins, and hashes (see Usage for more on that).

Installation

Add this line to your application's Gemfile:

gem 'ishin'

And then execute:

bundle

Or install it manually by:

gem install ishin

Example

As a class method callable on any object:

require 'ishin'

hash = Ishin.to_hash(my_object)

Or included in your object as a mixin:

class YourClass
  include Ishin::Mixin
  # etc.
end

instance = YourClass.new
hash = instance.to_hash

Usage

A simple example is worth a thousand words:

class Animal
  attr_reader :leg_count

  def initialize leg_count
    @leg_count = leg_count
  end
end

dog = Animal.new(4)

dog_hash = Ishin.to_hash(dog)
# => {:leg_count=>4}

Recursion

Ishin also handles object instances nested within other object instances. By default, recursive hash conversion is turned off. To enable recursion, set the recursive option to true:

test_struct = Struct.new(:value)
nested_structs = test_struct.new(test_struct.new('value'))


Ishin.to_hash(nested_structs, recursive: true)
# => {:value=>{:value=>"value"}}

Recursion Depth

For deeply nested object instances, a maximum recursion depth can be provided in combination with the recursive option. The default recursion depth is one (initial call + 1).

nest_me = Struct.new(:value)
deep_nesting = nest_me.new(nest_me.new(nest_me.new(nest_me.new('such depth'))))

Ishin.to_hash(deep_nesting, recursive: true, recursion_depth: 2)
# => {:value=>{:value=>{:value=>#<struct value="such depth">}}}

Notice in the above example that the recursion stopped after 3 steps (initial call + 2).

Expanding Hashes using Recursion

Using recursion, it is also possible to convert hashes containing object instances to a hash-only representation as well. Notice that this only works if the recursive option is provided.

another_struct = Struct.new(:value)
my_hash = {
  my_struct: another_struct.new("yup, it's a struct")
}

Ishin.to_hash(my_hash, recursive: true)
# => {:my_struct=>{:value=>"yup, it's a struct"}}

Keep in mind that the recursive option works in conjunction with the recursion_depth option.

Symbolizing Keys

By default, Ishin stores key names as symbols. This behavior can be disabled by setting the symbolize option to false.

class Dog
  attr_reader :says

  def initialize(says)
    @says = says
  end
end

lassie = Dog.new('Timmy is stuck in a well!')

Ishin.to_hash(lassie)
# => {:says=>"Timmy is stuck in a well!"}
Ishin.to_hash(lassie, symbolize: false)
# => {"says"=>"Timmy is stuck in a well!"}

When setting the symbolize option to false, the explicit conversion of strings to symbols is prevented. This, however, does not mean that hashes whose keys are already symbols are converted into string-based keys.

Evaluating Methods

Normally, Ishin does not evaluate methods, but is possible to do so through the optional evaluate option by passing it an array of method names to evaluate.

class Speaker
  def say
    "Say what?"
  end
end

speaker = Speaker.new
# => #<Speaker:0x007fb2bb1812d8>
Ishin.to_hash(speaker, evaluate: [ :say ])
# => {:say=>"Say what?"}

It is currently only possible to evaluate methods that do not require arguments.

As a Mixin

To use Ishin as a mixin in your own objects, simply include Ishin::Mixin:

class MyObject
  include Ishin::Mixin
  # etc.
end

Your object now exposes a method named to_hash taking the same options at the Ishin::to_hash class method documented above.

Running the Specs

Once bundle is executed, simply run:

rake spec

Changelog

• 0.1.0
  • Initial release.
• 0.2.0
  • Added Ishin::Mixin.
• 0.2.1
  • Now using Struct.to_h when converting a Struct instance.