README

Path: README
Last Update: Tue May 04 23:26:15 -0600 2010

Tap (Task Application)

  tap n. to draw a supply from a resource

A configurable, distributable workflow framework.

Description

Tap allows the construction of workflows that may be defined, configured, and run from the command line. The tasks and joins composing a workflow are easy to test, subclass, and distribute as gems.

Tap provides a standard library of tasks, generators, and test modules to expedite development.

Usage

Tasks are defined as subclasses of Tap::Task.

  [lib/goodnight.rb]
  require 'tap/task'

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

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

Tap discovers tasks.

  % tap list
  task:
    dump                 # dump data
    goodnight            # your basic goodnight moon task
    list                 # list resources
    load                 # load data
    prompt               # open a prompt
    signal               # signal via a task
  join:
    gate                 # collects results
    join                 # unsyncrhonized multi-way join
    sync                 # synchronized multi-way join
  middleware:
    debugger             # default debugger

Generates command-line documentation.

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

  configurations:
          --message MESSAGE            a goodnight message

  options:
          --help                       Print this help
          --config FILE                Specifies a config file

And provides a robust syntax for building both simple and complex workflows. This joins a goodnight task to a dump task in order to print the goodnight message.

  % tap goodnight moon -: dump
  goodnight moon

  % tap goodnight world --message hello -: dump
  hello world

Workflows support the use of middleware to wrap the execution of each task, most commonly for logging and/or debugging.

  % tap goodnight moon -: dump --/use debugger
    21:06:53       0 << ["moon"] (Goodnight)
    21:06:53       0 >> "goodnight moon" (Goodnight)
    21:06:53       1 << "goodnight moon" (Tap::Tasks::Dump)
  goodnight moon
    21:06:53       1 >> "goodnight moon" (Tap::Tasks::Dump)

Tap provides a set of test modules to simplify testing of workflows both off and on the command-line (this documentation is tested, for example):

  require 'tap/test/unit'

  class ShellTestTest < Test::Unit::TestCase
    acts_as_shell_test

    def test_goodnight_moon
      sh_test %q{
      % tap load 'goodnight moon' -: dump
      goodnight moon
      }
    end
  end

Tasks can be packaged into gems like any other code. Tap automatically finds tasks in gems containing a tap.yml file so that distribution feels normal and unobtrusive.

  % tap load/yaml
  unresolvable constant: "load/yaml"

  % gem install tap-tasks
  ...

  % tap load/yaml "[1, 2, 3]" -: dump/yaml
  ---
  - 1
  - 2
  - 3

For local tasks that don‘t need to be distributed, Tap provides declarations a-la Rake. By default any tasks in a tapfile are available for use.

  [tapfile]
  desc "concat file contents"
  task :cat do |config, *files|
    files.collect {|file| File.read(file) }.join
  end

  desc "grep lines"
  task :grep, :e => '.' do |config, str|
    str.split("\n").grep(/#{config.e}/)
  end

  % tap cat tapfile -:a grep -e task -:i dump
  task :cat do |config, *files|
  task :grep, :e => '.' do |config, str|

See the documentation for a greater explanation of the workflow syntax, several common patterns, and the underlying APIs.

Installation

Tap is available as a gem on Gemcutter.

  % gem install tap

Info

Developer:Simon Chiang
License:MIT-Style

[Validate]