tap 0.9.1 → 0.10.0

data/History

@@ -1,28 +1,20 @@
-== 0.7.9 / 2007-09-14
+== 0.10.0 / 2008-08-08
 
-* Initial testing release with partial documentation
+Major revision.  Reworked configurations and the execution
+environment.  Added Lazydoc documentation.  Backwards incompatible.
+Development is now on GitHub. 
 
-== 0.8.0 / 2007-12-08 revision 138
+== 0.9.1 / 2008-04-26 revision 253
 
-Major update to Tap. Many changes in this release ARE NOT BACKWARD COMPATIBLE.  
-Documentation is still patchy, but improving.
+Relatively minor update, but with one important refactoring that
+removes the Tap::Script module.  This breaks backward compatibility
+but only should affect people who have made their own commands.
+Simply sub Tap::Support::CommandLine for Tap::Script to fix.
 
-* Expanded/reworked application configuration, allowing specification of gems
-  to be loaded as task libraries.
-* Default app config file is now tap.yml (from app.yml)
-* Updated and improved generators
-* Included rails_generators in distribution, removing rails dependency
-* Reworked many classes to clean up interface
-* Reworked testing methods
-* Improved configuration for tasks
-* Optimized loading
-* Reworked threading model
-* Addition of TDoc documentation
-* Reworked tap command and subcommands
-* Added packaging into executables
-* Updated to ActiveSupport 2.0.1
-* documentation, documentation, documentation
-* many other things as well...
+* Added constants methods (ex try_constantize) to String
+* Added gem discovery when no tap.yml file is present
+* Cleanup and refactoring -- removal of Tap::Script
+* Bug fix for JRuby 1.1.1
 
 == 0.9.0 / 2008-04-09 revision 246
 
@@ -49,14 +41,29 @@ Major update to Tap. Many changes in this release ARE NOT BACKWARD COMPATIBLE.
 * Removed condition blocks from tasks
 * many other things also...
 
-== 0.9.1 / 2008-04-26 revision 253
+== 0.8.0 / 2007-12-08 revision 138
 
-Relatively minor update, but with one important refactoring that
-removes the Tap::Script module.  This breaks backward compatibility
-but only should affect people who have made their own commands.
-Simply sub Tap::Support::CommandLine for Tap::Script to fix.
+Major update to Tap. Many changes in this release ARE NOT BACKWARD COMPATIBLE.  
+Documentation is still patchy, but improving.
+
+* Expanded/reworked application configuration, allowing specification of gems
+  to be loaded as task libraries.
+* Default app config file is now tap.yml (from app.yml)
+* Updated and improved generators
+* Included rails_generators in distribution, removing rails dependency
+* Reworked many classes to clean up interface
+* Reworked testing methods
+* Improved configuration for tasks
+* Optimized loading
+* Reworked threading model
+* Addition of TDoc documentation
+* Reworked tap command and subcommands
+* Added packaging into executables
+* Updated to ActiveSupport 2.0.1
+* documentation, documentation, documentation
+* many other things as well...
+
+== 0.7.9 / 2007-09-14
+
+* Initial testing release with partial documentation
 
-* Added constants methods (ex try_constantize) to String
-* Added gem discovery when no tap.yml file is present
-* Cleanup and refactoring -- removal of Tap::Script
-* Bug fix for JRuby 1.1.1

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2007, Regents of the University of Colorado.
+Copyright (c) 2006-2008, Regents of the University of Colorado.
 Developer:: Simon Chiang, Biomolecular Structure Program, Hansen Lab
 Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
 

data/README

@@ -1,52 +1,103 @@
-= Tap (Task Application)
+= {Tap (Task Application)}[http://tap.rubyforge.org]
 
-A framework for creating configurable, distributable, and easy-to-use tasks and workflow applications.
-
-See the {website}[http://tap.rubyforge.org] for more information.
+A framework for creating configurable, distributable tasks and workflows.
 
 == Description
 
-Tap provides a framework to define, configure, and join tasks into workflows. Tap provides a lot of niceties like generators and libraries geared towards testing tasks, generating documentation, as well as task execution and distribution.  Tasks are immediately available from the command line through the 'tap' command.
+Tap tasks are designed to be easy to test, subclass, use in scripts, and run 
+from the command line.  Tap provides methods to generate and utilize config 
+files, join tasks into workflows, as well as dump and reuse results.  Task 
+libraries are readily shared as gems.  Check out the links for tutorials, 
+development, and bug tracking.
 
-Make a task:
+* {Tutorial}[link:files/doc/Tutorial.html], {Class}[link:files/doc/Class%20Reference.html] and {Command}[link:files/doc/Command%20Reference.html] Reference
+* Website[http://tap.rubyforge.org]
+* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/9908-tap-task-application/overview]
+* Github[http://github.com/bahuvrihi/tap/tree/master]
 
-  % tap generate task sample/task
+=== Additional Notes:
 
-Run the task setting the 'key' configuration:
-  
-  % tap run -- sample/task --key=value input
-  ctl-i prints information
-  ctl-c interupts execution
-  beginning run...
-    I[10:53:11]        sample/task input was processed with value
-  
-Interact with the task using irb:
+- Tap and Rake[http://rake.rubyforge.org/] are targeted at different problems, 
+  but play well together. See Tap::Tasks::Rake to use rake tasks in tap.
+- Tap is tested on MRI (the standard Ruby interpreter, versions 1.8.6 and 
+  1.9.0) and JRuby[http://jruby.codehaus.org/].
+
+=== Usage
+
+A simple task illustrates the usage of tap:
+
+  # 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 console
-  irb(main):001:0> t = app.task('sample/task', :key => 'value')
-  irb(main):002:0> t.enq('input')
-  irb(main):003:0> app.run
-    I[10:55:17]        sample/task input was processed with value
+Tap pulls documentation out of task classes to generate manifests:
 
-Additional Notes:
+  % tap run -T
+    sample:
+      goodnight   # your basic goodnight moon task
+    tap:
+      dump        # the default dump task
+      rake        # run rake tasks  
 
-- Tap can incorporate and run Rake[http://rake.rubyforge.org/] tasks as well as Tap tasks. 
-- Tap task libraries are designed for distribution as gems.  
-- Tap is tested on both MRI (the standard Ruby interpreter, versions 1.8.6 and 1.9.0) and JRuby[http://jruby.codehaus.org/].  
+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:
+      -h, --help                       Print this help
+          --name NAME                  Specify a name
+          --use FILE                   Loads inputs from file
+
+
+Tasks are immediately available to run:
+
+  % tap run -- goodnight moon
+    I[00:09:55]          goodnight moon
+  
+
+  % tap run -- goodnight moon --message hello
+    I[00:10:01]              hello moon
+  
+Tap comes with generators and allows distribution of task libraries as gems.  
+This can be illustrated by installing the 
+{sample_tasks}[http://tap.rubyforge.org/sample_tasks] gem:
+
+  % gem install sample_tasks
+  % tap run -T
+  sample:
+    goodnight   # your basic goodnight moon task
+  sample_tasks:
+    concat      # concatenate files with formatting
+    copy        # copies files
+    grep        # search for lines matching a pattern
+    print_tree  # print a directory tree
+  tap:
+    dump        # the default dump task
+    rake        # run rake tasks
 
 === Bugs/Known Issues
 
 - Some inconsequential tests on JRuby fail due to bugs in JRuby itself.
 - Several patches are required so that Tap runs properly on MRI 1.9.0.  These   
   will likely resolve themselves as 1.9.0 becomes stable.
-- Some code is still in progress; in general the well-documented code is stable.
-
-== Info 
-
-Copyright (c) 2006-2007, 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
-Licence:: MIT-Style
+- Despite the talk of workflows, the Workflow class should still be considered
+  in progress.  Tasks themselves are stable.
 
 == Installation
 
@@ -54,18 +105,15 @@ Tap is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
 
   % gem install tap
 
-See the tutorial or check out the {website}[http://tap.rubyforge.org] to get started using Tap programatically.
+Tap requires an updated version of RubyGems[http://docs.rubygems.org/] (>= 1.2.0).  To check the version and update RubyGems:
 
-== Credits
+  % gem --version
+  % gem --update system
 
-A great deal of inspiration came from other excellent open-source projects including Rake[http://rake.rubyforge.org] and {Ruby on Rails}[http://www.rubyonrails.org].  
-
-Thanks to my advisor {Dr. Kirk Hansen}[http://hsc-proteomics.uchsc.edu/hansenlab/] for his patience in letting me work on this project, and for putting together an awesome lab.
-
-Most of all I would like to <b>thank my family</b> for their never-ending support.
-
-=== Code
-
-Tap uses ActiveSupport for dependencies loading and a variety of other extensions.  Tap uses Rails generators and redistributes the code in the gem, to avoid an additional dependency.
+== Info 
 
+Copyright (c) 2006-2008, 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
+Licence:: {MIT-Style}[link:files/MIT-LICENSE.html]
 

data/bin/tap

@@ -8,120 +8,107 @@
 # help:
 #   tap help                             # prints this help
 #   tap command --help                   # prints help for 'command'
-# 
+#
 
-require File.join( File.dirname(__FILE__), "../lib/tap.rb")
+tap_root_dir  = File.dirname(__FILE__) + "/.."
+require "#{tap_root_dir}/lib/tap.rb"
 
 # setup the environment
-env = Tap::Env.instance
-app = Tap::App.instance
-
-env.logger = app.logger
-env.debug_setup if ARGV.delete('-d-')
+begin
+  
+  $DEBUG = true if ARGV.delete('-d-')
+  before = nil
+  after = nil
+  aliases = nil
 
-before = nil
-after = nil
+  app = Tap::App.instance
+  env = Tap::Env.instantiate(app, Tap::Env.load_config(Tap::Env::GLOBAL_CONFIG_FILE), app.logger) do |unhandled_configs|
+    before = unhandled_configs.delete(:before)
+    after = unhandled_configs.delete(:after)
+    
+    aliases = unhandled_configs.delete(:alias)
+    Tap::Support::Validation.validate(aliases, [Hash]) if aliases
 
-def handle_error(err)
-  case
-  when $DEBUG
-    puts err.message
-    puts
-    puts err.backtrace
-  when Tap::App.instance.debug? then raise err
-  else puts err.message
+    unless unhandled_configs.empty?
+      local.log(:warn, "ignoring non-env configs: #{unhandled_configs.keys.join(',')}", Logger::DEBUG)
+    end
   end
-end
-
-# configure the app to tap.yml if it exists
-default_config_file = Tap::Env::DEFAULT_CONFIG_FILE
-begin
   
-  env.load_config(default_config_file, app) do |non_env_configs|
-    before = non_env_configs.delete('before')
-    after = non_env_configs.delete('after')
-    
-    app.reconfigure(non_env_configs)
+  # add all gems if no gems are specified (Note this is VERY SLOW ~ 1/3 the overhead for tap)
+  if !File.exists?(Tap::Env::DEFAULT_CONFIG_FILE)
+    env.gems = Tap::Env.known_gems(true)
   end
   
-  env.discover_gems unless File.exists?(default_config_file)
+  tap = Tap::Env.instance_for(tap_root_dir)
+  env.push(tap)
 
-rescue(Exception)
+rescue(Tap::Env::ConfigError)
   # catch errors and exit gracefully
   # (errors usu from gem loading errors)
-  puts "Configuration error: #{$!.message}"
-  puts $!.backtrace if $DEBUG
-  puts "Check #{default_config_file} configurations"
+  puts $!.message
   exit(1)
 end
 
-# alert the user to the root directory if it's not Dir.pwd
-unless app.options.quiet || app.root == File.expand_path(Dir.pwd)
-  puts "root: #{app.root}" 
+#
+# setup after script
+#
+
+at_exit do
+  begin
+    eval(after) if after != nil
+  rescue(Exception)
+    puts "Error in after script."
+    env.handle_error($!)
+    exit(1)
+  end
 end
 
 #
 # run before script
 #
+
 begin
-  eval(before.to_s)
-rescue
+  eval(before) if before != nil
+rescue(Exception)
   puts "Error in before script."
-  handle_error($!)
+  env.handle_error($!)
   exit(1)
-end
+end 
+
+#
+# run tap
+#
 
 begin
-  available_commands = env.commands
+  env.activate
+
   command = ARGV.shift
+  if aliases && aliases.has_key?(command)
+    aliases[command].reverse_each {|arg| ARGV.unshift(arg)}
+    command = ARGV.shift
+  end
 
   case command  
-  when "--help", "-h", "help", "?", nil 
+  when nil, '--help'
     # give some help
-    File.open(__FILE__) do |file|
-      bang_line = true
-      file.each_line do |line|
-        if bang_line
-          bang_line = false
-          next
-        end
-        
-        break if line !~ /^#\s?(.*)/
-        puts $1
-      end
-    end
+    require 'tap/support/command_line'
     
+    puts Tap::Support::CommandLine.usage(__FILE__)
     puts
     puts "available commands:"
-
-    commands = available_commands.keys
-    commands.unshift("help")
-    
-    print "  "
-    puts commands.sort.join("\n  ")
+    puts env.summarize(:commands)
     puts
-    puts "version #{Tap::VERSION} -- #{Tap::WEBSITE}"
+    puts "version #{Tap::VERSION} -- #{Tap::WEBSITE}" 
   else
-    if available_commands.has_key?(command)
-      # run the command, if it exists
-      load available_commands[command]
+    if path = env.search(:commands, command)
+      load path # run the command, if it exists
     else
       puts "Unknown command: '#{command}'"
       puts "Type 'tap help' for usage information."
     end
   end
 rescue
-  handle_error($!)
-  puts "Type 'tap #{command} --help' for usage information."
+  env.handle_error($!)
 end
 
-#
-# run after script
-#
-begin
-  eval(after.to_s) 
-rescue
-  puts "Error in after script."
-  handle_error($!)
-  exit(1)
-end
+exit(0)

data/cmd/console.rb

@@ -0,0 +1,42 @@
+# tap console {options}
+#
+# Opens up an IRB session with Tap initialized to the configurations 
+# in tap.yml. Access the Tap::App.instance through 'app'.
+
+#
+# handle options
+#
+
+OptionParser.new do |opts|
+  opts.separator ""
+  opts.separator "options:"
+
+  opts.on("-h", "--help", "Show this message") do
+    opts.banner = Tap::Support::CommandLine.usage(__FILE__)
+    puts opts
+    exit
+  end
+end.parse!(ARGV)
+
+require "irb"
+
+def app
+  Tap::App.instance
+end
+
+def env
+  Tap::Env.instance
+end
+
+IRB.start
+
+# Handles a bug in IRB that causes exit to throw :IRB_EXIT
+# and consequentially make a warning message, even on a 
+# clean exit.  This module resets exit to the original 
+# aliased method.
+module CleanExit # :nodoc:
+  def exit(ret = 0)
+    __exit__(ret)
+  end
+end
+IRB.CurrentContext.extend CleanExit