= {Tap (Task Application)}[http://tap.rubyforge.org]

A framework for creating configurable, distributable tasks and workflows.

== Description

Tap tasks are designed to be easy to test, subclass, use in scripts, and run 
from the command line.  Tap provides methods to generate and utilize config 
files, join tasks into workflows, as well as dump and reuse results.  Task 
libraries are readily shared as gems.  Check out the links for tutorials, 
development, and bug tracking.

* {Tutorial}[link:files/doc/Tutorial.html], {Class}[link:files/doc/Class%20Reference.html] and 
{Command}[link:files/doc/Command%20Reference.html] Reference
* Website[http://tap.rubyforge.org]
* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/9908-tap-task-application/overview]
* Github[http://github.com/bahuvrihi/tap/tree/master]

=== Additional Notes:

- Tap and Rake[http://rake.rubyforge.org/] are targeted at different problems, 
  but play well together. See Tap::Tasks::Rake to use rake tasks in tap.
- Tap is tested on MRI (the standard Ruby interpreter, versions 1.8.6 and 
  1.9.0) and JRuby[http://jruby.codehaus.org/].

=== Usage

A simple task illustrates the usage of tap:

  # Goodnight::manifest your basic goodnight moon task
  # Says goodnight with a configurable message.
  class Goodnight < Tap::Task

    config :message, 'goodnight'           # a goodnight message

    def process(name)
      log(message, name)
      "#{message} #{name}"
    end
  end

Tap pulls documentation out of task classes to generate manifests:

  % tap run -T
    sample:
      goodnight   # your basic goodnight moon task
    tap:
      dump        # the default dump task
      rake        # run rake tasks  

And help:

  % tap run -- goodnight --help
  Goodnight -- your basic goodnight moon task
  --------------------------------------------------------------------------------
    Says goodnight with a configurable message.
  --------------------------------------------------------------------------------
  usage: tap run -- goodnight NAME

  configurations:
          --message MESSAGE            a goodnight message

  options:
      -h, --help                       Print this help
          --name NAME                  Specify a name
          --use FILE                   Loads inputs from file


Tasks are immediately available to run:

  % tap run -- goodnight moon
    I[00:09:55]          goodnight moon
  

  % tap run -- goodnight moon --message hello
    I[00:10:01]              hello moon
  
Tap comes with generators and allows distribution of task libraries as gems.  
This can be illustrated by installing the 
{sample_tasks}[http://tap.rubyforge.org/sample_tasks] gem:

  % gem install sample_tasks
  % tap run -T
  sample:
    goodnight   # your basic goodnight moon task
  sample_tasks:
    concat      # concatenate files with formatting
    copy        # copies files
    grep        # search for lines matching a pattern
    print_tree  # print a directory tree
  tap:
    dump        # the default dump task
    rake        # run rake tasks

=== Bugs/Known Issues

- Some inconsequential tests on JRuby fail due to bugs in JRuby itself.
- Several patches are required so that Tap runs properly on MRI 1.9.0.  These   
  will likely resolve themselves as 1.9.0 becomes stable.
- Despite the talk of workflows, the Workflow class should still be considered
  in progress.  Tasks themselves are stable.

== Installation

Tap is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:

  % gem install tap

Tap requires an updated version of RubyGems[http://docs.rubygems.org/] (>= 1.2.0).  To check the version and update 
RubyGems:

  % gem --version
  % gem --update system

== Info 

Copyright (c) 2006-2008, Regents of the University of Colorado.
Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], 
{Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
Licence:: {MIT-Style}[link:files/MIT-LICENSE.html]