safer 0.1.0 → 0.2.0

data/History.txt

@@ -2,3 +2,8 @@
 
 * First release
 
+=== 0.2.0 / 2010-10-10
+
+* ClassProtocol renamed to Protocol.
+* Protocol can non-violently check if a class or instance conforms.
+* Added much documentation.

data/README.txt

@@ -1,6 +1,6 @@
 = safer
 
-http://safer.rubyforge.org/
+http://safer.rubyforge.org
 
 == DESCRIPTION:
 
@@ -19,7 +19,7 @@ modules under the safer umbrella:
 
 * Name instance variables after the class in which they are defined.  Generate
   accessor functions for these instance variables.
-* Define an "Protocol" class, and derive a signature from it.  Verify that
+* Define a "Protocol" class, and derive a signature from it.  Verify that
   another class (or an instance of that class) implements the protocol
   signature.
 
@@ -53,7 +53,7 @@ modules under the safer umbrella:
 
 == INSTALL:
 
-* sudo gem install
+* sudo gem install safer
 
 == DEVELOPERS:
 

data/Rakefile

@@ -4,5 +4,5 @@ require 'hoe'
 Hoe.spec 'safer' do
   developer('Aidan Cully', 'aidan@panix.com')
 
-  self.rubyforge_name = 'aidancully'
+  self.rubyforge_name = 'safer'
 end

data/lib/safer/ivar.rb

@@ -3,10 +3,95 @@ module Safer
   # Create accessor functions for instance variables, in which the accessor
   # function is prefixed with the name of the class in which the instance
   # variable is defined.
+  #
+  # ==Usage
+  # Create one or more instance variables using instance_variable .
+  # For example, the following code:
+  #  class Outer
+  #    Safer::IVar.instance_variable(self, :variable)
+  #    class Inner < Outer
+  #      Safer::IVar.instance_variable(self, :variable)
+  #    end
+  #  end
+  #  puts(Outer.instance_methods.grep(/__variable/).inspect)
+  #  puts(Outer::Inner.instance_methods.grep(/__variable/).inspect)
+  # produces the following output:
+  #  ["outer__variable", "outer__variable="]
+  #  ["outer_inner__variable", "outer_inner__variable=", "outer__variable", "outer__variable="]
+  #
+  # Accessors for Safer::IVar-defined instance variables can be created using
+  # export_reader, export_writer, and export_accessor .
+  #
+  # ==Rationale
+  # Safer::IVar is intended to improve the clarity and consistency of ruby
+  # code in at least the following (related) ways:
+  #
+  # 1. Reducing the probability of instance variable usage errors.
+  # 2. Documenting the instance variables attached to a class.
+  # 
+  # ===Error Reduction
+  # Safer::IVar should help in reducing errors in at least the following ways:
+  #
+  # * Encapsulation errors.  Traditional ruby instance variables defined by one
+  #   class are transparently accessible to all subclasses.  They are not,
+  #   however, part of the public interface to a class (unless an accessor is
+  #   defined), which means they are not generally documented.  These two
+  #   factors create a situation in which it is quite possible that a subclass
+  #   inadvertantly re-define an instance variable in such a way as to render
+  #   the subclass unusable.  Bugs of this sort can be very difficult to
+  #   resolve.
+  #
+  #   Because instance variables generated by Safer::IVar are prefixed with a
+  #   string derived from the class in which the variable is defined, it is much
+  #   less likely that developers _inadvertantly_ re-define instance variables
+  #   in sub-classes, dramatically reducing the likelihood of this type of
+  #   error.
+  # 
+  # * Misspelling errors.  For example, suppose you typically write software
+  #   using the en-us dialect, and have an object with a +@color+ instance
+  #   variable.  A en-uk speaker then submits a patch that sets the default
+  #   color to green:
+  #     --- ex1.rb	2010-09-28 06:24:52.000000000 -0400
+  #     +++ ex2.rb	2010-09-28 06:25:00.000000000 -0400
+  #     @@ -1,6 +1,7 @@
+  #      class Foo
+  #        def initialize
+  #          @size = 3
+  #     +    @colour = "green"
+  #        end
+  #        attr_reader :color
+  #      end
+  #   This code will not raise any exceptions, but its behavior does not match
+  #   developer intent.  On the other hand, using Safer::IVar
+  #     --- ex1-safer.rb	2010-09-28 06:31:51.000000000 -0400
+  #     +++ ex2-safer.rb	2010-09-28 06:32:08.000000000 -0400
+  #     @@ -1,7 +1,8 @@
+  #      class Foo
+  #        Safer::IVar.instance_variable(self, :size, :color)
+  #        Safer::IVar.export_reader(self, :color)
+  #        def initialize
+  #          self.foo__size = 3
+  #     +    self.foo__colour = "green"
+  #        end
+  #      end
+  #   The new code will raise an exception at the call to Foo.new, making it
+  #   much less likely that the error will go undetected.
+  # 
+  # ===Documentation
+  # Traditional ruby instance variables are defined and used in an <i>ad hoc</i>
+  # manner.  As such, there is no natural location in which the instance
+  # variables defined by a class can be documented, and no obvious way to
+  # determine the set of instance variables used in a class.  Safer::IVar
+  # instance variables will all be associated with a single call to
+  # Safer::IVar.instance_variable.  This provides both a natural location for
+  # documenting an instance variable's interpretation, as well as a string to
+  # search for when determining the set of instance variables defined by a
+  # class.
+  # 
   module IVar
 
     ##
-    # Given a class name, derive the prefix string for the accessor functions
+    # Given a Class object, derive the prefix string for the accessor functions
     # that instance_variable will create.
     def self.class_symbol_prefix(klass)
       klass.to_s.split('::').inject(nil) do |memo, el|
@@ -19,7 +104,21 @@ module Safer
           el.downcase
         end
       end
-    end
+    end # Safer::IVar.class_symbol_prefix
+
+    ##
+    # Used internally.
+    # [+klass+] Class object for which to generate a symbol name.
+    # [+nmlist+] Array of +Symbol+ objects.
+    # [_return_] Array of +Symbol+ objects generated from +klass+ and each
+    #            element of +nmlist+.
+    def self._symbol_names(klass, nmlist)
+      kname = self.class_symbol_prefix(klass)
+
+      nmlist.map do |nm|
+        (kname + '__' + nm.to_s).to_sym
+      end
+    end # Safer::IVar._symbol_names
 
     ##
     # compute accessor routine symbol names, so that the names include the
@@ -29,21 +128,17 @@ module Safer
     # [_return_] Array of +Symbol+ objects generated from +klass+ and each
     #            element of +nmlist+.
     # For example, given the following listing:
-    #   class MyClass
-    #     class SubClass
+    #   class OuterClass
+    #     class InnerClass
     #       SYMNM = Safer::IVar::symbol_names(self, :foo)
-    #       puts(SYMNM)
+    #       puts(SYMNM.to_s)
     #     end
     #   end
     # the following output would be produced:
-    #   myclass_subclass__foo
-    def self.symbol_names(klass, nmlist)
-      kname = self.class_symbol_prefix(klass)
-
-      nmlist.map do |nm|
-        (kname + '__' + nm.to_s).to_sym
-      end
-    end # Safer::IVar::symbol_names
+    #   outerclass_innerclass__foo
+    def self.symbol_names(klass, *nmlist)
+      self._symbol_names(klass, nmlist)
+    end # Safer::IVar.symbol_names
 
     ##
     # create accessor routines for an instance variable, with variable name
@@ -69,12 +164,12 @@ module Safer
     # The name-mangling signals that these instance variables are, for all
     # intents and purposes, private to +klass+.
     def self.instance_variable(klass, *nmlist)
-      self.symbol_names(klass, nmlist).each do |symnm|
+      self.symbol_names(klass, *nmlist).each do |symnm|
         klass.class_eval do
           attr_accessor symnm
         end
       end
-    end # Safer::IVar::instance_variable
+    end # Safer::IVar.instance_variable
 
     ##
     # export the reader routines for instance variables in a nicer way.
@@ -84,13 +179,13 @@ module Safer
     #            Each symbol in +nmlist+ should have previously been given as
     #            an argument to Safer::IVar::instance_variables(+klass+).
     def self.export_reader(klass, *nmlist)
-      symlist = self.symbol_names(klass, nmlist)
+      symlist = self.symbol_names(klass, *nmlist)
       nmlist.size.times do |index|
         thisnm = nmlist[index]
         thissym = symlist[index]
         klass.class_eval("def #{thisnm} ; self.#{thissym} ; end")
       end
-    end # Safer::IVar::export_reader
+    end # Safer::IVar.export_reader
 
     ##
     # export the writer routines for instance variables in a nicer way.
@@ -100,7 +195,7 @@ module Safer
     #            Each symbol in +nmlist+ should have previously been given as
     #            an argument to Safer::IVar::instance_variables(+klass+).
     def self.export_writer(klass, *nmlist)
-      symlist = self.symbol_names(klass, nmlist)
+      symlist = self.symbol_names(klass, *nmlist)
       nmlist.size.times do |index|
         thisnm = nmlist[index]
         thissym = symlist[index]
@@ -108,7 +203,7 @@ module Safer
           "def #{thisnm}=(value) ; self.#{thissym} = value ; end"
         )
       end
-    end # Safer::IVar::export_writer
+    end # Safer::IVar.export_writer
 
     ##
     # export both reader and writer routines for instance variables in a
@@ -121,7 +216,7 @@ module Safer
     def self.export_accessor(klass, *nmlist)
       self.export_reader(klass, *nmlist)
       self.export_writer(klass, *nmlist)
-    end # Safer::IVar::export_accessor
+    end # Safer::IVar.export_accessor
 
   end # Safer::IVar
 end # Safer

data/lib/safer/protocol.rb

@@ -1,25 +1,119 @@
 require 'safer/ivar'
 
 module Safer
-  ## Safer::ClassProtocol
+  ## Safer::Protocol
   # Named set of class- and instance- methods, with associated numbers of
   # arguments.  Call +create_from_class+ or +create_from_instance+ to create a
-  # new +ClassProtocol+ object.  Call +class_conforms?+ or +instance_conforms?+
+  # new +Protocol+ object.  Call +class_conforms?+ or +instance_conforms?+
   # to verify that a Class or instance of the class (respectively) conforms to
   # a protocol.
-  class ClassProtocol
+  # 
+  # ==Usage
+  # In the example, we define a class with a single instance variable,
+  # initialized from an argument to #initialize.  We must verify that the
+  # object corresponding to this argument implements a particular protocol.
+  # 
+  #  class YourClass
+  #    # Define a class or module containing all the class- and instance-
+  #    # methods that you require from objects passed into your methods.  Here,
+  #    # we expect the +Class+ object to implement a +foo+ method that takes
+  #    # three arguments, and for instances to implement a +bar+ method that
+  #    # takes one required argument, followed by any number of optional
+  #    # arguments:
+  #    class FooInterface
+  #      # Note that we have a good place to document what these interfaces
+  #      # mean, in standard RDoc fashion.
+  #      def self.foo(arg1, arg2, arg3)
+  #      end
+  #      def bar(arg1, *rest)
+  #      end
+  #    end
+  #    
+  #    # Derive a Safer::Protocol object from this class:
+  #    FOOPROTOCOL = Safer::Protocol.create_from_class(FooProtocol)
+  #    # Note: we could also do this step as follows:
+  #    # FOOPROTOCOL = Safer::Protocol.create_from_instance(FooProtocol.new)
+  #    
+  #    # Our #initialize method takes an object that should conform to
+  #    # FOOPROTOCOL.
+  #    def initialize(obj)
+  #      # verify that 'obj' conforms to FOOPROTOCOL.  If it does not, a
+  #      # Safer::Protocol::Error::InstanceError exception will be raised.
+  #      FOOPROTOCOL.instance_conforms?(obj)
+  #      @obj = obj
+  #    end
+  #    
+  #    # Now, functions can assume that @obj implements FOOPROTOCOL.
+  #    def quux
+  #      @obj.class.foo(self, 2, 3)
+  #      @obj.bar(@obj)
+  #    end
+  #    # including client functions.
+  #    attr_reader :obj
+  #  end
+  #
+  #  class Foo
+  #    # implements YourClass::FOOPROTOCOL
+  #    def self.foo(arg1, arg2, arg3)
+  #      return arg1 + arg2 + arg3
+  #    end
+  #    def bar(arg1, *rest)
+  #      "#{arg1.class.to_s}:#{rest.inspect}"
+  #    end
+  #  end
+  #  # should succeed.
+  #  a = YourClass::new(Foo.new)
+  #  # should raise a Safer::Protocol::Error::InstanceError.
+  #  b = YourClass::new(15)
+  #
+  # ==Rationale
+  # It is often the case that we expect objects passed to our methods to
+  # follow some usage protocol.  There are two ways this is usually accomplished
+  # in Ruby:
+  # 
+  # 1. We can ensure that objects are of a particular type, by calling
+  #    Object.kind_of? and related functions, disabling features or signaling
+  #    error when the object is of the wrong type.  If the object is of a
+  #    particular type, then we can reasonably expect that the object will
+  #    conform to that type's interface.
+  # 2. We can verify that objects respond to desired interfaces using
+  #    Object#respond_to? and related functions, disabling features or
+  #    signaling error when these objects do not support certain interfaces.
+  #
+  # The first method cannot always be used, as there exist circumstances in
+  # which the inheritance hierarchy cannot (or should not be used to) predict
+  # if an object can be used in a particular way.  (For example, the object
+  # hierarchy does not determine if an object is serializable -- there is no
+  # base class for which all sub-classes are serializable, and only sub-classes
+  # are serializable.)  So we must sometimes rely on directly verifying that an
+  # object supports a set of interfaces.
+  #
+  # Safer::Protocol is intended to improve the maintainability of code that
+  # must directly verify that objects implement desired interfaces.  A Protocol
+  # object is derived from a class definition that includes the set of methods
+  # for which the Protocol should test, and provides a simple means of testing
+  # whether another class object (or instance objects) implement that set of
+  # methods.  If the method set is not fully supported, a report object
+  # (Safer::Protocol::Error) is generated describing the differences between
+  # the object under test and the Protocol's requirements.
+  #
+  # Safer::Protocol is also intended to make it easier to document the
+  # interfaces required from a Protocol-implementing object.  Protocol objects
+  # are derived from Class objects, so one can document the interfaces required
+  # by the protocol by documenting the Class definition.
+  class Protocol
 
     ##
-    # Utility function used during ClassProtocol operations.  Given an
-    # +Array+, construct a +Hash+ with the values in the +Array+ as keys.
-    # If no block is provided, then the values for all keys in the +Hash+ will
-    # be +true+.  If a block is provided, the block is called for each value
-    # in the +Array+, and its return value will be stored as the value for
-    # that element in the +Hash+.  If the block returns +nil+, then the element
-    # will not be stored in the resulting +Hash+.
+    # Utility function used during Protocol operations.  Given an +Array+,
+    # construct a +Hash+ with the values in the +Array+ as keys.  If no block
+    # is provided, then the values for all keys in the +Hash+ will be +true+.
+    # If a block is provided, the block is called for each value in the
+    # +Array+, and its return value will be stored as the value for that
+    # element in the +Hash+.  If the block returns +nil+, then the element will
+    # not be stored in the resulting +Hash+.
     def self._array_to_table(array, &block)
       if ! block
-        block = proc do |el| true ; end
+        block = proc do |h, el| true ; end
       end
       array.inject(Hash::new) do |h, el|
         newval = block.call(h, el)
@@ -28,12 +122,12 @@ module Safer
         end
         h
       end
-    end
+    end # Safer::Protocol._array_to_table
 
     ##
     # Describes a set of methods that should be implemented by an object, but
-    # are not implemented.  The ClassProtocol::Error object will contain two
-    # ClassProtocol::Violation objects: one for class-method protocol
+    # are not implemented.  The Protocol::Error object will contain two
+    # Protocol::Violation objects: one for class-method protocol
     # violations, and one for instance-method protocol violations.
     class Violation
       Safer::IVar::instance_variable(self, :table)
@@ -47,7 +141,7 @@ module Safer
       # had a different arity (number of required / optional arguments) than
       # the protocol, the value for that method will be the arity discovered in
       # the object.  (The desired arity can be accessed through the
-      # ClassProtocol::Signature for that method.)
+      # Protocol::Signature for that method.)
       Safer::IVar::export_reader(self, :table)
       ##
       # :attr_reader: report
@@ -56,22 +150,22 @@ module Safer
       Safer::IVar::export_reader(self, :report)
 
       ##
-      # Create a new ClassProtocol::Violation object.
+      # Create a new Protocol::Violation object.
       def initialize(table, report)
-        self.safer_classprotocol_violation__table = table
-        self.safer_classprotocol_violation__report = report
-      end
+        self.safer_protocol_violation__table = table
+        self.safer_protocol_violation__report = report
+      end # Safer::Protocol::Violation#initialize
       ##
-      # Compare two ClassProtocol::Violation objects for content equality.
+      # Compare two Protocol::Violation objects for content equality.
       def ==(other_object)
         self.class == other_object.class &&
-          self.safer_classprotocol_violation__table == other_object.safer_classprotocol_violation__table
-      end
-    end
+          self.safer_protocol_violation__table == other_object.safer_protocol_violation__table
+      end # Safer::Protocol::Violation#==
+    end # Safer::Protocol::Violation
 
     ##
     # Hash of method_name => method.arity, describing a set of methods that
-    # we expect to see implemented in another class.  ClassProtocol will contain
+    # we expect to see implemented in another class.  Protocol will contain
     # two of these objects - one describing class methods, and one describing
     # instance methods.
     class Signature
@@ -83,16 +177,16 @@ module Safer
       Safer::IVar::export_reader(self, :table)
 
       ##
-      # Create a ClassProtocol::Signature object.
+      # Create a Protocol::Signature object.
       def initialize(table)
-        self.safer_classprotocol_signature__table = table
-      end
+        self.safer_protocol_signature__table = table
+      end # Safer::Protocol::Signature#initialize
       ##
-      # Compare two ClassProtocol::Signature objects for content equality.
+      # Compare two Protocol::Signature objects for content equality.
       def ==(other_object)
         self.class == other_object.class &&
-          self.safer_classprotocol_signature__table == other_object.safer_classprotocol_signature__table
-      end
+          self.safer_protocol_signature__table == other_object.safer_protocol_signature__table
+      end # Safer::Protocol::Signature#==
 
       ##
       # Given an object, and the name of the method for getting a named method
@@ -102,7 +196,7 @@ module Safer
         report = ''
         have_error = false
         error_table = Hash::new
-        self.safer_classprotocol_signature__table.each_pair do |name, arity|
+        self.safer_protocol_signature__table.each_pair do |name, arity|
           begin
             m = object.send(get_method, name)
             if m.arity != arity
@@ -118,17 +212,17 @@ module Safer
         end
 
         if have_error
-          Safer::ClassProtocol::Violation.new(error_table, report)
+          Safer::Protocol::Violation.new(error_table, report)
         else
           nil
         end
-      end
+      end # Safer::Protocol::Signature#find_violations
 
       ##
       # Derive a Signature from an object.
       def self.create(object, get_methods, get_method, &filter)
         method_names = object.send(get_methods)
-        method_table = Safer::ClassProtocol._array_to_table(method_names) do
+        method_table = Safer::Protocol._array_to_table(method_names) do
           |h, method_name|
           if filter.call(method_name)
             m = object.send(get_method, method_name)
@@ -136,10 +230,10 @@ module Safer
           end
         end
         self.new(method_table)
-      end
-    end
+      end # Safer::Protocol::Signature.create
+    end # Safer::Protocol::Signature
 
-    ## Safer::ClassProtocol::Error
+    ## 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)
@@ -154,16 +248,16 @@ module Safer
       Safer::IVar::export_reader(self, :error_object)
       ##
       # :attr_reader: protocol
-      # ClassProtocol object describing the signature that error_object failed
+      # Protocol object describing the signature that error_object failed
       # to properly implement.
       Safer::IVar::export_reader(self, :protocol)
       ##
       # :attr_reader: class_violations
-      # ClassProtocol::Violation describing class-method protocol violations.
+      # Protocol::Violation describing class-method protocol violations.
       Safer::IVar::export_reader(self, :class_violations)
       ##
       # :attr_reader: instance_violations
-      # ClassProtocol::Violation describing instance-method protocol violations.
+      # Protocol::Violation describing instance-method protocol violations.
       Safer::IVar::export_reader(self, :instance_violations)
       ##
       # :attr_reader: report
@@ -173,19 +267,19 @@ module Safer
 
 
       ##
-      # Create a Safer::ClassProtocol::Error object.
+      # Create a Safer::Protocol::Error object.
       # Used internally.
       def initialize(message, error_object, protocol, class_violations, instance_violations)
         super(message)
-        self.safer_classprotocol_error__error_object = error_object
-        self.safer_classprotocol_error__protocol = protocol
-        self.safer_classprotocol_error__class_violations = class_violations
-        self.safer_classprotocol_error__instance_violations = instance_violations
+        self.safer_protocol_error__error_object = error_object
+        self.safer_protocol_error__protocol = protocol
+        self.safer_protocol_error__class_violations = class_violations
+        self.safer_protocol_error__instance_violations = instance_violations
         report = ''
         if class_violations
           report +=
             "Class method errors:\n" +
-            self.safer_classprotocol_error__class_violations.report
+            self.safer_protocol_error__class_violations.report
           if instance_violations
             report += "\n\n"
           end
@@ -193,49 +287,49 @@ module Safer
         if instance_violations
           report +=
             "Instance method errors:\n" +
-            self.safer_classprotocol_error__instance_violations.report
+            self.safer_protocol_error__instance_violations.report
         end
-        self.safer_classprotocol_error__report = report
-      end # Safer::ClassProtocol::Error#initialize
+        self.safer_protocol_error__report = report
+      end # Safer::Protocol::Error#initialize
 
       ##
-      # Compare two Safer::ClassProtocol::Error objects for content equality.
+      # Compare two Safer::Protocol::Error objects for content equality.
       def ==(other_object)
         self.class == other_object.class &&
           self.error_object == other_object.error_object &&
           self.protocol == other_object.protocol &&
           self.class_violations == other_object.class_violations &&
           self.instance_violations == other_object.instance_violations
-      end
+      end # Safer::Protocol::Error#==
 
       ##
       # Error generated when a Class object does not conform to a desired
       # protocol.
-      class ClassError < Safer::ClassProtocol::Error
+      class ClassError < Safer::Protocol::Error
         ##
-        # Create a Safer::ClassProtocol::Error::ClassError object.
+        # Create a Safer::Protocol::Error::ClassError object.
         def initialize(error_object, protocol, class_violations, instance_violations)
           super(
             "Class #{error_object} does not implement protocol" +
               "#{protocol.name}.",
             error_object, protocol, class_violations, instance_violations)
-        end
-      end # Safer::ClassProtocol::Error::ClassError
+        end # Safer::Protocol::Error::ClassError#initialize
+      end # Safer::Protocol::Error::ClassError
 
       ##
       # Error generated when an instance object does not conform to a desired
       # protocol.
-      class InstanceError < Safer::ClassProtocol::Error
+      class InstanceError < Safer::Protocol::Error
         ##
-        # Create a Safer::ClassProtocol::Error::InstanceError object.
+        # Create a Safer::Protocol::Error::InstanceError object.
         def initialize(error_object, protocol, class_violations, instance_violations)
           super(
             "Instance of #{error_object.class} does not implement protocol" +
               "#{protocol.name}.",
             error_object, protocol, class_violations, instance_violations)
-        end
-      end # Safer::ClassProtocol::Error::InstanceError
-    end # Safer::ClassProtocol::Error
+        end # Safer::Protocol::Error::InstanceError#initialize
+      end # Safer::Protocol::Error::InstanceError
+    end # Safer::Protocol::Error
 
 
     Safer::IVar::instance_variable(self, :name)
@@ -259,46 +353,78 @@ module Safer
     Safer::IVar::export_reader(self, :instance_signature)
 
     ##
-    # Create a +ClassProtocol+ object.
+    # Create a +Protocol+ object.
     # Used internally.
     # [+name+] Value for +name+ field object.
     # [+class_signature+] Value for +class_signature+ field.
     # [+instance_signature+] Value for +instance_signature+ field.
     def initialize(name, class_signature, instance_signature)
-      self.safer_classprotocol__name = name
-      self.safer_classprotocol__class_signature = class_signature
-      self.safer_classprotocol__instance_signature = instance_signature
-    end # Safer::ClassProtocol#initialize
+      self.safer_protocol__name = name
+      self.safer_protocol__class_signature = class_signature
+      self.safer_protocol__instance_signature = instance_signature
+    end # Safer::Protocol#initialize
+
+    ##
+    # Given a Class object, find the protocol methods that are not supported by
+    # a class, or its instances.
+    # [_returns_] If protocol violations are found, returns a
+    #             Safer::Protocol::Error::ClassError object describing the
+    #             violations.  Otherwise, returns +nil+.
+    def violations_from_class(klass)
+      class_violations = self.safer_protocol__class_signature.find_violations(klass, :method)
+      instance_violations = self.safer_protocol__instance_signature.find_violations(klass, :instance_method)
+
+      if class_violations || instance_violations
+        Error::ClassError.new(klass, self, class_violations, instance_violations)
+      else
+        nil
+      end
+    end # Safer::Protocol#violations_from_class
+
+    ##
+    # Given an instance object, find the protocol methods that are not supported
+    # by the instance, or its class.
+    # [_returns_] If protocol violations are found, returns a
+    #             Safer::Protocol::Error::InstanceError object describing the
+    #             violations.  Otherwise, returns +nil+.
+    def violations_from_instance(instance)
+      class_violations = self.safer_protocol__class_signature.find_violations(instance.class, :method)
+      instance_violations = self.safer_protocol__instance_signature.find_violations(instance, :method)
+      if class_violations || instance_violations
+        Error::InstanceError.new(instance, self, class_violations, instance_violations)
+      else
+        nil
+      end
+    end # Safer::Protocol#violations_from_instance
 
     ##
     # Check that a Class object conforms to this protocol.
     def class_conforms?(klass)
-      class_violations = self.safer_classprotocol__class_signature.find_violations(klass, :method)
-      instance_violations = self.safer_classprotocol__instance_signature.find_violations(klass, :instance_method)
-      if class_violations || instance_violations
-        raise(Error::ClassError.new(klass, self, class_violations, instance_violations))
+      violations = self.violations_from_class(klass)
+      if violations
+        raise violations
       end
       true
-    end # Safer::ClassProtocol#class_conforms?
+    end # Safer::Protocol#class_conforms?
+
     ##
     # Check that an instance object conforms to this protocol.
     def instance_conforms?(instance)
-      class_violations = self.safer_classprotocol__class_signature.find_violations(instance.class, :method)
-      instance_violations = self.safer_classprotocol__instance_signature.find_violations(instance, :method)
-      if class_violations || instance_violations
-        raise(Error::InstanceError.new(instance, self, class_violations, instance_violations))
+      violations = self.violations_from_instance(instance)
+      if violations
+        raise violations
       end
       true
-    end # Safer::ClassProtocol#instance_conforms?
+    end # Safer::Protocol#instance_conforms?
 
     ##
     # Given a +Class+ object +klass+ and a +Class+ object +base+, create a
-    # +ClassProtocol+ object representing the methods implemented in +klass+
+    # +Protocol+ object representing the methods implemented in +klass+
     # that are not present in +base+.
-    # [+klass+] +Class+ object from which to derive a +ClassProtocol+.
+    # [+klass+] +Class+ object from which to derive a +Protocol+.
     # [+base+] +Class+ object describing routines that will be implemented by
     #          +klass+, but which should not be included in the returned
-    #          +ClassProtocol+.
+    #          +Protocol+.
     def self.create_from_class(klass, base = Object)
       class_signature = Signature.create(klass, :methods, :method) do
         |method_name|
@@ -311,11 +437,11 @@ module Safer
       end
 
       self.new(klass.to_s, class_signature, instance_signature)
-    end # Safer::ClassProtocol.create_from_class
+    end # Safer::Protocol.create_from_class
 
     ##
     # Given an instance object +instance+ and a +Class+ object +baseclass+,
-    # create a +ClassProtocol+ object representing the methods implemented in
+    # create a +Protocol+ object representing the methods implemented in
     # +klass+ that are not present in +base+.
     def self.create_from_instance(instance, baseclass = Object)
       class_signature = Signature.create(instance.class, :methods, :method) do
@@ -329,7 +455,7 @@ module Safer
       end
 
       self.new(instance.class.to_s, class_signature, instance_signature)
-    end # Safer::ClassProtocol.create_from_instance
+    end # Safer::Protocol.create_from_instance
 
-  end # Safer::ClassProtocol
+  end # Safer::Protocol
 end # Safer

data/lib/safer.rb

@@ -4,5 +4,5 @@
 module Safer
   ##
   # Current release of Safer.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/test/test_safer_protocol.rb

@@ -34,9 +34,9 @@ end
 
 class TC_SaferProtocol < Test::Unit::TestCase
   def setup
-    @class_protocol = Safer::ClassProtocol.create_from_class(TestArityClass)
-    @instance_protocol = Safer::ClassProtocol.create_from_class(TestArityInstance)
-    @both_protocol = Safer::ClassProtocol.create_from_class(TestArityBoth)
+    @class_protocol = Safer::Protocol.create_from_class(TestArityClass)
+    @instance_protocol = Safer::Protocol.create_from_class(TestArityInstance)
+    @both_protocol = Safer::Protocol.create_from_class(TestArityBoth)
 
     @class_instance = TestArityClass::new
     @instance_instance = TestArityInstance::new
@@ -56,9 +56,19 @@ class TC_SaferProtocol < Test::Unit::TestCase
 
   def get_methods(useinstance)
     if useinstance
-      [ :instance_conforms?, proc do |obj| obj ; end, Safer::ClassProtocol::Error::InstanceError ]
+      {
+        :conforms => :instance_conforms?,
+        :violations => :violations_from_instance,
+        :get_object => proc do |obj| obj ; end,
+        :error_type => Safer::Protocol::Error::InstanceError
+      }
     else
-      [ :class_conforms?, proc do |obj| obj.class ; end, Safer::ClassProtocol::Error::ClassError ]
+      {
+        :conforms => :class_conforms?,
+        :violations => :violations_from_class,
+        :get_object => proc do |obj| obj.class ; end,
+        :error_type => Safer::Protocol::Error::ClassError
+      }
     end
   end
 
@@ -71,14 +81,19 @@ class TC_SaferProtocol < Test::Unit::TestCase
   end
 
   def run_shouldConform(useinstance)
-    conforms_method, object_get, except_type = get_methods(useinstance)
+    methods = get_methods(useinstance)
     assert_nothing_thrown do
-      @class_protocol.send(conforms_method, object_get.call(@class_instance))
-      @instance_protocol.send(conforms_method, object_get.call(@instance_instance))
-      @both_protocol.send(conforms_method, object_get.call(@both_instance))
-      @class_protocol.send(conforms_method, object_get.call(@both_instance))
-      @instance_protocol.send(conforms_method, object_get.call(@both_instance))
+      @class_protocol.send(methods[:conforms], methods[:get_object].call(@class_instance))
+      @instance_protocol.send(methods[:conforms], methods[:get_object].call(@instance_instance))
+      @both_protocol.send(methods[:conforms], methods[:get_object].call(@both_instance))
+      @class_protocol.send(methods[:conforms], methods[:get_object].call(@both_instance))
+      @instance_protocol.send(methods[:conforms], methods[:get_object].call(@both_instance))
     end
+    assert_same(@class_protocol.send(methods[:violations], methods[:get_object].call(@class_instance)), nil)
+    assert_same(@instance_protocol.send(methods[:violations], methods[:get_object].call(@instance_instance)), nil)
+    assert_same(@both_protocol.send(methods[:violations], methods[:get_object].call(@both_instance)), nil)
+    assert_same(@class_protocol.send(methods[:violations], methods[:get_object].call(@both_instance)), nil)
+    assert_same(@instance_protocol.send(methods[:violations], methods[:get_object].call(@both_instance)), nil)
   end
   def test_shouldConform
     run_shouldConform(false)
@@ -86,16 +101,18 @@ class TC_SaferProtocol < Test::Unit::TestCase
   end
 
   def run_arity(useinstance)
-    conforms_method, object_get, except_type = get_methods(useinstance)
+    methods = get_methods(useinstance)
+    violations = @instance_protocol.send(methods[:violations], methods[:get_object].call(@error_instance))
+    assert_same(violations.class, methods[:error_type])
+    assert_same(methods[:get_object].call(@error_instance), violations.error_object)
+    assert_same(@instance_protocol, violations.protocol)
+    assert_same(nil, violations.class_violations)
+    assert_equal({ 'arity_empty' => 1 }, violations.instance_violations.table)
     begin
-      @instance_protocol.send(conforms_method, object_get.call(@error_instance))
+      @instance_protocol.send(methods[:conforms], methods[:get_object].call(@error_instance))
       flunk("Expected exception.")
-    rescue Safer::ClassProtocol::Error => e
-      assert_same(e.class, except_type)
-      assert_same(object_get.call(@error_instance), e.error_object)
-      assert_same(@instance_protocol, e.protocol)
-      assert_same(nil, e.class_violations)
-      assert_equal({ 'arity_empty' => 1 }, e.instance_violations.table)
+    rescue Safer::Protocol::Error => e
+      assert_equal(violations, e)
     end
   end
   def test_arity
@@ -104,37 +121,41 @@ class TC_SaferProtocol < Test::Unit::TestCase
   end
 
   def run_classInstanceError(useinstance)
-    conforms_method, object_get, except_type = get_methods(useinstance)
+    methods = get_methods(useinstance)
+
+    class_instance_violations = @instance_protocol.send(methods[:violations], methods[:get_object].call(@class_instance))
+    assert_same(class_instance_violations.class, methods[:error_type])
+    assert_same(class_instance_violations.error_object, methods[:get_object].call(@class_instance))
+    assert_same(class_instance_violations.protocol, @instance_protocol)
+    assert_same(nil, class_instance_violations.class_violations)
+    assert_equal(class_instance_violations.instance_violations.table.keys.size, @instance_protocol.instance_signature.table.keys.size)
+    @instance_protocol.instance_signature.table.each_pair do |key, arity|
+      assert(class_instance_violations.instance_violations.table.has_key?(key))
+      assert_same(class_instance_violations.instance_violations.table[key], true)
+    end
 
-    class_instance_error = nil
     begin
-      @instance_protocol.send(conforms_method, object_get.call(@class_instance))
+      @instance_protocol.send(methods[:conforms], methods[:get_object].call(@class_instance))
       flunk("Expected exception.")
-    rescue Safer::ClassProtocol::Error => e
-      assert_same(e.class, except_type)
-      assert_same(e.error_object, object_get.call(@class_instance))
-      assert_same(e.protocol, @instance_protocol)
-      assert_same(nil, e.class_violations)
-      assert_equal(e.instance_violations.table.keys.size, @instance_protocol.instance_signature.table.keys.size)
-      @instance_protocol.instance_signature.table.each_pair do |key, arity|
-        assert(e.instance_violations.table.has_key?(key))
-        assert_same(e.instance_violations.table[key], true)
-      end
-      class_instance_error = e
+    rescue Safer::Protocol::Error => e
+      assert_equal(e, class_instance_violations)
     end
 
+    both_instance_violations = @both_protocol.send(methods[:violations], methods[:get_object].call(@class_instance))
+    assert_same(both_instance_violations.class, methods[:error_type])
+    assert_same(both_instance_violations.error_object, methods[:get_object].call(@class_instance))
+    assert_same(both_instance_violations.protocol, @both_protocol)
+    assert_equal(
+      both_instance_violations.instance_violations, class_instance_violations.instance_violations)
+    assert_same(
+      both_instance_violations.class_violations, class_instance_violations.class_violations)
+    assert_equal(both_instance_violations.report, class_instance_violations.report)
+
     begin
-      @both_protocol.send(conforms_method, object_get.call(@class_instance))
+      @both_protocol.send(methods[:conforms], methods[:get_object].call(@class_instance))
       flunk("Expected exception.")
-    rescue Safer::ClassProtocol::Error => e
-      assert_same(e.class, except_type)
-      assert_same(e.error_object, object_get.call(@class_instance))
-      assert_same(e.protocol, @both_protocol)
-      assert_equal(
-        e.instance_violations, class_instance_error.instance_violations)
-      assert_same(
-        e.class_violations, class_instance_error.class_violations)
-      assert_equal(e.report, class_instance_error.report)
+    rescue Safer::Protocol::Error => e
+      assert_equal(both_instance_violations, e)
     end
   end
   def test_classInstanceError

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: safer
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Aidan Cully
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-23 00:00:00 -04:00
+date: 2010-10-10 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -83,7 +83,7 @@ files:
 - test/test_safer_ivar.rb
 - test/test_safer_protocol.rb
 has_rdoc: true
-homepage: http://safer.rubyforge.org/
+homepage: http://safer.rubyforge.org
 licenses: []
 
 post_install_message: 
@@ -112,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: "0"
 requirements: []
 
-rubyforge_project: aidancully
+rubyforge_project: safer
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3