hammer_cli 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3fdeba3063ee3ba211aabb8a6d57d17a70fb7f22
-  data.tar.gz: b085e64553cde11ebed24c0525e461bdcf9ee3e0
+  metadata.gz: 836795c65ef362f852b3eed29126508d0bf23927
+  data.tar.gz: 8300578ae0b731724817506ee20bda1ea458b71b
 SHA512:
-  metadata.gz: 9a706bd9e66688c5642575c9eea4d3d5963847eb93dcac2293b14a3d109d3d52582effa20dd9f69c51448a5497e1555ed769759c58ce9a84b1d70ea96711a2b1
-  data.tar.gz: 967e76b9ee2e0ed6f131b5dced17032bfe288f9e74ac7e831dc92865b0478ee2b5056a6edcae41064e97d0c36092932529bfa07d0fe6002514dde1e8a28ca0ee
+  metadata.gz: 848a8e9636cb5c8e8dea817de554d943f73db10399d897d770d71a7df5cfc66d5c843b351c64587781dd93ae5be81ecd17afe0e2ffa4e0ce7192d55e4d5fd732
+  data.tar.gz: aa6bbeb277ae28f0d1c1626f78773dcfbd64a4b81de89609a5fa64eff4a7a607e582f464fb2b58bc7df30b3770c877b2188b62ed14030992630a21932e0b9cf8

data/doc/commands_modification.md

@@ -0,0 +1,82 @@
+Modify an existing command
+-------------------------
+
+### Modification of output fields
+
+Each command (as well as each field) might have its own
+output definition. You can modify the output definition of existing
+command or a specific field of that command by following output
+definition interface:
+
+```ruby
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+  # Appends fields to the end.
+  # Where:
+  #   fields is one or more existing fields
+  #   block is block of code with new fields
+  definition.append(fields) do
+    label
+    field
+    collection
+  end
+  # Inserts one or more fields.
+  # Where:
+  #   :mode is one of [:before, :after, :replace]
+  #   :id is field's id or key. Field's label can be used if field does not
+  # have id
+  #   fields is one or more existing fields
+  #   block is block of code with new fields
+  definition.insert(:mode, :id, fields) do
+    label
+    field
+    collection
+  end
+  # Returns output definition of the command or field specified with path.
+  # Where:
+  #   path = Array of :key or/and :id or/and 'label']
+  definition.at(path)
+  # Returns field from current output definition.
+  definition.find_field(:id)
+  # Deletes all fields from current output definition.
+  definition.clear
+end
+```
+#### Examples
+```ruby
+# Append some fields to the end
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+                                     definition.at(_('Collection Field Label'))
+                                               .append do
+                                                 field :value3, _('Value 3')
+                                               end
+                                    end
+# Change field's label
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+                                      definition.at(:path)
+                                      .find_field(:id).label = _('New label')
+                                    end
+# Expand a field with new definition
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+                                      definition.at([_('some'), :path])
+                                      .insert(:replace, :not_container_field_id) do
+                                        field nil, _('Label with new fields'), Fields::Label, id: :now_container_field_id do
+                                        field :new_field1, _('New field 1')
+                                        field :new_field2, _('New field 2')
+                                        end
+                                      end
+                                    end
+# Insert a new field after specific field
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+                                     definition.at([_('some'), :path])
+                                     .insert(:after, :other_field_id, [Fields::Field.new(label: _('My field'), id: :my_field_id)])
+                                    end
+# Insert a new field before specific field
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+                                      definition.insert(:before, :other_field_id,
+                                        Fields::Field.new(label: _('My field'), id: :my_field_id))
+                                    end
+# Remove field
+HammerCLIForeman::Host::InfoCommand.extend_output_definition do |definition|
+                                      definition.insert(:replace, :field_id) do; end
+                                    end
+```

data/doc/creating_commands.md

@@ -169,33 +169,7 @@ In cases when you want to deprecate just one of more possible switches use the e
 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.
 
-### Option validation
-Hammer provides extended functionality for validating options.
-
-#### DSL
-First of all there is a dsl for validating combinations of options:
-```ruby
-validate_options do
-  all(:option_name, :option_surname).required  # requires all the options
-  option(:option_age).required          # requires a single option,
-                                        # equivalent of :required => true in option declaration
-  any(:option_email, :option_phone).required   # requires at least one of the options
-
-  # It is possible to create more complicated constructs.
-  # This example requires either the full address or nothing
-  if any(:option_street, :option_city, :option_zip).exist?
-    all(:option_street, :option_city, :option_zip).required
-  end
-
-  # Here you can reject all address related option when --no-address is passed
-  if option(:option_no_address).exist?
-    all(:option_street, :option_city, :option_zip).rejected
-  end
-end
-
-```
-
-#### Option normalizers
+### Option normalizers
 Another option-related feature is a set of normalizers for specific option types. They validate and preprocess
 option values. Each normalizer has a description of the format it accepts. This description is printed
 in commands' help.
@@ -244,24 +218,90 @@ option "--attributes", "ATTRIBUTES", "Values of various attributes",
 
 ### Advanced option evaluation
 
-Sometimes it is necessary to tune the option values based on other parameters given on CLI.
+Sometimes it is necessary to tune or validate the option values based on other parameters given on CLI.
 An example could be setting default values based on other options, values lookup in a DB, etc.
-The right place for this are `OptionSources`. Abstract Hammer command uses two default option sources -
-`HammerCLI::Options::Sources::CommandLine` responsible for intial population of the options,
+The right place for this are option processors. There are two basic kinds of option processors in hammer:
+- *option sources* - they provide values for the options, descendants of `HammerCLI::Options::Sources::Base`
+- *option validators* - they check if the options values are valid, descendants of `HammerCLI::Options::Validators::Base`
+
+Option sources and validators can be mixed together. For example it's possible to collect options from the command line,
+do some validation on them and then continue with collecting options from a different source.
+The whole set of processors is invoked only once per command call. The processing is triggered by a first call
+to the `options` or `all_options` method, but at latest right after the option validation
+(before the command's `execute` method is invoked). The order is as follows:
+ 1. option parsing
+ 1. option normalization
+ 1. option processors execution (sources and validators)
+ 1. `execute` invocation
+
+#### Default option sources
+
+Abstract Hammer command uses two default option sources -
+`HammerCLI::Options::Sources::CommandLine` responsible for intial population of the options and
 `HammerCLI::Options::Sources::SavedDefaults` adding defaults managed by the `defaults` command.
 
+The default option sources are wrapped in `DefaultInputs` processor list so that it's possible to easily place
+custom sources before or behind all the default ones.
+The full default hierarchy is:
+
+```
+- DefaultInputs
+    - CommandLine
+    - SavedDefaults (present only when defaults are enabled)
+```
+
 By overriding `option_sources` method in a command it is possible to add custom option sources
 for various tasks to the list. The option sources are evaluated one by one each being given output
 of the previous one as its input so the order in which the sources are listed matters.
 
-Option sources are collected only once per command call. The collection is triggered by first call
-to the `options` or `all_options` method, but at latest right after the option validation
-(before the command's `execute` method is invoked). The order is as follows:
- 1. parse
- 1. option normalization
- 1. option validation (run against normalized raw options as given on CLI)
- 1. option sources execution
- 1. `execute` invocation
+#### Option validation
+Hammer provides extended functionality for validating options.
+
+First of all there is a DSL for validating combinations of options:
+```ruby
+validate_options do
+  all(:option_name, :option_surname).required  # requires all the options
+  option(:option_age).required          # requires a single option,
+                                        # equivalent of :required => true in option declaration
+  any(:option_email, :option_phone).required   # requires at least one of the options
+
+  # It is possible to create more complicated constructs.
+  # This example requires either the full address or nothing
+  if any(:option_street, :option_city, :option_zip).exist?
+    all(:option_street, :option_city, :option_zip).required
+  end
+
+  # Here you can reject all address related option when --no-address is passed
+  if option(:option_no_address).exist?
+    all(:option_street, :option_city, :option_zip).rejected
+  end
+end
+
+```
+
+It's possible to insert a validation block on a certain place in the option processor chain:
+```ruby
+validate_options(:after, 'DefaultInputs') do
+  # ...inserts the validation block after DefaultInputs option source
+end
+
+validate_options(:prepend) do
+  # ...adds validation to the first place in the queue
+end
+
+# Following insert modes can be used:
+# before, after, append, prepend (the default behavior)
+```
+
+Alternatively the functionality can be extracted in a validator object that can be shared by multiple commands:
+
+```ruby
+validate_options(:after, 'DefaultInputs', validator: Custom::Validator.new)
+
+```
+
+`validate_options` adds validators into a specific command class and they aren't inherited with subclasses.
+Inheritable validators can be created command's `add_validators` method.
 
 
 ### Adding subcommands

data/doc/developer_docs.md

@@ -8,6 +8,8 @@ before creating hammer specific plugins.
 Contents:
  - [Writing a plugin](writing_a_plugin.md#writing-your-own-hammer-plugin)
  - [Creating commands](creating_commands.md#create-your-first-command)
+ - [Help modification](help_modification.md#modify-an-existing-help)
+ - [Commands modification](commands_modification.md#modify-an-existing-command)
  - [Option builders](option_builders.md#option-builders)
  - [Creating ApiPie commands](creating_apipie_commands.md#creating-commands-for-restful-api-with-apipie)
  - [Development tips](development_tips.md#development-tips)

data/doc/help_modification.md

@@ -0,0 +1,119 @@
+Modify an existing help
+-------------------------
+Each command might have its own help definition. This definition is composed of various _help items_, which might contain their own definitions.
+
+Let's say `hammer host create -h` help string has the following structure:
+```
+hammer host create -h
++-- Usage
++-- Options
++-- Additional info
+|   +-- Section(Available keys for --interface:)
+|   |  +-- List
+|   |  +-- Section
+|   |  |  +-- List
+|   |  +-- Section
+|   |  |  +-- List
+|   |  +-- Section
+|   |  |  +-- List
+|   +-- Section(Provider specific options:)
+|   |  +-- Section
+|   |  |  +-- Section
+|   |  |  |  +-- List
+...
+|   |  +-- Section(Libvirt:)
+|   |  |  +-- Section(--compute-attributes:)
+|   |  |  |  +-- List[
+                   cpus                Number of CPUs
+                   memory              String, amount of memory, value in bytes
+                   start               Boolean (expressed as 0 or 1), whether to start the machine or not
+                 ]
+...
+|   |  |  +-- Section
+|   |  |  |  +-- List
+```
+Every `Section`, `List` and simple `Text` is _help item_ defined as `HammerCLI::Help::AbstractItem`, so everything might have its own ID now for easier addressing.
+
+To modify the structure above, you might use the following:
+```ruby
+HammerCLIForeman::Host::CreateCommand.extend_help do |h|
+  # Simple addition to the end.
+  h.section
+  h.list
+  h.text
+
+  # Inserts one or more help items.
+  # Where:
+  #   :mode is one of [:before, :after, :replace]
+  #   :item_id is item's id or label. Item's label can be used if it does not
+  # have an id, e.g. any Section
+  #   block is block of code with new items
+  h.insert(:mode, :item_id) do |h|
+    h.section
+    h.list
+    h.text
+  end
+  # Addition to custom path.
+  # Where:
+  #   path is Array of :item_id or/and 'item_label'
+  #   block is the code block with new help items.
+  h.at(path) do |h|
+    ...
+    h.section
+    h.list
+    h.text
+    ...
+  end
+  # Returns help item from current definition.
+  h.find_item(:item_id)
+end
+```
+
+#### Examples
+```ruby
+# Add a new section with list to the end of the Libvirt section.
+HammerCLIForeman::Host::CreateCommand.extend_help do |h|
+  h.at(['Provider specific options', 'Libvirt']) do |h|
+    h.section('--new-section-with-list', id: :section_with_list) do |h|
+      h.list([
+        ['item1', _('Desc1')],
+        ['item2'],
+        ['item3', _('Desc3')]
+      ], id: :list_with_id)
+    end
+  end
+end
+
+# Add important information
+HammerCLIForeman::Host::CreateCommand.extend_help do |h|
+  h.at(['Provider specific options']) do |h|
+    h.insert(:before, 'EC2') do |h|
+      h.text('Something important for all providers')
+    end
+    h.at(['EC2']) do |h|
+      h.insert(:before, '--compute-attributes') do |h|
+        h.text('Something important for EC2 only')
+      end
+    end
+  end
+end
+
+# Delete the Libvirt section from Provider specific options section.
+HammerCLIForeman::Host::CreateCommand.extend_help do |h|
+  h.at('Provider specific options') do |h|
+    h.insert(:replace, 'Libvirt') do |h|; end
+  end
+end
+
+# Add more text
+HammerCLIForeman::Host::CreateCommand.extend_help do |h|
+  h.at('Provider specific options') do |h|
+    h.insert(:before, 'EC2') do |h|
+      h.text('Imagine it already was here', id: :old_text_id)
+    end
+  end
+  h.at(['Provider specific options', :old_text_id]) do |h|
+    h.text('Additional information', id: :additional_text)
+  end
+end
+```

data/doc/i18n.md

@@ -73,8 +73,8 @@ HammerCLI::I18n::FindTask.define(HammerCLIAwesome::I18n::LocaleDomain.new, Hamme
 and create `locale/Makefile` with following content:
 ```make
 DOMAIN = hammer-cli-awesome
-VERSION = $(shell bundle exec ruby -e 'require "rubygems"; spec = Gem::Specification::load("../hammer_cli_awesome.gemspec"); puts spec.version')
-MAIN_MAKEFILE = $(shell bundle exec ruby -e 'require "hammer_cli"; puts HammerCLI::I18n.main_makefile')
+VERSION = $(shell bundle exec ruby -C ../ -e 'require "rubygems"; spec = Gem::Specification::load("../hammer_cli_awesome.gemspec"); puts spec.version')
+MAIN_MAKEFILE = $(shell bundle exec ruby -C ../ -e 'require "hammer_cli"; puts HammerCLI::I18n.main_makefile')
 
 include $(MAIN_MAKEFILE)
 ```

data/doc/installation_rpm.md

@@ -32,7 +32,7 @@ On RHEL systems you will also have to add [EPEL repository](https://fedoraprojec
 #### Step 2: install hammer core
 
 ```bash
-yum install rubygem-hammer_cli
+yum install tfm-rubygem-hammer_cli
 ```
 
 #### Step 3: install plugins
@@ -41,13 +41,13 @@ Currently, there are two plugins, both available as rpm packages.
  - commands for managing foreman
 
 ```bash
-yum install rubygem-hammer_cli_foreman
+yum install tfm-rubygem-hammer_cli_foreman
 ```
 
  - commands for managing [katello](https://github.com/Katello/katello)
 
 ```bash
-yum install rubygem-hammer_cli_katello
+yum install tfm-rubygem-hammer_cli_katello
 ```
 
 To install any other hammer plugin just make sure the appropriate gem is installed and follow with the [configuration](installation.md#configuration).

data/doc/release_notes.md

@@ -1,8 +1,16 @@
 Release notes
 =============
-### 0.15.1 (2018-11-06)
+### 0.16.0 (2019-01-16)
+* Fixed instructions in i18n docs ([#25724](http://projects.theforeman.org/issues/25724))
+* Option validators can be mixed with sources ([#22253](http://projects.theforeman.org/issues/22253))
+* Validator uses options from option collector ([#19574](http://projects.theforeman.org/issues/19574))
+* Hammer -h does work with --output json, csv, yaml ([#25438](http://projects.theforeman.org/issues/25438))
+* Update rpm names to use tfm ([PR #296](https://github.com/theforeman/hammer-cli/pull/296))
+* Allows modification of output fields ([PR #275](https://github.com/theforeman/hammer-cli/pull/275)) ([#21634](http://projects.theforeman.org/issues/21634))
+* Allow skipping message tests ([PR #292](https://github.com/theforeman/hammer-cli/pull/292)) ([#7451](http://projects.theforeman.org/issues/7451))
 * Helper for editing text in editor ([PR #294](https://github.com/theforeman/hammer-cli/pull/294)) ([#24489](http://projects.theforeman.org/issues/24489))
 * Add ability to disable defaults ([PR #293](https://github.com/theforeman/hammer-cli/pull/293)) ([#25307](http://projects.theforeman.org/issues/25307))
+* Allow modification of additional help texts ([PR #277](https://github.com/theforeman/hammer-cli/pull/277)) ([#21633](http://projects.theforeman.org/issues/21633))
 
 ### 0.15.0 (2018-10-24)
 * Correct the gemspec ([PR #286](https://github.com/theforeman/hammer-cli/pull/286))

data/lib/hammer_cli.rb

@@ -9,7 +9,6 @@ require 'hammer_cli/settings'
 require 'hammer_cli/logger'
 require 'hammer_cli/ca_cert_manager'
 require 'hammer_cli/connection'
-require 'hammer_cli/validator'
 require 'hammer_cli/output'
 require 'hammer_cli/options/normalizers'
 require 'hammer_cli/completer'

data/lib/hammer_cli/abstract.rb

@@ -2,14 +2,17 @@ require 'hammer_cli/exception_handler'
 require 'hammer_cli/logger_watch'
 require 'hammer_cli/options/option_definition'
 require 'hammer_cli/options/option_collector'
+require 'hammer_cli/options/processor_list'
 require 'hammer_cli/options/sources/command_line'
 require 'hammer_cli/options/sources/saved_defaults'
+require 'hammer_cli/options/validators/dsl_block_validator'
 require 'hammer_cli/clamp'
 require 'hammer_cli/subcommand'
 require 'hammer_cli/options/matcher'
 require 'hammer_cli/help/builder'
 require 'hammer_cli/help/text_builder'
 require 'logging'
+
 module HammerCLI
 
   class AbstractCommand < Clamp::Command
@@ -17,6 +20,10 @@ module HammerCLI
 
     class << self
       attr_accessor :validation_blocks
+
+      def help_extension_blocks
+        @help_extension_blocks ||= []
+      end
     end
 
     def adapter
@@ -40,7 +47,7 @@ module HammerCLI
       super
       validate_options
       logger.info "Called with options: %s" % options.inspect
-    rescue HammerCLI::Validator::ValidationError => e
+    rescue HammerCLI::Options::Validators::ValidationError => e
       signal_usage_error e.message
     end
 
@@ -48,15 +55,14 @@ module HammerCLI
       HammerCLI::EX_OK
     end
 
-    def self.validate_options(&block)
+    def self.validate_options(mode=:append, target_name=nil, validator: nil, &block)
+      validator ||= HammerCLI::Options::Validators::DSLBlockValidator.new(&block)
       self.validation_blocks ||= []
-      self.validation_blocks << block
+      self.validation_blocks << [mode, target_name, validator]
     end
 
     def validate_options
-      if self.class.validation_blocks && self.class.validation_blocks.any?
-        self.class.validation_blocks.each { |validation_block| validator.run(&validation_block) }
-      end
+      # keep the method for legacy reasons
     end
 
     def exception_handler
@@ -80,9 +86,16 @@ module HammerCLI
     def self.help(invocation_path, builder = HammerCLI::Help::Builder.new)
       super(invocation_path, builder)
 
-      if @help_extension_block
+      unless help_extension_blocks.empty?
         help_extension = HammerCLI::Help::TextBuilder.new(builder.richtext)
-        @help_extension_block.call(help_extension)
+        help_extension_blocks.each do |extension_block|
+          begin
+            extension_block.call(help_extension)
+          rescue ArgumentError => e
+            handler = HammerCLI::ExceptionHandler.new
+            handler.handle_exception(e)
+          end
+        end
         builder.add_text(help_extension.string)
       end
       builder.string
@@ -90,7 +103,14 @@ module HammerCLI
 
     def self.extend_help(&block)
       # We save the block for execution on object level, where we can access command's context and check :is_tty? flag
-      @help_extension_block = block
+      self.help_extension_blocks << block
+    end
+
+    def self.extend_output_definition(&block)
+      block.call(output_definition)
+    rescue ArgumentError => e
+      handler = HammerCLI::ExceptionHandler.new
+      handler.handle_exception(e)
     end
 
     def self.output(definition=nil, &block)
@@ -180,8 +200,8 @@ module HammerCLI
     end
 
     def validator
-      options = self.class.recognised_options.collect{|opt| opt.of(self)}
-      @validator ||= HammerCLI::Validator.new(options)
+      # keep the method for legacy reasons, it's used by validate_options
+      @validator ||= HammerCLI::Options::Validators::DSL.new(self.class.recognised_options, all_options)
     end
 
     def handle_exception(e)
@@ -240,13 +260,24 @@ module HammerCLI
     end
 
     def option_collector
-      @option_collector ||= HammerCLI::Options::OptionCollector.new(self.class.recognised_options, option_sources)
+      @option_collector ||= HammerCLI::Options::OptionCollector.new(self.class.recognised_options, add_validators(option_sources))
     end
 
 
     def option_sources
-      sources = [HammerCLI::Options::Sources::CommandLine.new(self)]
+      sources = HammerCLI::Options::ProcessorList.new(name: 'DefaultInputs')
+      sources << HammerCLI::Options::Sources::CommandLine.new(self)
       sources << HammerCLI::Options::Sources::SavedDefaults.new(context[:defaults], logger) if context[:use_defaults]
+
+      HammerCLI::Options::ProcessorList.new([sources])
+    end
+
+    def add_validators(sources)
+      if self.class.validation_blocks
+        self.class.validation_blocks.each do |validation_block|
+          sources.insert_relative(*validation_block)
+        end
+      end
       sources
     end