Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Fixes #25878 - New lines in text attr dont break output #300
The fix adds a possibility to print long text (e.g. descriptions) with line breakers into one line. Simply changes new lines into spaces. This can be achieved with
JSON and YAML output is not changed, since all whitespaces are escaped there.
@ofedoren thanks for the PR! I tested it and it works as expected. However I'm not bought for the way it is implemented. Maybe we can use this issue to make the Adapters - Formatters - Tags more understandable and better documented. It is a pain for a long time and it takes too much affort to figure out how it works every time we need to change something. I did the exercise again and here is what I re-learned and hopefully base for some documentation:
Adapter is responsible for rendering the output in a specific way (table, csv, yaml).
As the adapters vary significantly in the output structure and purpose we need to limit some formatters for specific adapters only. Hammer is designed to allow adding new adapters also from plugins so we need something flexible to bind the formatters correctly even to possible future adapters. The Tags serves for this purpose. Maybe adapter category would be better name for it. In practice the adapters have tags and the formatters have the same tags too. Formatter is applied during rendering of the field only if all the tags it has are also in the target adapter.
E.g. RedNegativeFormatter that prints negative numbers in red for NumericFields would have tags
Currently used tags are of two kinds. The first one help us to align by structure of the output. :flat means the fields are serialized into a string (:table, :csv, :base adapters), :data means the output is structured (:yaml and :json adapters). The other kind serves to distinguish the cases where we can use the xterm colors to improve the output and the relevant tags are :screen and :file. For this group the :table and :basic adapters have the :screen tag (:file is unused yet, maybe was intended as non-interractive output). This makes it possible that the RedNegativeFormatter from our example is applied only by :table and :base adapters and our xterm color escape sequences do not pollute the output in CSV or YAML.
The tags are symbols and can be freely added e.g. by plugins when necessary. We can have plugin adding XML adapter and some specific XML related formatters and binding them with a :xml tag.
So back to the PR - we should avoid adding :screen tag to :csv adapter. To dispatch the formatter correctly we may add new tag :inline that would indicate that the value will render into single line without newlines. Good candidates for this would be :table and :csv adapters. In :base adapter I think we may still print description over multiple lines though properly indented. For this :multiline tag could serve. then we could have two formatters one for :flat,:inline and one for :flat,:multiline.
Would it make sense? Are there any better solutions?
Also do we want to re-design our tags to make it cleaner? As probably no third-party adapters were added by plugins since the start of the project we can resign on the flexibility and list adapters the formatter is applicable in in each formatter (instead of the tags). That could make it clean and clear. on the other hand adding new adapter would require update in plugins that are adding own formatters for their specific value types.
I've added two additional formatters as you suggested and some documentation about adapters, formatters, tags: https://github.com/ofedoren/hammer-cli/blob/ac6bbb8bf2d0388aa53d7bd2fd783043f57c2464/doc/output.md
Also, I've refactored
If you don't like to have two names for pretty same thing, I'd suggest another one:
@ofedoren I almost merged this but I realized we have also formatters in hammer plugins and I believe renaming tags will break data rendering there. I guess we can keep the tags method and read it from the
Your approach made me to look at it from different perspective and maybe it could be pushed even further if we renamed the tags/features/limitations:
but the question is if the added value is worth the troubles with keeping the plugins compatible.
@mbacovsky, thanks for another detailed review :) I agree that renaming adapter's
I've also thought about renaming
@ofedoren sounds great!