safer 0.2.1 → 0.3.0

data/History.txt

@@ -1,6 +1,16 @@
-=== 0.1.0 / 2010-09-22
+=== 0.3.0 / 2010-11-20
 
-* First release
+* Make Safer a Class, instead of a Module, to prevent embedding.
+* Protocol provides match_class and match_instance methods, allowing use of
+  case statements to verify protocol conformity.
+* Added HashProtocol suite, to verify that keys of a Hash follow desired
+  usage guidelines.
+
+=== 0.2.1 / 2010-10-17
+
+* README.txt still referred to ClassProtocol.  Fixed.
+* The Safer module documentation now refers to its submodules.
+* Regularized use of '::' and '.'.
 
 === 0.2.0 / 2010-10-10
 
@@ -8,8 +18,6 @@
 * Protocol can non-violently check if a class or instance conforms.
 * Added much documentation.
 
-=== 0.2.1 / 2010-10-17
+=== 0.1.0 / 2010-09-22
 
-* README.txt still referred to ClassProtocol.  Fixed.
-* The Safer module documentation now refers to its submodules.
-* Regularized use of '::' and '.'.
+* First release

data/Manifest.txt

@@ -6,5 +6,7 @@ Rakefile
 lib/safer.rb
 lib/safer/ivar.rb
 lib/safer/protocol.rb
+lib/safer/hashprotocol.rb
 test/test_safer_ivar.rb
 test/test_safer_protocol.rb
+test/test_safer_hashprotocol.rb

data/README.txt

@@ -5,15 +5,18 @@ http://safer.rubyforge.org
 == DESCRIPTION:
 
 Safer is an umbrella library, with components designed to make it simple to
-verify and improve the safety of your ruby code.  There are at present two
+verify and improve the safety of your ruby code.  There are at present three
 modules under the safer umbrella:
 
-[<tt>Safer::IVar</tt>]     generates specially-named accessor functions
-                           for class instance variables.
-[<tt>Safer::Protocol</tt>] is used to provide a ruby analogue to
-                           Objective-C Protocols (which are similar to
-                           Java interfaces, but do not require
-                           inheritance).
+[<tt>Safer::IVar</tt>]         generates specially-named accessor functions
+                               for class instance variables.
+[<tt>Safer::Protocol</tt>]     is used to provide a ruby analogue to
+                               Objective-C Protocols (which are similar to
+                               Java interfaces, but do not require
+                               inheritance).
+[<tt>Safer::HashProtocol</tt>] verifies that a Hash keys follow a defined
+			       format.  Intended to help use of Hash objects as
+			       keyword parameters.
 
 == FEATURES/PROBLEMS:
 
@@ -22,11 +25,13 @@ modules under the safer umbrella:
 * Define a "Protocol" class, and derive a signature from it.  Verify that
   another class (or an instance of that class) implements the protocol
   signature.
+* Define a check if a Hash contains a desired combination of keys.
 
 == SYNOPSIS:
 
   require 'safer/ivar'
   require 'safer/protocol'
+  require 'safer/hashprotocol'
 
   module MyModule
     class MyProtocolClass
@@ -39,11 +44,29 @@ modules under the safer umbrella:
     class MyClass
       Safer::IVar.instance_variable(self, :var1, :var2)
       def initialize(var1, var2)
-        PROTOCOL.check_instance_conforms(var1)
-        PROTOCOL.check_instance_conforms(var2)
+        PROTOCOL.instance_conforms?(var1)
+        PROTOCOL.instance_conforms?(var2)
         self.mymodule_myclass__var1 = var1
         self.mymodule_myclass__var2 = var2
       end
+
+      SHP = Safer::HashProtocol
+      V1Keywords = SHP::HasKey.create(:name, :type)
+      V2Keywords = SHP::HasKey.create(:first, :last, :type)
+      V1Check = SHP::Only.new(SHP::Any.new(*V1Keywords))
+      V2Check = SHP::Only.new(SHP::Any.new(*V2Keywords))
+      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[:first], h[:last], h[:type])
+        end
+      end
     end
   end
 

data/lib/safer/hashprotocol.rb

@@ -0,0 +1,304 @@
+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 HashProtocol
+    ##
+    # 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
+
+      ##
+      # 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)
+
+    ##
+    # Base class of all classes exported from Safer::HashProtocol.  Implements
+    # ProtocolBase#description signature.
+    class Base
+      Safer::IVar.instance_variable(self, :description)
+
+      ##
+      # :attr_reader: description
+      # Human-readable description of this HashProtocol.
+      Safer::IVar.export_reader(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
+
+    ##
+    # 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)
+
+      ##
+      # :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)
+
+      ##
+      # 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)
+      ##
+      # 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
+
+      ##
+      # 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
+      ##
+      # 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, 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
+      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
+      ##
+      # 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.  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
+      ##
+      # 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.  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
+      ##
+      # 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
+      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
+    end # Safer::HashProtocol::Only
+  end # Safer::HashProtocol
+end # Safer

data/lib/safer/ivar.rb

@@ -1,4 +1,4 @@
-module Safer
+class Safer
   ##
   # Create accessor functions for instance variables, in which the accessor
   # function is prefixed with the name of the class in which the instance
@@ -88,7 +88,7 @@ module Safer
   # search for when determining the set of instance variables defined by a
   # class.
   # 
-  module IVar
+  class IVar
 
     ##
     # Given a Class object, derive the prefix string for the accessor functions

data/lib/safer/protocol.rb

@@ -1,7 +1,7 @@
 require 'safer/ivar'
 
-module Safer
-  ## Safer::Protocol
+class Safer
+  ##
   # Named set of class- and instance- methods, with associated numbers of
   # arguments.  Call +create_from_class+ or +create_from_instance+ to create a
   # new +Protocol+ object.  Call +class_conforms?+ or +instance_conforms?+
@@ -234,7 +234,7 @@ module Safer
       end # Safer::Protocol::Signature.create
     end # Safer::Protocol::Signature
 
-    ## Safer::Protocol::Error
+    ##
     # Error generated when a class does not conform to a protocol signature.
     class Error < StandardError
       Safer::IVar.instance_variable(self, :error_object)
@@ -332,10 +332,38 @@ module Safer
       end # Safer::Protocol::Error::InstanceError
     end # Safer::Protocol::Error
 
+    ##
+    # Object provides an +===+ operator, which will match when the class
+    # conforms to the protocol.  Instances are not created directly by clients,
+    # but instances can be retrieved through
+    # Safer::Protocol#match_class and Safer::Protocol#match_instance.
+    class Match
+      Safer::IVar.instance_variable(self, :method)
+      ##
+      # [<tt>method</tt>] Method to call from owning Protocol to verify that
+      #                   an object matches an interface.
+      def initialize(method)
+        self.safer_protocol_match__method = method
+      end # Safer::Protocol::Match#initialize
+
+      ##
+      # Returns true if the object conforms to the protocol, and false if
+      # it does not.
+      def ===(obj)
+        violations = self.safer_protocol_match__method.call(obj)
+        if violations
+          false
+        else
+          true
+        end
+      end # Safer::Protocol::Match#===
+    end # Safer::Protocol::Match
 
     Safer::IVar.instance_variable(self, :name)
     Safer::IVar.instance_variable(self, :class_signature)
     Safer::IVar.instance_variable(self, :instance_signature)
+    Safer::IVar.instance_variable(self, :match_class)
+    Safer::IVar.instance_variable(self, :match_instance)
 
     ##
     # :attr_reader: name
@@ -352,6 +380,16 @@ module Safer
     # Signatures of required instance methods for objects implementing this
     # protocol.
     Safer::IVar.export_reader(self, :instance_signature)
+    ##
+    # :attr_reader: match_class
+    # Object provides === operation matching when #violations_from_class would
+    # return no violations.
+    Safer::IVar.export_reader(self, :match_class)
+    ##
+    # :attr_reader: match_instance
+    # Object provides === operation matching when #violations_from_instance
+    # would return no violations.
+    Safer::IVar.export_reader(self, :match_instance)
 
     ##
     # Create a +Protocol+ object.
@@ -363,6 +401,8 @@ module Safer
       self.safer_protocol__name = name
       self.safer_protocol__class_signature = class_signature
       self.safer_protocol__instance_signature = instance_signature
+      self.safer_protocol__match_class = Safer::Protocol::Match.new(self.method(:violations_from_class))
+      self.safer_protocol__match_instance = Safer::Protocol::Match.new(self.method(:violations_from_instance))
     end # Safer::Protocol#initialize
 
     ##

data/lib/safer.rb

@@ -9,8 +9,8 @@
 #                            Objective-C Protocols (which are similar to
 #                            Java interfaces, but do not require
 #                            inheritance).
-module Safer
+class Safer
   ##
   # Current release of Safer.
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/test/test_safer_hashprotocol.rb

@@ -0,0 +1,47 @@
+require 'safer/hashprotocol'
+require 'test/unit'
+
+class TC_SaferHashProtocol < Test::Unit::TestCase
+  SHP = Safer::HashProtocol
+  def setup
+    @any_hash = { :foo => nil }
+    @all_hash = { :foo => nil, :bar => nil, :baz => nil }
+    @fail_hash = { :blubby => nil }
+    @has_key = SHP::HasKey.create(*@all_hash.keys)
+  end
+  def teardown
+  end
+
+  def test_any
+    any = SHP::Any.new(*@has_key)
+    not_any = SHP::Not.new(any)
+    assert(any === @any_hash)
+    assert(! (not_any === @any_hash))
+    assert(any === @all_hash)
+    assert(! (not_any === @all_hash))
+    assert(! (any === @fail_hash))
+    assert(not_any === @fail_hash)
+  end
+
+  def test_all
+    all = SHP::All.new(*@has_key)
+    not_all = SHP::Not.new(all)
+
+    assert(! (all === @any_hash))
+    assert(not_all === @any_hash)
+    assert(all === @all_hash)
+    assert(! (not_all === @all_hash))
+    assert(! (all === @fail_hash))
+    assert(not_all === @fail_hash)
+  end
+
+  def test_only
+    any = SHP::Any.new(*@has_key)
+    only = SHP::Only.new(any)
+    all_plus = @all_hash.merge(@fail_hash)
+    assert(only === @all_hash)
+    assert(any === @all_hash)
+    assert(! (only === all_plus))
+    assert(any === all_plus)
+  end
+end

data/test/test_safer_protocol.rb

@@ -60,6 +60,7 @@ class TC_SaferProtocol < Test::Unit::TestCase
         :conforms => :instance_conforms?,
         :violations => :violations_from_instance,
         :get_object => proc do |obj| obj ; end,
+        :match => :match_instance,
         :error_type => Safer::Protocol::Error::InstanceError
       }
     else
@@ -67,6 +68,7 @@ class TC_SaferProtocol < Test::Unit::TestCase
         :conforms => :class_conforms?,
         :violations => :violations_from_class,
         :get_object => proc do |obj| obj.class ; end,
+        :match => :match_class,
         :error_type => Safer::Protocol::Error::ClassError
       }
     end
@@ -162,4 +164,30 @@ class TC_SaferProtocol < Test::Unit::TestCase
     run_classInstanceError(false)
     run_classInstanceError(true)
   end
+  def run_matchCase(methods, protocol, instance)
+    case methods[:get_object].call(instance)
+    when protocol.send(methods[:match])
+      true
+    else
+      false
+    end
+  end
+  def run_match(useinstance)
+    methods = get_methods(useinstance)
+    assert_same(run_matchCase(methods, @class_protocol, @class_instance), true)
+    assert_same(run_matchCase(methods, @class_protocol, @instance_instance), false)
+    assert_same(run_matchCase(methods, @class_protocol, @both_instance), true)
+
+    assert_same(run_matchCase(methods, @instance_protocol, @class_instance), false)
+    assert_same(run_matchCase(methods, @instance_protocol, @instance_instance), true)
+    assert_same(run_matchCase(methods, @instance_protocol, @both_instance), true)
+
+    assert_same(run_matchCase(methods, @both_protocol, @class_instance), false)
+    assert_same(run_matchCase(methods, @both_protocol, @instance_instance), false)
+    assert_same(run_matchCase(methods, @both_protocol, @both_instance), true)
+  end
+  def test_match
+    run_match(false)
+    run_match(true)
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: safer
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Aidan Cully
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-17 00:00:00 -04:00
+date: 2010-11-20 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,15 +52,18 @@ dependencies:
   version_requirements: *id002
 description: |-
   Safer is an umbrella library, with components designed to make it simple to
-  verify and improve the safety of your ruby code.  There are at present two
+  verify and improve the safety of your ruby code.  There are at present three
   modules under the safer umbrella:
   
-  [<tt>Safer::IVar</tt>]     generates specially-named accessor functions
-                             for class instance variables.
-  [<tt>Safer::Protocol</tt>] is used to provide a ruby analogue to
-                             Objective-C Protocols (which are similar to
-                             Java interfaces, but do not require
-                             inheritance).
+  [<tt>Safer::IVar</tt>]         generates specially-named accessor functions
+                                 for class instance variables.
+  [<tt>Safer::Protocol</tt>]     is used to provide a ruby analogue to
+                                 Objective-C Protocols (which are similar to
+                                 Java interfaces, but do not require
+                                 inheritance).
+  [<tt>Safer::HashProtocol</tt>] verifies that a Hash keys follow a defined
+  			       format.  Intended to help use of Hash objects as
+  			       keyword parameters.
 email: 
 - aidan@panix.com
 executables: []
@@ -80,8 +83,10 @@ files:
 - lib/safer.rb
 - lib/safer/ivar.rb
 - lib/safer/protocol.rb
+- lib/safer/hashprotocol.rb
 - test/test_safer_ivar.rb
 - test/test_safer_protocol.rb
+- test/test_safer_hashprotocol.rb
 has_rdoc: true
 homepage: http://safer.rubyforge.org
 licenses: []
@@ -118,5 +123,6 @@ signing_key:
 specification_version: 3
 summary: Safer is an umbrella library, with components designed to make it simple to verify and improve the safety of your ruby code
 test_files: 
+- test/test_safer_hashprotocol.rb
 - test/test_safer_ivar.rb
 - test/test_safer_protocol.rb