Class: Toys::Utils::HelpText

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/utils/help_text.rb

Overview

Defined in the toys-core gem

A helper class that generates usage documentation for a tool.

This class generates full usage documentation, including description, flags, and arguments. It is used by middleware that implements help and related options.

This class is not loaded by default. Before using it directly, you should require "toys/utils/help_text"

Defined Under Namespace

Classes: HelpGenerationError

Constant Summary collapse

DEFAULT_LEFT_COLUMN_WIDTH =

Default width of first column

Returns:

  • (Integer) 
32
DEFAULT_INDENT =

Default indent

Returns:

  • (Integer) 
4

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(tool, loader, executable_name, delegates: []) ⇒ Toys::Utils::HelpText

Create a usage helper.

Parameters:

  • tool (Toys::ToolDefinition) —

    The tool to document.

  • loader (Toys::Loader) —

    A loader that can provide subcommands.

  • executable_name (String) —

    The name of the executable. e.g. "toys".

  • delegates (Array<Toys::ToolDefinition>) (defaults to: []) —

    The delegation path to the tool.



59
60
61
 
# File 'core-docs/toys/utils/help_text.rb', line 59

def initialize(tool, loader, executable_name, delegates: [])
  # Source available in the toys-core gem
end

Instance Attribute Details

#tool ⇒ Toys::ToolDefinition (readonly)

The ToolDefinition being documented.

Returns:



67
68
69
 
# File 'core-docs/toys/utils/help_text.rb', line 67

def tool
  @tool
end

Class Method Details

.from_context(context) ⇒ Toys::Utils::HelpText

Create a usage helper given an execution context.

Parameters:

Returns:



43
44
45
 
# File 'core-docs/toys/utils/help_text.rb', line 43

def self.from_context(context)
  # Source available in the toys-core gem
end

Instance Method Details

#help_string(recursive: false, search: nil, include_hidden: false, show_source_path: false, separate_sources: false, indent: nil, indent2: nil, wrap_width: nil, styled: true) ⇒ String

Generate a long help string.

Parameters:

  • recursive (boolean) (defaults to: false) —

    If true, and the tool is a namespace, display all subtools recursively. Defaults to false.

  • search (String, nil) (defaults to: nil) —

    An optional string to search for when listing subtools. Defaults to nil which finds all subtools.

  • include_hidden (boolean) (defaults to: false) —

    Include hidden subtools (i.e. whose names begin with underscore.) Default is false.

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

    If true, shows the source path section. Defaults to false.

  • separate_sources (boolean) (defaults to: false) —

    Split up tool list by source root. Defaults to false.

  • indent (Integer) (defaults to: nil) —

    Indent width. Default is DEFAULT_INDENT.

  • indent2 (Integer) (defaults to: nil) —

    Second indent width. Default is DEFAULT_INDENT.

  • wrap_width (Integer, nil) (defaults to: nil) —

    Wrap width of the column, or nil to disable wrap. Default is nil.

  • styled (boolean) (defaults to: true) —

    Output ansi styles. Default is true.

Returns:

  • (String) —

    A usage string.



113
114
115
116
117
 
# File 'core-docs/toys/utils/help_text.rb', line 113

def help_string(recursive: false, search: nil, include_hidden: false,
                show_source_path: false, separate_sources: false,
                indent: nil, indent2: nil, wrap_width: nil, styled: true)
  # Source available in the toys-core gem
end

#list_string(recursive: false, search: nil, include_hidden: false, separate_sources: false, indent: nil, wrap_width: nil, styled: true) ⇒ String

Generate a subtool list string.

Parameters:

  • recursive (boolean) (defaults to: false) —

    If true, and the tool is a namespace, display all subtools recursively. Defaults to false.

  • search (String, nil) (defaults to: nil) —

    An optional string to search for when listing subtools. Defaults to nil which finds all subtools.

  • include_hidden (boolean) (defaults to: false) —

    Include hidden subtools (i.e. whose names begin with underscore.) Default is false.

  • separate_sources (boolean) (defaults to: false) —

    Split up tool list by source root. Defaults to false.

  • indent (Integer) (defaults to: nil) —

    Indent width. Default is DEFAULT_INDENT.

  • wrap_width (Integer, nil) (defaults to: nil) —

    Wrap width of the column, or nil to disable wrap. Default is nil.

  • styled (boolean) (defaults to: true) —

    Output ansi styles. Default is true.

Returns:

  • (String) —

    A usage string.



137
138
139
140
 
# File 'core-docs/toys/utils/help_text.rb', line 137

def list_string(recursive: false, search: nil, include_hidden: false,
                separate_sources: false, indent: nil, wrap_width: nil, styled: true)
  # Source available in the toys-core gem
end

#usage_string(recursive: false, include_hidden: false, separate_sources: false, left_column_width: nil, indent: nil, wrap_width: nil) ⇒ String

Generate a short usage string.

Parameters:

  • recursive (boolean) (defaults to: false) —

    If true, and the tool is a namespace, display all subtools recursively. Defaults to false.

  • include_hidden (boolean) (defaults to: false) —

    Include hidden subtools (i.e. whose names begin with underscore.) Default is false.

  • separate_sources (boolean) (defaults to: false) —

    Split up tool list by source root. Defaults to false.

  • left_column_width (Integer) (defaults to: nil) —

    Width of the first column. Default is DEFAULT_LEFT_COLUMN_WIDTH.

  • indent (Integer) (defaults to: nil) —

    Indent width. Default is DEFAULT_INDENT.

  • wrap_width (Integer, nil) (defaults to: nil) —

    Overall width to wrap to. Default is nil indicating no wrapping.

Returns:

  • (String) —

    A usage string.



86
87
88
89
 
# File 'core-docs/toys/utils/help_text.rb', line 86

def usage_string(recursive: false, include_hidden: false, separate_sources: false,
                 left_column_width: nil, indent: nil, wrap_width: nil)
  # Source available in the toys-core gem
end