Class Reference in bahuvrihi-tap-0.12.0

- old
+ new

@@ -16,20 +16,18 @@
 
 Executable extends objects allowing them to be used in workflows, enqued, and run by an App.  Executable objects specify a method that gets called upon execution; in essence Executable wraps this method and adds workflow support for dependencies, joins, batches, and auditing.  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 (actually execute_with_callbacks is used to wrap process with before/after execute callbacks, but effectively this is the case).  Hence <tt>process</tt> is the standard method overridden in Task subclasses.
 
-==== Tap::Support::Configurable
+==== {Configurable}[http://tap.rubyforge.org/configurable/]
 
 http://tap.rubyforge.org/images/Configurable.png
 
-Configurable allows declaration of class configurations.  Configurable classes have a <tt>configurations</tt> method accessing a {ClassConfiguration}[link:classes/Tap/Support/ClassConfiguration.html] which holds all declared configs, their default values, and metadata for transforming configurations into command line options (for example).  
-
-Instances of a Configurable class have a <tt>config</tt> method accessing a {InstanceConfiguration}[link:classes/Tap/Support/InstanceConfiguration.html] object.  The instance configuration acts like a forwarding hash; read and write operations for declared configs get forwarded to class methods while undeclared configs are stored directly.  The writer for a config may be defined through a block provided during config declaration.  For instance:
-
+Tap uses the {Configurable}[http://tap.rubyforge.org/configurable/] module to declare class configurations and make them available in for use in contexts like the command line.  Configurations essentially consist of a reader, writer, and default value, but they may additionally be accessed through a hash-like config object.  For instance:
+  
   class ConfigClass
-    include Tap::Support::Configurable
+    include Configurable
 
     config :key, 'value' do |input|
       input.upcase
     end
     
@@ -50,11 +48,11 @@
     def initialize
       self.key = 'value'
     end
   end
 
-As you can see here:
+And as you can see here:
 
   c = ConfigClass.new
   c.key                       # => 'VALUE'
 
   c.config[:key] = 'new value'
@@ -63,16 +61,16 @@
   c.key = 'another value'
   c.config[:key]              # => 'ANOTHER VALUE'
 
 This setup is both fast and convenient.  
 
-==== Tap::Support::Validation
+==== {Configurable::Validation}[http://tap.rubyforge.org/configurable/classes/Configurable/Validation.html]
 
-When configurations are set from the command line, the writer method will inevitably receive a string, whereas configurations set within code can receive any type of object.  The {Validation}[link:classes/Tap/Support/Validation.html] module provides standard blocks for validating and transforming inputs, accessible through the <tt>c</tt> method (ex: <tt>c.integer</tt> or <tt>c.regexp</tt>).  These blocks (generally) load string inputs as YAML and validate that the result is the correct class; non-string inputs are simply validated.
+When configurations are set from the command line, the writer method inevitably receives a string, even though a non-string input may be desired.  The {Validation}[http://tap.rubyforge.org/configurable/classes/Configurable/Validation.html] module provides standard blocks for validating and transforming inputs, accessible through the <tt>c</tt> method (ex: <tt>c.integer</tt> or <tt>c.regexp</tt>).  These 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 Tap::Support::Configurable
+    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
@@ -87,13 +85,13 @@
 
   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.
 
-==== Tap::Support::Lazydoc
+==== {Lazydoc}[http://tap.rubyforge.org/lazydoc]
 
-Ah lazydoc.  Lazydoc fits into the space between live code and code documentation.  Lazydoc can scan a file (code or not) and pull documentation into the object space where it can be utilized.  Lazydoc uses a key-value syntax like this:
+Ah lazydoc.  {Lazydoc}[http://tap.rubyforge.org/lazydoc] fits into the space between live code and code documentation.  Lazydoc can scan a file (code or not) and pull documentation into the object space where it can be utilized.  Lazydoc uses a key-value syntax like this:
 
   # ::key value
 
 Lazydoc parses a constant name, the key, the value, and any comment following the value until a non-comment line or an end key.  For example:
 
@@ -110,14 +108,14 @@
   #
   # This does not.
 
   require 'tap'
 
-  lazydoc = Tap::Support::Lazydoc[__FILE__]
+  lazydoc = Lazydoc[__FILE__]
   lazydoc.resolve
 
-  lazydoc['Name::Space']['key'].to_s           # => "This documentation gets parsed."
+  lazydoc['Name::Space']['key'].comment        # => "This documentation gets parsed."
   lazydoc['Name::Space']['another'].value      # => "another value"
 
 Furthermore, Lazydoc can register specific lines for documentation.  These lines are parsed to echo what happens in RDoc.
 
   [another_lazydoc_file.rb]
@@ -126,11 +124,11 @@
   def method
   end
 
   require 'tap'
 
-  lazydoc = Tap::Support::Lazydoc[__FILE__]
+  lazydoc = Lazydoc[__FILE__]
   code_comment = lazydoc.register(2)
   lazydoc.resolve
   
   code_comment.subject         # => "def method"
   code_comment.to_s            # => "documentation for the method"
@@ -144,11 +142,11 @@
   #
   # This manifest is expected to apply to the Sample::Task class.
   # If more than one task is defined in this file, or if Sample::Task
   # is not defined by loading this file, Tap will run into trouble.
 
-However, the best practice is to include the namespace explicitly.
+However, the best practice is to include the namespace explicitly.  See the {Lazydoc}[http://tap.rubyforge.org/lazydoc] documentation for more information.
 
 === Tap::Task
 
 http://tap.rubyforge.org/images/Task.png
 
@@ -203,11 +201,11 @@
   t1.name = 'un'
   t2.name = 'deux'
   t3.name = 'trois'
   
   app._results(t2).collect do |_result|
-    _result._to_s
+    _result.dump
   end.join("---\n")
   # => 
   # o-[] "input"
   # o-[un] "input:one"
   # o-[deux] "input:one:two"
@@ -220,11 +218,11 @@
 
 ==== Tap::Root
 
 http://tap.rubyforge.org/images/Root.png
 
-A Root represents the base of a directory structure. Roots allow you to alias directories and ease working with filepaths, basically allowing you to develop code for a conceptual directory structure that can be defined later.
+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.filepath('config', 'sample.yml')          # => '/path/to/root/config/sample.yml'
@@ -246,11 +244,10 @@
 Tap tracks inputs as they are modified by various tasks, again through Executable.  At the end of a run, any individual result can be tracked back to it's original value with references to the source of each change (ie the task).  This auditing can be very useful when workflows diverge, as they often do.
 
 Auditing is largely invisible except in <tt>on_complete</tt> blocks.  <tt>on_complete</tt> blocks receive the audited results so that this information can be used, as needed, to make decisions.  
 
     Task.new.on_complete do |_result|            # _result is an Audit instance
-      _result._current                           # the current value
-      _result._original                          # the original value
+      _result.value                              # the current value
     end
 
 To help indicate when a result is actually a result and when it is an audit, Tap uses a convention whereby a leading underscore signals auditing is involved.
 
 ==== Tap::Support::Aggregator