Feature: free form --help text

lib/dry/cli/banner.rb

@@ -24,7 +24,8 @@ def self.call(command, name)
  command_subcommands(command),
  command_arguments(command),
  command_options(command),
- command_examples(command, name)
+ command_examples(command, name),
+ command_help(command)
  ].compact.join("\n")
  end
 
@@ -52,6 +53,14 @@ def self.command_examples(command, name)
  "\nExamples:\n#{command.examples.map { |example| " #{name} #{example}" }.join("\n")}"
  end
 
+ # @since 0.8.0
+ # @api private
+ def self.command_help(command)
+ return if command.help.nil?
+
+ "\n#{command.help.()}"
+ end
+
  # @since 0.1.0
  # @api private
  def self.command_description(command)

lib/dry/cli/command.rb

@@ -16,6 +16,7 @@ def self.inherited(base)
  base.class_eval do
  @_mutex = Mutex.new
  @description = nil
+ @help = nil
  @examples = []
  @subcommands = []
  @arguments = base.superclass_arguments || []
@@ -108,6 +109,46 @@ def self.example(*examples)
  @examples += examples.flatten(1)
  end
 
+ # Add extra free text when `--help` flag is used.
+ #
+ # @param blk [Proc] a block that must return a free form string to add
+ # extra information
+ #
+ # @since 0.8.0
+ #
+ # @example
+ # require "dry/cli"
+ #
+ # class Convert < Dry::CLI::Command
+ # help do
+ # require "tzinfo"
+ #
+ # "Available timezones:\n\n" +
+ # TZInfo::Timezone.all_identifiers.map { |i| "\t#{i}\n" }.join
+ # end
+ #
+ # def call(*)
+ # # ...
+ # end
+ # end
+ #
+ # # $ time convert --help
+ # # # ...
+ # #
+ # # Available timezones:
+ # #
+ # # Africa/Adibdjan
+ # # Africa/Accra
+ # # ...
+ # # Zulu
+ def self.help(&blk)
+ if blk
+ @help = blk
+ else
+ @help
+ end
+ end
+
  # Specify an argument
  #
  # @param name [Symbol] the argument name
@@ -375,6 +416,7 @@ def self.superclass_options
  delegate %i[
  description
  examples
+ help
  arguments
  options
  params