octothorpe 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44e56895848bd74e1a1c1e0fce48dd52d529bac4
-  data.tar.gz: d930fc76de139a233b1b9695d4f1881fb545168a
+  metadata.gz: 4eb5a75a4f6e96e372ad54747fd18dbe5246e0e6
+  data.tar.gz: d8c0c8a82fef44e3c160bd327d4d1d32f6ce3e50
 SHA512:
-  metadata.gz: b5fed196557a740921eded0a1ee32e7e2d92400a35a0498db54d98f895bc2af3f2e5cd6085bba9709526f624553ca93aad8041e3633fd711470d788524fd0761
-  data.tar.gz: c0909d019f3509d7a8ab001d470652a0d1929bc67fbb9e9a2d3f3990133bc8d068cd9c5d8e976d01f747b06ba41be5e900b362d268f00f7393f4be464dc1440b
+  metadata.gz: 7abfb6d20290533da8a8a8e3357bf6244748c8479b1c5da22b1b7c852d4ca33e792ee72423dc48caf845209261b083494d11ab9642de5ad7fc331b91a7a05579
+  data.tar.gz: af00c9772425af4d6d4b40b729305af4126e2d8155bc15d438e6b8d2dd519c6bc5755463492a51fd64b52ff3d1b1579a754c83b1b976f0d3f32b1353e60eb6bb

data/.hgignore

@@ -13,3 +13,4 @@ mkmf.log
 .ruby*
 .rbenv*
 .project
+.Project

data/.hgtags

@@ -1 +1,2 @@
 a17ae5a3dedd4d2b74b0840a7161e153efd72741 0.2.0
+a7a29ac9aca7023491b7bb58e0516c115b7f2511 0.3.0

data/README.md

@@ -1,6 +1,6 @@
 # Octothorpe
 
-A very simple hash-like class that borrows a little from OpenStruct, etc.
+A very simple hash-like class that borrows a little from OpenStruct, HashWithIndifferentAccess, etc.
 
 * Treats string and symbol keys as equal
 * Access member objects with ot.>>.keyname
@@ -29,28 +29,32 @@ Or install it yourself as:
 
 Simple example:
 
-    ot = Octotghorpe.new(one: 1, "two" => 2, "weird key" => 3)
-    ot.>>.one            # -> 1
-    ot.>>.two            # -> 2
-    ot.get("weird key")  # -> 3
+```ruby
+ot = Octotghorpe.new(one: 1, "two" => 2, "weird key" => 3)
+ot.>>.one            # -> 1
+ot.>>.two            # -> 2
+ot.get("weird key")  # -> 3
+```
 
 With guard conditions:
 
-    ot = Octotghorpe.new(one: 1, "two" => 2)
-    ot.guard(Array, :three)
-    ot.freeze       # optional step - makes OT truly read-only
-    ot.>>.three     # -> [] 
-    ot.>>.three[9]  # valid (of course; returns nil)
+```ruby
+ot = Octotghorpe.new(one: 1, "two" => 2)
+ot.guard(Array, :three)
+ot.freeze       # optional step - makes OT truly read-only
+ot.>>.three     # -> [] 
+ot.>>.three[9]  # valid (of course; returns nil)
+```
 
-Octothorpe responds to a good subset of the methods that hash does
-(although, not the write methods).
+Octothorpe responds to a good subset of the methods that hash does (although, not the write
+methods).
 
 ## FAQ
 
 ### Octo-what?
 
-An antiquated term for the pound, or, _hash_ key on a phone keyboard. It's a
-sort of a joke, you see. Or, very nearly.
+An antiquated term for the pound, or, _hash_ key on a phone keyboard. It's a sort of a joke, you
+see. Or, very nearly.
 
 ### This is a very small library. Was it really worth it?
 
@@ -58,21 +62,23 @@ Maybe not. Feel free to be your own judge.
 
 ### What possible use is it?
 
-If you are fed up with errors caused because Gem A gives you a hash with string
-keys and Gem B expects symbol keys; or you are tired of putting:
+If you are fed up with errors caused because Gem A gives you a hash with string keys and Gem B
+expects symbol keys; or you are tired of putting:
 
-    hash && (hash[:key] || {})[4]
+```ruby
+hash && (hash[:key] || {})[4]
+```
 
-...then this might just possibly be of use. 
+... and for some reason Ruby's new lonely operator is a problem, then this might just possibly be
+of use. 
 
-Alternatively you might try an OpenStruct, Rails' HashWithIndifferentAccess,
-the Hashie gem or the AndAnd gem.
+Alternatively you might try an OpenStruct, Rails' HashWithIndifferentAccess, the Hashie gem or the
+AndAnd gem.
 
 ### Why Read-Only?
 
 Functional programming. 
 
-I find it very hard to fully realise the ideals of functional programming in
-Ruby; but as I get closer to those ideals, my code becomes clearer to read and
-my tests become much, much simpler.
+I find it very hard to fully realise the ideals of functional programming in Ruby; but as I get
+closer to those ideals, my code becomes clearer to read and my tests become much, much simpler.
 

data/lib/octothorpe.rb

@@ -26,13 +26,12 @@ require 'forwardable'
 #     ot.>>.three     # -> [] 
 #     ot.>>.three[9]  # valid (of course; returns nil)
 #
-# Octothorpe additionally responds to the following methods exactly as a Hash
-# would:
+# Octothorpe additionally responds to the following methods exactly as a Hash would:
 #
 #    empty?, has_key?, has_value?, include?
 #    each,   each_key, each_value, keys,    values
 #    select, map,      reject,     inject
-#    merge,  <,        >
+#    merge,  <, >< ==, >+, <=
 #
 class Octothorpe
   extend Forwardable
@@ -42,7 +41,7 @@ class Octothorpe
   def_delegators :@inner_hash, :select, :map, :reject, :inject
 
   # Gem version number
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 
 
   # Generic Octothorpe error class
@@ -56,8 +55,8 @@ class Octothorpe
 
 
   ## 
-  # Inner class for storage. This is to minimise namespace collision with key
-  # names.  Not exposed to Octothorpe's caller.
+  # Inner class for storage. This is to minimise namespace collision with key names. Not exposed to
+  # Octothorpe's caller.
   #
   class Storage
     attr_reader :octothorpe_store
@@ -81,11 +80,11 @@ class Octothorpe
   #
   # Initialise an Octothorpe object by passing it a hash.
   #
-  # You can create an empty OT by calling Octothorpe.new, but there's probably
-  # little utility in that, given that it is read-only.
+  # You can create an empty OT by calling Octothorpe.new, but there's probably little utility in
+  # that, given that it is read-only.
   #
-  # If you pass anything other than nil or something OT can treat as a Hash,
-  # you will cause an Octothorpe::BadHash exception.
+  # If you pass anything other than nil or something OT can treat as a Hash, you will cause an
+  # Octothorpe::BadHash exception.
   #
   def initialize(hash=nil)
     @store = Storage.new( symbol_hash(hash || {}) )
@@ -97,14 +96,13 @@ class Octothorpe
   # :call-seq:
   #   ot.>>.keyname
   #
-  # You can use >> to access member objects in somewhat the same way as an
-  # OpenStruct.
+  # You can use >> to access member objects in somewhat the same way as an OpenStruct.
   #
   #   ot = Octotghorpe.new(one: 1, "two" => 2)
   #   ot.>>.one  # -> 1
   #
-  # This will not work for members that have keys with spaces in, or keys which
-  # have the same name as methods on Object. Use _get_ for those.
+  # This will not work for members that have keys with spaces in, or keys which have the same name
+  # as methods on Object. Use _get_ for those.
   #
   def >>; @store; end
 
@@ -117,8 +115,8 @@ class Octothorpe
   #
   # You can use get to access member object values instead of the >> syntax.
   #
-  # Unlike >>, this works for keys with spaces, or keys that have the same name
-  # as methods on Object.
+  # Unlike >>, this works for keys with spaces, or keys that have the same name as methods on
+  # Object.
   #
   def get(key); @store.octothorpe_store[key.to_sym]; end
 
@@ -135,20 +133,31 @@ class Octothorpe
   ##
   # :call-seq:
   #   ot.guard( class, key [, key, ...] )
+  #   ot.guard( key, [,key, ...] ) {|k| ... }
   #
-  # Guarantees the initial state of a memnber. Each key that is not already
-  # present will be set to <class>.new. Has no effect if key is already
-  # present.
+  # Guarantees the initial state of a memnber. Each key that is not already present will be set to
+  # <class>.new. Has no effect if key is already present. Class must be some class Thing that can
+  # respond to a vanilla Thing.new.
   #
-  # Class must be some class Thing that can respond to a vanilla Thing.new.
+  # Alternatively, for the block form, the key is passed to the block, and the value of the key
+  # becomes the return value of the block ... but again, ONLY if the key is not already set.
   #
-  # Note that this is the only time that you can modify an Octothorpe object
-  # once it is created. If you call _freeze_ on an it, it will become genuinely
-  # read-only, and any call to guard from then on will raise Octothorpe::Frozen.
+  # Note that this is the only time that you can modify an Octothorpe object once it is created. If
+  # you call _freeze_ on an it, it will become genuinely read-only, and any call to guard from then
+  # on will raise Octothorpe::Frozen.
   #
-  def guard(klass, *keys)
+  def guard(*args)
     raise Frozen if self.frozen?
-    keys.map(&:to_sym).each{|k| @store.octothorpe_store[k] ||= klass.new }
+
+    klass = args.shift unless block_given?
+    keys  = args.map(&:to_sym)
+
+    if block_given?
+      keys.each{|k| @store.octothorpe_store[k] ||= yield k }
+    else
+      keys.each{|k| @store.octothorpe_store[k] ||= klass.new }
+    end
+
     self
   end
 
@@ -160,8 +169,7 @@ class Octothorpe
   #
   # Exactly as _Hash.merge_, but returns a new Octothorpe object.
   #
-  # You may pass a hash or an octothorpe. Raises Octothorpe::BadHash
-  # if it is anything else.
+  # You may pass a hash or an octothorpe. Raises Octothorpe::BadHash if it is anything else.
   #
   def merge(other)
     thisHash  = @store.octothorpe_store
@@ -178,24 +186,15 @@ class Octothorpe
   end
 
 
-  ##
-  # Return true if this OT is a subset of the given OT or Hash
-  #
-  def <(other)
-    thisHash  = @store.octothorpe_store.to_h
-    otherHash = symbol_hash(other)
-    thisHash < otherHash
-  end
-
-
-  ##
-  # Return true if this OT is a superset of the given OT or Hash
+  # 
+  # Resolve some of the standard comparisons (with an OT or a hash)
   #
-  def >(other)
-    thisHash  = @store.octothorpe_store.to_h
-    otherHash = symbol_hash(other)
-    thisHash > otherHash
-  end
+  
+  def ==(other); compare_as_hash(other, :==); end
+  def <(other);  compare_as_hash(other, :<);  end
+  def >(other);  compare_as_hash(other, :>);  end
+  def >=(other); compare_as_hash(other, :>=); end
+  def <=(other); compare_as_hash(other, :<=); end
 
 
   ##
@@ -223,5 +222,15 @@ class Octothorpe
   end
 
 
+  ##
+  # Given an 'other' - Hash or OT - render both self and other down to a hash then run the given
+  # comparason on them and return the result
+  #
+  def compare_as_hash(other, method)
+    thisHash  = @store.octothorpe_store.to_h
+    otherHash = symbol_hash(other)
+    thisHash.send(method, otherHash)
+  end
+
 end
 

data/spec/octothorpe_spec.rb

@@ -90,36 +90,65 @@ describe Octothorpe do
 
   describe "#guard" do
 
-    it "sets the given fields with a default value for the class" do
-      @ot.guard(Array, :alpha)
-      @ot.guard(Hash,  :beta)
-
-      expect( @ot.>>.alpha ).to eq([])
-      expect( @ot.>>.beta  ).to eq({})
+    it "raises Octothorpe::Frozen if the OT is frozen" do
+      @ot.freeze
+      expect{ @ot.guard(Hash, :foo) }.to raise_exception Octothorpe::Frozen
     end
 
     it "returns self" do
       expect( @ot.guard(Array, :foo) ).to eq @ot
     end
 
-    it "only sets the field if it does not already exist" do
-      @ot.guard(Array, :one)
-      expect( @ot.>>.one ).to eq @hash2[:one]
-    end
+    context "when given a class" do
+
+      it "accepts a class and list of keys" do
+        @ot.guard(Array, :fred, :daphne, "velma")
+        otHash = @ot.to_h
+        expect( otHash[:fred]   ).to eq([])
+        expect( otHash[:daphne] ).to eq([])
+        expect( otHash[:velma]  ).to eq([])
+      end
+
+      it "sets the given fields with a default value for the class" do
+        @ot.guard(Array, :alpha)
+        @ot.guard(Hash,  :beta)
+
+        expect( @ot.>>.alpha ).to eq([])
+        expect( @ot.>>.beta  ).to eq({})
+      end
+
+      it "only sets the field if it does not already exist" do
+        @ot.guard(Array, :one)
+        expect( @ot.>>.one ).to eq @hash2[:one]
+      end
 
-    it "accepts a list of keys" do
-      @ot.guard(Array, :fred, :daphne, "velma")
-      otHash = @ot.to_h
-      expect( otHash[:fred]   ).to eq([])
-      expect( otHash[:daphne] ).to eq([])
-      expect( otHash[:velma]  ).to eq([])
     end
 
-    it "raises Octothorpe::Frozen if the OT is frozen" do
-      @ot.freeze
-      expect{ @ot.guard(Hash, :foo) }.to raise_exception Octothorpe::Frozen
+    context "when given a block" do
+      let(:foo) do
+        @ot.guard(:fred, :daphne, "velma"){|k| "jinks!" }
+      end
+
+      it "accepts a list of keys" do
+        expect{foo}.not_to raise_exception
+      end
+
+      it "sets the given fields using the block" do
+        otHash = foo.to_h
+        expect( otHash[:fred]   ).to eq("jinks!")
+        expect( otHash[:daphne] ).to eq("jinks!")
+        expect( otHash[:velma]  ).to eq("jinks!")
+      end
+
+      it "only sets the field if it does not already exist" do
+        otHash = foo.to_h
+        expect( otHash[:one]   ).to eq("a")
+        expect( otHash[:'weird key'] ).to eq(4)
+      end
+
     end
 
+
   end
 
 
@@ -163,6 +192,47 @@ describe Octothorpe do
   end
 
 
+  describe "#==" do
+
+    context 'when passed a hash' do
+      it 'returns true if the hash has the same keys' do
+        expect( @ot == @hash2 ).to eq true
+      end
+
+      it 'returns true if the hash has the same keys but as strings' do
+        expect( @ot == @hash ).to eq true
+      end
+
+      it 'returns false if the hash has different keys' do
+        expect( @ot == {one: 1, four: 2} ).to eq false
+      end
+
+      it 'returns false if the hash has the same keys but different values' do
+        h = @hash.merge(one: 'oneone')
+        expect( @ot == h ).to eq false
+      end
+    end
+
+    context 'when passed an OT' do
+      it 'returns true if the ot has the same keys' do
+        ot2 = Octothorpe.new(@hash)
+        expect( @ot == ot2 ).to eq true
+      end
+
+      it 'returns false if the ot has different keys' do
+        ot2 = Octothorpe.new( @hash.merge(four: 4) )
+        expect( @ot == ot2 ).to eq false
+      end
+
+      it 'returns false if the ot has the same keys but different values' do
+        ot2 = @hash.merge(one: 'oneone')
+        expect( @ot == ot2 ).to eq false
+      end
+    end
+
+  end
+
+
   describe "#>" do
 
     context 'when passed a hash' do
@@ -213,10 +283,39 @@ describe Octothorpe do
   end
 
 
+  ## 
+  # Even blindfold I think it's fair to say that I must have implemented >= using > and ==, but a
+  # quick happy path test just to be paranoid...
+  #
+  describe '#<=' do
+
+    it "returns true if the other is a subset" do
+      expect( @ot <= @superset ).to eq true
+    end
+
+    it "returns true if the other is the same" do 
+      expect( @ot <= @hash2 ).to eq true
+    end
+
+  end
+
+
+  describe '#>=' do
+
+    it "returns true if the other is a superset" do
+      expect( @ot >= @subset ).to eq true
+    end
+
+    it "returns true if the other is the same" do
+      expect( @ot >= @hash2 ).to eq true
+    end
+
+  end
+
+
   describe "(miscelaneous other stuff)" do
-    # I "imagine" that the actual class uses Forwardable, but the test code
-    # shouldn't know or care about that.  In any case, just testing with
-    # responds_to always feels like cheating.
+    # I "imagine" that the actual class uses Forwardable, but the test code shouldn't know or care
+    # about that.  In any case, just testing with responds_to always feels like cheating.
 
     it "behaves like a Hash for a bunch of query methods" do
       expect( @ot.empty? ).not_to eq true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octothorpe
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andy Jones
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-19 00:00:00.000000000 Z
+date: 2016-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler