prompt-base

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 :heart: and support.

Install

Install with npm:

$ npm install --save prompt-base

Release history

See the changelog for detailed release history.

What is this?

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:

Usage

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);
  })

Custom prompts

Inherit

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

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

Prompt.extend(CustomPrompt);

API

Prompt

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

.transform

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

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;
  }
});

.when

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;
  }
});

.ask

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

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);
  });

.getDefault

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

• returns {String}

Example

console.log(prompt.getDefault());

.getError

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

• returns {String}

Example

console.log(prompt.getError());

.getHelp

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

• returns {String}

Example

console.log(prompt.getHelp());

.getAnswer

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

• returns {String}

Example

console.log(prompt.getAnswer());

.render

(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));

.renderMessage

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();
  }
});

.renderBody

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}

.renderFooter

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

• returns {String}

.renderHelp

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}

.renderError

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}

.renderMask

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}

.renderAnswer

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

• returns {String}

.action

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.

.dispatch

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

Params

• direction {String}
• event {Object}

.onError

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}

.submitAnswer

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

.only

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
});

.mute

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();

.end

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

.resume

Resume the readline input stream if it has been paused.

• returns {undefined}

.choices

Getter for getting the choices array from the question.

• returns {Object}: Choices object

.message

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

• returns {String}: A formatted prompt message.

.symbol

Getter/setter for getting the checkbox symbol to use.

• returns {String}: The formatted symbol.

Example

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

.prefix

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 = ' ❤ ';

.ask

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

.run

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

.Question

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

.Choices

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']);

.Separator

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('---');

Events

prompt

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
});

ask

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...?';
});

answer

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
});

In the wild

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

About

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

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

Related projects

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

Contributors

| Commits | Contributor | | --- | --- | | 170 | jonschlinkert | | 6 | doowb | | 1 | sbj42 |

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

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

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