cape 1.0.1 → 1.0.2

data/Gemfile

@@ -2,8 +2,6 @@ source 'http://rubygems.org'
 
 gemspec
 
-gem 'jruby-openssl',          :platforms => :jruby
-
 group :debug do
   gem 'ruby-debug',           :platforms => :mri_18
 

data/History.markdown

@@ -1,12 +1,13 @@
-Version history for the _Cape_ project
-======================================
+# Version history for the _Cape_ project
 
-<a name="v1.0.1"></a>v1.0.0, Tue 11/29/2011
--------------------------------------------
+## <a name="v1.0.2"></a>v1.0.2, Thu 12/29/2011
+
+* Support Rake task arguments that contain whitespace
+
+## <a name="v1.0.1"></a>v1.0.1, Tue 11/29/2011
 
 * Don’t run Cucumber features from `gem test cape` because they fail
 
-<a name="v1.0.0"></a>v1.0.0, Mon 11/28/2011
--------------------------------------------
+## <a name="v1.0.0"></a>v1.0.0, Mon 11/28/2011
 
 (First release)

data/MIT-LICENSE.markdown

@@ -1,5 +1,4 @@
-The MIT License
-===============
+# The MIT License
 
 Source code for _Cape_ is Copyright © 2011 [Nils Jonsson](mailto:cape@nilsjonsson.com) and [contributors](http://github.com/njonsson/cape/contributors "Cape contributors at GitHub").
 

data/README.markdown

@@ -29,8 +29,7 @@
             <hNNBNBh=(.                                /   \   `
                ..
 
-[<img align="right" src="https://secure.travis-ci.org/njonsson/cape.png?branch=master" title="Travis CI build status" />](http://travis-ci.org/njonsson/cape) Cape
-==================================================================================================================================================================
+# [<img align="right" src="https://secure.travis-ci.org/njonsson/cape.png?branch=master" title="Travis CI build status" />](http://travis-ci.org/njonsson/cape) Cape
 
 If
 
@@ -39,40 +38,43 @@ If
 
 Then
 
-* **You can invoke [Cape](http://github.com/njonsson/cape)** to dynamically add Capistrano recipes for each of your application’s Rake tasks, and
+* **You can use the [Cape](http://github.com/njonsson/cape) DSL** within Capistrano recipes to dynamically add recipes for your application’s Rake tasks, and
 * **You can run your Rake tasks on your deployed servers,** friction-free, and look like a superhero. _[cue fanfare]_
 
-Installation
-------------
+## Features
 
-Install [the RubyGem](http://rubygems.org/gems/cape "Cape at RubyGems.org"):
+* **Mirror Rake tasks** as Capistrano recipes, optionally filtered by namespace or name
+* **Embed Rake tasks** in Capistrano namespaces
+* **Pass arguments** to Rake tasks by setting environment variables with the same names
+* **Override the default executables** for local and remote Rake installations (`/usr/bin/env rake` is the default)
+* **Enumerate Rake tasks** for your own purposes
+
+## Installation — get your Cape on
+
+Install [the RubyGem](http://rubygems.org/gems/cape "Cape at RubyGems.org").
 
     $ gem install cape
 
 Or you may want to make Cape a dependency of your project by using [Bundler](http://gembundler.com).
 
-Features
---------
+    # Gemfile
 
-* **Mirror Rake tasks** as Capistrano recipes, optionally filtered by namespace or name
-* **Embed Rake tasks** in a Capistrano namespace
-* **Pass arguments** to Rake tasks by setting environment variables with the same names
-* **Override the default executables** for local and remote Rake installations (`/usr/bin/env rake` is the default)
-* **Enumerate Rake tasks** for your own purposes
+    source 'http://rubygems.org'
 
-Examples
---------
+    gem 'cape'
 
-Assume we have the following _Rakefile_.
+## Examples
+
+Assume the following Rake tasks are defined.
 
     desc 'Rakes the leaves'
     task :leaves do
-      # (Raking action goes here.)
+      $stdout.puts "Raking the leaves"
     end
 
     desc 'Rakes and bags the leaves'
-    task :bag_leaves, [:paper_or_plastic] => :leaves do
-      # (Bagging action goes here.)
+    task :bag_leaves, [:paper_or_plastic] => :leaves do |task, arguments|
+      $stdout.puts "Putting the leaves in a #{arguments[:paper_or_plastic]} bag"
     end
 
 Rake lists these tasks in the expected fashion.
@@ -81,7 +83,15 @@ Rake lists these tasks in the expected fashion.
     rake bag_leaves[paper_or_plastic]  # Rakes and bags the leaves
     rake leaves                        # Rakes the leaves
 
-Put the following in your _config/deploy.rb_. **Note that Cape statements must be executed within a `Cape` block.**
+    $ rake --describe bag_leaves
+    rake bag_leaves[paper_or_plastic]
+        Rakes and bags the leaves
+
+### Simply mirror all Rake tasks as Capistrano recipes
+
+Add the following to your Capistrano recipes. Note that Cape statements must be executed within a `Cape` block.
+
+    # config/deploy.rb
 
     require 'cape'
 
@@ -90,7 +100,7 @@ Put the following in your _config/deploy.rb_. **Note that Cape statements must b
       mirror_rake_tasks
     end
 
-Now all your Rake tasks can be invoked as Capistrano recipes. Capistrano lists the recipes in the following fashion.
+Now all your Rake tasks appear alongside your Capistrano recipes.
 
     $ cap --tasks
     cap deploy               # Deploys your project.
@@ -116,10 +126,35 @@ Let’s use Capistrano to view the unabbreviated description of a Rake task reci
 
     You must set environment variable PAPER_OR_PLASTIC.
 
-Cape lets you filter the Rake tasks to be mirrored:
+Here’s how to invoke a task/recipe with arguments. On the local computer, via Rake:
+
+    $ rake bag_leaves[plastic]
+    (in /current/working/directory)
+    Raking the leaves
+    Putting the leaves in a plastic bag
+
+On remote computers, via Capistrano:
+
+    $ cap bag_leaves PAPER_OR_PLASTIC=plastic
+      * executing `bag_leaves'
+      * executing "cd /path/to/currently/deployed/version/of/your/app && rake bag_leaves[plastic]"
+        servers: ["your.server.name"]
+        [your.server.name] executing command
+     ** [out :: your.server.name] (in /path/to/currently/deployed/version/of/your/app)
+     ** [out :: your.server.name] Raking the leaves
+     ** [out :: your.server.name] Putting the leaves in a plastic bag
+        command finished in 1000ms
+
+### Mirror some Rake tasks, but not others
+
+Cape lets you filter the Rake tasks to be mirrored. Note that Cape statements must be executed within a `Cape` block.
+
+    # config/deploy.rb
+
+    require 'cape'
 
     Cape do
-      # Create Capistrano recipes for the Rake task 'foo' or for the tasks in a
+      # Create Capistrano recipes for the Rake task 'foo' or for the tasks in the
       # 'foo' namespace.
       mirror_rake_tasks :foo
 
@@ -128,39 +163,54 @@ Cape lets you filter the Rake tasks to be mirrored:
       mirror_rake_tasks 'bar:baz'
     end
 
-Cape plays friendly with the Capistrano DSL for organizing Rake tasks in Capistrano namespaces.
+### Mirror Rake tasks into a Capistrano namespace
+
+Cape plays friendly with the Capistrano DSL for organizing Rake tasks in Capistrano namespaces. Note that Cape statements must be executed within a `Cape` block.
+
+    # config/deploy.rb
+
+    require 'cape'
 
-    # Use an argument with the Cape block, if you want to or need to.
     namespace :rake_tasks do
+      # Use an argument with the Cape block, if you want to or need to.
       Cape do |cape|
         cape.mirror_rake_tasks
       end
     end
 
-Cape lets you enumerate Rake tasks, optionally filtering them by task name or namespace.
+### Iterate over available Rake tasks
+
+Cape lets you enumerate Rake tasks, optionally filtering them by task name or namespace. Note that Cape statements must be executed within a `Cape` block.
+
+    # config/deploy.rb
+
+    require 'cape'
 
     Cape do
+      # Enumerate all Rake tasks.
       each_rake_task do |t|
         # Do something interesting with this hash:
         # * t[:name] -- the full name of the task
         # * t[:parameters] -- the names of task arguments
         # * t[:description] -- documentation on the task, including parameters
       end
+
+      # Enumerate the Rake task 'foo' or the tasks in the 'foo' namespace.
+      each_rake_task 'foo' do |t|
+        # ...
+      end
     end
 
-Limitations
------------
+## Limitations
 
 For now, only Rake tasks that have descriptions can be mirrored or enumerated.
 
-Contributing
-------------
+## Contributing
 
 Report defects and feature requests on [GitHub Issues](http://github.com/njonsson/cape/issues).
 
 Your patches are welcome, and you will receive attribution here for good stuff.
 
-License
--------
+## License
 
 Released under the [MIT License](http://github.com/njonsson/cape/blob/master/MIT-LICENSE.markdown).

data/features/dsl/mirror_rake_tasks/inside_capistrano_namespace/without_arguments.feature

@@ -74,6 +74,25 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, witho
 
       """
 
+  Scenario: mirror Rake task 'with_period' with its implementation
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      set :current_path, '/path/to/current/deployed/application'
+      namespace :ns do
+        Cape do |cape|
+          cape.mirror_rake_tasks
+        end
+      end
+      """
+    When I run `cap ns:with_period`
+    Then the output should contain:
+      """
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env rake with_period"
+      """
+
   Scenario: mirror Rake task 'without_period' with its description
     Given a full-featured Rakefile
     And a file named "Capfile" with:

data/features/dsl/mirror_rake_tasks/without_arguments.feature

@@ -70,6 +70,23 @@ Feature: The #mirror_rake_tasks DSL method without arguments
 
       """
 
+  Scenario: mirror Rake task 'with_period' with its implementation
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      set :current_path, '/path/to/current/deployed/application'
+      Cape do
+        mirror_rake_tasks
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env rake with_period"
+      """
+
   Scenario: mirror Rake task 'without_period' with its description
     Given a full-featured Rakefile
     And a file named "Capfile" with:
@@ -179,6 +196,23 @@ Feature: The #mirror_rake_tasks DSL method without arguments
 
       """
 
+  Scenario: mirror Rake task 'my_namespace:my_nested_namespace:in_a_nested_namespace' with its implementation
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      set :current_path, '/path/to/current/deployed/application'
+      Cape do
+        mirror_rake_tasks
+      end
+      """
+      When I run `cap my_namespace:my_nested_namespace:in_a_nested_namespace`
+    Then the output should contain:
+      """
+      * executing "cd /path/to/current/deployed/application && /usr/bin/env rake my_namespace:my_nested_namespace:in_a_nested_namespace"
+      """
+
   Scenario: mirror Rake task 'with_two_args' with its description
     Given a full-featured Rakefile
     And a file named "Capfile" with:
@@ -225,6 +259,39 @@ Feature: The #mirror_rake_tasks DSL method without arguments
 
       """
 
+  Scenario: mirror Rake task 'with_three_args' with its implementation enforcing arguments
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      set :current_path, '/path/to/current/deployed/application'
+      Cape do
+        mirror_rake_tasks
+      end
+      """
+    When I run `cap with_three_args AN_ARG1="a value for an_arg1"`
+    Then the output should contain "Environment variable AN_ARG2 must be set (RuntimeError)"
+
+  Scenario: mirror Rake task 'with_three_args' with its implementation
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      set :current_path, '/path/to/current/deployed/application'
+      Cape do
+        mirror_rake_tasks
+      end
+      """
+      When I run `cap with_three_args AN_ARG1="a value for an_arg1" AN_ARG2="a value for an_arg2" AN_ARG3="a value for an_arg3"`
+    Then the output should contain:
+      """
+        * executing `with_three_args'
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env rake with_three_args[\"a value for an_arg1\",\"a value for an_arg2\",\"a value for an_arg3\"]"
+
+      """
+
   Scenario: do not mirror Rake task 'hidden_task'
     Given a full-featured Rakefile
     And a file named "Capfile" with:

data/features/dsl/rake_executable.feature

@@ -0,0 +1,70 @@
+Feature: The #local_rake_executable and #remote_rake_executable DSL attributes
+
+  In order to control which Rake executables are used locally and remotely,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: use a different Rake executable to enumerate Rake tasks
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      Cape do
+        self.local_rake_executable = 'echo "rake this-comes-from-overridden-rake  # This comes from overridden Rake" #'
+        $stdout.puts "We changed the local Rake executable to #{self.local_rake_executable.inspect}."
+        $stdout.puts "We left the remote Rake executable as #{self.remote_rake_executable.inspect}."
+        each_rake_task do |t|
+          $stdout.puts '', "Name: #{t[:name].inspect}"
+          if t[:parameters]
+            $stdout.puts "Parameters: #{t[:parameters].inspect}"
+          end
+          if t[:description]
+            $stdout.puts "Description: #{t[:description].inspect}"
+          end
+        end
+      end
+      """
+    When I run `cap -T`
+    Then the output should contain:
+      """
+      We changed the local Rake executable to "echo \"rake this-comes-from-overridden-rake  # This comes from overridden Rake\" #"
+      """
+    And the output should contain:
+      """
+      We left the remote Rake executable as "/usr/bin/env rake"
+      """
+    And the output should contain:
+      """
+
+      Name: "this-comes-from-overridden-rake"
+      Description: "This comes from overridden Rake"
+      """
+
+  Scenario: use a different Rake executable to execute Rake tasks
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      set :current_path, '/path/to/current/deployed/application'
+      Cape do
+        self.remote_rake_executable = 'echo "This comes from overridden Rake" #'
+        $stdout.puts "We changed the remote Rake executable to #{self.remote_rake_executable.inspect}."
+        $stdout.puts "We left the local Rake executable as #{self.local_rake_executable.inspect}."
+        mirror_rake_tasks
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+      We changed the remote Rake executable to "echo \"This comes from overridden Rake\" #"
+      """
+    And the output should contain:
+      """
+      We left the local Rake executable as "/usr/bin/env rake"
+      """
+    And the output should contain:
+      """
+        * executing "cd /path/to/current/deployed/application && echo \"This comes from overridden Rake\" # with_period"
+      """

data/features/support/env.rb

@@ -1 +1,5 @@
 require 'aruba/cucumber'
+
+Before do
+  @aruba_timeout_seconds = 10
+end

data/lib/cape.rb

@@ -1,5 +1,5 @@
-Dir.glob( File.expand_path( 'cape/*.rb', File.dirname( __FILE__ ))) do |f|
-  require "cape/#{File.basename f, '.rb'}"
+::Dir.glob(::File.expand_path('../cape/*.rb', __FILE__)) do |f|
+  require "cape/#{::File.basename f, '.rb'}"
 end
 
 # Contains the implementation of Cape.
@@ -9,7 +9,34 @@ module Cape
 
 end
 
-# The method used to group Cape statements in a block.
+# The method used to group Cape statements.
+#
+# @param [Proc] block Cape and Capistrano statements
+# @return [Cape] the Cape module
+#
+# @yield [cape] a block containing Cape statements
+# @yieldparam [Cape::DSL] cape the Cape DSL; optional
+#
+# @example Basic Cape usage
+#   # config/deploy.rb
+#
+#   require 'cape'
+#
+#   Cape do
+#     mirror_rake_tasks
+#   end
+#
+# @example Combining Cape statements with Capistrano statements
+#   # config/deploy.rb
+#
+#   require 'cape'
+#
+#   namespace :rake_tasks do
+#     # Use an argument with the Cape block, if you want to or need to.
+#     Cape do |cape|
+#       cape.mirror_rake_tasks
+#     end
+#   end
 def Cape(&block)
   Cape.module_eval do
     @outer_self = block.binding.eval('self', __FILE__, __LINE__)
@@ -19,4 +46,5 @@ def Cape(&block)
       module_eval(&block)
     end
   end
+  Cape
 end

data/lib/cape/capistrano.rb

@@ -1,21 +1,37 @@
-require 'cape/strings'
+require 'cape/util'
 
 module Cape
 
   # An abstraction of the Capistrano installation.
   class Capistrano
 
-    # Defines the specified _task_ as a Capistrano task, provided a Binding
-    # named argument +:binding+ and a Cape::Rake named argument +:rake+. Any
-    # parameters the task has are converted to environment variables, since
-    # Capistrano does not have the concept of task parameters.
+    # Defines the specified _task_ as a Capistrano task.
     #
-    # The _task_ argument must be a Hash of the form:
+    # @param [Hash] task            metadata for a task
+    # @param [Hash] named_arguments named arguments
     #
-    #   {:name        => <String>,
-    #    :parameters  => <String Array or nil>,
-    #    :description => <String>}
-    def define(task, named_arguments={})
+    # @option task [String]               :name        the name of the task
+    # @option task [Array of String, nil] :parameters  the names of the task's
+    #                                                  parameters, if any
+    # @option task [String]               :description documentation for the task
+    #
+    # @option named_arguments [Binding]           :binding the Binding of your
+    #                                                      Capistrano recipes
+    #                                                      file
+    # @option named_arguments [Rake]              :rake    a Cape abstraction of
+    #                                                      the Rake installation
+    # @option named_arguments [[Array of] Symbol] :roles   the Capistrano role(s)
+    #                                                      of remote computers
+    #                                                      that will execute
+    #                                                      _task_
+    #
+    # @return [Capistrano] the object
+    #
+    # @raise [ArgumentError] +named_arguments[:binding]+ is missing
+    # @raise [ArgumentError] +named_arguments[:rake]+ is missing
+    #
+    # @note Any parameters that the task has are integrated via environment variables, since Capistrano does not support task parameters per se.
+    def define(task, named_arguments)
       unless (binding = named_arguments[:binding])
         raise ::ArgumentError, ':binding named argument is required'
       end
@@ -40,8 +56,8 @@ module Cape
       description = [task[:description]]
       description << '.' unless task[:description].end_with?('.')
       unless (parameters = Array(task[:parameters])).empty?
-        noun            = Strings.pluralize('variable', parameters.length)
-        parameters_list = Strings.to_list_phrase(parameters.collect(&:upcase))
+        noun            = Util.pluralize('variable', parameters.length)
+        parameters_list = Util.to_list_phrase(parameters.collect(&:upcase))
         description << <<-end_description
 
 
@@ -60,7 +76,7 @@ You must set environment #{noun} #{parameters_list}.
             unless (value = ENV[a.upcase])
               fail "Environment variable #{a.upcase} must be set"
             end
-            value
+            value.inspect
           end
           if arguments.empty?
             arguments = nil

data/lib/cape/core_ext.rb

@@ -1,5 +1,5 @@
-Dir.glob( File.expand_path( 'core_ext/*.rb', File.dirname( __FILE__ ))) do |f|
-  require "cape/core_ext/#{File.basename f, '.rb'}"
+::Dir.glob(::File.expand_path('../core_ext/*.rb', __FILE__)) do |f|
+  require "cape/core_ext/#{::File.basename f, '.rb'}"
 end
 
 module Cape

data/lib/cape/core_ext/hash.rb

@@ -2,11 +2,14 @@ module Cape
 
   module CoreExt
 
-    # Contains extensions to the Hash core class.
+    # Adds methods missing from Ruby's Hash core class.
     module Hash
 
       # Returns a copy of the Hash containing values only for the specified
       # _keys_.
+      #
+      # @param [Array] keys zero or more hash keys
+      # @return [Hash] a subset of the Hash
       def slice(*keys)
         ::Hash[select { |key, value| keys.include? key }]
       end
@@ -17,8 +20,8 @@ module Cape
 
 end
 
-unless Hash.instance_methods.collect(&:to_s).include?('slice')
-  Hash.class_eval do
+unless ::Hash.instance_methods.collect(&:to_s).include?('slice')
+  ::Hash.class_eval do
     include Cape::CoreExt::Hash
   end
 end

data/lib/cape/core_ext/symbol.rb

@@ -2,12 +2,15 @@ module Cape
 
   module CoreExt
 
-    # Contains extensions to the Symbol core class.
+    # Adds methods missing from Ruby's Symbol core class.
     module Symbol
 
-      # Returns +0+ if the Symbol is equal to _other_, +-1+ if it is
-      # alphabetically lesser than _other_, and +1+ if it is alphabetically
-      # greater than _other_.
+      # Compares the String representation of the Symbol to that of another.
+      #
+      # @param [Symbol] other
+      # @return  [0] the Symbol is equal to _other_
+      # @return [-1] the Symbol is lesser than _other_
+      # @return  [1] the Symbol is greater than _other_
       def <=>(other)
         to_s <=> other.to_s
       end
@@ -18,8 +21,8 @@ module Cape
 
 end
 
-unless Symbol.instance_methods.collect(&:to_s).include?('<=>')
-  Symbol.class_eval do
+unless ::Symbol.instance_methods.collect(&:to_s).include?('<=>')
+  ::Symbol.class_eval do
     include Cape::CoreExt::Symbol
   end
 end

data/lib/cape/dsl.rb

@@ -6,36 +6,121 @@ module Cape
   # Provides methods for integrating Capistrano and Rake.
   module DSL
 
-    # Yields each available Rake task to a block. The optional _task_expression_
-    # argument limits the list to a single task or a namespace containing
-    # multiple tasks.
+    # Enumerates Rake tasks.
     #
-    # Tasks are yielded as Hash objects of the form:
+    # @param [String, Symbol] task_expression the full name of a task or
+    #                                         namespace to filter; optional
+    # @param [Proc]           block           a block that processes tasks
     #
-    #   {:name        => <String>,
-    #    :parameters  => <String Array or nil>,
-    #    :description => <String>}
+    # @yield [task] a block that processes tasks
+    # @yieldparam [Hash] task metadata on a task
+    #
+    # @return [DSL] the object
+    #
+    # @example Enumerating all Rake tasks
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     each_rake_task do |t|
+    #       # Do something interesting with this hash:
+    #       # * t[:name] -- the full name of the task
+    #       # * t[:parameters] -- the names of task arguments
+    #       # * t[:description] -- documentation on the task, including parameters
+    #     end
+    #   end
+    #
+    # @example Enumerating some Rake tasks
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     each_rake_task :foo do |t|
+    #       # Do something interesting with this hash:
+    #       # * t[:name] -- the full name of the task
+    #       # * t[:parameters] -- the names of task arguments
+    #       # * t[:description] -- documentation on the task, including parameters
+    #     end
+    #   end
     def each_rake_task(task_expression=nil, &block)
       rake.each_task(task_expression, &block)
       self
     end
 
-    # Returns the command used to run Rake on the local computer. Defaults to
-    # Rake::DEFAULT_EXECUTABLE.
+    # The command used to run Rake on the local computer.
+    #
+    # @return [String] the command used to run Rake on the local computer
+    #
+    # @see Rake::DEFAULT_EXECUTABLE
     def local_rake_executable
       rake.local_executable
     end
 
     # Sets the command used to run Rake on the local computer.
+    #
+    # @param [String] value the command used to run Rake on the local computer
+    # @return [String] _value_
+    #
+    # @example Changing the local Rake executable
+    #   require 'cape'
+    #
+    #   Cape do
+    #     self.local_rake_executable = '/path/to/rake'
+    #     $stdout.puts "We changed the local Rake executable to #{self.local_rake_executable.inspect}."
+    #   end
     def local_rake_executable=(value)
       rake.local_executable = value
     end
 
-    # Defines each available Rake task as a Capistrano task. Any
-    # parameters the tasks have are converted to environment variables, since
-    # Capistrano does not have the concept of task parameters. The optional
-    # _task_expression_ argument limits the list to a single task or a namespace
-    # containing multiple tasks.
+    # Makes the use of a block parameter optional by forwarding non-Cape method
+    # calls to the containing binding.
+    #
+    # @param [Symbol, String] method the method called
+    # @param [Array]          args   the arguments passed to _method_
+    # @param [Proc]           block  the block passed to _method_
+    # @return the result of the forwarded method call
+    def method_missing(method, *args, &block)
+      @outer_self.send(method, *args, &block)
+    end
+
+    # Defines Rake tasks as Capistrano tasks.
+    #
+    # @param [String, Symbol] task_expression the full name of a Rake task or
+    #                                         namespace to filter; optional
+    # @return [DSL] the object
+    #
+    # @note Any parameters that the Rake tasks have are integrated via environment variables, since Capistrano does not support task parameters per se.
+    #
+    # @example Mirroring all Rake tasks
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     mirror_rake_tasks
+    #   end
+    #
+    # @example Mirroring some Rake tasks
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     mirror_rake_tasks :foo
+    #   end
+    #
+    # @example Mirroring Rake tasks into a Capistrano namespace
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   namespace :rake_tasks do
+    #     Cape do |cape|
+    #       cape.mirror_rake_tasks
+    #     end
+    #   end
     def mirror_rake_tasks(task_expression=nil)
       d = nil
       rake.each_task task_expression do |t|
@@ -44,13 +129,27 @@ module Cape
       self
     end
 
-    # Returns the command used to run Rake on remote computers. Defaults to
-    # Rake::DEFAULT_EXECUTABLE.
+    # The command used to run Rake on remote computers.
+    #
+    # @return [String] the command used to run Rake on remote computers
+    #
+    # @see Rake::DEFAULT_EXECUTABLE
     def remote_rake_executable
       rake.remote_executable
     end
 
     # Sets the command used to run Rake on remote computers.
+    #
+    # @param [String] value the command used to run Rake on remote computers
+    # @return [String] _value_
+    #
+    # @example Changing the remote Rake executable
+    #   require 'cape'
+    #
+    #   Cape do
+    #     self.remote_rake_executable = '/path/to/rake'
+    #     $stdout.puts "We changed the remote Rake executable to #{self.remote_rake_executable.inspect}."
+    #   end
     def remote_rake_executable=(value)
       rake.remote_executable = value
     end
@@ -62,10 +161,6 @@ module Cape
       Capistrano.new
     end
 
-    def method_missing(method, *args, &block)
-      @outer_self.send(method, *args, &block)
-    end
-
     def raise_unless_capistrano
       if @outer_self.method(:task).owner.name !~ /^Capistrano::/
         raise 'Use this in the context of Capistrano recipes'

data/lib/cape/rake.rb

@@ -7,9 +7,15 @@ module Cape
     DEFAULT_EXECUTABLE = '/usr/bin/env rake'.freeze
 
     # Sets the command used to run Rake on the local computer.
+    #
+    # @param [String] value the command used to run Rake on the local computer
+    # @return [String] _value_
     attr_writer :local_executable
 
     # Sets the command used to run Rake on remote computers.
+    #
+    # @param [String] value the command used to run Rake on remote computers
+    # @return [String] _value_
     attr_writer :remote_executable
 
     # Constructs a new Rake object with the specified _attributes_.
@@ -19,15 +25,16 @@ module Cape
       end
     end
 
-    # Yields each available Rake task to a block. The optional _task_expression_
-    # argument limits the list to a single task or a namespace containing
-    # multiple tasks.
+    # Enumerates Rake tasks.
     #
-    # Tasks are yielded as Hash objects of the form:
+    # @param [String, Symbol] task_expression the full name of a task or
+    #                                         namespace to filter; optional
+    # @param [Proc]           block           a block that processes tasks
     #
-    #   {:name        => <String>,
-    #    :parameters  => <String Array or nil>,
-    #    :description => <String>}
+    # @yield [task] a block that processes tasks
+    # @yieldparam [Hash] task metadata on a task
+    #
+    # @return [Rake] the object
     def each_task(task_expression=nil)
       task_expression = " #{task_expression}" if task_expression
       command = "#{local_executable} --tasks #{task_expression}"
@@ -43,14 +50,20 @@ module Cape
       self
     end
 
-    # Returns the command used to run Rake on the local computer. Defaults to
-    # DEFAULT_EXECUTABLE.
+    # The command used to run Rake on the local computer.
+    #
+    # @return [String] the command used to run Rake on the local computer
+    #
+    # @see DEFAULT_EXECUTABLE
     def local_executable
       @local_executable ||= DEFAULT_EXECUTABLE
     end
 
-    # Returns the command used to run Rake on remote computers. Defaults to
-    # DEFAULT_EXECUTABLE.
+    # The command used to run Rake on remote computers.
+    #
+    # @return [String] the command used to run Rake on remote computers
+    #
+    # @see DEFAULT_EXECUTABLE
     def remote_executable
       @remote_executable ||= DEFAULT_EXECUTABLE
     end

data/lib/cape/util.rb

@@ -0,0 +1,30 @@
+module Cape
+
+  # Provides utility functions.
+  module Util
+
+    # Conditionally transforms the specified _noun_ into its plural form.
+    #
+    # @param [String] noun  a singular noun
+    # @param [Fixnum] count the quantity of _noun_; optional
+    # @return [String] the plural of _noun_, unless _count_ is +1+
+    def self.pluralize(singular_noun, count=2)
+      return singular_noun if count == 1
+
+      "#{singular_noun}s"
+    end
+
+    # Builds a list phrase from the elements of the specified _array_.
+    #
+    # @param [Array of String] array zero or more nouns
+    # @return [String] the elements of _array_, joined with commas and "and", as
+    #                  appropriate
+    def self.to_list_phrase(array)
+      return array.join(' and ') if (array.length <= 2)
+
+      [array[0...-1].join(', '), array[-1]].join ', and '
+    end
+
+  end
+
+end

data/lib/cape/version.rb

@@ -1,6 +1,6 @@
 module Cape
 
   # The version of Cape.
-  VERSION = '1.0.1'
+  VERSION = '1.0.2'
 
 end

data/spec/cape/{strings_spec.rb → util_spec.rb}

@@ -1,44 +1,44 @@
-require 'cape/strings'
+require 'cape/util'
 
-describe Cape::Strings do
+describe Cape::Util do
   describe '::pluralize' do
     it "should pluralize 'foo' as expected" do
-      Cape::Strings.pluralize('foo').should == 'foos'
+      Cape::Util.pluralize('foo').should == 'foos'
     end
 
     it "should pluralize 'foo' as expected for a count of 2" do
-      Cape::Strings.pluralize('foo', 2).should == 'foos'
+      Cape::Util.pluralize('foo', 2).should == 'foos'
     end
 
     it "should not pluralize for a count of 1" do
-      Cape::Strings.pluralize('foo', 1).should == 'foo'
+      Cape::Util.pluralize('foo', 1).should == 'foo'
     end
 
     it "should pluralize 'foo' as expected for a count of 0" do
-      Cape::Strings.pluralize('foo', 0).should == 'foos'
+      Cape::Util.pluralize('foo', 0).should == 'foos'
     end
 
     it "should pluralize 'foo' as expected for a count of -1" do
-      Cape::Strings.pluralize('foo', -1).should == 'foos'
+      Cape::Util.pluralize('foo', -1).should == 'foos'
     end
   end
 
   describe '::to_list_phrase' do
     it 'should make the expected list phrase of an empty array' do
-      Cape::Strings.to_list_phrase([]).should == ''
+      Cape::Util.to_list_phrase([]).should == ''
     end
 
     it 'should make the expected list phrase of a 1-element array' do
-      Cape::Strings.to_list_phrase(%w(foo)).should == 'foo'
+      Cape::Util.to_list_phrase(%w(foo)).should == 'foo'
     end
 
     it 'should make the expected list phrase of a 2-element array' do
-      Cape::Strings.to_list_phrase(%w(foo bar)).should == 'foo and bar'
+      Cape::Util.to_list_phrase(%w(foo bar)).should == 'foo and bar'
     end
 
     it 'should make the expected list phrase of a 3-element array' do
       array = %w(foo bar baz)
-      Cape::Strings.to_list_phrase(array).should == 'foo, bar, and baz'
+      Cape::Util.to_list_phrase(array).should == 'foo, bar, and baz'
     end
   end
 end 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cape
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 1
   - 0
-  - 1
-  version: 1.0.1
+  - 2
+  version: 1.0.2
 platform: ruby
 authors: 
 - Nils Jonsson
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-30 00:00:00 Z
+date: 2011-12-29 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: aruba
@@ -106,10 +106,9 @@ files:
 - features/dsl/mirror_rake_tasks/with_defined_task_argument.feature
 - features/dsl/mirror_rake_tasks/with_undefined_argument.feature
 - features/dsl/mirror_rake_tasks/without_arguments.feature
+- features/dsl/rake_executable.feature
 - features/step_definitions.rb
 - features/support/env.rb
-- features/task_invocation/nonparameterized.feature
-- features/task_invocation/parameterized.feature
 - lib/cape.rb
 - lib/cape/capistrano.rb
 - lib/cape/core_ext.rb
@@ -117,15 +116,15 @@ files:
 - lib/cape/core_ext/symbol.rb
 - lib/cape/dsl.rb
 - lib/cape/rake.rb
-- lib/cape/strings.rb
+- lib/cape/util.rb
 - lib/cape/version.rb
 - spec/cape/capistrano_spec.rb
 - spec/cape/core_ext/hash_spec.rb
 - spec/cape/core_ext/symbol_spec.rb
 - spec/cape/dsl_spec.rb
 - spec/cape/rake_spec.rb
-- spec/cape/strings_spec.rb
 - spec/cape/task_spec.rb
+- spec/cape/util_spec.rb
 - spec/cape/version_spec.rb
 - spec/cape_spec.rb
 homepage: ""
@@ -176,17 +175,16 @@ test_files:
 - features/dsl/mirror_rake_tasks/with_defined_task_argument.feature
 - features/dsl/mirror_rake_tasks/with_undefined_argument.feature
 - features/dsl/mirror_rake_tasks/without_arguments.feature
+- features/dsl/rake_executable.feature
 - features/step_definitions.rb
 - features/support/env.rb
-- features/task_invocation/nonparameterized.feature
-- features/task_invocation/parameterized.feature
 - spec/cape/capistrano_spec.rb
 - spec/cape/core_ext/hash_spec.rb
 - spec/cape/core_ext/symbol_spec.rb
 - spec/cape/dsl_spec.rb
 - spec/cape/rake_spec.rb
-- spec/cape/strings_spec.rb
 - spec/cape/task_spec.rb
+- spec/cape/util_spec.rb
 - spec/cape/version_spec.rb
 - spec/cape_spec.rb
 has_rdoc: true

data/features/task_invocation/nonparameterized.feature

@@ -1,69 +0,0 @@
-Feature: Invoking parameterless Rake tasks via Capistrano
-
-  In order to invoke Rake tasks via Capistrano,
-  As a developer using Cape,
-  I want to use the `cap` command.
-
-  Scenario: invoke Rake task 'with_period'
-    Given a full-featured Rakefile
-    And a file named "Capfile" with:
-      """
-      load 'deploy' if respond_to?(:namespace) # cap2 differentiator
-
-      # Uncomment if you are using Rails' asset pipeline
-      # load 'deploy/assets'
-
-      Dir['vendor/gems/*/recipes/*.rb','vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
-
-      load 'config/deploy' # remove this line to skip loading any of the default tasks
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    And a file named "config/deploy.rb" with:
-      """
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    When I run `cap with_period`
-    Then the output should contain:
-      """
-        * executing `with_period'
-      """
-
-  Scenario: invoke Rake task 'my_namespace:in_a_namespace'
-    Given a full-featured Rakefile
-    And a file named "Capfile" with:
-      """
-      load 'deploy' if respond_to?(:namespace) # cap2 differentiator
-
-      # Uncomment if you are using Rails' asset pipeline
-      # load 'deploy/assets'
-
-      Dir['vendor/gems/*/recipes/*.rb','vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
-
-      load 'config/deploy' # remove this line to skip loading any of the default tasks
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    And a file named "config/deploy.rb" with:
-      """
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-      When I run `cap my_namespace:in_a_namespace`
-    Then the output should contain:
-      """
-      * executing `my_namespace:in_a_namespace'
-      """

data/features/task_invocation/parameterized.feature

@@ -1,70 +0,0 @@
-Feature: Invoking parameterized Rake tasks via Capistrano
-
-  In order to invoke Rake tasks via Capistrano,
-  As a developer using Cape,
-  I want to use the `cap` command.
-
-  Scenario: invoke Rake task 'with_one_arg' without an argument
-    Given a full-featured Rakefile
-    And a file named "Capfile" with:
-      """
-      load 'deploy' if respond_to?(:namespace) # cap2 differentiator
-
-      # Uncomment if you are using Rails' asset pipeline
-      # load 'deploy/assets'
-
-      Dir['vendor/gems/*/recipes/*.rb','vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
-
-      load 'config/deploy' # remove this line to skip loading any of the default tasks
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    And a file named "config/deploy.rb" with:
-      """
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    When I run `cap with_one_arg`
-    Then the output should contain:
-      """
-        * executing `with_one_arg'
-      """
-    And the output should contain "Environment variable THE_ARG must be set (RuntimeError)"
-
-  Scenario: invoke Rake task 'with_one_arg' with its argument
-    Given a full-featured Rakefile
-    And a file named "Capfile" with:
-      """
-      load 'deploy' if respond_to?(:namespace) # cap2 differentiator
-
-      # Uncomment if you are using Rails' asset pipeline
-      # load 'deploy/assets'
-
-      Dir['vendor/gems/*/recipes/*.rb','vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
-
-      load 'config/deploy' # remove this line to skip loading any of the default tasks
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    And a file named "config/deploy.rb" with:
-      """
-      require 'cape'
-
-      Cape do
-        mirror_rake_tasks
-      end
-      """
-    When I run `cap with_one_arg THE_ARG="the arg goes here"`
-    Then the output should contain:
-      """
-        * executing `with_one_arg'
-      """

data/lib/cape/strings.rb

@@ -1,25 +0,0 @@
-module Cape
-
-  # Provides utility methods for String objects.
-  module Strings
-
-    extend self
-
-    # Returns the English plural form of _noun_, unless _count_ is +1+. The
-    # _count_ argument is optional, and defaults to +2+.
-    def pluralize(noun, count=2)
-      return noun if count == 1
-
-      "#{noun}s"
-    end
-
-    # Builds an English list phrase from the elements of _array_.
-    def to_list_phrase(array)
-      return array.join(' and ') if (array.length <= 2)
-
-      [array[0...-1].join(', '), array[-1]].join ', and '
-    end
-
-  end
-
-end