= Ruby Q.E.D.

      homepage: http://proutils.rubyforge.org/qed
  mailing list: http://groups.google.com/group/proutils
   development: http://github.com/proutils/qed


== Introduction

Q.E.D. is an abbreviation for the well known Latin phrase "Quod Erat Demonstrandum",
literally "which was to be demonstrated", which is oft written in its abbreviated
form at the end of a mathematical proof or philosophical argument to signify the
a successful conclusion. And so it is too for Ruby Q.E.D., though it might as easily
be taken to stand for "Quality Ensured Documentation". 

QED is in fact both a test framework and a documentation system for Ruby
developers. QED sits somewhere between lower-level testing tools like Test::Unit
and grand requirement specifications tools like Cucumber. In practice it works
exceptionally well for <i>API-Driven Design</i>, which is especially useful when
designing reusable libraries, but it can be used to test code at any level
of abstract, from unit test to systems tests.


== Features

* Write tests and documentation in the same breath!
* Demos can be RDoc, Markdown or any other conforming text format.
* Uses the excellent Assertive Expressive library for assertions.
* Table macro allows large sets of data to be run by the same code.
* Documentation tool provides nice output with jQuery-based TOC.


== Synopsis

=== Assertion Syntax

QED uses the AE (Assertive Expressive) library to provide an elegant means to
make assertions. To give a quick overview, assertion can be written as:

    4.assert == 5

In this example, because 4 != 5, this expression will raise an Assertion
exception. QED's Runner class is thus just a means of running and capturing
code blocks containing these assertions.

You can learn more about AE at http://proutils.github.com/ae.

=== Document Structure

QED documents are simply text files called *demonstrandum*. Because they 
largely consist of free-form descriptive text, they are a practice pure 
Literate Programming. For example:

    = Example

    Shows that the number 5 does not equal 4.

        5.assert! == 4

    But in fact equals 5.

        5.assert == 5

In this example RDoc was chosen for the document format. However, almost any
text format can be used. The only necessary distinction is that description text
align to the left margin and all code be indented, although QED does recognize
RDoc and Markdown single-line style headers, so any format that supports
those (which covers many markup formats in use today) will have mildly
improved console output. In any case, the essential take away here is that
QED *demonstrandum* are simply descriptive documents with interspersed 
blocks of example code.

Give this design some thought. It should become clear that this approach is
especially fruitful in that it allows *documentation* and *specification*
to seamlessly merge into a unified *demonstration*. 

=== Running Demonstrations

If we were to run the above document through QED in verbatim mode the output
would be identical (assuming we did not make a typo and the assertions passed).
If there were errors or failures, we would see information detailing each.

To run a document through QED, simply use the +qed+ command.

  $ qed -v demo/01_example.rdoc

The <code>-v</code> option specifies verbatim mode, which outputs the entire
document.

Notice we placed the QED document in the <code>demo/</code> or <code>demos/</code>
directory, this is the conical place that has been designated for them, though you
can of course put them elsewhere in your project if you prefer. Also notice the
<code>01_</code> prefix in front of the name. While this is not strictly necessary,
it helps order the documents properly when generating QED documentation (QEDocs).

=== Utilizeing Applique

QED demonstrandum descriptive text is not stricty passive explination. Using
pattern matching techniques, document phrases can trigger underlying actions.
These actions provide a support structure for running tests called the *applique*.

Creating an applique is easy. Along with your QED scripts, to which the 
applique will apply, create an <code>applique/</code> directory. In this
directory add Ruby scripts. When you run your demos every Ruby script in 
the directory will be automatically loaded.

Within these applique scripts *advice* can be defined. Advice can be
either *event advice*, which is simply triggered by some fixed cycle
of running, such as <code>Before :document</code> or <code>After :all</code>,
and *pattern advice* which are used to match against descriptive
phrases in the QED demos. An example would be:

  When "a new round is started" do
    @round = []
  end

So that whenever the phrase "a new round is started" appears in a demo,
the @round instance variable with be reset to an empty array.

It is rather amazing what can be accomplished with such a system,
be sure to look at QED's own demonstandum to get a better notion of
how you can put the the system to use.

=== Generating Documentation

To generate documentation from QED documents, use the +qedoc+ command.

  $ qedoc --output doc/qedoc --title "Example" demo/*.rdoc

When documenting, QED recognizes the format by the file extension and 
treats it accordingly. An extension of <code>.qed</code> is treated the same
as <code>.rdoc</code>.

Use the <code>--help</code> options on each command to get more information
on the use of these commands.




== Requirements

QED depends on the following external libraries:

  * AE     - Assertions Framework
  * ANSI   - ANSI Color Codes
  * Facets - Core Extensions

These will be automatically installed when installing QED via RubyGems,
if they are not already installed.


== Copyright and License

Q.E.D.

Copyright (c) 2007,2009 Thomas Sawyer

Unless otherwise permitted by the author, QED is distributed under the
terms of the GPL version 3 or greater. See COPYING file for details.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA