hammer_cli 0.19.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da086330c730e02850d33b001aecfc8203c366f535b03c9c48c33f83811fc796
-  data.tar.gz: 912ec4c67dbefe2cb3d6595cc6a8f8b484f12d4c004dd901442135fb4cce9103
+  metadata.gz: 1beb690641cf038528a35bee7964c73e60acbe8a70e94bb9d1a72af372218ea1
+  data.tar.gz: 516fd63e88f8df2996aefd0d3276a9ff56e1bf5f17c1a7a8b656210512f2896c
 SHA512:
-  metadata.gz: 655cd84a3f0114b2c216157941c86f7b76dcb7c79a54efcf8c7fe66ed72cc9bc83671eaef98223894e396c29d433df76f17ad86f980a92afdd6ec70591caffc8
-  data.tar.gz: 3a1a1826637889a8bf6ee7d8db334944daa0c30b343282b7e29edf7463d84cdc90084a696aacec19f3ca4a0dde9083fe41d4801e88449bd3493d5af6d7ec6337
+  metadata.gz: 8b35646b4dc9c494687b7bbd38c578ce5cf70e90080025f622b89a28f1c1d29abeafc11dbe1e16cb0786fe8ae3ac4c8673b905e8bf03cf87de86383817c653a6
+  data.tar.gz: 3a01e546cf71e7f015ec27d8c127328e380c3736106bc01b95d1b81593f2c7fa0a027e90a95bbf179407a953da871911e8dd0349c0ed980ed5cad613bd98363b

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

@@ -494,6 +494,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,18 +1,26 @@
 Release notes
 =============
-### 0.19.2 (2020-01-16)
-* Fixed userdata false display in image list ([PR #321](https://github.com/theforeman/hammer-cli/pull/321)), [#28134](http://projects.theforeman.org/issues/28134)
-
-### 0.19.1 (2019-12-31)
+### 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

@@ -74,6 +74,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)
@@ -194,6 +195,7 @@ module HammerCLI
         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
 
@@ -242,8 +244,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 = {})
@@ -314,6 +316,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 +355,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
 

data/lib/hammer_cli/apipie/command.rb

@@ -65,8 +65,8 @@ module HammerCLI::Apipie
       method_options(options)
     end
 
-    def print_data(data)
-      print_collection(output_definition, data) unless output_definition.empty?
+    def print_data(data, options = {})
+      print_collection(output_definition, data, options) unless output_definition.empty?
       print_success_message(data) unless success_message.nil?
     end
 
@@ -86,6 +86,7 @@ module HammerCLI::Apipie
         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

data/lib/hammer_cli/bash.rb

@@ -0,0 +1,2 @@
+require 'hammer_cli/bash/prebuild_command'
+require 'hammer_cli/bash/completion'

data/lib/hammer_cli/bash/completion.rb

@@ -0,0 +1,159 @@
+require 'json'
+
+module HammerCLI
+  module Bash
+    class Completion
+      def initialize(dict)
+        @dict = dict
+      end
+
+      def complete(line)
+        @complete_line = line.end_with?(' ')
+        full_path = line.split(' ')
+        complete_path = @complete_line ? full_path : full_path[0..-2]
+        dict, path = traverse_tree(@dict, complete_path)
+
+        return [] unless path.empty? # lost during traversing
+
+        partial = @complete_line ? '' : full_path.last
+        finish_word(dict, partial)
+      end
+
+      def self.load_description(path)
+        JSON.load(File.open(path))
+      rescue Errno::ENOENT
+        {}
+      end
+
+      private
+
+      def finish_word(dict, incomplete)
+        finish_option_value(dict, incomplete) ||
+          (finish_option_or_subcommand(dict, incomplete) + finish_param(dict, incomplete))
+      end
+
+      def finish_option_or_subcommand(dict, incomplete)
+        dict.keys.select { |k| k.is_a?(String) && k =~ /^#{incomplete}/ }.map { |k| k + ' ' }
+      end
+
+      def complete_value(value_description, partial, is_param)
+        case value_description['type']
+        when 'value'
+          if !partial.empty?
+            []
+          elsif is_param
+            ['--->', 'Add parameter']
+          else
+            ['--->', 'Add option <value>']
+          end
+        when 'directory'
+          directories(partial)
+        when 'file'
+          files(partial, value_description)
+        when 'enum'
+          enum(partial, value_description['values'])
+        when 'multienum'
+          multienum(partial, value_description['values'])
+        when 'schema'
+          schema(value_description['schema'])
+        when 'list'
+          ['--->', 'Add comma-separated list of values']
+        when 'key_value_list'
+          ['--->', 'Add comma-separated list of key=value']
+        end
+      end
+
+      def finish_param(dict, incomplete)
+        if dict['params'] && !dict['params'].empty?
+          complete_value(dict['params'].first, incomplete, true)
+        else
+          []
+        end
+      end
+
+      def finish_option_value(dict, incomplete)
+        complete_value(dict, incomplete, false) if dict.key?('type')
+      end
+
+      def traverse_tree(dict, path)
+        return [dict, []] if path.nil? || path.empty?
+        result = if dict.key?(path.first)
+                   if path.first.start_with?('-')
+                     parse_option(dict, path)
+                   else
+                     parse_subcommand(dict, path)
+                   end
+                 elsif dict['params']
+                   # traverse params one by one
+                   parse_params(dict, path)
+                 else
+                   # not found
+                   [{}, path]
+                 end
+        result
+      end
+
+      def parse_params(dict, path)
+        traverse_tree({ 'params' => dict['params'][1..-1] }, path[1..-1])
+      end
+
+      def parse_subcommand(dict, path)
+        traverse_tree(dict[path.first], path[1..-1])
+      end
+
+      def parse_option(dict, path)
+        if dict[path.first]['type'] == 'flag' # flag
+          traverse_tree(dict, path[1..-1])
+        elsif path.length >= 2 # option with value
+          traverse_tree(dict, path[2..-1])
+        else # option with value missing
+          [dict[path.first], path[1..-1]]
+        end
+      end
+
+      def directories(partial = '')
+        dirs = []
+        dirs += Dir.glob("#{partial}*").select { |f| File.directory?(f) }
+        dirs = dirs.map { |d| d + '/' } if dirs.length == 1
+        dirs
+      end
+
+      def files(partial = '', opts = {})
+        filter = opts.fetch('filter', '.*')
+        file_names = []
+        file_names += Dir.glob("#{partial}*").select do |f|
+          File.directory?(f) || f =~ /#{filter}/
+        end
+        file_names.map { |f| File.directory?(f) ? f + '/' : f + ' ' }
+      end
+
+      def enum(partial = '', values = [])
+        values.select { |v| v.start_with?(partial) }.map { |v| v + ' ' }
+      end
+
+      def multienum(partial = '', values = [])
+        return values if partial.empty?
+
+        parts = partial.split(',')
+        resolved = []
+        to_complete = parts.each_with_object([]) do |part, res|
+          next resolved << part if values.include?(part)
+
+          res << part
+        end
+
+        hints = to_complete.map do |p|
+          values.select { |v| v.start_with?(p) }
+        end.flatten(1).uniq
+        return values - parts if hints.empty?
+        return [(resolved + hints).join(',')] if hints.size == 1
+
+        hints
+      end
+
+      def schema(template = '')
+        ['--->', "Add value by following schema: #{template}"]
+      end
+    end
+  end
+end