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, delegate_target: nil) ⇒ 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".

  • delegate_target (Array<String>, nil) (defaults to: nil) —

    The full name of a tool this tool will delegate to. Default is nil for no delegation.



78
79
80
81
82
83
 
# File 'lib/toys/utils/help_text.rb', line 78

def initialize(tool, loader, executable_name, delegate_target: nil)
  @tool = tool
  @loader = loader
  @executable_name = executable_name
  @delegate_target = delegate_target
end

Instance Attribute Details

#tool ⇒ Toys::Tool (readonly)

The Tool being documented.

Returns:



89
90
91
 
# File 'lib/toys/utils/help_text.rb', line 89

def tool
  @tool
end

Class Method Details

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

Create a usage helper given an execution context.

Parameters:

Returns:



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

def self.from_context(context)
  orig_context = context
  while (from = context[Context::Key::DELEGATED_FROM])
    context = from
  end
  delegate_target = orig_context == context ? nil : orig_context[Context::Key::TOOL_NAME]
  cli = context[Context::Key::CLI]
  new(context[Context::Key::TOOL], cli.loader, cli.executable_name,
      delegate_target: delegate_target)
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.



138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/toys/utils/help_text.rb', line 138

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



167
168
169
170
171
172
173
174
 
# File 'lib/toys/utils/help_text.rb', line 167

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.



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/toys/utils/help_text.rb', line 106

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, @delegate_target, subtools,
    indent, left_column_width, wrap_width
  )
  assembler.result
end