cape 1.0.0

data/features/support/env.rb

@@ -0,0 +1 @@
+require 'aruba/cucumber'

data/features/task_invocation/nonparameterized.feature

@@ -0,0 +1,69 @@
+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

@@ -0,0 +1,70 @@
+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.rb

@@ -0,0 +1,22 @@
+Dir.glob( File.expand_path( 'cape/*.rb', File.dirname( __FILE__ ))) do |f|
+  require "cape/#{File.basename f, '.rb'}"
+end
+
+# Contains the implementation of Cape.
+module Cape
+
+  extend DSL
+
+end
+
+# The method used to group Cape statements in a block.
+def Cape(&block)
+  Cape.module_eval do
+    @outer_self = block.binding.eval('self', __FILE__, __LINE__)
+    if 0 < block.arity
+      block.call self
+    else
+      module_eval(&block)
+    end
+  end
+end

data/lib/cape/capistrano.rb

@@ -0,0 +1,86 @@
+require 'cape/strings'
+
+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.
+    #
+    # The _task_ argument must be a Hash of the form:
+    #
+    #   {:name        => <String>,
+    #    :parameters  => <String Array or nil>,
+    #    :description => <String>}
+    def define(task, named_arguments={})
+      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
+      end
+      implement task, roles, capistrano, rake
+      self
+    end
+
+  private
+
+    def build_capistrano_description(task)
+      return nil unless task[:description]
+
+      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))
+        description << <<-end_description
+
+
+You must set environment #{noun} #{parameters_list}.
+        end_description
+      end
+      description.join
+    end
+
+    def implement(task, roles, capistrano_context, rake)
+      name = task[:name].split(':')
+      # Define the task.
+      block = lambda { |context|
+        context.task name.last, :roles => roles do
+          arguments = Array(task[:parameters]).collect do |a|
+            unless (value = ENV[a.upcase])
+              fail "Environment variable #{a.upcase} must be set"
+            end
+            value
+          end
+          if arguments.empty?
+            arguments = nil
+          else
+            arguments = "[#{arguments.join ','}]"
+          end
+          context.run "cd #{context.current_path} && " +
+                      "#{rake.remote_executable} #{name.join ':'}#{arguments}"
+        end
+      }
+      # Nest the task inside its containing namespaces.
+      name[0...-1].reverse.each do |namespace_token|
+        inner_block = block
+        block = lambda { |context|
+          context.namespace(namespace_token, &inner_block)
+        }
+      end
+      block.call capistrano_context
+    end
+
+  end
+
+end

data/lib/cape/core_ext.rb

@@ -0,0 +1,10 @@
+Dir.glob( File.expand_path( 'core_ext/*.rb', File.dirname( __FILE__ ))) do |f|
+  require "cape/core_ext/#{File.basename f, '.rb'}"
+end
+
+module Cape
+
+  # Contains extensions to core types.
+  module CoreExt; end
+
+end

data/lib/cape/core_ext/hash.rb

@@ -0,0 +1,24 @@
+module Cape
+
+  module CoreExt
+
+    # Contains extensions to the Hash core class.
+    module Hash
+
+      # Returns a copy of the Hash containing values only for the specified
+      # _keys_.
+      def slice(*keys)
+        ::Hash[select { |key, value| keys.include? key }]
+      end
+
+    end
+
+  end
+
+end
+
+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

@@ -0,0 +1,25 @@
+module Cape
+
+  module CoreExt
+
+    # Contains extensions to the 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_.
+      def <=>(other)
+        to_s <=> other.to_s
+      end
+
+    end
+
+  end
+
+end
+
+unless Symbol.instance_methods.collect(&:to_s).include?('<=>')
+  Symbol.class_eval do
+    include Cape::CoreExt::Symbol
+  end
+end

data/lib/cape/dsl.rb

@@ -0,0 +1,81 @@
+require 'cape/capistrano'
+require 'cape/rake'
+
+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.
+    #
+    # Tasks are yielded as Hash objects of the form:
+    #
+    #   {:name        => <String>,
+    #    :parameters  => <String Array or nil>,
+    #    :description => <String>}
+    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.
+    def local_rake_executable
+      rake.local_executable
+    end
+
+    # Sets the command used to run Rake on the local computer.
+    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.
+    def mirror_rake_tasks(task_expression=nil)
+      d = nil
+      rake.each_task task_expression do |t|
+        (d ||= deployment_library).define t, :binding => binding, :rake => rake
+      end
+      self
+    end
+
+    # Returns the command used to run Rake on remote computers. Defaults to
+    # Rake::DEFAULT_EXECUTABLE.
+    def remote_rake_executable
+      rake.remote_executable
+    end
+
+    # Sets the command used to run Rake on remote computers.
+    def remote_rake_executable=(value)
+      rake.remote_executable = value
+    end
+
+  private
+
+    def deployment_library
+      raise_unless_capistrano
+      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'
+      end
+    end
+
+    def rake
+      @rake ||= Rake.new
+    end
+
+  end
+
+end

data/lib/cape/rake.rb

@@ -0,0 +1,60 @@
+module Cape
+
+  # An abstraction of the Rake installation and available tasks.
+  class Rake
+
+    # The default command used to run Rake.
+    DEFAULT_EXECUTABLE = '/usr/bin/env rake'.freeze
+
+    # Sets the command used to run Rake on the local computer.
+    attr_writer :local_executable
+
+    # Sets the command used to run Rake on remote computers.
+    attr_writer :remote_executable
+
+    # Constructs a new Rake object with the specified _attributes_.
+    def initialize(attributes={})
+      attributes.each do |name, value|
+        send "#{name}=", value
+      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.
+    #
+    # Tasks are yielded as Hash objects of the form:
+    #
+    #   {:name        => <String>,
+    #    :parameters  => <String Array or nil>,
+    #    :description => <String>}
+    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|
+          t[:name]        = matches[1].strip
+          t[:parameters]  = matches[2].split(',') if matches[2]
+          t[:description] = matches[3]
+        end
+        yield task
+      end
+      self
+    end
+
+    # Returns the command used to run Rake on the local computer. Defaults to
+    # DEFAULT_EXECUTABLE.
+    def local_executable
+      @local_executable ||= DEFAULT_EXECUTABLE
+    end
+
+    # Returns the command used to run Rake on remote computers. Defaults to
+    # DEFAULT_EXECUTABLE.
+    def remote_executable
+      @remote_executable ||= DEFAULT_EXECUTABLE
+    end
+
+  end
+
+end