Class: HighLine::Question
Overview
Question objects contain all the details of a single invocation of HighLine.ask(). The object is initialized by the parameters passed to HighLine.ask() and then queried to make sure each step of the input process is handled according to the users wishes.
Direct Known Subclasses
Defined Under Namespace
Classes: NoAutoCompleteMatch
Instance Attribute Summary collapse
-
#above ⇒ Object
Used to control range checks for answer.
-
#answer_type ⇒ Object
The type that will be used to convert this answer.
-
#below ⇒ Object
Used to control range checks for answer.
-
#case ⇒ Object
Used to control whitespace processing for the answer to this question.
-
#character ⇒ Object
Can be set to
true
to use HighLine’s cross-platform character reader instead of fetching an entire line of input. -
#confirm ⇒ Object
Asks a yes or no confirmation question, to ensure a user knows what they have just agreed to.
-
#default ⇒ Object
Used to provide a default answer to this question.
-
#directory ⇒ Object
The directory from which a user will be allowed to select files, when File or Pathname is specified as an answer_type.
-
#echo ⇒ Object
Can be set to
true
orfalse
to control whether or not input will be echoed back to the user. -
#first_answer ⇒ Object
Returns first_answer, which will be unset following this call.
-
#gather ⇒ Object
When set, the user will be prompted for multiple answers which will be collected into an Array or Hash and returned as the final answer.
-
#glob ⇒ Object
The glob pattern used to limit file selection when File or Pathname is specified as an answer_type.
-
#in ⇒ Object
If set, answer must pass an include?() check on this object.
-
#limit ⇒ Object
Allows you to set a character limit for input.
-
#question ⇒ Object
The ERb template of the question to be asked.
-
#readline ⇒ Object
Use the Readline library to fetch input.
-
#responses ⇒ Object
readonly
A Hash that stores the various responses used by HighLine to notify the user.
-
#validate ⇒ Object
If set to a Regexp, the answer must match (before type conversion).
-
#whitespace ⇒ Object
Used to control whitespace processing for the answer to this question.
Instance Method Summary collapse
-
#answer_or_default(answer_string) ⇒ Object
Returns the provided answer_string or the default answer for this Question if a default was set and the answer is empty.
-
#build_responses ⇒ Object
Called late in the initialization process to build intelligent responses based on the details of this Question object.
-
#change_case(answer_string) ⇒ Object
Returns the provided answer_string after changing character case by the rules of this Question.
-
#convert(answer_string) ⇒ Object
Transforms the given answer_string into the expected type for this Question.
-
#expected_range ⇒ Object
Returns a english explination of the current range settings.
-
#first_answer? ⇒ Boolean
Returns true if first_answer is set.
-
#in_range?(answer_object) ⇒ Boolean
Returns
true
if the answer_object is greater than the above attribute, less than the below attribute and included?()ed in the in attribute. -
#initialize(question, answer_type) {|_self| ... } ⇒ Question
constructor
Create an instance of HighLine::Question.
-
#remove_whitespace(answer_string) ⇒ Object
Returns the provided answer_string after processing whitespace by the rules of this Question.
-
#selection ⇒ Object
Returns an Array of valid answers to this question.
-
#to_str ⇒ Object
Stringifies the question to be asked.
-
#valid_answer?(answer_string) ⇒ Boolean
Returns
true
if the provided answer_string is accepted by the validate attribute orfalse
if it’s not.
Constructor Details
#initialize(question, answer_type) {|_self| ... } ⇒ Question
Create an instance of HighLine::Question. Expects a question to ask (can be ""
) and an answer_type to convert the answer to. The answer_type parameter must be a type recongnized by Question.convert(). If given, a block is yeilded the new Question object to allow custom initializaion.
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 |
# File 'lib/highline/question.rb', line 34 def initialize( question, answer_type ) # initialize instance data @question = question @answer_type = answer_type @character = nil @limit = nil @echo = true @readline = false @whitespace = :strip @case = nil @default = nil @validate = nil @above = nil @below = nil @in = nil @confirm = nil @gather = false @first_answer = nil @directory = Pathname.new(File.(File.dirname($0))) @glob = "*" @responses = Hash.new # allow block to override settings yield self if block_given? # finalize responses based on settings build_responses end |
Instance Attribute Details
#above ⇒ Object
Used to control range checks for answer.
123 124 125 |
# File 'lib/highline/question.rb', line 123 def above @above end |
#answer_type ⇒ Object
The type that will be used to convert this answer.
67 68 69 |
# File 'lib/highline/question.rb', line 67 def answer_type @answer_type end |
#below ⇒ Object
Used to control range checks for answer.
123 124 125 |
# File 'lib/highline/question.rb', line 123 def below @below end |
#case ⇒ Object
Used to control whitespace processing for the answer to this question. See HighLine::Question.change_case() for acceptable settings.
113 114 115 |
# File 'lib/highline/question.rb', line 113 def case @case end |
#character ⇒ Object
Can be set to true
to use HighLine’s cross-platform character reader instead of fetching an entire line of input. (Note: HighLine’s character reader ONLY supports STDIN on Windows and Unix.) Can also be set to :getc
to use that method on the input stream.
WARNING: The echo attribute for a question is ignored when using thw :getc
method.
77 78 79 |
# File 'lib/highline/question.rb', line 77 def character @character end |
#confirm ⇒ Object
Asks a yes or no confirmation question, to ensure a user knows what they have just agreed to. If set to true
the question will be, “Are you sure? ” Any other true value for this attribute is assumed to be the question to ask. When false
or nil
(the default), answers are not confirmed.
133 134 135 |
# File 'lib/highline/question.rb', line 133 def confirm @confirm end |
#default ⇒ Object
Used to provide a default answer to this question.
115 116 117 |
# File 'lib/highline/question.rb', line 115 def default @default end |
#directory ⇒ Object
The directory from which a user will be allowed to select files, when File or Pathname is specified as an answer_type. Initially set to Pathname.new(File.expand_path(File.dirname($0)))
.
160 161 162 |
# File 'lib/highline/question.rb', line 160 def directory @directory end |
#echo ⇒ Object
Can be set to true
or false
to control whether or not input will be echoed back to the user. A setting of true
will cause echo to match input, but any other true value will be treated as to String to echo for each character typed.
This requires HighLine’s character reader. See the character attribute for details.
93 94 95 |
# File 'lib/highline/question.rb', line 93 def echo @echo end |
#first_answer ⇒ Object
Returns first_answer, which will be unset following this call.
336 337 338 339 340 |
# File 'lib/highline/question.rb', line 336 def first_answer( ) @first_answer ensure @first_answer = nil end |
#gather ⇒ Object
When set, the user will be prompted for multiple answers which will be collected into an Array or Hash and returned as the final answer.
You can set gather to an Integer to have an Array of exactly that many answers collected, or a String/Regexp to match an end input which will not be returned in the Array.
Optionally gather can be set to a Hash. In this case, the question will be asked once for each key and the answers will be returned in a Hash, mapped by key. The @key
variable is set before each question is evaluated, so you can use it in your question.
147 148 149 |
# File 'lib/highline/question.rb', line 147 def gather @gather end |
#glob ⇒ Object
The glob pattern used to limit file selection when File or Pathname is specified as an answer_type. Initially set to "*"
.
165 166 167 |
# File 'lib/highline/question.rb', line 165 def glob @glob end |
#in ⇒ Object
If set, answer must pass an include?() check on this object.
125 126 127 |
# File 'lib/highline/question.rb', line 125 def in @in end |
#limit ⇒ Object
Allows you to set a character limit for input.
WARNING: This option forces a character by character read.
83 84 85 |
# File 'lib/highline/question.rb', line 83 def limit @limit end |
#question ⇒ Object
The ERb template of the question to be asked.
65 66 67 |
# File 'lib/highline/question.rb', line 65 def question @question end |
#readline ⇒ Object
Use the Readline library to fetch input. This allows input editing as well as keeping a history. In addition, tab will auto-complete within an Array of choices or a file listing.
WARNING: This option is incompatible with all of HighLine’s character reading modes and it causes HighLine to ignore the specified input stream.
103 104 105 |
# File 'lib/highline/question.rb', line 103 def readline @readline end |
#responses ⇒ Object (readonly)
A Hash that stores the various responses used by HighLine to notify the user. The currently used responses and their purpose are as follows:
:ambiguous_completion
-
Used to notify the user of an ambiguous answer the auto-completion system cannot resolve.
:ask_on_error
-
This is the question that will be redisplayed to the user in the event of an error. Can be set to
:question
to repeat the original question. :invalid_type
-
The error message shown when a type conversion fails.
:no_completion
-
Used to notify the user that their selection does not have a valid auto-completion match.
:not_in_range
-
Used to notify the user that a provided answer did not satisfy the range requirement tests.
:not_valid
-
The error message shown when validation checks fail.
190 191 192 |
# File 'lib/highline/question.rb', line 190 def responses @responses end |
#validate ⇒ Object
If set to a Regexp, the answer must match (before type conversion). Can also be set to a Proc which will be called with the provided answer to validate with a true
or false
return.
121 122 123 |
# File 'lib/highline/question.rb', line 121 def validate @validate end |
#whitespace ⇒ Object
Used to control whitespace processing for the answer to this question. See HighLine::Question.remove_whitespace() for acceptable settings.
108 109 110 |
# File 'lib/highline/question.rb', line 108 def whitespace @whitespace end |
Instance Method Details
#answer_or_default(answer_string) ⇒ Object
Returns the provided answer_string or the default answer for this Question if a default was set and the answer is empty.
196 197 198 199 200 201 202 |
# File 'lib/highline/question.rb', line 196 def answer_or_default( answer_string ) if answer_string.length == 0 and not @default.nil? @default else answer_string end end |
#build_responses ⇒ Object
Called late in the initialization process to build intelligent responses based on the details of this Question object.
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 |
# File 'lib/highline/question.rb', line 208 def build_responses( ) ### WARNING: This code is quasi-duplicated in ### ### Menu.update_responses(). Check there too when ### ### making changes! ### append_default unless default.nil? @responses = { :ambiguous_completion => "Ambiguous choice. " + "Please choose one of #{@answer_type.inspect}.", :ask_on_error => "? ", :invalid_type => "You must enter a valid #{@answer_type}.", :no_completion => "You must choose one of " + "#{@answer_type.inspect}.", :not_in_range => "Your answer isn't within the expected range " + "(#{expected_range}).", :not_valid => "Your answer isn't valid (must match " + "#{@validate.inspect})." }.merge(@responses) ### WARNING: This code is quasi-duplicated in ### ### Menu.update_responses(). Check there too when ### ### making changes! ### end |
#change_case(answer_string) ⇒ Object
Returns the provided answer_string after changing character case by the rules of this Question. Valid settings for whitespace are:
nil
-
Do not alter character case. (Default.)
:up
-
Calls upcase().
:upcase
-
Calls upcase().
:down
-
Calls downcase().
:downcase
-
Calls downcase().
:capitalize
-
Calls capitalize().
An unrecognized choice (like :none
) is treated as nil
.
248 249 250 251 252 253 254 255 256 257 258 |
# File 'lib/highline/question.rb', line 248 def change_case( answer_string ) if [:up, :upcase].include?(@case) answer_string.upcase elsif [:down, :downcase].include?(@case) answer_string.downcase elsif @case == :capitalize answer_string.capitalize else answer_string end end |
#convert(answer_string) ⇒ Object
Transforms the given answer_string into the expected type for this Question. Currently supported conversions are:
[...]
-
Answer must be a member of the passed Array. Auto-completion is used to expand partial answers.
lambda {...}
-
Answer is passed to lambda for conversion.
- Date
-
Date.parse() is called with answer.
- DateTime
-
DateTime.parse() is called with answer.
- File
-
The entered file name is auto-completed in terms of directory + glob, opened, and returned.
- Float
-
Answer is converted with Kernel.Float().
- Integer
-
Answer is converted with Kernel.Integer().
nil
-
Answer is left in String format. (Default.)
- Pathname
-
Same as File, save that a Pathname object is returned.
- String
-
Answer is converted with Kernel.String().
- Regexp
-
Answer is fed to Regexp.new().
- Symbol
-
The method to_sym() is called on answer and the result returned.
- any other Class
-
The answer is passed on to
Class.parse()
.
This method throws ArgumentError, if the conversion cannot be completed for any reason.
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 |
# File 'lib/highline/question.rb', line 288 def convert( answer_string ) if @answer_type.nil? answer_string elsif [Float, Integer, String].include?(@answer_type) Kernel.send(@answer_type.to_s.to_sym, answer_string) elsif @answer_type == Symbol answer_string.to_sym elsif @answer_type == Regexp Regexp.new(answer_string) elsif @answer_type.is_a?(Array) or [File, Pathname].include?(@answer_type) # cheating, using OptionParser's Completion module choices = selection choices.extend(OptionParser::Completion) answer = choices.complete(answer_string) if answer.nil? raise NoAutoCompleteMatch end if @answer_type.is_a?(Array) answer.last elsif @answer_type == File File.open(File.join(@directory.to_s, answer.last)) else Pathname.new(File.join(@directory.to_s, answer.last)) end elsif [Date, DateTime].include?(@answer_type) or @answer_type.is_a?(Class) @answer_type.parse(answer_string) elsif @answer_type.is_a?(Proc) @answer_type[answer_string] end end |
#expected_range ⇒ Object
Returns a english explination of the current range settings.
320 321 322 323 324 325 326 327 328 329 330 331 332 333 |
# File 'lib/highline/question.rb', line 320 def expected_range( ) expected = [ ] expected << "above #{@above}" unless @above.nil? expected << "below #{@below}" unless @below.nil? expected << "included in #{@in.inspect}" unless @in.nil? case expected.size when 0 then "" when 1 then expected.first when 2 then expected.join(" and ") else expected[0..-2].join(", ") + ", and #{expected.last}" end end |
#first_answer? ⇒ Boolean
Returns true if first_answer is set.
343 344 345 |
# File 'lib/highline/question.rb', line 343 def first_answer?( ) not @first_answer.nil? end |
#in_range?(answer_object) ⇒ Boolean
Returns true
if the answer_object is greater than the above attribute, less than the below attribute and included?()ed in the in attribute. Otherwise, false
is returned. Any nil
attributes are not checked.
353 354 355 356 357 |
# File 'lib/highline/question.rb', line 353 def in_range?( answer_object ) (@above.nil? or answer_object > @above) and (@below.nil? or answer_object < @below) and (@in.nil? or @in.include?(answer_object)) end |
#remove_whitespace(answer_string) ⇒ Object
Returns the provided answer_string after processing whitespace by the rules of this Question. Valid settings for whitespace are:
nil
-
Do not alter whitespace.
:strip
-
Calls strip(). (Default.)
:chomp
-
Calls chomp().
:collapse
-
Collapses all whitspace runs to a single space.
:strip_and_collapse
-
Calls strip(), then collapses all whitspace runs to a single space.
:chomp_and_collapse
-
Calls chomp(), then collapses all whitspace runs to a single space.
:remove
-
Removes all whitespace.
An unrecognized choice (like :none
) is treated as nil
.
This process is skipped, for single character input.
378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 |
# File 'lib/highline/question.rb', line 378 def remove_whitespace( answer_string ) if @whitespace.nil? answer_string elsif [:strip, :chomp].include?(@whitespace) answer_string.send(@whitespace) elsif @whitespace == :collapse answer_string.gsub(/\s+/, " ") elsif [:strip_and_collapse, :chomp_and_collapse].include?(@whitespace) result = answer_string.send(@whitespace.to_s[/^[a-z]+/]) result.gsub(/\s+/, " ") elsif @whitespace == :remove answer_string.gsub(/\s+/, "") else answer_string end end |
#selection ⇒ Object
Returns an Array of valid answers to this question. These answers are only known when answer_type is set to an Array of choices, File, or Pathname. Any other time, this method will return an empty Array.
400 401 402 403 404 405 406 407 408 409 410 |
# File 'lib/highline/question.rb', line 400 def selection( ) if @answer_type.is_a?(Array) @answer_type elsif [File, Pathname].include?(@answer_type) Dir[File.join(@directory.to_s, @glob)].map do |file| File.basename(file) end else [ ] end end |
#to_str ⇒ Object
Stringifies the question to be asked.
413 414 415 |
# File 'lib/highline/question.rb', line 413 def to_str( ) @question end |
#valid_answer?(answer_string) ⇒ Boolean
Returns true
if the provided answer_string is accepted by the validate attribute or false
if it’s not.
It’s important to realize that an answer is validated after whitespace and case handling.
424 425 426 427 428 |
# File 'lib/highline/question.rb', line 424 def valid_answer?( answer_string ) @validate.nil? or (@validate.is_a?(Regexp) and answer_string =~ @validate) or (@validate.is_a?(Proc) and @validate[answer_string]) end |