New API for setting+configuring formatter: use_format

lib/sshkit/configuration.rb

@@ -6,7 +6,7 @@ class Configuration
     attr_writer :output, :backend, :default_env
 
     def output
-      @output ||= formatter(:pretty)
+      @output ||= use_format(:pretty)
     end
 
     def deprecation_logger
@@ -34,8 +34,29 @@ def output_verbosity=(verbosity)
       @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
@@ -52,10 +73,13 @@ def logger(verbosity)
       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

test/unit/test_configuration.rb

@@ -78,6 +78,28 @@ def test_setting_formatter_types
       end
     end
 
+    def test_prohibits_unknown_formatter_type_with_exception
+      assert_raises(NameError) do
+        SSHKit.config.format = :doesnotexist
+      end
+    end
+
+    def test_options_can_be_provided_to_formatter
+      SSHKit.config.use_format(TestFormatter, :color => false)
+      formatter = SSHKit.config.output
+      assert_instance_of(TestFormatter, formatter)
+      assert_equal($stdout, formatter.output)
+      assert_equal({ :color => false }, formatter.options)
+    end
+
+    class TestFormatter
+      attr_accessor :output, :options
+
+      def initialize(output, options={})
+        @output = output
+        @options = options
+      end
+    end
   end
 
 end