prompt-choices

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 more choice 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. choice groups .

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 the Choices 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 of Choices.

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 of Choice.

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 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

<summary>Contributing</summary>

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

<summary>Running Tests</summary>

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

<summary>Building docs</summary>

(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

This file was generated by verb-generate-readme, v0.6.0, on May 28, 2018.

Current Tags

5.0.0 ... latest (6 years ago)

prompt-choices

Install

Usage

API

Release history

v3.0.2

v3.0.0

v2.0.0

Attribution

About

Related projects

Author

License

Current Tags

30 Versions