ask function

String ask(String prompt, { bool toLower = false, bool hidden = false, bool required = true, String? defaultValue, CustomAskPrompt customPrompt = Ask.defaultPrompt, AskValidator validator = Ask.dontCare, })

Reads a line of text from stdin with an optional prompt.

String response = ask("Do you like me?");

If the script is not attached to terminal Terminal().hasTerminal then ask returns immediatly with the defaultValue. If no defaultValue is passed then an empty string is returned. No validate will be applied.

If prompt is set then the prompt will be printed to the console and the cursor placed immediately after the prompt.

Pass an empty string to suppress the prompt.

var secret = ask('', required: false);

By default the ask required argument is true requiring the user to enter a non-empty string. All whitespace is trimmed from the string before the user input is validated so a single space is not an accepted input.

If you set the required argument to false then the user can just hit enter to skip past the ask prompt. If you use other validators when required = false then those validators will not be called if the entered value is empty (after it is trimmed).

if toLower is true then the returned result is converted to lower case. This can be useful if you need to compare the entered value.

If hidden is true then the entered values will not be echoed to the console, instead '*' will be displayed. This is uesful for capturing passwords.

NOTE: if there is no terminal detected then this will fallback to a standard ask input in which case the hidden characters WILL BE DISPLAYED as they are typed.

If a defaultValue is passed then it is displayed and the user fails to enter a value (just hits the enter key) then the defaultValue is returned.

Passing a defaultValue also modifies the prompt to display the value:

var result = ask('How many', defaultValue: '5');
> 'How many [5]'

ask will throw an AskValidatorException if the defaultValue doesn't match the given validator.

The validator is called each time the user hits enter.

The validator allows you to normalise and validate the user's input. The validator must return the normalised value which will be the value returned by ask.

If the validator detects an invalid input then you MUST throw AskValidatorException(error). The error will be displayed on the console and the user reprompted. You can color code the error using any of the dcli color functions. By default all input is considered valid.

  var subject = ask( 'Subject');
  subject = ask( 'Subject', required: true);
  subject = ask( 'Subject', validator: Ask.minLength(10));
  var name = ask( 'What is your name?', validator: Ask.alpha);
  var age = ask( 'How old are you?', validator: Ask.integer);
  var username = ask( 'Username?', validator: Ask.email);
  var password = ask( 'Password?', hidden: true,
    validator: Ask.all([Ask.alphaNumeric, AskValidatorLength(10,16)]));
  var color = ask( 'Favourite colour?'
    , Ask.inList(['red', 'green', 'blue']));

Implementation

String ask(
  String prompt, {
  bool toLower = false,
  bool hidden = false,
  bool required = true,
  String? defaultValue,
  CustomAskPrompt customPrompt = Ask.defaultPrompt,
  AskValidator validator = Ask.dontCare,
}) =>
    Ask()._ask(
      prompt,
      toLower: toLower,
      hidden: hidden,
      required: required,
      defaultValue: defaultValue,
      customPrompt: customPrompt,
      validator: validator,
    );