cape 1.6.2 → 1.7.0

data/lib/cape/dsl_deprecated.rb

@@ -0,0 +1,157 @@
+require 'cape/capistrano_deprecated'
+require 'cape/deprecation/capistrano_deprecated_define_rake_wrapper'
+require 'cape/deprecation/dsl_deprecated_mirror_rake_tasks'
+
+module Cape
+
+  # Implements deprecated methods of {DSL}.
+  #
+  # @api private
+  module DSLDeprecated
+
+    # The stream to which deprecation messages are printed.
+    #
+    # @return [Deprecation::Base]
+    def deprecation
+      @deprecation ||= Deprecation::DSLDeprecatedMirrorRakeTasks.new
+    end
+
+    # 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 [RecipeDefinitionDeprecated] env the environment variables to
+    #                                                set before executing the
+    #                                                Rake task
+    #
+    #   @return [DSLDeprecated] the object
+    #
+    # @overload mirror_rake_tasks(capistrano_task_options={})
+    #   Defines all Rake tasks as Capistrano recipes with options.
+    #
+    #   @deprecated Use {RecipeDefinition#options} instead.
+    #
+    #   @param [Hash] capistrano_task_options options to pass to the Capistrano
+    #                                         +task+ method
+    #
+    #   @yield [env] a block that defines environment variables for the Rake
+    #                task; optional
+    #   @yieldparam [RecipeDefinitionDeprecated] env the environment variables to
+    #                                                set before executing the
+    #                                                Rake task
+    #
+    #   @return [DSLDeprecated] the object
+    #
+    # @overload mirror_rake_tasks(task_expression, capistrano_task_options={})
+    #   Defines specific Rake tasks as Capistrano recipes with options.
+    #
+    #   @deprecated Use {RecipeDefinition#options} instead.
+    #
+    #   @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
+    #
+    #   @yield [env] a block that defines environment variables for the Rake
+    #                task; optional
+    #   @yieldparam [RecipeDefinitionDeprecated] env the environment variables to
+    #                                                set before executing the
+    #                                                Rake task
+    #
+    #   @return [DSLDeprecated] 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
+    #     mirror_rake_tasks
+    #   end
+    #
+    # @example Mirroring some Rake tasks, but not others
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     # Create Capistrano recipes for the Rake task 'foo' and/or for the
+    #     # tasks in the 'foo' namespace.
+    #     mirror_rake_tasks :foo
+    #   end
+    #
+    # @example Mirroring Rake tasks that require Capistrano recipe options and/or environment variables
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   Cape do
+    #     # 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
+    #
+    # @example Mirroring Rake tasks into a Capistrano namespace
+    #   # config/deploy.rb
+    #
+    #   require 'cape'
+    #
+    #   namespace :rake_tasks do
+    #     Cape do |cape|
+    #       cape.mirror_rake_tasks
+    #     end
+    #   end
+    #
+    # @api public
+    def mirror_rake_tasks(*arguments, &block)
+      arguments_count = arguments.length
+      options = arguments.last.is_a?(::Hash) ? arguments.pop.dup : {}
+      deprecation.task_expression = arguments.first
+      deprecation.options = options.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|
+        deployment_library.define_rake_wrapper(t, options, &block)
+      end
+      deployment_library.deprecation.env.each do |name, value|
+        deprecation.env[name] = value
+      end
+      unless deprecation.options.empty? && deprecation.env.empty?
+        deprecation.write_formatted_message_to_stream
+      end
+      self
+    end
+
+  private
+
+    def new_capistrano(*arguments)
+      CapistranoDeprecated.new(*arguments)
+    end
+
+  end
+
+end

data/lib/cape/hash_list.rb

@@ -7,6 +7,8 @@ module Cape
   #
   # This class exists because in Ruby v1.8.7 and earlier, Hash did not preserve
   # the insertion order of keys.
+  #
+  # @api private
   class HashList < ::Array
 
     # Constructs a new HashList using the specified _arguments_.

data/lib/cape/recipe_definition.rb

@@ -0,0 +1,103 @@
+require 'cape/hash_list'
+
+module Cape
+
+  # Determines how a Capistrano recipe will be defined.
+  class RecipeDefinition
+
+    # The remote directory from which Rake tasks will be executed.
+    #
+    # @overload cd
+    #   The remote directory from which Rake tasks will be executed.
+    #
+    #   @return [String, Proc] the value or a block that returns the value
+    #
+    # @overload cd(path)
+    #   Sets the remote directory from which Rake tasks will be executed.
+    #
+    #   @param [String, Proc] path the value or a callable object that returns
+    #                              the value
+    #
+    #   @return [String, Proc] _path_
+    #
+    #   @raise [ArgumentError] _path_ is a callable object that has parameters
+    #
+    # @overload cd(&block)
+    #   Sets the remote directory from which Rake tasks will be executed.
+    #
+    #   @yieldreturn [String] the value
+    #
+    #   @return [String, Proc] _block_
+    #
+    #   @raise [ArgumentError] _block_ has parameters
+    def cd(path=nil, &block)
+      if (cd = (path || block))
+        if cd.respond_to?(:arity)
+          case cd.arity
+            when -1
+              # Lambda: good
+            when 0
+              # Good
+            else
+              raise ::ArgumentError, "Must have 0 parameters but has #{cd.arity}"
+          end
+        end
+
+        @cd = cd
+      else
+        @cd
+      end
+    end
+
+    # A hash of remote environment variables.
+    #
+    # @return [HashList] the desired environment of the remote computer
+    def env
+      @env ||= HashList.new
+    end
+
+    # A hash of Capistrano recipe options to pass to the Capistrano +task+
+    # method.
+    #
+    # @return [HashList] the desired Capistrano recipe options
+    #
+    # @see http://github.com/capistrano/capistrano/blob/master/lib/capistrano/configuration/actions/invocation.rb#L99-L144 Valid Capistrano 'task' method options
+    def options
+      @options ||= HashList.new
+    end
+
+    # How Rake tasks will be named when they are mirrored as Capistrano recipes.
+    #
+    # @overload rename
+    #   How Rake tasks will be named when they are mirrored as Capistrano
+    #   recipes.
+    #
+    #   @return [Proc] the block that generates a Capistrano recipe name from a
+    #                  Rake task name
+    #
+    # @overload rename(&block)
+    #   Determines how Rake tasks will be named when they are mirrored as
+    #   Capistrano recipes.
+    #
+    #   @yield [task_name]
+    #   @yieldparam task_name [String] the name of a Rake task
+    #   @yieldreturn [String] a name for the Capistrano recipe
+    #
+    #   @return [Proc] _block_
+    #
+    #   @raise [ArgumentError] _block_ does not have exactly one parameter
+    def rename(&block)
+      if block
+        unless (block.arity == 1)
+          raise ::ArgumentError, "Must have 1 parameter but has #{block.arity}"
+        end
+
+        @rename = block
+      else
+        @rename
+      end
+    end
+
+  end
+
+end

data/lib/cape/recipe_definition_deprecated.rb

@@ -0,0 +1,41 @@
+require 'cape/recipe_definition'
+
+module Cape
+
+  # Implements {RecipeDefinition} with deprecated methods.
+  #
+  # @api private
+  class RecipeDefinitionDeprecated < RecipeDefinition
+
+    # The object in which deprecated API usage is recorded.
+    #
+    # @return [Deprecation::Base]
+    attr_reader :deprecation
+
+    # Constructs a new RecipeDefinitionDeprecated with the specified
+    # _deprecation_.
+    #
+    # @param [Deprecation::Base] deprecation the value of {#deprecation}
+    def initialize(deprecation)
+      @deprecation = deprecation
+    end
+
+    # Sets a remote environment variable.
+    #
+    # @param [String] name  the name of a remote environment variable
+    # @param [String] value a value for the remote environment variable
+    #
+    # @return [RecipeDefinitionDeprecated] the object
+    #
+    # @deprecated Use {RecipeDefinition#env} instead.
+    #
+    # @api public
+    def []=(name, value)
+      env[name]             = value
+      deprecation.env[name] = value
+      self
+    end
+
+  end
+
+end

data/lib/cape/util.rb

@@ -1,6 +1,8 @@
 module Cape
 
   # Provides utility functions.
+  #
+  # @api private
   module Util
 
     # Conditionally transforms the specified _noun_ into its plural form.

data/lib/cape/version.rb

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

data/lib/cape/xterm.rb

@@ -0,0 +1,326 @@
+module Cape
+
+  # Formats output for an xterm console.
+  #
+  # Convenience class methods are made available dynamically that permit multiple
+  # formats to be applied.
+  #
+  # @example Apply bold and red-foreground formatting to a string
+  #   Cape::XTerm.bold_and_red_foreground 'foo'
+  #
+  # @api private
+  module XTerm
+
+    # The xterm formatting codes.
+    FORMATS = {:bold               =>  '1',
+               :underlined         =>  '4',
+               :blinking           =>  '5',
+               :inverse            =>  '7',
+               :foreground_black   => '30',
+               :foreground_red     => '31',
+               :foreground_green   => '32',
+               :foreground_yellow  => '33',
+               :foreground_blue    => '34',
+               :foreground_magenta => '35',
+               :foreground_cyan    => '36',
+               :foreground_gray    => '37',
+               :foreground_default => '39',
+               :background_black   => '40',
+               :background_red     => '41',
+               :background_green   => '42',
+               :background_yellow  => '43',
+               :background_blue    => '44',
+               :background_magenta => '45',
+               :background_cyan    => '46',
+               :background_gray    => '47',
+               :background_default => '49'}
+
+    # @!method bold(string)
+    #   Formats the specified _string_ in bold type.
+    #
+    #   @param [String] string the string to format in bold type
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method underlined(string)
+    #   Formats the specified _string_ in underlined type.
+    #
+    #   @param [String] string the string to underline
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method blinking(string)
+    #   Formats the specified _string_ in blinking type.
+    #
+    #   @param [String] string the string to blink
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method inverse(string)
+    #   Formats the specified _string_ in inverse colors.
+    #
+    #   @param [String] string the string whose colors are to be inverted
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_black(string)
+    #   Formats the specified _string_ in black.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_red(string)
+    #   Formats the specified _string_ in red.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_green(string)
+    #   Formats the specified _string_ in green.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_yellow(string)
+    #   Formats the specified _string_ in yellow.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_blue(string)
+    #   Formats the specified _string_ in blue.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_magenta(string)
+    #   Formats the specified _string_ in magenta.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_cyan(string)
+    #   Formats the specified _string_ in cyan.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_gray(string)
+    #   Formats the specified _string_ in gray.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method foreground_default(string)
+    #   Formats the specified _string_ in the default foreground color.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_black(string)
+    #   Formats the specified _string_ with a black background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_red(string)
+    #   Formats the specified _string_ with a red background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_green(string)
+    #   Formats the specified _string_ with a green background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_yellow(string)
+    #   Formats the specified _string_ with a yellow background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_blue(string)
+    #   Formats the specified _string_ with a blue background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_magenta(string)
+    #   Formats the specified _string_ with a magenta background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_cyan(string)
+    #   Formats the specified _string_ with a cyan background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_gray(string)
+    #   Formats the specified _string_ with a gray background.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # @!method background_default(string)
+    #   Formats the specified _string_ in the default background color.
+    #
+    #   @param [String] string the string to color
+    #
+    #   @return [String] the formatted _string_
+    #
+    #   @!scope class
+    #
+    #   @api private
+
+    # Applies the specified _formats_ to _string_.
+    #
+    # @param [String]          string  the string to format
+    # @param [Array of Symbol] formats the formats to apply
+    #
+    # @return [String] the formatted _string_
+    def self.format(string, *formats)
+      formatting_codes = formats.collect do |f|
+        unless FORMATS.key?(f)
+          raise ::ArgumentError, "Unrecognized format #{f.inspect}"
+        end
+
+        FORMATS[f]
+      end
+
+      return string if formatting_codes.empty? || string.nil?
+
+      "\e[#{formatting_codes.join ';'}m#{string}\e[0m"
+    end
+
+  private
+
+    def self.method_missing(method, *arguments, &block)
+      unless respond_to_missing?(method, false)
+        return super(method, *arguments, &block)
+      end
+
+      formats = method.to_s.split('_and_').collect(&:to_sym)
+      format(*(arguments + formats))
+    end
+
+    def self.respond_to_missing?(method, include_private)
+      formats = method.to_s.split('_and_').collect(&:to_sym)
+      formats.all? do |f|
+        FORMATS.key? f
+      end
+    end
+
+    if RUBY_VERSION <= '1.8.7'
+      def self.respond_to?(method, include_private=false)
+        respond_to_missing? method, include_private
+      end
+    end
+
+  end
+
+end