cape 1.6.2 → 1.7.0

data/features/dsl/mirror_rake_tasks/{with_undefined_argument.feature → with_undefined_task_or_namespace.feature}

@@ -1,4 +1,4 @@
-Feature: The #mirror_rake_tasks DSL method with an undefined argument
+Feature: The #mirror_rake_tasks DSL method with an undefined task or namespace
 
   In order to include Rake tasks with descriptions in my Capistrano recipes,
   As a developer using Cape,
@@ -9,9 +9,8 @@ Feature: The #mirror_rake_tasks DSL method with an undefined argument
     And a Capfile with:
       """
       Cape do
-        mirror_rake_tasks :this_does_not_exist
+        mirror_rake_tasks 'period'
       end
       """
     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"
+    Then the output should not contain "period"

data/features/dsl/mirror_rake_tasks/with_valid_options.feature

@@ -0,0 +1,46 @@
+Feature: The #mirror_rake_tasks DSL method with 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.
+
+  @deprecated
+  Scenario: mirror a Rake task with its implementation (deprecated)
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/current/path'
+
+      Cape do
+        mirror_rake_tasks :roles => :app
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+      *** DEPRECATED: `mirror_rake_tasks :roles => :app`. Use this instead: `mirror_rake_tasks { |recipes| recipes.options[:roles] = :app }`
+        * executing `with_period'
+        * executing "cd /current/path && /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 {:roles=>:app}, but no servers matched
+      """
+
+  Scenario: mirror a Rake task with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/current/path'
+
+      Cape do
+        mirror_rake_tasks do |recipes|
+          recipes.options[:roles] = :app
+        end
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing `with_period'
+        * executing "cd /current/path && /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 {:roles=>:app}, but no servers matched
+      """
+    And the output should not contain "DEPRECATED"

data/features/dsl/mirror_rake_tasks/{with_valid_options_argument.feature → with_valid_options_and_cd.feature}

@@ -1,4 +1,4 @@
-Feature: The #mirror_rake_tasks DSL method with an argument of valid options
+Feature: The #mirror_rake_tasks DSL method with valid options and a different directory
 
   In order to include Rake tasks with descriptions in my Capistrano recipes,
   As a developer using Cape,
@@ -8,17 +8,19 @@ Feature: The #mirror_rake_tasks DSL method with an argument of valid options
     Given a full-featured Rakefile
     And a Capfile with:
       """
-      set :current_path, '/path/to/current/deployed/application'
-      set :rails_env,    'production'
+      set :release_path, '/release/path'
 
       Cape do
-        mirror_rake_tasks :roles => :app
+        mirror_rake_tasks do |recipes|
+          recipes.options[:roles] = :app
+          recipes.cd { release_path }
+        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"
+        * executing "cd /release/path && /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 {:roles=>:app}, but no servers matched
       """

data/features/dsl/mirror_rake_tasks/with_valid_options_and_cd_and_environment_variables.feature

@@ -0,0 +1,28 @@
+Feature: The #mirror_rake_tasks DSL method with valid options, a different directory, and 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 the matching Rake task with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :release_path, '/release/path'
+      set :rails_env,    'rails-env'
+
+      Cape do
+        mirror_rake_tasks do |recipes|
+          recipes.options[:roles] = :app
+          recipes.cd { release_path }
+          recipes.env['RAILS_ENV'] = lambda { rails_env }
+        end
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing `with_period'
+        * executing "cd /release/path && /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=\"rails-env\""
+      `with_period' is only run for servers matching {:roles=>:app}, but no servers matched
+      """

data/features/dsl/mirror_rake_tasks/with_valid_options_and_environment_variables.feature

@@ -0,0 +1,51 @@
+Feature: The #mirror_rake_tasks DSL method with valid options and 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.
+
+  @deprecated
+  Scenario: mirror the matching Rake task with its implementation (deprecated)
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/current/path'
+      set :rails_env,    'rails-env'
+
+      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:
+      """
+      *** DEPRECATED: `mirror_rake_tasks(:roles => :app) { |env| env["RAILS_ENV"] = "rails-env" }`. Use this instead: `mirror_rake_tasks { |recipes| recipes.options[:roles] = :app; recipes.env["RAILS_ENV"] = "rails-env" }`
+        * executing `with_period'
+        * executing "cd /current/path && /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=\"rails-env\""
+      `with_period' is only run for servers matching {:roles=>:app}, but no servers matched
+      """
+
+  Scenario: mirror the matching Rake task with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/current/path'
+      set :rails_env,    'rails-env'
+
+      Cape do
+        mirror_rake_tasks do |recipes|
+          recipes.options[:roles] = :app
+          recipes.env['RAILS_ENV'] = lambda { rails_env }
+        end
+      end
+      """
+    When I run `cap with_period`
+    Then the output should contain:
+      """
+        * executing `with_period'
+        * executing "cd /current/path && /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=\"rails-env\""
+      `with_period' is only run for servers matching {:roles=>:app}, but no servers matched
+      """
+    And the output should not contain "DEPRECATED"

data/features/dsl/rake_executable.feature

@@ -44,7 +44,7 @@ Feature: The #local_rake_executable and #remote_rake_executable DSL attributes
     Given a full-featured Rakefile
     And a Capfile with:
       """
-      set :current_path, '/path/to/current/deployed/application'
+      set :current_path, '/current/path'
 
       Cape.remote_rake_executable = 'echo "This comes from overridden Rake" #'
 
@@ -66,5 +66,5 @@ Feature: The #local_rake_executable and #remote_rake_executable DSL attributes
     And the output should contain:
       """
         * executing `with_period'
-        * executing "cd /path/to/current/deployed/application && echo \"This comes from overridden Rake\" # with_period"
+        * executing "cd /current/path && echo \"This comes from overridden Rake\" # with_period"
       """

data/features/step_definitions.rb

@@ -43,3 +43,43 @@ Given 'a full-featured Rakefile' do
     task :hidden_task
   end_step
 end
+
+Given 'a full-featured Rakefile defining a Ruby-method-shadowing task' do
+  step 'a file named "Rakefile" with:', <<-end_step
+    desc 'A task that shadows a Ruby method'
+    task :load
+
+    desc 'Ends with period.'
+    task :with_period
+
+    desc 'Ends without period'
+    task :without_period
+
+    desc 'My long task -- it has a very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very long description'
+    task :long
+
+    desc 'My task with one argument'
+    task :with_one_arg, [:the_arg]
+
+    desc 'A task that shadows a namespace'
+    task :my_namespace
+
+    namespace :my_namespace do
+      desc 'My task in a namespace'
+      task :in_a_namespace
+
+      namespace :my_nested_namespace do
+        desc 'My task in a nested namespace'
+        task :in_a_nested_namespace
+      end
+    end
+
+    desc 'My task with two arguments'
+    task :with_two_args, [:my_arg1, :my_arg2]
+
+    desc 'My task with three arguments'
+    task :with_three_args, [:an_arg1, :an_arg2, :an_arg3]
+
+    task :hidden_task
+  end_step
+end

data/lib/cape.rb

@@ -6,12 +6,14 @@ end
 module Cape
 
   extend DSL
+  extend DSLDeprecated
 
 end
 
 # 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

data/lib/cape/capistrano.rb

@@ -1,5 +1,5 @@
-require 'cape/hash_list'
 require 'cape/rake'
+require 'cape/recipe_definition'
 require 'cape/util'
 
 module Cape
@@ -17,14 +17,13 @@ module Cape
       attributes.each do |name, value|
         send "#{name}=", value
       end
-      self.rake ||= Rake.new
+      self.rake ||= new_rake
     end
 
     # Defines a wrapper in Capistrano around the specified Rake _task_.
     #
     # @param [Hash] task            metadata for a Rake task
-    # @param [Hash] named_arguments named arguments, including options to pass to
-    #                               the Capistrano +task+ method
+    # @param [Hash] named_arguments
     #
     # @option task [String]               :name        the name of the Rake task
     # @option task [Array of String, nil] :parameters  the names of the Rake
@@ -32,33 +31,28 @@ module Cape
     # @option task [String]               :description documentation for the Rake
     #                                                  task
     #
-    # @option named_arguments [Binding] :binding            the Binding of your
-    #                                                       Capistrano recipes
-    #                                                       file
+    # @option named_arguments [Binding] :binding the Binding of your Capistrano
+    #                                            recipes file
     #
-    # @yield [env] a block that defines environment variables for the Rake task;
-    #              optional
-    # @yieldparam [Hash] env the environment variables to set before executing
-    #                        the Rake task
+    # @yield [recipes] a block that customizes the Capistrano recipe(s)
+    #                  generated for the Rake task(s); optional
+    # @yieldparam [RecipeDefinition] recipes an interface for customizing the
+    #                                        Capistrano recipe(s) generated for
+    #                                        the Rake task(s)
     #
     # @return [Capistrano] the object
     #
     # @raise [ArgumentError] +named_arguments[:binding]+ is missing
     #
     # @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/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'
       end
 
       capistrano_context = binding.eval('self', __FILE__, __LINE__)
-      options = named_arguments.reject do |key, value|
-        key == :binding
-      end
       describe  task, capistrano_context
-      implement(task, capistrano_context, options, &block)
+      implement(task, capistrano_context, &block)
     end
 
   private
@@ -88,6 +82,11 @@ Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
       description.join
     end
 
+    def capture_recipe_definition(recipe_definition, &recipe_definition_block)
+      recipe_definition_block.call(recipe_definition) if recipe_definition_block
+      true
+    end
+
     def describe(task, capistrano_context)
       if (description = build_capistrano_description(task))
         capistrano_context.desc description
@@ -95,13 +94,18 @@ Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
       self
     end
 
-    def implement(task, capistrano_context, options, &env_block)
-      name_tokens = task[:name].split(':')
-      name_tokens << 'default' if task[:default]
+    def implement(task, capistrano_context, &recipe_definition_block)
+      name_tokens = tokenize_name(task)
+      recipe_definition = new_recipe_definition
+      capture_recipe_definition(recipe_definition, &recipe_definition_block)
+      env = nil
       rake = self.rake
-      # Define the recipe.
       block = lambda { |context|
-        context.task name_tokens.last, options do
+        recipe_name = name_tokens.last
+        if recipe_definition.rename
+          recipe_name = recipe_definition.rename.call(name_tokens.last)
+        end
+        context.task recipe_name, recipe_definition.options do
           arguments = Array(task[:parameters]).collect do |a|
             if (value = ENV[a.upcase])
               value = value.inspect
@@ -113,17 +117,26 @@ Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
           else
             arguments = "[#{arguments.join ','}]"
           end
-          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?
-          end
-          env_strings = env_hash.collect do |var_name, var_value|
-            "#{var_name}=#{var_value.inspect}"
+
+          unless env
+            env_strings = recipe_definition.env.collect do |var_name, var_value|
+              if var_name.nil? || var_value.nil?
+                nil
+              else
+                if var_value.is_a?(Proc)
+                  var_value = context.instance_eval do
+                    var_value.call
+                  end
+                end
+                "#{var_name}=#{var_value.inspect}"
+              end
+            end.compact
+            env = env_strings.empty? ? nil : (' ' + env_strings.join(' '))
           end
-          env = env_strings.empty? ? nil : (' ' + env_strings.join(' '))
-          command = "cd #{context.current_path} && " +
-                    "#{rake.remote_executable} "     +
+
+          path = recipe_definition.cd || context.current_path
+          path = path.call if path.respond_to?(:call)
+          command = "cd #{path} && #{rake.remote_executable} " +
                     "#{task[:name]}#{arguments}#{env}"
           context.run command
         end
@@ -139,6 +152,20 @@ Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
       self
     end
 
+    def new_rake(*arguments)
+      Rake.new(*arguments)
+    end
+
+    def new_recipe_definition(*arguments)
+      RecipeDefinition.new(*arguments)
+    end
+
+    def tokenize_name(task)
+      task[:name].split(':').tap do |result|
+        result << 'default' if task[:default]
+      end
+    end
+
   end
 
 end

data/lib/cape/capistrano_deprecated.rb

@@ -0,0 +1,165 @@
+require 'cape/capistrano'
+require 'cape/deprecation/capistrano_deprecated_define_rake_wrapper'
+require 'cape/recipe_definition_deprecated'
+require 'cape/xterm'
+
+module Cape
+
+  # Implements {Capistrano} with deprecated methods.
+  #
+  # @api private
+  class CapistranoDeprecated < Capistrano
+
+    # Defines a wrapper in Capistrano around the specified Rake _task_.
+    #
+    # @deprecated Use {Capistrano#define_rake_wrapper} instead.
+    #
+    # @param [Hash] task            metadata for a Rake task
+    # @param [Hash] named_arguments named arguments, including options to pass to
+    #                               the Capistrano +task+ method
+    #
+    # @option task [String]               :name        the name of the Rake task
+    # @option task [Array of String, nil] :parameters  the names of the Rake
+    #                                                  task's parameters, if any
+    # @option task [String]               :description documentation for the Rake
+    #                                                  task
+    #
+    # @option named_arguments [Binding] :binding            the Binding of your
+    #                                                       Capistrano recipes
+    #                                                       file
+    #
+    # @yield [env] a block that defines environment variables for the Rake task;
+    #              optional
+    # @yieldparam [Hash] env the environment variables to set before executing
+    #                        the Rake task
+    #
+    # @return [CapistranoDeprecated] the object
+    #
+    # @raise [ArgumentError] +named_arguments[:binding]+ is missing
+    #
+    # @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/configuration/actions/invocation.rb#L99-L144 Valid Capistrano 'task' method options
+    #
+    # @api public
+    def define_rake_wrapper(task, named_arguments, &block)
+      unless (binding = named_arguments[:binding])
+        raise ::ArgumentError, ':binding named argument is required'
+      end
+
+      deprecation.task            = task
+      deprecation.named_arguments = named_arguments
+
+      capistrano_context = binding.eval('self', __FILE__, __LINE__)
+      options = named_arguments.reject do |key, value|
+        key == :binding
+      end
+      describe  task, capistrano_context
+      implement(task, capistrano_context, options, &block)
+    end
+
+    # The object in which deprecated API usage is recorded.
+    #
+    # @return [Deprecation::Base]
+    def deprecation
+      @deprecation ||= Deprecation::CapistranoDeprecatedDefineRakeWrapper.new
+    end
+
+  private
+
+    def capture_recipe_definition(recipe_definition, &recipe_definition_block)
+      begin
+        super
+      rescue NoMethodError
+        unless @warned
+          deprecation.stream.puts XTerm.bold_and_foreground_red('*** DEPRECATED:') +
+                                  ' '                                              +
+                                  XTerm.bold('Referencing Capistrano variables '   +
+                                             'from Cape without wrapping them in ' +
+                                             'a block, a lambda, or another '      +
+                                             'callable object')
+          @warned = true
+        end
+        return false
+      end
+      true
+    end
+
+    def implement(task, capistrano_context, options, &env_block)
+      return super(task, capistrano_context, &env_block) if options.empty?
+
+      name_tokens = tokenize_name(task)
+      recipe_definition = new_recipe_definition(deprecation)
+      env = nil
+      if capture_recipe_definition(recipe_definition, &env_block)
+        env_strings = recipe_definition.env.collect do |var_name, var_value|
+          if var_name.nil? || var_value.nil?
+            nil
+          else
+            var_value = var_value.call if var_value.is_a?(Proc)
+            "#{var_name}=#{var_value.inspect}"
+          end
+        end.compact
+        env = env_strings.empty? ? nil : (' ' + env_strings.join(' '))
+      end
+      this = env ? nil : self
+      rake = self.rake
+      block = lambda { |context|
+        recipe_name = name_tokens.last
+        if recipe_definition.rename
+          recipe_name = recipe_definition.rename.call(name_tokens.last)
+        end
+        context.task recipe_name, options do
+          arguments = Array(task[:parameters]).collect do |a|
+            if (value = ENV[a.upcase])
+              value = value.inspect
+            end
+            value
+          end
+          if arguments.empty?
+            arguments = nil
+          else
+            arguments = "[#{arguments.join ','}]"
+          end
+
+          unless env
+            if this.instance_eval { capture_recipe_definition(recipe_definition, &env_block) }
+              env_strings = recipe_definition.env.collect do |var_name, var_value|
+                if var_name.nil? || var_value.nil?
+                  nil
+                else
+                  var_value = var_value.call if var_value.is_a?(Proc)
+                  "#{var_name}=#{var_value.inspect}"
+                end
+              end.compact
+              env = env_strings.empty? ? nil : (' ' + env_strings.join(' '))
+              this = nil
+            end
+          end
+
+          path = recipe_definition.cd || context.current_path
+          path = path.call if path.respond_to?(:call)
+          command = "cd #{path} && #{rake.remote_executable} " +
+                    "#{task[:name]}#{arguments}#{env}"
+          context.run command
+        end
+      }
+      # Nest the recipe inside its containing namespaces.
+      name_tokens[0...-1].reverse.each do |namespace_token|
+        inner_block = block
+        block = lambda { |context|
+          context.namespace(namespace_token, &inner_block)
+        }
+      end
+      block.call capistrano_context
+      self
+    end
+
+    def new_recipe_definition(*arguments)
+      arguments << deprecation if arguments.empty?
+      RecipeDefinitionDeprecated.new(*arguments)
+    end
+
+  end
+
+end