Modify an existing help

Help items

Before modifying help, it’s good to know which help items are available to use. There is a list with currently available items:

Command.extend_help do |h|
  # Add a simple text to the help output.
  # content - String - text to be shown
  # options - Hash   - options (id:, richtext:)
  h.text(content, options = {})
  # Add a notification to the help output (LABEL: content).
  # content - String - text to be shown
  # options - Hash   - options (same as #text, label:)
  h.note(content, options = {})
  # Add a list of items to the help output.
  # items   - Array - array of items to be shown. Each item can be either string
  #                   or an array of ['Key', 'Value', bold: true/false].
  #                   Item options are optional.
  #   Example: h.list(['a', 'b', 'c']) => "a\n b\n c\n"
  #            h.list([['a', 'b', bold: true], ['c', 'd']]) => "a   b\nc   d\n"
  # options - Hash  - same as #text
  h.list(items, options = {})
  # Add a section to the help output.
  # label   - String - Section header
  # options - Hash   - same as #text
  # block   - block with section definition (may include lists/texts/etc.)
  h.section(label, options = {}) { |h| ... }
end

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.

Help modification

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

To modify the structure above, you might use the following:

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

# 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