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::Tool) —

    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::Tool>) (defaults to: []) —

    The delegation path to the tool.



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

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

Instance Attribute Details

#tool ⇒ Toys::Tool (readonly)

The Tool being documented.

Returns:



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

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, 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.

  • 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.



114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/toys/utils/help_text.rb', line 114

def help_string(recursive: false, search: nil, include_hidden: false,
                show_source_path: false,
                indent: nil, indent2: nil, wrap_width: nil, styled: true)
  indent ||= DEFAULT_INDENT
  indent2 ||= DEFAULT_INDENT
  subtools = find_subtools(recursive, search, include_hidden)
  assembler = HelpStringAssembler.new(
    @tool, @executable_name, @delegates, subtools, search, show_source_path,
    indent, indent2, wrap_width, styled
  )
  assembler.result
end

#list_string(recursive: false, search: nil, include_hidden: 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.

  • 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.



143
144
145
146
147
148
149
150
 
# File 'lib/toys/utils/help_text.rb', line 143

def list_string(recursive: false, search: nil, include_hidden: false,
                indent: nil, wrap_width: nil, styled: true)
  indent ||= DEFAULT_INDENT
  subtools = find_subtools(recursive, search, include_hidden)
  assembler = ListStringAssembler.new(@tool, subtools, recursive, search,
                                      indent, wrap_width, styled)
  assembler.result
end

#usage_string(recursive: false, include_hidden: 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.

  • 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.



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/toys/utils/help_text.rb', line 83

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