bahuvrihi / tap

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

  tap n. to draw a supply from a resource

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 join tasks into imperative 
and dependecy-based workflows, utilize static config files, as well as dump 
and reuse results.  Task libraries are readily shared as gems.  

Check out these links for tutorials, development, and bug tracking.

* {Tutorial}[link:files/doc/Tutorial.html], {Class}[link:files/doc/Class%20Reference.html], 
{Command}[link:files/doc/Command%20Reference.html], and {Syntax}[link:files/doc/Syntax%20Reference.html] References
* Website[http://tap.rubyforge.org]
* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/9908-tap-task-application/tickets]
* Github[http://github.com/bahuvrihi/tap/tree/master]
* {Google Group}[http://groups.google.com/group/ruby-on-tap]

=== Features

- Tap and Rake[http://rake.rubyforge.org/] are targeted at different problems, 
  but play well together. See the {Tutorial}[link:files/doc/Tutorial.html].
- Tap is tested on MRI (the standard Ruby interpreter, versions 1.8.6 and 
  1.9.0) and JRuby[http://jruby.codehaus.org/].
- Tap is the core of the {Tap-Suite}[http://tap.rubyforge.org/tap-suite], a
  collection of several modules that simplify development.
  
=== Usage

A simple task illustrates the usage of tap:

  [lib/goodnight.rb]
  
  # 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:
      core_dump   # dumps the application
      dump        # the default dump task
      load        # the default load task
      
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:
          --help                       Print this help
          --name NAME                  Specifies the task name
          --config FILE                Specifies a config file
          --use FILE                   Loads inputs to ARGV

Tasks are immediately available to run through the tap executable:

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

Tap comes with generators. To get started:

  % tap generate root sample
  % cd sample
  % tap generate task goodnight
  % tap run -- goodnight moon

=== Bugs/Known Issues

- Some inconsequential tests on JRuby fail due to bugs in JRuby itself.
- Joins, Parser, and Schema require additional documentation and may be
  reworked in a future release.  The workflow syntax should remain the same.
- Audit.dump only works for certain cases.  Merges frequently cause trouble.

== 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-2009, 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
License:: {MIT-Style}[link:files/MIT-LICENSE.html]