[ANN] Handshake, an informal contract system for Ruby

Discussion in 'Ruby' started by Brian Guthrie, May 8, 2007.

  1. Handshake is an informal contract system for Ruby. It allows
    developers to apply clear, concise, and enforceable interfaces to
    classes, in three forms:

    - method signatures
    - class invariants
    - pre- and post-conditions

    Note that Handshake will only enforce checked contracts if the $DEBUG
    flag is set to true (ruby -d).

    Method signature contracts are applied in the following way:

    class Foo
    include Handshake

    contract [ all, acceptable, arguments ] => return_value
    def method(arg, ...) ...

    Signature contracts accept clauses, which are defined as any object
    that implements the === method. When specified with a symbol, they
    will be applied the named method; when specified without one, they
    will be applied to the next defined method. Handshake comes with a
    number of useful clauses predefined:

    contract :foo, any?(String, 0..5) => Symbol
    contract :sum, many?(Integer) => Integer
    contract :deposit, positive_n? => Integer

    It can also apply contracts to varargs and anonymous blocks:

    contract [ String, [ Integer ] ] => anything
    def foo(str, *ints) ...

    contract :each, Block(String => anything) => many?(String)

    In addition, users can define their own custom project-specific
    clauses very easily. See the RDoc for Handshake::ClauseMethods for
    more information.

    Class invariants accept a message and a block, which is expected to
    return a boolean value. Their value is checked before and after each
    method invocation and are scoped to allow checking of instance
    variables and private methods.

    class NonEmptyArray < Array
    include Handshake
    invariant("should never be empty") { not empty? }

    Pre- and post-conditions allow for grouping common sets of assertions,
    typically those that require checking arguments against one another.
    All Test::Unit assertions are available, although they raise a
    Handshake::ContractViolation exception here upon failure.

    before do |first_half, second_half|
    assert_equal 10, first_half.length + second_half.length
    def accepts_ten_items(first_half, second_half) ...

    Handshake is implemented by aliasing the new method of any class that
    includes it. The modified new method returns a proxy object in place
    of the original object that looks, acts, and feels like the real
    thing. It acts as a barrier, and all method invocations that cross
    the barrier are checked against the defined contracts. It differs in
    this manner from other Ruby DBC-style systems, which generally alias
    each contract-checked method as necessary. Because of both this and
    its grave irrelevance to a Rails context, I wouldn't recommend trying
    to use Handshake with any Rails projects.

    Handshake is written in pure Ruby, is available as open source under
    the same license as Ruby, and is installable as a gem (latest
    version=0.3.0). It lives at http://rubyforge.org/projects/handshake,
    and the RDoc is available at http://handshake.rubyforge.org.

    I'd love to hear any comments, criticisms, and suggestions. I'm also
    presenting Handshake tonight at the Boston Rubygroup and figured,
    well, I should probably announce the silly thing on ruby-talk first.

    Brian Guthrie

    Brian Guthrie, May 8, 2007
    1. Advertisements

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Tom Hawkins

    [ANN] InFormal 0.1.1 Released

    Tom Hawkins, Nov 9, 2004, in forum: VHDL
    Tom Hawkins
    Nov 9, 2004
  2. Replies:
    Stefan Ram
    Sep 14, 2005
  3. Alan Mackenzie
    Alan Mackenzie
    Apr 24, 2005
  4. Alan Mackenzie

    Emacs CC Mode's auto-newline facility: INFORMAL SURVEY

    Alan Mackenzie, Apr 8, 2005, in forum: C Programming
    those who know me have no need of my name
    Apr 28, 2005
  5. blangela
    Ian Collins
    Nov 25, 2006