hammer_cli 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1beb690641cf038528a35bee7964c73e60acbe8a70e94bb9d1a72af372218ea1
-  data.tar.gz: 516fd63e88f8df2996aefd0d3276a9ff56e1bf5f17c1a7a8b656210512f2896c
+  metadata.gz: f5401e68d37a678eb6193e892c4d148c165260a0e90f3a11c9dc2e2d49d464ae
+  data.tar.gz: 21d2f0466c0c433033e2bdbaf8aad4d8f3ea6a51261f4f695a135cb1e9f5b5c0
 SHA512:
-  metadata.gz: 8b35646b4dc9c494687b7bbd38c578ce5cf70e90080025f622b89a28f1c1d29abeafc11dbe1e16cb0786fe8ae3ac4c8673b905e8bf03cf87de86383817c653a6
-  data.tar.gz: 3a01e546cf71e7f015ec27d8c127328e380c3736106bc01b95d1b81593f2c7fa0a027e90a95bbf179407a953da871911e8dd0349c0ed980ed5cad613bd98363b
+  metadata.gz: c50b60e009c0f48736b540a4d7dcf39db860a8b128542aa15495ac5ae6bdc2c0c3eccf92e098b7c81ac55e90dbe295c5310fa1fd5e39d084e790c379171eeba2
+  data.tar.gz: 2482f77220d681fba21493cf80473132379127ef580c45dfe8293f2e5fb5ff420ba75c4276e4dfbad410f30d3ab0c880135a77b26d5a67d9ffbfb0e5914bd03d

data/doc/commands_extension.md

@@ -10,6 +10,11 @@ Each command can be easily extended with one ore more `HammerCLI::CommandExtensi
     inheritable true
     # Simply add a new option to a command is being extended
     option(option_params)
+    # Add option family to a command
+    option_family(common_options = {}) do
+      parent option_params
+      child option_params
+    end
     # Extend hash with data returned from server before it is printed
     before_print do |data|
       # data modifications
@@ -65,6 +70,13 @@ class MyCommandExtensions < HammerCLI::CommandExtensions
 
   option ['--new-option'], 'TYPE', _('Option description')
 
+  option_family(
+    description: _('Common description')
+  ) do
+    parent ['--new-option'], 'TYPE', _('Option description')
+    child ['--new-option-ver2'], 'TYPE', _('Option description')
+  end
+
   before_print do |data|
     data['results'].each do |result|
       result['status'] = process_errors(result['errors'])

data/doc/creating_commands.md

@@ -173,6 +173,54 @@ Here is the list of predefined options:
   * `:fields` Expects a list with fields to show in output, see [example](creating_commands.md#printing-hash-records).
 
 
+### Option family
+Option family is the way to unify options which have the same meaning or purpose,
+but contain some differences in their definitions (e.g. the name/switch of an option).
+Mainly serves as a container for options, which purpose is to show less repetitive
+output in commands' help. Option builders use it by default.
+
+To define an option family, use the following DSL:
+```ruby
+  # options is a Hash with options for family/each defined option within it
+  option_family(options = {}) do
+    # parent is the main option. Must be single, option family can have only one parent.
+    parent switches, type, description, options
+    # child  is an additional option. Could be none or more than one. Aren't shown in the help output.
+    child  switches, type, description, options
+  end
+```
+
+##### Example
+
+```ruby
+  option_family(
+    aliased_resource: 'environment',
+    description: _('Puppet environment'),
+    deprecation: _("Use %s instead") % '--puppet-environment[-id]'
+    deprecated: { '--environment' => _("Use %s instead") % '--puppet-environment[-id]',
+                  '--environment-id' => _("Use %s instead") % '--puppet-environment[-id]'}
+  ) do
+    parent '--environment-id', 'ENVIRONMENT_ID', _(''),
+           format: HammerCLI::Options::Normalizers::Number.new,
+           attribute_name: :option_environment_id
+    child '--environment', 'ENVIRONMENT_NAME', _('Environment name'),
+          attribute_name: :option_environment_name
+  end
+
+  # $ hammer command --help:
+  # ...
+  #  Options:
+  #    --environment[-id]               Puppet environment (Deprecated: Use --puppet-environment[-id] instead)
+  # ...
+
+  # $ hammer full-help:
+  # ...
+  #  Options:
+  #    --environment   ENVIRONMENT_NAME    Environment name (--environment is deprecated: Use --puppet-environment[-id] instead)
+  #    --environment-id   ENVIRONMENT_ID    (--environment-id is deprecated: Use --puppet-environment[-id] instead)
+  # ...
+```
+
 ### Option builders
 Hammer commands offer option builders that can be used for automatic option generation.
 See [documentation page](option_builders.md#option-builders) dedicated to this topic for more details.
@@ -406,6 +454,31 @@ Options:
     -h, --help                    print help
 ```
 
+#### Aliasing subcommands
+
+Commands can have two or more names, e.g. aliases. To support such functionality
+simple name addition could be used via `command_name` or `command_names` method:
+```ruby
+module HammerCLIHello
+
+  class SayCommand < HammerCLI::AbstractCommand
+
+    class GreetingsCommand < HammerCLI::AbstractCommand
+      command_name 'hello'
+      command_name 'hi'
+      # or use can use other method:
+      command_names 'hello', 'hi'
+
+      desc 'Say Hello World!'
+      # ...
+    end
+
+    autoload_subcommands
+  end
+
+  HammerCLI::MainCommand.subcommand 'say', "Say something", HammerCLIHello::SayCommand
+end
+```
 
 ### Conflicting subcommands
 It can happen that two different plugins define subcommands with the same name by accident.

data/doc/release_notes.md

@@ -1,5 +1,12 @@
 Release notes
 =============
+### 2.1.0 (2020-05-14)
+* Hammer full-help returns correct output, [#29697](http://projects.theforeman.org/issues/29697)
+* Add fuzzy subcommand matching, [#29413](http://projects.theforeman.org/issues/29413)
+* Help contains squeezed options, [#28440](http://projects.theforeman.org/issues/28440)
+* Keep referenced resource in option options, [#29015](http://projects.theforeman.org/issues/29015)
+* Bump to 2.1.0-develop
+
 ### 2.0.0 (2020-02-12)
 * Bump version to 2.0.0
 * Bump version to 2.0 ([PR #324](https://github.com/theforeman/hammer-cli/pull/324))

data/lib/hammer_cli/abstract.rb

@@ -13,6 +13,7 @@ require 'hammer_cli/options/predefined'
 require 'hammer_cli/help/builder'
 require 'hammer_cli/help/text_builder'
 require 'hammer_cli/command_extensions'
+require 'hammer_cli/options/option_family'
 require 'logging'
 
 module HammerCLI
@@ -191,6 +192,16 @@ module HammerCLI
         # skip switches that are already defined
         next if option.nil? or option.switches.any? {|s| find_option(s) }
 
+        if option.respond_to?(:referenced_resource)
+          # Collect options that don't have family, but related to this parent.
+          children = find_options(
+            referenced_resource: option.referenced_resource.to_s,
+            aliased_resource: option.aliased_resource.to_s
+          ).select { |o| o.family.nil? || o.family.head.nil? }
+          children.each do |child|
+            option.family.adopt(child) if option.family
+          end
+        end
         declared_options << option
         block ||= option.default_conversion_block
         define_accessors_for(option, &block)
@@ -207,6 +218,7 @@ module HammerCLI
         extension.delegatee(self)
         extension.extend_predefined_options(self)
         extension.extend_options(self)
+        extension.extend_option_family(self)
         extension.extend_output(self)
         extension.extend_help(self)
         logger('Extensions').info "Applied #{extension.details} on #{self}."
@@ -222,6 +234,12 @@ module HammerCLI
 
     protected
 
+    def self.option_family(options = {}, &block)
+      options[:creator] ||= self
+      family = HammerCLI::Options::OptionFamily.new(options)
+      family.instance_eval(&block)
+    end
+
     def self.find_options(switch_filter, other_filters={})
       filters = other_filters
       if switch_filter.is_a? Hash
@@ -285,8 +303,17 @@ module HammerCLI
     end
 
     def self.command_name(name=nil)
-      @name = name if name
-      @name || (superclass.respond_to?(:command_name) ? superclass.command_name : nil)
+      if @names && name
+        @names << name if !@names.include?(name)
+      else
+        @names = [name] if name
+      end
+      @names || (superclass.respond_to?(:command_names) ? superclass.command_names : nil)
+    end
+
+    def self.command_names(*names)
+      @names = names unless names.empty?
+      @names || (superclass.respond_to?(:command_names) ? superclass.command_names : nil)
     end
 
     def self.warning(message = nil)

data/lib/hammer_cli/apipie/option_builder.rb

@@ -41,12 +41,11 @@ module HammerCLI::Apipie
     end
 
     def create_option(param, resource_name_map)
-      option(
-        option_switch(param, resource_name_map),
-        option_type(param, resource_name_map),
-        option_desc(param),
-        option_opts(param)
-      )
+      family = HammerCLI::Options::OptionFamily.new
+      family.parent(option_switch(param, resource_name_map),
+                    option_type(param, resource_name_map),
+                    option_desc(param),
+                    option_opts(param, resource_name_map))
     end
 
     def option_switch(param, resource_name_map)
@@ -61,7 +60,7 @@ module HammerCLI::Apipie
       param.description || " "
     end
 
-    def option_opts(param)
+    def option_opts(param, resource_name_map)
       opts = {}
       opts[:required] = true if (param.required? and require_options?)
       if param.expected_type.to_s == 'array'
@@ -80,19 +79,22 @@ module HammerCLI::Apipie
       end
       opts[:attribute_name] = HammerCLI.option_accessor_name(param.name)
       opts[:referenced_resource] = resource_name(param)
+      opts[:aliased_resource] = aliased_name(resource_name(param), resource_name_map)
 
       return opts
     end
 
+    def aliased_name(name, resource_name_map)
+      return if name.nil?
+
+      resource_name_map[name.to_s] || resource_name_map[name.to_sym] || name
+    end
+
     def aliased(param, resource_name_map)
       resource_name = resource_name(param)
+      return param.name if resource_name.nil?
 
-      if resource_name.nil?
-        return param.name
-      else
-        aliased_name = resource_name_map[resource_name.to_s] || resource_name_map[resource_name.to_sym] || resource_name
-        return param.name.gsub(resource_name, aliased_name.to_s)
-      end
+      param.name.gsub(resource_name, aliased_name(resource_name, resource_name_map).to_s)
     end
 
     def resource_name(param)

data/lib/hammer_cli/apipie/option_definition.rb

@@ -1,21 +1,23 @@
 require File.join(File.dirname(__FILE__), 'options')
 
 module HammerCLI::Apipie
-
   class OptionDefinition < HammerCLI::Options::OptionDefinition
-
-    attr_accessor :referenced_resource
+    attr_accessor :referenced_resource, :aliased_resource, :family
 
     def initialize(switches, type, description, options = {})
-      if options.has_key? :referenced_resource
-        self.referenced_resource = options.delete(:referenced_resource).to_s if options[:referenced_resource]
-      end
+      @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
 
-  end
+    def child?
+      return unless @family
 
+      @family.children.include?(self)
+    end
+  end
 end

data/lib/hammer_cli/command_extensions.rb

@@ -15,7 +15,7 @@ module HammerCLI
     ALLOWED_EXTENSIONS = %i[
       option command_options before_print data output help request
       request_headers headers request_options options request_params params
-      option_sources predefined_options use_option
+      option_sources predefined_options use_option option_family
     ].freeze
 
     def initialize(options = {})
@@ -86,6 +86,11 @@ module HammerCLI
       @option_sources_block = block
     end
 
+    def self.option_family(options = {}, &block)
+      @option_family_opts = options
+      @option_family_block = block
+    end
+
     # Object
 
     def extend_options(command_class)
@@ -151,6 +156,13 @@ module HammerCLI
       self.class.extend_option_sources(sources, command)
     end
 
+    def extend_option_family(command_class)
+      allowed = @only & %i[option_family]
+      return if allowed.empty? || (allowed & @except).any?
+
+      self.class.extend_option_family(command_class)
+    end
+
     def delegatee(command_class)
       self.class.delegatee = command_class
     end
@@ -234,5 +246,13 @@ module HammerCLI
       @option_sources_block.call(sources, command)
       logger.debug("Called block for #{@delegatee} option sources:\n\t#{@option_sources_block}")
     end
+
+    def self.extend_option_family(command_class)
+      return if @option_family_block.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}")
+    end
   end
 end

data/lib/hammer_cli/exception_handler.rb

@@ -69,7 +69,7 @@ module HammerCLI
 
     def handle_usage_exception(e)
       print_error (_("Error: %{message}") + "\n\n" +
-                   _("See: '%{path} --help'.")) % {:message => e.message, :path => e.command.invocation_path}
+                   _("See: '%{path} --help'.")) % { message: e.message, path: HammerCLI.expand_invocation_path(e.command.invocation_path) }
       log_full_error e
       HammerCLI::EX_USAGE
     end

data/lib/hammer_cli/full_help.rb

@@ -6,8 +6,11 @@ module HammerCLI
 
     def execute
       @adapter = option_md? ? MDAdapter.new : TxtAdapter.new
+      HammerCLI.context[:full_help] = true
+      @invocation_paths = {}
       print_heading
       print_help
+      HammerCLI.context[:full_help] = false
       HammerCLI::EX_OK
     end
 
@@ -19,9 +22,13 @@ module HammerCLI
     end
 
     def print_help(name='hammer', command=HammerCLI::MainCommand, desc='')
-      @adapter.print_command(name, desc, command.new(name).help)
+      @invocation_paths[name] ||= []
+      @adapter.print_command(name, desc, command.new(name, path: @invocation_paths[name]).help)
 
       command.recognised_subcommands.each do |sub_cmd|
+        path = "#{name} #{sub_cmd.names.first}"
+        @invocation_paths[path] ||= []
+        @invocation_paths[path] += @invocation_paths[name]
         print_help(@adapter.command_name(name, sub_cmd.names.first), sub_cmd.subcommand_class, sub_cmd.description)
       end
     end

data/lib/hammer_cli/help/builder.rb

@@ -14,7 +14,7 @@ module HammerCLI
       def add_usage(invocation_path, usage_descriptions)
         heading(Clamp.message(:usage_heading))
         usage_descriptions.each do |usage|
-          puts "    #{invocation_path} #{usage}".rstrip
+          puts "    #{HammerCLI.expand_invocation_path(invocation_path)} #{usage}".rstrip
         end
       end
 
@@ -29,12 +29,19 @@ module HammerCLI
 
         label_width = DEFAULT_LABEL_INDENT
         items.each do |item|
-          label, description = item.help
+          label = item.help.first
           label_width = label.size if label.size > label_width
         end
 
         items.each do |item|
-          label, description = item.help
+          if item.respond_to?(:child?) && item.child?
+            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|
             puts " %-#{label_width}s %s" % [label, line]
             label = ''
@@ -54,6 +61,25 @@ module HammerCLI
         label = HighLine.color(label, :bold) if @richtext
         puts label
       end
+
+      private
+
+      def expand_invocation_path(path)
+        bits = path.split(' ')
+        parent_command = HammerCLI::MainCommand
+        new_path = (bits[1..-1] || []).each_with_object([]) do |bit, names|
+          subcommand = parent_command.find_subcommand(bit)
+          next if subcommand.nil?
+
+          names << if subcommand.names.size > 1
+                     "<#{subcommand.names.join('|')}>"
+                   else
+                     subcommand.names.first
+                   end
+          parent_command = subcommand.subcommand_class
+        end
+        new_path.unshift(bits.first).join(' ')
+      end
     end
   end
 end

data/lib/hammer_cli/options/option_definition.rb

@@ -22,14 +22,12 @@ module HammerCLI
 
     class OptionDefinition < Clamp::Option::Definition
 
-      attr_accessor :value_formatter
-      attr_accessor :context_target
-      attr_accessor :deprecated_switches
+      attr_accessor :value_formatter, :context_target, :deprecated_switches
 
       def initialize(switches, type, description, options = {})
-        self.value_formatter = options[:format] || HammerCLI::Options::Normalizers::Default.new
-        self.context_target = options[:context_target]
-        self.deprecated_switches = options[:deprecated]
+        @value_formatter = options[:format] || HammerCLI::Options::Normalizers::Default.new
+        @context_target = options[:context_target]
+        @deprecated_switches = options[:deprecated]
         super
       end
 

data/lib/hammer_cli/options/option_family.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module HammerCLI
+  module Options
+    class OptionFamily
+      attr_reader :children
+
+      IDS_REGEX = /\s?([Ii][Dd][s]?)\W|([Ii][Dd][s]?\Z)/
+
+      def initialize(options = {})
+        @all = []
+        @children = []
+        @options = options
+        @creator = options[:creator] || Class.new(HammerCLI::Apipie::Command)
+        @prefix = options[:prefix]
+        @description = options[:description]
+        @root = options[:root] || options[:aliased_resource] || options[:referenced_resource]
+      end
+
+      def description
+        types = all.map(&:type).map { |s| s.split('_').last.to_s }
+                   .map(&:capitalize).join('/')
+        @description ||= @parent.help[1].gsub(IDS_REGEX) { |w| w.gsub(/\w+/, types) }
+        if @options[:deprecation].class <= String
+          format_deprecation_msg(@description, _('Deprecated: %{deprecated_msg}') % { deprecated_msg: @options[:deprecation] })
+        elsif @options[:deprecation].class <= Hash
+          full_msg = @options[:deprecation].map do |flag, msg|
+            _('%{flag} is deprecated: %{deprecated_msg}') % { flag: flag, deprecated_msg: msg }
+          end.join(', ')
+          format_deprecation_msg(@description, full_msg)
+        else
+          @description
+        end
+      end
+
+      def switch
+        return if @parent.nil? && @children.empty?
+        return @parent.help_lhs.strip if @children.empty?
+
+        switch_start = main_switch.each_char
+                                  .zip(*all.map(&:switches).flatten.map(&:each_char))
+                                  .select { |a, b| a == b }.transpose.first.join
+        suffixes = all.map do |m|
+          m.switches.map { |s| s.gsub(switch_start, '') }
+        end.flatten.reject(&:empty?).sort { |x, y| x.size <=> y.size }
+        "#{switch_start}[#{suffixes.join('|')}]"
+      end
+
+      def head
+        @parent
+      end
+
+      def all
+        @children + [@parent].compact
+      end
+
+      def parent(switches, type, description, opts = {}, &block)
+        raise StandardError, 'Option family can have only one parent' if @parent
+
+        @parent = new_member(switches, type, description, opts, &block)
+      end
+
+      def child(switches, type, description, opts = {}, &block)
+        child = new_member(switches, type, description, opts, &block)
+        @children << child
+        child
+      end
+
+      def adopt(child)
+        child.family = self
+        @children << child
+      end
+
+      private
+
+      def format_deprecation_msg(option_desc, deprecation_msg)
+        "#{option_desc} (#{deprecation_msg})"
+      end
+
+      def new_member(switches, type, description, opts = {}, &block)
+        opts = opts.merge(@options)
+        opts[:family] = self
+        if opts[:deprecated]
+          handles = [switches].flatten
+          opts[:deprecated] = opts[:deprecated].select do |switch, _msg|
+            handles.include?(switch)
+          end
+        end
+        @creator.instance_eval do
+          option(switches, type, description, opts, &block)
+        end
+      end
+
+      def main_switch
+        root = @root || @parent.aliased_resource || @parent.referenced_resource || common_root
+        "--#{@prefix}#{root}".tr('_', '-')
+      end
+
+      def common_root
+        switches = all.map(&:switches).flatten
+        shortest = switches.min_by(&:length)
+        max_len = shortest.length
+        max_len.downto(0) do |curr_len|
+          0.upto(max_len - curr_len) do |start|
+            root = shortest[start, curr_len]
+            if switches.all? { |switch| switch.include?(root) }
+              return root[2..-1].chomp('-')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hammer_cli/subcommand.rb

@@ -23,6 +23,11 @@ module HammerCLI
         @subcommand_class
       end
 
+      def help
+        names = HammerCLI.context[:full_help] ? @names.join(", ") : @names.first
+        [names, description]
+      end
+
       attr_reader :warning
     end
 
@@ -90,8 +95,27 @@ module HammerCLI
         logger.info "subcommand #{name} (#{subcommand_class_name}) was created."
       end
 
+      def find_subcommand(name, fuzzy: true)
+        subcommand = super(name)
+        if subcommand.nil? && fuzzy
+          find_subcommand_starting_with(name)
+        else
+          subcommand
+        end
+      end
+
+      def find_subcommand_starting_with(name)
+        subcommands = recognised_subcommands.select { |sc| sc.names.any? { |n| n.start_with?(name) } }
+        if subcommands.size > 1
+          raise HammerCLI::CommandConflict, _('Found more than one command.') + "\n\n" +
+                                            _('Did you mean one of these?') + "\n\t" +
+                                            subcommands.collect(&:names).flatten.select { |n| n.start_with?(name) }.join("\n\t")
+        end
+        subcommands.first
+      end
+
       def define_subcommand(name, subcommand_class, definition, &block)
-        existing = find_subcommand(name)
+        existing = find_subcommand(name, fuzzy: false)
         if existing
           raise HammerCLI::CommandConflict, _("Can't replace subcommand %<name>s (%<existing_class>s) with %<name>s (%<new_class>s).") % {
             :name => name,

data/lib/hammer_cli/testing/command_assertions.rb

@@ -71,13 +71,13 @@ module HammerCLI
         if heading.nil?
           ["Error: #{message}",
            "",
-           "See: '#{command} --help'.",
+           "See: '#{HammerCLI.expand_invocation_path(command)} --help'.",
            ""].join("\n")
         else
           ["#{heading}:",
            "  Error: #{message}",
            "  ",
-           "  See: '#{command} --help'.",
+           "  See: '#{HammerCLI.expand_invocation_path(command)} --help'.",
            ""].join("\n")
         end
       end

data/lib/hammer_cli/utils.rb

@@ -116,4 +116,21 @@ module HammerCLI
 
     array.insert(idx, *new_items)
   end
+
+  def self.expand_invocation_path(path)
+    bits = path.split(' ')
+    parent_command = HammerCLI::MainCommand
+    new_path = (bits[1..-1] || []).each_with_object([]) do |bit, names|
+      subcommand = parent_command.find_subcommand(bit)
+      next if subcommand.nil?
+
+      names << if subcommand.names.size > 1
+                 "<#{subcommand.names.join('|')}>"
+               else
+                 subcommand.names.first
+               end
+      parent_command = subcommand.subcommand_class
+    end
+    new_path.unshift(bits.first).join(' ')
+  end
 end

data/lib/hammer_cli/version.rb

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

data/test/unit/abstract_test.rb

@@ -262,6 +262,27 @@ describe HammerCLI::AbstractCommand do
       end
 
     end
+
+    describe 'find_subcommand' do
+      it 'should find by full name' do
+        main_cmd.find_subcommand('some_command').wont_be_nil
+      end
+
+      it 'should find by partial name' do
+        main_cmd.find_subcommand('some_').wont_be_nil
+      end
+
+      it 'should not find by wrong name' do
+        main_cmd.find_subcommand('not_existing').must_be_nil
+      end
+
+      it 'should raise if more than one were found' do
+        main_cmd.subcommand('pong', 'description', Subcommand2)
+        proc do
+          main_cmd.find_subcommand('p')
+        end.must_raise HammerCLI::CommandConflict
+      end
+    end
   end
 
   describe "options" do
@@ -413,7 +434,7 @@ describe HammerCLI::AbstractCommand do
     class CmdName2 < CmdName1
     end
 
-    CmdName2.command_name.must_equal 'cmd'
+    CmdName2.command_name.must_equal ['cmd']
   end
 
   it "should inherit output definition" do
@@ -525,7 +546,7 @@ describe HammerCLI::AbstractCommand do
       opt = cmd.find_option('--flag')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal true
       cmd.output_definition.empty?.must_equal false
-      cmd.new({}).help.must_match(/.*text.*/)
+      cmd.new('', {}).help.must_match(/.*text.*/)
     end
 
     it 'should store more than one extension' do

data/test/unit/apipie/option_builder_test.rb

@@ -37,6 +37,14 @@ describe HammerCLI::Apipie::OptionBuilder do
     it "should set description with html tags stripped" do
       options[0].description.must_equal 'filter results'
     end
+
+    it "should build option with default family" do
+      options[0].family.wont_be_nil
+    end
+
+    it "should build parent option within default family" do
+      options[0].child?.must_equal false
+    end
   end
 
 

data/test/unit/command_extensions_test.rb

@@ -23,6 +23,12 @@ describe HammerCLI::CommandExtensions do
 
   class CmdExtensions < HammerCLI::CommandExtensions
     option '--ext', 'EXT', 'ext'
+    option_family(
+      description: 'Test',
+    ) do
+      parent '--test-one', '', ''
+      child '--test-two', '', ''
+    end
     before_print do |data|
       data['key'] = 'value'
     end
@@ -64,49 +70,55 @@ describe HammerCLI::CommandExtensions do
 
     it 'should extend help only' do
       cmd.extend_with(CmdExtensions.new(only: :help))
-      cmd.new({}).help.must_match(/.*Section.*/)
-      cmd.new({}).help.must_match(/.*text.*/)
+      cmd.new('', {}).help.must_match(/.*Section.*/)
+      cmd.new('', {}).help.must_match(/.*text.*/)
     end
 
     it 'should extend params only' do
       cmd.extend_with(CmdExtensions.new(only: :request_params))
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal({})
-      cmd.new({}).extended_request[2].must_equal({})
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal({})
+      cmd.new('', {}).extended_request[2].must_equal({})
     end
 
     it 'should extend headers only' do
       cmd.extend_with(CmdExtensions.new(only: :request_headers))
-      cmd.new({}).extended_request[0].must_equal({})
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal({})
+      cmd.new('', {}).extended_request[0].must_equal({})
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal({})
     end
 
     it 'should extend options only' do
       cmd.extend_with(CmdExtensions.new(only: :request_options))
-      cmd.new({}).extended_request[0].must_equal({})
-      cmd.new({}).extended_request[1].must_equal({})
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal({})
+      cmd.new('', {}).extended_request[1].must_equal({})
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend params and options and headers' do
       cmd.extend_with(CmdExtensions.new(only: :request))
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend data only' do
       cmd.extend_with(CmdExtensions.new(only: :data))
-      cmd.new({}).help.wont_match(/.*Section.*/)
-      cmd.new({}).help.wont_match(/.*text.*/)
+      cmd.new('', {}).help.wont_match(/.*Section.*/)
+      cmd.new('', {}).help.wont_match(/.*text.*/)
       cmd.output_definition.empty?.must_equal true
       opt = cmd.find_option('--ext')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal false
-      cmd.new({}).extended_request[0].must_equal({})
-      cmd.new({}).extended_request[1].must_equal({})
-      cmd.new({}).extended_request[2].must_equal({})
-      cmd.new({}).extended_data({}).must_equal('key' => 'value')
+      cmd.new('', {}).extended_request[0].must_equal({})
+      cmd.new('', {}).extended_request[1].must_equal({})
+      cmd.new('', {}).extended_request[2].must_equal({})
+      cmd.new('', {}).extended_data({}).must_equal('key' => 'value')
+    end
+
+    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']
     end
   end
 
@@ -116,9 +128,9 @@ describe HammerCLI::CommandExtensions do
       opt = cmd.find_option('--ext')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal false
       cmd.output_definition.empty?.must_equal false
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend all except output' do
@@ -126,62 +138,68 @@ describe HammerCLI::CommandExtensions do
       cmd.output_definition.empty?.must_equal true
       opt = cmd.find_option('--ext')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal true
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend all except help' do
       cmd.extend_with(CmdExtensions.new(except: :help))
-      cmd.new({}).help.wont_match(/.*Section.*/)
-      cmd.new({}).help.wont_match(/.*text.*/)
+      cmd.new('', {}).help.wont_match(/.*Section.*/)
+      cmd.new('', {}).help.wont_match(/.*text.*/)
       cmd.output_definition.empty?.must_equal false
       opt = cmd.find_option('--ext')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal true
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend all except params' do
       cmd.extend_with(CmdExtensions.new(except: :request_params))
-      cmd.new({}).extended_request[0].must_equal({})
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal({})
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend all except headers' do
       cmd.extend_with(CmdExtensions.new(except: :request_headers))
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal({})
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal({})
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
     end
 
     it 'should extend all except options' do
       cmd.extend_with(CmdExtensions.new(except: :request_options))
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal({})
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal({})
     end
 
     it 'should extend all except params and options and headers' do
       cmd.extend_with(CmdExtensions.new(except: :request))
-      cmd.new({}).extended_request[0].must_equal({})
-      cmd.new({}).extended_request[1].must_equal({})
-      cmd.new({}).extended_request[2].must_equal({})
+      cmd.new('', {}).extended_request[0].must_equal({})
+      cmd.new('', {}).extended_request[1].must_equal({})
+      cmd.new('', {}).extended_request[2].must_equal({})
     end
 
     it 'should extend all except data' do
       cmd.extend_with(CmdExtensions.new(except: :data))
-      cmd.new({}).help.must_match(/.*Section.*/)
-      cmd.new({}).help.must_match(/.*text.*/)
+      cmd.new('', {}).help.must_match(/.*Section.*/)
+      cmd.new('', {}).help.must_match(/.*text.*/)
       cmd.output_definition.empty?.must_equal false
       opt = cmd.find_option('--ext')
       opt.is_a?(HammerCLI::Options::OptionDefinition).must_equal true
-      cmd.new({}).extended_request[0].must_equal(thin: true)
-      cmd.new({}).extended_request[1].must_equal(ssl: true)
-      cmd.new({}).extended_request[2].must_equal(with_authentication: true)
-      cmd.new({}).extended_data({}).must_equal({})
+      cmd.new('', {}).extended_request[0].must_equal(thin: true)
+      cmd.new('', {}).extended_request[1].must_equal(ssl: true)
+      cmd.new('', {}).extended_request[2].must_equal(with_authentication: true)
+      cmd.new('', {}).extended_data({}).must_equal({})
+    end
+
+    it 'should extend all except option family' do
+      cmd.extend_with(CmdExtensions.new(except: :option_family))
+      cmd.output_definition.empty?.must_equal false
+      cmd.recognised_options.map(&:switches).flatten.must_equal ['--ext', '-h', '--help']
     end
   end
 

data/test/unit/help/builder_test.rb

@@ -69,4 +69,26 @@ describe HammerCLI::Help::Builder do
       help.string.strip.must_equal expected_output
     end
   end
+
+  describe 'option family' do
+    let(:family) { Class.new(HammerCLI::Options::OptionFamily) }
+
+    it 'prints option families' do
+      fm1 = family.new
+      fm1.parent(['--option-zzz'], 'OPT', 'Some description')
+      fm1.child(['--option-aaa'], 'OPT', 'Some description')
+      fm2 = family.new
+      fm2.parent(['--option-bbb'], 'OPT', 'Some description')
+      fm2.child(['--option-yyy'], 'OPT', 'Some description')
+
+      options = fm1.all + fm2.all
+      help.add_list('Options', options)
+
+      help.string.strip.must_equal [
+        'Options:',
+        ' --option[-yyy|-bbb]           Some description',
+        ' --option[-aaa|-zzz]           Some description',
+      ].join("\n")
+    end
+  end
 end

data/test/unit/options/option_family_test.rb

@@ -0,0 +1,48 @@
+require_relative '../test_helper'
+
+describe HammerCLI::Options::OptionFamily do
+  let(:family) do
+    HammerCLI::Options::OptionFamily.new(
+      deprecated: { '--test-one' => 'Use --test-two instead' }
+    )
+  end
+  let(:first_option) { HammerCLI::Apipie::OptionDefinition.new("--test-one", '', '') }
+  let(:second_option) { HammerCLI::Apipie::OptionDefinition.new("--test-two", '', '') }
+  let(:third_option) { HammerCLI::Apipie::OptionDefinition.new("--test-three", '', '') }
+  let(:full_family) do
+    family.parent('--test-one', '', 'Test').family.child('--test-two', '', '').family
+  end
+
+  describe 'switch' do
+    it 'returns nil if family is empty' do
+      family.switch.must_be_nil
+    end
+
+    it 'returns parent switch if family has no children' do
+      family.parent('--test-one', '', '')
+      family.switch.must_equal '--test-one'
+    end
+
+    it 'returns switch based on members' do
+      full_family.switch.must_equal '--test[-two|-one]'
+    end
+  end
+
+  describe 'description' do
+    it 'returns parent description if nothing passed to initializer' do
+      full_family.description.must_equal full_family.head.help[1]
+    end
+
+    it 'returns description with deprecation message' do
+      full_family.description.must_equal 'Test (--test-one is deprecated: Use --test-two instead)'
+    end
+  end
+
+  describe 'adopt' do
+    it 'appends an option to children' do
+      full_family.adopt(third_option)
+      full_family.children.size.must_equal 2
+      third_option.family.must_equal full_family
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hammer_cli
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Martin Bačovský
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-12 00:00:00.000000000 Z
+date: 2020-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clamp
@@ -145,7 +145,7 @@ dependencies:
         version: 0.2.0
 description: 'Hammer cli provides universal extendable CLI interface for ruby apps
 
-'
+  '
 email: mbacovsk@redhat.com
 executables:
 - hammer
@@ -252,6 +252,7 @@ files:
 - lib/hammer_cli/options/normalizers.rb
 - lib/hammer_cli/options/option_collector.rb
 - lib/hammer_cli/options/option_definition.rb
+- lib/hammer_cli/options/option_family.rb
 - lib/hammer_cli/options/option_processor.rb
 - lib/hammer_cli/options/predefined.rb
 - lib/hammer_cli/options/processor_list.rb
@@ -353,6 +354,7 @@ files:
 - test/unit/options/normalizers_test.rb
 - test/unit/options/option_collector_test.rb
 - test/unit/options/option_definition_test.rb
+- test/unit/options/option_family_test.rb
 - test/unit/options/processor_list_test.rb
 - test/unit/options/sources/command_line_test.rb
 - test/unit/options/sources/saved_defaults_test.rb
@@ -392,7 +394,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
 summary: Universal command-line interface
@@ -414,6 +416,7 @@ test_files:
 - test/unit/command_extensions_test.rb
 - test/unit/main_test.rb
 - test/unit/options/processor_list_test.rb
+- test/unit/options/option_family_test.rb
 - test/unit/options/validators/dsl_test.rb
 - test/unit/options/sources/command_line_test.rb
 - test/unit/options/sources/saved_defaults_test.rb