Class: Toys::StandardMiddleware::ShowHelp

Inherits:

Object

• Object
• Toys::StandardMiddleware::ShowHelp

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

DEFAULT_HELP_FLAGS =

Default help flags

Returns:

• (Array<String>)

["-?", "--help"].freeze

DEFAULT_USAGE_FLAGS =

Default usage flags

Returns:

• (Array<String>)

["--usage"].freeze

DEFAULT_LIST_FLAGS =

Default list subtools flags

Returns:

• (Array<String>)

["--tools"].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

DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS =

Default show-all-subtools flags

Returns:

• (Array<String>)

["--all"].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

SHOW_LIST_KEY =

Key set when the show subtool list 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

SHOW_ALL_SUBTOOLS_KEY =

Key for the show-all-subtools setting

Returns:

• (Object)

Object.new.freeze

TOOL_NAME_KEY =

Key for the tool name

Returns:

• (Object)

Object.new.freeze

Instance Method Summary

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

  Create a ShowHelp middleware.

Methods included from Middleware

resolve_specs, spec, spec_from_array

Constructor Details

#initialize(help_flags: false, usage_flags: false, list_flags: false, recursive_flags: false, search_flags: false, show_all_subtools_flags: false, default_recursive: false, default_show_all_subtools: 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.
• list_flags (Boolean, Array<String>, Proc) (defaults to: false) —

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

  • An array of flags.
  • The true value to use DEFAULT_LIST_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.
• show_all_subtools_flags (Boolean, Array<String>, Proc) (defaults to: false) —

  Specify flags to show all subtools, including hidden tools and non-runnable namespaces. The value may be any of the following:

  • An array of flags.
  • The true value to use DEFAULT_SHOW_ALL_SUBTOOLS_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.

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

  Whether to show all 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.

# File 'lib/toys/standard_middleware/show_help.rb', line 192

def initialize(help_flags: false,
               usage_flags: false,
               list_flags: false,
               recursive_flags: false,
               search_flags: false,
               show_all_subtools_flags: false,
               default_recursive: false,
               default_show_all_subtools: 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
  @list_flags = list_flags
  @recursive_flags = recursive_flags
  @search_flags = search_flags
  @show_all_subtools_flags = show_all_subtools_flags
  @default_recursive = default_recursive ? true : false
  @default_show_all_subtools = default_show_all_subtools ? 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 && !Compat.jruby?
end