tap 0.12.4 → 0.17.0

data/cmd/run.rb

@@ -11,24 +11,22 @@
 #
 
 env = Tap::Env.instance
-app = Tap::App.instance
+app = Tap::App.new
 
 #
-# divide argv
+# parse argv
 #
 
+# separate out argv schema
 argv = []
-break_regexp = Tap::Support::Parser::BREAK
+break_regexp = Tap::Schema::Parser::BREAK
 while !ARGV.empty? && ARGV[0] !~ break_regexp
   argv << ARGV.shift
 end
 
-#
-# handle options
-#
-
-dump = false
-ConfigParser.new do |opts|
+# parse options
+schemas = []
+ConfigParser.new(app.config) do |opts|
   opts.separator ""
   opts.separator "configurations:"
   
@@ -45,42 +43,62 @@ ConfigParser.new do |opts|
     Tap::App.lazydoc.resolve
     puts Lazydoc.usage(__FILE__)
     puts opts
-    exit
+    exit(0)
   end
   
   opts.on('-T', '--manifest', 'Print a list of available tasks') do
-    puts env.summarize(:tasks)
-    exit
+    tasks = env.manifest(:task)
+    tasks_found = !tasks.all_empty?
+    
+    middleware = env.manifest(:middleware)
+    middleware_found = !middleware.all_empty?
+    
+    if tasks_found 
+      puts "=== tasks ===" if middleware_found
+      puts tasks.summarize
+    end
+
+    if middleware_found
+      puts "=== middleware ===" if tasks_found
+      puts middleware.summarize
+    end
+    
+    exit(0)
   end
   
-  opts.on("-w", "--workflow FILE", "Build the workflow file") do |path|
+  opts.on('-m', '--middleware MIDDLEWARE', 'Specify app middleware') do |key|
+    middleware = env[:middleware][key] or raise("unknown middleware: #{key}")
+    app.use(middleware)
+  end
+  
+  opts.on("-s", "--schema FILE", "Build the schema file") do |path|
     unless File.exists?(path)
-      puts "No such file or directory - #{path}"
-      puts "(did you mean 'tap run -- #{path}'?)"
-      exit
+      puts "No such schema file - #{path}"
+      exit(1)
     end
-
-    schema = Tap::Support::Schema.load_file(path)
-    env.build(schema, app)
+    
+    schemas << Tap::Schema.load_file(path)
   end
   
-end.parse!(argv, app.config)
+end.parse!(argv, :clear_config => false, :add_defaults => false)
 
 #
-# build and run the argv
+# build and run
 #
 
-schema = Tap::Support::Schema.parse(ARGV)
-env.build(schema, app)
-ARGV.replace(argv)
-
-if app.queue.empty?
-  puts "no task specified"
-  unless ARGV.empty?
+begin
+  # parse argv schema
+  schemas << Tap::Schema.parse(ARGV)
+  ARGV.replace(argv)
+  
+  env.run(schemas, app)
+rescue
+  raise if $DEBUG
+  puts $!.message
+  if $!.message == "no nodes specified" && !ARGV.empty?
     puts "(did you mean 'tap run -- #{ARGV.join(' ')}'?)"
   end
-  exit
+  exit(1)
 end
 
-env.set_signals
-app.run
+exit(0)

data/doc/API

@@ -0,0 +1,84 @@
+= Application Programming Interface
+
+(Note these are all currently provisional.)
+
+== Tap::App
+
+Applications require the following API for nodes, joins, and middleware.
+
+==== Node
+
+Note the signature for call can be modified as necessary.
+
+  call(*inputs)    any return is allowed
+  dependencies()   returns an array of dependency nodes
+  joins()          returns an array of joins
+
+==== Dependency
+
+Same as a node, but call must be able to execute without inputs. For instance
+signatures like call(), call(a=:default), or call(*inputs) are allowed, but
+call(a, b, c) is not.
+
+==== Join
+
+  call(result)     any return is allowed
+
+==== Middleware
+
+  Middleware.new(stack)   returns an instance of middleware
+  call(node, inputs=[])   any return is allowed
+  stack()                 returns the original stack
+
+Note the middleware API is essentially the same as for {Rack}[http://rack.rubyforge.org/].
+
+== Tap::Schema
+
+Schema describe workflows as data.  To build a workflow from a schema, workflow classes need to instantiate themselves using the schema data. The <tt>parse</tt> and <tt>instantiate</tt> methods are provided to do so.  
+
+  WorkflowClass.parse(argv=ARGV, app=App.instance)
+  WorkflowClass.instantiate(argh, app=App.instance)
+  
+As implied in by the inputs, <tt>parse</tt> instantiates from an array, while <tt>instantiate</tt> instantiates from a hash with symbol keys.  If <tt>parse</tt> receives a string, it must be able to convert it to an array (ex using Shellwords).
+
+How the class actually performs the instantiation is up to the class but typically parse creates a hash and calls instantiate.
+
+==== Tap::Task (and subclasses)
+
+Parse and instantiate must return: [instance, args]
+
+==== Tap::Join (and subclasses)
+
+Parse and instantiate must return: [inputs, outputs, instance]
+
+== Tap::Env
+
+Envs identify resources by a constant attribute using Tap::Env#constant_manifest.  For instance this identifies the Sample node:
+
+  [sample.rb]
+  
+  # ::node summary
+  # description
+  class Sample < Tap::Node
+  end
+
+Here the constant name is inferred using the filepath.  A more formal declaration allows resources to be placed in files that are not named after the resource:
+
+  [alt.rb]
+  
+  # Sample::node summary
+  # description
+  class Sample < Tap::Node
+  end
+
+Joins are similarly identified by <tt>::join</tt>.  Resources intended to be discovered by constant_manifest must map the attribute documentation to the class 'desc' method.  
+
+  Sample::desc.summary         # => "summary"
+  Sample::desc.to_s            # => "description"
+  
+The easiest way to do so is with a {lazy_attr}[link:lazydoc/classes/Lazydoc/Attributes.html].
+
+  # ::resource
+  class Resource
+    lazy_attr :desc, 'resource'
+  end

data/doc/Class Reference

@@ -11,19 +11,16 @@ http://tap.rubyforge.org/images/Method.png
 
 Tasks are fundamentally just a method, simply a block of code.
 
-==== Tap::Support::Executable
+==== Tap::App::Node
 
-http://tap.rubyforge.org/images/Executable.png
+http://tap.rubyforge.org/images/Node.png
 
-Executable essentially wraps a method and adds support for dependencies, joins,
-and auditing.  Executables are the nodes in a workflow.  Any Executable may be
-joined to another Executable, enqued, and run by an App.  To wrap a method,
-Executable extends an object and defines which method on the object is 'executable'.
-Any method may be made executable, and so any method can participate in a workflow
-(see Object#_method).
-
-Tasks are constructed such that <tt>process</tt> is the executable method, hence
-<tt>process</tt> is the standard method overridden in Task subclasses.
+Nodes are the building blocks of workflows. Nodes are essentially a method
+wrapped with support for dependencies and joins. 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/]
 
@@ -104,7 +101,7 @@ simply validated.
 
   vc.array = "string"                          # !> ValidationError
 
-Validation blocks sometimes imply metadata.  For instance <tt>c.flag</tt> makes
+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]
@@ -134,12 +131,12 @@ For example:
   lazydoc['Const::Name']['key'].comment        # => "This is an extended, multiline comment."
 
 Lazydoc can also register specific lines for documentation, like method
-definitions or configurations.  Tap uses Lazydoc to identify files that contain
+definitions or configurations. Tap uses Lazydoc to identify files that contain
 tasks and generators, to extract config documentation, and to infer the args
-arguments a task receives.  Here is an example of information gleaned from a
+arguments a task receives. Here is an example of information gleaned from a
 task definition:
 
-  # Sample::manifest a summary of the task
+  # Sample::task a summary of the task
   class Sample < Tap::Task
     config :key, 'value'   # a simple configuration
     
@@ -147,7 +144,7 @@ task definition:
     end
   end
   
-  Sample::manifest.to_s                        # => "a summary of the task"
+  Sample::desc.to_s                            # => "a summary of the task"
   Sample::args.to_s                            # => "A B='B' C..."
   
   key = Sample.configurations[:key]
@@ -160,12 +157,13 @@ information.
 
 http://tap.rubyforge.org/images/Task.png
 
-Tasks are the bread and butter of Tap.  Tasks act as the nodes in workflows and,
-using the Configurable and Lazydoc metadata, map to the command line as miniature
-applications.  That said, tasks are perfectly useful as ordinary objects.
+Tasks are the bread and butter of Tap. Tasks act as the nodes in workflows
+and, using the Configurable and Lazydoc metadata, map to the command line as
+miniature applications. That said, tasks are perfectly useful as ordinary
+objects.
 
-When subclassing is too much, tasks may be interned with a block that effectively
-replaces <tt>process</tt>:
+When subclassing is too much, tasks may be interned with a block that
+effectively replaces <tt>process</tt>:
 
   t = Tap::Task.intern {|task| 1 + 2 }
   t.process                # => 3
@@ -194,91 +192,68 @@ and imperative workflows.
   end
   t1.sequence(t2)
   
-Results are aggregated into the underlying Tap::App.
-
-  t1.enq('input')
+  results = []
+  t2.on_complete do |result|
+    results << result
+  end
   
+Results may be collected by the underlying Tap::App.
+
   app = Tap::App.instance
+  app.enq(t1)
   app.run
   
   runlist                  # => [t0, t1, t2]
-  app.results(t2)          # => ["input:one:two"]
-
-Tracking the evolution of a result through a workflow can get complex.  Tap
-audits workflows to help.  Setting the names of the tasks will identify them
-in an audit dump:
-
-  t1.name = 'un'
-  t2.name = 'deux'
-  
-  app._results(t2)[0].dump
-  # => 
-  # o-[] "input"
-  # o-[un] "input:one"
-  # o-[deux] "input:one:two"
+  results                  # => ["input:one:two"]
 
 == Apps
 
-==== 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.
+==== Tap::App::Queue
 
-  root = Tap::Root.new '/path/to/root'
-  root.root                                      # => '/path/to/root'
-  root['config']                                 # => '/path/to/root/config'
-  root.filepath('config', 'sample.yml')          # => '/path/to/root/config/sample.yml'
+http://tap.rubyforge.org/images/Queue.png
 
-While simple, this ability to alias paths is useful, powerful, and forms the
-basis of the Tap execution environment.
-
-==== Tap::Support::ExecutableQueue
-
-http://tap.rubyforge.org/images/ExecutableQueue.png
-
-Apps coordinate the execution of tasks through a queue.  The queue is just a
-stack of Executable objects, basically methods, and the inputs to those 
-methods; during a run the enqued methods are sequentially executed with the 
-inputs.
+Apps coordinate the execution of tasks 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 tasks.
+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.  Normally a script will only need and use a single instance (often
-Tap::App.instance), but there is no reason why multiple instances could not be
-used.  
+themselves.
 
-  log = StringIO.new
-  app = Tap::App.instance
-  app.logger = Logger.new(log)
-  app.logger.formatter = lambda do |severity, time, progname, msg|
-    "  %s %s: %s\n" % [severity[0,1], progname, msg]
-  end
-  
-  t = Tap::Task.intern {|task, *inputs| inputs }
-  t.log 'action', 'to app'
-  log.string                 # =>  "  I action: to app\n"
-  
+  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
-  app.results(t)             # => [[1], [2,3]]
-  
-As shown, apps also aggregate results for tasks, which is important for
-divergent workflows.
+  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
@@ -312,61 +287,54 @@ 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
-'sample_tasks' gem.
+'tap-tasks' gem.
 
   % tap manifest
   --------------------------------------------------------------------------------
-  Desktop:           (/Users/username/Desktop)
+  Desktop:          (/Users/username/Desktop)
   --------------------------------------------------------------------------------
-  sample_tasks:      (/Library/Ruby/Gems/1.8/gems/sample_tasks-0.10.0)
+  tap-tasks:        (/Library/Ruby/Gems/1.8/gems/tap-tasks-0.1.0)
     tasks
-      concat         (lib/tap/tasks/concat.rb)
-      copy           (lib/tap/tasks/copy.rb)
-      grep           (lib/tap/tasks/grep.rb)
-      print_tree     (lib/tap/tasks/print_tree.rb)
+      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.10.8)
-    generators
-      command        (lib/tap/generator/generators/command/command_generator.rb)
-      config         (lib/tap/generator/generators/config/config_generator.rb)
-      file_task      (lib/tap/generator/generators/file_task/file_task_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)
+  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)
-      server         (cmd/server.rb)
+      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/tasks/dump.rb)
-      load           (lib/tap/tasks/load.rb)
-      rake           (lib/tap/tasks/rake.rb)
+      dump          (lib/tap/dump.rb)
+      load          (lib/tap/load.rb)
   --------------------------------------------------------------------------------
 
   Desktop
-  |- sample_tasks 
+  |- tap-tasks 
   `- tap 
 
-In this printout of the manifest, you can see the resources available to tap on
-the Desktop (none), in the sample_tasks gem, and in tap itself.  Since there
-aren't any conflicts among tasks, the minipath of any of the tasks is sufficient
-for identification:
+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 -- print_tree
-  % tap run -- dump
+  % tap run -- load --: dump/yaml
   
 If there were a conflict, you'd have to specify the environment minipath like:
 
-  % tap run -- sample_tasks:print_tree
-  % tap run -- tap:dump
+  % tap run -- tap:load --: tap-tasks:dump/yaml
 
 ==== Tap::Exe
 
 http://tap.rubyforge.org/images/Run-Env.png
 
-Tap::Exe adds several configurations (ex before/after) which only get loaded
-for the present directory, and methods for building and executing workflows
-from command line inputs.
+Tap::Exe adds methods for building and executing workflows from command line
+inputs.