hammer_cli 3.0.2 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7036ad620797bd887a62908eef5231092a47f019b5426ca4f4232c1c9e3c8791
-  data.tar.gz: 49c8e269f005306bb0f12031c59366d0d3ffb892cd08fef9926644477caa2ffd
+  metadata.gz: 510f07df29c39c069ae58e923507361a276e12ef50cc38628868361794a7754c
+  data.tar.gz: 13790a4114574688531978c11a9bb479062381d1b5196168f6d0e70deddc6a43
 SHA512:
-  metadata.gz: dbe31f4f8ab404b407754247f4887deb4687ad6b45cb0b2428757d3817192de9b8edd4f2c4cd95a3414047e92cfb9fd461eeef3ff200c47497a64d41da2500be
-  data.tar.gz: 93e25574abdfe8cf2942427ac55cf7c6c7667df0f277c630fdb644f14ab3cecb70e3c15f54f009c6d3cd6d0e37a3fd602f4cd23560c3b64bdb3baf223b99643f
+  metadata.gz: a8bd5241448ccae9b7bd27f4260ebe5cbc8d75f2a79dcf76fb710c13e7bba42275cda6332acd6b67c33125572393b17e1f2d1575166ce8edfc76c7a81cdb9854
+  data.tar.gz: 9656ed10f1c8d44f35f0d321e1568d82a9607dc82b5ecf3e03999ec471eb67aa5dc119fcc31c90b1f540bab4a3d5abc5eff444d498eb275a7e0b061c61426fcf

data/doc/creating_commands.md

@@ -190,6 +190,23 @@ To define an option family, use the following DSL:
   end
 ```
 
+You can also add additional options for automatically built ones:
+```ruby
+  # ...
+  build_options
+  # If --resource-id option comes from the API params and you want to add options
+  # with searchables such as --resource-name, --resource-label
+  option_family(associate: 'resource') do
+    child '--resource-name', 'RESOURCE', _('Resource desc'), attribute_name: :option_resource_name
+    child '--resource-label', 'RESOURCE', _('Resource desc'), attribute_name: :option_resource_label
+  end
+  # $ hammer command --help:
+  # ...
+  #  Options:
+  #    --resource[-id|-name|-label]               Resource desc
+  # ...
+```
+
 ##### Example
 
 ```ruby

data/doc/release_notes.md

@@ -1,10 +1,16 @@
 Release notes
 =============
-### 3.0.2 (2022-02-01)
-* Fix fr translation ([PR #358](https://github.com/theforeman/hammer-cli/pull/358)), [#34204](http://projects.theforeman.org/issues/34204)
-
-### 3.0.1 (2021-11-02)
+### 3.1.0 (2021-11-10)
 * Remove a space in hammer's shebang, [#33810](http://projects.theforeman.org/issues/33810)
+* Revert fix rake version
+* Fix rake version
+* Wrap option descriptions to 80 chars, [#33129](http://projects.theforeman.org/issues/33129)
+* Don't store @context in field params, [#33259](http://projects.theforeman.org/issues/33259)
+* Change from superficial copy to deep copy of fields ([PR #348](https://github.com/theforeman/hammer-cli/pull/348)), [#29093](http://projects.theforeman.org/issues/29093)
+* Make api docs params to be the main options, [#33226](http://projects.theforeman.org/issues/33226)
+* Show depr warning only on option usage, [#33225](http://projects.theforeman.org/issues/33225)
+* Extract descs to option details section, [#32783](http://projects.theforeman.org/issues/32783)
+* Bump to 3.1.0-develop
 
 ### 3.0.0 (2021-08-04)
 * Update rel-eng notebook ([PR #347](https://github.com/theforeman/hammer-cli/pull/347))

data/lib/hammer_cli/abstract.rb

@@ -25,6 +25,18 @@ module HammerCLI
     class << self
       attr_accessor :validation_blocks
 
+      def family_registry
+        @family_registry ||= HammerCLI::Options::OptionFamilyRegistry.new
+      end
+
+      def option_families
+        ancestors.inject([]) do |registry, ancestor|
+          next registry unless ancestor <= HammerCLI::AbstractCommand
+
+          registry + ancestor.family_registry
+        end
+      end
+
       def help_extension_blocks
         @help_extension_blocks ||= []
       end
@@ -43,25 +55,37 @@ module HammerCLI
         extensions
       end
 
-      def extend_options_help(option)
+      def add_option_schema(option)
         extend_help do |h|
+          option_details = h.find_item(:s_option_details)
           begin
-            h.find_item(:s_option_details)
+            option_details.definition.find_item(:t_schema_help)
           rescue ArgumentError
-            option_details = HammerCLI::Help::Section.new(_('Option details'), nil, id: :s_option_details, richtext: true)
             option_details.definition << HammerCLI::Help::Text.new(
               _('Following parameters accept format defined by its schema ' \
-                '(bold are required; <> contain acceptable type; [] contain acceptable value):')
+                '(bold are required; <> contains acceptable type; [] contains acceptable value):'),
+              id: :t_schema_help
             )
-            h.definition.unshift(option_details)
-          ensure
-            h.find_item(:s_option_details).definition << HammerCLI::Help::List.new([
-              [option.switches.last, option.value_formatter.schema.description]
-            ])
           end
+          option_details.definition << HammerCLI::Help::List.new([
+            [option.switches.last, option.value_formatter.schema.description]
+          ])
         end
       end
 
+      def add_option_details_section(help)
+        option_details = HammerCLI::Help::Section.new(_('Option details'), nil, id: :s_option_details, richtext: true)
+        option_details.definition << HammerCLI::Help::Text.new(
+          _('Here you can find option types and the value an option can accept:')
+        )
+        type_list = HammerCLI::Options::Normalizers.available.each_with_object([]) do |n, l|
+          l << [n.completion_type.to_s.upcase, n.common_description]
+        end.uniq(&:first).sort
+
+        option_details.definition << HammerCLI::Help::List.new(type_list)
+        help.definition.unshift(option_details)
+      end
+
       def add_sets_help(help)
         sets_details = HammerCLI::Help::Section.new(_('Predefined field sets'), nil, id: :s_sets_details, richtext: true)
         sets_details.definition << HammerCLI::Help::Text.new(output_definition.sets_table)
@@ -138,6 +162,7 @@ module HammerCLI
       super(invocation_path, builder)
       help_extension = HammerCLI::Help::TextBuilder.new(builder.richtext)
       fields_switch = HammerCLI::Options::Predefined::OPTIONS[:fields].first[0]
+      add_option_details_section(help_extension) if recognised_options.size > 1
       add_sets_help(help_extension) if find_option(fields_switch)
       unless help_extension_blocks.empty?
         help_extension_blocks.each do |extension_block|
@@ -194,18 +219,29 @@ module HammerCLI
       @option_builder
     end
 
+    def self.option(switches, type, description, opts = {}, &block)
+      option = HammerCLI::Options::OptionDefinition.new(switches, type, description, opts).tap do |option|
+        declared_options << option
+        block ||= option.default_conversion_block
+        define_accessors_for(option, &block)
+        add_option_schema(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
+        completion_type_for(option, opts)
+      end
+      option
+    end
+
     def self.build_options(builder_params={})
       builder_params = yield(builder_params) if block_given?
+      builder_params[:command] = self
 
       option_builder.build(builder_params).each do |option|
         # skip switches that are already defined
-        next if option.nil? || option.switches.any? { |s| find_option(s) }
+        next if option.nil? || option.family || option.switches.any? { |s| find_option(s) }
 
-        adjust_family(option) if option.respond_to?(:family)
         declared_options << option
         block ||= option.default_conversion_block
         define_accessors_for(option, &block)
-        extend_options_help(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
+        add_option_schema(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
         completion_type_for(option)
       end
     end
@@ -233,14 +269,20 @@ module HammerCLI
       end
     end
 
-    protected
-
     def self.option_family(options = {}, &block)
       options[:creator] ||= self
-      family = HammerCLI::Options::OptionFamily.new(options)
-      family.instance_eval(&block)
+      family = if options[:associate]
+                 option_families.find { |f| f.root.to_s == options[:associate].to_s }
+               else
+                 HammerCLI::Options::OptionFamily.new(options)
+               end
+      return family.instance_eval(&block) if family
+
+      logger('Option Family').debug "No family found for #{options[:associate]}, skipping"
     end
 
+    protected
+
     def self.find_options(switch_filter, other_filters={})
       filters = other_filters
       if switch_filter.is_a? Hash
@@ -339,17 +381,6 @@ module HammerCLI
       end
     end
 
-    def self.option(switches, type, description, opts = {}, &block)
-      option = HammerCLI::Options::OptionDefinition.new(switches, type, description, opts).tap do |option|
-        declared_options << option
-        block ||= option.default_conversion_block
-        define_accessors_for(option, &block)
-        completion_type_for(option, opts)
-      end
-      extend_options_help(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
-      option
-    end
-
     def all_options
       option_collector.all_options
     end
@@ -412,32 +443,6 @@ module HammerCLI
 
     private
 
-    def self.adjust_family(option)
-      # Collect options that should share the same family
-      # If those options have family, adopt the current one
-      # Else adopt those options to the family of the current option
-      # NOTE: this shouldn't rewrite any options,
-      # although options from similar family could be adopted (appended)
-      options = find_options(
-        aliased_resource: option.aliased_resource.to_s
-      ).select { |o| o.family.nil? || o.family.formats.include?(option.value_formatter.class) }.group_by do |o|
-        next :to_skip if option.family.children.include?(o)
-        next :to_adopt if o.family.nil? || o.family.head.nil?
-        next :to_skip if o.family.children.include?(option)
-        # If both family heads handle the same switch
-        # then `option` is probably from similar family and can be adopted
-        next :adopt_by if option.family.head.nil? || o.family.head.handles?(option.family.head.long_switch)
-
-        :to_skip
-      end
-      options[:to_adopt]&.each do |child|
-        option.family&.adopt(child)
-      end
-      options[:adopt_by]&.map(&:family)&.uniq&.each do |family|
-        family.adopt(option)
-      end
-    end
-
     def self.inherited_output_definition
       od = nil
       if superclass.respond_to? :output_definition

data/lib/hammer_cli/apipie/command.rb

@@ -86,9 +86,9 @@ module HammerCLI::Apipie
         declared_options << option
         block ||= option.default_conversion_block
         define_accessors_for(option, &block)
+        add_option_schema(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
         completion_type_for(option, opts)
       end
-      extend_options_help(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
       option
     end
 

data/lib/hammer_cli/apipie/option_builder.rb

@@ -9,11 +9,11 @@ module HammerCLI::Apipie
       @require_options = options[:require_options].nil? ? true : options[:require_options]
     end
 
-    def build(builder_params={})
+    def build(builder_params = {})
       filter = Array(builder_params[:without])
       resource_name_map = builder_params[:resource_mapping] || {}
 
-      options_for_params(@action.params, filter, resource_name_map)
+      options_for_params(@action.params, filter, resource_name_map, command: builder_params[:command])
     end
 
     attr_writer :require_options
@@ -27,21 +27,24 @@ module HammerCLI::Apipie
       HammerCLI::Apipie::OptionDefinition.new(*args)
     end
 
-    def options_for_params(params, filter, resource_name_map)
-      opts = []
+    def options_for_params(params, filter, resource_name_map, opts = {})
+      options = []
       params.each do |p|
-        next if filter.include?(p.name) || filter.include?(p.name.to_sym)
+        exists = opts[:command].find_option(option_switch(p, resource_name_map))
+        next if filter.include?(p.name) || filter.include?(p.name.to_sym) || exists
+
         if p.expected_type == :hash
-          opts += options_for_params(p.params, filter, resource_name_map)
+          options += options_for_params(p.params, filter, resource_name_map, opts)
         else
-          opts << create_option(p, resource_name_map)
+          options << create_option(p, resource_name_map, opts)
         end
       end
-      opts
+      options
     end
 
-    def create_option(param, resource_name_map)
-      family = HammerCLI::Options::OptionFamily.new
+    def create_option(param, resource_name_map, opts = {})
+      family = HammerCLI::Options::OptionFamily.new(creator: opts[:command])
+      # APIdoc params are considered to be the main options (parent) by default
       family.parent(option_switch(param, resource_name_map),
                     option_type(param, resource_name_map),
                     option_desc(param),

data/lib/hammer_cli/apipie/option_definition.rb

@@ -2,22 +2,15 @@ require File.join(File.dirname(__FILE__), 'options')
 
 module HammerCLI::Apipie
   class OptionDefinition < HammerCLI::Options::OptionDefinition
-    attr_accessor :referenced_resource, :aliased_resource, :family
+    attr_accessor :referenced_resource, :aliased_resource
 
     def initialize(switches, type, description, options = {})
       @referenced_resource = options[:referenced_resource].to_s if options[:referenced_resource]
       @aliased_resource = options[:aliased_resource].to_s if options[:aliased_resource]
-      @family = options[:family]
       super
       # Apipie currently sends descriptions as escaped HTML once this is changed this should be removed.
       # See #15198 on Redmine.
       @description = CGI::unescapeHTML(description)
     end
-
-    def child?
-      return unless @family
-
-      @family.children.include?(self)
-    end
   end
 end

data/lib/hammer_cli/command_extensions.rb

@@ -87,8 +87,11 @@ module HammerCLI
     end
 
     def self.option_family(options = {}, &block)
-      @option_family_opts = options
-      @option_family_block = block
+      @option_family_extensions ||= []
+      @option_family_extensions << {
+        options: options,
+        block: block
+      }
     end
 
     # Object
@@ -256,11 +259,13 @@ module HammerCLI
     end
 
     def self.extend_option_family(command_class)
-      return if @option_family_block.nil?
+      return if @option_family_extensions.nil?
 
-      @option_family_opts[:creator] = command_class
-      command_class.send(:option_family, @option_family_opts, &@option_family_block)
-      logger.debug("Called option family block for #{command_class}:\n\t#{@option_family_block}")
+      @option_family_extensions.each do |extension|
+        extension[:options][:creator] = command_class
+        command_class.send(:option_family, extension[:options], &extension[:block])
+        logger.debug("Called option family block for #{command_class}:\n\t#{extension[:block]}")
+      end
     end
   end
 end

data/lib/hammer_cli/help/builder.rb

@@ -29,7 +29,11 @@ module HammerCLI
 
         label_width = DEFAULT_LABEL_INDENT
         items.each do |item|
-          label = item.help.first
+          label = if !HammerCLI.context[:full_help] && item.respond_to?(:family) && item.family && !item.child?
+                    item.family.help.first
+                  else
+                    item.help.first
+                  end
           label_width = label.size if label.size > label_width
         end
 
@@ -38,11 +42,11 @@ module HammerCLI
             next unless HammerCLI.context[:full_help]
           end
           label, description = if !HammerCLI.context[:full_help] && item.respond_to?(:family) && item.family
-            [item.family.switch, item.family.description || item.help[1]]
-          else
-            item.help
-          end
-          description.gsub(/^(.)/) { Unicode::capitalize($1) }.each_line do |line|
+                                 item.family.help
+                               else
+                                 item.help
+                               end
+          description.gsub(/^(.)/) { Unicode.capitalize(Regexp.last_match(1)) }.wrap.each_line do |line|
             puts " %-#{label_width}s %s" % [label, line]
             label = ''
           end

data/lib/hammer_cli/options/normalizers.rb

@@ -4,8 +4,28 @@ require 'hammer_cli/csv_parser'
 module HammerCLI
   module Options
     module Normalizers
+      def self.available
+        AbstractNormalizer.available
+      end
 
       class AbstractNormalizer
+        class << self
+          attr_reader :available
+
+          def inherited(subclass)
+            @available ||= []
+            @available << subclass
+          end
+
+          def completion_type
+            :value
+          end
+
+          def common_description
+            _("Value described in the option's description. Mostly simple string")
+          end
+        end
+
         def description
           ""
         end
@@ -17,6 +37,10 @@ module HammerCLI
         def complete(val)
           []
         end
+
+        def completion_type
+          { type: self.class.completion_type }
+        end
       end
 
       class Default < AbstractNormalizer
@@ -30,9 +54,15 @@ module HammerCLI
         PAIR_RE = '([^,=]+)=([^,\{\[]+|[\{\[][^\{\}\[\]]*[\}\]])'
         FULL_RE = "^((%s)[,]?)+$" % PAIR_RE
 
-        def description
-          _("Comma-separated list of key=value.") + "\n" +
-          _("JSON is acceptable and preferred way for complex parameters")
+        class << self
+          def completion_type
+            :key_value_list
+          end
+
+          def common_description
+            _('Comma-separated list of key=value.') + "\n" +
+              _('JSON is acceptable and preferred way for such parameters')
+          end
         end
 
         def format(val)
@@ -94,9 +124,16 @@ module HammerCLI
 
 
       class List < AbstractNormalizer
-        def description
-          _("Comma separated list of values. Values containing comma should be quoted or escaped with backslash.") + "\n" +
-          _("JSON is acceptable and preferred way for complex parameters")
+        class << self
+          def completion_type
+            :list
+          end
+
+          def common_description
+            _('Comma separated list of values. Values containing comma should be quoted or escaped with backslash.') +
+              "\n" +
+              _('JSON is acceptable and preferred way for such parameters')
+          end
         end
 
         def format(val)
@@ -110,6 +147,18 @@ module HammerCLI
       end
 
       class ListNested < AbstractNormalizer
+        class << self
+          def completion_type
+            :schema
+          end
+
+          def common_description
+            _('Comma separated list of values defined by a schema.') +
+              "\n" +
+              _('JSON is acceptable and preferred way for such parameters')
+          end
+        end
+
         class Schema < Array
           def description(richtext: true)
             '"' + reduce([]) do |schema, nested_param|
@@ -135,11 +184,6 @@ module HammerCLI
           @schema = Schema.new(schema)
         end
 
-        def description
-          _("Comma separated list of values defined by a schema. See Option details section below.") + "\n" +
-          _("JSON is acceptable and preferred way for complex parameters")
-        end
-
         def format(val)
           return [] unless val.is_a?(String) && !val.empty?
           begin
@@ -152,9 +196,22 @@ module HammerCLI
             end
           end
         end
+
+        def completion_type
+          super.merge({ schema: schema.description(richtext: false) })
+        end
       end
 
       class Number < AbstractNormalizer
+        class << self
+          def completion_type
+            :number
+          end
+
+          def common_description
+            _('Numeric value. Integer')
+          end
+        end
 
         def format(val)
           if numeric?(val)
@@ -167,17 +224,22 @@ module HammerCLI
         def numeric?(val)
           Integer(val) != nil rescue false
         end
-
       end
 
 
       class Bool < AbstractNormalizer
-        def allowed_values
-          ['yes', 'no', 'true', 'false', '1', '0']
+        class << self
+          def completion_type
+            :boolean
+          end
+
+          def common_description
+            _('One of %s') % ['true/false', 'yes/no', '1/0'].join(', ')
+          end
         end
 
-        def description
-          _('One of %s.') % ['true/false', 'yes/no', '1/0'].join(', ')
+        def allowed_values
+          ['yes', 'no', 'true', 'false', '1', '0']
         end
 
         def format(bool)
@@ -194,10 +256,23 @@ module HammerCLI
         def complete(value)
           allowed_values.map { |v| v + ' ' }
         end
+
+        def completion_type
+          super.merge({ values: allowed_values })
+        end
       end
 
 
       class File < AbstractNormalizer
+        class << self
+          def completion_type
+            :file
+          end
+
+          def common_description
+            _('Path to a file')
+          end
+        end
 
         def format(path)
           ::File.read(::File.expand_path(path))
@@ -233,6 +308,16 @@ module HammerCLI
 
 
       class Enum < AbstractNormalizer
+        class << self
+          def completion_type
+            :enum
+          end
+
+          def common_description
+            _("Possible values are described in the option's description")
+          end
+        end
+
         attr_reader :allowed_values
 
         def initialize(allowed_values)
@@ -260,6 +345,10 @@ module HammerCLI
           Completer::finalize_completions(@allowed_values)
         end
 
+        def completion_type
+          super.merge({ values: allowed_values })
+        end
+
         private
 
         def quoted_values
@@ -269,9 +358,14 @@ module HammerCLI
 
 
       class DateTime < AbstractNormalizer
+        class << self
+          def completion_type
+            :datetime
+          end
 
-        def description
-          _("Date and time in YYYY-MM-DD HH:MM:SS or ISO 8601 format")
+          def common_description
+            _('Date and time in YYYY-MM-DD HH:MM:SS or ISO 8601 format')
+          end
         end
 
         def format(date)
@@ -283,6 +377,16 @@ module HammerCLI
       end
 
       class EnumList < AbstractNormalizer
+        class << self
+          def completion_type
+            :multienum
+          end
+
+          def common_description
+            _("Any combination of possible values described in the option's description")
+          end
+        end
+
         attr_reader :allowed_values
 
         def initialize(allowed_values)
@@ -301,6 +405,10 @@ module HammerCLI
           Completer::finalize_completions(@allowed_values)
         end
 
+        def completion_type
+          super.merge({ values: allowed_values })
+        end
+
         private
 
         def quoted_values

data/lib/hammer_cli/options/option_definition.rb

@@ -22,12 +22,14 @@ module HammerCLI
 
     class OptionDefinition < Clamp::Option::Definition
 
-      attr_accessor :value_formatter, :context_target, :deprecated_switches
+      attr_accessor :value_formatter, :context_target, :deprecated_switches,
+                    :family
 
       def initialize(switches, type, description, options = {})
         @value_formatter = options[:format] || HammerCLI::Options::Normalizers::Default.new
         @context_target = options[:context_target]
         @deprecated_switches = options[:deprecated]
+        @family = options[:family]
         super
       end
 
@@ -36,7 +38,9 @@ module HammerCLI
       end
 
       def help_lhs
-        super
+        lhs = switches.join(', ')
+        lhs += " #{completion_type[:type]}".upcase unless flag?
+        lhs
       end
 
       def help_rhs
@@ -50,14 +54,14 @@ module HammerCLI
         rhs.empty? ? " " : rhs
       end
 
-      def handles?(switch)
+      def extract_value(switch, arguments)
         message = _("Warning: Option %{option} is deprecated. %{message}")
         if deprecated_switches.class <= String && switches.include?(switch)
-          warn(message % { :option => switch, :message => deprecated_switches })
+          warn(message % { option: switch, message: deprecated_switches })
         elsif deprecated_switches.class <= Hash && deprecated_switches.keys.include?(switch)
-          warn(message % { :option => switch, :message => deprecated_switches[switch] })
+          warn(message % { option: switch, message: deprecated_switches[switch] })
         end
-        super(switch)
+        super(switch, arguments)
       end
 
       def deprecation_message(switch)
@@ -140,22 +144,13 @@ module HammerCLI
         return { type: :flag } if @type == :flag
 
         formatter ||= value_formatter
-        completion_type = case formatter
-                          when HammerCLI::Options::Normalizers::Bool,
-                               HammerCLI::Options::Normalizers::Enum
-                            { type: :enum, values: value_formatter.allowed_values }
-                          when HammerCLI::Options::Normalizers::EnumList
-                            { type: :multienum, values: value_formatter.allowed_values }
-                          when HammerCLI::Options::Normalizers::ListNested
-                            { type: :schema, schema: value_formatter.schema.description(richtext: false) }
-                          when HammerCLI::Options::Normalizers::List
-                            { type: :list }
-                          when HammerCLI::Options::Normalizers::KeyValueList
-                            { type: :key_value_list }
-                          when HammerCLI::Options::Normalizers::File
-                            { type: :file }
-                          end
-        completion_type || { type: :value }
+        formatter.completion_type
+      end
+
+      def child?
+        return unless @family
+
+        @family.children.include?(self)
       end
 
       private

data/lib/hammer_cli/options/option_family.rb

@@ -2,25 +2,33 @@
 
 module HammerCLI
   module Options
+    class OptionFamilyRegistry < Array
+      # rubocop:disable Style/Alias
+      alias_method :register, :push
+      alias_method :unregister, :delete
+      # rubocop:enable Style/Alias
+    end
+
     class OptionFamily
       attr_reader :children
 
-      IDS_REGEX = /(\A[Ii][Dd][s]?)|\s([Ii][Dd][s]?)\W|([Ii][Dd][s]?\Z)/
+      IDS_REGEX = /(\A[Ii][Dd][s]?)|\s([Ii][Dd][s]?)\W|([Ii][Dd][s]?\Z)|(numeric identifier|identifier)/.freeze
 
       def initialize(options = {})
         @all = []
         @children = []
         @options = options
-        @creator = options[:creator] || Class.new(HammerCLI::Apipie::Command)
+        @creator = options[:creator] || self
         @prefix = options[:prefix]
         @root = options[:root] || options[:aliased_resource] || options[:referenced_resource]
+        @creator.family_registry.register(self) if @creator != self
       end
 
       def description
         types = all.map(&:type).map { |s| s.split('_').last.to_s }
                    .map(&:downcase).join('/')
-        parent_desc = @parent.help[1].gsub(IDS_REGEX) { |w| w.gsub(/\w+/, types) }
-        desc = parent_desc.strip.empty? ? @options[:description] : parent_desc
+        parent_desc = @parent.help[1].gsub(IDS_REGEX) { |w| w.gsub(/\b.+\b/, types) }
+        desc = @options[:description] || parent_desc.strip.empty? ? @options[:description] : parent_desc
         if @options[:deprecation].class <= String
           format_deprecation_msg(desc, _('Deprecated: %{deprecated_msg}') % { deprecated_msg: @options[:deprecation] })
         elsif @options[:deprecation].class <= Hash
@@ -33,6 +41,21 @@ module HammerCLI
         end
       end
 
+      def help
+        [help_lhs, help_rhs]
+      end
+
+      def help_lhs
+        return @parent&.help_lhs if @children.empty?
+
+        types = all.map(&:value_formatter).map { |f| f.completion_type[:type].to_s.upcase }
+        switch + ' ' + types.uniq.join('/')
+      end
+
+      def help_rhs
+        description || @parent.help[1]
+      end
+
       def formats
         return [@options[:format].class] if @options[:format]
 
@@ -41,7 +64,7 @@ module HammerCLI
 
       def switch
         return if @parent.nil? && @children.empty?
-        return @parent.help_lhs.strip if @children.empty?
+        return @parent.switches.join(', ').strip if @children.empty?
 
         switch_start = main_switch.each_char
                                   .zip(*all.map(&:switches).flatten.map(&:each_char))
@@ -68,6 +91,8 @@ module HammerCLI
 
       def child(switches, type, description, opts = {}, &block)
         child = new_member(switches, type, description, opts, &block)
+        return unless child
+
         @children << child
         child
       end
@@ -80,6 +105,18 @@ module HammerCLI
         @children << child
       end
 
+      def root
+        @root || @parent&.aliased_resource || @parent&.referenced_resource || common_root
+      end
+
+      def option(*args)
+        HammerCLI::Apipie::OptionDefinition.new(*args)
+      end
+
+      def find_option(switch)
+        all.find { |m| m.handles?(switch) }
+      end
+
       private
 
       def format_deprecation_msg(option_desc, deprecation_msg)
@@ -90,18 +127,17 @@ module HammerCLI
         opts = opts.merge(@options)
         opts[:family] = self
         if opts[:deprecated]
-          handles = [switches].flatten
+          handles = Array(switches)
           opts[:deprecated] = opts[:deprecated].select do |switch, _msg|
             handles.include?(switch)
           end
         end
         @creator.instance_eval do
-          option(switches, type, description, opts, &block)
+          option(switches, type, description, opts, &block) unless Array(switches).any? { |s| find_option(s) }
         end
       end
 
       def main_switch
-        root = @root || @parent.aliased_resource || @parent.referenced_resource || common_root
         "--#{@prefix}#{root}".tr('_', '-')
       end
 

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

@@ -97,6 +97,12 @@ module HammerCLI::Output::Adapter
       @context[:fields] || ['DEFAULT']
     end
 
+    def context_for_fields
+      {
+        show_ids: @context[:show_ids]
+      }
+    end
+
     private
 
     def filter_formatters(formatters_map)

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

@@ -76,7 +76,7 @@ module HammerCLI::Output::Adapter
     def render_value(field, data)
       formatter = @formatters.formatter_for_type(field.class)
       parameters = field.parameters
-      parameters[:context] = @context
+      parameters[:context] = context_for_fields
       data = formatter.format(data, field.parameters) if formatter
       data.to_s
     end

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

@@ -55,7 +55,7 @@ module HammerCLI::Output::Adapter
       else
         formatter = @formatters.formatter_for_type(field.class)
         parameters = field.parameters
-        parameters[:context] = @context
+        parameters[:context] = context_for_fields
         if formatter
           data = formatter.format(data, field.parameters)
         end

data/lib/hammer_cli/output/field_filter.rb

@@ -11,7 +11,7 @@ module HammerCLI::Output
 
     def fields=(fields)
       @fields = fields || []
-      @filtered_fields = @fields.dup
+      @filtered_fields = Marshal.load(Marshal.dump(@fields))
     end
 
     def filter_by_classes(classes = nil)

data/lib/hammer_cli/utils.rb

@@ -40,6 +40,12 @@ class String
     HammerCLI.constant_path(self)[-1]
   end
 
+  # Rails implementation: https://github.com/rails/rails/blob/main/actionview/lib/action_view/helpers/text_helper.rb#L260
+  def wrap(line_width: 80, break_sequence: "\n")
+    split("\n").collect! do |line|
+      line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
+    end * break_sequence
+  end
 end
 
 class Hash

data/lib/hammer_cli/version.rb

@@ -1,5 +1,5 @@
 module HammerCLI
   def self.version
-    @version ||= Gem::Version.new "3.0.2"
+    @version ||= Gem::Version.new "3.1.0"
   end
 end

data/test/unit/abstract_test.rb

@@ -308,6 +308,13 @@ describe HammerCLI::AbstractCommand do
       opt = TestOptionCmd.find_option('--fields')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal true
     end
+
+    it 'should add option type and accepted value' do
+      help_str = TestOptionCmd.help('')
+      help_str.must_match(
+        /LIST                Comma separated list of values. Values containing comma should be quoted or escaped with backslash./
+      )
+    end
   end
 
   describe "#options" do

data/test/unit/apipie/option_builder_test.rb

@@ -17,7 +17,7 @@ describe HammerCLI::Apipie::OptionBuilder do
   let(:resource) {api.resource(:documented)}
   let(:action) {resource.action(:index)}
   let(:builder) { HammerCLI::Apipie::OptionBuilder.new(resource, action) }
-  let(:builder_options) { {} }
+  let(:builder_options) { { command: Class.new(HammerCLI::Apipie::Command) } }
   let(:options) { builder.build(builder_options) }
 
   context "with one simple param" do
@@ -51,7 +51,7 @@ describe HammerCLI::Apipie::OptionBuilder do
   context "required options" do
 
     let(:action) {resource.action(:create)}
-    let(:required_options) { builder.build.reject{|opt| !opt.required?} }
+    let(:required_options) { builder.build(builder_options).reject{|opt| !opt.required?} }
 
     it "should set required flag for the required options" do
       required_options.map(&:attribute_name).sort.must_equal [HammerCLI.option_accessor_name("array_param")]
@@ -146,7 +146,12 @@ describe HammerCLI::Apipie::OptionBuilder do
 
   context "aliasing resources" do
     let(:action) {resource.action(:action_with_ids)}
-    let(:builder_options) { {:resource_mapping => {:organization => 'company', 'compute_resource' => :compute_provider}} }
+    let(:builder_options) do
+      {
+        resource_mapping: { organization: 'company', 'compute_resource' => :compute_provider },
+        command: Class.new(HammerCLI::Apipie::Command)
+      }
+    end
 
     it "renames options" do
       # builder_options[:resource_mapping] = {:organization => 'company', 'compute_resource' => :compute_provider}

data/test/unit/command_extensions_test.rb

@@ -118,7 +118,7 @@ describe HammerCLI::CommandExtensions do
     it 'should extend option family only' do
       cmd.extend_with(CmdExtensions.new(only: :option_family))
       cmd.output_definition.empty?.must_equal true
-      cmd.recognised_options.map(&:switches).flatten.must_equal ['--test-one', '--test-two', '-h', '--help']
+      cmd.recognised_options.map(&:switches).flatten.must_equal ['-h', '--help', '--test-one', '--test-two']
     end
   end
 
@@ -203,5 +203,13 @@ describe HammerCLI::CommandExtensions do
     end
   end
 
-
+  context 'associate family' do
+    it 'should associate option family' do
+      cmd.extend_with(CmdExtensions.new(only: :option_family))
+      cmd.option_family associate: 'test' do
+        child '--test-three', '', ''
+      end
+      cmd.recognised_options.map(&:switches).flatten.must_equal ['-h', '--help', '--test-one', '--test-two', '--test-three']
+    end
+  end
 end

data/test/unit/help/builder_test.rb

@@ -21,6 +21,24 @@ describe HammerCLI::Help::Builder do
         ' --zzz-option OPT_Z            Some description'
       ].join("\n")
     end
+
+    it 'prints long option descriptions aligned' do
+      opt_a_desc = 'AAAAAAA ' * 20
+      opt_b_desc = 'BBBBBBB ' * 20
+      options = [
+        Clamp::Option::Definition.new(['--aaa-option'], 'OPT_A', opt_a_desc),
+        Clamp::Option::Definition.new(['--bbb-option'], 'OPT_B', opt_b_desc)
+      ]
+      help.add_list('Options', options)
+
+      help.string.strip.must_equal [
+        'Options:',
+        ' --aaa-option OPT_A            %s' % ('AAAAAAA ' * 10).strip,
+        '                               %s' % ('AAAAAAA ' * 10).strip,
+        ' --bbb-option OPT_B            %s' % ('BBBBBBB ' * 10).strip,
+        '                               %s' % ('BBBBBBB ' * 10).strip
+      ].join("\n")
+    end
   end
 
   describe 'adding an option with lower case description' do
@@ -86,8 +104,8 @@ describe HammerCLI::Help::Builder do
 
       help.string.strip.must_equal [
         'Options:',
-        ' --option[-yyy|-bbb]           Some description',
-        ' --option[-aaa|-zzz]           Some description',
+        ' --option[-yyy|-bbb] VALUE     Some description',
+        ' --option[-aaa|-zzz] VALUE     Some description'
       ].join("\n")
     end
   end

data/test/unit/options/option_definition_test.rb

@@ -25,6 +25,10 @@ describe HammerCLI::Options::OptionDefinition do
     option "--another-deprecated", "OLD_OPTION", "Test old option",
       :context_target => :old_option,
       :deprecated => "It is going to be removed"
+
+    def find_option(switch)
+      super(switch)
+    end
   end
 
   def opt_with_deprecation(deprecation)
@@ -73,6 +77,14 @@ describe HammerCLI::Options::OptionDefinition do
       context[:test_option].must_equal "VALUE"
     end
 
+    it "doesn't print deprecation warning if the option is not used" do
+      context = {}
+      cmd = TestDeprecatedOptionCmd.new('', context)
+      cmd.find_option('--deprecated')
+      _out, err = capture_io { cmd.run([]) }
+      err.must_equal ''
+    end
+
     it 'shows depracated message in help' do
       opt = opt_with_deprecation("Use --better-switch instead")
       opt.description.must_equal "Test option (Deprecated: Use --better-switch instead)"
@@ -98,4 +110,3 @@ describe HammerCLI::Options::OptionDefinition do
     end
   end
 end
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hammer_cli
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.1.0
 platform: ruby
 authors:
 - Martin Bačovský
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-01 00:00:00.000000000 Z
+date: 2021-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clamp
@@ -163,7 +163,7 @@ extra_rdoc_files:
 - doc/option_normalizers.md
 - doc/writing_a_plugin.md
 - doc/installation_source.md
-- doc/creating_commands.md
+- doc/release_notes.md
 - doc/commands_extension.md
 - doc/commands_modification.md
 - doc/developer_docs.md
@@ -172,7 +172,7 @@ extra_rdoc_files:
 - doc/installation_rpm.md
 - doc/output.md
 - doc/review_checklist.md
-- doc/release_notes.md
+- doc/creating_commands.md
 - config/cli.modules.d/module_config_template.yml
 - config/cli_config.template.yml
 - config/hammer.completion
@@ -443,8 +443,8 @@ test_files:
 - test/unit/options/sources/command_line_test.rb
 - test/unit/options/sources/saved_defaults_test.rb
 - test/unit/options/validators/dsl_test.rb
-- test/unit/options/option_family_test.rb
 - test/unit/options/normalizers_test.rb
+- test/unit/options/option_family_test.rb
 - test/unit/options/option_definition_test.rb
 - test/unit/output/adapter/abstract_test.rb
 - test/unit/output/adapter/base_test.rb