rap 0.12.3 → 0.13.0

data/History

@@ -1,3 +1,10 @@
+== 0.13.0 / 2009-05-25
+
+Updates to use Tap-0.17.0.
+
+* added Test task
+* added Manifest task
+
 == 0.12.3 / 2009-03-23
 
 Update executable to use Tap-0.12.4.  No significant changes.

data/README

@@ -1,7 +1,7 @@
 = {Rap (Rakish App)}[http://tap.rubyforge.org/rap]
 
   rap v. a quick, sharp knock or blow
-  rakish adj. having a dashing, jaunty, or slightly disreputable quality or appearance
+  rak.ish adj. having a dashing, jaunty, or slightly disreputable quality or appearance
 
 A rakish extension to {Tap}[http://tap.rubyforge.org/rdoc].
 
@@ -20,16 +20,13 @@ Check out these links for documentation, development, and bug tracking.
 
 == Usage
 
-Usage is much like {rake}[http://rake.rubyforge.org/]:
+Usage is much like {Rake}[http://rake.rubyforge.org/]:
 
   [Rapfile]
-  require 'rap/declarations'
-  include Rap::Declarations
-  
-  desc "your basic goodnight moon task"
   
+  # ::desc your basic goodnight moon task
   # Says goodnight with a configurable message.
-  task(:goodnight, :obj, :message => 'goodnight') do |task, args|
+  Rap.task(:goodnight, :obj, :message => 'goodnight') do |task, args|
     puts "#{task.message} #{args.obj}\n"
   end
   
@@ -52,13 +49,14 @@ Now from the command line:
           --message MESSAGE
 
   options:
-      -h, --help                       Print this help
-          --name NAME                  Specify a name
-          --use FILE                   Loads inputs from file
+          --help                       Print this help
+          --name NAME                  Specifies the task name
+          --config FILE                Specifies a config file
 
 For testing, load the Rapfile and access the task as a constant.
 
   [test.rb]
+  require 'rap'
   load 'Rapfile'
   require 'test/unit'
   require 'stringio'
@@ -86,19 +84,39 @@ The test passes:
   1 tests, 2 assertions, 0 failures, 0 errors
 
 Generally speaking, the rap executable is a shorthand for 'tap run --' so you
-can use rap to quickly launch workflows as well.  See the 
-{Command}[link:files/doc/Command%20Reference.html] and 
-{Syntax}[link:files/doc/Syntax%20Reference.html] References for more information.
+can use rap to launch workflows as well.
+
+== Limitations
+
+Rap is not a pure replacement of Rake, nor do the Rap tasks behave exactly
+like standard Tap tasks.
+
+==== Regarding Rake:
+
+* Rap does not support builds by default
+* Classes like FileList are not available
+* Namespace lookup is slightly different (see the {Syntax Reference}[link:files/doc/Syntax%20Reference.html])
+
+That said, many rakefiles can be renamed as rapfiles and they'll work with
+minor and sometimes no changes.
+
+==== Regarding Tap
+
+Rap tasks (ie subclasses of Rap::DeclarationTask) are designed to behave like
+Rake tasks. As such Rap tasks:
 
-=== Limitations
+* return nil and pass nil in workflows 
+* only execute once
+* are effectively singletons
 
-Rap is not a pure replacement of Rake.  Rap does not support builds by default,
-classes like FileList are not included, and namespace lookup is slightly
-different (see the {Syntax Reference}[link:files/doc/Syntax%20Reference.html]).
+This makes rap tasks useful in dependency-based workflows but fairly useless
+in imperative workflows. However, other tasks behave as normal and any
+workflow you can run with 'tap run' can be run without alteration by rap.
 
 == Installation
 
-Rap is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+Rap is available as a gem on RubyForge[http://rubyforge.org/projects/tap].
+Use:
 
   % gem install rap
 

data/bin/rap

@@ -2,20 +2,14 @@
 # usage: rap taskname {options} [args] [-d-]
 
 $:.unshift "#{File.dirname(__FILE__)}/../lib"
-require 'rap/declarations'
+require 'rap'
 
 # setup the environment
 begin
   
-  env = Tap::Exe.setup(ARGV)
-  env.unshift(Rap::Declarations.env)
-  
-  Dir.glob('[TtRr]apfile{,.rb}').each do |task_file|
-    task_file  = File.expand_path(task_file)
-    next unless File.file?(task_file)
-    
-    env.loads.unshift(task_file)
-  end
+  env = Tap::Exe.setup
+  Rap::Declarations.env = env
+  env.activate
   
 rescue(Tap::Env::ConfigError)
   # catch errors and exit gracefully
@@ -24,92 +18,58 @@ rescue(Tap::Env::ConfigError)
   exit(1)
 end
 
-#
-# setup after script
-#
-
-at_exit do
-  begin
-    eval(env.after) if env.after != nil
-  rescue(Exception)
-    puts "Error in after script."
-    env.handle_error($!)
-    exit(1)
-  end
-end
-
-#
-# run before script
-#
-
-begin
-  eval(env.before) if env.before != nil
-rescue(Exception)
-  puts "Error in before script."
-  env.handle_error($!)
-  exit(1)
-end 
-
 #
 # run rap
 #
 
-module Rap
-  autoload(:Rake, 'rap/rake')
+Dir.glob('[TtRr]apfile{,.rb}').each do |rapfile|
+  next unless File.file?(rapfile)
+  load rapfile
 end
 
-begin
-  env.activate
+case ARGV[0]
+when '--help', nil, '-T'
   
-  case ARGV[0]
-  when '--help', nil, '-T'
-    rap_template = %Q{<% if count > 1 && !entries.empty? %>
-<%= env_name %>:
+  # same as normal summarize, but pass over tasks that have no comment
+  summary_template = %Q{<% entries.delete_if {|key, const| const.comment.kind_of?(Rap::Description) && const.comment.resolve.desc == nil } %>
+<% if !entries.empty? && count > 1 %>
+<%= env_key %>:
 <% end %>
-<% entries.each do |name, const| %>
-<%   desc = if const.require_path == nil # should be a declaration %>
-<%     manifest = const.constantize.manifest %>
-<%     next if manifest == nil || manifest.empty? %>
-<%     manifest %>
-<%   else %>
-<%     const.document[const.name]['manifest'] %>
-<%   end %>
-  <%= name.ljust(width) %><%= desc.empty? ? '' : '  # ' %><%= desc %>
-<% end %>}
-
-    puts Lazydoc.usage(__FILE__)
-    puts
-    puts "===  tap tasks ==="
-    puts env.summarize(:tasks, rap_template)
+<% entries.each do |key, const| %>
+  <%= key.ljust(width) %> # <%= const.comment %>
+<% end %>
+}
+  
+  puts Lazydoc.usage(__FILE__)
+  puts
+  puts "===  tap tasks ==="
+  puts env.manifest(:task).summarize(summary_template)
+  
+  if Rap::Rake.has_rakefile?
     puts
     puts "=== rake tasks ==="
-    Rap::Rake.new.enq('-T')
-    Tap::App.instance.run
-    
-    # this is not currently reached as rake exits on -T
-    puts
-    puts "version #{Tap::VERSION} -- #{Tap::WEBSITE}"
-    exit
-  else
-    app = Tap::App.instance
-    schema = Tap::Support::Schema.parse(ARGV)
-    ARGV.clear
-    env.build(schema, app) do |args|
-      warn "warning: implict rake for [#{args.join(' ')}]"
-      Rap::Rake
-    end
-
-    if app.queue.empty?
-      puts "no task specified"
-      exit
-    end
-
-    env.set_signals
-    app.run
+    Rap::Rake.new.execute('-T')
   end
   
-rescue
-  env.handle_error($!)
+  puts
+  puts "version #{Tap::VERSION} -- #{Tap::WEBSITE}"
+else
+  begin
+    schema = Tap::Schema.parse(ARGV)
+    env.run(schema) do |type, key, metadata|
+      if type == :task && Rap::Rake.has_rakefile?
+        warn "warning: implict rake for '#{metadata.join(' ')}'"
+        metadata.unshift(key)
+        Rap::Rake
+      else
+        nil
+      end
+    end
+  rescue
+    raise if $DEBUG
+    puts $!.message
+    exit(1)
+  end
 end
 
 exit(0)

data/doc/Syntax Reference

@@ -4,13 +4,7 @@
 
 A task declaration:
 
-  # name::           the name of the task, either alone or as the
-  #                  key of a {key => dependencies} hash
-  # dependencies::   an array of task names (optional)
-  # arg_names::      an array of argument names (optional)
-  # configurations:: a hash of {key => default} pairs (optional)
-
-  task({<name> => [<dependencies...>]}, <arg_names...>, {<configs>}) do |task, args|
+  task(<name>, <arg_names...>, {<configs>}) do |task, args|
     # arguments are available through args:
     args.arg_name
     
@@ -18,6 +12,10 @@ A task declaration:
     task.key
   end
 
+A task declaration with dependencies:
+
+  task({<name> => [<dependencies...>]}, <arg_names...>, {<configs>}) { task ... }
+
 A namespace declaration:
 
   namespace(<name>) { task ... }
@@ -39,19 +37,19 @@ Extended documentation:
   # Lines are justified and wrapped on the command line.
   task ...
 
-Pains were taken to make task declarations for rap work the similar to rake
-tasks.  In both cases (noting that in general, beyond rap, task classes are
-not limited in these ways):
+Pains were taken to make task declarations for Rap work the similar to Rake
+tasks. For both Rake and Rap (noting that in general task classes are not
+limited in these ways):
 
 * tasks are singleton instances that may be extended across multiple
   declarations
 * tasks do not pass inputs from one task to the next
 * tasks only execute once
 
-A few syntactical differences between rake and rap must to be noted, as they
-can cause errors if you try to migrate rake tasks to tap.
+A few syntactical differences between Rake and Rap must to be noted, as they
+can cause errors during migration.
 
-==== no needs
+==== No :needs
 
 Rap does not support :needs as a way to specify dependencies.  For instance,
 this will declare a ':needs' configuration with the default value ':another',
@@ -59,24 +57,34 @@ not a task which depends on another:
 
   Rap.task :name, :needs => :another
 
-==== immediate namespace lookup
+==== Namespace Lookup
 
-Within a namespace, task will look for a literal match to the dependency first.
-If it doesn't find one, it will declare it within the namespace; one way or the
-other the dependency is resolved to a constant immediately.  Hence, in this
-example the nested task depends on the non-nested task.  
+Rap immediately resolves dependencies relative to the top level namespace,
+which is very different from Rake. Rake waits to resolve dependencies and will
+use a match within a namespace if it becomes available. For these tasks rap
+and rake produce different results:
 
-  task :outer { print 'non-nested' }
+  [Rapfile/Rakfile]
+  
+  task(:outer) { print 'non-nested' }
   namespace :nest do
-    task :inner => :outer { puts 'was executed' }
-    task :outer { print 'nested' }
+    task(:inner1 => :outer) { puts ' was executed' }
+    task(:inner2 => 'nest:outer') { puts ' was executed' }
+    task(:outer) { print 'nested' }
   end
   
-By contrast, rake waits to resolve dependencies and will always use a match
-within a namespace in preference to a literal match.  For these tasks rap and
-rake produce different results:
+Rap resolves the dependencies literally:
 
-  % rap nest/inner
+  % rap nest/inner1
   non-nested was executed
-  % rake nest:inner
-  nested was executed
+  
+  % rap nest/inner2
+  nested was executed
+
+Rake resolves the dependencies relative to the namespace:
+  
+  % rake nest:inner1
+  nested was executed
+  
+  % rake nest:inner2
+  nested was executed

data/lib/rap.rb

@@ -0,0 +1,6 @@
+require 'tap'
+require 'rap/declarations'
+
+module Rap
+  autoload(:Rake, 'rap/rake')
+end

data/lib/rap/declaration_task.rb

@@ -1,14 +1,41 @@
-require 'tap'
+require 'tap/task'
+require 'tap/env'
 require 'ostruct'
 require 'rap/description'
 
 module Rap
   
-  # DeclarationTasks are a singleton version of tasks.  DeclarationTasks only
-  # have one instance (DeclarationTask.instance) and the instance is
-  # registered as a dependency, so it will only execute once.
+  # DeclarationTasks are a special breed of Tap::Task designed to behave much
+  # like Rake tasks.  As such, declaration tasks:
+  #
+  # * return nil and pass nil in workflows 
+  # * only execute once
+  # * are effectively singletons (one instance per app)
+  # * allow for multiple actions
+  #
+  # The DeclarationTask class partially includes Declarations so subclasses
+  # may directly declare tasks.  A few alias acrobatics makes it so that ONLY
+  # Declarations#task is made available (desc cannot be used because Task
+  # classes already use that method for documentation, and namespace
+  # would be silly).
+  #
+  # Weird? Yes, but it leads to this syntax:
+  #
+  #   # [Rapfile]
+  #   # class Subclass < Rap::DeclarationTask
+  #   #   def helper(); "help"; end
+  #   # end
+  #   #
+  #   # # ::desc a help task
+  #   # Subclass.task(:help) {|task, args| puts "got #{task.helper}"}
+  #   
+  #   % rap help
+  #   got help
+  #
   class DeclarationTask < Tap::Task
     class << self
+      
+      # Sets actions.
       attr_writer :actions
       
       # An array of actions (blocks) associated with this class.  Each of the
@@ -18,6 +45,7 @@ module Rap
         @actions ||= []
       end
       
+      # Sets argument names
       attr_writer :arg_names
       
       # The argument names pulled from a task declaration.
@@ -32,24 +60,43 @@ module Rap
         args
       end
       
-      # Initializes instance and registers it as a dependency.
-      def new(*args)
-        @instance ||= super
-        @instance.app.dependencies.register(@instance)
-        @instance
+      # Instantiates the instance of self for app and reconfigures it using
+      # argh.  Configurations are set, the task name is set, and the
+      # arguments are stored on the instance.  The arguments are returned
+      # as normal in the [instance, args] result.
+      #
+      # These atypical behaviors handle various situations on the command
+      # line.  Setting the args this way, for example, allows arguments to
+      # be specified on dependency tasks:
+      #
+      #   # [Rapfile]
+      #   # Rap.task(:a, :obj) {|t, a| puts "A #{a.obj}"}
+      #   # Rap.task({:b => :a}, :obj) {|t, a| puts "B #{a.obj}"}
+      #
+      #   % rap b world -- a hello
+      #   A hello
+      #   B world
+      #
+      def instantiate(argh={}, app=Tap::App.instance)
+        config = argh[:config]
+        config_file = argh[:config_file]
+        
+        instance = self.instance(app)
+        instance.reconfigure(load_config(config_file)) if config_file
+        instance.reconfigure(config) if config
+        instance.args = argh[:args]
+      
+        [instance, instance.args]
       end
       
-      # Looks up or creates the DeclarationTask subclass specified by name
-      # (nested within declaration_base), and adds the configs and dependencies.
-      # Declare also registers the subclass in the declaration_env tasks
-      # manifest.
-      # 
-      # Configurations are always validated using the yaml transformation block
-      # (see {Configurable::Validation.yaml}[http://tap.rubyforge.org/configurable/classes/Configurable/Validation.html]).
+      # Looks up or creates the DeclarationTask subclass specified by const_name
+      # and adds the configs and dependencies.
       #
+      # Configurations are always validated using the yaml transformation block
+      # (see {Configurable::Validation}[http://tap.rubyforge.org/configurable/classes/Configurable/Validation.html]).
       def subclass(const_name, configs={}, dependencies=[])
         # lookup or generate the subclass
-        subclass = Tap::Support::Constant.constantize(const_name.to_s) do |base, constants|
+        subclass = Tap::Env::Constant.constantize(const_name.to_s) do |base, constants|
           subclass_const = constants.pop
           constants.inject(base) do |namespace, const|
             # nesting Task classes into other Task classes is required
@@ -72,19 +119,74 @@ module Rap
 
         # add dependencies
         dependencies.each do |dependency|
-          dependency_name = File.basename(dependency.default_name)
+          dependency_name = File.basename(dependency.to_s.underscore)
+          
+          # this suppresses 'method redefined' warnings
+          if subclass.method_defined?(dependency_name)
+            subclass.send(:undef_method, dependency_name)
+          end
+          
           subclass.send(:depends_on, dependency_name, dependency)
         end
         
         subclass
       end
+    end
+    
+    # The result of self, set by call.
+    attr_reader :result
+    
+    # The arguments assigned to self during call.
+    attr_accessor :args
+    
+    def initialize(config={}, app=Tap::App.instance)
+      super
+      @resolved = false
+      @result = nil
+      @args = nil
+    end
+    
+    # Conditional call to the super call; only calls once.  Returns result.
+    def call(*args)
       
-      private
+      # Declaration tasks function as dependencies, but unlike normal
+      # dependencies, they CAN take arguments from the command line.
+      # Such arguments will be set as args, and be used to enque the
+      # task.  
+      #
+      # If the task executes from the queue first, args will be
+      # provided to call and they should equal self.args.  If the task
+      # executes as a dependency first, call will not receive args and
+      # in that case self.args will be used.
+      #
+      # This warns for cases that odd workflows can produce where the
+      # args have been set and DIFFERENT args are used to enque the task.
+      # In these cases always go with the pre-set args but warn the issue.
+      self.args ||= args
+      unless self.args == args
+        if @resolved
+          warn "warn: ignorning dependency task inputs #{args.inspect} (#{self})"
+        else
+          warn "warn: invoking dependency task with preset args #{self.args.inspect} and not inputs #{args.inspect} (#{self})"
+        end
+      end
       
-      # overridden to provide self as the declaration_class
-      def declaration_class # :nodoc:
-        self
+      unless @resolved
+        @resolved = true
+        @result = super(*self.args)
       end
+      result
+    end
+    
+    # Returns true if already resolved by call.
+    def resolved?
+      @resolved
+    end
+    
+    # Resets self so call will call again.  Also sets result to nil.
+    def reset
+      @resolved = false
+      @result = nil
     end
     
     # Collects the inputs into an OpenStruct according to the class arg_names,

data/lib/rap/declarations.rb

@@ -1,27 +1,28 @@
 require 'rap/declaration_task'
-require 'tap/support/shell_utils'
+require 'rap/utils'
 
 module Rap
   
-  # Defines the rakish task declaration methods.  They may be included at the
-  # top level (like Rake) or, since they included as a part of the API, used
-  # through Rap.
+  # Defines the Rap task declaration methods.  They may be included at the
+  # top level (like Rake) or used through Rap.
   #
-  # Unlike rake, task will define actual task classes according to the task
+  # === Usage
+  #
+  # Unlike in rake, task will define actual task classes according to the task
   # names.  Task classes may be nested within modules using namespace.  It's
   # VERY important to realize this is the case both to aid in thing like
   # testing and to prevent namespace conflicts.  For example:
   #
-  #   Rap.task(:sample)              # => Sample.instance
+  #   t = Rap.task(:sample)                  
+  #   t.class                            # => Sample
+  #
   #   Rap.namespace(:nested) do
-  #     Rap.task(:sample)            # => Nested::Sample.instance
+  #     t = Rap.task(:sample)                
+  #     t.class                          # => Nested::Sample
   #   end
   #
-  # Normally all declared tasks are subclasses of DeclarationTask.  An easy
-  # way to use an existing subclasses of DeclarationTask as a base task is
-  # to call declare on the subclass.  This feature is only available to
-  # subclasses of DeclarationTask, but can be used within namespaces, and in
-  # conjunction with desc.
+  # Normally all declared tasks are subclasses of DeclarationTask, but
+  # subclasses of DeclarationTask can declare tasks as well.
   #
   #   class Alt < DeclarationTask
   #   end
@@ -30,31 +31,41 @@ module Rap
   #
   #   desc "task one, a subclass of DeclarationTask"
   #   o = Rap.task(:one)
-  #   o.class                          # => One
-  #   o.class.superclass               # => DeclarationTask
-  #   o.class.manifest.desc            # => "task one, a subclass of DeclarationTask"
+  #   o.class                            # => One
+  #   o.class.superclass                 # => DeclarationTask
+  #   o.class.desc.to_s                  # => "task one, a subclass of DeclarationTask"
   #
   #   namespace(:nest) do
-  #
   #     desc "task two, a nested subclass of Alt"
-  #     t = Alt.declare(:two)
+  #     t = Alt.task(:two)
   #     t.class                          # => Nest::Two
   #     t.class.superclass               # => Alt
-  #     t.class.manifest.desc            # => "task two, a nested subclass of Alt"
-  #   
+  #     t.class.desc.to_s                # => "task two, a nested subclass of Alt"
   #   end
   #
-  # See the {Syntax Reference}[link:files/doc/Syntax%20Reference.html] for usage.
+  # This feature is only available to subclasses of DeclarationTask and can
+  # be very useful for creating inheritance hierarchies.  Note that other
+  # declaration methods like 'desc' and 'namespace' are not available on
+  # DeclarationTask or subclasses, just 'task'.
+  #
+  # See the {Syntax Reference}[link:files/doc/Syntax%20Reference.html] for more
+  # information.
   module Declarations
-    include Tap::Support::ShellUtils
+    include Utils
     
     # The environment in which declared task classes are registered.
-    # By default the Tap::Env for Dir.pwd.
-    def Declarations.env() @@env ||= Tap::Env.instantiate(Dir.pwd); end
+    # By default a Tap::Env for Dir.pwd.
+    def Declarations.env() @@env ||= Tap::Env.new; end
     
     # Sets the declaration environment.
     def Declarations.env=(env) @@env=env; end
     
+    # The declaration App (default Tap::App.instance)
+    def Declarations.app() @@app ||= Tap::App.instance; end
+    
+    # Sets the declaration App.
+    def Declarations.app=(app) @@app=app; end
+    
     # The base constant for all task declarations, prepended to the task name.
     def Declarations.current_namespace() @@current_namespace; end
     @@current_namespace = ''
@@ -64,6 +75,11 @@ module Rap
     def Declarations.current_desc() @@current_desc; end
     @@current_desc = nil
     
+    # Returns the instance of the task class in app.
+    def Declarations.instance(tasc)
+      tasc.instance(Declarations.app)
+    end
+    
     # Declares a task with a rake-like syntax.  Task generates a subclass of
     # DeclarationTask, nested within the current namespace.
     def task(*args, &action)
@@ -74,22 +90,27 @@ module Rap
       
       # generate the task class
       const_name = File.join(@@current_namespace, name.to_s).camelize
-      task_class = register declaration_class.subclass(const_name, configs, dependencies)
+      tasc = declaration_class.subclass(const_name, configs, dependencies)
       
       # register documentation        
-      manifest = Lazydoc.register_caller(Description)
-      manifest.desc = @@current_desc
+      desc = Lazydoc.register_caller(Description)
+      desc.desc = @@current_desc
       @@current_desc = nil
       
-      task_class.arg_names = arg_names
-      task_class.manifest = manifest
-      task_class.source_file = manifest.document.source_file
+      tasc.arg_names = arg_names
+      tasc.desc = desc
+      tasc.source_file = desc.document.source_file
       
       # add the action
-      task_class.actions << action if action
+      tasc.actions << action if action
+      
+      # register
+      register tasc
       
       # return the instance
-      task_class.instance
+      instance = Declarations.instance(tasc)
+      instance.config.bind(instance, true)
+      instance
     end
     
     # Nests tasks within the named module for the duration of the block.
@@ -152,7 +173,7 @@ module Rap
         unless need.kind_of?(Class)
           # lookup or declare non-class dependencies
           name = normalize_name(need).camelize
-          need = Tap::Support::Constant.constantize(name) do |base, constants|
+          need = Tap::Env::Constant.constantize(name) do |base, constants|
             const = block_given? ? yield(name) : nil
             const or raise ArgumentError, "unknown task class: #{name}"
           end
@@ -186,26 +207,46 @@ module Rap
     
     # Registers a task class with the Declarations.env, if necessary.
     # Returns task_class.
-    def register(task_class)
-      tasks = Declarations.env.tasks
-      const_name = task_class.to_s
-      unless tasks.entries.any? {|const| const.name == const_name }
-        tasks.entries << Tap::Support::Constant.new(const_name)
+    def register(tasc)
+      tasks = Declarations.env.manifest(:task)
+      
+      const_name = tasc.to_s
+      constant = tasks.find do |const| 
+        const.const_name == const_name
+      end
+      
+      unless constant
+        constant = Tap::Env::Constant.new(const_name)
+        tasks.entries << constant
       end
       
-      task_class
+      constant.comment = tasc.desc(false)
+      tasc
     end
   end
   
   class DeclarationTask
     class << self
+      # :stopdoc:
+      alias original_desc desc
+      # :startdoc:
+      
       include Declarations
       
-      # alias task as declare, so that DeclarationTask and subclasses
-      # may directly declare subclasses of themselves
+      # :stopdoc:
+      undef_method :desc
+      alias desc original_desc
+      
+      # hide remaining Declarations methods (including Utils methods)
+      private :namespace, :sh
+      # :startdoc:
       
-      alias declare task
-      private :task, :desc, :namespace
+      private
+      
+      # overridden to provide self as the declaration_class
+      def declaration_class # :nodoc:
+        self
+      end
     end
   end
   

data/lib/rap/description.rb

@@ -1,13 +1,13 @@
 module Rap
   
-  # :::-
+  # :startdoc:::-
   # A special type of Lazydoc::Comment designed to handle the comment syntax
   # for task declarations.
   #
   # Description instances can be assigned a description, or they may parse
   # one directly from the comment.  Comment lines with the constant attribute
   # '::desc' will have the value set as desc.
-  # :::+
+  # :startdoc:::+
   class Description < Lazydoc::Comment
     
     # The description for self.
@@ -15,8 +15,8 @@ module Rap
     
     # Parses in-comment descriptions from prepended lines, if present.
     def prepend(line)
-      if line =~ /::desc\s+(.*?)\s*$/
-        self.desc = $1
+      if line =~ /::desc(?:\s+(.*?))?\s*$/
+        self.desc = $1.to_s
         false
       else
         super

data/lib/rap/rake.rb

@@ -1,14 +1,15 @@
-require 'rap/rake_app'
+require 'rubygems'
+require 'rake'
 
 module Rap
 
-  # :startdoc::manifest run rake tasks
+  # :startdoc::task run rake tasks
   # 
   # Simply enques the specified rake task(s) for execution.  Useful when a
   # rake task needs to be executed within a workflow.  For example these
   # are equivalent:
   #
-  #   % tap run -- rake test
+  #   % rap rake test
   #   % rake test
   # 
   # The only exeception is in the use of the --help option.  Use --rake-help
@@ -16,7 +17,7 @@ module Rap
   #
   class Rake < Tap::Task
     class << self
-  
+
       # Overrides Tap::Support::FrameworkClass#parse! to do  
       # nothing so that all args get passed forward to rake.
       def parse!(argv, app=Tap::App.instance) # => instance, argv
@@ -24,13 +25,21 @@ module Rap
           puts help
           exit
         end
-        [new({}, default_name, app), argv.collect {|arg| arg == '--rake-help' ? '--help' : arg}]
+        argv = argv.collect {|arg| arg == '--rake-help' ? '--help' : arg}
+        [new({}, app), argv]
+      end
+      
+      # Returns true if Rake detects a rakefile.
+      def has_rakefile?
+        ::Rake.application.have_rakefile != nil
       end
     end
-  
+    
+    # Executes Rake using the input arguments as if they came from the
+    # command line.
     def process(*argv)
       rake = ::Rake.application
-    
+  
       # run as if from command line using argv
       current_argv = ARGV.dup
       begin
@@ -45,9 +54,9 @@ module Rap
         ARGV.clear
         ARGV.concat(current_argv)
       end
-  
-      rake.enq_top_level(app)
-  
+
+      rake.top_level
+    
       nil
     end
   end

data/lib/rap/utils.rb

@@ -0,0 +1,18 @@
+module Rap
+  module Utils
+    # Run the system command +cmd+, passing the result to the block, if given.
+    # Raises an error if the command fails. Uses the same semantics as 
+    # Kernel::exec and Kernel::system.
+    #
+    # Based on FileUtils#sh from Rake.
+    def sh(*cmd) # :yields: ok, status
+      ok = system(*cmd)
+
+      if block_given?
+        yield(ok, $?)
+      else
+        ok or raise "Command failed with status (#{$?.exitstatus}): [#{cmd.join(' ')}]"
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rap
 version: !ruby/object:Gem::Version 
-  version: 0.12.3
+  version: 0.13.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.12.4
+        version: 0.17.0
     version: 
 description: 
 email: simon.a.chiang@gmail.com
@@ -32,19 +32,18 @@ extra_rdoc_files:
 - README
 - MIT-LICENSE
 - History
-- doc/Command Reference
 - doc/Syntax Reference
 files: 
 - lib/rap/declaration_task.rb
 - lib/rap/declarations.rb
 - lib/rap/description.rb
-- lib/rap/rake_app.rb
 - lib/rap/rake.rb
+- lib/rap/utils.rb
+- lib/rap.rb
 - tap.yml
 - README
 - MIT-LICENSE
 - History
-- doc/Command Reference
 - doc/Syntax Reference
 has_rdoc: true
 homepage: http://tap.rubyforge.org

data/doc/Command Reference

@@ -1,22 +0,0 @@
-= Command Reference
-
-Rap comes the rap executable.  For help on the command line, type:
-
-  % rap --help
-
-The rap executable is basically a shorthand for 'tap run --'.  Specifying tasks
-for rap is no different than 'tap run' (see the Tap {Command Reference}[http://tap.rubyforge.org/rdoc/files/doc/Command%20Reference.html]).
-The only exception occurs when the task can't be found; unknown tasks are run
-as if by rake.  For instance all of these are the same:
-
-Run a rake task with inputs and an ENV config:
-
-  % rake task_name[1,2,3] key=value
-
-Explicitly run a Rap::Rake task using the same inputs:
-
-  % rap rake task_name[1,2,3] key=value
-
-Implicitly run the Rap::Rake task:
-
-  % rap task_name[1,2,3] key=value

data/lib/rap/rake_app.rb

@@ -1,107 +0,0 @@
-require 'rubygems'
-require 'rake'
-require 'tap'
-
-module Rap
-  class RakeManifest < Tap::Support::Manifest
-    def initialize(env)
-      @env = env
-      rake = ::Rake.application
-      super(rake.have_rakefile(env.root.root) ? [rake.instance_variable_get(:@rakefile)] : [])
-    end
-  end
-
-  module RakeApp
-    def self.extended(base)
-      Tap::Env.instantiate(Dir.pwd).activate unless Tap::Env.instance
-      base.env = Tap::Env.instance
-    end
-  
-    attr_accessor :env
-   
-    def enq_top_level(app)
-      # takes the place of rake.top_level
-      if options.show_tasks
-        display_tasks_and_comments
-        exit
-      elsif options.show_prereqs
-        display_prerequisites
-        exit
-      else
-        top_level_tasks.each do |task_string|
-          name, args = parse_task_string(task_string)
-          task = self[name]
-          app.mq(task, :invoke, *args)
-        end
-      end  
-    end
-    
-    def collect_tasks(*args)
-      # a little song and dance for compliance with
-      # rake pre- and post-0.8.2
-      argv = args.empty? ? ARGV : args[0]
-      argv.collect! do |arg|
-        next(arg) unless arg =~ /^:([a-z_\d]+):(.*)$/
-        env_pattern = $1
-        rake_task = $2
-      
-        next(arg) unless entry = env.find(:envs, env_pattern, false)
-      
-        mini_path, env = entry
-        root_path = env.root.root
-      
-        if have_rakefile(root_path)
-          # load sequence echos that in raw_load_rakefile
-          puts "(in #{root_path})" unless options.silent
-          current_global_rakefile = $rakefile
-          $rakefile = @rakefile
-        
-          namespaces = Tap::Root.split(mini_path, false).delete_if do |segment| 
-            segment.empty?
-          end
-        
-          #if @rakefile != ''
-          eval nest_namespace(%Q{load "#{File.join(root_path, @rakefile)}"}, namespaces.dup)
-          #end
-        
-          $rakefile = current_global_rakefile
-          @rakefile = nil
-        
-          namespaces << rake_task
-          namespaces.join(":")
-        else
-          fail "No Rakefile found for '#{env_pattern}' (looking for: #{@rakefiles.join(', ')})"
-        end
-      end
-      
-      super
-    end
-  
-    def have_rakefile(dir=nil)
-      return super() if dir == nil
-      Tap::Root.chdir(dir) { super() }
-    end
-
-    protected
-  
-    NAMESPACE_STR = %Q{
-namespace(:'%s') do
-%s
-end
-}.strip
-  
-    def nest_namespace(nest_str, namespaces)
-      return nest_str if namespaces.empty?
-    
-      NAMESPACE_STR % [
-        namespaces.shift, 
-        namespaces.empty? ? nest_str : nest_namespace(nest_str, namespaces)
-      ]
-    end
-  end
-end
-
-Rake.application.extend Rap::RakeApp
-Tap::Env.manifest(:rakefiles) do |env|
-  Rap::RakeManifest.new(env)
-end