Allow all Formatters to accept options hash

[mattbrictson]

This PR adds optional options to all Formatters via Formatter::Abstract.

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.

[robd]

I think this is good; if I understand, this is just about using DI instead of static lookup of config options from SSHKit.config.

Perhaps this should be a separate PR, but I was wondering if we should use the newly available @options attribute in the Pretty formatter? Or were you thinking the built in SSHKit formatters should carry on using the SSHKit.config API? If we changed this, I think there are tests in unit/formatters which could be simplified to remove some static setup calls to SSHKit.config.output_verbosity.

[mattbrictson]

this is just about using DI instead of static lookup of config options from SSHKit.config.

I hadn't really thought it through that far, but yes, that makes sense. Right now SSHKit isn't injecting any of its own options, but it could inject output_verbosity from the config, which would relieve the formatter from having to do a static lookup.

Perhaps this should be a separate PR, but I was wondering if we should use the newly available @options attribute in the Pretty formatter?

Yes, I think this is a natural evolution of the options idea. You also mentioned it might allow us to collapse Pretty and SimpleText into a single formatter using options to produce the two types of output. My vote is to put those things in a separate PR.

[robd]

If we're not going to use the options in SSHKit, it might be helpful to have a test which demonstrates a sample formatter using the options or a comment which explains to people looking at the code why there is an options parameter passed. People may not know that they have to check the Airbrussh formatter constructor signature, or that the Formatter API must not be changed. I guess they can look at the history and check this PR, but someone might think it is a left over attribute which can be deleted. Unfortunately I don't have any time at the moment, otherwise I would do a PR to use the options within SSHKit. But maybe a comment for now just to give people a heads up to check the Airbrussh Repo?

[mattbrictson]

To clarify, here is my reason for normalizing the Formatter constructors to all accept options:

My primary concern is the scenario where someone specifies :format_options for Airbrussh, but then later switches to a different :format, like :pretty.

If they forget to also delete :format_options, and Pretty's constructor doesn't allow an options argument, then suddenly the user gets a runtime error (Pretty#initialize expects 1 argument, got 2).

If all formatters have the same constructor signature, then this problem goes away. At worst, a formatter might be sent options it doesn't care about and can ignore.

Also: I agree some documentation and/or tests are needed to clarify this intention. I'll update this PR.

On Dec 27, 2015, at 11:05 AM, Rob Dupuis notifications@github.com wrote:

If we're not going to use the options in SSHKit, it might be helpful to have a test which demonstrates a sample formatter using the options or a comment which explains to people looking at the code why there is an options parameter passed. People may not know that they have to check the Airbrussh formatter constructor signature, or that the Formatter API must not be changed. I guess they can look at the history and check this PR, but someone might think it is a left over attribute which can be deleted. Unfortunately I don't have any time at the moment, otherwise I would do a PR to use the options within SSHKit. But maybe a comment for now just to give people a heads up to check the Airbrussh Repo?

―
Reply to this email directly or view it on GitHub.

[robd]

Ahh I see - makes total sense

[mattbrictson]

I've updated the README and added a test to explain the use of formatter options as @robd suggested. I also rebased onto the latest master commit.

Good to merge?

[leehambley]

Looks good. Well played, always nice seeing docs in a PR :)