= Ruby Quarry

  http://quarry.rubyforge.org


== Introduction

Ruby Quarry is a developers testing and debugging suite.
It features a literal-programming BDD specification system,
and exception based assertion system, and a few other of
useful QA tools.


== Features

=== Specifications

Quarry's BBD system is uniqe in a few ways. First it utilizes
Ruby's Execption system to catch Assertions which are defined
via assertion <i>functors</i>. Eg.

    require 'quarry/assertion'

    4.assert == 5

Because 4 != 5, this expression will raise an Assertion exception.
Quarry's Specification Runner class is thus just a means of
running and capturing these assertions.

Quarry's Specifications themselves are simple text files, a practice
of literal programming. 

    Example Specification
    =====================
    Shows that the number 5 does not equal 4.

        5.assert! == 4

    But in fact equals 5.

        5.assert == 5

    QED.

If we run this specification in verbatim mode the output would identical
(assuming we did not make a type and the assertions passed).
If there were errors or assertion failures, we would see information
detaling each.

As you can see I used Markdown for my spcecification. You can use almost any
format you like. The only neccesary distiction is that desciption text be
align to the left margin and all specification code be indented. Quarry also
recognized headers, currently Markdown and RDoc style headers (We'll add
Textile soon.)

We'll leave discussion of the merits of this system to another place. But
it should be clear that this approach if especcailly conveniant, allowing
documentation and specification to seemlessly merge.


=== Stubs

Quarry provides a flexible stubbing facility.

For now see RDoc API.


=== MethodProbe

MethodProbe (aka the Duck Hunter) can dip-down into a method and
provide a read-out how it functions --known as a <i>method signiture</i>.
MethodProbe is somewhat expiremental becuase it is runtime bound, so proper
execution can not be 100% guarenteed.  It can miss some parts of a method
due to conditional branching (a probe can;t pretend to be false) and,
albiet rare, it can also get stuck in an infinite loop a la the
Halting Problem. Even so, it can be used effectively under controlled
situations if used with care.


=== More to come ....


== Copying

Copyright (c) 2007, 2008 Tiger Ops / Thomas Sawyer

Quarry is distributed under the terms of the GPLv3.