hammer_cli 0.19.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba56b0d34d9914c40df8f424e68d9268d7e2a38e5f2dd421e10991f477fbd1d
-  data.tar.gz: 5b1e6d8ea29af809ab09884cc2579c3f328439a7d102335940820bd32ec3289d
+  metadata.gz: d903c3dbbe33a2411dfd2e23b781609a40b39b4ed29066cabe35af22335042d5
+  data.tar.gz: 25acdf29e7a071a945a4c7c2c4745083e0e11e7d12ce098c662054a7d87caeb1
 SHA512:
-  metadata.gz: 7fdb4ed23030a8d87156504452c1b04959dd466015579ec2dec75b548bd5af2baea8a5538f0d4b866a2038addf2034c9df2bd89dc709378b275868e6c48c9e99
-  data.tar.gz: 45d29077823ab5997435b51f4cfab81a4c1373cd42793958811cf7ec48ab5837f48779b4ab237af9b980aca43dd43b685b2197e3f485dfc4894421098898c5f3
+  metadata.gz: 8a117c635359bc261f70cb67bf33fc2080f15b909981a98f87d7c64235a2ecf686bf1530b5293e60565e5e52cab2ed9bbf17f604816099ada8e11b11a5b7f064
+  data.tar.gz: 3e296e36f46d6374fc1878a51447cd2fe820104fa5ba191c6bde91a62aff2fd7b76e12743d152ca0eb9457b541e38dd39351da138020501d286c3af071e33b39

data/bin/hammer-complete

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'English'
+@project_root = File.expand_path('../..', __FILE__)
+$LOAD_PATH.unshift(File.join(@project_root, 'lib'))
+HAMMER = ENV['HAMMER'] || File.join(@project_root, 'bin/hammer')
+
+require 'yaml'
+
+completion_cache_file = ENV['HAMMER_COMPLETION_CACHE'] || '~/.cache/hammer_completion.yml'
+completion_cache_file = File.expand_path(completion_cache_file)
+
+# build the cache if it does not exist
+unless File.exist?(completion_cache_file)
+  require 'hammer_cli'
+  `#{HAMMER} prebuild-bash-completion`
+end
+
+require 'hammer_cli/bash/completion'
+
+dict = HammerCLI::Bash::Completion.load_description(completion_cache_file)
+
+comp_line = ENV['COMP_LINE'] || ''
+comp_args = comp_line.split(' ', 2).last || ''
+
+result = HammerCLI::Bash::Completion.new(dict).complete(comp_args)
+
+puts result.join("\n")

data/config/cli_config.template.yml

@@ -44,6 +44,8 @@
 # Log record pattern (logging gem syntax)
 #:log_pattern: '[%5l %d %c] %m'
 
+# Location of cache for bash completion
+:completion_cache_file: '~/.cache/hammer_completion.yml'
 
 # SSL auth options
 #:ssl:

data/config/hammer.completion

@@ -0,0 +1,5 @@
+#
+# Hammer CLI bash completion script
+#
+
+complete -C hammer-complete -o nospace hammer

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.
@@ -494,6 +567,33 @@ You first create an _output definition_ that you apply to your data. The result
 is a collection of fields, each having its type. The collection is then passed to an
 _output adapter_ which handles the actual formatting and printing.
 
+Adapters support printing by chunks, e.g. if you want to print a large set of
+data (1000+ records), but you make several calls to the server instead of one,
+you may want to print received data right away instead of waiting for the rest.
+This can be achieved via `:current_chunk` option for
+`print_collection` and `print_data` methods. Allowed values for `:current_chunk`
+are `:first`, `:another`, `:last`. By default adapters use `:single` value that
+means only one record will be printed.
+
+##### Printing by chunks
+```ruby
+# ...
+  def execute
+    loop do
+      # ...
+      data = send_request
+      print_data(data, current_chunk: :first)
+      # ...
+      data = send_request
+      print_data(data, current_chunk: :another)
+      # ...
+      data = send_request
+      print_data(data, current_chunk: :last)
+    end
+  end
+# ...
+```
+
 Hammer provides a DSL for defining the output. Next rather complex example will
 explain how to use it in action.
 

data/doc/installation.md

@@ -132,8 +132,51 @@ And you are done. Your hammer client is configured and ready to use.
 Autocompletion
 --------------
 
-It is necessary to copy the hammer_cli_complete script to the bash_completion.d directory.
-
-    $ sudo cp hammer-cli/hammer_cli_complete /etc/bash_completion.d/
+The completion offers suggestion of possible command-line subcommands and their
+options as usual. It can also suggest values for options and params where file
+or directory path is expected.
+
+Bash completion is automatically installed by RPM. To use it for development
+setup `cp ./config/hammer.completion /etc/bash_completion.d/hammer` and load it
+to the current shell `source /etc/bash_completion.d/hammer`. Make sure
+the `$PWD/bin` is in `PATH` or there is full path to `hammer-complete`
+executable specified in `/etc/bash_completion.d/hammer`.
+
+Bash completion for hammer needs pre-built cache that holds description of
+all subcommands and its parameters. The cache is located by default in
+`~/.cache/hammer_completion.yml`. The location can be changed in hammer's
+config file. The cache can be built manually with
+`hammer prebuild-bash-completion` or is built automatically when completion is
+used and the cache is missing (this may cause slight delay). The cache expires
+if your API cache was changed (it indicates that the features on the instance
+may have changed which has impact on hammer CLI options and subcommands).
+
+####  Available value types
+
+Completion of values is dependent on CLI option and prameter settings, e.g.:
+
+```ruby
+  option '--value', 'VALUE', 'One of a, b, c', completion: { type: :enum, values: %w[a b c] }
+```
 
-Then after starting a new shell the completion should work.
+Possible options for the `:completion` attribute are:
+ - `{ type: :flag }` option has no value, default for flags.
+ - `{ type: :value }` option has value of unknown type, no suggestions for the
+value, default.
+- `{ type: :list }` option has value of list type, no suggestions for the
+value.
+- `{ type: :key_value_list }` option has value of key=value list type, no
+suggestions for the value.
+ - `{ type: :directory }` value is directory, suggestions follow directory
+structure.
+ - `{ type: :file, filter: '\.txt$' }` value is file, suggestions follow
+directory structure, optional `:filter` is regexp to filter the results.
+ - `{ type: :enum, values: ['first', 'second']}` option can have one of the
+listed values, suggestions follow specified `values`.
+ - `{ type: :multienum, values: ['first', 'second']}` option can have one or
+more of the listed values, suggestions follow specified `values`.
+ - `{ type: :schema, schema: 'a=int\,b=string' }` option should have value
+according to specified schema, suggestion is the specified schema.
+
+All those completion attributes are generated automatically, specify you own to
+override.

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,15 +1,40 @@
 Release notes
 =============
-### 0.19.1 (2019-12-31)
+### 2.2.0 (2020-08-11)
+* Update installation_rpm.md ([PR #333](https://github.com/theforeman/hammer-cli/pull/333))
+* Clean gem_release.ipynb up
+* Replace awesome_print with amazing_print ([PR #330](https://github.com/theforeman/hammer-cli/pull/330)), [#29846](http://projects.theforeman.org/issues/29846)
+* Fix typo: s/filed/feild/ ([PR #331](https://github.com/theforeman/hammer-cli/pull/331))
+* Bump to 2.2.0-develop
+
+### 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))
+* Better promts for missing arguments, [#28793](http://projects.theforeman.org/issues/28793)
 * Allow column max width more than 80, [#28503](http://projects.theforeman.org/issues/28503)
+* Remove computing sha, [#27728](http://projects.theforeman.org/issues/27728)
+* Fixed userdata false display in image list, [#28134](http://projects.theforeman.org/issues/28134)
+* Add new bash completion, [#27728](http://projects.theforeman.org/issues/27728)
+* Allow adapters print page by page, [#17819](http://projects.theforeman.org/issues/17819)
+* Add release documentation ([PR #317](https://github.com/theforeman/hammer-cli/pull/317)), [#28149](http://projects.theforeman.org/issues/28149)
+* Fix pr links in release notes ([PR #318](https://github.com/theforeman/hammer-cli/pull/318)), [#28202](http://projects.theforeman.org/issues/28202)
 * Extract table generator into reusable component ([PR #314](https://github.com/theforeman/hammer-cli/pull/314)), [#27318](http://projects.theforeman.org/issues/27318)
+* Better prompts for missing arguments ([PR #313](https://github.com/theforeman/hammer-cli/pull/313)), [#27595](http://projects.theforeman.org/issues/27595)
+* Bump to 0.20-develop
 
 ### 0.19.0 (2019-10-26)
-* Allow schema building for custom options ([PR #316](https://github.com/Apipie/apipie-bindings/pull/316)), [#27899](http://projects.theforeman.org/issues/27899)
-* New lines in text attr dont break output ([PR #300](https://github.com/Apipie/apipie-bindings/pull/300)), [#25878](http://projects.theforeman.org/issues/25878)
-* Added error to wrong --output ([PR #315](https://github.com/Apipie/apipie-bindings/pull/315)), [#21590](http://projects.theforeman.org/issues/21590)
-* Pr review checklist ([PR #305](https://github.com/Apipie/apipie-bindings/pull/305)), [#26950](http://projects.theforeman.org/issues/26950)
-* List items in help with customization ([PR #309](https://github.com/Apipie/apipie-bindings/pull/309)), [#27237](http://projects.theforeman.org/issues/27237)
+* Allow schema building for custom options ([PR #316](https://github.com/theforeman/hammer-cli/pull/316)), [#27899](http://projects.theforeman.org/issues/27899)
+* New lines in text attr dont break output ([PR #300](https://github.com/theforeman/hammer-cli/pull/300)), [#25878](http://projects.theforeman.org/issues/25878)
+* Added error to wrong --output ([PR #315](https://github.com/theforeman/hammer-cli/pull/315)), [#21590](http://projects.theforeman.org/issues/21590)
+* Pr review checklist ([PR #305](https://github.com/theforeman/hammer-cli/pull/305)), [#26950](http://projects.theforeman.org/issues/26950)
+* List items in help with customization ([PR #309](https://github.com/theforeman/hammer-cli/pull/309)), [#27237](http://projects.theforeman.org/issues/27237)
 
 ### 0.18.0 (2019-08-01)
 * Unsure minimal label length ([PR #310](https://github.com/theforeman/hammer-cli/pull/310)) ([#26960](http://projects.theforeman.org/issues/26960))

data/lib/hammer_cli.rb

@@ -23,3 +23,4 @@ require 'hammer_cli/apipie'
 require 'hammer_cli/shell'
 require 'hammer_cli/defaults'
 require 'hammer_cli/full_help'
+require 'hammer_cli/bash'

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
@@ -74,6 +75,7 @@ module HammerCLI
       begin
         begin
           exit_code = super
+          context.delete(:fields)
           raise "exit code must be integer" unless exit_code.is_a? Integer
         rescue => e
           exit_code = handle_exception(e)
@@ -190,10 +192,21 @@ 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)
         extend_options_help(option) if option.value_formatter.is_a?(HammerCLI::Options::Normalizers::ListNested)
+        completion_type_for(option)
       end
     end
 
@@ -205,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}."
@@ -220,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
@@ -242,8 +262,8 @@ module HammerCLI
       output.print_record(definition, record)
     end
 
-    def print_collection(definition, collection)
-      output.print_collection(definition, collection)
+    def print_collection(definition, collection, options = {})
+      output.print_collection(definition, collection, options)
     end
 
     def print_message(msg, msg_params = {}, options = {})
@@ -283,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)
@@ -314,6 +343,7 @@ module HammerCLI
         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
@@ -352,6 +382,33 @@ module HammerCLI
       sources
     end
 
+    def self.completion_map
+      completion = {}
+      # collect options
+      recognised_options.each do |opt|
+        opt.switches.each do |switch|
+          completion[switch] = completion_types.fetch(switch, {})
+        end
+      end
+      # collect subcommands recursively
+      recognised_subcommands.each do |cmd|
+        completion[cmd.names.first] = cmd.subcommand_class.completion_map
+      end
+      # collect params
+      completion[:params] = completion_types[:params] unless completion_types[:params].empty?
+      completion
+    end
+
+    def self.completion_types
+      @completion_types ||= { :params => [] }
+    end
+
+    def self.completion_type_for(option, opts = {})
+      completion_type = opts.delete(:completion)
+      completion_type ||= option.completion_type(opts[:format])
+      [option.switches].flatten(1).each { |s| completion_types[s] = completion_type }
+    end
+
     private
 
     def self.inherited_output_definition