NAME map.rb

SYNOPSIS the awesome ruby container you've always wanted: a string/symbol indifferent ordered hash that works in all rubies

maps are bitchin ordered hashes that are both ordered, string/symbol indifferent, and have all sorts of sweetness like recursive conversion, more robust implementation than HashWithIndifferentAccess, support for struct like (map.foo) access, and support for option/keyword access which avoids several nasty classes of errors in many ruby libraries

INSTALL gem install map

URI http://github.com/ahoward/map

DESCRIPTION

maps are always ordered. constructing them in an ordered fashion builds

them that way, although the normal hash contructor is also supported

m = Map[:k, :v, :key, :val] m = Map(:k, :v, :key, :val) m = Map.new(:k, :v, :key, :val)

m = Map[[:k, :v], [:key, :val]] m = Map(:k => :v, :key => :val) # ruh-oh, the input hash loses order! m = Map.new(:k => :v, :key => :val) # ruh-oh, the input hash loses order!

m = Map.new m[:a] = 0 m[:b] = 1 m[:c] = 2

p m.keys #=> ['a','b','c'] ### always ordered! p m.values #=> [0,1,2] ### always ordered!

maps don't care about symbol vs.string keys

p m[:a] #=> 0 p m["a"] #=> 0

even via deep nesting

p m[:foo]['bar'][:baz] #=> 42

many functions operate in a way one would expect from an ordered container

m.update(:k2 => :v2) m.update(:k2, :v2)

key_val_pair = m.shift key_val_pair = m.pop

maps keep mapiness for even deep operations

m.update :nested => {:hashes => {:are => :converted}}

maps can give back clever little struct objects

m = Map(:foo => {:bar => 42}) s = m.struct p s.foo.bar #=> 42

because option parsing is such a common use case for needing string/symbol

indifference map.rb comes out of the box loaded with option support

def foo(*args, &block) opts = Map.options(args) a = opts.getopt(:a) b = opts.getopt(:b, :default => false) end

opts = Map.options(:a => 42, :b => nil, :c => false) opts.getopt(:a) #=> 42 opts.getopt(:b) #=> nil opts.getopt(:b, :default => 42) #=> 42 opts.getopt(:c) #=> false opts.getopt(:d, :default => false) #=> false

this avoids such bugs as

options = {:read_only => false} read_only = options[:read_only] || true # should be false but is true

with options this becomes

options = Map.options(:read_only => true) read_only = options.getopt(:read_only, :default => false) #=> true

maps support some really nice operators that hashes/orderedhashes do not

m = Map.new m.set(:h, :a, 0, 42) m.has?(:h, :a) #=> true p m #=> {'h' => {'a' => [42]}} m.set(:h, :a, 1, 42.0) p m #=> {'h' => {'a' => [42, 42.0]}}

m.get(:h, :a, 1) #=> 42.0 m.get(:x, :y, :z) #=> nil m[:x][:y][:z] #=> raises exception!

m = Map.new(:array => [0,1]) defaults = {:array => [nil, nil, 2]} m.apply(defaults) p m[:array] #=> [0,1,2]

they also support some different iteration styles

m = Map.new

m.set( [:a, :b, :c, 0] => 0, [:a, :b, :c, 1] => 10, [:a, :b, :c, 2] => 20, [:a, :b, :c, 3] => 30 )

m.set(:x, :y, 42) m.set(:x, :z, 42.0)

m.depth_first_each do |key, val| p key => val end

#=> [:a, :b, :c, 0] => 0 #=> [:a, :b, :c, 1] => 10 #=> [:a, :b, :c, 2] => 20 #=> [:a, :b, :c, 3] => 30 #=> [:x, :y] => 42 #=> [:x, :z] => 42.0

USAGE see lib/map.rb and test/map_test.rb

HISTORY 4.3.0: - support for dot keys. map.set('a.b.c' => 42) #=> {'a'=>{'b'=>{'c'=>42}}}