User input

​
For complete API documentation refer to: pub.dev​
Asking the user to input data into a CLI application should be simple. DCli provide a number of core methods to facilitate user input.
ask
confirm
menu
Ask
The 'ask' function provides a simple but flexible means of requesting information from the user.
In its simplest form you can ask the user for an input string.
Any user input has whitespace stripped before it is validated or returned.
Arguments
prompt
The prompt is the only positional argument that ask takes. Ask will display the prompt verbatim.
var username = ask('Username:');
Username: brett
You may pass an empty string for the prompt in which case no prompt will be displayed.
hidden
You can request that the user input isn't echoed back to the user:
var password = ask('Password:', hidden: true);
Password: ******
defaultValue
You can provide a default value. If the user hits enter without entering any text then the default value will be returned.
var username = ask('Username:', defaultValue: 'Administrator');
Username: [Administrator]
If you combine a defaultValue with the hidden argument then the default value will be rendered as 6 '*'.
var password = ask('Password:', hidden: true, defaultValue: 'a secret');
password: [******] 
If you combine a defaultValue with an empty prompt then Ask will not display the prompt nor the default value.
var secretQuestion = ask('', defaultValue: 'a secret', required: false);
See the 'customPrompt' argument to modify how the default is displayed.
validator
Ask takes a validator. If the entered input doesn't match the supplied validator then the user will be re-prompted until they enter a valid value.
var age = ask('Age:', validator: Ask.integer);
Age: abc
Invalid integer.
Age:
See the section on validators for more details.
required
By default the ask function requires the user to enter a non-blank line (whitespace is stripped from user input before it is evaluated).
If you want to make a user value optional either pass in a defaultValue or pass required: false
var age = ask('Age:', required: false, validator: Ask.integer);
customPrompt
Since: 2.0.0
By default when passing a default value the ask command formats the default within brackets:
var username = ask('Username:', defaultValue: 'Administrator');
Username: [Administrator]
You can completely modify the prompt by providing the customPrompt argument.
final response = ask('say something:', defaultValue: 'my default'
    , customPrompt: (prompt, defaultValue, hidden) { 
      if (hidden) { 
        return '$prompt>'; 
      } 
      else { 
        return '($defaultValue) $prompt>'; 
      } 
  });
Becareful to suppress displaying the default value when hidden is true, otherwise you may end up displaying a password.
​
Confirm
The confirm method allows you to ask the user for a true/false response and returns a bool reflecting what the user entered.
bool allowed = confirm('Are you over 18', defaultValue: false);
Arguments
prompt
The prompt is the only positional argument that confirm takes. Confirm will display the prompt verbatim.
var alive = confirm('Are you alive:');
Are you alive (y/n): y
You may pass an empty string for the prompt in which case no prompt will be displayed.
defaultValue
You can provide a default value. If the user hits enter without entering any text then the default value will be returned.
var confirmed = confirm('Are you sure:', defaultValue: true);
The default value is capitalised.
Are you sure: (Y/n):
customPrompt
Since: 2.0.0
By default when passing a default value the confirm command formats the default within brackets:
Are you alive (y/n): y
You can completely modify the prompt by providing the customPrompt argument.
  final confirmed = confirm('Are you sure?', defaultValue: false,
      customPrompt: (prompt, defaultValue) {
    var yes = 'yes';
    var no = 'no';
​
    if (defaultValue != null) {
      yes = defaultValue ? 'Yes' : 'yes';
​
      no = !defaultValue ? 'No' : 'no';
    }
    return '$prompt> [$yes/$no]';
  });
Are you sure?> [yes/No]
Menu
The menu function allows you to display a list of menu items for the user to select from and returns the selected item.
var selected = menu('Select your poison'
   , options: ['beer', 'wine', 'spirits']
   , defaultOption: 'beer');
print(green('You chose $selected'));
1) beer
2) wine
3) spirits
Select your poison: 1
You can also specify a default option. If you pass a default value and the user hits enter without entering a value then the default value will be returned.
The list of options can be a String or a Dart class. By default menu will call toString on any object passed but you can pass the format argument to control how each option is displayed:
class Car
{
   String make;
   String model;
   Car(this.make, this.model);
}
var available = [Car('Ford', 'Falcon'), Car('Holden', 'Capree'), Car('BMW', 'M3')];
var selected = menu('Choose your preferred car:'
   , options: available
   , format: (Car car) => '${car.make} ${car.model}'
   , defaultOption: available[0]);
print(green('You chose $selected'));
 1) Ford Falcon
 2) Holden Capree
 3) BMW M3
Choose your preferred car: [1] 
Arguments
options
A list of options for the user to select from.
The list can be a list of Strings or a list of Dart objects (all of the same type).
defaultOption
Specifies the defaultOption from the list of options. The defaultOption must be of the same type as the items in the options list.
The default option will be coloured coded in the list if your terminal supports ansi escape codes.
The default option will be displayed as an index after the prompt.
format
By default the menu function will display each option by calling toString on the passed option.
You can provide an alternate formatter for each option by passing a lambda to the format argument.
format: (Car car) => '${car.make} ${car.model}'
customPrompt
Since: 2.0.0
The customPrompt allows you modify the selection prompt.
customPrompt: (prompt, defaultOption) {
  return '$prompt> $defaultValue';
}
limit
If you pass in a large option list you can pass in the limit argument to limit the number of options displayed in the menu. The first limit options in the list of options will be displayed.
fromStart
FromStart is true by default. If you set it to false and you pass a limit then the menu will show the last limit options.

Tour - Previous

Using DCli functions

Ask Validators

Last modified 6d ago

Copy link

On this page

Ask

Arguments

Confirm

Arguments