tap 0.9.1 → 0.10.0

data/Command Reference

@@ -1,99 +0,0 @@
-= Tap from the Command Line
-
-The tap command is the gateway for the execution of sub-commands.  To get help for tap, type:
-
-  % tap --help
-  
-The tap command sets up the execution environment from 'tap.yml', if it exists, and passes control to the specified sub-command.  Sub-command help can be obtained using:
-
-  % tap [sub-command] --help
-
-== run
-
-Run configures, enqueues, and executes tasks.  Run has a rich syntax allowing the specification of any number of tasks with configurations and inputs, but simplifies under most circumstances.  Several examples illustrate the key points:
-
-  % tap run sample/task 
-  % tap run -- sample/task --key=value input_one -- another/task input_two
-  
-The second statement specifies two tasks with inputs, and specifies a configuration for sample/task.  As can be seen, run separates tasks using a double-dash, the standard option break.  Options for run itself can be specified before the first option break.
-
-  % tap run --debug -- sample/task --key=value
-  
-Here run receives the '--debug' option and sample/task receives the '--key=value' option'.  <em>NOTE</em> it's always a good idea to include the first option break to formally signify when configuration of run stops.  Otherwise you may be confused when the following commands both produce the help for run:
-
-  % tap run --help
-  % tap run sample/task --help
-
-Inputs work the same way.  For example:
-
-  % tap run -- sample/task --key=value one -- another/task two three
-  
-Specifies the following:
-
-  t1 = app.task('sample/task', :key => 'value')
-  t1.enq('one')
-  
-  t2 = app.task('another/task')
-  t2.enq('two', 'three') 
-  
-Any number of tasks, configurations, and inputs may be specified in this way.  As a special note, rake tasks can be specified as well.  If the app cannot find a tap task by the specified name, rake is loaded (using the same loading  rules as the rake command) and run tries to find a corresponding rake task. ENV options can be specified in the rake statement.
-
-  % tap run -- test KEY=value
-
-=== YAML inputs
-
-Non-string inputs can be provided through run.  If an input begins with "---\n" then it is loaded as YAML into an object before being passed to a task. The syntax can be a lot to type, but is very handy to have around.  The following enques 'sample/task' with a hash input, {'number' => 1}.  
-
-On *nix, just hit enter to get the next line:
-
-  % tap run -- sample/task '---
-  > number: 1'
-
-On Windows, you need to pull some tricks to get newlines into your argument. Cleverly use a caret to ignore the next line feed:
-
-  % tap run -- sample/task '---^
-  More?
-  More? number: 1'
-  
-Notice that pressing enter _every other line_ is what actually puts the "\n" into the  parameter.  Keep using carets to enter more lines. The syntax on Windows isn't exactly pretty, but it works... with a caveat.  The latest execution script generated by rubygems (tap.bat) re-processes inputs to tap before executing the command for real.  I haven't found a workaround short of invoking tap from ruby itself:
-
-  % ruby C:/ruby/bin/tap run -- sample/task '---^
-  More?
-  More? number: 1'
-
-== generate/destroy
-
-Generate and destory launch generator scripts, the same as in Rails.  By default Tap provides generators for:
-
-root:: the basic Tap directory structure
-task:: a Tap:Task and test for the task
-file_task:: a Tap::FileTask and test for the task
-workflow:: a Tap::Workflow and test for the workflow
-config:: a yaml config file for the specified task 
-command:: a new subcommand
-generator:: a new generator
-
-Some examples:
-
-  % tap generate root .
-  % tap generate task sample_task
-  % tap generate config sample_task
-  
-  % tap destroy config sample_task
-  % tap destroy task sample_task
-  % tap destroy root .
-
-== console
-
-Console opens an irb session with Tap loaded and configured using 'tap.yml'.  Console defines a variable 'app' referencing Tap::App.instance, for easy access.
-
-  % tap console
-  irb(main):001:0> app.log(:hello)
-    I[17:18:53]              hello
-  => true
-  irb(main):002:0>
- 
-For actively testing your code, remember that many of your files will be loaded using Dependencies (from {ActiveSupport}[http://rubyforge.org/projects/activesupport/]).  You can modify your code, clear the  dependencies, and observe the changes within a single session.  The command is:
-
-  irb(main):003:0> app.reload
-  # => [... an array of unloaded constants ...]

data/Rakefile

@@ -1,127 +0,0 @@
-require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
-require 'rake/gempackagetask'
-
-$:.unshift "./lib"
-require 'tap/constants'
-require 'tap/patches/rake/testtask.rb'
-
-desc 'Default: Run tests.'
-task :default => :test
-
-#
-# Gem specification
-#
-Gem::manage_gems
-
-spec = Gem::Specification.new do |s|
-	s.name = "tap"
-	s.version = Tap::VERSION
-	s.author = "Simon Chiang"
-	s.email = "simon.chiang@uchsc.edu"
-	s.homepage = Tap::WEBSITE
-	s.platform = Gem::Platform::RUBY
-	s.summary = "A framework for configurable, distributable, and easy-to-use tasks and workflow applications."
-	s.files = File.read("Manifest.txt").split("\n").select {|f| f !~ /^\s*#/ && !File.directory?(f) }
-	s.require_path = "lib"
-	s.rubyforge_project = "tap"
-	s.test_file = "test/tap_test_suite.rb"
-	s.bindir = "bin"
-	s.executables = ["tap"]
-  s.default_executable = "tap"
-  
-	s.has_rdoc = true
-  s.rdoc_options << '--title' << 'Tap - Task Application' << '--main' << 'README' 
-	s.extra_rdoc_files = ["README", "MIT-LICENSE", "History", "Tutorial", "Basic Overview", "Command Reference"]
-  s.add_dependency("activesupport", ">=2.0.1")
-end
-
-Rake::GemPackageTask.new(spec) do |pkg|
-	pkg.need_tar = true
-end
-
-desc 'Prints the gem manifest.'
-task :print_manifest do
-  spec.files.each do |file|
-    puts file
-  end
-end
-
-desc 'Run tests.'
-Rake::TestTask.new(:test) do |t|
-  t.test_files = if ENV['check']
-    Dir.glob( File.join('test',  "**/*#{ENV['check']}*_check.rb") )
-  else
-    Dir.glob( File.join('test', ENV['pattern'] || '**/*_test.rb') ).delete_if do |filename|
-      filename =~ /test\/check/
-    end
-  end
-  
-  t.verbose = true
-  t.warning = true
-end
-
-#
-# Documentation tasks
-#
-
-desc 'Generate documentation.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  require 'tap/support/tdoc'
-  
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'tap'
-  rdoc.template = 'tap/support/tdoc/tdoc_html_template' 
-  rdoc.options << '--line-numbers' << '--inline-source' << '--fmt' << 'tdoc'
-  rdoc.rdoc_files.include('README', 'MIT-LICENSE', "History", "Tutorial", "Basic Overview", "Command Reference")
-  rdoc.rdoc_files.include('lib/tap/**/*.rb')
-end
-
-desc 'Generate website.'
-task :website => [:rdoc] do |t|
-  require 'tap'
-  
-  # temporary
-  $: << File.dirname(__FILE__) + "/tap/simple_site/lib"
-  $: << File.dirname(__FILE__) + "/tap/ddb/lib"
-  Dependencies.load_paths << File.dirname(__FILE__) + "/tap/simple_site/lib"
-  Dependencies.load_paths << File.dirname(__FILE__) + "/tap/ddb/lib"
-
-  require 'simple_site'
-  
-  app = Tap::App.instance
-  
-  app['pkg'] = "pkg/website-#{Tap::VERSION}"
-  app['content'] = 'website/content'
-  app['views'] = 'website/views'
-  app.run 'simple_site/compile', '.'
-  
-  cp_r "rdoc", app.filepath('pkg', "rdoc")
-end
-
-#
-# Hoe tasks
-#
-
-desc 'Install the package as a gem'
-task :install_gem => [:package] do
-  sh "#{'sudo ' unless WINDOZE}gem install pkg/*.gem"
-end
-
-desc "Publish Website to RubyForge"
-task :publish_website => [:website] do
-  config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
-  host = "#{config["username"]}@rubyforge.org"
-  
-  rsync_args = "-v -c -r"
-  remote_dir = "/var/www/gforge-projects/tap"
-  local_dir = "pkg/website-#{Tap::VERSION}"
- 
-  sh %{rsync #{rsync_args} #{local_dir}/ #{host}:#{remote_dir}}
-end
-
-desc 'Show information about the gem.'
-task :debug_gem do
-  puts spec.to_ruby
-end

data/Tutorial

@@ -1,287 +0,0 @@
-= Quick Start Tutorial
-
-This tutorial demonstrates the basic use of tap from the command line, how to:
-
-* generate and run a task
-* generate and run a command
-
-=== Task Basics
-
-Begin by creating a tap root directory structure:
-
-  % tap generate root /path/to/root_dir
-  % cd /path/to/root_dir
-  
-Make a task:
-
-  % tap generate task sample/task
-
-Test the task (in fact using the rake test task):
- 
-  % tap run test 
-  
-Get help for the task:
-
-  % tap run -- sample/task --help
-  Sample::Task
-
-  Replace with a description.  The default task simply 
-  demonstrates the use of a config and logging.  
-  Usage:
-  Replace with usage instructions
-
-  Options:
-    --key                               a sample config ('value')
-    --help                              Print this help.
-    --debug                             Trace execution and debug
-    --use                               Loads inputs from file.
-    --iterate                           Iterates over inputs.
-
-Run the task in the most basic way:
-
-  % tap run sample/task input_one
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[21:32:28]        sample/task input_one was processed with value
-    
-Run the task, setting the 'key' configuration and iterating over several inputs:
-  
-  % tap run -- sample/task --key='the new value' --iterate one two three
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[21:33:31]        sample/task one was processed with the new value
-    I[21:33:31]        sample/task two was processed with the new value
-    I[21:33:31]        sample/task three was processed with the new value
-    
-Run multiple tasks, or in this case the same task twice, followed by a dump task.  The tasks are separated into 'rounds' of execution, where the rounds are indicated by '--' and '--+' respectively.   The sample tasks in the first round run to completion before tap runs the dump task.  Normally the dump task saves results to a file you specify, but with no specified file (as below) the dump is to the console:
-
-  % tap run -- sample/task one -- sample/task two --+ tap/dump 
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[21:50:40]        sample/task one was processed with value
-    I[21:50:40]        sample/task two was processed with value
-  # audit:
-  # o-[] "two"
-  # o-[sample/task] "two was processed with value"
-  # 
-  # o-[] "one"
-  # o-[sample/task] "one was processed with value"
-  # 
-  # date: 2008-04-08 21:50:40
-  --- 
-  sample/task (8603460): 
-  - one was processed with value
-  sample/task (8602320): 
-  - two was processed with value
-
-Don't be thrown by the shuffled order in the dump -- the dump is valid YAML and represents the results hashed by task.
-
-Now navigate to and open the 'lib/sample/task.rb' file.  Inside you can see the class definition, with comments indicating how to define additional configurations, add command line documentation, log activity, and define the process method.  Let's change it up a bit:
-
-  [lib/sample/task.rb]
-  module Sample
-    # == Description
-    # A simple math task that multiplies an input by a 
-    # factor. Remember, strings can be multipled too!
-    # === Usage
-    #   % tap run -- sample/task INPUT
-    #
-    class Task < Tap::Task
-  
-      # The sum of the inputs is multiplied by this
-      # factor.  String factors are converted to 
-      # an integer.
-      config(:factor, 2) do |value|    # a factor
-        value.to_i
-      end
-    
-      def process(input)
-        result = input * factor
-        log self.name, result
-    
-        result
-      end
-    
-    end
-  end
-
-The new configurations and documentation are immediately available:
-
-  % tap run -- sample/task --help
-  Sample::Task
-
-  A simple math task that multiplies an input by a 
-  factor. Remember, strings can be multipled too!
-  Usage:
-    % tap run -- sample/task INPUT
-
-  Options:
-    --factor                            a factor (2)
-    --help                              Print this help.
-    --debug                             Trace execution and debug
-    --use                               Loads inputs from file.
-    --iterate                           Iterates over inputs.
-
-And the task is ready to go:
-
-  % tap run -- sample/task "yo"
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[22:22:13]        sample/task yo yo
-    
-Make a configuration file for the task:
-
-  % tap generate config sample/task
-        
-You get documentation in the configuration file as well.  We can set configurations here and have them be used by the task:
-
-  [config/sample/task.yml]
-  # Sample::Task configuration
-
-  # The sum of the inputs is multiplied by this
-  # factor.  String factors are converted to
-  # an integer.
-  # a factor (2)
-  factor: 3
-
-As can be seen here:
-
-  % tap run -- sample/task yo
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[22:26:41]        sample/task yo yo yo
-
-If you need to batch run the same task with the same inputs, but multiple sets of configurations, simply define an array of configurations in the config file:
-  
-  [config/sample/task.yml]
-  # Sample::Task configuration
-  - factor: 1
-  - factor: 2
-  - factor: 3
-
-  % tap run -- sample/task yo
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[22:37:46]        sample/task yo
-    I[22:37:46]        sample/task yo yo
-    I[22:37:46]        sample/task yo yo yo
-
-=== Command Basics
-
-Now say you want to do something fancier than the basic execution provided by the run command.  First, generate a new command:
-
-  % tap generate command echo
-  
-The new command is now available from tap:
-
-  % tap echo --help
-  tap echo {options} ARGS...
-
-  The default command simply prints the input arguments
-  and application information, then exits.
-
-  Options:
-    --help                    (-h)      Print this help.
-    --debug                             Specifies debug mode.
-    
-  % tap echo one two three
-  Received: one, two, three
-  state: 0 (READY) queue: 0 thread_queue: 0 threads: 0 results: 0
-
-The command script itself is very general and can be run through ruby directly.  The tap command basically just sets up the environment using tap.yml and then loads the command script, hence you can do whatever you like within the command script.  Lets open it up and change a few things:
-
-  [cmd/echo.rb]
-  # = Usage
-  # tap echo {options} ARGS...
-  #
-  # = Description
-  # Formats the inputs, then echoes them to the 
-  # 'echo/output.txt' file and to the console.
-  #
-  
-  require 'tap'
-  require 'tap/script'
-  
-  app = Tap::App.instance   
-  
-  #
-  # handle options
-  #
-  
-  opts = [
-    ['--help', '-h', GetoptLong::NO_ARGUMENT, "Print this help."],
-    ['--debug', nil, GetoptLong::NO_ARGUMENT, "Specifies debug mode."]]
-    
-  Tap::Script.handle_options(*opts) do |opt, value| 
-    case opt
-    when '--help'
-      puts Tap::Script.usage(__FILE__, "Usage", "Description", "Information", :keep_headers => false)
-      puts
-      puts "Options:"
-      puts Tap::Script.usage_options(opts)
-      exit
-      
-    when '--debug'
-      app.options.debug = true
-  
-    end
-  end
-  
-  #
-  # initialize some tasks
-  #
-  
-  # transform the inputs
-  t1 = Tap::Task.new do |task, *inputs| 
-    inputs.collect {|input| "echo #{input}" }.join("\n")
-  end
-  
-  # write to a file
-  t2 = Tap::FileTask.new do |task, input|
-    target = "echo/output.txt"
-    
-    # backup existing files, and ensure the directory exists
-    task.prepare(target)  
-    
-    File.open(target, "wb") {|f| f << input }
-    target
-  end
-  
-  # now make a simple workflow
-  app.sequence(t1, t2)
-  
-  #
-  # enque, run, and print out the results
-  #
-  
-  t1.enq(*ARGV)
-  app.run
-  
-  app.results(t2).each do |target|
-    puts "[#{target}]"
-    puts File.read(target)
-  end
-  
-Now run the command a few times:
-
-  % tap echo one two three
-  [echo/output.txt]
-  echo one
-  echo two
-  echo three
-
-  % tap echo tip top tap
-  [echo/output.txt]
-  echo tip
-  echo top
-  echo tap
-  
-You should find that the 'echo/output.txt' file exists with the 'tip top tap' result.  Moreover a backup directory will exist with the 'one two three' result, due to the FileTask#prepare method.  
-  
-