From b9cd0df6213358653066feaff2d2089fd940c6ef Mon Sep 17 00:00:00 2001
From: Matt Brictson <matt@mattbrictson.com>
Date: Fri, 25 Dec 2015 18:29:40 -0800
Subject: [PATCH 1/2] Allow all Formatters to accept options hash

None of the built in formatters yet do anything with these options. However, it
provides a consistent #initialize API that allows us to promote "formatter
options" as a concept further up the stack in Capistrano.

For example, in Capistrano we can offer this configuration system:

set :format, ...
set :format_options, key: value, ...

We can only reasonable offer this if we are sure that the underlying formatters
all accept an options hash (i.e. the :format_options).

Most importantly, Airbrussh *does* have options, and this will allow us to have
a standard way for those options to be declared. Airbrussh will be the default
formatter in a future version of Capistrano, and this commit is part of laying
the groundwork.
---
 CHANGELOG.md                      | 2 ++
 lib/sshkit/formatters/abstract.rb | 5 +++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd40af34..84487ee7 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/lib/sshkit/formatters/abstract.rb b/lib/sshkit/formatters/abstract.rb
index 8b7c2a68..aa6ab125 100644
--- a/lib/sshkit/formatters/abstract.rb
+++ b/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
 

From 75fb82df76e7dda9f6cd80c344acd604b3ae0b84 Mon Sep 17 00:00:00 2001
From: Matt Brictson <matt@mattbrictson.com>
Date: Mon, 28 Dec 2015 17:35:36 -0800
Subject: [PATCH 2/2] Update docs and tests to cover formatter options

---
 README.md                           | 10 ++++------
 test/unit/formatters/test_custom.rb |  5 +++++
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6a768b4b..a5a234f3 100644
--- a/README.md
+++ b/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
 
diff --git a/test/unit/formatters/test_custom.rb b/test/unit/formatters/test_custom.rb
index e4afac3e..5d637731 100644
--- a/test/unit/formatters/test_custom.rb
+++ b/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)