Add -t (--tools) switch for showing a tool-friendly task listing

CHANGELOG.rdoc

@@ -1,5 +1,7 @@
 == (unreleased)
 
+* Add -t (--tools) switch for better task lists for external tools [Jamis Buck]
+
 * Make the RemoteDependency#try method use invoke_command instead of run, for sudo-ability [Matthias Marschall]
 
 * Make locally executed commands in Windows more Windows-friendly [esad@esse.at]

lib/capistrano/cli/help.rb

@@ -21,16 +21,18 @@ module Capistrano
       end
 
       def task_list(config, pattern = true) #:nodoc:
+        tool_output = options[:tool]
+
         if pattern.is_a?(String)
           tasks = config.task_list(:all).select {|t| t.fully_qualified_name =~ /#{pattern}/}
         end
         if tasks.nil? || tasks.length == 0
-          puts "Pattern '#{pattern}' not found. Listing all tasks.\n\n" unless pattern.is_a?(TrueClass)
+          warn "Pattern '#{pattern}' not found. Listing all tasks.\n\n" if !tool_output && !pattern.is_a?(TrueClass)
           tasks = config.task_list(:all)
         end
 
         if tasks.empty?
-          warn "There are no tasks available. Please specify a recipe file to load."
+          warn "There are no tasks available. Please specify a recipe file to load." unless tool_output
         else
           all_tasks_length = tasks.length
           if options[:verbose].to_i < 1
@@ -44,19 +46,25 @@ module Capistrano
           max_length = MIN_MAX_LEN if max_length < MIN_MAX_LEN
 
           tasks.each do |task|
-            puts "cap %-#{longest}s # %s" % [task.fully_qualified_name, task.brief_description(max_length)]
+            if tool_output
+              puts "cap #{task.fully_qualified_name}"
+            else
+              puts "cap %-#{longest}s # %s" % [task.fully_qualified_name, task.brief_description(max_length)]
+            end
           end
 
-          if all_tasks_length > tasks.length
+          unless tool_output
+            if all_tasks_length > tasks.length
+              puts
+              puts "Some tasks were not listed, either because they have no description,"
+              puts "or because they are only used internally by other tasks. To see all"
+              puts "tasks, type `#{File.basename($0)} -vT'."
+            end
+
             puts
-            puts "Some tasks were not listed, either because they have no description,"
-            puts "or because they are only used internally by other tasks. To see all"
-            puts "tasks, type `#{File.basename($0)} -vT'."
+            puts "Extended help may be available for these tasks."
+            puts "Type `#{File.basename($0)} -e taskname' to view it."
           end
-
-          puts
-          puts "Extended help may be available for these tasks."
-          puts "Type `#{File.basename($0)} -e taskname' to view it."
         end
       end
 
@@ -107,4 +115,4 @@ module Capistrano
       end
     end
   end
-end
+end

lib/capistrano/cli/help.txt

@@ -46,6 +46,9 @@ The following options are understood:
   <%= color '-T, --tasks PATTERN', :bold %>
 	Displays the list of all tasks (matching optional PATTERN) in all loaded recipe files. If a task has no description, or if the description starts with the [internal] tag, the task will not be listed unless you also specify -v.
 
+  <%= color '-t, --tool', :bold %>
+	Abbreviates the output of -T for integration with other tools. Without -t, -T will list tasks with their summaries, and may include additional instructive text at the bottom. When integrating with other tools (e.g., bash auto-expansion and the like) that additional text can get in the way. This switch makes it easier for those tools to parse the list of tasks. (The -t switch has no effect if the -T switch is not specified.)
+
   <%= color '-V, --version', :bold %>
 	Shows the current Capistrano version number and exits.
 

lib/capistrano/cli/options.rb

@@ -90,6 +90,10 @@ module Capistrano
             options[:verbose] ||= 0
           end
 
+          opts.on("-t", "--tool",
+            "Abbreviates the output of -T for tool integration."
+          ) { options[:tool] = true }
+
           opts.on("-V", "--version",
             "Display the Capistrano version, and exit."
           ) do
@@ -100,7 +104,10 @@ module Capistrano
 
           opts.on("-v", "--verbose",
             "Be more verbose. May be given more than once."
-          ) { options[:verbose] ||= 0; options[:verbose] += 1 }
+          ) do
+            options[:verbose] ||= 0
+            options[:verbose] += 1
+          end
 
           opts.on("-X", "--skip-system-config",
             "Don't load the system config file (capistrano.conf)"

test/cli/help_test.rb

@@ -84,6 +84,7 @@ class CLIHelpTest < Test::Unit::TestCase
     config = mock("config")
     config.expects(:task_list).with(:all).times(2).returns(task_list)
 
+    @cli.stubs(:warn)
     @cli.stubs(:puts)
     @cli.task_list(config, "z")
   end