bahuvrihi-tap 0.10.0

data/History

@@ -0,0 +1,69 @@
+== 0.10.0 / 2008-08-08
+
+Major revision.  Reworked configurations and the execution
+environment.  Added Lazydoc documentation.  Backwards incompatible.
+Development is now on GitHub. 
+
+== 0.9.1 / 2008-04-26 revision 253
+
+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.
+
+* 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
+
+Major update to Tap. Many changes in this release ARE NOT BACKWARD COMPATIBLE.  
+
+* Reworked Task and App such that methods,  are
+  enqued and executed.  Made the Executable module 
+  to allow any Method to be enqued and executed.
+* App now aggregates results for methods that have no 
+  on_complete block; enabled access through App#results 
+  and App#_results.
+* Removed iteration from tasks
+* Task no longer templates app.config_templates.  Templating code
+  removed from this distribution.
+* Work to improve audit usability and visualization
+* Removed methods forwarding from Audit to Audit#_current,
+  as well as ambiguous Audit methods
+* Root [] now returns expanded paths unchanged. Example:
+  app['relative/path']  # => File.join(app.root, 'relative/path')
+  app['/expanded/path'] # => '/expanded/path'
+* Generalized rake support; now supports version 0.8.1
+* Fixes in generators
+* Improvements in running of multithread tasks
+* Removed condition blocks from tasks
+* many other things also...
+
+== 0.8.0 / 2007-12-08 revision 138
+
+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
+

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+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
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,119 @@
+= {Tap (Task Application)}[http://tap.rubyforge.org]
+
+A framework for creating configurable, distributable tasks and workflows.
+
+== Description
+
+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.
+
+* {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]
+
+=== Additional Notes:
+
+- 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 pulls documentation out of task classes to generate manifests:
+
+  % tap run -T
+    sample:
+      goodnight   # your basic goodnight moon task
+    tap:
+      dump        # the default dump task
+      rake        # run rake tasks  
+
+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.
+- Despite the talk of workflows, the Workflow class should still be considered
+  in progress.  Tasks themselves are stable.
+
+== Installation
+
+Tap is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+
+  % gem install tap
+
+Tap 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) 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

@@ -0,0 +1,114 @@
+#!/usr/local/bin/ruby
+# usage: tap <command> {options} [args]
+#
+# examples:
+#   tap generate root .                  # generates a root dir
+#   tap run taskname --option input      # runs the 'taskname' task
+#
+# help:
+#   tap help                             # prints this help
+#   tap command --help                   # prints help for 'command'
+#
+
+tap_root_dir  = File.dirname(__FILE__) + "/.."
+require "#{tap_root_dir}/lib/tap.rb"
+
+# setup the environment
+begin
+  
+  $DEBUG = true if ARGV.delete('-d-')
+  before = nil
+  after = nil
+  aliases = 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
+
+    unless unhandled_configs.empty?
+      local.log(:warn, "ignoring non-env configs: #{unhandled_configs.keys.join(',')}", Logger::DEBUG)
+    end
+  end
+  
+  # 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
+  
+  tap = Tap::Env.instance_for(tap_root_dir)
+  env.push(tap)
+
+rescue(Tap::Env::ConfigError)
+  # catch errors and exit gracefully
+  # (errors usu from gem loading errors)
+  puts $!.message
+  exit(1)
+end
+
+#
+# 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) if before != nil
+rescue(Exception)
+  puts "Error in before script."
+  env.handle_error($!)
+  exit(1)
+end 
+
+#
+# run tap
+#
+
+begin
+  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 nil, '--help'
+    # give some help
+    require 'tap/support/command_line'
+    
+    puts Tap::Support::CommandLine.usage(__FILE__)
+    puts
+    puts "available commands:"
+    puts env.summarize(:commands)
+    puts
+    puts "version #{Tap::VERSION} -- #{Tap::WEBSITE}" 
+  else
+    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
+  env.handle_error($!)
+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

data/cmd/destroy.rb

@@ -0,0 +1,16 @@
+require 'tap/generator/base'
+require 'tap/generator/destroy'
+
+env = Tap::Env.instance
+
+if ARGV.empty? || ARGV == ['-T']
+  puts env.summarize(:generators) {|const| const.document[const.name]['generator'] }
+  exit
+end
+
+name = ARGV.shift
+const = env.search(:generators, name) or raise "unknown generator: #{name}"
+
+generator_class = const.constantize
+generator, argv = generator_class.instantiate(ARGV)
+generator.extend(Tap::Generator::Destroy).process(*argv)

data/cmd/generate.rb

@@ -0,0 +1,16 @@
+require 'tap/generator/base'
+require 'tap/generator/generate'
+
+env = Tap::Env.instance
+
+if ARGV.empty? || ARGV == ['-T']
+  puts env.summarize(:generators) {|const| const.document[const.name]['generator'] }
+  exit
+end
+
+name = ARGV.shift
+const = env.search(:generators, name) or raise "unknown generator: #{name}"
+
+generator_class = const.constantize
+generator, argv = generator_class.instantiate(ARGV)
+generator.extend(Tap::Generator::Generate).process(*argv)

data/cmd/run.rb

@@ -0,0 +1,126 @@
+# tap run {options} -- {task options} task INPUTS...
+#
+# examples:
+#   tap run --help                     Prints this help
+#   tap run -- task --help             Prints help for task
+#
+
+env = Tap::Env.instance
+app = Tap::App.instance
+cmdline = Tap::Support::CommandLine
+
+#
+# handle options
+#
+
+dump = false
+OptionParser.new do |opts|
+  
+  opts.separator ""
+  opts.separator "configurations:"
+  
+  Tap::App.configurations.each do |receiver, key, config|
+    next if receiver == Tap::Root
+    
+    opts.on(*cmdline.configv(config)) do |value|
+      app.send(configuration.writer, value)
+    end
+  end
+ 
+  opts.separator ""
+  opts.separator "options:"
+
+  opts.on("-h", "--help", "Show this message") do
+    opts.banner = cmdline.usage(__FILE__)
+    Tap::App.lazydoc.resolve
+    puts opts
+    exit
+  end
+  
+  opts.on('-T', '--manifest', 'Print a list of available tasks') do |v|
+    puts env.summarize(:tasks) {|const| const.document[const.name]['manifest'] }
+    exit
+  end
+  
+end.parse!(ARGV)
+
+#
+# handle options for each specified task
+#
+
+rounds = cmdline.split(ARGV).collect do |argvs|
+  argvs.each do |argv|
+    ARGV.clear  
+    ARGV.concat(argv)
+   
+    unless td = cmdline.shift(ARGV)
+      # warn nil?
+      next
+    end
+
+    # attempt lookup the task class
+    const = env.search(:tasks, td) or raise "unknown task: #{td}"
+    task_class = const.constantize or raise "unknown task: #{td}"
+    
+    # now let the class handle the argv
+    task, argv = task_class.instantiate(ARGV, app)
+    task.enq *argv.collect! {|str| cmdline.parse_yaml(str) }
+  end
+
+  app.queue.clear
+end
+ARGV.clear
+
+rounds.delete_if {|round| round.empty? }
+if rounds.empty?
+  puts "no task specified"
+  exit
+end
+
+#
+# set signals 
+#
+
+# info signal -- Note: some systems do 
+# not support the INFO signal 
+# (windows, fedora, at least)
+signals = Signal.list.keys
+if signals.include?("INFO")
+  Signal.trap("INFO") do
+    puts app.info
+  end
+end
+
+# interuption signal
+if signals.include?("INT")
+  Signal.trap("INT") do
+    puts " interrupted!"
+    # prompt for decision
+    while true
+      print "stop, terminate, exit, or resume? (s/t/e/r):"
+      case gets.strip
+      when /s(top)?/i 
+        app.stop
+        break
+      when /t(erminate)?/i 
+        app.terminate
+        break
+      when /e(xit)?/i 
+        exit
+      when /r(esume)?/i 
+        break
+      else
+        puts "unexpected response..."
+      end
+    end
+  end
+end
+
+#
+# enque tasks and run!
+#
+
+rounds.each_with_index do |queue, i|
+  app.queue.concat(queue)
+  app.run
+end