prompt-choices
Create an array of multiple choice objects for use in prompts.
Install
Install with npm:
$ npm install --save prompt-choices
Usage
var Choices = require('prompt-choices');
var choices = new Choices(['foo', 'bar', 'baz']);
API
Create a new Choices
collection.
Params
choices
{Array}: One or more choice
strings or objects.
Example
var choices = new Choices(['foo', 'bar', 'baz']);
var choices = new Choices([{name: 'foo'}, {name: 'bar'}, {name: 'baz'}]);
Create a new Choice
object.
Params
choice
{String|Object}returns
{Object}: Returns a choice object.
Example
choices.choice('blue');
Returns a normalized choice
object.
Params
choice
{Object|String}returns
{Object}
Example
choices.toChoice('foo');
choices.toChoice({name: 'foo'});
Add a normalized choice
object to the choices
array.
Params
choice
{string|Object}: One or more choices to add.
Example
choices.addChoice(['foo', 'bar', 'baz']);
Add an array of normalized choice
objects to the choices
array. This method is called in the constructor, but it can also be used to add choices after instantiation.
Params
choices
{Array|Object}: One or more choices to add.
Example
choices.addChoices(['foo', 'bar', 'baz']);
Create choice "groups" from the given choices object. .
Params
choices
{Object}: (required) The value of each object must be an array of choices (strings or objects).returns
{Array}: Returns an array of normalized choice objects.
Example
choices.toGroups({
foo: ['a', 'b', 'c'],
bar: ['d', 'e', 'f']
});
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
choices.separator();
Returns true if a choice exists.
Params
val
{Number}: The index or key of the choice to check for.returns
{Boolean}
Example
choices.hasChoice(1);
choices.hasChoice('foo');
Get a non-separator choice from the collection.
Params
idx
{Number}: The selected choice indexreturns
{Object|undefined}: Return the matched choice object or undefined
Example
choices.getChoice(1);
choices.getChoice('foo');
Get the index of a non-separator choice from the collection.
Params
key
{String}: The key of the choice to getreturns
{Number}: Index of the choice or -1
;
Example
var choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.getIndex('foo'));
console.log(choices.getIndex('baz'));
console.log(choices.getIndex('bar'));
console.log(choices.getIndex('qux'));
Get the choice or separator object at the specified index.
Params
key
{Number|String}: The name or index of the object to getreturns
{Object}: Returns the specified choice
Example
var choice = choices.get(1);
Check the choice at the given idx
.
Params
val
{Number|Array}: The key(s) or index(s) of the choice(s) to check.
Example
choices.check(1);
Disable the choice at the given idx
.
Params
idx
{Number}: The index of the choice to enable.
Example
choices.uncheck(1);
Returns true if a choice is checked.
Params
name
{String|Number}: Name or index of the choice.returns
{Boolean}
Example
var choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.isChecked('foo'));
choices.check('foo');
console.log(choices.isChecked('foo'));
Toggle the choice at the given idx
.
Params
idx
{Number}: The index of the choice to toggle.
Example
choices.toggle(1);
choices.toggle(1, true);
Render the current choice "line".
Params
position
{Number}: Cursor positionoptions
{Object}returns
{String}
Return choice values for choices that return truthy based
on the given val
.
Params
val
{Object|Function|String|RegExp}returns
{Array}: Matching choices or empty array
Returns true if the given choice
is a valid choice item, and
not a "group" or "radio" choice.
Params
key
{String}: Property name to use for plucking objects.returns
{Array}: Plucked objects
Returns true if the given index
is a valid choice index.
Params
key
{String}: Property name to use for plucking objects.returns
{Array}: Plucked objects
Return the .key
property from the choice at the given index.
Params
key
{String}: Property name to use for plucking objects.returns
{Array}: Plucked objects
Pluck an object with the specified key from the choices collection.
Params
key
{String}: Property name to use for plucking objects.returns
{Array}: Plucked objects
Getter for getting the checked choices from the collection.
Getter for getting the length of the collection.
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 Choices.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
var Choices = require('prompt-choices');
var choices = new Choices(['foo']);
console.log(Choices.isChoices(choices));
console.log(Choices.isChoices({}));
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
var Choices = require('prompt-choices');
var choices = new Choices(['foo']);
var foo = choices.getChoice('foo');
console.log(Choices.isChoice(foo));
console.log(Choices.isChoice({}));
Release history
v2.0.0
Changed
- renamed
Move
class to Actions
- renamed
choices.move
property to choices.actions
Removed
- removed
.enable
and .disable
prototype methods from both Choice
and Choices
. These methods were ambiguous as they blurred the distinction between "enabling" a choice (meaning that it's "checked") versus enabling a property on a choice. If this is confusing, that's why they were removed.
Added
- adds
Actions
class (previously named Move
) for managing actions on choices - adds
.addChoice
prototype method, for adding a single choice after instantiation - adds
.action
prototype method to Choices
, which calls a method on the Actions
class - adds
.check
and .uncheck
prototype methods (previously ambiguously named .enable
and .disable
)
Attribution
Some of the code in this library was initially based on the Choices
class in Inquirer.
About
Related projects
- enquirer: Intuitive, plugin-based prompt system for node.js. Much faster and lighter alternative to Inquirer, with all… more | homepage
- prompt-base: Base prompt module used for creating custom prompt types for Enquirer. | homepage
- prompt-checkbox: Multiple-choice/checkbox prompt. Can be used standalone or with a prompt system like [Enquirer]. | homepage
- prompt-question: Question object, used by Enquirer and prompt plugins. | homepage
- prompt-radio: Radio prompt. This prompt behaves like other radio-button interfaces, where only one choice is enabled… more | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Building 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
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 test
Author
Jon Schlinkert
License
Copyright © 2017, Jon Schlinkert.
Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on May 21, 2017.