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:

``sh
$ npm install --save prompt-choices
`

Usage

`js
var Choices = require('prompt-choices');
var choices = new Choices(['foo', 'bar', 'baz']);
`

API

$3

Create a new Choices collection.

Params

* choices {Array}: One or more choice strings or objects.

Example

`js
const choices = new Choices(['foo', 'bar', 'baz']);
const choices = new Choices([{name: 'foo'}, {name: 'bar'}, {name: 'baz'}]);
`

$3

Render choices.

Params

* position {Number}: Cursor position
* options {Object}
* returns {String}

$3

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

`js
choices.render = function(choice, position, options) {
// do custom logic
return '';
};
`

$3

Create a new Choice object.

Params

* val {String|Object}
* returns {Object}: Returns a choice object.

Example

`js
choices.choice('blue');
`

$3

Returns a normalized choice object.

Params

* choice {Object|String}
* returns {Object}

Example

`js
choices.toChoice('foo');
choices.toChoice({name: 'foo'});
`

$3

Add a normalized choice object to the choices array.

Params

* choice {string|Object}: One or more choices to add.

Example

`js
choices.addChoice(['foo', 'bar', 'baz']);
`

$3

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

`js
choices.addChoices(['foo', 'bar', 'baz']);
`

$3

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

`js
choices.toGroups({
foo: ['a', 'b', 'c'],
bar: ['d', 'e', 'f']
});
`

$3

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

`js
choices.separator();
`

$3

Returns true if a choice exists.

Params

* val {Number}: The index or key of the choice to check for.
* returns {Boolean}

Example

`js
choices.hasChoice(1);
choices.hasChoice('foo');
`

$3

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

`js
choices.getChoice(1);
choices.getChoice('foo');
`

$3

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

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

$3

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

`js
const choice = choices.get(1);
//=> {name: 'foo'}
const choice = choices.get(1, 'name');
//=> 'foo'
`

$3

Clear all choices from the instance. This is useful when you need to update the indices of choices without re-instantiating.

Example

`js
choices.clear();
`

$3

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

$3

Check the choice at the given idx.

Params

* val {Number|Array}: The key(s) or index(s) of the choice(s) to check.

Example

`js
choices.check(1);
`

$3

Disable the choice at the given idx.

Params

* idx {Number}: The index of the choice to enable.

Example

`js
choices.uncheck(1);
`

$3

Returns true if a choice is checked.

Params

* name {String|Number}: Name or index of the choice.
* returns {Boolean}

Example

`js
const choices = new Choices(['foo', 'bar', 'baz']);
console.log(choices.isChecked('foo'));
//=> false
choices.check('foo');
console.log(choices.isChecked('foo'));
//=> true
`

$3

Toggle the choice at the given idx.

Params

* idx {Number}: The index of the choice to toggle.

Example

`js
choices.toggle(1);
// radio mode
choices.toggle(1, true);
`

$3

Swap two choices in the choices array.

Params

* a {String|Number}
* b {String|Number}
* returns {Object}: Returns the Choices instance

$3

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

$3

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

$3

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

$3

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

$3

Getter for getting the default choice.

$3

Getter for getting the checked choices from the collection.

$3

Getter for getting the length of the collection.

$3

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

`js
new Choices.Separator();
`

$3

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

`js
const Choices = require('prompt-choices');
const choices = new Choices(['foo']);
console.log(Choices.isChoices(choices)); //=> true
console.log(Choices.isChoices({})); //=> false
`

$3

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

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

$3

Added

* adds array support to .isChecked

Fixed

* ensures that choice groups are checked/unchecked based on group items

$3

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.

$3

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

$3

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

$3

Jon Schlinkert

* LinkedIn Profile
* GitHub Profile
* Twitter Profile

$3

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

*

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