cape 1.1.0 → 1.2.0

data/features/step_definitions.rb

@@ -21,6 +21,9 @@ Given 'a full-featured Rakefile' do
     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

data/lib/cape/capistrano.rb

@@ -1,3 +1,4 @@
+require 'cape/rake'
 require 'cape/util'
 
 module Cape
@@ -5,56 +6,66 @@ module Cape
   # An abstraction of the Capistrano installation.
   class Capistrano
 
-    # Defines the specified _task_ as a Capistrano task.
+    # A Cape abstraction of the Rake installation.
+    attr_accessor :rake
+
+    # Constructs a new Capistrano object with the specified _attributes_.
+    def initialize(attributes={})
+      attributes.each do |name, value|
+        send "#{name}=", value
+      end
+      self.rake ||= Rake.new
+    end
+
+    # Defines a wrapper in Capistrano around the specified Rake _task_.
     #
-    # @param [Hash] task            metadata for a task
-    # @param [Hash] named_arguments named arguments
+    # @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 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 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
-    # @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_
+    # @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 [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)
+    # @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
+    def define_rake_wrapper(task, named_arguments, &block)
       unless (binding = named_arguments[:binding])
         raise ::ArgumentError, ':binding named argument is required'
       end
-      unless (rake = named_arguments[:rake])
-        raise ::ArgumentError, ':rake named argument is required'
-      end
-      roles = named_arguments[:roles] || :app
 
-      capistrano = binding.eval('self', __FILE__, __LINE__)
-      if (description = build_capistrano_description(task))
-        capistrano.desc description
+      capistrano_context = binding.eval('self', __FILE__, __LINE__)
+      options = named_arguments.reject do |key, value|
+        key == :binding
       end
-      implement task, roles, capistrano, rake
-      self
+      describe( task, capistrano_context, options, &block)
+      implement(task, capistrano_context, options, &block)
     end
 
   private
 
-    def build_capistrano_description(task)
+    def build_capistrano_description(task, options, &block)
       return nil unless task[:description]
 
       description = [task[:description]]
       description << '.' unless task[:description].end_with?('.')
+
       unless (parameters = Array(task[:parameters])).empty?
         noun            = Util.pluralize('variable', parameters.length)
         parameters_list = Util.to_list_phrase(parameters.collect(&:upcase))
@@ -62,20 +73,30 @@ module Cape
         noun_phrase     = (parameters.length == 1) ?
                           "a #{singular}"          :
                           Util.pluralize(singular)
-        description << <<-end_description
+        description << <<-end_fragment
 
 
-Set environment #{noun} #{parameters_list} to pass #{noun_phrase}.
-        end_description
+Set environment #{noun} #{parameters_list} if you want to pass #{noun_phrase}.
+        end_fragment
       end
+
       description.join
     end
 
-    def implement(task, roles, capistrano_context, rake)
-      name = task[:name].split(':')
-      # Define the task.
+    def describe(task, capistrano_context, options, &block)
+      if (description = build_capistrano_description(task, options, &block))
+        capistrano_context.desc description
+      end
+      self
+    end
+
+    def implement(task, capistrano_context, options, &env_block)
+      name_tokens = task[:name].split(':')
+      name_tokens << 'default' if task[:default]
+      rake = self.rake
+      # Define the recipe.
       block = lambda { |context|
-        context.task name.last, :roles => roles do
+        context.task name_tokens.last, options do
           arguments = Array(task[:parameters]).collect do |a|
             if (value = ENV[a.upcase])
               value = value.inspect
@@ -87,18 +108,27 @@ Set environment #{noun} #{parameters_list} to pass #{noun_phrase}.
           else
             arguments = "[#{arguments.join ','}]"
           end
-          context.run "cd #{context.current_path} && " +
-                      "#{rake.remote_executable} #{name.join ':'}#{arguments}"
+          env_hash = {}
+          env_block.call(env_hash) if env_block
+          env_strings = env_hash.collect do |var_name, var_value|
+            "#{var_name}=#{var_value.inspect}"
+          end
+          env = env_strings.empty? ? nil : (' ' + env_strings.join(' '))
+          command = "cd #{context.current_path} && " +
+                    "#{rake.remote_executable} "     +
+                    "#{task[:name]}#{arguments}#{env}"
+          context.run command
         end
       }
-      # Nest the task inside its containing namespaces.
-      name[0...-1].reverse.each do |namespace_token|
+      # 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
 
   end

data/lib/cape/dsl.rb

@@ -74,8 +74,8 @@ module Cape
       rake.local_executable = value
     end
 
-    # Makes the use of a block parameter optional by forwarding non-Cape method
-    # calls to the containing binding.
+    # Makes the use of a Cape 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_
@@ -85,13 +85,54 @@ module Cape
       @outer_self.send(method, *args, &block)
     end
 
-    # Defines Rake tasks as Capistrano tasks.
+    # Defines Rake tasks as Capistrano recipes.
     #
-    # @param [String, Symbol] task_expression the full name of a Rake task or
-    #                                         namespace to filter; optional
-    # @return [DSL] the object
+    # @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; 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(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
+    #
+    #   @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
     #
-    # @note Any parameters that the Rake tasks have are integrated via environment variables, since Capistrano does not support task parameters per se.
+    # @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
     #
     # @example Mirroring all Rake tasks
     #   # config/deploy.rb
@@ -102,13 +143,24 @@ module Cape
     #     mirror_rake_tasks
     #   end
     #
-    # @example Mirroring some Rake tasks
+    # @example Mirroring specific Rake tasks
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     mirror_rake_tasks 'log:clear'
+    #   end
+    #
+    # @example Mirroring specific Rake tasks with Capistrano recipe options and/or environment variables
     #   # config/deploy.rb
     #
     #   require 'cape'
     #
     #   Cape do
-    #     mirror_rake_tasks :foo
+    #     mirror_rake_tasks :db, :roles => :app do |env|
+    #       env['RAILS_ENV'] = rails_env
+    #     end
     #   end
     #
     # @example Mirroring Rake tasks into a Capistrano namespace
@@ -121,10 +173,19 @@ module Cape
     #       cape.mirror_rake_tasks
     #     end
     #   end
-    def mirror_rake_tasks(task_expression=nil)
-      d = nil
+    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
       rake.each_task task_expression do |t|
-        (d ||= deployment_library).define t, :binding => binding, :rake => rake
+        deployment_library.define_rake_wrapper(t, options, &block)
       end
       self
     end
@@ -157,8 +218,10 @@ module Cape
   private
 
     def deployment_library
+      return @deployment_library if @deployment_library
+
       raise_unless_capistrano
-      Capistrano.new
+      @deployment_library = Capistrano.new(:rake => rake)
     end
 
     def raise_unless_capistrano

data/lib/cape/rake.rb

@@ -25,6 +25,17 @@ module Cape
       end
     end
 
+    # Compares the Rake object to another.
+    #
+    # @param [Object] other another object
+    # @return [true]  the Rake object is equal to _other_
+    # @return [false] the Rake object is unequal to _other_
+    def ==(other)
+      other.kind_of?(Rake)                          &&
+      (other.local_executable  == local_executable) &&
+      (other.remote_executable == remote_executable)
+    end
+
     # Enumerates Rake tasks.
     #
     # @param [String, Symbol] task_expression the full name of a task or
@@ -36,17 +47,30 @@ module Cape
     #
     # @return [Rake] the object
     def each_task(task_expression=nil)
-      task_expression = " #{task_expression}" if task_expression
-      command = "#{local_executable} --tasks #{task_expression}"
-      `#{command}`.each_line do |l|
-        matches = l.chomp.match(/^rake (.+?)(?:\[(.+?)\])?\s+# (.+)/)
-        task = {}.tap do |t|
+      previous_task, this_task = nil, nil
+      task_expression = task_expression                       ?
+                        ::Regexp.escape(task_expression.to_s) :
+                        '.+?'
+      regexp = /^rake (#{task_expression}(?::.+?)?)(?:\[(.+?)\])?\s+# (.+)/
+      `#{local_executable} --tasks 2> /dev/null`.each_line do |l|
+        unless (matches = l.chomp.match(regexp))
+          next
+        end
+
+        previous_task = this_task
+        this_task = {}.tap do |t|
           t[:name]        = matches[1].strip
           t[:parameters]  = matches[2].split(',') if matches[2]
           t[:description] = matches[3]
         end
-        yield task
+        if previous_task
+          all_but_last_segment = this_task[:name].split(':')[0...-1].join(':')
+          previous_task[:default] = (all_but_last_segment ==
+                                     previous_task[:name])
+          yield previous_task
+        end
       end
+      yield this_task if this_task
       self
     end
 

data/lib/cape/version.rb

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

data/spec/cape/capistrano_spec.rb

@@ -0,0 +1,16 @@
+require 'cape/capistrano'
+require 'cape/rake'
+
+describe Cape::Capistrano do
+  describe 'without specified attributes' do
+    its(:rake) { should == Cape::Rake.new }
+  end
+
+  describe 'with specified attributes' do
+    subject {
+      described_class.new :rake => 'I see you have the machine that goes "Bing!"'
+    }
+
+    its(:rake) { should == 'I see you have the machine that goes "Bing!"' }
+  end
+end

data/spec/cape/dsl_spec.rb

@@ -19,7 +19,7 @@ describe Cape::DSL do
 
   before :each do
     Cape::Capistrano.stub!(:new).and_return mock_capistrano
-    Cape::Rake.stub!(:new).and_return mock_rake
+    Cape::Rake.      stub!(:new).and_return mock_rake
   end
 
   describe 'when sent #each_rake_task' do
@@ -47,52 +47,131 @@ describe Cape::DSL do
       subject.stub! :raise_unless_capistrano
     end
 
-    def do_mirror_rake_tasks
-      subject.mirror_rake_tasks task_expression
+    def do_mirror_rake_tasks(*arguments, &block)
+      subject.mirror_rake_tasks(*arguments, &block)
     end
 
-    it 'should collect Rake#each_task' do
-      mock_rake.should_receive(:each_task).with task_expression
-      do_mirror_rake_tasks
+    describe 'with two scalar arguments' do
+      specify do
+        lambda {
+          do_mirror_rake_tasks task_expression, task_expression
+        }.should raise_error(ArgumentError,
+                             'wrong number of arguments (2 for 0 or 1, plus ' +
+                             'an options hash)')
+      end
     end
 
-    it 'should verify that Capistrano is in use' do
-      subject.should_receive :raise_unless_capistrano
-      do_mirror_rake_tasks
-    end
+    shared_examples_for 'a successful call' do |task_expression_in_use,
+                                                options_in_use|
+      it 'should collect Rake#each_task' do
+        mock_rake.should_receive(:each_task).with task_expression_in_use
+        do_mirror_rake_tasks
+      end
 
-    describe 'should Capistrano#define Rake#each_task' do
-      it 'with the expected task' do
-        mock_capistrano.should_receive(:define).with do |task, options|
-          task == {:name => task_expression}
-        end
+      it 'should verify that Capistrano is in use' do
+        subject.should_receive :raise_unless_capistrano
         do_mirror_rake_tasks
       end
 
-      it 'with the expected named options' do
-        mock_capistrano.should_receive(:define).with do |task, opts|
-          opts.keys.sort == [:binding, :rake]
+      describe 'should Capistrano#define_rake_wrapper for Rake#each_task' do
+        specify 'with the expected task' do
+          mock_capistrano.should_receive(:define_rake_wrapper).with do |task,
+                                                                        named_arguments|
+            task == {:name => task_expression}
+          end
+          do_mirror_rake_tasks
+        end
+
+        specify 'with the expected named options' do
+          mock_capistrano.should_receive(:define_rake_wrapper).with do |task,
+                                                                        named_arguments|
+            named_arguments.keys.sort == ([:binding] + options_in_use.keys).sort
+          end
+          do_mirror_rake_tasks
+        end
+
+        specify 'with a :binding option' do
+          mock_capistrano.should_receive(:define_rake_wrapper).with do |task,
+                                                                        named_arguments|
+            named_arguments[:binding].is_a? Binding
+          end
+          do_mirror_rake_tasks
+        end
+
+        specify 'with any provided extra options' do
+          mock_capistrano.should_receive(:define_rake_wrapper).with do |task,
+                                                                        named_arguments|
+            named_arguments.slice(*options_in_use.keys) == options_in_use
+          end
+          do_mirror_rake_tasks
         end
-        do_mirror_rake_tasks
       end
 
-      it 'with a :binding option' do
-        mock_capistrano.should_receive(:define).with do |task, options|
-          options[:binding].is_a? Binding
+      it 'should return itself' do
+        do_mirror_rake_tasks.should == subject
+      end
+    end
+
+    describe 'with one scalar argument, an options hash, and a block' do
+      def do_mirror_rake_tasks
+        super 'task:expression', :bar => :baz do |env|
+          env['AN_ENV_VAR'] = 'an environment variable'
         end
-        do_mirror_rake_tasks
       end
 
-      it 'with the expected :rake option' do
-        mock_capistrano.should_receive(:define).with do |task, options|
-          options[:rake] == mock_rake
+      it_should_behave_like 'a successful call', 'task:expression', :bar => :baz
+    end
+
+    describe 'with one scalar argument and an options hash' do
+      def do_mirror_rake_tasks
+        super 'task:expression', :bar => :baz
+      end
+
+      it_should_behave_like 'a successful call', 'task:expression', :bar => :baz
+    end
+
+    describe 'with an options hash and a block' do
+      def do_mirror_rake_tasks
+        super :bar => :baz do |env|
+          env['AN_ENV_VAR'] = 'an environment variable'
         end
-        do_mirror_rake_tasks
       end
+
+      it_should_behave_like 'a successful call', nil, :bar => :baz
     end
 
-    it 'should return itself' do
-      do_mirror_rake_tasks.should == subject
+    describe 'with an options hash' do
+      def do_mirror_rake_tasks
+        super :bar => :baz
+      end
+
+      it_should_behave_like 'a successful call', nil, :bar => :baz
+    end
+
+    describe 'with one scalar argument and a block' do
+      def do_mirror_rake_tasks
+        super 'task:expression' do |env|
+          env['AN_ENV_VAR'] = 'an environment variable'
+        end
+      end
+
+      it_should_behave_like('a successful call', 'task:expression', {})
+    end
+
+    describe 'with one scalar argument' do
+      def do_mirror_rake_tasks
+        super 'task:expression'
+      end
+
+      it_should_behave_like('a successful call', 'task:expression', {})
+    end
+
+    describe 'without arguments' do
+      def do_mirror_rake_tasks
+        super
+      end
+
+      it_should_behave_like('a successful call', nil, {})
     end
   end