Method: CLI::UI::Prompt.ask

Defined in:
lib/cli/ui/prompt.rb

.ask(question, options: nil, default: nil, is_file: false, allow_empty: true, multiple: false, filter_ui: true, select_ui: true, &options_proc) ⇒ Object

Ask a user a question with either free form answer or a set of answers (multiple choice) Can use arrows, y/n, numbers (1/2), and vim bindings to control multiple choice selection Do not use this method for yes/no questions. Use confirm

  • Handles free form answers (options are nil)

  • Handles default answers for free form text

  • Handles file auto completion for file input

  • Handles interactively choosing answers using InteractiveOptions

Attributes

  • question - (required) The question to ask the user

Options

  • :options - Options that the user may select from. Will use InteractiveOptions to do so.

  • :default - The default answer to the question (e.g. they just press enter and don’t input anything)

  • :is_file - Tells the input to use file auto-completion (tab completion)

  • :allow_empty - Allows the answer to be empty

  • :multiple - Allow multiple options to be selected

  • :filter_ui - Enable option filtering (default: true)

  • :select_ui - Enable long-form option selection (default: true)

Note:

  • :options or providing a Block conflicts with :default and :is_file,

    you cannot set options with either of these keywords

  • :default conflicts with +:allow_empty:, you cannot set these together

  • :options conflicts with providing a Block , you may only set one

  • :multiple can only be used with :options or a Block; it is ignored, otherwise.

Block (optional)

  • A Proc that provides a OptionsHandler and uses the public :option method to add options and their respective handlers

Return Value

  • If a Block was not provided, the selected option or response to the free form question will be returned

  • If a Block was provided, the evaluated value of the Block will be returned

Example Usage:

Free form question

CLI::UI::Prompt.ask('What color is the sky?')

Free form question with a file answer

CLI::UI::Prompt.ask('Where is your Gemfile located?', is_file: true)

Free form question with a default answer

CLI::UI::Prompt.ask('What color is the sky?', default: 'blue')

Free form question when the answer can be empty

CLI::UI::Prompt.ask('What is your opinion on this question?', allow_empty: true)

Interactive (multiple choice) question

CLI::UI::Prompt.ask('What kind of project is this?', options: %w(rails go ruby python))

Interactive (multiple choice) question with defined handlers

CLI::UI::Prompt.ask('What kind of project is this?') do |handler|
  handler.option('rails')  { |selection| selection }
  handler.option('go')     { |selection| selection }
  handler.option('ruby')   { |selection| selection }
  handler.option('python') { |selection| selection }
end

: (String question, ?options: Array?, ?default: (String | Array)?, ?is_file: bool, ?allow_empty: bool, ?multiple: bool, ?filter_ui: bool, ?select_ui: bool) ?{ (OptionsHandler handler) -> void } -> (String | Array)



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/cli/ui/prompt.rb', line 103

def ask(
  question,
  options: nil,
  default: nil,
  is_file: false,
  allow_empty: true,
  multiple: false,
  filter_ui: true,
  select_ui: true,
  &options_proc
)
  has_options = !!(options || block_given?)
  if has_options && is_file
    raise(ArgumentError, 'conflicting arguments: is_file is only useful when options are not provided')
  end

  if options && multiple && default && !(Array(default) - options).empty?
    raise(ArgumentError, 'conflicting arguments: default should only include elements present in options')
  end

  if multiple && !has_options
    raise(ArgumentError, 'conflicting arguments: options must be provided when multiple is true')
  end

  if !multiple && default.is_a?(Array)
    raise(ArgumentError, 'conflicting arguments: multiple defaults may only be provided when multiple is true')
  end

  if has_options
    ask_interactive(
      question,
      options,
      multiple: multiple,
      default: default,
      filter_ui: filter_ui,
      select_ui: select_ui,
      &options_proc
    )
  else
    ask_free_form(
      question,
      default, #: as String?
      is_file,
      allow_empty,
    )
  end
end