class TTY::Prompt

A main entry for asking prompt questions.

A class responsible for shell prompt interactions.

A class responsible for terminal prompt interactions.

Public Class Methods

messages() click to toggle source

# File lib/tty/prompt.rb, line 82
def self.messages
  {
    range?: 'Value %{value} must be within the range %{in}',
    valid?: 'Your answer is invalid (must match %{valid})',
    required?: 'Value must be provided'
  }
end

new(*args) click to toggle source

Initialize a Prompt

@param [Hash] options @option options [IO] :input

the input stream

@option options [IO] :output

the output stream

@option options [Hash] :env

the environment variables

@option options [String] :prefix

the prompt prefix, by default empty

@option options [Boolean] :enable_color

enable color support, true by default

@option options [String] :active_color

the color used for selected option

@option options [String] :help_color

the color used for help text

@option options [String] :error_color

the color used for displaying error messages

@option options [Symbol] :interrupt

handling of Ctrl+C key out of :signal, :exit, :noop

@option options [Boolean] :track_history

disable line history tracking, true by default

@api public

# File lib/tty/prompt.rb, line 115
def initialize(*args)
  options = Utils.extract_options!(args)
  @input  = options.fetch(:input) { $stdin }
  @output = options.fetch(:output) { $stdout }
  @env    = options.fetch(:env) { ENV }
  @prefix = options.fetch(:prefix) { '' }
  @enabled_color = options[:enable_color]
  @active_color  = options.fetch(:active_color) { :green }
  @help_color    = options.fetch(:help_color)   { :bright_black }
  @error_color   = options.fetch(:error_color)  { :red }
  @interrupt     = options.fetch(:interrupt)    { :error }
  @track_history = options.fetch(:track_history) { true }

  @cursor = TTY::Cursor
  @pastel = Pastel.new(@enabled_color.nil? ? {} : { enabled: @enabled_color })
  @reader = TTY::Reader.new(
    input: @input,
    output: @output,
    interrupt: @interrupt,
    track_history: @track_history,
    env: @env
  )
end

Public Instance Methods

ask(message, *args, &block) click to toggle source

Ask a question.

@example

propmt = TTY::Prompt.new
prompt.ask("What is your name?")

@param [String] message

the question to be asked

@yieldparam [TTY::Prompt::Question] question

further configure the question

@yield [question]

@return [TTY::Prompt::Question]

@api public

# File lib/tty/prompt.rb, line 172
def ask(message, *args, &block)
  invoke_question(Question, message, *args, &block)
end

collect(options = {}, &block) click to toggle source

Gathers more than one aswer

@example

prompt.collect do
  key(:name).ask('Name?')
end

@return [Hash]

the collection of answers

@api public

# File lib/tty/prompt.rb, line 488
def collect(options = {}, &block)
  collector = AnswersCollector.new(self, options)
  collector.call(&block)
end

enum_select(question, *args, &block) click to toggle source

Ask a question with indexed list

@example

prompt = TTY::Prompt.new
editors = %w(emacs nano vim)
prompt.enum_select(EnumList, "Select editor: ", editors)

@param [String] question

the question to ask

@param [Array] choices

the choices to select from

@return [String]

@api public

# File lib/tty/prompt.rb, line 298
def enum_select(question, *args, &block)
  invoke_select(EnumList, question, *args, &block)
end

error(*args) click to toggle source

Print statement(s) out in red color.

@example

prompt.error "Shutting down all systems!"
prompt.error "Nothing is fine!", "All is broken!"

@param [Array] messages

@return [Array] messages

@api public

# File lib/tty/prompt.rb, line 445
def error(*args)
  options = Utils.extract_options!(args)
  args.each { |message| say message, options.merge(color: :red) }
end

expand(message, *args, &block) click to toggle source

Expand available options

@example

prompt = TTY::Prompt.new
choices = [{
  key: 'Y',
  name: 'Overwrite',
  value: :yes
}, {
  key: 'n',
  name: 'Skip',
  value: :no
}]
prompt.expand('Overwirte Gemfile?', choices)

@return [Object]

the user specified value

@api public

# File lib/tty/prompt.rb, line 361
def expand(message, *args, &block)
  invoke_select(Expander, message, *args, &block)
end

inspect() click to toggle source

Inspect class name and public attributes @return [String]

@api public

# File lib/tty/prompt.rb, line 527
def inspect
  attributes = {
    input: input,
    output: output,
    prefix: prefix,
    active_color: active_color,
    error_color: error_color,
    enabled_color: enabled_color,
    help_color: help_color
  }
  "#<#{self.class}: #{attributes.each { |name, val| "@#{name}=#{val}" }}"
end

invoke_question(object, message, *args, &block) click to toggle source

Invoke a question type of prompt

@example

prompt = TTY::Prompt.new
prompt.invoke_question(Question, "Your name? ")

@return [String]

@api public

# File lib/tty/prompt.rb, line 148
def invoke_question(object, message, *args, &block)
  options = Utils.extract_options!(args)
  options[:messages] = self.class.messages
  question = object.new(self, options)
  question.(message, &block)
end

invoke_select(object, question, *args, &block) click to toggle source

Invoke a list type of prompt

@example

prompt = TTY::Prompt.new
editors = %w(emacs nano vim)
prompt.invoke_select(EnumList, "Select editor: ", editors)

@return [String]

@api public

# File lib/tty/prompt.rb, line 207
def invoke_select(object, question, *args, &block)
  options = Utils.extract_options!(args)
  choices = if block
              []
            elsif args.empty?
              possible = options.dup
              options = {}
              possible
            elsif args.size == 1 && args[0].is_a?(Hash)
              Utils.extract_options!(args)
            else
              args.flatten
            end

  list = object.new(self, options)
  list.(question, choices, &block)
end

keypress(message, *args, &block) click to toggle source

Ask a question with a keypress answer

@see ask

@api public

# File lib/tty/prompt.rb, line 181
def keypress(message, *args, &block)
  invoke_question(Keypress, message, *args, &block)
end

mask(message, *args, &block) click to toggle source

Ask masked question

@example

propmt = TTY::Prompt.new
prompt.mask("What is your secret?")

@return [TTY::Prompt::MaskQuestion]

@api public

# File lib/tty/prompt.rb, line 234
def mask(message, *args, &block)
  invoke_question(MaskQuestion, message, *args, &block)
end

multi_select(question, *args, &block) click to toggle source

Ask a question with multiple attributes activated

@example

prompt = TTY::Prompt.new
choices = %w(Scorpion Jax Kitana Baraka Jade)
prompt.multi_select("Choose your destiny?", choices)

@param [String] question

the question to ask

@param [Array] choices

the choices to select from

@return [String]

@api public

# File lib/tty/prompt.rb, line 278
def multi_select(question, *args, &block)
  invoke_select(MultiList, question, *args, &block)
end

multiline(message, *args, &block) click to toggle source

Ask a question with a multiline answer

@example

prompt.multiline('Description?')

@return [Array]

@api public

# File lib/tty/prompt.rb, line 193
def multiline(message, *args, &block)
  invoke_question(Multiline, message, *args, &block)
end

no?(message, *args, &block) click to toggle source

A shortcut method to ask the user negative question and return true for 'no' reply.

@example

prompt = TTY::Prompt.new
prompt.no?('Are you alien?') # => true
# => Are you human? (y/N)

@return [Boolean]

@api public

# File lib/tty/prompt.rb, line 333
def no?(message, *args, &block)
  defaults = { default: false }
  options  = Utils.extract_options!(args)
  options.merge!(defaults.reject { |k, _| options.key?(k) })

  question = ConfirmQuestion.new(self, options)
  !question.call(message, &block)
end

ok(*args) click to toggle source

Print statement(s) out in red green.

@example

prompt.ok "Are you sure?"
prompt.ok "All is fine!", "This is fine too."

@param [Array] messages

@return [Array] messages

@api public

# File lib/tty/prompt.rb, line 413
def ok(*args)
  options = Utils.extract_options!(args)
  args.each { |message| say message, options.merge(color: :green) }
end

say(message = '', options = {}) click to toggle source

Print statement out. If the supplied message ends with a space or tab character, a new line will not be appended.

@example

say("Simple things.", color: :red)

@param [String] message

@return [String]

@api public

# File lib/tty/prompt.rb, line 394
def say(message = '', options = {})
  message = message.to_s
  return if message.empty?

  statement = Statement.new(self, options)
  statement.call(message)
end

select(question, *args, &block) click to toggle source

Ask a question with a list of options

@example

prompt = TTY::Prompt.new
prompt.select("What size?", %w(large medium small))

@example

prompt = TTY::Prompt.new
prompt.select("What size?") do |menu|
  menu.choice :large
  menu.choices %w(:medium :small)
end

@param [String] question

the question to ask

@param [Array] choices

the choices to select from

@api public

# File lib/tty/prompt.rb, line 258
def select(question, *args, &block)
  invoke_select(List, question, *args, &block)
end

slider(question, *args, &block) click to toggle source

Ask a question with a range slider

@example

prompt = TTY::Prompt.new
prompt.slider('What size?', min: 32, max: 54, step: 2)

@param [String] question

the question to ask

@return [String]

@api public

# File lib/tty/prompt.rb, line 377
def slider(question, *args, &block)
  options = Utils.extract_options!(args)
  slider = Slider.new(self, options)
  slider.call(question, &block)
end

stderr() click to toggle source

Return standard error

@api private

# File lib/tty/prompt.rb, line 519
def stderr
  $stderr
end

stdin() click to toggle source

Return standard in

@api private

# File lib/tty/prompt.rb, line 505
def stdin
  $stdin
end

stdout() click to toggle source

Return standard out

@api private

# File lib/tty/prompt.rb, line 512
def stdout
  $stdout
end

suggest(message, possibilities, options = {}) click to toggle source

Takes the string provided by the user and compare it with other possible matches to suggest an unambigous string

@example

prompt.suggest('sta', ['status', 'stage', 'commit', 'branch'])
# => "status, stage"

@param [String] message

@param [Array] possibilities

@param [Hash] options @option options [String] :indent

The number of spaces for indentation

@option options [String] :single_text

The text for a single suggestion

@option options [String] :plural_text

The text for multiple suggestions

@return [String]

@api public

# File lib/tty/prompt.rb, line 472
def suggest(message, possibilities, options = {})
  suggestion = Suggestion.new(options)
  say(suggestion.suggest(message, possibilities))
end

tty?() click to toggle source

Check if outputing to terminal

@return [Boolean]

@api public

# File lib/tty/prompt.rb, line 498
def tty?
  stdout.tty?
end

warn(*args) click to toggle source

Print statement(s) out in yellow color.

@example

prompt.warn "This action can have dire consequences"
prompt.warn "Carefull young apprentice", "This is potentially dangerous"

@param [Array] messages

@return [Array] messages

@api public

# File lib/tty/prompt.rb, line 429
def warn(*args)
  options = Utils.extract_options!(args)
  args.each { |message| say message, options.merge(color: :yellow) }
end

yes?(message, *args, &block) click to toggle source

A shortcut method to ask the user positive question and return true for 'yes' reply, false for 'no'.

@example

prompt = TTY::Prompt.new
prompt.yes?('Are you human?')
# => Are you human? (Y/n)

@return [Boolean]

@api public

# File lib/tty/prompt.rb, line 313
def yes?(message, *args, &block)
  defaults = { default: true }
  options  = Utils.extract_options!(args)
  options.merge!(defaults.reject { |k, _| options.key?(k) })

  question = ConfirmQuestion.new(self, options)
  question.call(message, &block)
end