cape 1.6.0 → 1.6.1

data/features/dsl/mirror_rake_tasks/with_defined_task_argument.feature

@@ -9,7 +9,7 @@ Feature: The #mirror_rake_tasks DSL method with an argument of a defined task
     And a Capfile with:
       """
       Cape do
-        mirror_rake_tasks 'with_period'
+        mirror_rake_tasks :with_period
       end
       """
     When I run `cap -vT`
@@ -17,38 +17,23 @@ Feature: The #mirror_rake_tasks DSL method with an argument of a defined task
       """
       cap with_period # Ends with period.
       """
-    And the output should not contain "cap without_period"
+    And the output should not contain "without_period"
 
-  Scenario: mirror Rake task 'with_period' with its description
+  Scenario: mirror the matching Rake task with its implementation
     Given a full-featured Rakefile
     And a Capfile with:
       """
-      Cape do
-        mirror_rake_tasks :with_period
-      end
-      """
-    When I run `cap -e with_period`
-    Then the output should contain exactly:
-      """
-      ------------------------------------------------------------
-      cap with_period
-      ------------------------------------------------------------
-      Ends with period.
+      set :current_path, '/path/to/current/deployed/application'
+      set :rails_env,    'production'
 
-
-      """
-
-  Scenario: do not mirror Rake task 'without_period'
-    Given a full-featured Rakefile
-    And a Capfile with:
-      """
       Cape do
-        mirror_rake_tasks :with_period
+        mirror_rake_tasks 'with_period'
       end
       """
-    When I run `cap -e without_period`
-    Then the output should contain exactly:
+    When I run `cap with_period`
+    Then the output should contain:
       """
-      The task `without_period' does not exist.
-
+        * executing `with_period'
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_period"
+      `with_period' is only run for servers matching {}, but no servers matched
       """

data/features/dsl/mirror_rake_tasks/with_defined_task_argument_and_environment_variables.feature

@@ -0,0 +1,43 @@
+Feature: The #mirror_rake_tasks DSL method with an argument of a defined task, and with environment variables
+
+  In order to include Rake tasks with descriptions in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: mirror only the matching Rake task
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      Cape do
+        mirror_rake_tasks :with_period do |env|
+          env['RAILS_ENV'] = rails_env
+        end
+      end
+      """
+    When I run `cap -vT`
+    Then the output should contain:
+      """
+      cap with_period # Ends with period.
+      """
+    And the output should not contain "without_period"
+
+  Scenario: mirror the matching Rake task with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/path/to/current/deployed/application'
+      set :rails_env,    'production'
+
+      Cape do
+        mirror_rake_tasks 'with_period' do |env|
+          env['RAILS_ENV'] = rails_env
+        end
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing `with_period'
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_period RAILS_ENV=\"production\""
+      `with_period' is only run for servers matching {}, but no servers matched
+      """

data/features/dsl/mirror_rake_tasks/with_environment_variables.feature

@@ -0,0 +1,29 @@
+Feature: The #mirror_rake_tasks DSL method with environment variables
+
+  In order to include Rake tasks with descriptions in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: mirror a Rake task with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/path/to/current/deployed/application'
+      set :rails_env,    'production'
+
+      Cape do
+        mirror_rake_tasks do |env|
+          env['RAILS_ENV']  = rails_env
+          env[nil]          = 'foo'
+          env['FOO']        = nil
+          env['SOME_OTHER'] = 'var'
+        end
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing `with_period'
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_period RAILS_ENV=\"production\" SOME_OTHER=\"var\""
+      `with_period' is only run for servers matching {}, but no servers matched
+      """

data/features/dsl/mirror_rake_tasks/with_undefined_argument.feature

@@ -5,17 +5,6 @@ Feature: The #mirror_rake_tasks DSL method with an undefined argument
   I want to use the Cape DSL.
 
   Scenario: do not mirror any Rake tasks
-    Given a full-featured Rakefile
-    And a Capfile with:
-      """
-      Cape do
-        mirror_rake_tasks 'this_does_not_exist'
-      end
-      """
-    When I run `cap -vT`
-    Then the output should not contain "cap with_period"
-
-  Scenario: do not mirror Rake task 'with_period'
     Given a full-featured Rakefile
     And a Capfile with:
       """
@@ -23,9 +12,6 @@ Feature: The #mirror_rake_tasks DSL method with an undefined argument
         mirror_rake_tasks :this_does_not_exist
       end
       """
-    When I run `cap -e with_period`
-    Then the output should contain exactly:
-      """
-      The task `with_period' does not exist.
-
-      """
+    When I run `cap -vT`
+    Then the output should not contain "cap this_does_not_exist"
+    And the output should not contain "cap with_period"

data/features/dsl/mirror_rake_tasks/with_valid_options_argument.feature

@@ -1,75 +1,10 @@
-Feature: The #mirror_rake_tasks DSL method with arguments of a defined task and valid options, and with environment variables
+Feature: The #mirror_rake_tasks DSL method with an argument of valid options
 
   In order to include Rake tasks with descriptions in my Capistrano recipes,
   As a developer using Cape,
   I want to use the Cape DSL.
 
-  Scenario: mirror all Rake tasks with the specified options
-    Given a full-featured Rakefile
-    And a Capfile with:
-      """
-      Cape do
-        mirror_rake_tasks :roles => :app
-      end
-      """
-    When I run `cap -vT`
-    Then the output should contain:
-      """
-      cap with_period                                            # Ends with period.
-      """
-    And the output should contain:
-      """
-      cap without_period                                         # Ends without period.
-      """
-    And the output should contain:
-      """
-      cap long                                                   # My long task -- it has a ve...
-      """
-    And the output should contain:
-      """
-      cap with_one_arg                                           # My task with one argument.
-      """
-    And the output should contain:
-      """
-      cap my_namespace                                           # A task that shadows a names...
-      """
-    And the output should contain:
-      """
-      cap my_namespace:in_a_namespace                            # My task in a namespace.
-      """
-    And the output should contain:
-      """
-      cap my_namespace:my_nested_namespace:in_a_nested_namespace # My task in a nested namespace.
-      """
-    And the output should contain:
-      """
-      cap with_two_args                                          # My task with two arguments.
-      """
-    And the output should contain:
-      """
-      cap with_three_args                                        # My task with three arguments.
-      """
-
-  Scenario: mirror Rake task 'with_period' with its description
-    Given a full-featured Rakefile
-    And a Capfile with:
-      """
-      Cape do
-        mirror_rake_tasks :roles => :app
-      end
-      """
-    When I run `cap -e with_period`
-    Then the output should contain exactly:
-      """
-      ------------------------------------------------------------
-      cap with_period
-      ------------------------------------------------------------
-      Ends with period.
-
-
-      """
-
-  Scenario: mirror Rake task 'with_period' with its implementation
+  Scenario: mirror a Rake task with its implementation
     Given a full-featured Rakefile
     And a Capfile with:
       """

data/features/dsl/mirror_rake_tasks/with_valid_options_arguments_and_environment_variables.feature

@@ -0,0 +1,26 @@
+Feature: The #mirror_rake_tasks DSL method with an argument of valid options, and with environment variables
+
+  In order to include Rake tasks with descriptions in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: mirror a Rake task with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/path/to/current/deployed/application'
+      set :rails_env,    'production'
+
+      Cape do
+        mirror_rake_tasks :roles => :app do |env|
+          env['RAILS_ENV'] = rails_env
+        end
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing `with_period'
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_period RAILS_ENV=\"production\""
+      `with_period' is only run for servers matching {:roles=>:app}, but no servers matched
+      """

data/features/dsl/mirror_rake_tasks/without_arguments.feature

@@ -84,6 +84,7 @@ Feature: The #mirror_rake_tasks DSL method without arguments
       """
         * executing `with_period'
         * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_period"
+      `with_period' is only run for servers matching {}, but no servers matched
       """
 
   Scenario: mirror Rake task 'without_period' with its description
@@ -181,6 +182,7 @@ Feature: The #mirror_rake_tasks DSL method without arguments
       """
         * executing `my_namespace'
         * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake my_namespace"
+      `my_namespace' is only run for servers matching {}, but no servers matched
       """
 
   Scenario: mirror Rake task 'my_namespace:in_a_namespace' with its description
@@ -236,6 +238,7 @@ Feature: The #mirror_rake_tasks DSL method without arguments
       """
         * executing `my_namespace:my_nested_namespace:in_a_nested_namespace'
         * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake my_namespace:my_nested_namespace:in_a_nested_namespace"
+      `my_namespace:my_nested_namespace:in_a_nested_namespace' is only run for servers matching {}, but no servers matched
       """
 
   Scenario: mirror Rake task 'with_two_args' with its description
@@ -297,7 +300,7 @@ Feature: The #mirror_rake_tasks DSL method without arguments
       """
         * executing `with_three_args'
         * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_three_args[\"a value for an_arg1\",\"a value for an_arg2\",\"a value for an_arg3\"]"
-
+      `with_three_args' is only run for servers matching {}, but no servers matched
       """
 
   Scenario: mirror Rake task 'with_three_args' with its implementation not enforcing arguments
@@ -315,5 +318,5 @@ Feature: The #mirror_rake_tasks DSL method without arguments
       """
         * executing `with_three_args'
         * executing "cd /path/to/current/deployed/application && /usr/bin/env `/usr/bin/env bundle check >/dev/null 2>&1; case $? in 0|1 ) echo bundle exec ;; esac` rake with_three_args[,\"a value for an_arg2\",]"
-
+      `with_three_args' is only run for servers matching {}, but no servers matched
       """

data/lib/cape/capistrano.rb

@@ -1,3 +1,4 @@
+require 'cape/hash_list'
 require 'cape/rake'
 require 'cape/util'
 
@@ -10,6 +11,8 @@ module Cape
     attr_accessor :rake
 
     # Constructs a new Capistrano object with the specified _attributes_.
+    #
+    # @param [Hash] attributes attribute values
     def initialize(attributes={})
       attributes.each do |name, value|
         send "#{name}=", value
@@ -44,7 +47,7 @@ module Cape
     #
     # @note Any parameters that the Rake task has are integrated via environment variables, since Capistrano does not support recipe parameters per se.
     #
-    # @see http://github.com/capistrano/capistrano/blob/master/lib/capistrano/task_definition.rb#L15-L17 Valid Capistrano ‘task’ method options
+    # @see http://github.com/capistrano/capistrano/blob/master/lib/capistrano/configuration/actions/invocation.rb#L99-L144 Valid Capistrano ‘task’ method options
     def define_rake_wrapper(task, named_arguments, &block)
       unless (binding = named_arguments[:binding])
         raise ::ArgumentError, ':binding named argument is required'
@@ -54,13 +57,13 @@ module Cape
       options = named_arguments.reject do |key, value|
         key == :binding
       end
-      describe( task, capistrano_context, options, &block)
+      describe  task, capistrano_context
       implement(task, capistrano_context, options, &block)
     end
 
   private
 
-    def build_capistrano_description(task, options, &block)
+    def build_capistrano_description(task)
       return nil unless task[:description]
 
       description = [task[:description]]
@@ -85,8 +88,8 @@ Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
       description.join
     end
 
-    def describe(task, capistrano_context, options, &block)
-      if (description = build_capistrano_description(task, options, &block))
+    def describe(task, capistrano_context)
+      if (description = build_capistrano_description(task))
         capistrano_context.desc description
       end
       self
@@ -110,7 +113,7 @@ Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
           else
             arguments = "[#{arguments.join ','}]"
           end
-          env_hash = {}
+          env_hash = HashList.new
           env_block.call(env_hash) if env_block
           env_hash.reject! do |var_name, var_value|
             var_name.nil? || var_value.nil?

data/lib/cape/core_ext/hash.rb

@@ -9,6 +9,7 @@ module Cape
       # _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 }]

data/lib/cape/core_ext/symbol.rb

@@ -8,6 +8,7 @@ module Cape
       # 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_

data/lib/cape/dsl.rb

@@ -9,7 +9,7 @@ module Cape
     # Enumerates Rake tasks.
     #
     # @param [String, Symbol] task_expression the full name of a task or
-    #                                         namespace to filter; optional
+    #                                         namespace to filter
     # @param [Proc]           block           a block that processes tasks
     #
     # @yield [task] a block that processes tasks
@@ -27,7 +27,8 @@ module Cape
     #       # 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
+    #       # * t[:description] -- documentation on the task, including
+    #       #                      parameters
     #     end
     #   end
     #
@@ -41,7 +42,8 @@ module Cape
     #       # 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
+    #       # * t[:description] -- documentation on the task, including
+    #       #                      parameters
     #     end
     #   end
     def each_rake_task(task_expression=nil, &block)
@@ -61,6 +63,7 @@ module Cape
     # 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
@@ -68,7 +71,8 @@ module Cape
     #
     #   Cape do
     #     self.local_rake_executable = '/path/to/rake'
-    #     $stdout.puts "We changed the local Rake executable to #{self.local_rake_executable.inspect}."
+    #     $stdout.puts 'We changed the local Rake executable to ' +
+    #                  "#{local_rake_executable.inspect}."
     #   end
     def local_rake_executable=(value)
       rake.local_executable = value
@@ -80,6 +84,7 @@ module Cape
     # @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)
@@ -91,7 +96,7 @@ module Cape
     #   Defines Rake tasks as Capistrano recipes.
     #
     #   @param [String, Symbol] task_expression the full name of a Rake task or
-    #                                           namespace to filter; optional
+    #                                           namespace to filter
     #
     #   @yield [env] a block that defines environment variables for the Rake
     #                task; optional
@@ -132,7 +137,7 @@ module Cape
     #
     # @note Any parameters that the Rake tasks have are integrated via environment variables, since Capistrano does not support recipe parameters per se.
     #
-    # @see http://github.com/capistrano/capistrano/blob/master/lib/capistrano/task_definition.rb#L15-L17 Valid Capistrano ‘task’ method options
+    # @see http://github.com/capistrano/capistrano/blob/master/lib/capistrano/configuration/actions/invocation.rb#L99-L144 Valid Capistrano ‘task’ method options
     #
     # @example Mirroring all Rake tasks
     #   # config/deploy.rb
@@ -143,22 +148,31 @@ module Cape
     #     mirror_rake_tasks
     #   end
     #
-    # @example Mirroring specific Rake tasks
+    # @example Mirroring some Rake tasks, but not others
     #   # config/deploy.rb
     #
     #   require 'cape'
     #
     #   Cape do
-    #     mirror_rake_tasks 'log:clear'
+    #     # Create Capistrano recipes for the Rake task 'foo' and/or for the
+    #     # tasks in the 'foo' namespace.
+    #     mirror_rake_tasks :foo
     #   end
     #
-    # @example Mirroring specific Rake tasks with Capistrano recipe options and/or environment variables
+    # @example Mirroring Rake tasks that require Capistrano recipe options and/or environment variables
     #   # config/deploy.rb
     #
     #   require 'cape'
     #
     #   Cape do
-    #     mirror_rake_tasks :db, :roles => :app do |env|
+    #     # Display defined Rails routes on application server remote machines
+    #     # only.
+    #     mirror_rake_tasks :routes, :roles => :app
+    #
+    #     # Execute database migration on application server remote machines
+    #     # only, and set the 'RAILS_ENV' environment variable to the value of
+    #     # the Capistrano variable 'rails_env'.
+    #     mirror_rake_tasks 'db:migrate', :roles => :app do |env|
     #       env['RAILS_ENV'] = rails_env
     #     end
     #   end
@@ -178,8 +192,8 @@ module Cape
       options = arguments.last.is_a?(Hash) ? arguments.pop.dup : {}
       unless arguments.length <= 1
         raise ::ArgumentError,
-              "wrong number of arguments (#{arguments_count} for 0 or 1, plus " +
-              'an options hash)'
+              ("wrong number of arguments (#{arguments_count} for 0 or 1, " +
+               'plus an options hash)')
       end
 
       task_expression = arguments.first
@@ -202,6 +216,7 @@ module Cape
     # 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
@@ -209,7 +224,8 @@ module Cape
     #
     #   Cape do
     #     self.remote_rake_executable = '/path/to/rake'
-    #     $stdout.puts "We changed the remote Rake executable to #{self.remote_rake_executable.inspect}."
+    #     $stdout.puts 'We changed the remote Rake executable to ' +
+    #                  "#{remote_rake_executable.inspect}."
     #   end
     def remote_rake_executable=(value)
       rake.remote_executable = value