inquirer.rb

A collection of common interactive command line user interfaces. A (not yet completed) clone of the great Inquirer.js and strongly inspired by the similar inquirer.rb.

Started as a fork of inquirer.rb the changes become to fundamental to keep it that way.

Goals

• Inquirer.js API conform as possible
• Extended functionality API similar as possible
• Slim dependencies
• Easy integration

Installation

Add this line to your application's Gemfile:

gem 'inquirer.rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install inquirer.rb

Usage

require 'inquirer'

questions = [
  {
    name:    :user_name,
    type:    :input,  # optional - default ':input', others see below
    message: 'What is your name?',
  }
]

answers = Inquirer.prompt(questions)

p answers[:user_name]

# => Tyler

See the examples folder for more examples.

Basically it's:

• Inquirer.prompt takes an Array as parameter, containing question Hashes
• Each question Hash has to contain the parameters required for the given :type parameter
• If no :type paramter is given :input is used as default
• Inquirer.prompt returns a Hash with the question :name parameter as key and the user input as value

Prompt types

There parameters are valid for all prompt types:

• :message (String) The question to print.
• :filter (Proc) (optional) Receive the user input and return the filtered value to be used inside the program. The value returned will be added to the answers Hash.
• :when (Proc|Boolean) (optional) Receive the current user answers Hash and should return true or false depending on whether or not this question should be asked. The value can also be a simple boolean.

Input (type: :input)

• :default (String) (optional) Default value to use if nothing is entered.
• :validate (Proc) (optional) Receive the user input and should return true if the value is valid, and an error message (String) otherwise. If false is returned, a default error message is provided.

Password (type: :password)

• :default (String) (optional) Default value to use if nothing is entered.
• :validate (Proc) (optional) Receive the user input and should return true if the value is valid, and an error message (String) otherwise. If false is returned, a default error message is provided.

List (type: :list)

• :choices (Array) Has to contain Hashes with the following parameters:
  • :name (String) The display value
  • :short (String) (optional) To display after selection
  • :value (String|Symbol) To save in the answers Hash
  • :when (Proc|Boolean) (optional) Should return true or false depending on whether or not this question should be asked. The value can also be a simple boolean.
• :default (Integer|String|Symbol) (optional) Must be the choice index (Integer) in the Array or a choice :value parameters value (String|Symbol).

List filterable (type: :list_filterable)

• :choices (Array) Has to contain Hashes with the following parameters:
  • :name (String) The display value
  • :short (String) (optional) To display after selection
  • :value (String|Symbol) To save in the answers Hash
  • :when (Proc|Boolean) (optional) Should return true or false depending on whether or not this question should be asked. The value can also be a simple boolean.
• :default (Integer|String|Symbol) (optional) Must be the choice index (Integer) in the Array or a choice :value parameters value (String|Symbol).

Checkbox (type: :checkbox)

• :choices (Array) Has to contain Hashes with the following parameters:
  • :name (String) The display value
  • :short (String) (optional) To display after selection
  • :value (String|Symbol) To save in the answers Hash
  • :checked (Boolean) (optional) True choices will be checked by default
  • :when (Proc|Boolean) (optional) Should return true or false depending on whether or not this question should be asked. The value can also be a simple boolean.
• :default (Array) (optional) An Array of choices :value parameters values (String|Symbol).
• :validate (Proc) (optional) Receive the user input and should return true if the value is valid, and an error message (String) otherwise. If false is returned, a default error message is provided.

Checkbox filterable (type: :checkbox_filterable)

• :choices (Array) Has to contain Hashes with the following parameters:
  • :name (String) The display value
  • :short (String) (optional) To display after selection
  • :value (String|Symbol) To save in the answers Hash
  • :checked (Boolean) (optional) True choices will be checked by default
  • :when (Proc|Boolean) (optional) Should return true or false depending on whether or not this question should be asked. The value can also be a simple boolean.
• :default (Array) (optional) An Array of choices :value parameters values (String|Symbol).
• :validate (Proc) (optional) Receive the user input and should return true if the value is valid, and an error message (String) otherwise. If false is returned, a default error message is provided.

Confirm (type: :confirm)

• :default (Boolean) (optional) Default value to use if nothing is entered is expected to be a boolean.

Development

General

• :type parameter (InquirerJS conform)
• no :type parameter provided results in :input (InquirerJS conform)
• :name parameter (InquirerJS conform)
• :message (String) parameter (InquirerJS conform)
• :message (Proc) parameter (InquirerJS conform)
• :default (String) parameter (optional) (InquirerJS conform)
• :default (Proc) parameter (optional) (InquirerJS conform)
• :when (Proc) parameter (optional) (InquirerJS conform)
• :when (Boolean) parameter (optional) (InquirerJS conform)
• :filter (Proc) parameter (optional)
• :validate (Proc) parameter (optional) (InquirerJS conform)
• colored formatting (InquirerJS conform)
• easy styling / formatting of all output components (question, result, items, password....)

Input

• Backend
• :validate (Proc) parameter (optional) (InquirerJS conform)
• Tests

Password

• Backend
• :validate (Proc) parameter (optional) (InquirerJS conform)
• Tests

List

• Backend
• :choices (Array) parameter (InquirerJS conform)
• :choices (Proc) parameter (InquirerJS conform)
• :choices :name parameter (InquirerJS conform)
• :choices :value parameter (InquirerJS conform)
• :choices :short parameter (InquirerJS conform)
• :choices :when (Proc) parameter
• :choices :when (Boolean) parameter
• :validate (Proc) parameter (optional) (InquirerJS conform)
• Tests

List filterable

• Backend
• :choices (Array) parameter (InquirerJS conform)
• :choices (Proc) parameter (InquirerJS conform)
• :choices :name parameter (InquirerJS conform)
• :choices :value parameter (InquirerJS conform)
• :choices :short parameter (InquirerJS conform)
• :choices :when (Proc) parameter
• :choices :when (Boolean) parameter
• :validate (Proc) parameter (optional) (InquirerJS conform)
• Tests

Checkbox

• Backend
• :choices (Array) parameter (InquirerJS conform)
• :choices (Proc) parameter (InquirerJS conform)
• :choices :name parameter (InquirerJS conform)
• :choices :value parameter (InquirerJS conform)
• :choices :checked parameter (InquirerJS conform)
• :choices :when (Proc) parameter
• :choices :when (Boolean) parameter
• :choices :disabled (String) parameter (InquirerJS conform)
• :choices :disabled (Boolean) parameter (InquirerJS conform)
• :choices :disabled (Proc) parameter (InquirerJS conform)
• :choices :short parameter
• Tests

Checkbox filterable

• Backend
• :choices (Array) parameter (InquirerJS conform)
• :choices (Proc) parameter (InquirerJS conform)
• :choices :name parameter (InquirerJS conform)
• :choices :value parameter (InquirerJS conform)
• :choices :checked parameter (InquirerJS conform)
• :choices :when (Proc) parameter
• :choices :when (Boolean) parameter
• :choices :disabled (String) parameter (InquirerJS conform)
• :choices :disabled (Boolean) parameter (InquirerJS conform)
• :choices :disabled (Proc) parameter (InquirerJS conform)
• :choices :short parameter
• Tests

Confirm

• Backend
• Tests

Raw List

• Backend
• :choices parameter (InquirerJS conform)
• Tests

Expand

• Backend
• :choices parameter (InquirerJS conform)
• Tests

Seperator

• constructor takes a facultative String value that'll be use as the separator (InquirerJS conform)
• default separator -------- (InquirerJS conform)
• Tests

BottomBar

• fixed text at the bottom of a free text zone (InquirerJS conform)
• Tests

Development

Run rake spec to run the tests.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thorsteneckel/inquirer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.