hashery 1.3.0 → 1.4.0

data/qed/01_openhash.rdoc

@@ -0,0 +1,57 @@
+= OpenHash
+
+An OpenHash is a Hash that provides +open+ access to its entries via method
+calls. Writers (methods ending in =-marks) assign entries. Methods without
+special puncuation will retrieve entries. 
+
+  require 'hashery/openhash'
+
+  o = OpenHash.new
+  o.a = 1
+  o.b = 2
+  o.a.assert == 1
+  o.b.assert == 2
+
+Writers always use a Symbol for keys in the underlying Hash.
+
+  o.to_h.assert == { :a=>1, :b=>2 }
+
+All the usual Hash methods are still available in an OpenHash.
+
+  o.map{ |k,v| [k,v] }
+
+And they are protected from being overridden by writers.
+
+  o.map = 3
+  o.map{ |k,v| [k,v] }
+
+Even so, the underlying Hash object does contain the entry even 
+when it can not be accessed via a reader method.
+
+  o.to_h.assert == {:a=>1, :b=>2, :map=>3 }
+
+For some usecases it may be necessary to give up access to one or
+more Hash methods in favor of access to the hash entries. This can
+be done using the #omit! method.
+
+  o.omit!(:map, :merge)
+  o.map.assert == 3
+  o.merge = 4
+  o.merge.assert == 4
+
+Becuase of nature of a writer, a certain set of Hash methods are always
+protected, namely any of those ending in a puctuation mark. In addition,
+the implementation protects all shadow methods (e.g. __id__).
+
+  o.__id__ = 4
+  o.__id__.assert! == 4
+
+Even though writers alwasy use Symbols as keys, because an OpenHash
+is a true Hash object, any object can be used as a key internally.
+
+  o = OpenHash.new
+  o[nil] = "Nothing"
+  o.to_h.assert == { nil=>"Nothing" }
+
+It simply will not be accessible via a reader method.
+

data/qed/02_queryhash.rdoc

@@ -0,0 +1,21 @@
+= QueryHash
+
+A QueryHash is a Hash that provides open access much like
+an OpenHash, but it limits readers to query methods (i.e.
+method ending in ?-marks).
+
+  require 'hashery/queryhash'
+
+  q = QueryHash.new
+  q.a = 1
+  q.b = 2
+  q.a?.assert == 1
+  q.b?.assert == 2
+
+Writers always use Symbols for entry keys.
+
+  q.assert == { :a=>1, :b=>2 }
+
+A QueryHash is compatible with Ruby's standard Hash in
+every other respect.
+

data/qed/03_castinghash.rdoc

@@ -0,0 +1,13 @@
+= CastingHash
+
+A CastingHash is a Hash that allows _casting_ procedures to
+defined that the keys and values pass through upon assignment.
+
+  require 'hashery/castinghash'
+
+  c = CastingHash.new{ |x| x.to_s }
+
+  c[:a] = 1
+
+  c.assert == {'a'=>1}
+

data/qed/04_statichash.rdoc

@@ -0,0 +1,22 @@
+= StaticHash
+
+A StaticHash is simply a Hash that can only be assigned
+once per key. Once assigned a subsequent attempt to assign
+a value to the same key will raise an ArgumentError.
+
+  require 'hashery/statichash'
+
+  h = StaticHash.new
+
+  h["x"] = 1
+
+  expect ArgumentError do
+    h["x"] = 2
+  end
+
+The same error will be raised when using #update or #merge!.
+
+  expect ArgumentError do
+    h.update( :x=>2 )
+  end
+

data/qed/05_association.rdoc

@@ -0,0 +1,59 @@
+= Association
+
+An Association is a class for creating simple pairings.
+
+    require 'hashery/association'
+
+An Association can bew created through the usual means 
+of instantiation.
+
+    Association.new(:a, :b)
+
+Or the shortcut method #>> can be used in most cases.
+
+    :x >> :z
+
+An association provides two methods to access its content, #index and #value.
+
+    a = 'foo' >> 'bar'
+
+    a.index.assert == 'foo'
+    a.value.assert == 'bar'
+
+Associations can be used to create ordered-hashes via normal
+arrays.
+
+    keys = []
+    vals = []
+
+    ohash = [ 'A' >> '3', 'B' >> '2', 'C' >> '1' ]
+
+    ohash.each{ |k,v| keys << k ; vals << v }
+
+    keys.assert == ['A','B','C']
+    vals.assert == ['3','2','1']
+
+
+Becuase Associations are objects in themselves more complex
+collections can also be created.
+
+    complex = [
+      'parent' >> 'child',
+      'childless',
+      'another_parent' >> [
+        'subchildless',
+        'subparent' >> 'subchild'
+      ]
+    ]
+
+An experimental feature of Association keeps a cache of all defined associations.
+
+    o = Object.new
+    o >> :a
+    o >> :b
+    o >> :c
+
+    o.associations.assert == [:a, :b, :c]
+
+However this feature will probably be deprecated.
+

data/qed/06_opencascade.rdoc

@@ -0,0 +1,58 @@
+= OpenCascade
+
+OpenCascade is subclass of OpenObject. It differs in a few
+significant ways.
+
+   require 'hashery/opencascade'
+
+The main reason this class is labeled "cascade", every internal
+Hash is transformed into an OpenCascade dynamically upon access.
+This makes it easy to create "cascading" references.
+
+    h = { :x => { :y => { :z => 1 } } }
+    c = OpenCascade[h]
+    c.x.y.z.assert == 1
+
+As soon as you access a node it automatically becomes an OpenCascade.
+
+    c = OpenCascade.new
+    c.r.assert.is_a? OpenCascade
+    c.a.b.assert.is_a? OpenCascade
+
+But if you set a node, then that will be it's value.
+
+    c.a.b = 4
+    c.a.b.assert == 4
+
+To query a node without causing the auto-creation of an OpenCasade
+object, use the ?-mark.
+
+   c.a.z?.assert == nil
+
+OpenCascade also transforms Hashes within Arrays.
+
+  h = { :x=>[ {:a=>1}, {:a=>2} ], :y=>1 }
+  c = OpenCascade[h]
+  c.x.first.a.assert == 1
+  c.x.last.a.assert == 2
+
+Like OpenObject, OpenCascade allows you to insert entries as array
+pairs.
+
+   c = OpenCascade.new
+   c << [:x,8]
+   c << [:y,9]
+
+   c.x.assert == 8
+   c.y.assert == 9
+
+Finally, you can call methods ending in a !-mark to access the
+underlying hash (Note that these differ in behavior from the
+built-in !-methods).
+
+   bk = c.map!{ |k,v| k.to_s.upcase }
+   bk.sort.assert ==  ['X', 'Y']
+
+So you can see that for the most an OpenCascade is just like
+OpenObject, but it allows you to conveniently build open sub-layers. 
+

data/qed/07_fuzzyhash.rdoc

@@ -0,0 +1,141 @@
+= FuzzyHash
+
+Require the library.
+
+    require 'hashery/fuzzyhash'
+
+Should accept strings and retrieve based on them.
+
+    l = FuzzyHash.new
+    l['asd'] = 'qwe'
+    l['asd'].should == 'qwe'
+  
+Should accept strings, but the second time you set the same string, it should overwrite.
+
+    l = FuzzyHash.new
+    l['asd'] = 'asd'
+    l['asd'] = 'qwe'
+    l['asd'].should == 'qwe'
+
+Should accept regexs too.
+
+    l = FuzzyHash.new
+    l[/asd.*/] = 'qwe'
+    l['asdqweasd'].should == 'qwe'
+
+Should accept regexs too, but the second time you set the same regex, it should overwrite.
+
+    l = FuzzyHash.new
+    l[/asd/] = 'asd'
+    l[/asd/] = 'qwe'
+    l['asdqweasd'].should == 'qwe'
+
+Should accept regexs too with the match.
+
+    l = FuzzyHash.new
+    l[/asd.*/] = 'qwe'
+    l.match_with_result('asdqweasd').should == ['qwe', 'asdqweasd']
+
+Should accept regexs that match the whole strong too with the match.
+
+    l = FuzzyHash.new
+    l[/asd/] = 'qwe'
+    l.match_with_result('asd').should == ['qwe', 'asd']
+
+Should prefer string to regex matches.
+
+    l = FuzzyHash.new
+    l['asd'] = 'qwe2'
+    l[/asd.*/] = 'qwe'
+    l['asd'].should == 'qwe2'
+
+Should allow nil keys.
+
+    l = FuzzyHash.new
+    l[nil] = 'qwe2'
+    l['asd'] = 'qwe'
+    l['asd'].should == 'qwe'
+    l[nil].should == 'qwe2'
+
+Should allow boolean keys.
+
+    l = FuzzyHash.new
+    l[false] = 'false'
+    l[true] = 'true'
+    l[/.*/] = 'everything else'
+    l[true].should == 'true'
+    l[false].should == 'false'
+    l['false'].should == 'everything else'
+
+Should pick between the correct regex.
+
+    hash = FuzzyHash.new
+    hash[/^\d+$/] = 'number'
+    hash[/.*/] = 'something'
+    hash['123asd'].should == 'something'
+
+Should be able to delete by value for hash.
+
+    l = FuzzyHash.new
+    l[nil] = 'qwe2'
+    l['asd'] = 'qwe'
+    l['asd'].should == 'qwe'
+    l[nil].should == 'qwe2'
+    l.delete_value('qwe2')
+    l[nil].should == nil
+
+Should be able to delete by value for regex.
+
+    l = FuzzyHash.new
+    l[/qwe.*/] = 'qwe2'
+    l['asd'] = 'qwe'
+    l['asd'].should == 'qwe'
+    l['qweasd'].should == 'qwe2'
+    l.delete_value('qwe2')
+    l['qweasd'].should == nil
+
+Should iterate through the keys.
+
+    l = FuzzyHash.new
+    l[/qwe.*/] = 'qwe2'
+    l['asd'] = 'qwe'
+    l['zxc'] = 'qwe'
+    l.keys.size.should == 3
+
+Should iterate through the values.
+
+    l = FuzzyHash.new
+    l[/qwe.*/] = 'qwe2'
+    l['asd'] = 'qwe'
+    l['zxc'] = 'qwelkj'
+    (['qwe2','qwe','qwelkj'] & l.values).size.should == 3
+
+Should clear.
+
+    l = FuzzyHash.new
+    l[/qwe.*/] = 'qwe2'
+    l['asd'] = 'qwe'
+    l['zxc'] = 'qwelkj'
+    l.clear
+    l.empty?.should == true
+ 
+Should handle equality.
+
+    l_1 = FuzzyHash.new
+    l_1[/qwe.*/] = 'qwe2'
+    l_1['asd'] = 'qwelkj'
+    l_1['zxc'] = 'qwe'
+    l_2 = FuzzyHash.new
+    l_2['zxc'] = 'qwe'
+    l_2['asd'] = 'qwelkj'
+    l_2[/qwe.*/] = 'qwe2'
+    l_1.should == l_2
+
+Should return the value when adding the value.
+
+    h = FuzzyHash.new
+    (h[/asd/] = '123').should == '123'
+    (h['qwe'] = '123').should == '123'
+
+That's It.
+

data/qed/08_properyhash.rdoc

@@ -0,0 +1,38 @@
+= PropertyHash
+
+Require the library.
+
+    require 'hashery/propertyhash'
+
+The Property hash can be used an object in itself.
+
+     h = PropertyHash.new(:a=>1, :b=>2)
+     h[:a]        #=> 1
+     h[:a] = 3
+     h[:a]        #=> 3
+
+Becuase the properties are fixed, if we try to set a key that is not present,
+then we will get an error.
+
+    expect ArgumentError do
+      h[:x] = 5
+    end
+
+The PropertyHash can also be used as a superclass.
+
+    class MyPropertyHash < PropertyHash
+      property :a, :default => 1
+      property :b, :default => 2
+    end
+
+    h = MyPropertyHash.new
+    h[:a]        #=> 1
+    h[:a] = 3
+    h[:a]        #=> 3
+
+Again, if we try to set key that was not fixed, then we will get an error.
+
+    expect ArgumentError do
+      h[:x] = 5
+    end
+

data/qed/09_ostructable.rdoc

@@ -0,0 +1,56 @@
+= OpenStructable
+
+OpensStructable is a mixin module which can provide OpenStruct behavior to
+any class or object. OpenStructable allows extention of data objects
+with arbitrary attributes.
+
+  require 'hashery/ostructable'
+
+  class Record
+    include OpenStructable
+  end
+
+Now let's create a new record and see if we can assign values to open
+properties.
+
+    record = Record.new
+    record.name    = "John Smith"
+    record.age     = 70
+    record.pension = 300
+
+We can see that the values were set.
+
+    record.name.assert    == "John Smith"
+    record.age.assert     == 70
+    record.pension.assert == 300
+
+If we havent' assigned a value to a property it should just return +nil+.
+
+    record.address.assert == nil
+
+OpenStructable is also smart enough to adjust itself to work with a subclass
+of a Hash.
+
+    class HashRecord < Hash
+      include OpenStructable
+    end
+
+We can apply similar settings as above.
+
+    record = HashRecord.new
+    record.name    = "John Doe"
+    record.age     = 40
+    record.pension = 200
+
+We can see that the values were set.
+
+    record.name.assert    == "John Doe"
+    record.age.assert     == 40
+    record.pension.assert == 200
+
+The differnce here is that the data is accessible via the normal Hash 
+methods too.
+
+    record.assert == {:name=>"John Doe", :age=>40, :pension=>200}
+
+Notice that entries are converted to Symbols, not Strings.