From: "ara.t.howard" <ara.t.howard@...>
Date: 2010-12-24T16:48:32+09:00
Subject: [ANN] map.rb 2.0.0

------=_Part_560_12723549.1293176775969
Content-Type: multipart/alternative; 
	boundary="----=_Part_561_2307975.1293176775969"

------=_Part_561_2307975.1293176775969
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

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!

# 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


------=_Part_561_2307975.1293176775969
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<div>NAME</div><div>&nbsp;&nbsp;map.rb</div><div><br></div><div>SYNOPSIS</d=
iv><div>&nbsp;&nbsp;the awesome ruby container you've always wanted: a stri=
ng/symbol indifferent</div><div>&nbsp;&nbsp;ordered hash that works in all =
rubies</div><div><br></div><div>&nbsp;&nbsp;maps are bitchin ordered hashes=
 that are both ordered, string/symbol</div><div>&nbsp;&nbsp;indifferent, an=
d have all sorts of sweetness like recursive conversion, more</div><div>&nb=
sp;&nbsp;robust implementation than HashWithIndifferentAccess, support for =
struct</div><div>&nbsp;&nbsp;like (map.foo) access, and support for option/=
keyword access which avoids</div><div>&nbsp;&nbsp;several nasty classes of =
errors in many ruby libraries</div><div><br></div><div>INSTALL</div><div>&n=
bsp;&nbsp;gem install map</div><div><br></div><div>URI</div><div>&nbsp;&nbs=
p;http://github.com/ahoward/map</div><div><br></div><div>DESCRIPTION</div><=
div><br></div><div># maps are always ordered. &nbsp;constructing them in an=
 ordered fashion builds</div><div># them that way, although the normal hash=
 contructor is also supported</div><div>#</div><div>&nbsp;&nbsp;m =3D Map[:=
k, :v, :key, :val]</div><div>&nbsp;&nbsp;m =3D Map(:k, :v, :key, :val)</div=
><div>&nbsp;&nbsp;m =3D Map.new(:k, :v, :key, :val)</div><div><br></div><di=
v>&nbsp;&nbsp;m =3D Map[[:k, :v], [:key, :val]]</div><div>&nbsp;&nbsp;m =3D=
 Map(:k =3D&gt; :v, :key =3D&gt; :val) &nbsp;# ruh-oh, the input hash loses=
 order!</div><div>&nbsp;&nbsp;m =3D Map.new(:k =3D&gt; :v, :key =3D&gt; :va=
l) &nbsp;# ruh-oh, the input hash loses order!</div><div><br></div><div><br=
></div><div>&nbsp;&nbsp;m =3D Map.new</div><div>&nbsp;&nbsp;m[:a] =3D 0</di=
v><div>&nbsp;&nbsp;m[:b] =3D 1</div><div>&nbsp;&nbsp;m[:c] =3D 2</div><div>=
<br></div><div>&nbsp;&nbsp;p m.keys #=3D&gt; ['a','b','c'] &nbsp;### always=
 ordered!</div><div>&nbsp;&nbsp;p m.keys #=3D&gt; [0,1,2] &nbsp; &nbsp; &nb=
sp; &nbsp;### always ordered!</div><div><br></div><div># maps don't care ab=
out symbol vs.string keys</div><div>#</div><div>&nbsp;&nbsp;p m[:a] &nbsp;#=
=3D&gt; 0</div><div>&nbsp;&nbsp;p m["a"] #=3D&gt; 0</div><div><br></div><di=
v># even via deep nesting&nbsp;</div><div>#</div><div>&nbsp;&nbsp;p m[:foo]=
['bar'][:baz] &nbsp;#=3D&gt; 42</div><div><br></div><div># many functions o=
perate in a way one would expect from an ordered container</div><div>#</div=
><div>&nbsp;&nbsp;m.update(:k2 =3D&gt; :v2)</div><div>&nbsp;&nbsp;m.update(=
:k2, :v2)</div><div><br></div><div>&nbsp;&nbsp;key_val_pair =3D m.shift</di=
v><div>&nbsp;&nbsp;key_val_pair =3D m.pop</div><div><br></div><div># maps k=
eep mapiness for even deep operations</div><div>#</div><div>&nbsp;&nbsp;m.u=
pdate :nested =3D&gt; {:hashes =3D&gt; {:are =3D&gt; :converted}}</div><div=
><br></div><div># maps can give back clever little struct objects</div><div=
>#</div><div>&nbsp;&nbsp;m =3D Map(:foo =3D&gt; {:bar =3D&gt; 42})</div><di=
v>&nbsp;&nbsp;s =3D m.struct</div><div>&nbsp;&nbsp;p s.foo.bar #=3D&gt; 42<=
/div><div><br></div><div># because option parsing is such a common use case=
 for needing string/symbol</div><div># indifference map.rb comes out of the=
 box loaded with option support</div><div>#</div><div>&nbsp;&nbsp;def foo(*=
args, &amp;block)</div><div>&nbsp;&nbsp; &nbsp;opts =3D Map.options(args)</=
div><div>&nbsp;&nbsp; &nbsp;a =3D opts.getopt(:a)</div><div>&nbsp;&nbsp; &n=
bsp;b =3D opts.getopt(:b, :default =3D&gt; false)</div><div>&nbsp;&nbsp;end=
</div><div><br></div><div><br></div><div>&nbsp;&nbsp;opts =3D Map.options(:=
a =3D&gt; 42, :b =3D&gt; nil, :c =3D&gt; false)</div><div>&nbsp;&nbsp;opts.=
getopt(:a) &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &=
nbsp;#=3D&gt; 42</div><div>&nbsp;&nbsp;opts.getopt(:b) &nbsp; &nbsp; &nbsp;=
 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;#=3D&gt; nil</div><div>&nb=
sp;&nbsp;opts.getopt(:b, :default =3D&gt; 42) &nbsp; &nbsp;#=3D&gt; 42&nbsp=
;</div><div>&nbsp;&nbsp;opts.getopt(:c) &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; =
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;#=3D&gt; false</div><div>&nbsp;&nbsp;opts=
.getopt(:d, :default =3D&gt; false) #=3D&gt; false</div><div><br></div><div=
># this avoids such bugs as</div><div># &nbsp;</div><div>&nbsp;&nbsp;option=
s =3D {:read_only =3D&gt; false}</div><div>&nbsp;&nbsp;read_only =3D option=
s[:read_only] || true &nbsp;# should be false but is true</div><div><br></d=
iv><div># with options this becomes</div><div>#</div><div>&nbsp;&nbsp;optio=
ns =3D Map.options(:read_only =3D&gt; true)</div><div>&nbsp;&nbsp;read_only=
 =3D options.getopt(:read_only, :default =3D&gt; false) #=3D&gt; true</div>=
<div><br></div><div># maps support some really nice operators that hashes/o=
rderedhashes do not</div><div>#</div><div>&nbsp;&nbsp;m =3D Map.new</div><d=
iv>&nbsp;&nbsp;m.set(:h, :a, 0, 42)</div><div>&nbsp;&nbsp;m.has?(:h, :a) &n=
bsp; &nbsp; &nbsp; &nbsp; #=3D&gt; true</div><div>&nbsp;&nbsp;p m &nbsp; &n=
bsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;#=3D&gt; {'h' =
=3D&gt; {'a' =3D&gt; [42]}}&nbsp;</div><div>&nbsp;&nbsp;m.set(:h, :a, 1, 42=
.0)</div><div>&nbsp;&nbsp;p m &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nb=
sp; &nbsp; &nbsp; &nbsp;#=3D&gt; {'h' =3D&gt; {'a' =3D&gt; [42, 42.0]}}&nbs=
p;</div><div><br></div><div>&nbsp;&nbsp;m.get(:h, :a, 1) &nbsp; &nbsp; &nbs=
p; #=3D&gt; 42.0</div><div>&nbsp;&nbsp;m.get(:x, :y, :z) &nbsp; &nbsp; &nbs=
p;#=3D&gt; nil</div><div>&nbsp;&nbsp;m[:x][:y][:z] &nbsp; &nbsp; &nbsp; &nb=
sp; &nbsp;#=3D&gt; raises exception!</div><div><br></div><div># they also s=
upport some different iteration styles</div><div>#</div><div>&nbsp;&nbsp;m =
=3D Map.new</div><div><br></div><div>&nbsp;&nbsp;m.set(</div><div>&nbsp;&nb=
sp; &nbsp;[:a, :b, :c, 0] =3D&gt; 0,</div><div>&nbsp;&nbsp; &nbsp;[:a, :b, =
:c, 1] =3D&gt; 10,</div><div>&nbsp;&nbsp; &nbsp;[:a, :b, :c, 2] =3D&gt; 20,=
</div><div>&nbsp;&nbsp; &nbsp;[:a, :b, :c, 3] =3D&gt; 30</div><div>&nbsp;&n=
bsp;)</div><div><br></div><div>&nbsp;&nbsp;m.set(:x, :y, 42)</div><div>&nbs=
p;&nbsp;m.set(:x, :z, 42.0)</div><div><br></div><div>&nbsp;&nbsp;m.depth_fi=
rst_each do |key, val|</div><div>&nbsp;&nbsp; &nbsp;p key =3D&gt; val</div>=
<div>&nbsp;&nbsp;end</div><div><br></div><div>&nbsp;&nbsp;#=3D&gt; [:a, :b,=
 :c, 0] =3D&gt; 0</div><div>&nbsp;&nbsp;#=3D&gt; [:a, :b, :c, 1] =3D&gt; 10=
</div><div>&nbsp;&nbsp;#=3D&gt; [:a, :b, :c, 2] =3D&gt; 20</div><div>&nbsp;=
&nbsp;#=3D&gt; [:a, :b, :c, 3] =3D&gt; 30</div><div>&nbsp;&nbsp;#=3D&gt; [:=
x, :y] =3D&gt; 42</div><div>&nbsp;&nbsp;#=3D&gt; [:x, :z] =3D&gt; 42.0</div=
><div><br></div><div><br></div><div>USAGE</div><div>&nbsp;&nbsp;see lib/map=
.rb and test/map_test.rb</div><div><br></div>
------=_Part_561_2307975.1293176775969--

------=_Part_560_12723549.1293176775969--