Class: Toys::Utils::HelpText

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/utils/help_text.rb

Overview

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". If nil, defaults to a placeholder.

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

    The delegation path to the tool.



65
66
67
68
69
70
 
# File 'lib/toys/utils/help_text.rb', line 65

def initialize(tool, loader, executable_name, delegates: [])
  @tool = tool
  @loader = loader
  @executable_name = executable_name || "(binary-name)"
  @delegates = delegates
end

Instance Attribute Details

#tool ⇒ Toys::ToolDefinition (readonly)

The ToolDefinition being documented.

Returns:



76
77
78
 
# File 'lib/toys/utils/help_text.rb', line 76

def tool
  @tool
end

Class Method Details

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

Create a usage helper given an execution context.

Parameters:

Returns:



41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/toys/utils/help_text.rb', line 41

def self.from_context(context)
  delegates = []
  cur = context
  while (cur = cur[Context::Key::DELEGATED_FROM])
    delegates << cur[Context::Key::TOOL]
  end
  new(context[Context::Key::TOOL],
      context[Context::Key::LOADER],
      context[Context::Key::EXECUTABLE_NAME],
      delegates: delegates)
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.



129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/toys/utils/help_text.rb', line 129

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)
  indent ||= DEFAULT_INDENT
  indent2 ||= DEFAULT_INDENT
  subtools = collect_subtool_info(recursive, search, include_hidden, separate_sources)
  assembler = HelpStringAssembler.new(
    @tool, @executable_name, @delegates, subtools, search,
    show_source_path, separate_sources,
    indent, indent2, wrap_width, styled
  )
  assembler.result
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.



161
162
163
164
165
166
167
168
 
# File 'lib/toys/utils/help_text.rb', line 161

def list_string(recursive: false, search: nil, include_hidden: false,
                separate_sources: false, indent: nil, wrap_width: nil, styled: true)
  indent ||= DEFAULT_INDENT
  subtools = collect_subtool_info(recursive, search, include_hidden, separate_sources)
  assembler = ListStringAssembler.new(@tool, subtools, recursive, search, separate_sources,
                                      indent, wrap_width, styled)
  assembler.result
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.



95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/toys/utils/help_text.rb', line 95

def usage_string(recursive: false, include_hidden: false, separate_sources: false,
                 left_column_width: nil, indent: nil, wrap_width: nil)
  left_column_width ||= DEFAULT_LEFT_COLUMN_WIDTH
  indent ||= DEFAULT_INDENT
  subtools = collect_subtool_info(recursive, nil, include_hidden, separate_sources)
  assembler = UsageStringAssembler.new(
    @tool, @executable_name, subtools, separate_sources,
    indent, left_column_width, wrap_width
  )
  assembler.result
end