tap 0.19.0 → 1.3.0

data/bin/tapexe

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+# usage: tap [workflow] [--- tapfile] [-d-]
+#
+# workflow:
+#   [break] [left:]right [ARGS...]   Constants are identified by matching the
+#                                    left and right paths; all subsequent args
+#   example:                         are passed to the constant. Breaks delimit
+#   tap:load -> Tap::Tasks::Load     and the syntax repeats.
+#
+# breaks:
+#   -                                Delimiter, separates object argvs
+#   --                               Delimits argvs and enques the next object
+#   -:[qai][.class]                  Sequence - joins previous and next objects
+#   -/obj[/sig]                      Signal - enques signal with argv
+#   --/obj[/sig]                     Signal - executes signal with argv
+#   -@ obj                           Enque  - enques obj with argv
+#   -! obj                           Execute - executes obj with argv
+#   -. .-                            Escape begin/end
+#   ---                              End workflow
+#
+# env:
+#   TAP_GEMS                         Gem patterns to match and register
+#   TAP_PATH                         Directory paths to register
+#   TAPENV                           Signal files for env
+#   TAPRC                            Signal files for app
+#   TAPFILE                          Declaration files
+#
+# examples:
+#   tap load str -: dump             A simple sequence workflow
+#   tap load str - dump - join 0 1   Manually build the join
+#   tap --/use debugger -d-          Debugging utilities
+#   tap prompt                       Open a prompt
+#   tap list                         List resources
+#
+
+require 'tap'
+require 'tap/parser'
+
+begin
+  options = Tap.options
+  
+  if ARGV[-1] == '-d-'
+    ARGV.pop
+    options[:debug] = 'true'
+  end
+  
+  if ARGV == ['--help']
+    puts Lazydoc.usage(__FILE__)
+    puts "\nversion #{Tap::VERSION} -- #{Tap::WEBSITE}"
+    exit(0)
+  end
+  
+  app = Tap.setup(options)
+  parser = Tap::Parser.new
+  
+  loop do
+    break if ARGV.empty?
+    parser.parse!(ARGV)
+    parser.build_to(app)
+  
+    break if ARGV.empty?
+    config_parser = ConfigParser.new(app.config, 
+      :option_break => Tap::Parser::BREAK, 
+      :keep_break => true, 
+      :clear_config => false, 
+      :add_defaults => false)
+    config_parser.add(app.class.configurations)
+    
+    config_parser.scan(ARGV) do |file|
+      app.call('sig' => 'load', 'args' => [file])
+    end
+  end
+  
+  app.run
+rescue
+  if $DEBUG || options[:debug]
+    raise $!
+  end
+  $stderr.puts $!.message
+  exit(1)
+end
+
+exit(0)

data/doc/API

@@ -1,70 +1,71 @@
-= Application Programming Interface
+= Application Programming Interfaces
 
-Applications require the following methods for nodes, joins, and middleware.
-Tap provides modules and base classes that implement these APIs.
+All of the objects used by tap have two APIs -- one regarding the specific
+type of object (ex a task, a join, or middleware), and another regarding how
+applications find and use the objects. These APIs allow users to make custom
+objects.
 
-=== {Node}[link:classes/Tap/App/Node.html] ({Task}[link:classes/Tap/Task.html])
+== Object Interface
 
-  call(*inputs)    # any return is allowed
-  joins()          # returns an array of joins, or nil (optional)
+Applications require the following methods for tasks, joins, and middleware.
+Tap provides base classes that implement these APIs. Objects satisfying the
+task, join, or middleware API are referred to as workflow objects.
 
-The signature for call defines the arguments that must be enqued to the node
-or passed to the node via a join. All signature constructs are allowed
-including multiple arguments, default arguments and splats (blocks are
-technically allowed but will never receive a value).
+=== {Task}[link:classes/Tap/Task.html]
 
-The optional joins method specifies an array of joins to be called by a
-running application when the node completes. Each join is called in order. An
-empty array specifies the default application joins should be called; nil
-specifies that no joins should be called. No joins will be called when joins
-is left undefined.
+  call(input)                    # any return is allowed
+  joins()                        # returns an array of joins, or nil (optional)
+
+The call method takes an object and returns an object. There are no formal
+constraints for the input/output objects. The optional joins method returns an
+array of joins to be called when the task completes, or nil if no joins are to
+be called. Each join is called in order.
 
 === {Join}[link:classes/Tap/Join.html]
 
-  call(result)     # any return is allowed
+  call(output)                   # any return is allowed
 
-The call method receives the result of input nodes. The result of call is not
-used; call must internally performing the join actions.
+The call method receives the output of a task. The result of call is not used;
+call internally performs the join actions.
 
 === {Middleware}[link:classes/Tap/Middleware.html]
 
   Middleware.new(stack, *args)   # returns an instance of middleware
-  call(node, inputs=[])          # any return is allowed
+  call(node, input)              # return is the task output
   stack()                        # returns the original stack
 
-Middleware wraps the execution of nodes. Nodes and inputs are passed to the
-middleware during execution; the middleware is responsible for processing the
-node or passing it into the stack using the same call API. By default the base
-stack invokes call on the node with the inputs. Joins are performed after the
-middleware returns.
+Middleware wraps the execution of tasks. Tasks and inputs are passed to the
+middleware during execution. Joins are performed with the call output.
+
+== {Application Interface}[link:classes/Tap/App/Api.html]
+
+Tap defines an interface allowing applications to create and manage objects
+using signals. The application interface is distinct from the workflow APIs,
+although typically one will be implemented on top of the other. Objects
+satisfying the application interface are referred to as application objects.
 
-== Application Interface
+The application interface allows instantiation of a class from a hash and
+serialization of an instance back into a hash. The hash is referred to as a
+specification and must be serializable as {JSON}[http://json.org/] (meaning
+the hash must consist of simple object types: numbers, strings, hashes, and
+arrays).
 
-In addition to the APIs for individual workflow objects, Tap defines an
-application interface allowing objects to be created and modified using
-signals sent to an application (think HTTP to a web app). Signals are simple
-hash constructs and typically form the basis for user interfaces. The
-application interface is distinct from the object APIs, although it is typical
-to implement the application interface on top of an object API.
+The application interface consists of two methods:
 
-Tap::App::Api implements the application interface in a general way and is the
-baseclass for Tap::Task, Tap::Join, and Tap::Middleware. The basic idea is to
-allow instantiation of a class from a hash and serialization of an instance
-back into a hash. The hash is referred to as a specification and must be
-serializable as {JSON}[http://json.org/], basically meaning the hash must
-consist of simple object types: numbers, strings, hashes, and arrays.
+  Const.build(spec, app)         # returns an instance of self
+  to_spec                        # returns a spec
 
-The application interface consists of two methods, build and to_spec:
+As an example:
 
-  class Stub
+  class Example
     class << self
-      # Build takes a specification hash and returns an instance of self.
+      # Build takes a specification and returns an instance of self.
       # The spec must be serializable as JSON.
-      def build(spec={}, app=Tap::App.instance)
+      def build(spec={}, app=Tap::App.current)
       end
     end
     
-    # Takes no inputs and returns a specification hash that, when built,
+    # Takes no inputs and returns a specification that, when built,
     # returns an object like self.
     #
     #   obj.class.build(obj.to_spec)      # => returns an object like obj
@@ -74,22 +75,29 @@ The application interface consists of two methods, build and to_spec:
     end
   end
 
-The application API reserves several additional methods that do not need to be
-implemented but add functionality for specific, common use cases. If they are
-present they must adhere to these specifications.
+The application interface reserves several additional methods that do not need
+to be implemented but add functionality for specific, common use cases. These
+are:
+
+  Const.parse(argv, app)         # returns an instance of self, cannot modify ARGV
+  Const.parse!(argv, app)        # same as parse but can modify ARGV
+  signal(sig)                    # returns an object responding to call
+  associations                   # returns an array like [refs, brefs]
+
+If present they must do the following:
 
-  # Optional methods #
-  class Stub
+  class Example
     class << self
-      # Parse takes an argument vector (an array, usually from the command
-      # line) and returns an instance of self and any remaining arguments
-      # in an array like [instance, args].  The remaining arguments may be
-      # nil.  Parse cannot modify argv.
-      def parse(argv=ARGV, app=Tap::App.instance)
+      # Takes an argument vector (an array, usually from the command line)
+      # and returns an instance of self.  If a block is given, parse
+      # yields the instance and remaining args and returns block result.
+      #
+      # Parse should not modify argv.
+      def parse(argv=ARGV, app=Tap::App.current)
       end
       
       # Same as parse, but able to modify argv.
-      def parse!(argv=ARGV, app=Tap::App.instance)
+      def parse!(argv=ARGV, app=Tap::App.current)
       end
     end
     
@@ -98,18 +106,17 @@ present they must adhere to these specifications.
     def signal(sig)
     end
     
-    # Returns a nested array of workflow objects associated with self (ex 
-    # input/output nodes for a join).  The array should be structured like
-    # [refs, brefs], where refs are references to objects that must be built
-    # BEFORE self and brefs are back-references to objects that must be built
-    # AFTER self.
+    # Returns a nested array of application objects associated with self.
+    # The array should be structured like [refs, brefs], where refs are
+    # references to objects that must be built BEFORE self and brefs are
+    # back-references to objects that must be built AFTER self.
     #
-    # For example, nodes must be built before joins.  As such, the associations
-    # method for a node returns a brefs for each of its joins. Similarly, joins
-    # must be built after nodes and hence the associations method for a join
-    # returns refs to their input and output nodes:
+    # For example, tasks must be built before joins.  As such, the associations
+    # method for a task returns a brefs for each of its joins. Similarly, joins
+    # must be built after tasks and hence the associations method for a join
+    # returns refs to their input and output tasks:
     #
-    #   node.associations       # => [nil, join]
+    #   task.associations       # => [nil, join]
     #   join.associations       # => [inputs + outputs, nil]
     #
     # Nil is a valid return for associations, indicating no associations.
@@ -118,7 +125,7 @@ present they must adhere to these specifications.
   end
 
 The parse methods are used for building objects from interfaces that provide
-an array of inputs (ex the command line) rather a hash; without them objects
+an array of inputs rather a hash (ex the command line); without them objects
 are effectively excluded from use within these interfaces.
 
 Signals can be used to interact with specific objects from a user interface
@@ -128,96 +135,41 @@ cannot receive signals.
 The associations method is used to order complex builds and is described in
 more detail below.
 
-=== Spec References
+=== Object References
 
-Specifications often require references to other resources, as when a join
-refers to input and output nodes. These references are normally specified as
-variables that, unlike the resource itself, are easily serializable as JSON
-and may be used in multiple places. Apps are constructed to do this easily via
-the +obj+ and +var+ methods.
+Specifications often require references to other application objects, as when
+a join refers to input and output tasks. These references are normally
+specified as variables that, unlike the object itself, are serializable as
+JSON. Apps manage variables via the +obj+ and +var+ methods.
 
-As an example, consider the Sample class that references some other
-application object:
+As an example:
 
-  class Sample
-    def initialize(object)
-      @object = object
+  class A
+    def initialize(b)
+      @b = b
     end
 
     def to_spec
-      {'key' => app.var(@object)}        # store a variable into the spec
+      {'b' => app.var(@b)}       # store a variable into the spec
     end
 
     def associations
-      [[@object], nil]                   # establish a build order
+      [[@b], nil]                # establish a build order
     end
     
     class << self
-      def build(spec={}, app=Tap::App.instance)
-        object = app.obj(spec['key'])    # retrieve an object referenced by the spec
-        new(object)
+      def build(spec={}, app=Tap::App.current)
+        b = app.obj(spec['b'])   # retrieve an object referenced by the spec
+        new(b)
       end
     end
   end
 
-Using this technique the spec will have a serializable variable representing
-the object and the app will be able to properly schematize and rebuild the
-instance and all its references. Apps use the associations array to determine
-the correct build order for the references. In the example the @object
-reference must be built before the Sample instance and correspondingly the
-associations method returns @object in the 'ref' array.
+The to_spec method records a variable identifying @b, rather than @b itself,
+which allows the spec to be properly serialized. Likewise the build method
+de-references the variable to retrieve b when initializing a new instance; the
+associations array is used to ensure that b is built by the time A.build tries
+to de-reference the variable.
 
 Note that only references to objects implementing the application interface
-may be stored this way; references to objects that do not implement the
-application interface must be serialized and deserialized by the build/to_spec
-methods internally.
-
-=== Resource Identifiers
-
-Tap discovers application resources using resource identifiers (ie constant
-attributes, see {Lazydoc}[http://tap.rubyforge.org/lazydoc]). Resources
-identified in this way can be automatically loaded by the Tap::Env. If no
-identifiers are specified for a resource, the user must manually load the
-resource files.
-
-As an example, this identifies the Sample constant as an 'example' resource.
-
-  [lib/file.rb]
-  
-  # Sample::example summary
-  class Sample
-  end
-
-A resource can be identified by zero or more identifiers. Typically all
-identifiers will be put in the same file as the class, but this does not have
-to be the case; applications automatically require all files that identify a
-resource. The order in which the files are required is indeterminate and it is
-up to the user to ensure consistency. For example:
-
-  [a.rb]
-  # Sample::a
-  class Sample
-  end
-  
-  [b.rb]
-  require 'a'
-
-  # Sample::b
-  class Sample
-  end
-
-Here the require statement ensures a.rb is always required before b.rb. Note
-that consistency is automatic when all identifiers are in the same file (and
-thus only one file is required).
-
-The constant name will be inferred from file path if no constant name is
-specified. This is the most compact form for identifying a resource:
-
-  [lib/sample.rb]
-  
-  # ::example summary
-  class Sample
-  end
-
-In this case no constant name is specified, so 'Sample' is inferred from
-'sample.rb'. Constant names are determined from the path using camelization.
+should be stored this way.

data/doc/Configuration

@@ -0,0 +1,93 @@
+= Configuration
+
+Configuring tap is a matter of setting ENV variables that tell the executable
+what to make available to workflows. Each of the ENV variables can be treated
+like PATH, where multiple paths may be joined by a colon. The config files
+specified in the ENV are handled in order as listed, before the command line
+workflow is parsed.
+
+=== TAP_GEMS (default '.')
+
+Specifies globs of gems to automatically load into the environment. Versions
+can be specified as normal, separated by a comma. Use an empty string to
+specify no gems.
+
+  % gem install tap-tasks
+  % TAP_GEMS=. tap inspect a b c
+  ["a", "b", "c"]
+  % TAP_GEMS=tap-ta* tap inspect a b c
+  ["a", "b", "c"]
+  % TAP_GEMS='tap-tasks, >= 0.6.0' tap inspect a b c
+  ["a", "b", "c"]
+  % TAP_GEMS=nomatch tap inspect a b c
+  unresolvable constant: "inspect"
+  % TAP_GEMS= tap inspect a b c
+  unresolvable constant: "inspect"
+
+Note that all matching gems will be activated when tap launches.
+
+=== TAP_PATH (default '.')
+
+Specifies directories to be scanned and registered with the tap env. All files
+matching TAP_PATH/lib/**/*.rb will be scanned for constants; TAP_PATH itself
+will be registered as a path in env. If TAP_PATH/tap.yml exists, it will be
+loaded as a map of paths.
+
+As a shorthand, just know that any constants under the lib directory of
+TAP_PATH will be discovered.
+
+  [dir/lib/goodnight.rb]
+  require 'tap/task'
+  
+  # ::task
+  class Goodnight < Tap::Task
+    def process(input)
+      puts "goodnight #{input}"
+    end
+  end
+  
+  % tap goodnight moon
+  unresolvable constant: "goodnight"
+  % TAP_PATH=dir tap goodnight moon
+  goodnight moon
+  
+=== TAPENV (default 'tapenv')
+
+Specifies signal files to be loaded in the env signaling context. These files
+can be used to manually adjust an environment by setting/unsetting constants
+and resource paths.
+
+  [tapenv]
+  unset Tap::Tasks::Dump
+  
+  % tap load a -: dump
+  unresolvable constant: "dump"
+
+=== TAPRC (default '~/.taprc:taprc')
+
+Specifies signal files to be loaded in the app signaling context. These files
+can be used to manually build workflows, or configure the app.
+
+  [taprc]
+  set loader load
+  set dumper dump
+
+  % tap - join loader dumper -/enq loader 'goodnight moon'
+  goodnight moon
+
+=== TAPFILE (default 'tapfile')
+
+Specifies ruby files that will be executed in the app context (ie using the
+binding of the app instance). Tapfiles can be used to declare tasks, typically
+using the Tap::Declarations module, or to manually setup workflows.
+
+  [tapfile]
+  require 'tap/declarations'
+  extend Tap::Declarations
+  
+  task :goodnight do |config, args|
+    "Goodnight #{args}!"
+  end
+
+  % tap goodnight Moon -: dump
+    Goodnight Moon!