# User input

{% hint style="info" %}

For complete API documentation refer to: [pub.dev](https://pub.dev/documentation/dcli/latest/dcli/dcli-library.html)
{% endhint %}

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.

{% hint style="info" %}
Any user input **whitespace** is stripped before it is validated or returned.
{% endhint %}

### Arguments

#### prompt

The prompt is the only positional argument that `ask` takes. Ask will display the prompt verbatim.

```dart
var username = ask('Username:');
```

```bash
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:

```dart
var password = ask('Password:', hidden: true);
```

```bash
Password: ******
```

#### defaultValue

You can provide a default value. If the user hits enter without entering any text then the default value will be returned.

```dart
var username = ask('Username:', defaultValue: 'Administrator');
```

```bash
Username: [Administrator]
```

If you combine a defaultValue with the hidden argument then the default value will be rendered as 6 '\*'.

```dart
var password = ask('Password:', hidden: true, defaultValue: 'a secret');
```

```bash
password: [******] 
```

If you combine a defaultValue with an empty prompt then Ask will not display the prompt nor the default value.

```dart
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.

```dart
var age = ask('Age:', validator: Ask.integer);
```

```bash
Age: abc
Invalid integer.
Age:
```

See the section on [validators](/dcli-api/user-input/ask-validators.md) 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

```dart
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:

```dart
var username = ask('Username:', defaultValue: 'Administrator');
```

```bash
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>'; 
      } 
  });
```

Be careful 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.

```dart
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.

```dart
var alive = confirm('Are you alive:');
```

```bash
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.

```dart
var confirmed = confirm('Are you sure:', defaultValue: true);
```

The default value is capitalized.

```bash
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:

```bash
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.

```dart
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:

```dart
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 colored-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.

```dart
format: (Car car) => '${car.make} ${car.model}'
```

#### customPrompt

Since: 2.0.0

The customPrompt allows you to modify the selection prompt.

```dart
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dcli.onepub.dev/dcli-api/user-input.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.