= Reap -- A Project Assistant for Ruby

Reap is an easy to use project assistant for Ruby developers.
Reap makes it easy to do the following tasks:

* Build new convention-based project folders.
* Generate RDoc API documentation.
* Run unit tests (each in it's ruby process).
* Extract comment embedded tests from source code.
* Run comment embedded unit test directly from source.
* Create source tar.gz, tar.bz2 and zip packages.
* Create RubyGem and Debian packages, plus pacman PKGBUILDs.
* Publish documents to Rubyforge or other web sites.
* Make announcement to ruby-talk or other mailing list.
* Prepare files for distribution (i.e. chmod, tag, etc.)
* Release distributions on Rubyforge or other such host.
* Generate XML-format DOAP project file.

New features continue to be be developed. If you have special
needs that Reap doesn't accomodate, new tasks are farily easy
to create. And Reap's maintainers are always happy to engage
suggestions.


== Installation

=== Requirements

Reap requires Ruby Facets. If manually installing be sure to
have the latest version of Facets installed too.

=== Gem Install

Install the ruby gem as you would any other:

    gem install reap

Gems still suffers from the datadir problem, so we've had
to create some work arounds, for the template and scaffold
tasks in particular. If you have any trouble with the Gem
install please let us know so we can correct.

=== Manual Install

To install manually follow the usual setup.rb steps:

1. Download the compressed package.
2. Unpack it.
3. Change into the unpacked directory.
4. run 'sudo ruby setup.rb'

You should be good to go.


== Usage

=== Using a Reap Task

Reap makes it pretty easy to use it's built-in tasks.
Largely this is because it utilizes a single data file,
called the ProjectInfo file, to describe project procedures.

To use Reap the first thing your project will need is a
ProjectInfo file in it's main directory. A template is provided
and a task to copy it to your current directory. Simply type:

    % reap template

Then edit the ProjectInfo file created. The fields are fairly self
explanitiory. The template has a number of commented-out exmaples.
Apart from utilization by Reap, such a file is even nice to have
just on it's own informative merits too.

Alternatively, Reap can build an entire new project directory with
all the conventional components pre-arranged. Try it by creating
a new empty directory, changing into it and then typing:

    % reap scaffold

The directory will be filled out with all the ususal directories,
lib/, bin/, etc.  If you use subversion for version management,
you can create a subversion layout instead.

    % reap scaffold svn

Filling out a ProjectInfo file is simply a matter adding entries
for the primary information of you project and adding sections for
the tasks you wish to use in for project. For example to use the
RDoc task you could add:

    document: !!rdoc
      dir: rdoc

By default Reap's Rdoc task will look in the bin/ lib/ and ext/
directories for ruby scripts to document. Or you can specify
exactly which files to include (See the Reap RDocs themselves
for parameter details.) Some tasks can operate automatically
based on reasonable defaults. Indeed in some cases all one might
need is the one line:

    name: !!task

In others cases certain parameters are required for the task to function.
But Reap will do it's best to extrapolate the needed information from
what's available in the ProjectInfo file.

Once you have some entries in your ProjectInfo file, enter:

    % reap

And you will see a list of executable tasks. To run a task enter:

    % reap [task]

For basic help try:

    % reap help

For a list of all avaialbe tasks or to get more detailed help on how to 
use a particular task have a look at the RDoc API documentation.


=== Building a Reap Task

Building a Reap task is pretty easy too. In fact if you ever used Rake
you already have a good idea about how to do it. 

First make sure your project has a task/ folder. Any file in that
folder will be read by Reap and used to setup tasks. In a file with
in that folder you can add a task or collection of tasks.
Here's an "oh-so-simple" example:

    module Tasks

      def simple( name, data )

        desc 'This is a custom reap task class.'

        task name do
          data.message ||= master.message
          puts data.message + "\n\n" + data.signed
        end

      end

    end

The corresponding settings in the ProjectInfo file will then be:

    message: Hi, how are you?

    simple: !!simple
      signed: Your friend, Tom.

And to use it type:

    % reap simple

Notice the reference to 'master'. This is an OpenCascade interface
(similar to OpenObject and OpenStruct) to the whole ProjectInfo dataset.

You might recognize the core methods of creating a task, 'desc' and 'task'.
These are used exactly as they are in Rake. We encapsulate them in a
task-definition method (eg. simple) so the task can be generated dyanmically
if such a section (!!simple) appears in the ProjectInfo file. Such 
task-definition methods are recognized by reap b/c they are stored in the 
special purpose Tasks module.


== Status

Reap is currently what one might call "usable beta". Most of the tasks
work very well. Refinements are still common though.

Also, Windows support is weak. Reap hasn't been fully tested in that
environment so it is likely a few tasks will not yet work in this case.
If you are Windows user and would like to use Reap, we would
really appreciate someone working out the issues here.


== Legal

  Reap
  Copyright (c) 2004-2006 Thomas Sawyer
  Ruby License