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-baseSee 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 choicesreturns{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
Contributing
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 Tests
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 testBuilding docs
(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 && verbYou 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
| Commits | Contributor |
|---|---|
| 170 | jonschlinkert |
| 6 | doowb |
| 1 | sbj42 |
Jon Schlinkert
Copyright © 2017, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on October 20, 2017.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent