Merge pull request #308 from mattbrictson/formatter-options

Allow all Formatters to accept options hash

CHANGELOG.md

@@ -13,6 +13,8 @@ appear at the top.
   * display more accurate string for commands with spaces being output in `Formatter::Pretty`
     [PR #304](https://github.com/capistrano/sshkit/pull/304)
     @steved
+  * `SSHKit::Formatter::Abstract` now accepts an optional Hash of options
+    [PR #308](https://github.com/capistrano/sshkit/pull/308) @mattbrictson
 
 ## 1.8.1
 

README.md

@@ -443,24 +443,22 @@ ENV['SSHKIT_COLOR'] = 'TRUE'
 
 Want custom output formatting? Here's what you have to do:
 
-1. Write a new formatter class in the `SSHKit::Formatter` module. As an example, check out the default [pretty](https://github.com/capistrano/sshkit/blob/master/lib/sshkit/formatters/pretty.rb) formatter.
+1. Write a new formatter class in the `SSHKit::Formatter` module. Your class should subclass `SSHKit::Formatter::Abstract` to inherit conveniences and common behavior. For a basic an example, check out the [Pretty](https://github.com/capistrano/sshkit/blob/master/lib/sshkit/formatters/pretty.rb) formatter.
 1. Set the output format as described above. E.g. if your new formatter is called `FooBar`:
 
 ```ruby
 SSHKit.config.use_format :foobar
 ```
 
-If your formatter class takes a second `options` argument in its constructor, you can pass options to it like this:
+All formatters that extend from `SSHKit::Formatter::Abstract` accept an options Hash as a constructor argument. You can pass options to your formatter like this:
 
 ```ruby
 SSHKit.config.use_format :foobar, :my_option => "value"
 ```
 
-Which will call your constructor:
+You can then access these options using the `options` accessor within your formatter code.
 
-```ruby
-SSHKit::Formatter::FooBar.new($stdout, :my_option => "value")
-```
+For a much more full-featured formatter example that makes use of options, check out the [Airbrussh repository](https://github.com/mattbrictson/airbrussh/).
 
 ## Output Verbosity
 

lib/sshkit/formatters/abstract.rb

@@ -7,12 +7,13 @@ module Formatter
     class Abstract
 
       extend Forwardable
-      attr_reader :original_output
+      attr_reader :original_output, :options
       def_delegators :@original_output, :read, :rewind
       def_delegators :@color, :colorize
 
-      def initialize(output)
+      def initialize(output, options={})
         @original_output = output
+        @options = options
         @color = SSHKit::Color.new(output)
       end
 

test/unit/formatters/test_custom.rb

@@ -43,6 +43,11 @@ def test_double_chevron_logs_commands
       assert_log_output 'C 1 /usr/bin/env ls'
     end
 
+    def test_accepts_options_hash
+      custom = CustomFormatter.new(output, :foo => 'value')
+      assert_equal('value', custom.options[:foo])
+    end
+
     private
 
     def assert_log_output(expected_output)