tap 0.12.4 → 0.17.0

data/lib/tap/tasks/dump.rb

@@ -0,0 +1,58 @@
+require 'tap/task'
+
+module Tap
+  module Tasks
+    # :startdoc::task the default dump task
+    #
+    # Dumps data to $stdout or a file output.
+    #
+    #   % tap run -- dump content --output FILEPATH
+    #
+    # Dump faciliates normal redirection:
+    #
+    #   % tap run -- load hello --: dump | more
+    #   hello
+    #
+    #   % tap run -- load hello --: dump 1> results.txt
+    #   % more results.txt
+    #   hello
+    #
+    # Note that dumps are appended to the file.  Dump only accepts one object
+    # at a time, so joins that produce an array (like sync) need to iterate
+    # outputs to dump:
+    #
+    #   % tap run -- load hello -- load world -- dump --[0,1][2]i.sync
+    #   hello
+    #   world
+    #
+    # :startdoc::task-
+    #
+    # Dump serves as a baseclass for more complicated dumps.  A YAML dump
+    # (see {tap-tasks}[http://tap.rubyforge.org/tap-tasks]) looks like this:
+    #
+    #   class Yaml < Tap::Dump
+    #     def dump(obj, io)
+    #       YAML.dump(obj, io)
+    #     end
+    #   end
+    #
+    class Dump < Tap::Task
+      config :output, $stdout, &c.io(:<<, :puts, :print)   # The dump target file
+      config :overwrite, false, &c.flag                    # Overwrite the existing target
+    
+      # The default process prints dump headers as specified in the config,
+      # then append the audit value to io.
+      def process(input)
+        open_io(output, overwrite ? 'w' : 'a') do |io|
+          dump(input, io)
+        end
+        output
+      end
+    
+      # Dumps the object to io, by default dump puts (not prints) obj.to_s.
+      def dump(input, io)
+        io.puts input.to_s
+      end
+    end
+  end
+end

data/lib/tap/tasks/load.rb

@@ -0,0 +1,62 @@
+require 'tap/task'
+require 'stringio'
+
+module Tap
+  module Tasks
+    # :startdoc::task the default load task
+    #
+    # Loads data from $stdin.  String data may be passed directly.  Load
+    # is typically used as a gateway to other tasks.
+    #
+    #   % tap run -- load string --: dump
+    #   string
+    #
+    # Load facilitates normal redirection:
+    #
+    #   % echo goodnight moon | tap run -- load --: dump
+    #   goodnight moon
+    #
+    #   % tap run -- load --: dump < somefile.txt
+    #   contents of somefile
+    #
+    # :startdoc::task-
+    #
+    # Load serves as a baseclass for more complicated loads.  A YAML load
+    # (see {tap-tasks}[http://tap.rubyforge.org/tap-tasks]) looks like this:
+    #
+    #   class Yaml < Tap::Load
+    #     def load(io)
+    #       YAML.load(io)
+    #     end
+    #   end
+    #
+    class Load < Tap::Task
+      
+      config :file, false, &c.flag         # opens the input as a file
+      
+      # The default process simply reads the input data and returns it.
+      # See load.
+      def process(io=$stdin)
+        # read on an empty stdin ties up the command line;
+        # this facilitates the intended behavior
+        if io.kind_of?(IO) && io.stat.size == 0
+          io = '' 
+        end
+      
+        if io.kind_of?(String)
+          io = StringIO.new(io)
+        end unless file
+      
+        open_io(io) do |data|
+          load(data)
+        end
+      end
+    
+      # Loads data from the io; the return of load is the return of process.  By
+      # default load simply reads data from io.
+      def load(io)
+        io.read
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tap
 version: !ruby/object:Gem::Version 
-  version: 0.12.4
+  version: 0.17.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-23 00:00:00 -06:00
+date: 2009-05-25 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.4.1
+        version: 0.5.0
     version: 
 description: 
 email: simon.a.chiang@gmail.com
@@ -32,93 +32,50 @@ extra_rdoc_files:
 - README
 - MIT-LICENSE
 - History
+- doc/API
 - doc/Class Reference
-- doc/Command Reference
-- doc/Syntax Reference
-- doc/Tutorial
+- doc/Examples/Command Line
+- doc/Examples/Workflow
 files: 
 - cmd/console.rb
-- cmd/destroy.rb
-- cmd/generate.rb
 - cmd/manifest.rb
 - cmd/run.rb
-- bin/tap
 - lib/tap.rb
 - lib/tap/app.rb
+- lib/tap/app/node.rb
+- lib/tap/app/queue.rb
+- lib/tap/app/stack.rb
+- lib/tap/app/state.rb
 - lib/tap/constants.rb
+- lib/tap/tasks/dump.rb
 - lib/tap/env.rb
+- lib/tap/env/constant.rb
+- lib/tap/env/gems.rb
+- lib/tap/env/manifest.rb
+- lib/tap/env/minimap.rb
+- lib/tap/env/string_ext.rb
 - lib/tap/exe.rb
-- lib/tap/file_task.rb
-- lib/tap/generator/arguments.rb
-- lib/tap/generator/base.rb
-- lib/tap/generator/destroy.rb
-- lib/tap/generator/generate.rb
-- lib/tap/generator/generators/command/command_generator.rb
-- lib/tap/generator/generators/command/templates/command.erb
-- lib/tap/generator/generators/config/config_generator.rb
-- lib/tap/generator/generators/generator/generator_generator.rb
-- lib/tap/generator/generators/generator/templates/task.erb
-- lib/tap/generator/generators/generator/templates/test.erb
-- lib/tap/generator/generators/root/root_generator.rb
-- lib/tap/generator/generators/root/templates/MIT-LICENSE
-- lib/tap/generator/generators/root/templates/README
-- lib/tap/generator/generators/root/templates/Rakefile
-- lib/tap/generator/generators/root/templates/Rapfile
-- lib/tap/generator/generators/root/templates/gemspec
-- lib/tap/generator/generators/root/templates/test/tap_test_helper.rb
-- lib/tap/generator/generators/task/task_generator.rb
-- lib/tap/generator/generators/task/templates/task.erb
-- lib/tap/generator/generators/task/templates/test.erb
-- lib/tap/generator/manifest.rb
-- lib/tap/generator/preview.rb
+- lib/tap/join.rb
+- lib/tap/joins.rb
+- lib/tap/joins/switch.rb
+- lib/tap/joins/sync.rb
+- lib/tap/tasks/load.rb
 - lib/tap/root.rb
-- lib/tap/spec.rb
-- lib/tap/support/aggregator.rb
-- lib/tap/support/audit.rb
-- lib/tap/support/constant.rb
-- lib/tap/support/constant_manifest.rb
-- lib/tap/support/dependencies.rb
-- lib/tap/support/dependency.rb
-- lib/tap/support/executable.rb
-- lib/tap/support/executable_queue.rb
-- lib/tap/support/gems.rb
+- lib/tap/root/utils.rb
+- lib/tap/root/versions.rb
+- lib/tap/schema.rb
+- lib/tap/schema/parser.rb
+- lib/tap/schema/utils.rb
 - lib/tap/support/intern.rb
-- lib/tap/support/join.rb
-- lib/tap/support/joins.rb
-- lib/tap/support/joins/switch.rb
-- lib/tap/support/joins/sync_merge.rb
-- lib/tap/support/manifest.rb
-- lib/tap/support/minimap.rb
-- lib/tap/support/node.rb
-- lib/tap/support/parser.rb
-- lib/tap/support/schema.rb
-- lib/tap/support/shell_utils.rb
-- lib/tap/support/string_ext.rb
 - lib/tap/support/templater.rb
-- lib/tap/support/versions.rb
 - lib/tap/task.rb
-- lib/tap/dump.rb
-- lib/tap/load.rb
-- lib/tap/test.rb
-- lib/tap/test/assertions.rb
-- lib/tap/test/env_vars.rb
-- lib/tap/test/extensions.rb
-- lib/tap/test/file_test.rb
-- lib/tap/test/file_test_class.rb
-- lib/tap/test/regexp_escape.rb
-- lib/tap/test/script_test.rb
-- lib/tap/test/script_tester.rb
-- lib/tap/test/subset_test.rb
-- lib/tap/test/subset_test_class.rb
-- lib/tap/test/tap_test.rb
-- lib/tap/test/utils.rb
 - README
 - MIT-LICENSE
 - History
+- doc/API
 - doc/Class Reference
-- doc/Command Reference
-- doc/Syntax Reference
-- doc/Tutorial
+- doc/Examples/Command Line
+- doc/Examples/Workflow
 has_rdoc: true
 homepage: http://tap.rubyforge.org
 post_install_message: 
@@ -149,6 +106,6 @@ rubyforge_project: tap
 rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
-summary: A framework for creating configurable, distributable tasks and workflows.
+summary: A configurable, distributable workflow framework.
 test_files: []
 

data/cmd/destroy.rb

@@ -1,27 +0,0 @@
-# usage: tap destroy GENERATOR ...
-#
-# Runs a generator in reverse.  Each generator works a little differently; the
-# best way to figure out what a generator does is to use --help. For example:
-#
-#   % tap generate root --help
-#
-
-require 'tap/generator/base'
-require 'tap/generator/destroy'
-
-env = Tap::Env.instance
-
-if ARGV.empty? || ARGV == ['--help']
-  puts Lazydoc.usage(__FILE__)
-  puts
-  puts "generators:"
-  puts env.summarize(:generators)
-  exit
-end
-
-name = ARGV.shift
-const = env.generators.search(name) or raise "unknown generator: #{name}"
-
-generator_class = const.constantize
-generator, argv = generator_class.parse(ARGV)
-generator.extend(Tap::Generator::Destroy).process(*argv)

data/cmd/generate.rb

@@ -1,27 +0,0 @@
-# usage: tap generate GENERATOR ...
-#
-# Runs a generator.  Each generator works a little differently; the best way to
-# figure out what a generator does is to use --help. For example:
-#
-#   % tap generate root --help
-#
-
-require 'tap/generator/base'
-require 'tap/generator/generate'
-
-env = Tap::Env.instance
-
-if ARGV.empty? || ARGV == ['--help']
-  puts Lazydoc.usage(__FILE__)
-  puts
-  puts "generators:"
-  puts env.summarize(:generators)
-  exit
-end
-
-name = ARGV.shift
-const = env.generators.search(name) or raise "unknown generator: #{name}"
-
-generator_class = const.constantize
-generator, argv = generator_class.parse(ARGV)
-generator.extend(Tap::Generator::Generate).process(*argv)

data/doc/Command Reference

@@ -1,105 +0,0 @@
-= Command Reference
-
-Tap comes the tap executable.  For help on the command line, type:
-
-  % tap --help
-
-== console
-
-Console opens an irb session after loading the tap environment.  Console
-defines variables 'app' and 'env' referencing Tap::App.instance and
-Tap::Env.instance, for easy access.
-
-  % tap console
-  irb(main):001:0> app.log(:hello)
-    I[17:18:53]              hello
-  => true
-  irb(main):002:0>
-
-== generate/destroy
-
-Generate and destroy launch generator scripts, similar to those in 
-{Rails}[http://www.rubyonrails.org/].  By default Tap provides generators for:
-
-{command}[link:classes/Tap/Generator/Generators/CommandGenerator.html]:: a new command
-{config}[link:classes/Tap/Generator/Generators/ConfigGenerator.html]:: a static config file for the specified task
-{generator}[link:classes/Tap/Generator/Generators/GeneratorGenerator.html]:: a new generator
-{root}[link:classes/Tap/Generator/Generators/RootGenerator.html]:: the basic directory structure
-{task}[link:classes/Tap/Generator/Generators/TaskGenerator.html]:: a task class and test
-
-For example:
-
-  % 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 .
-
-Each generator works a little differently.  For help:
-
-  % tap generate --help
-  % tap generate <generator> --help
-
-== manifest
-
-Manifest prints a list of all resources (commands, tasks, generators, etc)
-available to tap.  Environments are listed in the same order as they are
-searched, and at the end a tree diagram is printed showing how the
-environments are nested.
-
-  % tap manifest
-  --------------------------------------------------------------------------------
-  Desktop:           (/Users/username/Desktop)
-  --------------------------------------------------------------------------------
-  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)
-      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)
-    commands
-      console        (cmd/console.rb)
-      destroy        (cmd/destroy.rb)
-      generate       (cmd/generate.rb)
-      manifest       (cmd/manifest.rb)
-      run            (cmd/run.rb)
-    tasks
-      dump           (lib/tap/tasks/dump.rb)
-      load           (lib/tap/tasks/load.rb)
-      rake           (lib/tap/tasks/rake.rb)
-  --------------------------------------------------------------------------------
-
-  Desktop
-  `- tap
-
-== 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.  The run syntax is detailed in the {Syntax Reference}[link:files/doc/Syntax%20Reference.html], but a couple 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 the run command can be
-specified before the first break.
-
-  % tap run --debug -- sample/task --key=value
-
-Here run receives the <tt>--debug</tt> option and sample/task receives the 
-<tt>--key=value</tt> option.  Inputs work the same way.  For example:
-
-  % tap run -- sample/task --key=value one -- another/task two three
-
-Specifies the following:
-
-  Sample::Task.new(:key => 'value').enq('one')
-  Another::Task.new.enq('two', 'three') 
-
-Any number of tasks, configurations, and inputs may be specified in this way.

data/doc/Syntax Reference

@@ -1,234 +0,0 @@
-= Syntax Reference
-
-Tap uses several domain-specific languages to declare tasks and workflows.
-This is a reference for:
-
-* class definitions
-* workflows
-
-== Task Classes
-
-This is a verbose prototype for Tap::Task subclasses:
-
-  # <ClassName>::manifest summary description
-  #
-  # Extended documentation...
-  #
-  class ClassName < Tap::Task
-    
-    # Sets up a configuration and makes the 'key' and 'key=' accessors.
-    # 
-    # This documentation appears in static config files, and in RDoc.
-    #
-    config :key, 'default value' do |value|  # config summary
-      "the config is set to the return value"
-    end 
-    
-    # Subclasses BaseClass with the specified configs, using the block
-    # to override process.
-    #
-    # Also creates the methods 'name', 'name_config', 'name_config='.  
-    # The first will access an instance-specific instance of the 
-    # subclass, the other two are accessors for the instance configs.
-    # 
-    # Primarily used in conjunction with workflow.
-    #
-    define :name, <BaseClass>, {<configs>} do |*args|
-      # this is the process block
-    end
-    
-    # Causes each instance to depend on DependencyClass.instance.
-    #
-    # Also defines a reader 'name' which will access the results
-    # of the dependency.
-    depends_on :name, <DependencyClass>
-    
-    def process(*args)
-      # the method defining what this task does 
-    end
-    
-    protected
-
-    def workflow
-      # a hook to setup joins between various tasks used
-      # by the current instance.  workflow is called
-      # during initialize
-    end
-
-    def before_execute() 
-      # a hook to execute code before process
-      # (only works in workflows)
-    end
-  
-    def after_execute()
-      # a hook to execute code after process
-      # (only works in workflows)
-    end
-
-    def on_execute_error(err)
-      # a hook to handle errors during process
-      # (only works in workflows)
-    end
-  end
-
-== Workflows
-
-The tap workflow syntax is designed to specify an arbitrary number of tasks,
-inputs, configurations, and joins.  The syntax works both as text and as YAML;
-'tap run' uses it to specify which tasks to execute.  Basically, the syntax
-uses double-dash delimiters to separate task vectors and modified delimiters
-to specify joins for the tasks.  
-
-These both specify three tasks (x,y,z) joined in a sequence:
-
-  % tap run -- x --: y --: z
-  % tap run -- x -- y -- z --0:1:2
-  
-The modified delimiters use numbers to indicate which tasks participate in a
-join and punctuation to indicate the join type.  In the first example, the
-numbers are implicitly added for the preceding and following task.  A variety
-of joins are supported:
-
-  delimiter  function         syntax                 example        meaning 
-  --         delimiter                               a -- b -- c    enques/configures tasks a, b, c
-  --*        dependency                              --* a          enques dependency instance
-  --+        round                                   --+ a --++ b   enques a to round one, b to round two
-  --+[]      round shorthand  +round[targets]        --+2[0,1]      enques (a,b) to round two
-  
-  --:        sequence         source:target          --0:1:2        sequence a, b, c
-  --[]       fork             source[targets...]     --0[1,2]       fork a to (b,c)
-  --{}       merge            target{sources...}     --2{0,1}       merge (a,b) to c
-  --()       sync_merge       target(sources...)     --2(0,1)       synchronize merge (a,b) to c
-
-Inputs may be specified between delimiters:
-
-  % tap run -- x alpha beta --: y gamma --: z delta
-
-As may be configurations, in a variety of formats:
-
-  % tap run -- x alpha beta -k --: y gamma --key value --: z delta --key=value
-  
-These are the corresponding task vectors:
-
-  ['x', 'alpha', 'beta', '-k']
-  ['y', 'gamma', '--key', 'value']
-  ['z', 'delta', '--key=value']
-
-This is how it would look as YAML:
-
-  - - x
-    - alpha
-    - beta
-    - -k
-  - - y
-    - gamma
-    - key: value
-  - - z
-    - delta
-    - --key=value
-  - 0:1:2
-
-The task vectors are converted into a task and an argument vector by first
-looking up a task class and then calling TaskClass.parse.  The parse method
-returns a configured instance of the task and an argv to be executed by the
-task.  Once the task are instantiated, instances are joined and enqued to
-Tap::App for execution (see Tap::Support::Schema#build).
-
-==== Class Lookup
-
-Tap looks up classes via Tap::Env.  Tap can find tasks from multiple
-environments; by adding in environments for gems, Tap can find tasks
-within a gem.
-
-During lookup, classes are treated like filepaths which match from the
-basename up:
-
-  class             lookup              matched by
-  Sample::Task      sample/task         task, sample/task
-  A::Nested::Task   a/nested/task       task, nested/task, a/nested/task
-
-In the event of a name conflict, the path of the environment may also be
-specified.  It seems like this could get confusing, but the tap executable
-produces manifests that specify the minimal path required to uniquely
-identify a class.  Fragments of the minimized paths will be resolved in order
-from top to bottom within the specified environment.  For example: 
-
-  % tap run -T
-  one:
-    sample/task      # some sample task
-    another/task     # another task
-  two:
-    sample/task      # a conflicting sample task
-
-Runs the 'one' sample/task:
-
-  % tap run -- sample/task
-  % tap run -- one:sample/task
-
-Runs the 'two' sample/task:
-
-  % tap run -- two:sample/task
-
-Runs the 'one' sample/task:
-
-  % tap run -- task
-
-Runs the 'two' sample/task:
-
-  % tap run -- two:task
-
-Runs another/task:
-
-  % tap run -- another/task
-  % tap run -- one:another/task
-
-Notice that the full minimized path ('another/task') is required because simply
-using 'task' will be matched to sample/task.  The order of tasks is obviously
-not alphabetical -- rather it corresponds to the order in which Tap::Env
-discovers the tasks.
-
-==== Dependencies (--*)
-
-Normally each task vector specifies a new instance of a task.  This specifies
-three instance of the 'a' task.
-
-  % tap run -- a -- a -- a
-  
-When you want to specify a 'singleton' instance of a task, the instance
-specified by TaskClass.instance, use the dependency delimiter '--*'.  
-
-  % tap run --* a
-  
-The dependency instance will be configured and enqued with the arguments.
-Dependency instances will be executed first, even if they are specified at the
-end of a workflow, they cannot participate in workflows, and any single
-dependency may only be specified once in a workflow.  These are equivalent:
-
-  % tap run --* a -- b -- c
-  % tap run b -- c --* a
-
-While these raise errors:
-
-  % tap run --* a --* a
-  % tap run --* a --: b
-
-==== Rounds (--+)
-
-The workflow syntax allows multiple execution rounds to be specified  All tasks
-in a round are run to completion before the next round begins.  Rounds are
-specified by adding '+' characters after the double-dash break.
-
-  % tap run -- round_one_task --+ round_two_task
-
-Tasks may be added to rounds in any order and may use the shorthand for multiple
-tasks.  These are equivalents:
-
-  % tap run -- a --+ b --+ c --++ d
-  % tap run --+ b --++ d -- a --+ c
-  % tap run -- a -- b -- c -- d --+1[1,2] --+2[3]
-
-Rounds are particularly useful for dump tasks; add a dump task as a final round
-to capture all results from previous rounds:
-
-  % tap run -- task -- task --+ dump
-