sshkit 1.7.1 → 1.8.0

data/lib/sshkit/color.rb

@@ -1,27 +1,58 @@
-require 'colorize'
+module SSHKit
+  # Very basic support for ANSI color, so that we don't have to rely on
+  # any external dependencies. This class handles colorizing strings, and
+  # automatically disabling color if the underlying output is not a tty.
+  #
+  class Color
+    COLOR_CODES = {
+      :black   => 30,
+      :red     => 31,
+      :green   => 32,
+      :yellow  => 33,
+      :blue    => 34,
+      :magenta => 35,
+      :cyan    => 36,
+      :white   => 37,
+      :light_black   => 90,
+      :light_red     => 91,
+      :light_green   => 92,
+      :light_yellow  => 93,
+      :light_blue    => 94,
+      :light_magenta => 95,
+      :light_cyan    => 96,
+      :light_white   => 97
+    }.freeze
 
-module Color
-  String.colors.each do |color|
-    instance_eval <<-RUBY, __FILE__, __LINE__
-      def #{color}(string = '')
-        string = yield if block_given?
-        colorize? ? string.colorize(:color => :#{color}) : string
-      end
-    RUBY
-  end
+    def initialize(output, env=ENV)
+      @output, @env = output, env
+    end
 
-  String.modes.each do |mode|
-    instance_eval <<-RUBY, __FILE__, __LINE__
-      def #{mode}(string = '')
-        string = yield if block_given?
-        colorize? ? string.colorize(:mode => :#{mode}) : string
-      end
-    RUBY
-  end
+    # Converts the given obj to string and surrounds in the appropriate ANSI
+    # color escape sequence, based on the specified color and mode. The color
+    # must be a symbol (see COLOR_CODES for a complete list).
+    #
+    # If the underlying output does not support ANSI color (see `colorize?),
+    # the string will be not be colorized. Likewise if the specified color
+    # symbol is unrecognized, the string will not be colorized.
+    #
+    # Note that the only mode currently support is :bold. All other values
+    # will be silently ignored (i.e. treated the same as mode=nil).
+    #
+    def colorize(obj, color, mode=nil)
+      string = obj.to_s
+      return string unless colorize?
+      return string unless COLOR_CODES.key?(color)
+
+      result = mode == :bold ? "\e[1;" : "\e[0;"
+      result << COLOR_CODES.fetch(color).to_s
+      result << ";49m#{string}\e[0m"
+    end
 
-  class << self
+    # Returns `true` if the underlying output is a tty, or if the SSHKIT_COLOR
+    # environment variable is set.
+    #
     def colorize?
-      ENV['SSHKIT_COLOR'] || $stdout.tty?
+      @env['SSHKIT_COLOR'] || (@output.respond_to?(:tty?) && @output.tty?)
     end
   end
 end

data/lib/sshkit/command.rb

@@ -4,38 +4,12 @@ require 'securerandom'
 # @author Lee Hambley
 module SSHKit
 
-  # @author Lee Hambley
-  module CommandHelper
-
-    def rake(tasks=[])
-      execute :rake, tasks
-    end
-
-    def make(tasks=[])
-      execute :make, tasks
-    end
-
-    def execute(command, args=[])
-      Command.new(command, args)
-    end
-
-    private
-
-    def map(command)
-      SSHKit.config.command_map[command.to_sym]
-    end
-
-  end
-
   # @author Lee Hambley
   class Command
 
     Failed = Class.new(SSHKit::StandardError)
 
-    attr_reader :command, :args, :options, :started_at, :started, :exit_status
-
-    attr_accessor :stdout, :stderr
-    attr_accessor :full_stdout, :full_stderr
+    attr_reader :command, :args, :options, :started_at, :started, :exit_status, :full_stdout, :full_stderr
 
     # Initialize a new Command object
     #
@@ -45,14 +19,13 @@ module SSHKit
     # nothing in stdin or stdout
     #
     def initialize(*args)
-      raise ArgumentError, "May not pass no arguments to Command.new" if args.empty?
+      raise ArgumentError, "Must pass arguments to Command.new" if args.empty?
       @options = default_options.merge(args.extract_options!)
       @command = args.shift.to_s.strip.to_sym
       @args    = args
       @options.symbolize_keys!
       sanitize_command!
-      @stdout, @stderr = String.new, String.new
-      @full_stdout, @full_stderr = String.new, String.new
+      @stdout, @stderr, @full_stdout, @full_stderr = String.new, String.new, String.new, String.new
     end
 
     def complete?
@@ -83,6 +56,38 @@ module SSHKit
     end
     alias :failed? :failure?
 
+    def stdout
+      log_reader_deprecation('stdout')
+      @stdout
+    end
+
+    def stdout=(new_value)
+      log_writer_deprecation('stdout')
+      @stdout = new_value
+    end
+
+    def stderr
+      log_reader_deprecation('stderr')
+      @stderr
+    end
+
+    def stderr=(new_value)
+      log_writer_deprecation('stderr')
+      @stderr = new_value
+    end
+
+    def on_stdout(channel, data)
+      @stdout = data
+      @full_stdout += data
+      call_interaction_handler(:stdout, data, channel)
+    end
+
+    def on_stderr(channel, data)
+      @stderr = data
+      @full_stderr += data
+      call_interaction_handler(:stderr, data, channel)
+    end
+
     def exit_status=(new_exit_status)
       @finished_at = Time.now
       @exit_status = new_exit_status
@@ -125,7 +130,7 @@ module SSHKit
     end
 
     def verbosity
-      if vb = options[:verbosity]
+      if (vb = options[:verbosity])
         case vb.class.name
         when 'Symbol' then return Logger.const_get(vb.to_s.upcase)
         when 'Fixnum' then return vb
@@ -136,12 +141,12 @@ module SSHKit
     end
 
     def should_map?
-      !command.match /\s/
+      !command.match(/\s/)
     end
 
-    def within(&block)
+    def within(&_block)
       return yield unless options[:in]
-      "cd #{options[:in]} && %s" % yield
+      sprintf("cd #{options[:in]} && %s", yield)
     end
 
     def environment_hash
@@ -150,35 +155,33 @@ module SSHKit
 
     def environment_string
       environment_hash.collect do |key,value|
-        if key.is_a? Symbol
-          "#{key.to_s.upcase}=#{value}"
-        else
-          "#{key.to_s}=#{value}"
-        end
+        key_string = key.is_a?(Symbol) ? key.to_s.upcase : key.to_s
+        escaped_value = value.to_s.gsub(/"/, '\"')
+        %{#{key_string}="#{escaped_value}"}
       end.join(' ')
     end
 
-    def with(&block)
+    def with(&_block)
       return yield unless environment_hash.any?
-      "( #{environment_string} %s )" % yield
+      sprintf("( export #{environment_string} ; %s )", yield)
     end
 
-    def user(&block)
+    def user(&_block)
       return yield unless options[:user]
       "sudo -u #{options[:user]} #{environment_string + " " unless environment_string.empty?}-- sh -c '%s'" % %Q{#{yield}}
     end
 
-    def in_background(&block)
+    def in_background(&_block)
       return yield unless options[:run_in_background]
-      "( nohup %s > /dev/null & )" % yield
+      sprintf("( nohup %s > /dev/null & )", yield)
     end
 
-    def umask(&block)
+    def umask(&_block)
       return yield unless SSHKit.config.umask
-      "umask #{SSHKit.config.umask} && %s" % yield
+      sprintf("umask #{SSHKit.config.umask} && %s", yield)
     end
 
-    def group(&block)
+    def group(&_block)
       return yield unless options[:group]
       "sg #{options[:group]} -c \\\"%s\\\"" % %Q{#{yield}}
       # We could also use the so-called heredoc format perhaps:
@@ -227,6 +230,24 @@ module SSHKit
       end
     end
 
+    def call_interaction_handler(stream_name, data, channel)
+      interaction_handler = options[:interaction_handler]
+      interaction_handler = MappingInteractionHandler.new(interaction_handler) if interaction_handler.kind_of?(Hash)
+      interaction_handler.on_data(self, stream_name, data, channel) if interaction_handler.respond_to?(:on_data)
+    end
+
+    def log_reader_deprecation(stream)
+      SSHKit.config.deprecation_logger.log(
+        "The #{stream} method on Command is deprecated. " \
+        "The @#{stream} attribute will be removed in a future release. Use full_#{stream}() instead."
+      )
+    end
+
+    def log_writer_deprecation(stream)
+      SSHKit.config.deprecation_logger.log(
+        "The #{stream}= method on Command is deprecated. The @#{stream} attribute will be removed in a future release."
+      )
+    end
   end
 
 end

data/lib/sshkit/configuration.rb

@@ -6,7 +6,16 @@ module SSHKit
     attr_writer :output, :backend, :default_env
 
     def output
-      @output ||= formatter(:pretty)
+      @output ||= use_format(:pretty)
+    end
+
+    def deprecation_logger
+      self.deprecation_output = $stderr if @deprecation_logger.nil?
+      @deprecation_logger
+    end
+
+    def deprecation_output=(out)
+      @deprecation_logger = DeprecationLogger.new(out)
     end
 
     def default_env
@@ -25,8 +34,29 @@ module SSHKit
       @output_verbosity = logger(verbosity)
     end
 
+    # TODO: deprecate in favor of `use_format`
     def format=(format)
-      self.output = formatter(format)
+      use_format(format)
+    end
+
+    # Tell SSHKit to use the specified `formatter` for stdout. The formatter
+    # can be the name of a built-in SSHKit formatter, like `:pretty`, a
+    # formatter class, like `SSHKit::Formatter::Pretty`, or a custom formatter
+    # class you've written yourself.
+    #
+    # Additional arguments will be passed to the formatter's constructor.
+    #
+    # Example:
+    #
+    #   config.use_format(:pretty)
+    #
+    # Is equivalent to:
+    #
+    #   config.output = SSHKit::Formatter::Pretty.new($stdout)
+    #
+    def use_format(formatter, *args)
+      klass = formatter.is_a?(Class) ? formatter : formatter_class(formatter)
+      self.output = klass.new($stdout, *args)
     end
 
     def command_map
@@ -43,10 +73,13 @@ module SSHKit
       verbosity.is_a?(Integer) ? verbosity : Logger.const_get(verbosity.upcase)
     end
 
-    def formatter(format)
-      SSHKit::Formatter.constants.each do |const|
-        return SSHKit::Formatter.const_get(const).new($stdout) if const.downcase.eql?(format.downcase)
+    def formatter_class(symbol)
+      name = symbol.to_s.downcase
+      found = SSHKit::Formatter.constants.find do |const|
+        const.to_s.downcase == name
       end
+      fail NameError, 'Unrecognized SSHKit::Formatter "#{symbol}"' if found.nil?
+      SSHKit::Formatter.const_get(found)
     end
 
   end

data/lib/sshkit/deprecation_logger.rb

@@ -0,0 +1,17 @@
+module SSHKit
+  class DeprecationLogger
+    def initialize(out)
+      @out = out
+      @previous_warnings = Set.new
+    end
+
+    def log(message)
+      return if @out.nil?
+      warning_msg = "[Deprecated] #{message}\n"
+      caller_line = caller.find { |line| !line.include?('lib/sshkit') }
+      warning_msg << "    (Called from #{caller_line})\n" unless caller_line.nil?
+      @out << warning_msg unless @previous_warnings.include?(warning_msg)
+      @previous_warnings << warning_msg
+    end
+  end
+end

data/lib/sshkit/formatters/abstract.rb

@@ -9,15 +9,39 @@ module SSHKit
       extend Forwardable
       attr_reader :original_output
       def_delegators :@original_output, :read, :rewind
+      def_delegators :@color, :colorize
 
-      def initialize(oio)
-        @original_output = oio
+      def initialize(output)
+        @original_output = output
+        @color = SSHKit::Color.new(output)
       end
 
-      def write(obj)
+      %w(fatal error warn info debug).each do |level|
+        define_method(level) do |message|
+          write(LogMessage.new(Logger.const_get(level.upcase), message))
+        end
+      end
+      alias :log :info
+
+      def log_command_start(command)
+        write(command)
+      end
+
+      def log_command_data(command, _stream_type, _stream_data)
+        write(command)
+      end
+
+      def log_command_exit(command)
+        write(command)
+      end
+
+      def <<(obj)
+        write(obj)
+      end
+
+      def write(_obj)
         raise "Abstract formatter should not be used directly, maybe you want SSHKit::Formatter::BlackHole"
       end
-      alias :<< :write
 
     end
 

data/lib/sshkit/formatters/black_hole.rb

@@ -4,10 +4,9 @@ module SSHKit
 
     class BlackHole < Abstract
 
-      def write(obj)
+      def write(_obj)
         # Nothing, nothing to do
       end
-      alias :<< :write
 
     end
 

data/lib/sshkit/formatters/dot.rb

@@ -4,18 +4,11 @@ module SSHKit
 
     class Dot < Abstract
 
-      def write(obj)
-        return unless obj.is_a? SSHKit::Command
-        if obj.finished?
-          original_output << (obj.failure? ? c.red('.') : c.green('.'))
-        end
+      def log_command_exit(command)
+        original_output << colorize('.', command.failure? ? :red : :green)
       end
-      alias :<< :write
 
-      private
-
-      def c
-        @c ||= Color
+      def write(_obj)
       end
 
     end

data/lib/sshkit/formatters/pretty.rb

@@ -4,77 +4,52 @@ module SSHKit
 
     class Pretty < Abstract
 
+      LEVEL_NAMES = %w{ DEBUG INFO WARN ERROR FATAL }.freeze
+      LEVEL_COLORS = [:black, :blue, :yellow, :red, :red].freeze
+
       def write(obj)
-        return if obj.verbosity < SSHKit.config.output_verbosity
-        case obj
-        when SSHKit::Command    then write_command(obj)
-        when SSHKit::LogMessage then write_log_message(obj)
+        if obj.kind_of?(SSHKit::LogMessage)
+          write_message(obj.verbosity, obj.to_s)
         else
-          original_output << c.black(c.on_yellow("Output formatter doesn't know how to handle #{obj.class}\n"))
+          raise "write only supports formatting SSHKit::LogMessage, called with #{obj.class}: #{obj.inspect}"
         end
       end
-      alias :<< :write
-
-      private
 
-      def write_command(command)
-        unless command.started?
-          original_output << "%6s %s\n" % [level(command.verbosity),
-                                           uuid(command) + "Running #{c.yellow(c.bold(String(command)))} #{command.host.user ? "as #{c.blue(command.host.user)}@" : "on "}#{c.blue(command.host.to_s)}"]
-          if SSHKit.config.output_verbosity == Logger::DEBUG
-            original_output << "%6s %s\n" % [level(Logger::DEBUG),
-                                             uuid(command) + "Command: #{c.blue(command.to_command)}"]
-          end
-        end
-
-        if SSHKit.config.output_verbosity == Logger::DEBUG
-          unless command.stdout.empty?
-            command.stdout.lines.each do |line|
-              original_output << "%6s %s" % [level(Logger::DEBUG),
-                                             uuid(command) + c.green("\t" + line)]
-              original_output << "\n" unless line[-1] == "\n"
-            end
-            command.stdout = ''
-          end
-
-          unless command.stderr.empty?
-            command.stderr.lines.each do |line|
-              original_output << "%6s %s" % [level(Logger::DEBUG),
-                                             uuid(command) + c.red("\t" + line)]
-              original_output << "\n" unless line[-1] == "\n"
-            end
-            command.stderr = ''
-          end
-        end
-
-        if command.finished?
-          original_output << "%6s %s\n" % [level(command.verbosity),
-                                           uuid(command) + "Finished in #{sprintf('%5.3f seconds', command.runtime)} with exit status #{command.exit_status} (#{c.bold { command.failure? ? c.red('failed') : c.green('successful') }})."]
-        end
+      def log_command_start(command)
+        host_prefix = command.host.user ? "as #{colorize(command.host.user, :blue)}@" : 'on '
+        message = "Running #{colorize(command, :yellow, :bold)} #{host_prefix}#{colorize(command.host, :blue)}"
+        write_message(command.verbosity, message, command.uuid)
+        write_message(Logger::DEBUG, "Command: #{colorize(command.to_command, :blue)}", command.uuid)
       end
 
-      def write_log_message(log_message)
-        original_output << "%6s %s\n" % [level(log_message.verbosity), log_message.to_s]
+      def log_command_data(command, stream_type, stream_data)
+        color = case stream_type
+          when :stdout then :green
+          when :stderr then :red
+          else raise "Unrecognised stream_type #{stream_type}, expected :stdout or :stderr"
+        end
+        write_message(Logger::DEBUG, colorize("\t#{stream_data}".chomp, color), command.uuid)
       end
 
-      def c
-        @c ||= Color
+      def log_command_exit(command)
+        runtime = sprintf('%5.3f seconds', command.runtime)
+        successful_or_failed =  command.failure? ? colorize('failed', :red, :bold) : colorize('successful', :green, :bold)
+        message = "Finished in #{runtime} with exit status #{command.exit_status} (#{successful_or_failed})."
+        write_message(command.verbosity, message, command.uuid)
       end
 
-      def uuid(obj)
-        "[#{c.green(obj.uuid)}] "
-      end
+      protected
 
-      def level(verbosity)
-        c.send(level_formatting(verbosity), level_names(verbosity))
+      def format_message(verbosity, message, uuid=nil)
+        message = "[#{colorize(uuid, :green)}] #{message}" unless uuid.nil?
+        level = colorize(Pretty::LEVEL_NAMES[verbosity], Pretty::LEVEL_COLORS[verbosity])
+        '%6s %s' % [level, message]
       end
 
-      def level_formatting(level_num)
-        %w{ black blue yellow red red }[level_num]
-      end
+      private
 
-      def level_names(level_num)
-        %w{ DEBUG INFO WARN ERROR FATAL }[level_num]
+      def write_message(verbosity, message, uuid=nil)
+        original_output << "#{format_message(verbosity, message, uuid)}\n" if verbosity >= SSHKit.config.output_verbosity
       end
 
     end