Class: HighLine
- Extended by:
- SingleForwardable
- Includes:
- BuiltinStyles, CustomErrors
- Defined in:
- lib/highline.rb,
lib/highline/list.rb,
lib/highline/menu.rb,
lib/highline/style.rb,
lib/highline/string.rb,
lib/highline/version.rb,
lib/highline/wrapper.rb,
lib/highline/question.rb,
lib/highline/simulate.rb,
lib/highline/terminal.rb,
lib/highline/menu/item.rb,
lib/highline/paginator.rb,
lib/highline/statement.rb,
lib/highline/color_scheme.rb,
lib/highline/custom_errors.rb,
lib/highline/list_renderer.rb,
lib/highline/builtin_styles.rb,
lib/highline/question_asker.rb,
lib/highline/terminal/ncurses.rb,
lib/highline/string_extensions.rb,
lib/highline/template_renderer.rb,
lib/highline/terminal/unix_stty.rb,
lib/highline/terminal/io_console.rb,
lib/highline/question/answer_converter.rb
Overview
:nodoc:
Defined Under Namespace
Modules: BuiltinStyles, CustomErrors, StringExtensions, Wrapper Classes: ColorScheme, List, ListRenderer, Menu, Paginator, Question, QuestionAsker, SampleColorScheme, Simulate, Statement, String, Style, TemplateRenderer, Terminal
Constant Summary collapse
- VERSION =
The version of the installed library.
"3.1.0".freeze
Constants included from BuiltinStyles
BuiltinStyles::BASIC_COLORS, BuiltinStyles::COLORS, BuiltinStyles::COLOR_LIST, BuiltinStyles::STYLES, BuiltinStyles::STYLE_LIST
Class Attribute Summary collapse
-
.color_scheme ⇒ Object
Pass ColorScheme to set a HighLine color scheme.
-
.default_instance ⇒ Object
Returns the value of attribute default_instance.
Instance Attribute Summary collapse
-
#indent_level ⇒ Integer
The indentation level.
-
#indent_size ⇒ Integer
The indentation size in characters.
-
#input ⇒ IO
readonly
The default input stream for a HighLine instance.
-
#key ⇒ Object
When gathering a Hash with QuestionAsker#gather_hash, it tracks the current key being asked.
-
#multi_indent ⇒ Boolean
Indentation over multiple lines.
-
#output ⇒ IO
readonly
The default output stream for a HighLine instance.
-
#page_at ⇒ Integer
The current row setting for paging output.
-
#terminal ⇒ HighLine::Terminal
readonly
System specific that responds to #initialize_system_extensions, #terminal_size, #raw_no_echo_mode, #restore_mode, #get_character.
-
#track_eof ⇒ Object
Pass
false
to turn off HighLine’s EOF tracking. -
#use_color ⇒ Object
Set it to false to disable ANSI coloring.
-
#wrap_at ⇒ Integer
The current column setting for wrapping output.
Class Method Summary collapse
-
.colorize_strings ⇒ Object
Adds color support to the base String class.
-
.find_or_create_style(arg) ⇒ Style
Search for a Style with the given properties and return it.
-
.find_or_create_style_list(*args) ⇒ Style
Find a Style list or create a new one.
-
.reset ⇒ Object
Reset HighLine to default.
-
.reset_color_scheme ⇒ Object
Reset color scheme to default (
nil
). -
.String(s) ⇒ HighLine::String
Returns a HighLine::String from any given String.
-
.Style(*args) ⇒ Style
Creates a style using HighLine.find_or_create_style or HighLine.find_or_create_style_list.
-
.supports_rgb_color? ⇒ Boolean
For checking if the current version of HighLine supports RGB colors Usage: HighLine.supports_rgb_color? rescue false using rescue for compatibility with older versions Note: color usage also depends on HighLine.use_color being set TODO: Discuss removing this method.
-
.using_color_scheme? ⇒ Boolean
Returns
true
if HighLine is currently using a color scheme.
Instance Method Summary collapse
-
#agree(yes_or_no_question, character = nil) ⇒ Object
A shortcut to HighLine.ask() a question that only accepts “yes” or “no” answers (“y” and “n” are allowed) and returns
true
orfalse
(true
for “yes”). -
#ask(template_or_question, answer_type = nil, &details) ⇒ Object
This method is the primary interface for user input.
-
#choose(*items, &details) ⇒ String
This method is HighLine’s menu handler.
-
#color(string, *colors) ⇒ String
This method provides easy access to ANSI color sequences, without the user needing to remember to CLEAR at the end of each sequence.
-
#color_code(*colors) ⇒ String
In case you just want the color code, without the embedding and the CLEAR sequence.
-
#get_response_character_mode(question) ⇒ String
Get response each character per turn.
-
#get_response_getc_mode(question) ⇒ String
Get response using #getc.
-
#get_response_line_mode(question) ⇒ String
Get response one line at time.
-
#indent(increase = 1, statement = nil, multiline = nil) ⇒ void
Executes block or outputs statement with indentation.
-
#indentation ⇒ Object
Outputs indentation with current settings.
-
#initialize(input = $stdin, output = $stdout, wrap_at = nil, page_at = nil, indent_size = 3, indent_level = 0) ⇒ HighLine
constructor
Create an instance of HighLine connected to the given input and output streams.
-
#list(items, mode = :rows, option = nil) ⇒ String
Renders a list of itens using a ListRenderer.
-
#new_scope ⇒ Object
Creates a new HighLine instance with the same options.
-
#newline ⇒ Object
Outputs newline.
-
#output_cols ⇒ Object
Returns the number of columns for the console, or a default it they cannot be determined.
-
#output_rows ⇒ Object
Returns the number of rows for the console, or a default if they cannot be determined.
-
#puts(*args) ⇒ Object
Call #puts on the HighLine’s output stream.
-
#render_and_ident_statement(statement) ⇒ String
Renders and indents a statement.
-
#render_statement(statement) ⇒ Statement
Renders a statement using Statement.
-
#reset_use_color ⇒ Object
Resets the use of color.
-
#say(statement) ⇒ Object
The basic output method for HighLine objects.
-
#shell_style_lambda(menu) ⇒ lambda
Convenience method to craft a lambda suitable for beind used in autocompletion operations by #choose.
-
#track_eof? ⇒ Boolean
Returns true if HighLine is currently tracking EOF for input.
-
#uncolor(string) ⇒ String
Remove color codes from a string.
-
#use_color? ⇒ Boolean
Returns truethy if HighLine instance is currently using color escapes.
Methods included from BuiltinStyles
Constructor Details
#initialize(input = $stdin, output = $stdout, wrap_at = nil, page_at = nil, indent_size = 3, indent_level = 0) ⇒ HighLine
Create an instance of HighLine connected to the given input and output streams.
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 |
# File 'lib/highline.rb', line 101 def initialize(input = $stdin, output = $stdout, wrap_at = nil, page_at = nil, indent_size = 3, indent_level = 0) @input = input @output = output @multi_indent = true @indent_size = indent_size @indent_level = indent_level self.wrap_at = wrap_at self.page_at = page_at @header = nil @prompt = nil @key = nil @use_color = default_use_color @track_eof = true # The setting used to disable EOF tracking. @terminal = HighLine::Terminal.get_terminal(input, output) end |
Class Attribute Details
.color_scheme ⇒ Object
Pass ColorScheme to set a HighLine color scheme.
57 58 59 |
# File 'lib/highline.rb', line 57 def color_scheme @color_scheme end |
.default_instance ⇒ Object
Returns the value of attribute default_instance.
54 55 56 |
# File 'lib/highline.rb', line 54 def default_instance @default_instance end |
Instance Attribute Details
#indent_level ⇒ Integer
Returns The indentation level.
157 158 159 |
# File 'lib/highline.rb', line 157 def indent_level @indent_level end |
#indent_size ⇒ Integer
Returns The indentation size in characters.
154 155 156 |
# File 'lib/highline.rb', line 154 def indent_size @indent_size end |
#input ⇒ IO (readonly)
Returns the default input stream for a HighLine instance.
160 161 162 |
# File 'lib/highline.rb', line 160 def input @input end |
#key ⇒ Object
We should probably move this into the HighLine::Question object.
When gathering a Hash with HighLine::QuestionAsker#gather_hash, it tracks the current key being asked.
170 171 172 |
# File 'lib/highline.rb', line 170 def key @key end |
#multi_indent ⇒ Boolean
Returns Indentation over multiple lines.
151 152 153 |
# File 'lib/highline.rb', line 151 def multi_indent @multi_indent end |
#output ⇒ IO (readonly)
Returns the default output stream for a HighLine instance.
163 164 165 |
# File 'lib/highline.rb', line 163 def output @output end |
#page_at ⇒ Integer
Returns The current row setting for paging output.
148 149 150 |
# File 'lib/highline.rb', line 148 def page_at @page_at end |
#terminal ⇒ HighLine::Terminal (readonly)
System specific that responds to #initialize_system_extensions, #terminal_size, #raw_no_echo_mode, #restore_mode, #get_character. It polymorphically handles specific cases for different platforms.
176 177 178 |
# File 'lib/highline.rb', line 176 def terminal @terminal end |
#track_eof ⇒ Object
Pass false
to turn off HighLine’s EOF tracking.
137 138 139 |
# File 'lib/highline.rb', line 137 def track_eof @track_eof end |
#use_color ⇒ Object
Set it to false to disable ANSI coloring
124 125 126 |
# File 'lib/highline.rb', line 124 def use_color @use_color end |
#wrap_at ⇒ Integer
Returns The current column setting for wrapping output.
145 146 147 |
# File 'lib/highline.rb', line 145 def wrap_at @wrap_at end |
Class Method Details
.colorize_strings ⇒ Object
Adds color support to the base String class
127 128 129 |
# File 'lib/highline/string_extensions.rb', line 127 def self.colorize_strings ::String.send(:include, StringExtensions) end |
.find_or_create_style(arg) ⇒ Style
Search for a Style with the given properties and return it. If there’s no matched Style, it creates one. You can pass a Style, String or a Hash.
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
# File 'lib/highline/style.rb', line 30 def self.find_or_create_style(arg) if arg.is_a?(Style) Style.list[arg.name] || Style.index(arg) elsif arg.is_a?(::String) && arg =~ /^\e\[/ # arg is a code styles = Style.code_index[arg] if styles styles.first else Style.new(code: arg) end elsif Style.list[arg] Style.list[arg] elsif HighLine.color_scheme && HighLine.color_scheme[arg] HighLine.color_scheme[arg] elsif arg.is_a?(Hash) Style.new(arg) elsif arg.to_s.downcase =~ /^rgb_([a-f0-9]{6})$/ Style.rgb(Regexp.last_match(1)) elsif arg.to_s.downcase =~ /^on_rgb_([a-f0-9]{6})$/ Style.rgb(Regexp.last_match(1)).on else raise NameError, "#{arg.inspect} is not a defined Style" end end |
.find_or_create_style_list(*args) ⇒ Style
Find a Style list or create a new one.
62 63 64 65 |
# File 'lib/highline/style.rb', line 62 def self.find_or_create_style_list(*args) name = args Style.list[name] || Style.new(list: args) end |
.reset ⇒ Object
Reset HighLine to default. Clears Style index and resets color_scheme and use_color settings.
71 72 73 74 75 |
# File 'lib/highline.rb', line 71 def reset Style.clear_index reset_color_scheme reset_use_color end |
.reset_color_scheme ⇒ Object
Reset color scheme to default (nil
)
65 66 67 |
# File 'lib/highline.rb', line 65 def reset_color_scheme self.color_scheme = nil end |
.String(s) ⇒ HighLine::String
Returns a HighLine::String from any given String.
7 8 9 |
# File 'lib/highline/string_extensions.rb', line 7 def self.String(s) # rubocop:disable Naming/MethodName HighLine::String.new(s) end |
.Style(*args) ⇒ Style
Creates a style using find_or_create_style or find_or_create_style_list
16 17 18 19 20 21 22 23 |
# File 'lib/highline/style.rb', line 16 def self.Style(*args) args = args.compact.flatten if args.size == 1 find_or_create_style(args.first) else find_or_create_style_list(*args) end end |
.supports_rgb_color? ⇒ Boolean
For checking if the current version of HighLine supports RGB colors Usage: HighLine.supports_rgb_color? rescue false
using rescue for compatibility with older versions
Note: color usage also depends on HighLine.use_color being set TODO: Discuss removing this method
82 83 84 |
# File 'lib/highline.rb', line 82 def supports_rgb_color? true end |
.using_color_scheme? ⇒ Boolean
Returns true
if HighLine is currently using a color scheme.
60 61 62 |
# File 'lib/highline.rb', line 60 def using_color_scheme? true if @color_scheme end |
Instance Method Details
#agree(yes_or_no_question, character = nil) ⇒ Object
A shortcut to HighLine.ask() a question that only accepts “yes” or “no” answers (“y” and “n” are allowed) and returns true
or false
(true
for “yes”). If provided a true
value, character will cause HighLine to fetch a single character response. A block can be provided to further configure the question as in HighLine.ask()
Raises EOFError if input is exhausted.
192 193 194 195 196 197 198 199 200 201 202 |
# File 'lib/highline.rb', line 192 def agree(yes_or_no_question, character = nil) ask(yes_or_no_question, ->(yn) { yn.downcase[0] == "y" }) do |q| q.validate = /\A(?:y(?:es)?|no?)\Z/i q.responses[:not_valid] = 'Please enter "yes" or "no".' q.responses[:ask_on_error] = :question q.character = character q.completion = %w[yes no] yield q if block_given? end end |
#ask(template_or_question, answer_type = nil, &details) ⇒ Object
This method is the primary interface for user input. Just provide a question to ask the user, the answer_type you want returned, and optionally a code block setting up details of how you want the question handled. See #say for details on the format of question, and Question for more information about answer_type and what’s valid in the code block.
Raises EOFError if input is exhausted.
216 217 218 219 220 221 222 223 224 |
# File 'lib/highline.rb', line 216 def ask(template_or_question, answer_type = nil, &details) question = Question.build(template_or_question, answer_type, &details) if question.gather QuestionAsker.new(question, self).gather_answers else QuestionAsker.new(question, self).ask_once end end |
#choose(*items, &details) ⇒ String
This method is HighLine’s menu handler. For simple usage, you can just pass all the menu items you wish to display. At that point, choose() will build and display a menu, walk the user through selection, and return their choice among the provided items. You might use this in a case statement for quick and dirty menus.
However, choose() is capable of much more. If provided, a block will be passed a HighLine::Menu object to configure. Using this method, you can customize all the details of menu handling from index display, to building a complete shell-like menuing system. See HighLine::Menu for all the methods it responds to.
Raises EOFError if input is exhausted.
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 |
# File 'lib/highline.rb', line 244 def choose(*items, &details) = Menu.new(&details) .choices(*items) unless items.empty? # Set auto-completion .completion = . # Set _answer_type_ so we can double as the Question for ask(). # menu.option = normal menu selection, by index or name .answer_type = .shell ? shell_style_lambda() : . selected = ask() return unless selected if .shell if .gather selection = [] details = [] selected.each do |value| selection << value[0] details << value[1] end else selection, details = selected end else selection = selected end if .gather .gather_selected(self, selection, details) else .select(self, selection, details) end end |
#color(string, *colors) ⇒ String
This method provides easy access to ANSI color sequences, without the user needing to remember to CLEAR at the end of each sequence. Just pass the string to color, followed by a list of colors you would like it to be affected by. The colors can be HighLine class constants, or symbols (:blue for BLUE, for example). A CLEAR will automatically be embedded to the end of the returned String.
This method returns the original string unchanged if use_color? is false
.
320 321 322 323 |
# File 'lib/highline.rb', line 320 def color(string, *colors) return string unless use_color? HighLine.Style(*colors).color(string) end |
#color_code(*colors) ⇒ String
In case you just want the color code, without the embedding and the CLEAR sequence.
340 341 342 |
# File 'lib/highline.rb', line 340 def color_code(*colors) HighLine.Style(*colors).code end |
#get_response_character_mode(question) ⇒ String
Get response each character per turn
620 621 622 623 624 625 626 627 628 629 630 631 |
# File 'lib/highline.rb', line 620 def get_response_character_mode(question) terminal.raw_no_echo_mode_exec do response = terminal.get_character if question.overwrite erase_current_line else echo = question.get_echo_for_response(response) say("#{echo}\n") end question.format_answer(response) end end |
#get_response_getc_mode(question) ⇒ String
Get response using #getc
610 611 612 613 614 615 |
# File 'lib/highline.rb', line 610 def get_response_getc_mode(question) terminal.raw_no_echo_mode_exec do response = @input.getc question.format_answer(response) end end |
#get_response_line_mode(question) ⇒ String
Get response one line at time
523 524 525 526 527 528 529 |
# File 'lib/highline.rb', line 523 def get_response_line_mode(question) if question.echo == true && !question.limit get_line(question) else get_line_raw_no_echo_mode(question) end end |
#indent(increase = 1, statement = nil, multiline = nil) ⇒ void
This method returns an undefined value.
Executes block or outputs statement with indentation
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 |
# File 'lib/highline.rb', line 440 def indent(increase = 1, statement = nil, multiline = nil) @indent_level += increase multi = @multi_indent @multi_indent ||= multiline begin if block_given? yield self else say(statement) end ensure @multi_indent = multi @indent_level -= increase end end |
#indentation ⇒ Object
Outputs indentation with current settings
428 429 430 |
# File 'lib/highline.rb', line 428 def indentation " " * @indent_size * @indent_level end |
#list(items, mode = :rows, option = nil) ⇒ String
Renders a list of itens using a ListRenderer
357 358 359 |
# File 'lib/highline.rb', line 357 def list(items, mode = :rows, option = nil) ListRenderer.new(items, mode, option, self).render end |
#new_scope ⇒ Object
Creates a new HighLine instance with the same options
494 495 496 497 |
# File 'lib/highline.rb', line 494 def new_scope self.class.new(@input, @output, @wrap_at, @page_at, @indent_size, @indent_level) end |
#newline ⇒ Object
Outputs newline
459 460 461 |
# File 'lib/highline.rb', line 459 def newline @output.puts end |
#output_cols ⇒ Object
Returns the number of columns for the console, or a default it they cannot be determined.
467 468 469 470 471 472 |
# File 'lib/highline.rb', line 467 def output_cols return 80 unless @output.tty? terminal.terminal_size.first rescue NoMethodError return 80 end |
#output_rows ⇒ Object
Returns the number of rows for the console, or a default if they cannot be determined.
478 479 480 481 482 483 |
# File 'lib/highline.rb', line 478 def output_rows return 24 unless @output.tty? terminal.terminal_size.last rescue NoMethodError return 24 end |
#puts(*args) ⇒ Object
Call #puts on the HighLine’s output stream
487 488 489 |
# File 'lib/highline.rb', line 487 def puts(*args) @output.puts(*args) end |
#render_and_ident_statement(statement) ⇒ String
Renders and indents a statement.
Note: extracted here to be used by readline to render its prompt.
392 393 394 395 396 |
# File 'lib/highline.rb', line 392 def render_and_ident_statement(statement) statement = render_statement(statement) statement = (indentation + statement) unless statement.empty? statement end |
#render_statement(statement) ⇒ Statement
Renders a statement using Statement
401 402 403 |
# File 'lib/highline.rb', line 401 def render_statement(statement) Statement.new(statement, self).to_s end |
#reset_use_color ⇒ Object
Resets the use of color.
132 133 134 |
# File 'lib/highline.rb', line 132 def reset_use_color @use_color = true end |
#say(statement) ⇒ Object
The basic output method for HighLine objects. If the provided statement ends with a space or tab character, a newline will not be appended (output will be flush()ed). All other cases are passed straight to Kernel.puts().
The statement argument is processed as an ERb template, supporting embedded Ruby code. The template is evaluated within a HighLine instance’s binding for providing easy access to the ANSI color constants and the HighLine#color() method.
372 373 374 375 376 377 378 379 380 381 382 383 384 |
# File 'lib/highline.rb', line 372 def say(statement) statement = render_and_ident_statement(statement) return statement if statement.empty? # Don't add a newline if statement ends with whitespace, OR # if statement ends with whitespace before a color escape code. if /[ \t](\e\[\d+(;\d+)*m)?\Z/ =~ statement output.print(statement) output.flush else output.puts(statement) end end |
#shell_style_lambda(menu) ⇒ lambda
Convenience method to craft a lambda suitable for beind used in autocompletion operations by #choose
284 285 286 287 288 289 290 291 292 293 294 295 296 |
# File 'lib/highline.rb', line 284 def shell_style_lambda() lambda do |command| # shell-style selection first_word = command.to_s.split.first || "" = . .extend(OptionParser::Completion) answer = .complete(first_word) raise Question::NoAutoCompleteMatch unless answer [answer.last, command.sub(/^\s*#{first_word}\s*/, "")] end end |
#track_eof? ⇒ Boolean
Returns true if HighLine is currently tracking EOF for input.
140 141 142 |
# File 'lib/highline.rb', line 140 def track_eof? true if track_eof end |
#uncolor(string) ⇒ String
Remove color codes from a string.
347 348 349 |
# File 'lib/highline.rb', line 347 def uncolor(string) Style.uncolor(string) end |
#use_color? ⇒ Boolean
Returns truethy if HighLine instance is currently using color escapes.
127 128 129 |
# File 'lib/highline.rb', line 127 def use_color? use_color end |