hammer_cli 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9220eb335ba2042ecc85e93719288e69ad5d2a72e38064d6751f0c3d616a653
-  data.tar.gz: c094be038bcd4b5d0bf40471b17e3d5fb9bdb77ec0b8732823be3fd5254a1dca
+  metadata.gz: 257e54094a8995f71d00dbe29299e84801b68404271de7baaad58b6a9207fe93
+  data.tar.gz: f14b2acba71f1a4ad5a237f7dc6da746a23245ba30c504e689bf5a319e5e86b2
 SHA512:
-  metadata.gz: 9aab1c7d0ad045be9e220266ca5115b6675beffb5fa3d78ffbdbfa72034080287c42008a2d1a81a66a9ab5ac01d5b46e979903679821e73d54806b7deefd9f90
-  data.tar.gz: be143c72f569e96b42dd4ba5ea11fad61169d4b4730b3d31f38ba36e225e241f5f884405c84df4ee279cfd6d62111c35d8b80ac441f396e1906c3166a5dbd171
+  metadata.gz: 559d6704483f5dd8bb2f27ba7c0f8d3c4212033297168fad4cdea0696ee4cd31f8421f1e79cd758b9f4228ff45d2c41751f7509091de0f92ab86a1dab4d97649
+  data.tar.gz: 2396627dc3f2b9d97dca8b0501dc2260b6c02d4a59fbf64e2fbfcdf625d913703dd02d47557193d575156f5a2b1270c81c57ff8caae08345675567d063ecc892

data/doc/creating_commands.md

@@ -477,13 +477,7 @@ directly with `puts` in Hammer. The reason is we separate definition
 of the output from its interpretation. Hammer uses so called _output adapters_
 that can modify the output format.
 
-Hammer comes with four basic output adapters:
-  * __base__   - simple output, structured records
-  * __table__  - records printed in tables, ideal for printing lists of records
-  * __csv__    - comma separated output, ideal for scripting and grepping
-  * __silent__ - no output, used for testing
-
-The detailed documentation on creating adapters is coming soon.
+The detailed documentation on adapters and related things is [here](output.md#adapters).
 
 #### Printing messages
 Very simple, just call
@@ -496,7 +490,7 @@ Typical usage of a CLI is interaction with some API. In many cases it's listing
 some records returned by the API.
 
 Hammer comes with support for selecting and formatting of hash record fields.
-You first create a _output definition_ that you apply to your data. The result
+You first create an _output definition_ that you apply to your data. The result
 is a collection of fields, each having its type. The collection is then passed to an
 _output adapter_ which handles the actual formatting and printing.
 

data/doc/developer_docs.md

@@ -8,6 +8,7 @@ before creating hammer specific plugins.
 Contents:
  - [Writing a plugin](writing_a_plugin.md#writing-your-own-hammer-plugin)
  - [Creating commands](creating_commands.md#create-your-first-command)
+ - [Output adapters, formatters, etc](output.md#output)
  - [Help modification](help_modification.md#modify-an-existing-help)
  - [Commands modification](commands_modification.md#modify-an-existing-command)
  - [Command extensions](commands_extension.md#extend-an-existing-command)
@@ -16,6 +17,7 @@ Contents:
  - [Development tips](development_tips.md#development-tips)
  - [Option normalizers](option_normalizers.md#option-normalizers)
  - [Internationalization](i18n.md#internationalization)
+ - [PR review checklist](review_checklist.md)
 
 Links:
  - slides from tutorial at Config Management Camp 2015: [Hacking with hammer](https://tstrachota.fedorapeople.org/slides/hacking_with_hammer/)

data/doc/help_modification.md

@@ -1,6 +1,38 @@
-Modify an existing help
--------------------------
-Each command might have its own help definition. This definition is composed of various _help items_, which might contain their own definitions.
+# Modify an existing help
+
+### Help items
+Before modifying help, it's good to know which help items are available to use.
+There is a list with currently available items:
+```ruby
+Command.extend_help do |h|
+  # Add a simple text to the help output.
+  # content - String - text to be shown
+  # options - Hash   - options (id:, richtext:)
+  h.text(content, options = {})
+  # Add a notification to the help output (LABEL: content).
+  # content - String - text to be shown
+  # options - Hash   - options (same as #text, label:)
+  h.note(content, options = {})
+  # Add a list of items to the help output.
+  # items   - Array - array of items to be shown. Each item can be either string
+  #                   or an array of ['Key', 'Value', bold: true/false].
+  #                   Item options are optional.
+  #   Example: h.list(['a', 'b', 'c']) => "a\n b\n c\n"
+  #            h.list([['a', 'b', bold: true], ['c', 'd']]) => "a   b\nc   d\n"
+  # options - Hash  - same as #text
+  h.list(items, options = {})
+  # Add a section to the help output.
+  # label   - String - Section header
+  # options - Hash   - same as #text
+  # block   - block with section definition (may include lists/texts/etc.)
+  h.section(label, options = {}) { |h| ... }
+end
+```
+Every `Section`, `List` and simple `Text` is _help item_ defined as `HammerCLI::Help::AbstractItem`, so everything might have its own ID now for easier addressing.
+
+### Help modification
+
+Each command might have its own help definition. This definition is composed of various [_help items_](#Help-items), which might contain their own definitions.
 
 Let's say `hammer host create -h` help string has the following structure:
 ```
@@ -32,7 +64,6 @@ hammer host create -h
 |   |  |  +-- Section
 |   |  |  |  +-- List
 ```
-Every `Section`, `List` and simple `Text` is _help item_ defined as `HammerCLI::Help::AbstractItem`, so everything might have its own ID now for easier addressing.
 
 To modify the structure above, you might use the following:
 ```ruby

data/doc/output.md

@@ -0,0 +1,43 @@
+Output
+------------------------------
+
+### Adapters
+Output adapter is responsible for rendering the output in a specific way using
+__formatters__ (see below).
+Hammer comes with following adapters:
+  * __base__   - simple output, structured records
+  * __table__  - records printed in tables, ideal for printing lists of records
+  * __csv__    - comma separated output, ideal for scripting and grepping
+  * __yaml__   - YAML output
+  * __json__   - JSON output
+  * __silent__ - no output, used for testing
+
+### Formatters
+Formatter is a bit of code that can modify a representation of a field during
+output rendering. Formatter is registered for specific field type. Each field
+type can have multiple formatters.
+  * __ColorFormatter__    - colors data with a specific color
+  * __DateFormatter__     - formats a date string with `%Y/%m/%d %H:%M:%S` style
+  * __ListFormatter__     - formats an array of data with csv style
+  * __KeyValueFormatter__ - formats a hash with `key => value` style
+  * __BooleanFormatter__  - converts `1/0`/`true/false`/`""` to `"yes"`/`"no"`
+  * __LongTextFormatter__ - adds a new line at the start of the data string
+  * __InlineTextFormatter__    - removes all new lines from data string
+  * __MultilineTextFormatter__ - splits a long data string to fixed size chunks
+  with indentation
+
+### Formatter/Adapter features
+Currently used formatter (or adapter) features are of two kinds.
+The first one help us to align by structure of the output:
+  * __:serialized__ - means the fields are serialized into a string (__table__, __csv__, __base__ adapters)
+  * __:structured__ - means the output is structured  (__yaml__, __json__ adapters)
+  * __:inline__     - means that the value will be rendered into single line without newlines (__table__, __csv__ adapters)
+  * __:multiline__  - means that the properly indented value will be printed over multiple lines (__base__ adapter)
+
+The other kind serves to distinguish the cases where we can use the xterm colors
+to improve the output:
+  * __:rich_text__  - means we can use the xterm colors (__table__, __base__ adapters)
+  * __:plain_text__ - unused yet
+
+All the features the formatter has need to match (be present in) the adapter's
+features. Otherwise the formatter won't apply.

data/doc/release_notes.md

@@ -1,7 +1,11 @@
 Release notes
 =============
-### 0.18.1 (2019-10-31)
-* Allow schema building for custom options ([PR #316](https://github.com/theforeman/hammer-cli/pull/316)), [#27899](http://projects.theforeman.org/issues/27899)
+### 0.19.0 (2019-10-26)
+* Allow schema building for custom options ([PR #316](https://github.com/Apipie/apipie-bindings/pull/316)), [#27899](http://projects.theforeman.org/issues/27899)
+* New lines in text attr dont break output ([PR #300](https://github.com/Apipie/apipie-bindings/pull/300)), [#25878](http://projects.theforeman.org/issues/25878)
+* Added error to wrong --output ([PR #315](https://github.com/Apipie/apipie-bindings/pull/315)), [#21590](http://projects.theforeman.org/issues/21590)
+* Pr review checklist ([PR #305](https://github.com/Apipie/apipie-bindings/pull/305)), [#26950](http://projects.theforeman.org/issues/26950)
+* List items in help with customization ([PR #309](https://github.com/Apipie/apipie-bindings/pull/309)), [#27237](http://projects.theforeman.org/issues/27237)
 
 ### 0.18.0 (2019-08-01)
 * Unsure minimal label length ([PR #310](https://github.com/theforeman/hammer-cli/pull/310)) ([#26960](http://projects.theforeman.org/issues/26960))

data/doc/review_checklist.md

@@ -0,0 +1,17 @@
+PR review Checklist
+-------------------
+Before the PR in hammer project is merged the reviewer should check the following things:
+- [ ] Related issue exists
+- [ ] Commit message is in correct format 
+- [ ] The patch fixes the problem described in the issue
+- [ ] UX is consistent across commands
+- [ ] The fix is in the right repo hammer core/hammer plugin/API
+- [ ] It doesn't break compatibility for users
+- [ ] It doesn't break compatibility for hammer plugins (even hammer-cli-foreman is extended by plugins)
+- [ ] Strings are translated and the translations are properly formated
+- [ ] The code is readable and understandable
+- [ ] The code style is consistent with already existing
+- [ ] Docs updated if changing documented patterns or adding new ones
+- [ ] Tests for the new functionality/fix are added
+- [ ] Automated tests are green
+- [ ] Note if multiple commits needs squash on merge

data/lib/hammer_cli/help/definition.rb

@@ -1,5 +1,6 @@
 require_relative 'definition/abstract_item'
 require_relative 'definition/text'
+require_relative 'definition/note'
 require_relative 'definition/list'
 require_relative 'definition/section'
 

data/lib/hammer_cli/help/definition/abstract_item.rb

@@ -3,12 +3,13 @@ module HammerCLI
     class AbstractItem
       INDENT_STEP = 2
 
-      attr_reader :id
+      attr_reader :id, :richtext
       attr_accessor :definition
 
       def initialize(options = {})
         @id = options[:id]
         @indentation = options[:indentation]
+        @richtext = options[:richtext] || false
       end
 
       def build_string

data/lib/hammer_cli/help/definition/list.rb

@@ -36,9 +36,12 @@ module HammerCLI
       end
 
       def format_item(item)
-        col1, col2 = item
+        col1, col2, options = item
+        options ||= {}
+        col1 = HighLine.color(col1.to_s, :bold) if options[:bold]
         col2 = indent(col2.to_s, ' ' * @indent_size).lstrip
-        line = "%-#{@indent_size}s%s" % [col1, col2]
+        padding = col1.length - HammerCLI::Output::Utils.real_length(col1)
+        line = "%-#{@indent_size + padding}s%s" % [col1, col2]
         line.strip!
         line
       end

data/lib/hammer_cli/help/definition/note.rb

@@ -0,0 +1,30 @@
+module HammerCLI
+  module Help
+    class Note < Text
+      def initialize(text, options = {})
+        @label = options[:label] || _('NOTE')
+        super
+      end
+
+      def build_string
+        @text
+      end
+
+      protected
+
+      def build_definition(content)
+        @text = heading + ' '
+        @text += content.to_s
+        @definition = Definition.new([self])
+      end
+
+      private
+
+      def heading
+        @label += ':'
+        @label = HighLine.color(@label, :bold) if @richtext
+        @label
+      end
+    end
+  end
+end

data/lib/hammer_cli/help/definition/section.rb

@@ -6,7 +6,6 @@ module HammerCLI
       def initialize(label, definition = nil, options = {})
         super(options)
         @label = label
-        @richtext = options[:richtext] || false
         @id ||= label
         build_definition(definition)
       end

data/lib/hammer_cli/help/definition/text.rb

@@ -7,7 +7,9 @@ module HammerCLI
       end
 
       def build_string
-        @text
+        text = @text
+        text = HighLine.color(@text, :bold) if @richtext
+        text
       end
 
       protected

data/lib/hammer_cli/help/text_builder.rb

@@ -18,9 +18,14 @@ module HammerCLI
         @definition << HammerCLI::Help::Text.new(content, options)
       end
 
-      def list(items, options = {})
+      def note(content, options = {})
+        @definition << HammerCLI::Help::Note.new(content, options)
+      end
+
+      def list(items, options = {}, &block)
         return if items.empty?
-        @definition << HammerCLI::Help::List.new(items, options)
+
+        @definition << HammerCLI::Help::List.new(items, options, &block)
       end
 
       def section(label, options = {}, &block)

data/lib/hammer_cli/main.rb

@@ -47,8 +47,8 @@ module HammerCLI
       :context_target => :interactive
     option ["--no-headers"], :flag, _("Hide headers from output")
     option ["--csv"], :flag, _("Output as CSV (same as --output=csv)")
-    option ["--output"], "ADAPTER", _("Set output format. One of [%s]") %
-      HammerCLI::Output::Output.adapters.keys.join(', '),
+    option ["--output"], "ADAPTER", _("Set output format"),
+           format: HammerCLI::Options::Normalizers::Enum.new(HammerCLI::Output::Output.adapters.keys.map(&:to_s)),
       :context_target => :adapter
     option ["--output-file"], "OUTPUT_FILE", _("Path to custom output file") do |filename|
       begin

data/lib/hammer_cli/output/adapter/abstract.rb

@@ -3,7 +3,13 @@ module HammerCLI::Output::Adapter
   class Abstract
 
     def tags
-      []
+      %i[]
+    end
+
+    def features
+      return %i[] if tags.empty?
+
+      tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
     end
 
     def initialize(context={}, formatters={}, filters = {})
@@ -101,9 +107,9 @@ module HammerCLI::Output::Adapter
       formatters_map ||= {}
       formatters_map.inject({}) do |map, (type, formatter_list)|
         # remove incompatible formatters
-        filtered = formatter_list.select { |f| f.match?(tags) }
+        filtered = formatter_list.select { |f| f.match?(features) }
         # put serializers first
-        map[type] = filtered.sort_by { |f| f.tags.include?(:flat) ? 0 : 1 }
+        map[type] = filtered.sort_by { |f| f.required_features.include?(:serialized) ? 0 : 1 }
         map
       end
     end

data/lib/hammer_cli/output/adapter/base.rb

@@ -4,8 +4,10 @@ module HammerCLI::Output::Adapter
     GROUP_INDENT = " "*4
     LABEL_DIVIDER = ": "
 
-    def tags
-      [:flat, :screen]
+    def features
+      return %i[serialized rich_text multiline] if tags.empty?
+
+      tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
     end
 
     def print_record(fields, record)

data/lib/hammer_cli/output/adapter/csv.rb

@@ -131,8 +131,10 @@ module HammerCLI::Output::Adapter
       @paginate_by_default = false
     end
 
-    def tags
-      [:flat]
+    def features
+      return %i[serialized inline] if tags.empty?
+
+      tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
     end
 
     def row_data(fields, collection)

data/lib/hammer_cli/output/adapter/table.rb

@@ -12,8 +12,10 @@ module HammerCLI::Output::Adapter
     LINE_SEPARATOR = '-|-'
     COLUMN_SEPARATOR = ' | '
 
-    def tags
-      [:screen, :flat]
+    def features
+      return %i[rich_text serialized inline] if tags.empty?
+
+      tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
     end
 
     def print_record(fields, record)

data/lib/hammer_cli/output/adapter/tree_structure.rb

@@ -5,10 +5,10 @@ module HammerCLI::Output::Adapter
       @paginate_by_default = false
     end
 
-    def tags
-      [
-        :data
-      ]
+    def features
+      return %i[structured] if tags.empty?
+
+      tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
     end
 
     def prepare_collection(fields, collection)

data/lib/hammer_cli/output/fields.rb

@@ -109,6 +109,9 @@ module Fields
   class LongText < Field
   end
 
+  class Text < Field
+  end
+
   class KeyValue < Field
   end
 

data/lib/hammer_cli/output/formatters.rb

@@ -24,28 +24,37 @@ module HammerCLI::Output
       end
     end
 
-    # Tags:
-    # All the tags the formatter has, needs to be present in the addapter.
-    # Otherwise the formatter won't apply. Formatters with :flat tag are used first
-    # as we expect them to serialize the value.
-    #
-    #   - by format: :flat x :data
-    #   - by output: :file X :screen
-
     # abstract formatter
     class FieldFormatter
-
       def tags
-        []
+        %i[]
+      end
+
+      def required_features
+        return %i[] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
-      def match?(other_tags)
-        tags & other_tags == tags
+      def match?(features)
+        required_features & features == required_features
       end
 
       def format(data, field_params={})
         data
       end
+
+      def self.inherited(subclass)
+        subclass.define_singleton_method(:method_added) do |method_name|
+          if method_name == :tags
+            warn(
+              _('Method %{tags} for field formatters and output adapters is deprecated. Please use %{feat} or %{req_feat} instead.') % {
+                tags: 'tags', feat: 'features', req_feat: 'required_features'
+              }
+            )
+          end
+        end
+      end
     end
 
     class FormatterContainer < FieldFormatter
@@ -69,8 +78,10 @@ module HammerCLI::Output
         @color = color
       end
 
-      def tags
-        [:screen, :flat]
+      def required_features
+        return %i[rich_text serialized] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
       def format(data, field_params={})
@@ -80,8 +91,10 @@ module HammerCLI::Output
 
     class DateFormatter < FieldFormatter
 
-      def tags
-        [:flat]
+      def required_features
+        return %i[serialized] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
       def format(string_date, field_params={})
@@ -95,8 +108,10 @@ module HammerCLI::Output
     class ListFormatter < FieldFormatter
       INDENT = "  "
 
-      def tags
-        [:flat]
+      def required_features
+        return %i[serialized] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
       def format(list, field_params={})
@@ -117,8 +132,10 @@ module HammerCLI::Output
 
     class KeyValueFormatter < FieldFormatter
 
-      def tags
-        [:screen, :flat]
+      def required_features
+        return %i[rich_text serialized] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
       def format(params, field_params={})
@@ -140,8 +157,10 @@ module HammerCLI::Output
         @indent = options[:indent].nil? ? true : options[:indent]
       end
 
-      def tags
-        [:screen]
+      def required_features
+        return %i[rich_text] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
       def format(text, field_params={})
@@ -150,10 +169,42 @@ module HammerCLI::Output
       end
     end
 
+    class InlineTextFormatter < FieldFormatter
+      def required_features
+        return %i[serialized inline] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
+      end
+
+      def format(text, _field_params = {})
+        text.to_s.tr("\r\n", ' ')
+      end
+    end
+
+    class MultilineTextFormatter < FieldFormatter
+      INDENT = '    '.freeze
+      MAX_WIDTH = 120
+      MIN_WIDTH = 60
+
+      def required_features
+        return %i[serialized multiline rich_text] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
+      end
+
+      def format(text, field_params = {})
+        width = [[field_params.fetch(:width, 0), MIN_WIDTH].max, MAX_WIDTH].min
+        text.to_s.chars.each_slice(width).map(&:join).join("\n")
+            .indent_with(INDENT).prepend("\n")
+      end
+    end
+
     class BooleanFormatter < FieldFormatter
 
-      def tags
-        [:flat, :screen]
+      def required_features
+        return %i[serialized rich_text] if tags.empty?
+
+        tags.map { |t| HammerCLI::Output::Utils.tag_to_feature(t) }
       end
 
       def format(value, field_params={})
@@ -165,10 +216,9 @@ module HammerCLI::Output
     HammerCLI::Output::Output.register_formatter(ListFormatter.new, :List)
     HammerCLI::Output::Output.register_formatter(KeyValueFormatter.new, :KeyValue)
     HammerCLI::Output::Output.register_formatter(LongTextFormatter.new, :LongText)
+    HammerCLI::Output::Output.register_formatter(InlineTextFormatter.new, :Text)
+    HammerCLI::Output::Output.register_formatter(MultilineTextFormatter.new, :Text)
     HammerCLI::Output::Output.register_formatter(BooleanFormatter.new, :Boolean)
 
   end
 end
-
-
-