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"

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.



56
57
58
59
60
61
 
# File 'lib/toys/utils/help_text.rb', line 56

def initialize(tool, loader, executable_name, delegates: [])
  @tool = tool
  @loader = loader
  @executable_name = executable_name
  @delegates = delegates
end

Instance Attribute Details

#tool ⇒ Toys::ToolDefinition (readonly)

The ToolDefinition being documented.

Returns:



67
68
69
 
# File 'lib/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:



34
35
36
37
38
39
40
41
42
 
# File 'lib/toys/utils/help_text.rb', line 34

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



120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/toys/utils/help_text.rb', line 120

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.



152
153
154
155
156
157
158
159
 
# File 'lib/toys/utils/help_text.rb', line 152

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.



86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/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)
  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