tap 0.18.0 → 0.19.0

data/doc/Class Reference

@@ -1,330 +0,0 @@
-= Class Reference
-
-This is a ground-up overview of the main classes and modules used by Tap,
-specifically Tasks, Apps, and Envs.
-
-== Tasks
-
-==== Tap::App::Node
-
-http://tap.rubyforge.org/images/Node.png
-
-Nodes are the building blocks of workflows. Nodes are essentially a method
-with an array of joins to call when the method completes. Any object
-responding to <tt>call</tt> may be turned into a node, so any method may be
-used in a workflow. 
-
-Tasks are constructed so that <tt>call</tt> forwards arguments to
-<tt>process</tt>. This allows hooks and callbacks to be inserted as needed in
-subclasses.
-
-==== {Configurable}[http://tap.rubyforge.org/configurable/]
-
-http://tap.rubyforge.org/images/Configurable.png
-
-Tap uses the {Configurable}[http://tap.rubyforge.org/configurable/] module to
-declare class configurations and make them available on the command line.
-Configurations provide a shorthand to define attributes with a default value.
-For instance:
-  
-  class ConfigClass
-    include Configurable
-
-    config :key, 'value' do |input|
-      input.upcase
-    end
-    
-    def initialize
-      initialize_config
-    end
-  end
-
-Is basically the same as:
-
-  class RegularClass
-    attr_reader :key
-
-    def key=(input)
-      @key = input.upcase
-    end
-
-    def initialize
-      self.key = 'value'
-    end
-  end
-
-Configurations may be accessed through a hash-like config object, as you can
-see here:
-
-  c = ConfigClass.new
-  c.key                       # => 'VALUE'
-
-  c.config[:key] = 'new value'
-  c.key                       # => 'NEW VALUE'
-
-  c.key = 'another value'
-  c.config[:key]              # => 'ANOTHER VALUE'
-
-This setup is both fast and convenient. See the
-{Configurable}[http://tap.rubyforge.org/configurable] documentation for more
-information.
-
-==== {Configurable::Validation}[http://tap.rubyforge.org/configurable/classes/Configurable/Validation.html]
-
-When configurations are set from the command line, the config writer
-inevitably receives a string, even though you may want a non-string input. The
-{Validation}[http://tap.rubyforge.org/configurable/classes/Configurable/Validation.html]
-module provides standard blocks to validate and transform inputs. These blocks
-may be accessed through the shortcut method <tt>c</tt> (ex: <tt>c.integer</tt>
-or <tt>c.regexp</tt>). Validation blocks generally load string inputs as
-YAML and validate that the result is the correct class; non-string inputs are
-simply validated.
-
-  class ValidatingClass
-    include Configurable
-
-    config :int, 1, &c.integer                 # assures the input is an integer
-    config :int_or_nil, 1, &c.integer_or_nil   # integer or nil only
-    config :array, [], &c.array                # you get the idea
-  end
-
-  vc = ValidatingClass.new
-
-  vc.array = [:a, :b, :c]
-  vc.array                                     # => [:a, :b, :c]
-
-  vc.array = "[1, 2, 3]"
-  vc.array                                     # => [1, 2, 3]
-
-  vc.array = "string"                          # !> ValidationError
-
-Validation blocks sometimes imply metadata. For instance <tt>c.flag</tt> makes
-a config into a flag on the command line.
-
-==== {Lazydoc}[http://tap.rubyforge.org/lazydoc]
-
-{Lazydoc}[http://tap.rubyforge.org/lazydoc] fits into the space between live
-code and code documentation. Lazydoc scans files to pull documentation into
-the object space, and uses a syntax like this:
-
-  # Constant::key value
-  # comment
-
-For example:
-
-  [lazydoc_file.rb]
-  # Const::Name::key value
-  # 
-  # This is an extended,
-  # multiline comment.
-  #
-
-  require 'tap'
-
-  lazydoc = Lazydoc[__FILE__]
-  lazydoc.resolve
-  
-  lazydoc['Const::Name']['key'].value          # => "value"
-  lazydoc['Const::Name']['key'].comment        # => "This is an extended, multiline comment."
-
-Lazydoc can also register specific lines for documentation, such as method
-definitions or configurations. Tap uses Lazydoc to identify files that contain
-resources like tasks and joins, to extract config documentation, and to infer
-the arguments a task receives from the command line. Here is an example of
-information gleaned from a task definition:
-
-  # Sample::task a summary of the task
-  class Sample < Tap::Task
-    config :key, 'value'   # a simple configuration
-    
-    def process(a, b='B', *c)
-    end
-  end
-  
-  Sample::desc.to_s                            # => "a summary of the task"
-  Sample::args.to_s                            # => "A B='B' C..."
-  
-  key = Sample.configurations[:key]
-  key.attributes[:desc].to_s                   # => "a simple configuration"
-  
-See the {Lazydoc}[http://tap.rubyforge.org/lazydoc] documentation for more
-information.
-
-=== Tap::Task
-
-http://tap.rubyforge.org/images/Task.png
-
-Tasks are the bread and butter of Tap. Tasks serve as nodes in workflows and
-map to the command line as miniature applications. Tasks are also useful as
-ordinary objects.
-
-Tasks may be dynamically generated on an app using the <tt>task</tt> method.   This provides a quick way of sketching out a workflow.
-
-  app = Tap::App.instance
-  t = app.task {|task| 1 + 2 }
-  t.process                # => 3
-
-  t = app.task {|task, x, y| x + y }
-  t.process(1, 2)          # => 3
-
-Tasks can be configured and joined into workflows.
-
-  runlist = []
-  results = []
-  
-  t1 = app.task(:key => 'one') do |task, input| 
-    runlist << task
-    "#{input}:#{task.config[:key]}"
-  end
-
-  t2 = app.task do |task, input|
-    runlist << task
-    "#{input}:two"
-  end
-  
-  t2.on_complete do |result|
-    results << result
-  end
-  
-  t1.sequence(t2)
-
-Results may be collected by the underlying Tap::App.
-
-  app.enq(t1)
-  app.run
-  
-  runlist                  # => [t1, t2]
-  results                  # => ["input:one:two"]
-
-== Apps
-
-==== Tap::App::Queue
-
-http://tap.rubyforge.org/images/Queue.png
-
-Apps coordinate the execution of nodes through a queue. The queue is just a
-stack of nodes and inputs; during a run the nodes are sequentially executed
-with the inputs.
-
-=== Tap::App
-
-http://tap.rubyforge.org/images/App.png
-
-Instances of Tap::App coordinate the execution of nodes.
-
-Task initialization requires an App, which is by default Tap::App.instance.  
-Tasks use their app for logging, dependency-resolution, checks, and to enque 
-themselves.
-
-  results = []
-  app = Tap::App.new {|result| results << result }
-  t = app.task {|task, *inputs| inputs }
-  t.enq(1)
-  t.enq(2,3)
-  
-  app.queue.to_a             # => [[t, [1]], [t, [2,3]]]
-  app.run
-  results                    # => [[1], [2,3]]
-
-== Envs 
-
-==== Tap::Root
-
-http://tap.rubyforge.org/images/Root.png
-
-A Root represents the base of a directory structure. Roots allow you to alias
-relative paths, basically allowing you to develop code for a conceptual
-directory structure that can be defined later.
-
-  root = Tap::Root.new '/path/to/root'
-  root.root                                      # => '/path/to/root'
-  root['config']                                 # => '/path/to/root/config'
-  root.path('config', 'sample.yml')              # => '/path/to/root/config/sample.yml'
-
-While simple, this ability to alias paths is useful, powerful, and forms the
-basis of the Tap environment.
-
-==== Tap::Env
-
-http://tap.rubyforge.org/images/Env.png
-
-Envs generate manifests of various resources (tasks, generators, etc) and 
-provide methods to uniquely identify resources using minimized base paths.
-In this directory structure:
-
-  path
-  `- to
-      |- another
-      |   `- file.rb
-      |- file-0.1.0.rb
-      |- file-0.2.0.rb
-      `- file.rb
-
-The minimal paths that uniquely identify these files are (respectively):
-
-  'another/file'
-  'file-0.1.0'
-  'file-0.2.0'
-  'file.rb'
-
-Envs facilitate mapping a minimal path to an actual path, and hence to a
-resource.  Envs can be nested so that manifests span multiple directories.
-Indeed, this is how tap accesses tasks and generators within gems; the gem
-directories are initialized as Envs and nested within the Env for the working
-directory.
-
-http://tap.rubyforge.org/images/Nested-Env.png
-
-To prevent conflicts between similarly-named resources under different Envs,
-Env allows selection of Envs, also by minimized paths.  Say you installed the
-'tap-tasks' gem.
-
-  % tap manifest
-  --------------------------------------------------------------------------------
-  Desktop:          (/Users/username/Desktop)
-  --------------------------------------------------------------------------------
-  tap-tasks:        (/Library/Ruby/Gems/1.8/gems/tap-tasks-0.1.0)
-    tasks
-      argv          (lib/tap/tasks/argv.rb)
-      inspect       (lib/tap/tasks/dump/inspect.rb)
-      dump/yaml     (lib/tap/tasks/dump/yaml.rb)
-      load/yaml     (lib/tap/tasks/load/yaml.rb)
-  --------------------------------------------------------------------------------
-  tap:              (/Library/Ruby/Gems/1.8/gems/tap-0.12.4)
-    commands
-      console       (cmd/console.rb)
-      destroy       (cmd/destroy.rb)
-      generate      (cmd/generate.rb)
-      manifest      (cmd/manifest.rb)
-      run           (cmd/run.rb)
-    generators
-      command       (lib/tap/generator/generators/command/command_generator.rb)
-      config        (lib/tap/generator/generators/config/config_generator.rb)
-      generator     (lib/tap/generator/generators/generator/generator_generator.rb)
-      root          (lib/tap/generator/generators/root/root_generator.rb)
-      task          (lib/tap/generator/generators/task/task_generator.rb)
-    tasks
-      dump          (lib/tap/dump.rb)
-      load          (lib/tap/load.rb)
-  --------------------------------------------------------------------------------
-
-  Desktop
-  |- tap-tasks 
-  `- tap 
-
-In this printout of the manifest, you can see the resources available to tap
-on the Desktop (none), in the tap-tasks gem, and in tap itself. In most cases
-the minipath of any of the tasks is sufficient for identification:
-
-  % tap run -- load --: dump/yaml
-  
-If there were a conflict, you'd have to specify the environment minipath like:
-
-  % tap run -- tap:load --: tap-tasks:dump/yaml
-
-==== Tap::Exe
-
-http://tap.rubyforge.org/images/Run-Env.png
-
-Tap::Exe adds methods for building and executing workflows from command line
-inputs.

data/lib/tap/exe.rb

@@ -1,130 +0,0 @@
-require 'tap/env'
-require 'tap/task'
-require 'tap/schema'
-
-module Tap
-  module Exe
-    
-    # Adapted from Gem.find_home
-    # def self.user_home
-    #   ['HOME', 'USERPROFILE'].each do |homekey|
-    #     return ENV[homekey] if ENV[homekey]
-    #   end
-    # 
-    #   if ENV['HOMEDRIVE'] && ENV['HOMEPATH'] then
-    #     return "#{ENV['HOMEDRIVE']}#{ENV['HOMEPATH']}"
-    #   end
-    # 
-    #   begin
-    #     File.expand_path("~")
-    #   rescue
-    #     File::ALT_SEPARATOR ? "C:/" : "/"
-    #   end
-    # end
-
-    # Setup an execution environment.
-    def self.setup(options={}, argv=ARGV, env=ENV)
-      if argv[-1] == "-d-"
-        argv.pop
-        $DEBUG = true 
-      end
-      
-      options = {
-        :dir => Dir.pwd,
-        :config_file => CONFIG_FILE
-      }.merge(options)
-      
-      # load configurations
-      dir = options.delete(:dir)
-      config_file = options.delete(:config_file)
-      user_config_file = config_file ? File.join(dir, config_file) : nil
-      
-      user = Env.load_config(user_config_file)
-      global = {}
-      env.each_pair do |key, value|
-        if key =~ /\ATAP_(.*)\z/
-          global[$1.downcase] = value
-        end
-      end
-      
-      config = {
-        'root' => dir,
-        'gems' => :all
-      }.merge(global).merge(user).merge(options)
-      
-      # keys must be symbolize as they are immediately 
-      # used to initialize the Env configs
-      config = config.inject({}) do |options, (key, value)|
-        options[key.to_sym || key] = value
-        options
-      end
-      
-      # instantiate
-      exe = Env.new(config, :basename => config_file).extend(Exe)
-      
-      exe.register('command') do |env|
-        env.root.glob(:cmd, "**/*.rb")
-      end
-      
-      # add the tap env if necessary
-      unless exe.any? {|env| env.root.root == TAP_HOME }
-        exe.push Env.new(TAP_HOME, exe.context) 
-      end
-      
-      exe
-    end
-    
-    # The config file path
-    CONFIG_FILE = "tap.yml"
-    
-    # The home directory for Tap
-    TAP_HOME = File.expand_path("#{File.dirname(__FILE__)}/../..")
-    
-    def launch(argv=ARGV)
-      case command = argv.shift.to_s  
-      when '', '--help'
-        yield
-      else
-        if path = seek('command', command)
-          load path # run the command, if it exists
-        else
-          puts "Unknown command: '#{command}'"
-          puts "Type 'tap --help' for usage information."
-        end
-      end
-    end
-    
-    def self.set_signals(app)
-      # info signal -- Note: some systems do 
-      # not support the INFO signal 
-      # (windows, fedora, at least)
-      signals = Signal.list.keys
-      Signal.trap("INFO") do
-        puts app.info
-      end if signals.include?("INFO")
-
-      # interuption signal
-      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 if signals.include?("INT")
-    end
-  end
-end