h2. Description

HookR is a publish/subscribe callback hook facility for Ruby.

h2. What is it?

HookR can be understood in a few different ways.

* If you are familiar with Events and Event Listeners in “Java”:http://java.sun.com/docs/books/tutorial/javabeans/events/index.html or “C#”:http://msdn.microsoft.com/en-us/library/aa645739(VS.71).aspx; “Hooks”:http://www.gnu.org/software/emacs/manual/html_node/elisp/Hooks.html#Hooks in Emacs-lisp; or signals-and-slots as implemented in the “Qt”:http://doc.trolltech.com/4.4/signalsandslots.html, “Boost.Signals”:http://www.boost.org/doc/libs/1_37_0/doc/html/signals.html, or “libsigc++”:http://libsigc.sourceforge.net/ frameworks – HookR provides a very similar facility.
* If you’ve ever used the Observer standard library, but wished you could have more than one type of notification per observable object, HookR is the library for you.
* HookR is an easy way to add “Rails-style”:http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html before- and after-filters to your own classes.
* HookR is an “Inversion-of-Control”:http://martinfowler.com/bliki/InversionOfControl.html framework in that it makes it easy to write event-driven code.
* HookR is a way to support a limited, structured form of Aspect Oriented Programming (“AOP”:http://en.wikipedia.org/wiki/Aspect-oriented_programming) where the advisable events are explicitly defined.

h2. What HookR is not:

* HookR is not (yet) an asynchronous event notification system. No provision is made for multi-threaded operation or event queueing.
* HookR will show you a good time, but it will not make you breakfast in the morning.

h2. Synopsis

  require 'rubygems'
  require 'hookr'

  class ZeroWing
    include HookR::Hooks
    define_hook :we_get_signal, :message

    def start_game
      execute_hook(:we_get_signal, "How are you gentlemen?")
    end

    def bomb(event, message)
      puts "somebody set us up the bomb!"
    end

    we_get_signal do |event, message|
      puts "Main screen turn on!"
      puts "Cats: #{message}"
    end

    we_get_signal :bomb

  end

  zw = ZeroWing.new
  zw.we_get_signal do
    puts "Take off every zig!"
  end

  zw.start_game
  # >> Main screen turn on!
  # >> Cats: How are you gentlemen?
  # >> somebody set us up the bomb!
  # >> Take off every zig!

h2. Get it Now

Pull your hat way down over your eyes, drive over to the your local red-light district, and type:

sudo gem install hookr

For more information, check out the website: http://hookr.rubyforge.org

h2. Description

FailFast is a collection of assertion methods intended for lightweight contract checking.

h2. Installing

sudo gem install fail-fast

h2. Synopsis

  def try
    yield
  rescue FailFast::AssertionFailureError
    ""
  end

  include FailFast::Assertions

  try { assert(true) }            # => true
  try { assert(false) }           # => ""
  try { assert(nil) }             # => ""

  # We can check multiple values at once
  try { assert("foo", :bar, 42) } # => 42
  try { assert(1, 2, nil) }       # => ""

  # assert_exists only checks for nil-ness - false is OK.
  try { assert_exists(true) }     # => true
  try { assert_exists(false) }    # => false
  try { assert_exists(nil) }      # => ""

  # check further constraints after verifying the object is non-nil
  try { assert_exists(99) {|n| n > 100 } } # => ""

  # Assert that a collection is non-empty
  try { assert_one_or_more([1]) }         # => [1]
  try { assert_one_or_more(:foo => :bar) } # => {:foo=>:bar}
  try { assert_one_or_more([]) }           # => ""

  # #deny is the opposite of #assert
  try {  deny(true) }             # => ""
  try { deny(false) }             # => false
  try { deny(nil) }               # => nil

  # Assert that an object is hash-like and contains non-nil values for given keys
  h = {:foo => 1, :bar => 2, :baz => nil}
  try { assert_keys(h, :foo, :bar) } # => {:foo=>1, :bar=>2, :baz=>nil}
  try { assert_keys(h, :baz) }       # => ""
  try { assert_keys(h, :buz) }       # => ""

h2. Rationale

Unexpected nils and other bad values will usually bring a Ruby program down eventually, but the actual point of failure might be deep down the call stack and the error message less than revealing. Judicious use of FailFast assertions to check your assumptions can ensures that the program will end as soon as a contract violation is detected, with a stack trace that points directly at the assertion which failed.

One of the primary goals of FailFast is to make assumption-checking declarative. Assumption checking should be simple and concise so that we can get to the meat of a method without getting bogged down in verifications. At the same time, FailFast is lightweight. It is not a metaprogrammed Design-by-Contract DSL. It is a simple set of shorthand methods for validating values.

It is not the intent of FailFast to have specialized assertions for every eventuality. Rather, it seeks to cover a few common cases where there is a potential for significantly increased clarity and declarativeness.

h2. Features

* Fully spec’d/tested.
* In most cases assertions return their last argument. This makes it easy to check values inline. For instance: assert_exists(obj).foo()
* Most assertions can take a block where a further boolean check can be performed. For instance, use assert_exists(x) { x.predicate? } to check first that x is not nil, and then that it satisfies a predicate.
* AssertionFailure derives directly from Exception so that it will never be silently eaten by no-argument catch statements.

h2. Documentation

See the RDoc.

See the “project site”:http://fail-fast.rubyforge.org for more.