safer 0.3.1 → 0.4.0

data/lib/safer/protocol.rb

@@ -1,502 +1,499 @@
 require 'safer/ivar'
 
-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?+
+# to verify that a Class or instance of the class (respectively) conforms to
+# a protocol.
+# 
+# ==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 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 +Protocol+ object.  Call +class_conforms?+ or +instance_conforms?+
-  # to verify that a Class or instance of the class (respectively) conforms to
-  # a protocol.
-  # 
-  # ==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 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 |h, el| true ; end
-      end
-      array.inject(Hash.new) do |h, el|
-        newval = block.call(h, el)
-        if newval
-          h[el] = newval
-        end
-        h
+  # 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 |h, el| true ; end
+    end
+    array.inject(Hash.new) do |h, el|
+      newval = block.call(h, el)
+      if newval
+        h[el] = newval
       end
-    end # Safer::Protocol._array_to_table
+      h
+    end
+  end # Safer::Protocol._array_to_table
 
-    ##
-    # Describes a set of methods that should be implemented by an object, but
-    # 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)
-      Safer::IVar.instance_variable(self, :report)
+  ##
+  # Describes a set of methods that should be implemented by an object, but
+  # 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)
+    Safer::IVar.instance_variable(self, :report)
 
-      ##
-      # :attr_reader: table
-      # Hash describing method violations.  Keys are the names of methods
-      # containing errors.  If a method was unimplemented in the class, the
-      # value for that method will be +true+.  If a method was implemented, but
-      # 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
-      # Protocol::Signature for that method.)
-      Safer::IVar.export_reader(self, :table) 
+    ##
+    # :attr_reader: table
+    # Hash describing method violations.  Keys are the names of methods
+    # containing errors.  If a method was unimplemented in the class, the
+    # value for that method will be +true+.  If a method was implemented, but
+    # 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
+    # Protocol::Signature for that method.)
+    Safer::IVar.export_reader(self, :table) 
 
-      ##
-      # :attr_reader: report
-      # String describing the errors from +table+ in a more human-readable
-      # fashion.
-      Safer::IVar.export_reader(self, :report)
+    ##
+    # :attr_reader: report
+    # String describing the errors from +table+ in a more human-readable
+    # fashion.
+    Safer::IVar.export_reader(self, :report)
 
-      ##
-      # Create a new Protocol::Violation object.
-      def initialize(table, report)
-        self.safer_protocol_violation__table = table
-        self.safer_protocol_violation__report = report
-      end # Safer::Protocol::Violation#initialize
-      ##
-      # Compare two Protocol::Violation objects for content equality.
-      def ==(other_object)
-        self.class == other_object.class &&
-          self.safer_protocol_violation__table == other_object.safer_protocol_violation__table
-      end # Safer::Protocol::Violation#==
-    end # Safer::Protocol::Violation
+    ##
+    # Create a new Protocol::Violation object.
+    def initialize(table, report)
+      self.safer_protocol_violation__table = table
+      self.safer_protocol_violation__report = report
+    end # Safer::Protocol::Violation#initialize
+    ##
+    # Compare two Protocol::Violation objects for content equality.
+    def ==(other_object)
+      self.class == other_object.class &&
+        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.  Protocol will contain
+  # two of these objects - one describing class methods, and one describing
+  # instance methods.
+  class Signature
+    Safer::IVar.instance_variable(self, :table)
     ##
-    # Hash of method_name => method.arity, describing a set of methods that
-    # 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
-      Safer::IVar.instance_variable(self, :table)
-      ##
-      # :attr_reader: table
-      # +Hash+ object, in which the keys are the names of methods, and the
-      # value for a key is the required arity of that method.
-      Safer::IVar.export_reader(self, :table)
+    # :attr_reader: table
+    # +Hash+ object, in which the keys are the names of methods, and the
+    # value for a key is the required arity of that method.
+    Safer::IVar.export_reader(self, :table)
 
-      ##
-      # Create a Protocol::Signature object.
-      def initialize(table)
-        self.safer_protocol_signature__table = table
-      end # Safer::Protocol::Signature#initialize
-      ##
-      # Compare two Protocol::Signature objects for content equality.
-      def ==(other_object)
-        self.class == other_object.class &&
-          self.safer_protocol_signature__table == other_object.safer_protocol_signature__table
-      end # Safer::Protocol::Signature#==
+    ##
+    # Create a Protocol::Signature object.
+    def initialize(table)
+      self.safer_protocol_signature__table = table
+    end # Safer::Protocol::Signature#initialize
+    ##
+    # Compare two Protocol::Signature objects for content equality.
+    def ==(other_object)
+      self.class == other_object.class &&
+        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
-      # from that object, check that the object implements this function
-      # signature.
-      def find_violations(object, get_method)
-        report = ''
-        have_error = false
-        error_table = Hash.new
-        self.safer_protocol_signature__table.each_pair do |name, arity|
-          begin
-            m = object.send(get_method, name)
-            if m.arity != arity
-              report += "#{get_method}(#{name}) arity #{m.arity} != desired #{arity}.\n"
-              error_table[name] = m.arity
-              have_error = true
-            end
-          rescue NameError => e
-            report += "#{get_method}(#{name}) unimplemented.\n"
-            error_table[name] = true
+    ##
+    # Given an object, and the name of the method for getting a named method
+    # from that object, check that the object implements this function
+    # signature.
+    def find_violations(object, get_method)
+      report = ''
+      have_error = false
+      error_table = Hash.new
+      self.safer_protocol_signature__table.each_pair do |name, arity|
+        begin
+          m = object.send(get_method, name)
+          if m.arity != arity
+            report += "#{get_method}(#{name}) arity #{m.arity} != desired #{arity}.\n"
+            error_table[name] = m.arity
             have_error = true
           end
+        rescue NameError => e
+          report += "#{get_method}(#{name}) unimplemented.\n"
+          error_table[name] = true
+          have_error = true
         end
+      end
 
-        if have_error
-          Safer::Protocol::Violation.new(error_table, report)
-        else
-          nil
-        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::Protocol._array_to_table(method_names) do
-          |h, method_name|
-          if filter.call(method_name)
-            m = object.send(get_method, method_name)
-            m.arity
-          end
-        end
-        self.new(method_table)
-      end # Safer::Protocol::Signature.create
-    end # Safer::Protocol::Signature
+      if have_error
+        Safer::Protocol::Violation.new(error_table, report)
+      else
+        nil
+      end
+    end # Safer::Protocol::Signature#find_violations
 
     ##
-    # Error generated when a class does not conform to a protocol signature.
-    class Error < StandardError
-      Safer::IVar.instance_variable(self, :error_object)
-      Safer::IVar.instance_variable(self, :protocol)
-      Safer::IVar.instance_variable(self, :class_violations)
-      Safer::IVar.instance_variable(self, :instance_violations)
-      Safer::IVar.instance_variable(self, :report)
-
-      ##
-      # :attr_reader: error_object
-      # Object that does not properly implement a desired method protocol.
-      Safer::IVar.export_reader(self, :error_object)
-      ##
-      # :attr_reader: protocol
-      # Protocol object describing the signature that error_object failed
-      # to properly implement.
-      Safer::IVar.export_reader(self, :protocol)
-      ##
-      # :attr_reader: class_violations
-      # Protocol::Violation describing class-method protocol violations.
-      Safer::IVar.export_reader(self, :class_violations)
-      ##
-      # :attr_reader: instance_violations
-      # Protocol::Violation describing instance-method protocol violations.
-      Safer::IVar.export_reader(self, :instance_violations)
-      ##
-      # :attr_reader: report
-      # String for displaying human-readable error message describing protocol
-      # violations.
-      Safer::IVar.export_reader(self, :report)
-
-
-      ##
-      # Create a Safer::Protocol::Error object.
-      # Used internally.
-      def initialize(message, error_object, protocol, class_violations, instance_violations)
-        super(message)
-        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_protocol_error__class_violations.report
-          if instance_violations
-            report += "\n\n"
-          end
+    # Derive a Signature from an object.
+    def self.create(object, get_methods, get_method, &filter)
+      method_names = object.send(get_methods)
+      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)
+          m.arity
         end
-        if instance_violations
-          report +=
-            "Instance method errors:\n" +
-            self.safer_protocol_error__instance_violations.report
-        end
-        self.safer_protocol_error__report = report
-      end # Safer::Protocol::Error#initialize
+      end
+      self.new(method_table)
+    end # Safer::Protocol::Signature.create
+  end # Safer::Protocol::Signature
 
-      ##
-      # 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 # 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)
+    Safer::IVar.instance_variable(self, :protocol)
+    Safer::IVar.instance_variable(self, :class_violations)
+    Safer::IVar.instance_variable(self, :instance_violations)
+    Safer::IVar.instance_variable(self, :report)
 
-      ##
-      # Error generated when a Class object does not conform to a desired
-      # protocol.
-      class ClassError < Safer::Protocol::Error
-        ##
-        # 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 # Safer::Protocol::Error::ClassError#initialize
-      end # Safer::Protocol::Error::ClassError
+    ##
+    # :attr_reader: error_object
+    # Object that does not properly implement a desired method protocol.
+    Safer::IVar.export_reader(self, :error_object)
+    ##
+    # :attr_reader: protocol
+    # Protocol object describing the signature that error_object failed
+    # to properly implement.
+    Safer::IVar.export_reader(self, :protocol)
+    ##
+    # :attr_reader: class_violations
+    # Protocol::Violation describing class-method protocol violations.
+    Safer::IVar.export_reader(self, :class_violations)
+    ##
+    # :attr_reader: instance_violations
+    # Protocol::Violation describing instance-method protocol violations.
+    Safer::IVar.export_reader(self, :instance_violations)
+    ##
+    # :attr_reader: report
+    # String for displaying human-readable error message describing protocol
+    # violations.
+    Safer::IVar.export_reader(self, :report)
 
-      ##
-      # Error generated when an instance object does not conform to a desired
-      # protocol.
-      class InstanceError < Safer::Protocol::Error
-        ##
-        # 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 # Safer::Protocol::Error::InstanceError#initialize
-      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
+    # Create a Safer::Protocol::Error object.
+    # Used internally.
+    def initialize(message, error_object, protocol, class_violations, instance_violations)
+      super(message)
+      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_protocol_error__class_violations.report
+        if instance_violations
+          report += "\n\n"
         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)
+      end
+      if instance_violations
+        report +=
+          "Instance method errors:\n" +
+          self.safer_protocol_error__instance_violations.report
+      end
+      self.safer_protocol_error__report = report
+    end # Safer::Protocol::Error#initialize
 
     ##
-    # :attr_reader: name
-    # Name of this protocol signature.  Typically derived from the class name
-    # from which this signature is derived.
-    Safer::IVar.export_reader(self, :name)
+    # 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 # Safer::Protocol::Error#==
+
     ##
-    # :attr_reader: class_signature
-    # Signatures of required class methods for objects implementing this
+    # Error generated when a Class object does not conform to a desired
     # protocol.
-    Safer::IVar.export_reader(self, :class_signature)
+    class ClassError < Safer::Protocol::Error
+      ##
+      # 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 # Safer::Protocol::Error::ClassError#initialize
+    end # Safer::Protocol::Error::ClassError
+
     ##
-    # :attr_reader: instance_signature
-    # Signatures of required instance methods for objects implementing this
+    # Error generated when an instance object does not conform to a desired
     # 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)
+    class InstanceError < Safer::Protocol::Error
+      ##
+      # 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 # Safer::Protocol::Error::InstanceError#initialize
+    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)
     ##
-    # 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_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
+    # [<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
 
     ##
-    # 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)
+    # 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
-        nil
+        true
       end
-    end # Safer::Protocol#violations_from_class
+    end # Safer::Protocol::Match#===
+  end # Safer::Protocol::Match
 
-    ##
-    # 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
+  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)
 
-    ##
-    # Check that a Class object conforms to this protocol.
-    def class_conforms?(klass)
-      violations = self.violations_from_class(klass)
-      if violations
-        raise violations
-      end
-      true
-    end # Safer::Protocol#class_conforms?
+  ##
+  # :attr_reader: name
+  # Name of this protocol signature.  Typically derived from the class name
+  # from which this signature is derived.
+  Safer::IVar.export_reader(self, :name)
+  ##
+  # :attr_reader: class_signature
+  # Signatures of required class methods for objects implementing this
+  # protocol.
+  Safer::IVar.export_reader(self, :class_signature)
+  ##
+  # :attr_reader: instance_signature
+  # 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)
 
-    ##
-    # Check that an instance object conforms to this protocol.
-    def instance_conforms?(instance)
-      violations = self.violations_from_instance(instance)
-      if violations
-        raise violations
-      end
-      true
-    end # Safer::Protocol#instance_conforms?
+  ##
+  # 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_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
 
-    ##
-    # Given a +Class+ object +klass+ and a +Class+ object +base+, create a
-    # +Protocol+ object representing the methods implemented in +klass+
-    # that are not present in +base+.
-    # [+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
-    #          +Protocol+.
-    def self.create_from_class(klass, base = Object)
-      class_signature = Signature.create(klass, :methods, :method) do
-        |method_name|
-        ! Class.respond_to?(method_name)
-      end
-      baseinstance_table = self._array_to_table(base.instance_methods)
-      instance_signature = Signature.create(klass, :instance_methods, :instance_method) do
-        |method_name|
-        ! baseinstance_table.has_key?(method_name)
-      end
+  ##
+  # 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
 
-      self.new(klass.to_s, class_signature, instance_signature)
-    end # Safer::Protocol.create_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
 
-    ##
-    # Given an instance object +instance+ and a +Class+ object +baseclass+,
-    # 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
-        |method_name|
-        ! Class.method_defined?(method_name)
-      end
-      baseinstance_table = self._array_to_table(base.instance_methods)
-      instance_signature = Signature.create(instance, :methods, :method) do
-        |method_name|
-        ! baseinstance_table.has_key?(method_name)
-      end
+  ##
+  # Check that a Class object conforms to this protocol.
+  def class_conforms?(klass)
+    violations = self.violations_from_class(klass)
+    if violations
+      raise violations
+    end
+    true
+  end # Safer::Protocol#class_conforms?
+
+  ##
+  # Check that an instance object conforms to this protocol.
+  def instance_conforms?(instance)
+    violations = self.violations_from_instance(instance)
+    if violations
+      raise violations
+    end
+    true
+  end # Safer::Protocol#instance_conforms?
 
-      self.new(instance.class.to_s, class_signature, instance_signature)
-    end # Safer::Protocol.create_from_instance
+  ##
+  # Given a +Class+ object +klass+ and a +Class+ object +base+, create a
+  # +Protocol+ object representing the methods implemented in +klass+
+  # that are not present in +base+.
+  # [+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
+  #          +Protocol+.
+  def self.create_from_class(klass, base = Object)
+    class_signature = Signature.create(klass, :methods, :method) do
+      |method_name|
+      ! Class.respond_to?(method_name)
+    end
+    baseinstance_table = self._array_to_table(base.instance_methods)
+    instance_signature = Signature.create(klass, :instance_methods, :instance_method) do
+      |method_name|
+      ! baseinstance_table.has_key?(method_name)
+    end
+
+    self.new(klass.to_s, class_signature, instance_signature)
+  end # Safer::Protocol.create_from_class
 
-  end # Safer::Protocol
-end # Safer
+  ##
+  # Given an instance object +instance+ and a +Class+ object +baseclass+,
+  # 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
+      |method_name|
+      ! Class.method_defined?(method_name)
+    end
+    baseinstance_table = self._array_to_table(base.instance_methods)
+    instance_signature = Signature.create(instance, :methods, :method) do
+      |method_name|
+      ! baseinstance_table.has_key?(method_name)
+    end
+
+    self.new(instance.class.to_s, class_signature, instance_signature)
+  end # Safer::Protocol.create_from_instance
+
+end # Safer::Protocol