Base prompt module used for creating custom prompts.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

Install with npm:

$ npm install --save prompt-base

See the changelog for detailed release history.

prompt-base is a node.js library for creating command line prompts. You can use prompt-base directly for simple input prompts, or as a "base" for creating custom prompts:

See the examples folder for additional usage examples.

var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'color',
  message: 'What is your favorite color?'
});

// promise
prompt.run()
  .then(function(answer) {
    console.log(answer);
    //=> 'blue'
  })

// or async
prompt.ask(function(answer) {
  console.log(answer);
  //=> 'blue'
});

You can also pass a string directly to the main export:

var prompt = require('prompt-base')('What is your favorite color?');
  
prompt.run()
  .then(function(answer) {
    console.log(answer);
  })

Inherit

var Prompt = require('prompt-base');

function CustomPrompt(/*question, answers, rl*/) {
  Prompt.apply(this, arguments);
}

Prompt.extend(CustomPrompt);

Create a new Prompt with the given question object, answers and optional instance of readline-ui.

Params

• question {Object}: Plain object or instance of prompt-question.
• answers {Object}: Optionally pass an answers object from a prompt manager (like enquirer).
• ui {Object}: Optionally pass an instance of readline-ui. If not passed, an instance is created for you.

Example

var prompt = new Prompt({
  name: 'color',
  message: 'What is your favorite color?'
});

prompt.ask(function(answer) {
  console.log(answer);
  //=> 'blue'
});

Modify the answer value before it's returned. Must return a string or promise.

• returns {String}

Example

var answers = {};
var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'name',
  message: 'What is your name?',
  transform: function(input) {
    return input.toUpperCase();
  }
});

Validate user input on keypress events and the answer value when it's submitted by the line event (when the user hits enter. This may be overridden in custom prompts. If the function returns false, either question.errorMessage or the default validation error message (invalid input) is used. Must return a boolean, string or promise.

• returns {Boolean}

Example

var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'first',
  message: 'What is your name?',
  errorMessage: 'alphabetical characters only',
  validate: function(input) {
    var str = input ? input.trim() : '';
    var isValid = /^[a-z]+$/i.test(str);
    if (this.state === 'submitted') {
      return str.length > 10 && isValid;
    }
    return isValid;
  }
});

A custom .when function may be defined to determine whether or not a question should be asked at all. Must return a boolean, undefined, or a promise.

• returns {Boolean}

Example

var answers = {};
var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'name',
  message: 'What is your name?',
  when: function(answers) {
    return !answers.name;
  }
});

Run the prompt with the given callback function.

Params

• callback {Function}
• returns {undefined}

Example

var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'name',
  message: 'What is your name?'
});

prompt.ask(function(answer) {
  console.log(answer);
});

Run the prompt and resolve answers. If when is defined and returns false, the prompt will be skipped.

Params

• answers {Object}: (optional) When supplied, the answer value will be added to a property where the key is the question name.
• returns {Promise}

Example

var answers = {};
var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'name',
  message: 'What is your name?'
});

prompt.run(answers)
  .then(function(answer) {
    console.log(answer);
    console.log(answers);
  });

Get the answer to use. This can be overridden in custom prompts.

• returns {String}

Example

console.log(prompt.getDefault());

Get the error message to use. This can be overridden in custom prompts.

• returns {String}

Example

console.log(prompt.getError());

Get the help message to use. This can be overridden in custom prompts.

• returns {String}

Example

console.log(prompt.getHelp());

Get the answer to use. This can be overridden in custom prompts.

• returns {String}

Example

console.log(prompt.getAnswer());

(Re-)render the prompt message, along with any help or error messages, user input, choices, list items, and so on. This is called to render the initial prompt, then it's called again each time the prompt changes, such as on keypress events (when the user enters input, or a multiple-choice option is selected). This method may be overridden in custom prompts, but it's recommended that you override the more specific render "status" methods instead.

• returns {undefined}

Example

prompt.ui.on('keypress', prompt.render.bind(prompt));

Format the prompt message.

• returns {String}

Example

var answers = {};
var Prompt = require('prompt-base');
var prompt = new Prompt({
  name: 'name',
  message: 'What is your name?',
  transform: function(input) {
    return input.toUpperCase();
  }
});

Called by render to render the readline line when prompt.status is anything besides answered, which includes everything except for error and help messages.

• returns {String}

Called by render to add a footer after the message body.

• returns {String}

Called by render to render a help message when the prompt.status is initialized or help (usually when the prompt is first rendered). Calling this method changes the prompt.status to "interacted", and as such, by default, the message is only displayed until the user interacts. By default the help message is positioned to the right of the prompt "question". A custom help message may be defined on options.helpMessage.

Params

• valid {boolean|string|undefined}
• returns {String}

Render an error message in the prompt, when valid is false or a string. This is used when a validation method either returns false, indicating that the input was invalid, or the method returns a string, indicating that a custom error message should be rendered. A custom error message may also be defined on options.errorMessage.

Params

• valid {boolean|string|undefined}
• returns {String}

Mask user input. Called by renderBody, this is an identity function that does nothing by default, as it's intended to be overwritten in custom prompts, such as prompt-password.

• returns {String}

Render the user's "answer". Called by render when the prompt.status is changed to answered.

• returns {String}

Get action name, or set action name with the given fn. This is useful for overridding actions in custom prompts. Actions are used to move the pointer position, toggle checkboxes and so on

Params

• name {String}
• fn {Function}
• returns {Object|Function}: Returns the prompt instance if setting, or the action function if getting.

Move the cursor in the given direction when a keypress event is emitted.

Params

• direction {String}
• event {Object}

Default error event handler. If an error listener exist, an error event will be emitted, otherwise the error is logged onto stderr and the process is exited. This can be overridden in custom prompts.

Params

• err {Object}

Re-render and pass the final answer to the callback. This can be replaced by custom prompts.

Ensures that events for event name are only registered once and are disabled correctly when specified. This is different from .once, which only emits once.

Example

prompt.only('keypress', function() {
  // do keypress stuff
});

Mutes the output stream that was used to create the readline interface, and returns a function for unmuting the stream. This is useful in unit tests.

• returns {Function}

Example

// mute the stream
var unmute = prompt.mute();

// unmute the stream
unmute();

Pause the readline and unmute the output stream that was used to create the readline interface, which is process.stdout by default.

Resume the readline input stream if it has been paused.

• returns {undefined}

Getter for getting the choices array from the question.

• returns {Object}: Choices object

Getter that returns question.message after passing it to format.

• returns {String}: A formatted prompt message.

Getter/setter for getting the checkbox symbol to use.

• returns {String}: The formatted symbol.

Example

// customize
prompt.symbol = '[ ]';

Getter/setter that returns the prefix to use before question.message. The default value is a green ?.

• returns {String}: The formatted prefix.

Example

// customize
prompt.prefix = ' ❤ ';

Static convenience method for running the .ask method. Takes the same arguments as the contructror.

Params

• question {Object}: Plain object or instance of prompt-question.
• answers {Object}: Optionally pass an answers object from a prompt manager (like enquirer).
• ui {Object}: Optionally pass an instance of readline-ui. If not passed, an instance is created for you.
• callback {Function}
• returns {undefined}

Example

var prompt = require('prompt-base');
  .ask('What is your favorite color?', function(answer) {
    console.log({color: answer});
    //=> { color: 'blue' }
  });

Static convenience method for running the .run method. Takes the same arguments as the contructror.

Params

• question {Object}: Plain object or instance of prompt-question.
• answers {Object}: Optionally pass an answers object from a prompt manager (like enquirer).
• ui {Object}: Optionally pass an instance of readline-ui. If not passed, an instance is created for you.
• returns {Promise}

Example

var prompt = require('prompt-base');
  .run('What is your favorite color?')
  .then(function(answer) {
    console.log({color: answer});
    //=> { color: 'blue' }
  });

Create a new Question. See prompt-question for more details.

Params

• options {Object}
• returns {Object}: Returns an instance of prompt-question

Example

var question = new Prompt.Question({name: 'foo'});

Create a new Choices object. See prompt-choices for more details.

Params

• choices {Array}: Array of choices
• returns {Object}: Returns an intance of Choices.

Example

var choices = new Prompt.Choices(['foo', 'bar', 'baz']);

Create a new Separator object. See choices-separator for more details.

Params

• separator {String}: Optionally pass a string to use as the separator.
• returns {Object}: Returns a separator object.

Example

new Prompt.Separator('---');

Emitted when a prompt (plugin) is instantiated, after the readline interface is created, but before the actual "question" is asked.

Example usage

enquirer.on('prompt', function(prompt) {
  // do stuff with "prompt" instance
});

Emitted when the actual "question" is asked.

Example usage

Emit keypress events to supply the answer (and potentially skip the prompt if the answer is valid):

enquirer.on('ask', function(prompt) {
  prompt.rl.input.emit('keypress', 'foo');
  prompt.rl.input.emit('keypress', '\n');
});

Change the prompt message:

enquirer.on('ask', function(prompt) {
  prompt.message = 'I..\'m Ron Burgundy...?';
});

Emitted when the final (valid) answer is submitted, and custom validation function (if defined) returns true.

(An "answer" is the final input value that's captured when the readline emits a line event; e.g. when the user hits enter)

Example usage

enquirer.on('answer', function(answer) {
  // do stuff with answer
});

The following custom prompts were created using this library:

• prompt-autocomplete: A prompt in the terminal but with autocomplete functionality | homepage
• prompt-checkbox: Multiple-choice/checkbox prompt. Can be used standalone or with a prompt system like Enquirer. | homepage
• prompt-confirm: Confirm (yes/no) prompt. Can be used standalone or with a prompt system like Enquirer. | homepage
• prompt-editor: Editor prompt. Opens your text editor and waits for you to save your input during… more | homepage
• prompt-expand: Expand prompt. Can be used as a standalone prompt, or with a prompt system like… more | homepage
• prompt-list: List-style prompt. Can be used as a standalone prompt, or with a prompt system like… more | homepage
• prompt-password: Password prompt. Can be used as a standalone prompt, or as a plugin for Enquirer. | homepage
• prompt-radio: Radio prompt. Can be used as a standalone prompt, or as a plugin for Enquirer. | homepage
• prompt-rawlist: Rawlist prompt. Can be used as a standalone prompt, or with a prompt system like… more | homepage

$ npm install && npm test

$ npm install -g verbose/verb#dev verb-generate-readme && verb

You might also be interested in these projects:

• enquirer: Intuitive, plugin-based prompt system for node.js. | homepage
• prompt-choices: Create an array of multiple choice objects for use in prompts. | homepage
• prompt-question: Question object, used by Enquirer and prompt plugins. | homepage
• readline-utils: Readline utils, for moving the cursor, clearing lines, creating a readline interface, and more. | homepage

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.6.0, on October 20, 2017.