Class: TTY::Option::Formatter Private

Inherits:
Object
  • Object
show all
Includes:
UsageWrapper
Defined in:
lib/tty/option/formatter.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Responsible for formatting help display

Constant Summary collapse

BOOLEANS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

[true, false].freeze
DEFAULT_WIDTH =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

80
DOUBLE_SPACE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

"  "
ELLIPSIS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

"..."
EMPTY =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

""
LIST_SEPARATOR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

", "
MAP_SEPARATOR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

":"
NEWLINE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

"\n"
SPACE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

" "
DEFAULT_NAME_SELECTOR =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

->(param) { param.name }
DEFAULT_ORDER =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

->(params) { params.sort }
DEFAULT_PARAM_DISPLAY =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

->(str) { str.to_s.upcase }
NOOP_PROC =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

->(param) { param }

Class Method Summary collapse

Instance Method Summary collapse

Methods included from UsageWrapper

wrap

Constructor Details

#initialize(parameters, usage, param_display: DEFAULT_PARAM_DISPLAY, width: DEFAULT_WIDTH, order: DEFAULT_ORDER, indent: 0) ⇒ Formatter

Create a Formatter instance

Parameters:

  • parameters (TTY::Option::Parameters) —

    the parameters to format

  • usage (TTY::Option::Usage) —

    the usage to format

  • param_display (Proc) (defaults to: DEFAULT_PARAM_DISPLAY) —

    the parameter display formatter, by default, uppercases all chars

  • width (Integer) (defaults to: DEFAULT_WIDTH) —

    the width at which to wrap the help display, by default 80 columns

  • order (Proc) (defaults to: DEFAULT_ORDER) —

    the order for displaying parameters, by default alphabetical

  • indent (Integer) (defaults to: 0) —

    the indent for help display



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/tty/option/formatter.rb', line 59

def initialize(parameters, usage, param_display: DEFAULT_PARAM_DISPLAY,
               width: DEFAULT_WIDTH, order: DEFAULT_ORDER, indent: 0)
  @parameters = parameters
  @usage = usage
  @param_display = param_display
  @order = order
  @width = width
  @indent = indent
  @space_indent = SPACE * indent
  @param_indent = indent + 2
  @section_names = {
    usage: "Usage:",
    arguments: "Arguments:",
    keywords: "Keywords:",
    options: "Options:",
    env: "Environment:",
    examples: "Examples:"
  }
end

Class Method Details

.help(parameters, usage, **config, &block) ⇒ String

Generate help for parameters and usage

Parameters:

Returns:

  • (String) 


39
40
41
 
# File 'lib/tty/option/formatter.rb', line 39

def self.help(parameters, usage, **config, &block)
  new(parameters, usage, **config).help(&block)
end

Instance Method Details

#help {|sections| ... } ⇒ String

Generate help display

Examples:

formatter.help

Yield Parameters:

Returns:

  • (String) 


89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/tty/option/formatter.rb', line 89

def help
  sections = Sections.new

  sections.add(:header, help_header) if @usage.header?
  sections.add(:banner, help_banner)
  sections.add(:description, help_description) if @usage.desc?

  if @parameters.arguments.any?(&:display?)
    sections.add(:arguments, help_arguments)
  end

  if @parameters.keywords.any?(&:display?)
    sections.add(:keywords, help_keywords)
  end

  if @parameters.options?
    sections.add(:options, help_options)
  end

  if @parameters.environments.any?(&:display?)
    sections.add(:environments, help_environments)
  end

  sections.add(:examples, help_examples) if @usage.example?
  sections.add(:footer, help_footer) if @usage.footer?

  yield(sections) if block_given?

  formatted = sections.reject(&:empty?).join(NEWLINE)
  formatted.end_with?(NEWLINE) ? formatted : formatted + NEWLINE
end

#help_arguments ⇒ String

Generate help arguments

Examples:

formatter.help_arguments

Returns:

  • (String) 


165
166
167
168
169
170
 
# File 'lib/tty/option/formatter.rb', line 165

def help_arguments
  "#{NEWLINE}#{@space_indent}#{@section_names[:arguments]}#{NEWLINE}" +
    format_section(@parameters.arguments, ->(param) do
      @param_display.(param.name)
    end)
end

#help_banner ⇒ String

Generate help banner

Examples:

formatter.help_banner

Returns:

  • (String) 


141
142
143
 
# File 'lib/tty/option/formatter.rb', line 141

def help_banner
  (@usage.banner? ? @usage.banner : format_usage)
end

#help_description ⇒ String

Generate help description

Examples:

formatter.help_description

Returns:

  • (String) 


153
154
155
 
# File 'lib/tty/option/formatter.rb', line 153

def help_description
  "#{NEWLINE}#{format_description}"
end

#help_environments ⇒ String

Generate help environment variables

Examples:

formatter.help_environments

Returns:

  • (String) 


208
209
210
211
 
# File 'lib/tty/option/formatter.rb', line 208

def help_environments
  "#{NEWLINE}#{@space_indent}#{@section_names[:env]}#{NEWLINE}" +
    format_section(@order.(@parameters.environments))
end

#help_examples ⇒ String

Generate help examples

Examples:

formatter.help_examples

Returns:

  • (String) 


221
222
223
224
 
# File 'lib/tty/option/formatter.rb', line 221

def help_examples
  "#{NEWLINE}#{@space_indent}#{@section_names[:examples]}#{NEWLINE}" +
    format_examples
end

#help_footer ⇒ String

Generate help footer

Examples:

formatter.help_footer

Returns:

  • (String) 


234
235
236
 
# File 'lib/tty/option/formatter.rb', line 234

def help_footer
  "#{NEWLINE}#{format_multiline(@usage.footer, @indent)}"
end

#help_header ⇒ String

Generate help header

Examples:

formatter.help_header

Returns:

  • (String) 


129
130
131
 
# File 'lib/tty/option/formatter.rb', line 129

def help_header
  "#{format_multiline(@usage.header, @indent)}#{NEWLINE}"
end

#help_keywords ⇒ String

Generate help keywords

Examples:

formatter.help_keywords

Returns:

  • (String) 


180
181
182
183
184
185
 
# File 'lib/tty/option/formatter.rb', line 180

def help_keywords
  "#{NEWLINE}#{@space_indent}#{@section_names[:keywords]}#{NEWLINE}" +
    format_section(@parameters.keywords, ->(param) do
      kwarg_param_display(param).split("=").map(&@param_display).join("=")
    end)
end

#help_options ⇒ String

Generate help options

Examples:

formatter.help_options

Returns:

  • (String) 


195
196
197
198
 
# File 'lib/tty/option/formatter.rb', line 195

def help_options
  "#{NEWLINE}#{@space_indent}#{@section_names[:options]}#{NEWLINE}" +
    format_options
end