handshake 0.1.0 → 0.2.0

data/Manifest.txt

@@ -1,10 +1,12 @@
 Manifest.txt
-README
+README.txt
 MIT-LICENSE
 Rakefile
 
 lib/handshake.rb
-lib/handshake/handshake.rb
+lib/handshake/block_contract.rb
+lib/handshake/clause_methods.rb
 lib/handshake/inheritable_attributes.rb
+lib/handshake/proxy_self.rb
 lib/handshake/version.rb
 test/tc_handshake.rb

data/README.txt

@@ -0,0 +1,110 @@
+= Handshake
+
+Handshake is an informal design-by-contract system written in pure Ruby.
+It's intended to allow Ruby developers to apply simple, clear constraints
+to their methods and classes.  Handshake is written by Brian Guthrie
+(btguthrie@gmail.com) and lives at http://handshake.rubyforge.org.
+
+=== Features
+
+* Method signature contracts
+* Contracts on blocks and procs
+* Method pre- and post-conditions
+* Class invariants
+* Define a class as abstract
+
+=== Examples
+
+Here's an example of Handshake in action:
+
+  # An array that can never be empty.
+  class NonEmptyArray < Array
+    include Handshake
+    invariant { not empty? }
+  end
+  
+  # An array to which only strings may be added.
+  class NonEmptyStringArray < NonEmptyArray
+    contract :initialize, [[ String ]] => anything
+    contract :<<, String => self
+    contract :+, many?(String) => self
+    contract :each, Block(String => anything) => self
+  end
+
+Handshake can also define pre- and post-conditions on your methods.
+
+  class Foo
+    before do
+      assert( not @widget.nil? )
+    end
+    def something_that_requires_widget
+      ...
+    end
+  end
+
+See Handshake::ClassMethods for more documentation on exact syntax and
+capabilities.  Handshake::ClauseMethods contains a number of helper and
+combinator clauses for defining contract signatures.
+
+=== Caveats
+
+Handshake works by wrapping any class that includes it with a proxy object
+that performs the relevant contract checks.  It acts as a barrier between
+an object and its callers.  Unfortunately, this means that internal calls,
+for example to private methods, that do not pass across this barrier, are
+unchecked.  Here's an example:
+
+  class UncheckedCall
+    include Handshake
+
+    contract String => Numeric
+    def checked_public(str); str.to_i; end
+
+    def checked_public_delegates(str)
+      checked_private(str)
+    end
+
+    private
+    contract String => Numeric
+    def checked_private(str); str.to_i; end
+  end
+
+In this example, we have a public checked method protected by a contract.  Any
+external call to this method will be checked.  The method marked as
+checked_public_delegates calls a private method that is itself protected by a
+contract.  But because the call to that private method is internal, and does not
+pass across the contract barrier, no contract will be applied.
+
+You can get around this problem by calling private methods on the special
+private method +checked_self+:
+
+  class UncheckedCall
+    ...
+    def checked_public_delegates(str)
+      checked_self.checked_private(str)
+    end
+    ...
+  end
+
+=== License (MIT)
+
+Copyright (c) 2007 Brian Guthrie
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -8,6 +8,7 @@ require 'rake/rdoctask'
 require 'rake/contrib/rubyforgepublisher'
 require 'fileutils'
 require 'hoe'
+
 include FileUtils
 require File.join(File.dirname(__FILE__), 'lib', 'handshake', 'version')
 
@@ -23,7 +24,7 @@ NAME      = "handshake"
 REV       = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
 VERS      = ENV['VERSION'] || (Handshake::VERSION::STRING + (REV ? ".#{REV}" : ""))
 CLEAN.include ['**/.*.sw?', '*.gem', '.config']
-RDOC_OPTS = ['--quiet', '--title', "handshake documentation",
+RDOC_OPTS = ['--quiet', '--title', "Handshake documentation",
              "--opname", "index.html",
              "--line-numbers", 
              "--main", "README",

data/lib/handshake/block_contract.rb

@@ -0,0 +1,53 @@
+class Proc
+  attr_reader :contract
+
+  # Define a contract on this Proc.  When the contract is set, redefine this
+  # proc's call method to ensure that values that pass through the proc are
+  # checked according to the contract.
+  def contract=(proc_contract)
+    @contract = proc_contract
+  end
+
+  def checked?
+    not @contract.nil?
+  end
+
+  def checked_call(*args)
+    Handshake.catch_contract("Contract violated in call to proc #{self}") do
+      @contract.check_accepts! *args
+    end if checked?
+    
+    return_value = orig_call(*args)
+    
+    Handshake.catch_contract("Contract violated by proc #{self}") do
+      @contract.check_returns! return_value
+    end if checked?
+    
+    return_value
+  end
+  alias :orig_call :call
+  alias :call :checked_call
+
+end
+
+module Handshake
+  # For block-checking, we need a class which is_a? Proc for instance checking
+  # purposes but isn't the same so as not to prevent the user from passing in
+  # explicitly defined procs as arguments.
+  # Retained for backwards compatibility; all blocks should be block contracts.
+  class Block
+    def Block.===(o); Proc === o; end
+  end
+  
+  module ClauseMethods
+    
+    # Block signature definition.  Returns a ProcContract with the given
+    # attributes
+    def Block(contract_hash)
+      pc = Handshake::ProcContract.new
+      pc.signature = contract_hash
+      pc
+    end
+    
+  end
+end

data/lib/handshake/clause_methods.rb

@@ -0,0 +1,170 @@
+module Handshake
+  # Transforms the given block into a contract clause.  Clause fails if
+  # the given block returns false or nil, passes otherwise.  See
+  # Handshake::ClauseMethods for more examples of its use.  This object may
+  # be instantiated directly but calling Handshake::ClauseMethods#clause is
+  # generally preferable.
+  class Clause
+    # Defines a new Clause object with a block and a message.
+    # The block should return a boolean value.  The message is optional but
+    # strongly recommended for human-readable contract violation errors.
+    def initialize(mesg=nil, &block) # :yields: argument
+      @mesg, @block = mesg, block
+    end
+    # Returns true if the block passed to the constructor returns true when
+    # called with the given argument.
+    def ===(o)
+      @block.call(o)
+    end
+    # Returns the message defined for this Clause, or "undocumented clause"
+    # if none is defined.
+    def inspect; @mesg || "undocumented clause"; end
+    def ==(other)
+      other.class == self.class && other.mesg == @mesg && other.block == @block
+    end
+  end
+  
+  # A collection of methods for defining constraints on method arguments.
+  # Use them inline with method signatures:
+  #   contract any?(String, nil) => all?(Fixnum, nonzero?)
+  module ClauseMethods
+    ANYTHING = Clause.new("anything") { true }
+
+    # Passes if the given block returns true when passed the argument.
+    def clause(mesg=nil, &block) # :yields: argument
+      Clause.new(mesg, &block)
+    end
+    
+    # Passes if the subclause does not pass on the argument.
+    def not?(clause)
+      clause("not #{clause.inspect}") { |o| not ( clause === o ) }
+    end
+    
+    # Always passes.
+    def anything; ANYTHING; end
+    
+    # Distinct from nil, and only for accepts: passes if zero arguments.
+    # Since Ruby will throw an arity exception anyway, this is essentially
+    # aesthetics.
+    def nothing; []; end
+
+    # Passes if argument is true or false.
+    #   contract self => boolean?
+    #   def ==(other)
+    #     ...
+    #   end
+    def boolean?
+      any?(TrueClass, FalseClass)
+    end
+
+    # Passes if any of the subclauses pass on the argument.
+    #   contract any?(String, Symbol) => anything
+    def any?(*clauses)
+      clause("any of #{clauses.inspect}") { |o| clauses.any? {|c| c === o} }
+    end
+    alias :or? :any?
+    
+    # Passes only if all of the subclauses pass on the argument.
+    #   contract all?(Integer, nonzero?)
+    def all?(*clauses)
+      clause("all of #{clauses.inspect}") { |o| clauses.all? {|c| c === o} }
+    end
+    alias :and? :all?
+    
+    # Passes if argument is numeric and nonzero.
+    def nonzero?
+      all? Numeric, clause("nonzero") {|o| o != 0}
+    end
+
+    # Passes if argument is Enumerable and the subclause passes on all of 
+    # its objects.
+    #
+    #   class StringArray < Array
+    #     include Handshake
+    #     contract :+, many?(String) => self
+    #   end
+    def many?(clause)
+      many_with_map?(clause) { |o| o }
+    end
+    
+    # Passes if argument is Enumerable and the subclause passes on all of
+    # its objects, mapped over the given block.
+    #   contract many_with_map?(nonzero?, "person age") { |person| person.age } => anything
+    def many_with_map?(clause, mesg=nil, &block) # :yields: argument
+      map_mesg = ( mesg.nil? ? "" : " after map #{mesg}" )
+      many_with_map = clause("many of #{clause.inspect}#{map_mesg}") do |o|
+        o.map(&block).all? { |p| clause === p }
+      end
+      all? Enumerable, many_with_map
+    end
+    
+    # Passes if argument is a Hash and if the key and value clauses pass all
+    # of its keys and values, respectively.
+    # E.g. <tt>hash_of?(Symbol, String)</tt>:
+    #   
+    #   :foo => "bar", :baz => "qux" # passes
+    #   :foo => "bar", "baz" => 3    # fails
+    def hash_of?(key_clause, value_clause)
+      all_keys   = many_with_map?(key_clause, "all keys")     { |kv| kv[0] }
+      all_values = many_with_map?(value_clause, "all values") { |kv| kv[1] }
+      all? Hash, all_keys, all_values
+    end
+
+    # Passes only if argument is a hash and does not contain any keys except
+    # those given.
+    # E.g. <tt>hash_with_keys(:foo, :bar, :baz)</tt>:
+    # 
+    #   :foo => 3                                     # passes
+    #   :foo => 10, :bar => "foo"                     # passes
+    #   :foo => "eight", :chunky_bacon => "delicious" # fails
+    def hash_with_keys(*keys)
+      key_assertion = clause("contains keys #{keys.inspect}") do |o|
+        ( o.keys - keys ).empty?
+      end
+      all? Hash, key_assertion
+    end
+    alias :hash_with_options :hash_with_keys
+
+    # Passes if:
+    # * argument is a hash, and
+    # * argument contains only the keys explicitly specified in the given
+    #   hash, and
+    # * every value contract in the given hash passes every applicable value
+    #   in the argument hash
+    # E.g. <tt>hash_contract(:foo => String, :bar => Integer)</tt>
+    #
+    #   :foo => "foo"               # passes
+    #   :bar => 3                   # passes
+    #   :foo => "bar", :bar => 42   # passes
+    #   :foo => 88, :bar => "none"  # fails
+    def hash_contract(hash)
+      value_assertions = hash.keys.map do |k|
+        clause("key #{k} requires #{hash[k].inspect}") do |o|
+          o.has_key?(k) ? hash[k] === o[k] : true
+        end
+      end
+      all? hash_with_keys(*hash.keys), *value_assertions
+    end
+
+    # Passes if argument responds to all of the given methods.
+    def responds_to?(*methods)
+      respond_assertions = methods.map do |m| 
+        clause("responds to #{m}") { |o| o.respond_to? m }
+      end
+      all? *respond_assertions
+    end
+    
+    # Allows you to check whether the argument is_a? of the given symbol.
+    # For example, is?(:String).  Useful for situations where you want
+    # to check for a class type that hasn't been defined yet when Ruby
+    # evaluates the contract but will have been by the time the code runs.
+    # Note that <tt>String => anything</tt> is equivalent to
+    # <tt>is?(:String) => anything</tt>.
+    def is?(class_symbol)
+      clause(class_symbol.to_s) { |o|
+        Object.const_defined?(class_symbol) && o.is_a?(Object.const_get(class_symbol))
+      }
+    end
+
+  end
+end

data/lib/handshake/proxy_self.rb

@@ -0,0 +1,19 @@
+# Redefines each of the given methods as a call to self#send.  This assumes
+# that self#send knows what do with them.  In this case is to make sure each
+# method call is checked by contracts.
+class Class # :nodoc:
+  def proxy_self(*meths)
+    meths.each do |meth|
+      class_eval <<-EOS
+        def #{meth}(*args, &block)
+          self.send(:#{meth}, *args, &block)
+        end
+      EOS
+    end
+    nil
+  end
+
+  # def ===(other)
+  #   other.is_a? self
+  # end
+end

data/lib/handshake/version.rb

@@ -1,7 +1,7 @@
 module Handshake # :nodoc:
   module VERSION # :nodoc:
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     TINY  = 0
     STRING = [MAJOR, MINOR, TINY].join('.')
   end