safer 0.3.1 → 0.4.0

data/History.txt

@@ -1,3 +1,17 @@
+=== 0.4.0 / 2011-10-29
+
+* Safer::IVar functionality moved into Safer::IVarFactory class.
+* Safer::IVar is now an instance of Safer::IVarFactory.
+* Added DSL interface to Safer::IVarFactory.
+* Safer::IVarFactory has pluggable symbol prefix generation.
+* Added facility to generate symbols based on last component of class name.
+
+=== 0.3.2 / 2010-12-01
+
+* Made compatible with ruby 1.9.2.
+* Renamed README.txt to README.rdoc
+* Refactored HashProtocol tests in accordance with common ruby practice.
+
 === 0.3.1 / 2010-11-21
 
 * ri Safer didn't include mention of HashProtocol.  Fixed.

data/Manifest.txt

@@ -1,7 +1,7 @@
 .autotest
 History.txt
 Manifest.txt
-README.txt
+README.rdoc
 Rakefile
 lib/safer.rb
 lib/safer/ivar.rb

data/Rakefile

@@ -2,7 +2,8 @@ require 'rubygems'
 require 'hoe'
 
 Hoe.spec 'safer' do
-  developer('Aidan Cully', 'aidan@panix.com')
+  self.developer('Aidan Cully', 'aidan@panix.com')
 
   self.rubyforge_name = 'safer'
+  self.readme_file = 'README.rdoc'
 end

data/lib/safer/hashprotocol.rb

@@ -1,304 +1,302 @@
 require 'safer/ivar'
 require 'safer/protocol'
 
-class Safer
+##
+# Check that the keys in a Hash object follow a set of constraints.
+# ==Usage
+# In this example, we use a Hash to simulate keyword parameters to our
+# function.
+#  class YourClass
+#    SHP = Safer::HashProtocol
+#    # we support two versions of the keyword arguments to our function.
+#    # In both versions, the Hash is required to have a :type field.
+#    CommonKeywords = SHP::HasKey.create(:type)
+#    # In the old version, a person's full name is presented in the :name
+#    # keyword.
+#    V1Keywords = SHP::HasKey.create(:name)
+#    # In the new version, the full name is separated into :familyName
+#    # and :givenName.
+#    V2Keywords = SHP::HasKey.create(:familyName, :givenName)
+#    # Check if the keywords in the Hash match Version1 (that is,
+#    # :name and :type fields must be present in the Hash, and no other
+#    # fields should be present).
+#    V1Check = SHP::Only.new(SHP::All.new(*CommonKeywords + *V1Keywords))
+#    # Check if the keywords in the Hash match Version2 (that is,
+#    # :familyName, :givenName, and :type fields must be present in the Hash,
+#    # and no other fields should be present).
+#    V2Check = SHP::Only.new(SHP::All.new(*CommonKeywords + *V2Keywords))
+#    # Check if the Hash matches either version 1 or version 2.
+#    ValidCheck = SHP::Any.new(V1Check, V2Check)
+#    def my_fn(h)
+#      if ! (ValidCheck === h)
+#        raise ArgumentError, "h should conform to #{ValidCheck.description}"
+#      end
+#      case h
+#      when V1Check
+#        v1_process(h[:name], h[:type])
+#      when V2Check
+#        v2_process(h[:familyName], h[:givenName], h[:type])
+#      end
+#    end
+#  end
+# ==Rationale
+# It is a common design practice in Ruby code to use Hash objects to get an
+# analogue to function keyword arguments in other languages.  Among other
+# uses, this practice simplifies the implementation of embedded DSLs within
+# Ruby.  When used in this way, the Hash keys are semantically meaningful,
+# and are generally entered by hand.  It's important to get these Hashes
+# right.  Safer::HashProtocol is intended to help, by simultaneously
+# providing a means of documenting the key combinations required of a Hash,
+# and by detecting when the Hash does not contain a valid set of keys.
+class Safer::HashProtocol
   ##
-  # Check that the keys in a Hash object follow a set of constraints.
-  # ==Usage
-  # In this example, we use a Hash to simulate keyword parameters to our
-  # function.
-  #  class YourClass
-  #    SHP = Safer::HashProtocol
-  #    # we support two versions of the keyword arguments to our function.
-  #    # In both versions, the Hash is required to have a :type field.
-  #    CommonKeywords = SHP::HasKey.create(:type)
-  #    # In the old version, a person's full name is presented in the :name
-  #    # keyword.
-  #    V1Keywords = SHP::HasKey.create(:name)
-  #    # In the new version, the full name is separated into :familyName
-  #    # and :givenName.
-  #    V2Keywords = SHP::HasKey.create(:familyName, :givenName)
-  #    # Check if the keywords in the Hash match Version1 (that is,
-  #    # :name and :type fields must be present in the Hash, and no other
-  #    # fields should be present).
-  #    V1Check = SHP::Only.new(SHP::All.new(*CommonKeywords + *V1Keywords))
-  #    # Check if the keywords in the Hash match Version2 (that is,
-  #    # :familyName, :givenName, and :type fields must be present in the Hash,
-  #    # and no other fields should be present).
-  #    V2Check = SHP::Only.new(SHP::All.new(*CommonKeywords + *V2Keywords))
-  #    # Check if the Hash matches either version 1 or version 2.
-  #    ValidCheck = SHP::Any.new(V1Check, V2Check)
-  #    def my_fn(h)
-  #      if ! (ValidCheck === h)
-  #        raise ArgumentError, "h should conform to #{ValidCheck.description}"
-  #      end
-  #      case h
-  #      when V1Check
-  #        v1_process(h[:name], h[:type])
-  #      when V2Check
-  #        v2_process(h[:familyName], h[:givenName], h[:type])
-  #      end
-  #    end
-  #  end
-  # ==Rationale
-  # It is a common design practice in Ruby code to use Hash objects to get an
-  # analogue to function keyword arguments in other languages.  Among other
-  # uses, this practice simplifies the implementation of embedded DSLs within
-  # Ruby.  When used in this way, the Hash keys are semantically meaningful,
-  # and are generally entered by hand.  It's important to get these Hashes
-  # right.  Safer::HashProtocol is intended to help, by simultaneously
-  # providing a means of documenting the key combinations required of a Hash,
-  # and by detecting when the Hash does not contain a valid set of keys.
-  class HashProtocol
+  # Object signature required of HashProtocol objects.  Used to derive
+  # Safer::HashProtocol::Protocol.
+  class ProtocolBase
     ##
-    # Object signature required of HashProtocol objects.  Used to derive
-    # Safer::HashProtocol::Protocol.
-    class ProtocolBase
-      ##
-      # Retrieve a human-readable description of this HashProtocol object.
-      def description
-      end
-
-      ##
-      # Check that a Hash (h) follows this object's protocol.
-      def ===(h)
-      end
+    # Retrieve a human-readable description of this HashProtocol object.
+    def description
+    end
 
-      ##
-      # Check that a Hash (h) follows this object's protocol, keeping
-      # track of which parts of (h) do not.  +remaining+ should only
-      # be updated if +h+ matches this object.
-      def match(h, remaining)
-      end
-    end # Safer::HashProtocol::ProtocolBase
     ##
-    # Object signature required of HashProtocol objects.  Derived from
-    # ProtocolBase.
-    Protocol = Safer::Protocol.create_from_class(ProtocolBase)
+    # Check that a Hash (h) follows this object's protocol.
+    def ===(h)
+    end
 
     ##
-    # Base class of all classes exported from Safer::HashProtocol.  Implements
-    # ProtocolBase#description signature.
-    class Base
-      Safer::IVar.instance_variable(self, :description)
+    # Check that a Hash (h) follows this object's protocol, keeping
+    # track of which parts of (h) do not.  +remaining+ should only
+    # be updated if +h+ matches this object.
+    def match(h, remaining)
+    end
+  end # Safer::HashProtocol::ProtocolBase
+  ##
+  # Object signature required of HashProtocol objects.  Derived from
+  # ProtocolBase.
+  Protocol = Safer::Protocol.create_from_class(ProtocolBase)
 
-      ##
-      # :attr_reader: description
-      # Human-readable description of this HashProtocol.
-      Safer::IVar.export_reader(self, :description)
+  ##
+  # Base class of all classes exported from Safer::HashProtocol.  Implements
+  # ProtocolBase#description signature.
+  class Base
+    Safer::IVar.instance_variable(self, :description)
 
-      ##
-      # Store +description+ into the #description reader attribute.
-      def initialize(description)
-        self.safer_hashprotocol_base__description = description
-      end # Safer::HashProtocol::Base#initialize
-    end # Safer::HashProtocol::Base
+    ##
+    # :attr_reader: description
+    # Human-readable description of this HashProtocol.
+    Safer::IVar.export_reader(self, :description)
 
     ##
-    # Base class of Safer::HashProtocol implementations that provide some
-    # derived value from a single "base" implementation.
-    class Single < Safer::HashProtocol::Base
-      Safer::IVar.instance_variable(self, :base)
+    # Store +description+ into the #description reader attribute.
+    def initialize(description)
+      self.safer_hashprotocol_base__description = description
+    end # Safer::HashProtocol::Base#initialize
+  end # Safer::HashProtocol::Base
 
-      ##
-      # :attr_reader: base
-      # Base HashProtocol object from which this object's match operation
-      # should be derived.
-      Safer::IVar.export_reader(self, :base)
-      ##
-      # Stores the description and base HashProtocol object in this
-      # HashProtocol object.  The description is derived from the description
-      # of the base object, prepended by +prefix+.
-      def initialize(prefix, base)
-        Protocol.instance_conforms?(base)
-        super("#{prefix}#{base.description}")
-        self.safer_hashprotocol_single__base = base
-      end # Safer::HashProtocol::Single#initialize
-    end # Safer::HashProtocol::Single
+  ##
+  # Base class of Safer::HashProtocol implementations that provide some
+  # derived value from a single "base" implementation.
+  class Single < Safer::HashProtocol::Base
+    Safer::IVar.instance_variable(self, :base)
 
     ##
-    # Base class of Safer::HashProtocol implementations that provide some
-    # derived value from a set of other HashProtocol implementations.
-    class Compound < Safer::HashProtocol::Base
-      Safer::IVar.instance_variable(self, :list)
+    # :attr_reader: base
+    # Base HashProtocol object from which this object's match operation
+    # should be derived.
+    Safer::IVar.export_reader(self, :base)
+    ##
+    # Stores the description and base HashProtocol object in this
+    # HashProtocol object.  The description is derived from the description
+    # of the base object, prepended by +prefix+.
+    def initialize(prefix, base)
+      Protocol.instance_conforms?(base)
+      super("#{prefix}#{base.description}")
+      self.safer_hashprotocol_single__base = base
+    end # Safer::HashProtocol::Single#initialize
+  end # Safer::HashProtocol::Single
+
+  ##
+  # Base class of Safer::HashProtocol implementations that provide some
+  # derived value from a set of other HashProtocol implementations.
+  class Compound < Safer::HashProtocol::Base
+    Safer::IVar.instance_variable(self, :list)
 
-      ##
-      # :attr_reader: list
-      # Set of HashProtocol objects from which this object's match operation
-      # should be derived.
-      Safer::IVar.export_reader(self, :list)
+    ##
+    # :attr_reader: list
+    # Set of HashProtocol objects from which this object's match operation
+    # should be derived.
+    Safer::IVar.export_reader(self, :list)
 
-      ##
-      # Stores the description and set of base HashProtocol objects in this
-      # HashProtocol object.  The description is derived from the description
-      # of the base HashProtocol objects, with +sep+ between each element.
-      def initialize(sep, *list)
-        desc = list.map do |el|
-          Protocol.instance_conforms?(el)
-          "(#{el.description})"
-        end.join(sep)
-        super(desc)
-        self.safer_hashprotocol_compound__list = list
-      end # Safer::HashProtocol::Compound#initialize
-    end # Safer::HashProtocol::Compound
+    ##
+    # Stores the description and set of base HashProtocol objects in this
+    # HashProtocol object.  The description is derived from the description
+    # of the base HashProtocol objects, with +sep+ between each element.
+    def initialize(sep, *list)
+      desc = list.map do |el|
+        Protocol.instance_conforms?(el)
+        "(#{el.description})"
+      end.join(sep)
+      super(desc)
+      self.safer_hashprotocol_compound__list = list
+    end # Safer::HashProtocol::Compound#initialize
+  end # Safer::HashProtocol::Compound
 
+  ##
+  # Terminal Safer::HashProtocol implementation, checks that a key exists in
+  # a Hash.
+  class HasKey < Safer::HashProtocol::Base
+    Safer::IVar.instance_variable(self, :key)
     ##
-    # Terminal Safer::HashProtocol implementation, checks that a key exists in
-    # a Hash.
-    class HasKey < Safer::HashProtocol::Base
-      Safer::IVar.instance_variable(self, :key)
-      ##
-      # The match operation will check that +key+ exists in the Hash.
-      # +key.inspect+ is used for the description.
-      def initialize(key)
-        super(key.inspect)
-        self.safer_hashprotocol_haskey__key = key
-      end # Safer::HashProtocol::HasKey#initialize
+    # The match operation will check that +key+ exists in the Hash.
+    # +key.inspect+ is used for the description.
+    def initialize(key)
+      super(key.inspect)
+      self.safer_hashprotocol_haskey__key = key
+    end # Safer::HashProtocol::HasKey#initialize
 
-      ##
-      # Check that the +key+ from self.initialize is stored in Hash h.
-      def ===(h)
-        h.has_key?(self.safer_hashprotocol_haskey__key)
-      end # Safer::HashProtocol::HasKey#===
-      ##
-      # Check that the +key+ from self.initialize is stored in Hash h.  If it
-      # is, remove that key from +remaining+.
-      def match(h, remaining)
-        if h.has_key?(self.safer_hashprotocol_haskey__key)
-          remaining.delete(self.safer_hashprotocol_haskey__key)
-          true
-        else
-          false
-        end
-      end # Safer::HashProtocol::HasKey#match
+    ##
+    # Check that the +key+ from self.initialize is stored in Hash h.
+    def ===(h)
+      h.has_key?(self.safer_hashprotocol_haskey__key)
+    end # Safer::HashProtocol::HasKey#===
+    ##
+    # Check that the +key+ from self.initialize is stored in Hash h.  If it
+    # is, remove that key from +remaining+.
+    def match(h, remaining)
+      if h.has_key?(self.safer_hashprotocol_haskey__key)
+        remaining.delete(self.safer_hashprotocol_haskey__key)
+        true
+      else
+        false
+      end
+    end # Safer::HashProtocol::HasKey#match
 
-      ##
-      # Convenience function creates a HasKey object for each argument
-      # passed in.
-      def self.create(*args)
-        args.map do |el| self.new(el) end
-      end # Safer::HashProtocol::HasKey.create
-    end # Safer::HashProtocol::HasKey
+    ##
+    # Convenience function creates a HasKey object for each argument
+    # passed in.
+    def self.create(*args)
+      args.map do |el| self.new(el) end
+    end # Safer::HashProtocol::HasKey.create
+  end # Safer::HashProtocol::HasKey
 
+  ##
+  # Check that at least one of a set of Safer::HashProtocol objects matches
+  # a Hash.
+  class Any < Safer::HashProtocol::Compound
     ##
-    # Check that at least one of a set of Safer::HashProtocol objects matches
-    # a Hash.
-    class Any < Safer::HashProtocol::Compound
-      ##
-      # The description for this object will be the descriptions for each
-      # argument, separated by " OR ".
-      def initialize(*list)
-        super(" OR ", *list)
-      end # Safer::HashProtocol::Any#initialize
+    # The description for this object will be the descriptions for each
+    # argument, separated by " OR ".
+    def initialize(*list)
+      super(" OR ", *list)
+    end # Safer::HashProtocol::Any#initialize
 
-      ##
-      # Check if any elements from the +list+ argument to initialize match
-      # Hash h.
-      def ===(h)
-        self.list.any? do |el| el === h end
-      end # Safer::HashProtocol::Any#===
+    ##
+    # Check if any elements from the +list+ argument to initialize match
+    # Hash h.
+    def ===(h)
+      self.list.any? do |el| el === h end
+    end # Safer::HashProtocol::Any#===
 
-      ##
-      # Check if any elements from the +list+ argument to initialize match
-      # Hash h, keeping track of which elements from h have not been matched.
-      def match(h, remaining)
-        self.list.inject(false) do |memo, el|
-          if el.match(h, remaining)
-            true
-          else
-            memo
-          end
+    ##
+    # Check if any elements from the +list+ argument to initialize match
+    # Hash h, keeping track of which elements from h have not been matched.
+    def match(h, remaining)
+      self.list.inject(false) do |memo, el|
+        if el.match(h, remaining)
+          true
+        else
+          memo
         end
-      end # Safer::HashProtocol::Any#match
-    end # Safer::HashProtocol::Any
+      end
+    end # Safer::HashProtocol::Any#match
+  end # Safer::HashProtocol::Any
 
+  ##
+  # Check that all of a set of Safer::HashProtocol objects match a Hash.
+  class All < Safer::HashProtocol::Compound
     ##
-    # Check that all of a set of Safer::HashProtocol objects match a Hash.
-    class All < Safer::HashProtocol::Compound
-      ##
-      # The description for this object will be the descriptions for each
-      # argument, separated by " AND ".
-      def initialize(*list)
-        super(" AND ", *list)
-      end # Safer::HashProtocol::All#initialize
+    # The description for this object will be the descriptions for each
+    # argument, separated by " AND ".
+    def initialize(*list)
+      super(" AND ", *list)
+    end # Safer::HashProtocol::All#initialize
 
-      ##
-      # Check if all elements from the +list+ argument to initialize match
-      # Hash h.
-      def ===(h)
-        self.list.all? do |el| el === h end
-      end # Safer::HashProtocol::All#===
+    ##
+    # Check if all elements from the +list+ argument to initialize match
+    # Hash h.
+    def ===(h)
+      self.list.all? do |el| el === h end
+    end # Safer::HashProtocol::All#===
 
-      ##
-      # Check if all elements from the +list+ argument to initialize match
-      # Hash h.  If they do, +remaining+ will be updated to remove all matching
-      # elements from +list+.  If not all elements match, +remaining+ will be
-      # unmodified.
-      def match(h, remaining)
-        nremaining = remaining.dup
-        rval = self.list.all? do |el| el.match(h, nremaining) end
-        if rval
-          remaining.update(nremaining)
-        end
-        rval
-      end # Safer::HashProtocol::All#match
-    end # Safer::HashProtocol::All
+    ##
+    # Check if all elements from the +list+ argument to initialize match
+    # Hash h.  If they do, +remaining+ will be updated to remove all matching
+    # elements from +list+.  If not all elements match, +remaining+ will be
+    # unmodified.
+    def match(h, remaining)
+      nremaining = remaining.dup
+      rval = self.list.all? do |el| el.match(h, nremaining) end
+      if rval
+        remaining.update(nremaining)
+      end
+      rval
+    end # Safer::HashProtocol::All#match
+  end # Safer::HashProtocol::All
 
+  ##
+  # Check that a base Safer::HashProtocol object does NOT match a Hash.
+  # That is, invert the match of a base HashProtocol object.
+  class Not < Safer::HashProtocol::Single
     ##
-    # Check that a base Safer::HashProtocol object does NOT match a Hash.
-    # That is, invert the match of a base HashProtocol object.
-    class Not < Safer::HashProtocol::Single
-      ##
-      # The description for this object will be "NOT #{base.description}".
-      def initialize(base)
-        super("NOT ", base)
-      end # Safer::HashProtocol::Not#initialize
+    # The description for this object will be "NOT #{base.description}".
+    def initialize(base)
+      super("NOT ", base)
+    end # Safer::HashProtocol::Not#initialize
 
-      ##
-      # Check that the base object does NOT match the hash.
-      def ===(h)
-        ! (self.base === h)
-      end # Safer::HashProtocol::Not#===
+    ##
+    # Check that the base object does NOT match the hash.
+    def ===(h)
+      ! (self.base === h)
+    end # Safer::HashProtocol::Not#===
 
-      ##
-      # Check that the base object does NOT match the hash.  Does not update
-      # +remaining+ under any circumstance.
-      def match(h, remaining)
-        self === h
-      end # Safer::HashProtocol::Not#match
-    end # Safer::HashProtocol::Not
+    ##
+    # Check that the base object does NOT match the hash.  Does not update
+    # +remaining+ under any circumstance.
+    def match(h, remaining)
+      self === h
+    end # Safer::HashProtocol::Not#match
+  end # Safer::HashProtocol::Not
 
+  ##
+  # Check that the Hash only contains elements that match the base
+  # Safer::HashProtocol object.
+  class Only < Safer::HashProtocol::Single
     ##
-    # Check that the Hash only contains elements that match the base
-    # Safer::HashProtocol object.
-    class Only < Safer::HashProtocol::Single
-      ##
-      # The description for this object will be "ONLY #{base.description}".
-      def initialize(base)
-        super("ONLY ", base)
-      end
-      ##
-      # Check that all keys in a hash are matched by the base HashProtocol
-      # object.
-      def ===(h)
-        remaining = h.dup
-        if self.base.match(h, remaining)
-          remaining.empty?
-        else
-          false
-        end
+    # The description for this object will be "ONLY #{base.description}".
+    def initialize(base)
+      super("ONLY ", base)
+    end
+    ##
+    # Check that all keys in a hash are matched by the base HashProtocol
+    # object.
+    def ===(h)
+      remaining = h.dup
+      if self.base.match(h, remaining)
+        remaining.empty?
+      else
+        false
       end
-      ##
-      # Check that all keys in a hash are matched by the base HashProtocol
-      # object.  If they are, then empty +remaining+.
-      def match(h, remaining)
-        if self === h
-          remaining.clear
-          true
-        else
-          false
-        end
+    end
+    ##
+    # Check that all keys in a hash are matched by the base HashProtocol
+    # object.  If they are, then empty +remaining+.
+    def match(h, remaining)
+      if self === h
+        remaining.clear
+        true
+      else
+        false
       end
-    end # Safer::HashProtocol::Only
-  end # Safer::HashProtocol
-end # Safer
+    end
+  end # Safer::HashProtocol::Only
+end # Safer::HashProtocol