prompt-choices
prompt-choices copied to clipboard
This repository has been archived, use Enquirer instead.
prompt-choices
![Linux Build Status](https://img.shields.io/travis/enquirer/prompt-choices.svg?style=flat&label=Travis)
Create an array of multiple choice objects for use in 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-choices
Usage
var Choices = require('prompt-choices');
var choices = new Choices(['foo', 'bar', 'baz']);
API
Choices
Create a new Choices
collection.
Params
-
choices
{Array}: One or morechoice
strings or objects.
Example
const choices = new Choices(['foo', 'bar', 'baz']);
const choices = new Choices([{name: 'foo'}, {name: 'bar'}, {name: 'baz'}]);
.render
Render choices.
Params
-
position
{Number}: Cursor position -
options
{Object} -
returns
{String}
.renderChoice
Render a specific choice. This can be overridden in prompts.
Params
-
choice
{Object} -
position
{Number} -
options
{Object} -
returns
{String}: Returns the line to render.
Example
choices.render = function(choice, position, options) {
// do custom logic
return '';
};
.choice
Create a new Choice
object.
Params
-
val
{String|Object} -
returns
{Object}: Returns a choice object.
Example
choices.choice('blue');
.toChoice
Returns a normalized choice
object.
Params
-
choice
{Object|String} -
returns
{Object}
Example
choices.toChoice('foo');
choices.toChoice({name: 'foo'});
.addChoice
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']);
.addChoices
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']);
.toGroups
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']
});
.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
choices.separator();
.hasChoice
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');
.getChoice
Get a non-separator choice from the collection.
Params
-
idx
{Number}: The selected choice index -
returns
{Object|undefined}: Return the matched choice object or undefined
Example
choices.getChoice(1);
choices.getChoice('foo');
.getIndex
Get the index of a non-separator choice from the collection.
Params
-
key
{String}: The key of the choice to get -
returns
{Number}: Index of the choice or-1
;
Example
const choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.getIndex('foo')); //=> 0
console.log(choices.getIndex('baz')); //=> 2
console.log(choices.getIndex('bar')); //=> 1
console.log(choices.getIndex('qux')); //=> -1
.get
Get the choice at the specified index.
Params
-
key
{Number|String}: The name or index of the object to get -
returns
{Object}: Returns the specified choice
Example
const choice = choices.get(1);
//=> {name: 'foo'}
const choice = choices.get(1, 'name');
//=> 'foo'
.clear
Clear all choices from the instance. This is useful when you need to update the indices of choices without re-instantiating.
Example
choices.clear();
.key
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
.check
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);
.uncheck
Disable the choice at the given idx
.
Params
-
idx
{Number}: The index of the choice to enable.
Example
choices.uncheck(1);
.isChecked
Returns true if a choice is checked.
Params
-
name
{String|Number}: Name or index of the choice. -
returns
{Boolean}
Example
const choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.isChecked('foo'));
//=> false
choices.check('foo');
console.log(choices.isChecked('foo'));
//=> true
.toggle
Toggle the choice at the given idx
.
Params
-
idx
{Number}: The index of the choice to toggle.
Example
choices.toggle(1);
// radio mode
choices.toggle(1, true);
.swap
Swap two choices in the choices array.
Params
-
a
{String|Number} -
b
{String|Number} -
returns
{Object}: Returns theChoices
instance
.where
Return choice values for choices that return truthy based
on the given val
.
Params
-
val
{Array|Object|Function|String|RegExp} -
returns
{Array}: Matching choices or empty array
.isItem
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
.isValidIndex
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
.pluck
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
.default
Getter for getting the default choice.
.checked
Getter for getting the checked choices from the collection.
.length
Getter for getting the length of the collection.
.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 Choices.Separator();
.isChoices
Create a new Separator
object. See choices-separator for more details.
Params
-
choices
{String}: The value to test. -
returns
{Boolean}: Returns true if the given value is an instance ofChoices
.
Example
const Choices = require('prompt-choices');
const choices = new Choices(['foo']);
console.log(Choices.isChoices(choices)); //=> true
console.log(Choices.isChoices({})); //=> false
.isChoice
Create a new Separator
object. See choices-separator for more details.
Params
-
choice
{String}: The value to test. -
returns
{Boolean}: Returns true if the given value is an instance ofChoice
.
Example
const Choices = require('prompt-choices');
const choices = new Choices(['foo']);
const foo = choices.getChoice('foo');
console.log(Choices.isChoice(foo)); //=> true
console.log(Choices.isChoice({})); //=> false
Release history
v3.0.2
Added
- adds array support to
.isChecked
Fixed
- ensures that choice groups are checked/unchecked based on group items
v3.0.0
Added
- adds support for choice "groups"! This allows you to define an object of choice arrays, where each key in the object creates a choice group.
v2.0.0
Changed
- renamed
Move
class toActions
- renamed
choices.move
property tochoices.actions
Removed
- removed
.enable
and.disable
prototype methods from bothChoice
andChoices
. 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 namedMove
) for managing actions on choices - adds
.addChoice
prototype method, for adding a single choice after instantiation - adds
.action
prototype method toChoices
, which calls a method on theActions
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
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
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
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#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-base: Base prompt module used for creating custom prompts. | 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. Can be used as a standalone prompt, or as a plugin for [Enquirer]. | homepage
Author
Jon Schlinkert
License
Copyright © 2018, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on May 28, 2018.