cape 1.6.2 → 1.7.0

data/lib/cape/core_ext.rb

@@ -5,6 +5,8 @@ end
 module Cape
 
   # Contains extensions to core types.
+  #
+  # @api private
   module CoreExt; end
 
 end

data/lib/cape/deprecation.rb

@@ -0,0 +1,12 @@
+::Dir.glob(::File.expand_path('../deprecation/*.rb', __FILE__)) do |f|
+  require "cape/deprecation/#{::File.basename f, '.rb'}"
+end
+
+module Cape
+
+  # Contains implementations of deprecation stream printers.
+  #
+  # @api private
+  module Deprecation; end
+
+end

data/lib/cape/deprecation/base.rb

@@ -0,0 +1,59 @@
+require 'cape/xterm'
+
+module Cape
+
+  module Deprecation
+
+    # Prints to a stream a message related to deprecated API usage.
+    #
+    # @abstract
+    class Base
+
+      # Sets the value of {#stream}.
+      #
+      # @param [IO] value a new value for {#stream}
+      #
+      # @return [IO] _value_
+      attr_writer :stream
+
+      # Formats {#message_content} for display.
+      #
+      # @return [String] the full message
+      def formatted_message
+        [].tap do |fragments|
+          fragments << XTerm.bold_and_foreground_red('*** DEPRECATED:')
+          fragments << ' '
+          fragments << XTerm.bold(message_content)
+        end.join
+      end
+
+      # Prepares a message based on deprecated API usage.
+      #
+      # @raise [NotImplementedError]
+      #
+      # @abstract
+      def message_content
+        raise ::NotImplementedError
+      end
+
+      # The stream to which deprecation messages are printed. Defaults to
+      # $stderr.
+      #
+      # @return [IO]
+      def stream
+        @stream ||= $stderr
+      end
+
+      # Writes {#formatted_message} to {#stream}.
+      #
+      # @return [Base] the object
+      def write_formatted_message_to_stream
+        stream.puts formatted_message
+        self
+      end
+
+    end
+
+  end
+
+end

data/lib/cape/deprecation/capistrano_deprecated_define_rake_wrapper.rb

@@ -0,0 +1,168 @@
+require 'cape/deprecation/base'
+require 'cape/hash_list'
+
+module Cape
+
+  module Deprecation
+
+    # Prints to a stream a message related to deprecated usage of
+    # {CapistranoDeprecated#define_rake_wrapper}.
+    class CapistranoDeprecatedDefineRakeWrapper < Base
+
+      # The _task_ argument to {CapistranoDeprecated#define_rake_wrapper}.
+      #
+      # @return [Symbol, String]
+      attr_accessor :task
+
+      # Environment variable names and values set in a call to
+      # {CapistranoDeprecated#define_rake_wrapper}.
+      #
+      # @return [HashList]
+      def env
+        @env ||= HashList.new
+      end
+
+      # Prepares a message based on deprecated usage of
+      # {CapistranoDeprecated#define_rake_wrapper}.
+      #
+      # @return [String] a deprecation message
+      def message_content
+        [].tap do |fragments|
+          fragments << message_content_actual
+          fragments << '. '
+          fragments << message_content_expected
+        end.join
+      end
+
+      # The _named_arguments_ argument to
+      # {CapistranoDeprecated#define_rake_wrapper}.
+      #
+      # @return [HashList]
+      def named_arguments
+        @named_arguments ||= HashList.new
+      end
+
+      # Sets the value of {#named_arguments}.
+      #
+      # @param [Hash] value a new value for {#named_arguments}
+      #
+      # @return [HashList] _value_
+      def named_arguments=(value)
+        @named_arguments = HashList.new(value)
+      end
+
+    private
+
+      def binding_named_arguments
+        named_arguments.select do |name, value|
+          name == :binding
+        end
+      end
+
+      def message_content_env_actual
+        [].tap do |fragments|
+          env_entries = env.collect do |name, value|
+            "env[#{name.inspect}] = #{value.inspect}"
+          end
+          unless env_entries.empty?
+            fragments << ' { |env| '
+            fragments << env_entries.join('; ')
+            fragments << ' }'
+          end
+        end.join
+      end
+
+      def message_content_options_and_env_expected
+        [].tap do |fragments|
+          unless named_arguments.empty? && env.empty?
+            fragments << ' { |recipes| '
+
+            options_entries = options.collect do |name, value|
+              "recipes.options[#{name.inspect}] = #{value.inspect}"
+            end
+            env_entries = env.collect do |name, value|
+              "recipes.env[#{name.inspect}] = #{value.inspect}"
+            end
+            fragments << (options_entries + env_entries).join('; ')
+
+            fragments << ' }'
+          end
+        end.join
+      end
+
+      def message_content_actual
+        [].tap do |fragments|
+          fragments << '`'
+          fragments << message_content_method_name
+          fragments << message_content_task_and_named_arguments_actual
+          fragments << message_content_env_actual
+          fragments << '`'
+        end.join
+      end
+
+      def message_content_expected
+        [].tap do |fragments|
+          fragments << 'Use this instead: '
+          fragments << '`'
+          fragments << message_content_method_name
+          fragments << message_content_task_and_named_arguments_expected
+          fragments << message_content_options_and_env_expected
+          fragments << '`'
+        end.join
+      end
+
+      def message_content_method_name
+        'define_rake_wrapper'
+      end
+
+      def message_content_task_and_named_arguments_actual
+        [].tap do |fragments|
+          arguments = []
+          arguments << task.inspect unless task.nil?
+          named_arguments_entries = named_arguments.collect do |name, value|
+            "#{name.inspect} => #{value.inspect}"
+          end
+          unless named_arguments_entries.empty?
+            arguments << named_arguments_entries.join(', ')
+          end
+          unless arguments.empty?
+            if env.empty?
+              fragments << " #{arguments.join ', '}"
+            else
+              fragments << "(#{arguments.join ', '})"
+            end
+          end
+        end.join
+      end
+
+      def message_content_task_and_named_arguments_expected
+        [].tap do |fragments|
+          arguments = []
+          arguments << task.inspect unless task.nil?
+          binding_named_arguments_entries = binding_named_arguments.collect do |name, value|
+            "#{name.inspect} => #{value.inspect}"
+          end
+          unless binding_named_arguments_entries.empty?
+            arguments << binding_named_arguments_entries.join(', ')
+          end
+          unless arguments.empty?
+            if options.empty? && env.empty?
+              fragments << " #{arguments.join ', '}"
+            else
+              fragments << "(#{arguments.join ', '})"
+            end
+          end
+        end.join
+      end
+
+      def options
+        named_arguments.reject do |name, value|
+          name == :binding
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/cape/deprecation/dsl_deprecated_mirror_rake_tasks.rb

@@ -0,0 +1,145 @@
+require 'cape/deprecation/base'
+require 'cape/hash_list'
+
+module Cape
+
+  module Deprecation
+
+    # Prints to a stream a message related to deprecated usage of
+    # {DSLDeprecated#mirror_rake_tasks}.
+    class DSLDeprecatedMirrorRakeTasks < Base
+
+      # The _task_expression_ argument to {DSLDeprecated#mirror_rake_tasks}.
+      #
+      # @return [Symbol, String]
+      attr_accessor :task_expression
+
+      # Environment variable names and values set in a call to
+      # {DSLDeprecated#mirror_rake_tasks}.
+      #
+      # @return [HashList]
+      def env
+        @env ||= HashList.new
+      end
+
+      # Prepares a message based on deprecated usage of
+      # {DSLDeprecated#mirror_rake_tasks}.
+      #
+      # @return [String] a deprecation message
+      def message_content
+        [].tap do |fragments|
+          fragments << message_content_actual
+          fragments << '. '
+          fragments << message_content_expected
+        end.join
+      end
+
+      # The _options_ argument to {DSLDeprecated#mirror_rake_tasks}.
+      #
+      # @return [HashList]
+      def options
+        @options ||= HashList.new
+      end
+
+      # Sets the value of {#options}.
+      #
+      # @param [Hash] value a new value for {#options}
+      #
+      # @return [HashList] _value_
+      def options=(value)
+        @options = HashList.new(value)
+      end
+
+    private
+
+      def message_content_env_actual
+        [].tap do |fragments|
+          env_entries = env.collect do |name, value|
+            "env[#{name.inspect}] = #{value.inspect}"
+          end
+          unless env_entries.empty?
+            fragments << ' { |env| '
+            fragments << env_entries.join('; ')
+            fragments << ' }'
+          end
+        end.join
+      end
+
+      def message_content_options_and_env_expected
+        [].tap do |fragments|
+          unless options.empty? && env.empty?
+            fragments << ' { |recipes| '
+
+            options_entries = options.collect do |name, value|
+              "recipes.options[#{name.inspect}] = #{value.inspect}"
+            end
+            env_entries = env.collect do |name, value|
+              "recipes.env[#{name.inspect}] = #{value.inspect}"
+            end
+            fragments << (options_entries + env_entries).join('; ')
+
+            fragments << ' }'
+          end
+        end.join
+      end
+
+      def message_content_actual
+        [].tap do |fragments|
+          fragments << '`'
+          fragments << message_content_method_name
+          fragments << message_content_task_expression_and_options_actual
+          fragments << message_content_env_actual
+          fragments << '`'
+        end.join
+      end
+
+      def message_content_expected
+        [].tap do |fragments|
+          fragments << 'Use this instead: '
+          fragments << '`'
+          fragments << message_content_method_name
+          fragments << message_content_task_expression_expected
+          fragments << message_content_options_and_env_expected
+          fragments << '`'
+        end.join
+      end
+
+      def message_content_method_name
+        'mirror_rake_tasks'
+      end
+
+      def message_content_task_expression_and_options_actual
+        [].tap do |fragments|
+          arguments = []
+          arguments << task_expression.inspect unless task_expression.nil?
+          options_entries = options.collect do |name, value|
+            "#{name.inspect} => #{value.inspect}"
+          end
+          arguments << options_entries.join(', ') unless options_entries.empty?
+          unless arguments.empty?
+            if env.empty?
+              fragments << " #{arguments.join ', '}"
+            else
+              fragments << "(#{arguments.join ', '})"
+            end
+          end
+        end.join
+      end
+
+      def message_content_task_expression_expected
+        [].tap do |fragments|
+          unless task_expression.nil?
+            if options.empty? && env.empty?
+              fragments << " #{task_expression.inspect}"
+            else
+              fragments << "(#{task_expression.inspect})"
+            end
+          end
+        end.join
+      end
+
+    end
+
+  end
+
+end

data/lib/cape/dsl.rb

@@ -92,59 +92,26 @@ module Cape
 
     # Defines Rake tasks as Capistrano recipes.
     #
-    # @overload mirror_rake_tasks(task_expression=nil)
-    #   Defines Rake tasks as Capistrano recipes.
-    #
-    #   @param [String, Symbol] task_expression the full name of a Rake task or
-    #                                           namespace to filter
-    #
-    #   @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 [DSL] the object
-    #
-    # @overload mirror_rake_tasks(capistrano_task_options={})
-    #   Defines all Rake tasks as Capistrano recipes with options.
-    #
-    #   @param [Hash] capistrano_task_options options to pass to the Capistrano
-    #                                         +task+ method; optional
-    #
-    #   @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 [DSL] the object
-    #
-    # @overload mirror_rake_tasks(task_expression, capistrano_task_options={})
-    #   Defines specific Rake tasks as Capistrano recipes with options.
-    #
-    #   @param [String, Symbol] task_expression         the full name of a Rake
-    #                                                   task or namespace to
-    #                                                   filter
-    #   @param [Hash]           capistrano_task_options options to pass to the
-    #                                                   Capistrano +task+ method;
-    #                                                   optional
+    # @param [String, Symbol] task_expression the full name of a Rake task or
+    #                                         namespace to filter
     #
-    #   @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 [DSL] the object
+    # @return [DSL] the object
     #
     # @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/configuration/actions/invocation.rb#L99-L144 Valid Capistrano ‘task’ method options
-    #
     # @example Mirroring all Rake tasks
     #   # config/deploy.rb
     #
     #   require 'cape'
     #
     #   Cape do
+    #     # Create Capistrano recipes for all Rake tasks.
     #     mirror_rake_tasks
     #   end
     #
@@ -159,7 +126,7 @@ module Cape
     #     mirror_rake_tasks :foo
     #   end
     #
-    # @example Mirroring Rake tasks that require Capistrano recipe options and/or environment variables
+    # @example Mirroring Rake tasks that require renaming, Capistrano recipe options, path switching, and/or environment variables
     #   # config/deploy.rb
     #
     #   require 'cape'
@@ -167,13 +134,37 @@ module Cape
     #   Cape do
     #     # Display defined Rails routes on application server remote machines
     #     # only.
-    #     mirror_rake_tasks :routes, :roles => :app
+    #     mirror_rake_tasks :routes do |recipes|
+    #       recipes.options[:roles] = :app
+    #     end
     #
     #     # 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
+    #     mirror_rake_tasks 'db:migrate' do |recipes|
+    #       recipes.options[:roles] = :app
+    #       recipes.env['RAILS_ENV'] = lambda { rails_env }
+    #     end
+    #
+    #     # Support a Rake task that must be run on application server remote
+    #     # machines only, and in the remote directory 'release_path' instead of
+    #     # the default, 'current_path'.
+    #     before 'deploy:symlink', :spec
+    #     mirror_rake_tasks :spec do |recipes|
+    #       recipes.cd { release_path }
+    #       recipes.options[:roles] = :app
+    #     end
+    #
+    #     # Avoid collisions with the existing Ruby method #test, run tests 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 :test do |recipes|
+    #       recipes.rename do |rake_task_name|
+    #         "#{rake_task_name}_task"
+    #       end
+    #       recipes.options[:roles] = :app
+    #       recipes.env['RAILS_ENV'] = lambda { rails_env }
     #     end
     #   end
     #
@@ -187,19 +178,9 @@ module Cape
     #       cape.mirror_rake_tasks
     #     end
     #   end
-    def mirror_rake_tasks(*arguments, &block)
-      arguments_count = arguments.length
-      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)')
-      end
-
-      task_expression = arguments.first
-      options[:binding] = binding
+    def mirror_rake_tasks(task_expression=nil, &block)
       rake.each_task task_expression do |t|
-        deployment_library.define_rake_wrapper(t, options, &block)
+        deployment_library.define_rake_wrapper(t, :binding => binding, &block)
       end
       self
     end
@@ -235,7 +216,7 @@ module Cape
 
     # Returns an abstraction of the Rake installation and available tasks.
     def rake
-      @rake ||= Rake.new
+      @rake ||= new_rake
     end
 
   private
@@ -244,7 +225,15 @@ module Cape
       return @deployment_library if @deployment_library
 
       raise_unless_capistrano
-      @deployment_library = Capistrano.new(:rake => rake)
+      @deployment_library = new_capistrano(:rake => rake)
+    end
+
+    def new_capistrano(*arguments)
+      Capistrano.new(*arguments)
+    end
+
+    def new_rake(*arguments)
+      Rake.new(*arguments)
     end
 
     def raise_unless_capistrano