hammer_cli 0.19.1 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba56b0d34d9914c40df8f424e68d9268d7e2a38e5f2dd421e10991f477fbd1d
-  data.tar.gz: 5b1e6d8ea29af809ab09884cc2579c3f328439a7d102335940820bd32ec3289d
+  metadata.gz: bc020640c6f4416caa469fe39b9c029bd7feec0730a626636753046b400ac3be
+  data.tar.gz: aa7fc51d9a7ec86bb2ba0b512c9272696a399272bf90ed8e40604bfe849247dc
 SHA512:
-  metadata.gz: 7fdb4ed23030a8d87156504452c1b04959dd466015579ec2dec75b548bd5af2baea8a5538f0d4b866a2038addf2034c9df2bd89dc709378b275868e6c48c9e99
-  data.tar.gz: 45d29077823ab5997435b51f4cfab81a4c1373cd42793958811cf7ec48ab5837f48779b4ab237af9b980aca43dd43b685b2197e3f485dfc4894421098898c5f3
+  metadata.gz: b271be2146f0d730bb71e66b6ab785481b2a81ac762e101337936dcee5ae540468b060b11753ca732d5a26ded757365f2d6f52db9bee7031c767ec1db6f3f654
+  data.tar.gz: 23bfbb0ff4bbe1f556860fce41a14a39a7e17890807d85f96d09e9ff101cc254275ecce8b42f8502518da7f452f6a5101b318569f51b61a880eff4c914980d40

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

@@ -1,15 +1,41 @@
 Release notes
 =============
-### 0.19.1 (2019-12-31)
+### 2.1.2 (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.1 (2020-05-29)
+* 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))
+
+### 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

data/lib/hammer_cli/apipie/api_connection.rb

@@ -10,7 +10,11 @@ module HammerCLI::Apipie
       @api = ApipieBindings::API.new(params, HammerCLI::SSLOptions.new.get_options(params[:uri]))
       if options[:reload_cache]
         @api.clean_cache
-        @logger.debug 'Apipie cache was cleared' unless @logger.nil?
+        HammerCLI.clear_cache
+        unless @logger.nil?
+          @logger.debug 'Apipie cache was cleared'
+          @logger.debug 'Completion cache was cleared'
+        end
       end
     end