bahuvrihi / tap

= {Rap (Rakish App)}[http://tap.rubyforge.org/rap]

  rap v. a quick, sharp knock or blow
  rak.ish adj. having a dashing, jaunty, or slightly disreputable quality or appearance

A rakish extension to {Tap}[http://tap.rubyforge.org/rdoc].

== Description

Rap supercharges the syntax of Rake by adding configurations, extended
documentation, and class-based tasks that are easy to test.

Rap is a part of the {Tap-Suite}[http://tap.rubyforge.org/tap-suite].
Check out these links for documentation, development, and bug tracking.

* 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]

== Usage

Usage is much like {Rake}[http://rake.rubyforge.org/]:

  [Rapfile]
  
  # ::desc your basic goodnight moon task
  # Says goodnight with a configurable message.
  Rap.task(:goodnight, :obj, :message => 'goodnight') do |task, args|
    puts "#{task.message} #{args.obj}\n"
  end
  
Now from the command line:

  % rap goodnight moon
  goodnight moon
  
  % rap goodnight world --message hello
  hello world
  
  % rap goodnight --help
  Goodnight -- your basic goodnight moon task
  --------------------------------------------------------------------------------
    Says goodnight with a configurable message.
  --------------------------------------------------------------------------------
  usage: rap goodnight OBJ

  configurations:
          --message MESSAGE

  options:
          --help                       Print this help
          --name NAME                  Specifies the task name
          --config FILE                Specifies a config file

For testing, load the Rapfile and access the task as a constant.

  [test.rb]
  require 'rap'
  load 'Rapfile'
  require 'test/unit'
  require 'stringio'
  
  class RapfileTest < Test::Unit::TestCase
    def test_the_goodnight_task
      $stdout = StringIO.new
      
      task = Goodnight.new
      assert_equal 'goodnight', task.message
      
      task.process('moon')
      assert_equal "goodnight moon", $stdout.string
    end
  end

The test passes:

  % ruby test.rb
  Loaded suite test
  Started
  .
  Finished in 0.004921 seconds.

  1 tests, 2 assertions, 0 failures, 0 errors

Generally speaking, the rap executable is a shorthand for 'tap run --' so you
can use rap to launch workflows as well.

== Limitations

Rap is not a pure replacement of Rake, nor do the Rap tasks behave exactly
like standard Tap tasks.

==== Regarding Rake:

* Rap does not support builds by default
* Classes like FileList are not available
* Namespace lookup is slightly different (see the {Syntax Reference}[link:files/doc/Syntax%20Reference.html])

That said, many rakefiles can be renamed as rapfiles and they'll work with
minor and sometimes no changes.

==== Regarding Tap

Rap tasks (ie subclasses of Rap::DeclarationTask) are designed to behave like
Rake tasks. As such Rap tasks:

* return nil and pass nil in workflows 
* only execute once
* are effectively singletons

This makes rap tasks useful in dependency-based workflows but fairly useless
in imperative workflows. However, other tasks behave as normal and any
workflow you can run with 'tap run' can be run without alteration by rap.

== Installation

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

  % gem install rap

Rap 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) 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]