Virtuous Code

Number two out of three in my weekend releasing spree, I’m happy to announce the availability of FailFast v.1.0.0.

Description

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

Installing

sudo gem install fail-fast

Synopsis

  def try
    yield
  rescue FailFast::AssertionFailureError
    "<Assertion Failure>"
  end
 
  include FailFast::Assertions
 
  try { assert(true) }            # => true
  try { assert(false) }           # => "<Assertion Failure>"
  try { assert(nil) }             # => "<Assertion Failure>"
 
  # We can check multiple values at once
  try { assert("foo", :bar, 42) } # => 42
  try { assert(1, 2, nil) }       # => "<Assertion Failure>"
 
  # assert_exists only checks for nil-ness - false is OK.
  try { assert_exists(true) }     # => true
  try { assert_exists(false) }    # => false
  try { assert_exists(nil) }      # => "<Assertion Failure>"
 
  # check further constraints after verifying the object is non-nil
  try { assert_exists(99) {|n| n > 100 } } # => "<Assertion Failure>"
 
  # 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([]) }           # => "<Assertion Failure>"
 
  # #deny is the opposite of #assert
  try {  deny(true) }             # => "<Assertion Failure>"
  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) }       # => "<Assertion Failure>"
  try { assert_keys(h, :buz) }       # => "<Assertion Failure>"

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.

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.

Documentation

See the RDoc.

See the project site for more.

Viewing 2 Comments

nicholas a. evans 1 month ago 1 point
Please login to rate.

Do you already have an account? Log in and claim this comment.

I assume AlterEgo 1.0.1 will be refactored to use this, eh? :-)

reply edit flag

http://ekenosen.net/nick

avdi 1 month ago 1 point
Please login to rate.

Do you already have an account? Log in and claim this comment.

It was already part of AlterEgo, it just needed to be pulled out into its own gem. Next release of AlterEgo will depend on FailFast as well as the forthcoming HookR library which I wrote over the weekend.

reply edit flag

1 /people/avdi/ /people/avdi/following/ http://avdi.org 1210547532 pub/3/186/981 avdi avdi avdi avdi

[ANN] fail-fast 1.0.0 Released