= Reap

User Friendly Project Assitant for Ruby


== What's This Then?

Reap is a user friendly project assistant for Ruby developers.
By organizing your project in a conventional manner, 
as promoted by setup.rb, Reap makes it easy to do the
following tasks:

* Generate RDocs.
* Run unit tests.
* Extract tests for scripts.
* Create Ruby Gem packages.
* Create standard .tgz, tbz (bzip2) and/or .zip packages.
* Publish documents to Rubyforge or other web sites.
* Announce a release to Ruby-talk or other mailing list.
* Prepare files for distribution (i.e. chmod, tag, etc.).
* Upload packages (coming soon!).

If you have special needs that Reap doesn't accomodate,
new task are farily easy to create. And I am always
happy to hear suggestions.


== Installation

=== Gem Install

Install the ruby gem as you would any other:

  <tt>gem install reap</tt>

Reap requires Ruby Facets.

=== Manual Install

To install manually follow the usual setup.eb steps:

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

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 grabs common data from a ProjectInfo
(or Reapfile) as available. Some Reap tasks are
automatic b/c there are reasonable defaults, others
_require_ entries in the ProjectInfo file.

For instance, to create a "package" target you generally do not need
an entry in the ProjectInfo file. Reap will package up everything
in the typical directories and makes compressed versions in the
common formats. It will then place those in either ../leaf/
(for those or you using trunk/ branches/ layouts) or pkg/ otherwise.
The same holds for other tasks. Reap will do it's best to extrapolate
the needed information from the ProjectInfo file.

Of course no matter the level of content, you will of course need to
create this file in you projects main directory. A template is provided
and a command line tool to copy it to your current directory. Simply type:

  > reap template

Then edit the ProjectInfo file. The fields are fairly self
explanitiory. Apart from Reap such a file is nice to have just on
it's own merits too.

=== Building a Reap Task

Building a Reap task I pretty easy, but is is quite differt
from building a Rake task.

Here's an, oh so simple, example:

  class OhSoSimple < Reap::Task

     task_desc 'This is a custom reap task'

     task_help %{

       reap ohsosimple

       This is help information for a custom reap task.

     }

     task_attr :ohso

     def init
       ohso.message ||= 'None Found!'
       ohso.another ||= 'Again!'
     end

     # run the target task
     def run
       puts ohso.message + "\n" + @another
     end

   end

The corresponding settings in the ProjectInfo file (master) will then be:

   default: Default text, if any.
   ohsosimple:
     another: Your other message here.

And to use it

  > reap ohsosimple

Reap used to use standard attributes for task properties.
But this has changed as of v4.3.3. Now it uses 'task', which
you can also reference by any name you like usng the #task_arr
class method. The nice thing about using this interface instead
of attributes is that reap will automatically search the
ProjectInfo's root if the property is not found in the task
specific section. This allows for a nice form of inheritance
within the document.

Sometimes you may need to override this behavor. In that case
just set the task property directly equal to the section property
in the init method. Eg.

     def init
       task.message = section.message
       ...
     end

Notice we used 'task' here rather than 'osho'. This task object
is always available. In the above, 'osho' is just being referenced
to 'task' via the #task_attr class method for readability convenience.
Both refer to the same underlying object.


== Status

Reap is currently Usable Beta. Most of the tasks
work very well. Refinements are still common though,
and a few important tasks are still being planned.


== Legal

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