Class: Toys::StandardMiddleware::ShowHelp

Inherits:
Object
  • Object
show all
Includes:
Middleware
Defined in:
lib/toys/standard_middleware/show_help.rb

Overview

A middleware that shows help text for the tool when a flag (typically --help) is provided. It can also be configured to show help by default if the tool is a namespace that is not runnable.

If a tool is not runnable, this middleware can also add a --[no-]recursive flag, which, when set to true (the default), shows all subtools recursively rather than only immediate subtools. This middleware can also search for keywords in its subtools.

Constant Summary collapse

DEFAULT_HELP_FLAGS =

Default help flags

Returns:

  • (Array<String>) 
["-?", "--help"].freeze
DEFAULT_USAGE_FLAGS =

Default usage flags

Returns:

  • (Array<String>) 
["--usage"].freeze
DEFAULT_RECURSIVE_FLAGS =

Default recursive flags

Returns:

  • (Array<String>) 
["-r", "--[no-]recursive"].freeze
DEFAULT_SEARCH_FLAGS =

Default search flags

Returns:

  • (Array<String>) 
["-s WORD", "--search=WORD"].freeze
SHOW_HELP_KEY =

Key set when the show help flag is present

Returns:

  • (Object) 
Object.new.freeze
SHOW_USAGE_KEY =

Key set when the show usage flag is present

Returns:

  • (Object) 
Object.new.freeze
RECURSIVE_SUBTOOLS_KEY =

Key for the recursive setting

Returns:

  • (Object) 
Object.new.freeze
SEARCH_STRING_KEY =

Key for the search string

Returns:

  • (Object) 
Object.new.freeze
TOOL_NAME_KEY =

Key for the tool name

Returns:

  • (Object) 
Object.new.freeze

Instance Method Summary collapse

Constructor Details

#initialize(help_flags: false, usage_flags: false, recursive_flags: false, search_flags: false, default_recursive: false, fallback_execution: false, allow_root_args: false, show_source_path: false, use_less: false, stream: $stdout, styled_output: nil) ⇒ ShowHelp

Create a ShowHelp middleware.

Parameters:

  • help_flags (Boolean, Array<String>, Proc) (defaults to: false) —

    Specify flags to display help. The value may be any of the following:

    • An array of flags.
    • The true value to use DEFAULT_HELP_FLAGS.
    • The false value for no flags. (Default)
    • A proc that takes a tool and returns any of the above.
  • usage_flags (Boolean, Array<String>, Proc) (defaults to: false) —

    Specify flags to display usage. The value may be any of the following:

    • An array of flags.
    • The true value to use DEFAULT_USAGE_FLAGS.
    • The false value for no flags. (Default)
    • A proc that takes a tool and returns any of the above.
  • recursive_flags (Boolean, Array<String>, Proc) (defaults to: false) —

    Specify flags to control recursive subtool search. The value may be any of the following:

    • An array of flags.
    • The true value to use DEFAULT_RECURSIVE_FLAGS.
    • The false value for no flags. (Default)
    • A proc that takes a tool and returns any of the above.
  • search_flags (Boolean, Array<String>, Proc) (defaults to: false) —

    Specify flags to search subtools for a search term. The value may be any of the following:

    • An array of flags.
    • The true value to use DEFAULT_SEARCH_FLAGS.
    • The false value for no flags. (Default)
    • A proc that takes a tool and returns any of the above.
  • default_recursive (Boolean) (defaults to: false) —

    Whether to search recursively for subtools by default. Default is false.

  • fallback_execution (Boolean) (defaults to: false) —

    Cause the tool to display its own help text if it is not otherwise runnable. This is mostly useful for namespaces, which have children are not runnable. Default is false.

  • allow_root_args (Boolean) (defaults to: false) —

    If the root tool includes flags for help or usage, and doesn't otherwise use positional arguments, then a tool name can be passed as arguments to display help for that tool.

  • show_source_path (Boolean) (defaults to: false) —

    Show the source path section. Default is false.

  • use_less (Boolean) (defaults to: false) —

    If the less tool is available, and the output stream is a tty, then use less to display help text.

  • stream (IO) (defaults to: $stdout) —

    Output stream to write to. Default is stdout.

  • styled_output (Boolean, nil) (defaults to: nil) —

    Cause the tool to display help text with ansi styles. If nil, display styles if the output stream is a tty. Default is nil.



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/toys/standard_middleware/show_help.rb', line 157

def initialize(help_flags: false,
               usage_flags: false,
               recursive_flags: false,
               search_flags: false,
               default_recursive: false,
               fallback_execution: false,
               allow_root_args: false,
               show_source_path: false,
               use_less: false,
               stream: $stdout,
               styled_output: nil)
  @help_flags = help_flags
  @usage_flags = usage_flags
  @recursive_flags = recursive_flags
  @search_flags = search_flags
  @default_recursive = default_recursive ? true : false
  @fallback_execution = fallback_execution
  @allow_root_args = allow_root_args
  @show_source_path = show_source_path
  @stream = stream
  @styled_output = styled_output
  @use_less = use_less
end

Instance Method Details

#config(tool_definition, loader) ⇒ Object

Configure flags and default data.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/toys/standard_middleware/show_help.rb', line 184

def config(tool_definition, loader)
  unless tool_definition.argument_parsing_disabled?
    help_flags = add_help_flags(tool_definition)
    usage_flags = add_usage_flags(tool_definition)
    if @allow_root_args && (!help_flags.empty? || !usage_flags.empty?)
      if tool_definition.root? && tool_definition.arg_definitions.empty?
        tool_definition.set_remaining_args(TOOL_NAME_KEY,
                                           display_name: "TOOL_NAME",
                                           desc: "The tool for which to display help")
      end
    end
    if (!help_flags.empty? || @fallback_execution) &&
       loader.has_subtools?(tool_definition.full_name)
      add_recursive_flags(tool_definition)
      add_search_flags(tool_definition)
    end
  end
  yield
end

#run(tool) ⇒ Object

Display help text if requested.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/toys/standard_middleware/show_help.rb', line 207

def run(tool)
  if tool[SHOW_USAGE_KEY]
    help_text = get_help_text(tool)
    str = help_text.usage_string(wrap_width: terminal.width)
    terminal.puts(str)
  elsif @fallback_execution && !tool[Tool::Keys::TOOL_DEFINITION].runnable? ||
        tool[SHOW_HELP_KEY]
    help_text = get_help_text(tool)
    str = help_text.help_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
                                search: tool[SEARCH_STRING_KEY],
                                show_source_path: @show_source_path,
                                wrap_width: terminal.width)
    output_help(str)
  else
    yield
  end
end