Class: HighLine
- Inherits:
-
Object
- Object
- HighLine
- Defined in:
- lib/highline.rb,
lib/highline/question.rb
Overview
A HighLine object is a “high-level line oriented” shell over an input and an output stream. HighLine simplifies common console interaction, effectively replacing puts() and gets(). User code can simply specify the question to ask and any details about user interaction, then leave the rest of the work to HighLine. When HighLine.ask() returns, you’ll have to answer you requested, even if HighLine had to ask many times, validate results, perform range checking, convert types, etc.
Defined Under Namespace
Classes: Question, QuestionError
Constant Summary collapse
- CLEAR =
Embed in a String to clear all previous ANSI sequences. This MUST be done before the program exits!
"\e[0m"
- RESET =
An alias for CLEAR.
CLEAR
- BOLD =
The start of an ANSI bold sequence.
"\e[1m"
- DARK =
The start of an ANSI dark sequence. (Terminal support uncommon.)
"\e[2m"
- UNDERLINE =
The start of an ANSI underline sequence.
"\e[4m"
- UNDERSCORE =
An alias for UNDERLINE.
UNDERLINE
- BLINK =
The start of an ANSI blink sequence. (Terminal support uncommon.)
"\e[5m"
- REVERSE =
The start of an ANSI reverse sequence.
"\e[7m"
- CONCEALED =
The start of an ANSI concealed sequence. (Terminal support uncommon.)
"\e[8m"
- BLACK =
Set the terminal’s foreground ANSI color to black.
"\e[30m"
- RED =
Set the terminal’s foreground ANSI color to red.
"\e[31m"
- GREEN =
Set the terminal’s foreground ANSI color to green.
"\e[32m"
- YELLOW =
Set the terminal’s foreground ANSI color to yellow.
"\e[33m"
- BLUE =
Set the terminal’s foreground ANSI color to blue.
"\e[34m"
- MAGENTA =
Set the terminal’s foreground ANSI color to magenta.
"\e[35m"
- CYAN =
Set the terminal’s foreground ANSI color to cyan.
"\e[36m"
- WHITE =
Set the terminal’s foreground ANSI color to white.
"\e[37m"
- ON_BLACK =
Set the terminal’s background ANSI color to black.
"\e[40m"
- ON_RED =
Set the terminal’s background ANSI color to red.
"\e[41m"
- ON_GREEN =
Set the terminal’s background ANSI color to green.
"\e[42m"
- ON_YELLOW =
Set the terminal’s background ANSI color to yellow.
"\e[43m"
- ON_BLUE =
Set the terminal’s background ANSI color to blue.
"\e[44m"
- ON_MAGENTA =
Set the terminal’s background ANSI color to magenta.
"\e[45m"
- ON_CYAN =
Set the terminal’s background ANSI color to cyan.
"\e[46m"
- ON_WHITE =
Set the terminal’s background ANSI color to white.
"\e[47m"
Instance Attribute Summary collapse
-
#page_at ⇒ Object
Set to an integer value to cause HighLine to page output lines over the indicated line limit.
-
#wrap_at ⇒ Object
Set to an integer value to cause HighLine to wrap output lines at the indicated character limit.
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(question, answer_type = String, &details) ⇒ Object
This method is the primary interface for user input.
-
#color(string, *colors) ⇒ Object
This method provides easy access to ANSI color sequences, without the user needing to remember to CLEAR at the end of each sequence.
-
#initialize(input = $stdin, output = $stdout, wrap_at = nil, page_at = nil) ⇒ HighLine
constructor
Create an instance of HighLine, connected to the streams input and output.
-
#say(statement) ⇒ Object
The basic output method for HighLine objects.
Constructor Details
#initialize(input = $stdin, output = $stdout, wrap_at = nil, page_at = nil) ⇒ HighLine
Create an instance of HighLine, connected to the streams input and output.
88 89 90 91 92 93 94 |
# File 'lib/highline.rb', line 88 def initialize( input = $stdin, output = $stdout, wrap_at = nil, page_at = nil ) @input = input @output = output @wrap_at = wrap_at @page_at = page_at end |
Instance Attribute Details
#page_at ⇒ Object
Set to an integer value to cause HighLine to page output lines over the indicated line limit. When nil
, the default, no paging occurs.
105 106 107 |
# File 'lib/highline.rb', line 105 def page_at @page_at end |
#wrap_at ⇒ Object
Set to an integer value to cause HighLine to wrap output lines at the indicated character limit. When nil
, the default, no wrapping occurs.
100 101 102 |
# File 'lib/highline.rb', line 100 def wrap_at @wrap_at 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.
113 114 115 116 117 118 119 120 |
# File 'lib/highline.rb', line 113 def agree( yes_or_no_question, character = nil ) ask(yes_or_no_question, lambda { |yn| yn.downcase[0] == ?y}) do |q| q.validate = /\Ay(?:es)?|no?\Z/i q.responses[:not_valid] = 'Please enter "yes" or "no".' q.responses[:ask_on_error] = :question q.character = character end end |
#ask(question, answer_type = String, &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 HighLine.say() for details on the format of question, and HighLine::Question for more information about answer_type and what’s valid in the code block.
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 |
# File 'lib/highline.rb', line 130 def ask( question, answer_type = String, &details ) # :yields: question @question = Question.new(question, answer_type, &details) say(@question) begin answer = @question.answer_or_default(get_response ) unless @question.valid_answer?(answer) explain_error(:not_valid) raise QuestionError end answer = @question.convert(answer) if @question.in_range?(answer) answer else explain_error(:not_in_range) raise QuestionError end rescue QuestionError retry rescue ArgumentError explain_error(:invalid_type) retry rescue NameError raise if $!.is_a?(NoMethodError) explain_error(:ambiguous_completion) retry end end |
#color(string, *colors) ⇒ Object
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.
169 170 171 172 173 174 175 176 177 178 |
# File 'lib/highline.rb', line 169 def color( string, *colors ) colors.map! do |c| if c.is_a?(Symbol) self.class.const_get(c.to_s.upcase) else c end end "#{colors.join}#{string}#{CLEAR}" 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 parameter is processed as an ERb template, supporting embedded Ruby code. The template is evaluated with a binding inside the HighLine instance, providing easy access to the ANSI color constants and the HighLine.color() method.
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 |
# File 'lib/highline.rb', line 190 def say( statement ) statement = statement.to_s return unless statement.length > 0 template = ERB.new(statement, nil, "%") statement = template.result(binding) statement = wrap(statement) unless @wrap_at.nil? statement = page_print(statement) unless @page_at.nil? if statement[-1, 1] == " " or statement[-1, 1] == "\t" @output.print(statement) @output.flush else @output.puts(statement) end end |