capistrano 1.4.2 → 2.0.0

data/lib/capistrano/cli.rb

@@ -1,83 +1,25 @@
-require 'optparse'
 require 'capistrano'
+require 'capistrano/cli/execute'
+require 'capistrano/cli/help'
+require 'capistrano/cli/options'
+require 'capistrano/cli/ui'
 
 module Capistrano
   # The CLI class encapsulates the behavior of capistrano when it is invoked
-  # as a command-line utility. This allows other programs to embed ST and
-  # preserve it's command-line semantics.
+  # as a command-line utility. This allows other programs to embed Capistrano
+  # and preserve its command-line semantics.
   class CLI
-    # Invoke capistrano using the ARGV array as the option parameters. This
-    # is what the command-line capistrano utility does.
-    def self.execute!
-      new.execute!
-    end
-
-    # The following determines whether or not echo-suppression is available.
-    # This requires the termios library to be installed (which, unfortunately,
-    # is not available for Windows).
-    begin
-      require 'termios'
-
-      # Enable or disable stdin echoing to the terminal.
-      def self.echo(enable)
-        term = Termios::getattr(STDIN)
-
-        if enable
-          term.c_lflag |= (Termios::ECHO | Termios::ICANON)
-        else
-          term.c_lflag &= ~Termios::ECHO
-        end
-
-        Termios::setattr(STDIN, Termios::TCSANOW, term)
-      end
-    rescue LoadError
-      def self.echo(enable)
-      end
-    end
-
-    # execute the associated block with echo-suppression enabled. Note that
-    # if termios is not available, echo suppression will not be available
-    # either.
-    def self.with_echo
-      unless @warned_about_echo
-        puts "WARNING: Password will echo -- install the 'termios' gem to hide your password." if !defined?(Termios) && RUBY_PLATFORM !~ /mswin/
-        @warned_about_echo = true
-      end
-      echo(false)
-      yield
-    ensure
-      echo(true)
-    end
-
-    # Prompt for a password using echo suppression.
-    def self.password_prompt(prompt="Password: ")
-      sync = STDOUT.sync
-      begin
-        with_echo do
-          STDOUT.sync = true
-          print(prompt)
-          STDIN.gets.chomp
-        end
-      ensure
-        STDOUT.sync = sync
-        puts
-      end
-    end
-
     # The array of (unparsed) command-line options
     attr_reader :args
 
-    # The hash of (parsed) command-line options
-    attr_reader :options
-
     # Create a new CLI instance using the given array of command-line parameters
     # to initialize it. By default, +ARGV+ is used, but you can specify a
-    # different set of parameters (such as when embedded ST in a program):
+    # different set of parameters (such as when embedded cap in a program):
     #
     #   require 'capistrano/cli'
-    #   Capistrano::CLI.new(%w(-vvvv -r config/deploy -a update_code)).execute!
+    #   Capistrano::CLI.parse(%w(-vvvv -r config/deploy update_code)).execute!
     #
-    # Note that you can also embed ST directly by creating a new Configuration
+    # Note that you can also embed cap directly by creating a new Configuration
     # instance and setting it up, but you'll often wind up duplicating logic
     # defined in the CLI class. The above snippet, redone using the Configuration
     # class directly, would look like:
@@ -87,261 +29,19 @@ module Capistrano
     #   config = Capistrano::Configuration.new
     #   config.logger_level = Capistrano::Logger::TRACE
     #   config.set(:password) { Capistrano::CLI.password_prompt }
-    #   config.load "standard", "config/deploy"
-    #   config.actor.update_code
+    #   config.load "config/deploy"
+    #   config.update_code
     #
     # There may be times that you want/need the additional control offered by
     # manipulating the Configuration directly, but generally interfacing with
     # the CLI class is recommended.
-    def initialize(args = ARGV)
-      @args = args
-      @options = { :recipes => [], :actions => [], :vars => {},
-        :pre_vars => {}, :sysconf => default_sysconf, :dotfile => default_dotfile }
-
-      OptionParser.new do |opts|
-        opts.banner = "Usage: #{$0} [options] [args]"
-
-        opts.separator ""
-        opts.separator "Recipe Options -----------------------"
-        opts.separator ""
-
-        opts.on("-a", "--action ACTION",
-          "An action to execute. Multiple actions may",
-          "be specified, and are loaded in the given order."
-        ) { |value| @options[:actions] << value }
-        
-        opts.on("-f", "--file FILE",
-          "A recipe file to load. Multiple recipes may",
-          "be specified, and are loaded in the given order."
-        ) { |value| @options[:recipes] << value }
-
-        opts.on("-p", "--password [PASSWORD]",
-          "The password to use when connecting. If the switch",
-          "is given without a password, the password will be",
-          "prompted for immediately. (Default: prompt for password",
-          "the first time it is needed.)"
-        ) { |value| @options[:password] = value }
-
-        opts.on("-r", "--recipe RECIPE",
-          "A recipe file to load. Multiple recipes may",
-          "be specified, and are loaded in the given order.",
-          "(This option is deprecated--please use -f instead)"
-        ) do |value|
-          warn "Deprecated -r/--recipe flag used. Please use -f instead"
-          @options[:recipes] << value
-        end
-
-        opts.on("-s", "--set NAME=VALUE",
-          "Specify a variable and it's value to set. This",
-          "will be set after loading all recipe files."
-        ) do |pair|
-          name, value = pair.split(/=/, 2)
-          @options[:vars][name.to_sym] = value
-        end
-
-        opts.on("-S", "--set-before NAME=VALUE",
-          "Specify a variable and it's value to set. This",
-          "will be set BEFORE loading all recipe files."
-        ) do |pair|
-          name, value = pair.split(/=/, 2)
-          @options[:pre_vars][name.to_sym] = value
-        end
-
-        opts.on("-x", "--skip-config",
-          "Disables the loading of the default personal config",
-          "file. Specifying -C after this option will reenable",
-          "it. (Default: config file is loaded)"
-        ) { @options[:dotfile] = nil }
-
-        opts.separator ""
-        opts.separator "Framework Integration Options --------"
-        opts.separator ""
-
-        opts.on("-A", "--apply-to DIRECTORY",
-          "Create a minimal set of scripts and recipes to use",
-          "capistrano with the application at the given",
-          "directory. (Currently only works with Rails apps.)"
-        ) { |value| @options[:apply_to] = value }
-
-        opts.separator ""
-        opts.separator "Miscellaneous Options ----------------"
-        opts.separator ""
-
-        opts.on("-h", "--help", "Display this help message") do
-          puts opts
-          exit
-        end
-
-        opts.on("-P", "--[no-]pretend",
-          "Run the task(s), but don't actually connect to or",
-          "execute anything on the servers. (For various reasons",
-          "this will not necessarily be an accurate depiction",
-          "of the work that will actually be performed.",
-          "Default: don't pretend.)"
-        ) { |value| @options[:pretend] = value }
-
-        opts.on("-q", "--quiet",
-          "Make the output as quiet as possible (the default)"
-        ) { @options[:verbose] = 0 }
-
-        opts.on("-v", "--verbose",
-          "Specify the verbosity of the output.",
-          "May be given multiple times. (Default: silent)"
-        ) { @options[:verbose] ||= 0; @options[:verbose] += 1 }
-
-        opts.on("-V", "--version",
-          "Display the version info for this utility"
-        ) do
-          require 'capistrano/version'
-          puts "Capistrano v#{Capistrano::Version::STRING}"
-          exit
-        end
-
-        opts.separator ""
-        opts.separator <<-DETAIL.split(/\n/)
-You can use the --apply-to switch to generate a minimal set of capistrano
-scripts and recipes for an application. Just specify the path to the application
-as the argument to --apply-to, like this:
-
-  cap --apply-to ~/projects/myapp
-
-You'll wind up with a sample deployment recipe in config/deploy.rb and some new
-rake tasks in lib/tasks.
-
-(Currently, --apply-to only works with Rails applications.)
-DETAIL
-#' # vim syntax highlighting fix
-
-        if args.empty?
-          puts opts
-          exit
-        else
-          opts.parse!(args)
-        end
-      end
-
-      check_options!
-
-      password_proc = Proc.new { self.class.password_prompt }
-
-      if !@options.has_key?(:password)
-        @options[:password] = password_proc
-      elsif !@options[:password]
-        @options[:password] = password_proc.call
-      end
-    end
-
-    # Beginning running Capistrano based on the configured options.
-    def execute!
-      if @options[:apply_to]
-        execute_apply_to!
-      else
-        execute_recipes!
-      end
+    def initialize(args)
+      @args = args.dup
+      $stdout.sync = true # so that Net::SSH prompts show up
     end
 
-    private
-
-      # Load the recipes specified by the options, and execute the actions
-      # specified.
-      def execute_recipes!
-        config = Capistrano::Configuration.new
-        config.logger.level = options[:verbose]
-        config.set :password, options[:password]
-        config.set :pretend, options[:pretend]
-
-        options[:pre_vars].each { |name, value| config.set(name, value) }
-
-        # load the standard recipe definition
-        config.load "standard"
-        
-        # load systemwide config/recipe definition
-        config.load(@options[:sysconf]) if @options[:sysconf] && File.exist?(@options[:sysconf])        
-        
-        # load user config/recipe definition
-        config.load(@options[:dotfile]) if @options[:dotfile] && File.exist?(@options[:dotfile])
-
-        options[:recipes].each { |recipe| config.load(recipe) }
-        options[:vars].each { |name, value| config.set(name, value) }
-
-        actor = config.actor
-        options[:actions].each { |action| actor.send action }
-      rescue Exception => error
-        handle_error(error)
-      end
-
-      # Load the Rails generator and apply it to the specified directory.
-      def execute_apply_to!
-        require 'capistrano/generators/rails/loader'
-        Generators::RailsLoader.load! @options
-      end
-
-      APPLY_TO_OPTIONS = [:apply_to]
-      RECIPE_OPTIONS   = [:password]
-      DEFAULT_RECIPES  = %w(Capfile capfile config/deploy.rb)
-
-      # A sanity check to ensure that a valid operation is specified.
-      def check_options!
-        # if no verbosity has been specified, be verbose
-        @options[:verbose] = 3 if !@options.has_key?(:verbose)
-
-        apply_to_given = !(@options.keys & APPLY_TO_OPTIONS).empty?
-        recipe_given   = !(@options.keys & RECIPE_OPTIONS).empty? ||
-                         !@options[:recipes].empty? ||
-                         !@options[:actions].empty?
-
-        if apply_to_given && recipe_given
-          abort "You cannot specify both recipe options and framework integration options."
-        elsif !apply_to_given
-          look_for_default_recipe_file! if @options[:recipes].empty?
-          look_for_raw_actions!
-          abort "You must specify at least one action" if @options[:actions].empty?
-        else
-          @options[:application] = args.shift
-          @options[:recipe_file] = args.shift
-        end
-      end
-
-      def default_sysconf
-        File.join(sysconf_directory, "capistrano.conf")
-      end
-      
-      def default_dotfile
-        File.join(home_directory, ".caprc")
-      end
-
-      def sysconf_directory
-        # I'm guessing at where Windows users would keep their conf file.
-        ENV["SystemRoot"] || '/etc'
-      end
-      
-      def home_directory
-        ENV["HOME"] ||
-          (ENV["HOMEPATH"] && "#{ENV["HOMEDRIVE"]}#{ENV["HOMEPATH"]}") ||
-          "/"
-      end
-
-      def look_for_default_recipe_file!
-        DEFAULT_RECIPES.each do |file|
-          if File.exist?(file)
-            @options[:recipes] << file
-            break
-          end
-        end
-      end
-
-      def look_for_raw_actions!
-        @options[:actions].concat(@args)
-      end
-
-      def handle_error(error)
-        case error
-        when Net::SSH::AuthenticationFailed
-          abort "authentication failed for `#{error.message}'"
-        when Capistrano::Command::Error
-          abort(error.message)
-        else raise error
-        end
-      end
+    # Mix-in the actual behavior
+    include Execute, Options, UI
+    include Help # needs to be included last, because it overrides some methods
   end
 end

data/lib/capistrano/cli/execute.rb

@@ -0,0 +1,82 @@
+require 'capistrano/configuration'
+
+module Capistrano
+  class CLI
+    module Execute
+      def self.included(base) #:nodoc:
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Invoke capistrano using the ARGV array as the option parameters. This
+        # is what the command-line capistrano utility does.
+        def execute
+          parse(ARGV).execute!
+        end
+      end
+
+      # Using the options build when the command-line was parsed, instantiate
+      # a new Capistrano configuration, initialize it, and execute the
+      # requested actions.
+      #
+      # Returns the Configuration instance used, if successful.
+      def execute!
+        config = instantiate_configuration
+        config.logger.level = options[:verbose]
+
+        set_pre_vars(config)
+        load_recipes(config)
+
+        config.trigger(:load)
+        execute_requested_actions(config)
+        config.trigger(:exit)
+
+        config
+      rescue Exception => error
+        handle_error(error)
+      end
+
+      def execute_requested_actions(config)
+        Array(options[:vars]).each { |name, value| config.set(name, value) }
+
+        Array(options[:actions]).each do |action|
+          config.find_and_execute_task(action, :before => :start, :after => :finish)
+        end
+      end
+
+      def set_pre_vars(config) #:nodoc:
+        config.set :password, options[:password]
+        Array(options[:pre_vars]).each { |name, value| config.set(name, value) }
+      end
+
+      def load_recipes(config) #:nodoc:
+        # load the standard recipe definition
+        config.load "standard"
+      
+        # load systemwide config/recipe definition
+        config.load(options[:sysconf]) if options[:sysconf] && File.file?(options[:sysconf])        
+      
+        # load user config/recipe definition
+        config.load(options[:dotfile]) if options[:dotfile] && File.file?(options[:dotfile])
+
+        Array(options[:recipes]).each { |recipe| config.load(recipe) }
+      end
+
+      # Primarily useful for testing, but subclasses of CLI could conceivably
+      # override this method to return a Configuration subclass or replacement.
+      def instantiate_configuration #:nodoc:
+        Capistrano::Configuration.new
+      end
+
+      def handle_error(error) #:nodoc:
+        case error
+        when Net::SSH::AuthenticationFailed
+          abort "authentication failed for `#{error.message}'"
+        when Capistrano::Error
+          abort(error.message)
+        else raise error
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/cli/help.rb

@@ -0,0 +1,102 @@
+module Capistrano
+  class CLI
+    module Help
+      LINE_PADDING = 7
+      MIN_MAX_LEN  = 30
+      HEADER_LEN   = 60
+
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :execute_requested_actions_without_help, :execute_requested_actions
+        base.send :alias_method, :execute_requested_actions, :execute_requested_actions_with_help
+      end
+
+      def execute_requested_actions_with_help(config)
+        if options[:tasks]
+          task_list(config)
+        elsif options[:explain]
+          explain_task(config, options[:explain])
+        else
+          execute_requested_actions_without_help(config)
+        end
+      end
+
+      def task_list(config) #:nodoc:
+        tasks = config.task_list(:all)
+
+        if tasks.empty?
+          warn "There are no tasks available. Please specify a recipe file to load."
+        else
+          all_tasks_length = tasks.length
+          if options[:verbose].to_i < 1
+            tasks = tasks.reject { |t| t.description.empty? || t.description =~ /^\[internal\]/ }
+          end
+
+          tasks = tasks.sort_by { |task| task.fully_qualified_name }
+
+          longest = tasks.map { |task| task.fully_qualified_name.length }.max
+          max_length = output_columns - longest - LINE_PADDING
+          max_length = MIN_MAX_LEN if max_length < MIN_MAX_LEN
+
+          tasks.each do |task|
+            puts "cap %-#{longest}s # %s" % [task.fully_qualified_name, task.brief_description(max_length)]
+          end
+
+          if all_tasks_length > tasks.length
+            puts
+            puts "Some tasks were not listed, either because they have no description,"
+            puts "or because they are only used internally by other tasks. To see all"
+            puts "tasks, type `#{File.basename($0)} -Tv'."
+          end
+
+          puts
+          puts "Extended help may be available for these tasks."
+          puts "Type `#{File.basename($0)} -e taskname' to view it."
+        end
+      end
+
+      def explain_task(config, name) #:nodoc:
+        task = config.find_task(name)
+        if task.nil?
+          warn "The task `#{name}' does not exist."
+        else
+          puts "-" * HEADER_LEN
+          puts "cap #{name}"
+          puts "-" * HEADER_LEN
+
+          if task.description.empty?
+            puts "There is no description for this task."
+          else
+            puts format_text(task.description)
+          end
+
+          puts
+        end
+      end
+
+      def long_help #:nodoc:
+        help_text = File.read(File.join(File.dirname(__FILE__), "help.txt"))
+        self.class.ui.page_at = self.class.ui.output_rows - 2
+        self.class.ui.say format_text(help_text)
+      end
+
+      def format_text(text) #:nodoc:
+        formatted = ""
+        text.each_line do |line|
+          indentation = line[/^\s+/] || ""
+          indentation_size = indentation.split(//).inject(0) { |c,s| c + (s[0] == ?\t ? 8 : 1) }
+          lines = line.strip.gsub(/(.{1,#{output_columns - indentation_size}})(?:\s+|\Z)/, "\\1\n").split(/\n/)
+          if lines.empty?
+            formatted << "\n"
+          else
+            formatted << lines.map { |l| "#{indentation}#{l}\n" }.join
+          end
+        end
+        formatted
+      end
+
+      def output_columns #:nodoc:
+        @output_columns ||= self.class.ui.output_cols > 80 ? 80 : self.class.ui.output_cols
+      end
+    end
+  end
+end