hammer_cli 2.0.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1beb690641cf038528a35bee7964c73e60acbe8a70e94bb9d1a72af372218ea1
-  data.tar.gz: 516fd63e88f8df2996aefd0d3276a9ff56e1bf5f17c1a7a8b656210512f2896c
+  metadata.gz: d4f350c15926f88971bd4ca5a7c6e2de1a58c4f5500129e61a68b2ab7f3e2643
+  data.tar.gz: 9ff9f540add2c845efb74fdced769846fe9118a1dcafdab99537a3eb1d9263f9
 SHA512:
-  metadata.gz: 8b35646b4dc9c494687b7bbd38c578ce5cf70e90080025f622b89a28f1c1d29abeafc11dbe1e16cb0786fe8ae3ac4c8673b905e8bf03cf87de86383817c653a6
-  data.tar.gz: 3a01e546cf71e7f015ec27d8c127328e380c3736106bc01b95d1b81593f2c7fa0a027e90a95bbf179407a953da871911e8dd0349c0ed980ed5cad613bd98363b
+  metadata.gz: 1540908ed1806938b8bf53819b0884a17bd2e6d095b5f2ab14a8843bb125e49934732546390475d60349ef9a2cc7bcbf44c19af7c8cbe76e1f61786d1b2b9a0a
+  data.tar.gz: 0c9f1525623225a28472b3221c528b0d03d425507263049b34ff4e0ebf167dc08ea3f9ed6f9014459930639a26935755327cb0a7b339c8f2affaa714179ab09c

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/installation_rpm.md

@@ -1,8 +1,8 @@
 ### Installation from RPMs
 
-#### Step 1: setup yum repositories
+#### Step 1: set up yum repositories
 
-For Foreman 1.3 stable the hammer packages are part of your installation repo and you can skip this step.
+For Foreman 1.3 stable, the hammer packages are part of your installation repo and you can skip this step.
 
 You can choose from stable or nightly repo. Nightly has more recent version of hammer packages, but it was subject to less testing so there is a higher risk of issues.
 Add the Foreman yum repository to your yum repo files. For Fedora installations replace 'el6' with 'f18' or 'f19' as appropriate.

data/doc/release_notes.md

@@ -1,5 +1,15 @@
 Release notes
 =============
+### 2.2.1 (2020-09-04)
+* Make fuzzy search work in hammer shell ([PR #335](https://github.com/theforeman/hammer-cli/pull/335)), [#30747](http://projects.theforeman.org/issues/30747)
+
+### 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 = ''

data/lib/hammer_cli/logger_watch.rb

@@ -1,4 +1,4 @@
-require 'awesome_print'
+require 'amazing_print'
 
 module HammerCLI
   module Logger

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/options/predefined.rb

@@ -6,7 +6,7 @@ module HammerCLI
     module Predefined
       OPTIONS = {
         fields: [['--fields'], 'FIELDS',
-                 _('Show specified fileds or predefined filed sets only. (See below)'),
+                 _('Show specified fields or predefined field sets only. (See below)'),
                  format: HammerCLI::Options::Normalizers::List.new,
                  context_target: :fields]
       }.freeze

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, fuzzy: false)
+      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.2.1"
   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.2.1
 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-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clamp
@@ -74,7 +74,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: awesome_print
+  name: amazing_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -153,26 +153,26 @@ executables:
 extensions: []
 extra_rdoc_files:
 - doc/commands_extension.md
-- doc/release_notes.md
-- doc/design.png
 - doc/commands_modification.md
-- doc/installation.md
-- doc/development_tips.md
-- doc/writing_a_plugin.md
-- doc/output.md
+- doc/creating_apipie_commands.md
+- doc/creating_commands.md
+- doc/design.png
+- doc/design.uml
 - doc/developer_docs.md
+- doc/development_tips.md
+- doc/help_modification.md
+- doc/i18n.md
+- doc/installation.md
 - doc/installation_deb.md
-- doc/option_normalizers.md
-- doc/installation_rpm.md
 - doc/installation_gem.md
-- doc/help_modification.md
-- doc/creating_commands.md
-- doc/installation_source.md
 - doc/option_builders.md
-- doc/i18n.md
+- doc/option_normalizers.md
+- doc/output.md
 - doc/review_checklist.md
-- doc/creating_apipie_commands.md
-- doc/design.uml
+- doc/writing_a_plugin.md
+- doc/installation_rpm.md
+- doc/installation_source.md
+- doc/release_notes.md
 - config/cli.modules.d/module_config_template.yml
 - config/cli_config.template.yml
 - config/hammer.completion
@@ -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,74 +394,75 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Universal command-line interface
 test_files:
-- test/unit/messages_test.rb
-- test/unit/exception_handler_test.rb
-- test/unit/modules_test.rb
-- test/unit/connection_test.rb
-- test/unit/completer_test.rb
-- test/unit/csv_parser_test.rb
-- test/unit/option_builder_test.rb
-- test/unit/test_helper.rb
-- test/unit/utils_test.rb
+- test/functional/defaults_test.rb
+- test/functional/help_test.rb
+- test/functional/nil_values_test.rb
+- test/functional/test_helper.rb
+- test/test_helper.rb
+- test/unit/abstract_test.rb
+- test/unit/apipie/api_connection_test.rb
 - test/unit/apipie/command_test.rb
 - test/unit/apipie/option_builder_test.rb
-- test/unit/apipie/test_helper.rb
-- test/unit/apipie/api_connection_test.rb
 - test/unit/apipie/option_definition_test.rb
+- test/unit/apipie/test_helper.rb
+- test/unit/bash_test.rb
+- test/unit/ca_cert_manager_test.rb
 - test/unit/command_extensions_test.rb
-- test/unit/main_test.rb
-- test/unit/options/processor_list_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
-- test/unit/options/matcher_test.rb
-- test/unit/options/option_collector_test.rb
-- test/unit/options/normalizers_test.rb
-- test/unit/options/option_definition_test.rb
-- test/unit/settings_test.rb
-- test/unit/history_test.rb
+- test/unit/completer_test.rb
+- test/unit/connection_test.rb
+- test/unit/csv_parser_test.rb
 - test/unit/defaults_test.rb
-- test/unit/logger_test.rb
-- test/unit/output/formatters_test.rb
-- test/unit/output/record_collection_test.rb
-- test/unit/output/dsl_test.rb
-- test/unit/output/definition_test.rb
-- test/unit/output/output_test.rb
-- test/unit/output/field_filter_test.rb
-- test/unit/output/fields_test.rb
-- test/unit/output/adapter/table_test.rb
-- test/unit/output/adapter/json_test.rb
-- test/unit/output/adapter/abstract_test.rb
-- test/unit/output/adapter/yaml_test.rb
-- test/unit/output/adapter/csv_test.rb
-- test/unit/output/adapter/base_test.rb
-- test/unit/abstract_test.rb
-- test/unit/i18n_test.rb
+- test/unit/exception_handler_test.rb
 - test/unit/fixtures/apipie/architectures.json
 - test/unit/fixtures/apipie/documented.json
-- test/unit/fixtures/defaults/defaults_dashed.yml
-- test/unit/fixtures/defaults/defaults.yml
-- test/unit/fixtures/json_input/valid.json
-- test/unit/fixtures/json_input/invalid.json
 - test/unit/fixtures/certs/ca_cert.pem
 - test/unit/fixtures/certs/non_ca_cert.pem
-- test/unit/bash_test.rb
-- test/unit/help/definition/section_test.rb
-- test/unit/help/definition/list_test.rb
-- test/unit/help/definition/text_test.rb
+- test/unit/fixtures/defaults/defaults.yml
+- test/unit/fixtures/defaults/defaults_dashed.yml
+- test/unit/fixtures/json_input/invalid.json
+- test/unit/fixtures/json_input/valid.json
+- test/unit/help/builder_test.rb
 - test/unit/help/definition/abstract_item_test.rb
+- test/unit/help/definition/list_test.rb
 - test/unit/help/definition/note_test.rb
+- test/unit/help/definition/section_test.rb
+- test/unit/help/definition/text_test.rb
 - test/unit/help/definition_test.rb
-- test/unit/help/builder_test.rb
 - test/unit/help/text_builder_test.rb
-- test/unit/ca_cert_manager_test.rb
-- test/functional/help_test.rb
-- test/functional/test_helper.rb
-- test/functional/nil_values_test.rb
-- test/functional/defaults_test.rb
-- test/test_helper.rb
+- test/unit/history_test.rb
+- test/unit/i18n_test.rb
+- test/unit/logger_test.rb
+- test/unit/main_test.rb
+- test/unit/messages_test.rb
+- test/unit/modules_test.rb
+- test/unit/option_builder_test.rb
+- test/unit/options/matcher_test.rb
+- 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
+- test/unit/options/validators/dsl_test.rb
+- test/unit/output/adapter/abstract_test.rb
+- test/unit/output/adapter/base_test.rb
+- test/unit/output/adapter/csv_test.rb
+- test/unit/output/adapter/json_test.rb
+- test/unit/output/adapter/table_test.rb
+- test/unit/output/adapter/yaml_test.rb
+- test/unit/output/definition_test.rb
+- test/unit/output/dsl_test.rb
+- test/unit/output/field_filter_test.rb
+- test/unit/output/fields_test.rb
+- test/unit/output/formatters_test.rb
+- test/unit/output/output_test.rb
+- test/unit/output/record_collection_test.rb
+- test/unit/settings_test.rb
+- test/unit/test_helper.rb
+- test/unit/utils_test.rb