= Quick Start Tutorial

=== Basic Usage

Begin by creating a tap directory structure:

  % tap generate root sample
  % cd sample
  
Comes with a task:

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

Test the task:
 
  % rake test 
  
Get help for the task:

  % tap run -- goodnight --help
  Goodnight -- your basic goodnight moon task
  --------------------------------------------------------------------------------
    Prints the input with a configurable message.
  --------------------------------------------------------------------------------
  usage: tap run -- goodnight INPUT

  configurations:
          --message MESSAGE

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

Run the task:

  % tap run -- goodnight moon
    I[23:22:19]          goodnight moon
    
Run the task, setting the 'message' configuration:
  
  % tap run -- goodnight moon --message hello
    I[23:22:46]              hello moon
  
Run multiple tasks, or in this case the same task twice:

  % tap run -- goodnight moon -- goodnight opus
    I[23:23:06]          goodnight moon
    I[23:23:06]          goodnight opus

Same as above, but now dump the results to a file:

  % tap run -- goodnight moon -- goodnight opus --+ dump output.yml
    I[23:23:26]          goodnight moon
    I[23:23:26]          goodnight opus
    I[23:23:26]               dump output.yml

The dump file contents look like this:

  # audit:
  # o-[] "opus"
  # o-[goodnight] "goodnight opus"
  # 
  # o-[] "moon"
  # o-[goodnight] "goodnight moon"
  # 
  # date: 2008-08-05 23:23:26
  --- 
  goodnight (2769410): 
  - goodnight opus
  goodnight (2780180): 
  - goodnight moon

The comments at the beginning are an audit trace of the run.  In this case two 
separate tasks were run sequentially, hence you can see each task, the task inputs, 
and the task results as separate units.  A YAML hash follows the audit with the 
aggregated task results, keyed by the task name and object id.  Since the results 
are represented as a hash, the order of the tasks sometimes gets scrambled, as in 
this case.

=== Task Declaration

Tap provides a declaration syntax a-la rake, accessible through the Tap module to 
prevent conflicts with rake.  Declarations can get put in any <tt>.rb</tt> file 
under the lib directory or in <tt>tapfile.rb</tt>.

  [tapfile.rb]
  # Goodnight::manifest your basic goodnight moon task
  # Prints the input with a configurable message.

  Tap.task('goodnight', :message => 'goodnight') do |task, name|
     task.log task.message, name
     "#{task.message} #{name}"
  end

The declaration makes a task class based on the name (ie namespaces are naturally
supported by names like <tt>'nested/task'</tt>).  The classes are ready for use in 
scripts:

  require 'tapfile'
  Goodnight.new.process('moon')       # => 'goodnight moon'

And from the command line, as above.

=== Task Definition

Sometimes you need more than a block to define a task.  Generate a task:

  % tap generate task hello

Navigate to and open the <tt>lib/hello.rb</tt> file.  Inside you can see the class 
definition.  Notice configurations are mapped to methods, and the task documentation 
is located in the comments.  Let's change it up a bit:

  [lib/hello.rb]
  # Hello::manifest your basic hello world task
  #
  # Prints hello to a number of things with a configurable, 
  # reversible message.
  #
  class Hello < Tap::Task

    config :message, 'hello'               # a greeting
    config :reverse, false, &c.flag        # reverses the message

    def process(*names)
      names.collect do |name|
        log(reverse ? message.reverse : message, name)
        "#{message} #{name}"
      end
    end
  end

The new configurations and documentation are immediately available:

  % tap run -- hello --help
  Hello -- your basic hello world task
  --------------------------------------------------------------------------------
    Prints hello to a number of things with a configurable, reversible message.
  --------------------------------------------------------------------------------
  usage: tap run -- hello NAMES...

  configurations:
          --message MESSAGE            a greeting
          --reverse                    reverses the message

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

And the task is ready to go:

  % tap run -- hello moon lamp 'little toy boat'
    I[23:29:26]              hello moon
    I[23:29:26]              hello lamp
    I[23:29:26]              hello little toy boat

  % tap run -- hello mittens --reverse
    I[23:29:53]              olleh mittens

Now lets use the previous results; they get loaded and added to the end of the inputs:

  % tap run -- hello --use output.yml
    I[23:31:32]              hello goodnight moon
    I[23:31:32]              hello goodnight opus
  
=== Config Files

So say you wanted static configs for a task.  Make a configuration file:

  % tap generate config goodnight
        
Set the configurations here and they get used by the task:

  [config/goodnight.yml]
  ###############################################################################
  # Goodnight configuration
  ###############################################################################

  message: good evening
  
As can be seen here:

  % tap run -- goodnight moon
    I[23:40:39]       good evening moon

If you need to run a task with multiple sets of configurations, simply define an 
array of configurations in the config file:
  
  [config/goodnight.yml]
  - message: good afternoon
  - message: good evening
  - message: goodnight

  % tap run -- goodnight moon
    I[23:42:46]     good afternoon moon
    I[23:42:46]       good evening moon
    I[23:42:46]          goodnight moon

The --name option sets the config file used:

  % tap run -- goodnight moon --name no_config_file
    I[23:43:20]          goodnight moon

=== Tap Configuration

Tap itself is highly configurable.  Say you think the run syntax is unnecessarily 
verbose; you can make command aliases to shorten it.  Open the <tt>tap.yml</tt> 
file in your root directory and set the following:

  [tap.yml]
  alias:
    --: [run, --]
    -T: [run, -T]

Now:

  % tap -- hello world
    I[23:43:59]              hello world

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

Global configurations can go in the <tt>~/.tap.yml</tt> file.  Using configurations,
you can specify directory aliases, options, gems, and even additional paths to load 
as if they were gems.