HashMagic simply contains a couple of spin-off data structures based on the basic Ruby Hash:
1. SlashedHash
2. OrderedHash

You can use either of those separately or in combination. Note that ruby-1.9 Hashes are made to keep their order, but I'm not sure about setting an order explicitly for them, and definitely not setting an order ahead of time.

==SlashedHash
The concept of a SlashedHash is to flatten down a multi-level Hash structure into a single-level Hash whose keys represent the pathway to the data in the original multi-level structure. For example,
  >> sh = {'a' => 'b', 'c' => {'d' => :e, 'f' => ['a', 'b']}, 'd' => ['e', 'f']}.slashed
  => {slashed: "a"=>"b", "c/d"=>:e, "d"=>["e", "f"], "c/f"=>["a", "b"]}

Once you transform a Hash into a SlashedHash, the only negative differences are:
1. All but the end-point (or 'leaf node') data are turned into strings. Restated: Any data at the "end" of a Hash multi-level structure is left alone, but all keys in between, whether string, symbol, or anything else, is turned into a string in order to pack them together into a "slashed" key.
2. Speed. A Ruby Hash is built into the core and written mostly in C so it is very fast; but a SlashedHash clones the same C functionality on all the Hash's methods so that it can act as a normal Hash but with more sugar.

Like I said, the above mentioned things are the only negative differences. You can still access items by their original keys -- to continue the example above,
  >> sh['c']['d']
  => :e
BUT you can also access the same values by their "slashed" keys:
  >> sh['c/d']
  => :e
  >> sh['c/f']
  => ["a", "b"]
And you can access the keys either normally or flattened:
  >> sh.keys
  => ["a", "c", "d"]
  >> sh.flat.keys
  => ["a", "c/d", "d", "c/f"]
Accessing one level into the SlashedHash gives you another SlashedHash, if applicable:
  >> sh['c']
  => {slashed: "d"=>:e, "f"=>["a", "b"]}

==What good is SlashedHash? What can it do for me?

1) It comes in VERY handy when doing special transformations or multi-level key mappings. Think of reading an XML structure into specific property names (example uses the formattedstring gem syntax):
  >> joe = "<person><name>Joe Schmoe</name><age>25</age><parent><name>Joseph Schmoe</name><age>56</age></parent>".formatted(:xml).to_hash.slashed
  => {slashed: "person"=>{"name"=>"Joe Schmoe", "age"=>"25", "parent"=>{"name"=>"Joseph Schmoe", "age"=>"56"}}}
  >> mapping = {'name' => 'person/name', 'age' => 'person/age', 'parent_name' => 'person/parent/name', 'parent_age' => 'person/parent/age'}
  >> joe.transform_keys_with_mapping(mapping)
  => {"name"=>"Joe Schmoe", "parent_name"=>"Joseph Schmoe", "age"=>"25", "parent_age"=>"56"}

2) It is useful for sorting multi-level hashes by integration with OrderedHash.

 / / / Still writing, will come back to this sometime... :) / / /