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.keys #=> [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