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.

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, binary_name) ⇒ Toys::Utils::HelpText

Create a usage helper.

Parameters:

  • tool (Toys::Tool) —

    The tool for which to generate documentation.

  • loader (Toys::Loader) —

    A loader that can provide subcommands.

  • binary_name (String) —

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



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

def initialize(tool, loader, binary_name)
  @tool = tool
  @loader = loader
  @binary_name = binary_name
end

Instance Attribute Details

#tool ⇒ Object (readonly)

Returns the value of attribute tool.



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

def tool
  @tool
end

Class Method Details

.from_tool(tool) ⇒ Toys::Utils::HelpText

Create a usage helper given an executable tool.

Parameters:

Returns:



60
61
62
63
 
# File 'lib/toys/utils/help_text.rb', line 60

def self.from_tool(tool)
  new(tool[Tool::Keys::TOOL_DEFINITION], tool[Tool::Keys::LOADER],
      tool[Tool::Keys::BINARY_NAME])
end

Instance Method Details

#help_string(recursive: false, search: nil, 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 subcommands recursively. Defaults to false.

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

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

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



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

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

#usage_string(recursive: 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 subcommands recursively. 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
 
# File 'lib/toys/utils/help_text.rb', line 95

def usage_string(recursive: 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)
  assembler = UsageStringAssembler.new(@tool, @binary_name, subtools,
                                       indent, left_column_width, wrap_width)
  assembler.result
end