Fields
Fields is a small library that provides a handful of useful input fields for use at the command line. Each field type supports both an object-oriented and chainable method-based API.
Installation
npm install fields
Features
- Tab completion for File and Select fields
- Password masks
- Titles, descriptions, prompt labels
- Custom renderers and validation handler support
- Fully customizable appearance
- Command history
- Batch field prompting including flow control
- Support for select field option accelerators
Field Types
Text
Simple prompt for capturing a string of text. Also supports password masks and history.
File
Prompt for a specific file or directory. Supports tab completion.
Select list
Displays a list of options which a single item can be selected. Supports tab completion, numbered options, and setting the display method.
Set
Group multiple fields into a single "set" and prompts for each field. Supports skipping fields in the set.
Getting Started
Start by requiring the fields module:
var fields = ;
Global Settings
fields.setup(opts)
Sets default settings.
{object}
opts
Contains settings that will override the default values
Example:
fields;
Available Default Settings
{boolean}
colors
- Enables colors.
- Scope: applies to all field types
- Default:
true
{string}
separator
- The separator between the promptLabel and the input.
- Scope: applies to all field types
- Default:
'> '
{string}
defaultLeft
- When a default value is set, this string is printed to the left of the default value.
- Scope: applies to
File
,Select
, andText
- Default:
'['
{string}
defaultRight
- When a default value is set, this string is printed to the right of the default value.
- Scope: applies to
File
,Select
, andText
- Default:
']'
{string}
promptValuesLeft
- When displaying a list of values in the prompt, this string is printed to the left of the list of values.
- Scope: applies to
Select
, but will work withFile
andText
- Default:
'('
{string}
promptValuesSeparator
- When displaying a list of values in the prompt, this string is printed between each value.
- Scope: applies to
Select
, but will work withFile
andText
- Default:
'|'
{string}
promptValuesRight
- When displaying a list of values in the prompt, this string is printed to the right of the list of values.
- Scope: applies to
Select
, but will work withFile
andText
- Default:
')'
{string}
mask
- The character to be rendered when prompting for a password.
- Scope: applies to
Text
whenpassword
=true
- Default:
'*'
{string}
fieldSeparator
- The string to be displayed between fields in a
Set
. - Scope: applies to
Set
- Default:
'\n'
{object}
style
- An object containing one or more style classes where the value is a color
or style or an array containg a color and one or more styles. Values may
also be
null
. - Properties:
default
(default value:'cyan'
)title
(default value:'magenta'
)promptLabel
(default value:'bold'
)promptValues
(default value:null
)desc
(default value:'grey'
)mask
(default value:'magenta'
)group
(default value:'grey'
)error
(default value:'red'
)suggestion
(default value:'cyan'
)option
(default value:'cyan'
)accelerator
(default value['underline', 'bold', 'cyan']
)
- Colors:
'red'
'yellow'
'green'
'blue'
'cyan'
'magenta'
'black'
'grey'
'white'
- Styles:
'bold'
'underline'
'italic'
'inverse'
- NOTE: some styles, such as
italic
, may not work in all environments and styles such aswhite
orblack
may conflict with the background color of the user's terminal.
{boolean}
repromptOnError
- If the field has a
validate()
function, validation fails, andrepromptOnError
istrue
(default), then it will reprompt for the value again. IfrepromptOnError
is false, then it will stop prompting. This is useful when you have aSet
and you need to prompt for multiple values, then possibly return to a previous field if validation fails. For example, you prompt for a username and password, but authentication fails, you may want to re-prompt for the username again. - Scope: applies to
File
,Select
, andText
- Default:
true
fields.Text(opts)
Creates a new Text field.
-
{object}
opts
Text field options.-
Text field specific options:
-
{object}
opts.formatters
An object of specific formatting functions.-
{function}
opts.formatters.desc(string)
Custom field description formatter.
-
{function}
opts.formatters.error(Error|string)
Error message formatter.
-
{function}
opts.formatters.title(string)
Custom field title formatter.
-
-
-
Standard options:
-
{boolean}
opts.colors
Enables text being rendered with color. Default value is
true
. -
{string}
opts.default
The default value. Returned when the user enters an empty value at the prompt.
-
{string}
opts.defaultLeft
A string displayed before the default value in the prompt. Default value is
'['
. -
{string}
opts.defaultRight
A string displayed after the default value in the prompt. Default value is
']'
. -
{string}
opts.desc
The description to print below the title, but above the prompt.
-
{boolean}
opts.hidden
When true, the value is still prompted, but it's not apart of the results. Useful for decisions in a
Set
. -
{string}
opts.mask
The character to be rendered when entering a password. The mask must be 1 character. Default value is
'*'
. -
{function}
opts.next(err, value, callback)
When this field is being prompted in a
Set
, thenext()
function is called after prompting andvalidate()
has completed to tell theSet
which field to visit next.If
validate()
fails andrepromptOnError
==true
, thennext()
is not called since the field will continue to re-prompt untilvalidate()
passes.next()
may return the name or index of the next field or call the suppliedcallback()
with the name or index of the next field to visit.If
next()
returns nothing orundefined
, it will assume you are planning on calling the suppliedcallback
function.If
next()
returnsnull
, then theSet
will proceed to the next field.If
next()
returnsfalse
, then it will tell theSet
to stop prompting. -
{boolean}
opts.password
Treat input as a secret.
-
{string}
opts.promptLabel
The label to display before prompt.
-
{array<string>}
opts.promptValues
The values to print between the
promptLabel
and the prompt input. -
{string}
opts.promptValuesLeft
A string displayed before the
promptValues
. Default value is'('
. -
{string}
opts.promptValuesRight
A string displayed after the
promptValues
. Default value is')'
. -
{string}
opts.promptValuesSeparator
A string used to separate the prompt values. Default value is
'|'
. -
{boolean}
opts.repromptOnError
If the field has a
validate()
function, validation fails, andrepromptOnError
istrue
(default), then it will reprompt for the value again.If
repromptOnError
is false, then it will stop prompting. This is useful when you have aSet
and you need to prompt for multiple values, then possibly return to a previous field if validation fails.For example, you prompt for a username and password, but authentication fails, you may want to re-prompt for the username again.
Default value is
true
. -
{string}
opts.separator
A string displayed after the prompt, but before the prompt input. Default value is
': '
. -
{string}
opts.title
The title to print above the prompt.
-
{boolean}
opts.trim
Trim the input after entered. Default value is
true
. -
{function}
opts.validate(value, callback(err, value), field)
A function to be called when a value is submitted. The
validate()
function is passed in thevalue
and acallback
.If the
validate()
function returnstrue
, validation passes.If it returns
false
, validation fails.If it returns
undefined
, then it will wait for thecallback()
parameter to be called. Thecallback(err, value)
function MUST pass thevalue
back. This allows thecallback()
to not only validate, but modify the value.
-
-
Returns a Text
field instance with the following properties:
-
{function}
prompt(callback)
-
{function}
callback(err, value)
A function that is called when prompting has completed.
-
-
{Set}
set
If the field is apart of a
Set
, then this property will reference the set, otherwiseset
will benull
.
Events:
-
pre-prompt
Emitted before the current field is prompted.
{object}
field
The current field
-
post-prompt
Emitted after the current field has been prompted.
{object}
field
The current field{anything}
err
The error if something failed{string}
result
The result after the prompting
Object-oriented example:
var nameField = title: 'We would like to know your name' promptLabel: 'What is your name?'; nameFieldprompt { if err console; else console; };
Chainable function example:
var ageField = fields.text({
title: 'What is your age?',
description: 'We promise not to tell anyone',
validate: function (value) {
return /^\d+$/.test(value);
}
});
ageField.prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('You entered ' + value);
}
});
Callback validation example:
fields.text({
title: 'What is your favorite food?'
validate: function (value, callback) {
callback(null, value.toLowerCase());
}
}).prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('You entered ' + value);
}
});
fields.File(opts)
Creates a new File field.
-
{object}
opts
File field options.-
File field specific options:
-
{object}
opts.formatters
An object of specific formatting functions.
-
{function}
opts.formatters.desc(string)
Custom field description formatter.
-
{function}
opts.formatters.error(Error|string)
Error message formatter.
-
{function}
opts.formatters.title(string)
Custom field title formatter.
-
-
{regexp}
opts.ignoreDirs
A regular expression of directory names to ignore when autocompleting.
-
{regexp}
opts.ignoreFiles
A regular expression of filenames to ignore when autocompleting.
-
{boolean}
opts.showHidden
If true, will display files beginning with a '.' in the autocomplete results. Defaults to
true
.
-
-
Autocomplete options:
-
{boolean}
opts.complete
If true, will autocomplete the current entry when the key is entered. Default value is
false
.
-
-
Standard options:
-
{boolean}
opts.colors
Enables text being rendered with color. Default value is
true
. -
{string}
opts.default
The default value. Returned when the user enters an empty value at the prompt.
-
{string}
opts.defaultLeft
A string displayed before the default value in the prompt. Default value is
'['
. -
{string}
opts.defaultRight
A string displayed after the default value in the prompt. Default value is
']'
. -
{string}
opts.desc
The description to print below the title, but above the prompt.
-
{boolean}
opts.hidden
When true, the value is still prompted, but it's not apart of the results. Useful for decisions in a
Set
. -
{string}
opts.mask
The character to be rendered when entering a password. The mask must be 1 character. Default value is
'*'
. -
{function}
opts.next(err, value, callback)
When this field is being prompted in a
Set
, thenext()
function is called after prompting andvalidate()
has completed to tell theSet
which field to visit next.If
validate()
fails andrepromptOnError
==true
, thennext()
is not called since the field will continue to re-prompt untilvalidate()
passes.next()
may return the name or index of the next field or call the suppliedcallback()
with the name or index of the next field to visit.If
next()
returns nothing orundefined
, it will assume you are planning on calling the suppliedcallback
function.If
next()
returnsnull
, then theSet
will proceed to the next field.If
next()
returnsfalse
, then it will tell theSet
to stop prompting. -
{boolean}
opts.password
Treat input as a secret.
-
{string}
opts.promptLabel
The label to display before prompt.
-
{array<string>}
opts.promptValues
The values to print between the
promptLabel
and the prompt input. -
{string}
opts.promptValuesLeft
A string displayed before the
promptValues
. Default value is'('
. -
{string}
opts.promptValuesRight
A string displayed after the
promptValues
. Default value is')'
. -
{string}
opts.promptValuesSeparator
A string used to separate the prompt values. Default value is
'|'
. -
{boolean}
opts.repromptOnError
If the field has a
validate()
function, validation fails, andrepromptOnError
istrue
(default), then it will reprompt for the value again.If
repromptOnError
is false, then it will stop prompting. This is useful when you have aSet
and you need to prompt for multiple values, then possibly return to a previous field if validation fails.For example, you prompt for a username and password, but authentication fails, you may want to re-prompt for the username again.
Default value is
true
. -
{string}
opts.separator
A string displayed after the prompt, but before the prompt input. Default value is
': '
. -
{string}
opts.title
The title to print above the prompt.
-
{boolean}
opts.trim
Trim the input after entered. Default value is
true
. -
{function}
opts.validate(value, callback(err, value), field)
A function to be called when a value is submitted. The
validate()
function is passed in thevalue
and acallback
.If the
validate()
function returnstrue
, validation passes.If it returns
false
, validation fails.If it returns
undefined
, then it will wait for thecallback()
parameter to be called. Thecallback(err, value)
function MUST pass thevalue
back. This allows thecallback()
to not only validate, but modify the value.
-
-
Returns a File
field instance with the following properties:
-
{function}
prompt(callback)
-
{function}
callback(err, value)
A function that is called when prompting has completed.
-
-
{Set}
set
If the field is apart of a
Set
, then this property will reference the set, otherwiseset
will benull
.
Events:
-
pre-prompt
Emitted before the current field is prompted.
{object}
field
The current field
-
post-prompt
Emitted after the current field has been prompted.
{object}
field
The current field{anything}
err
The error if something failed{string}
result
The result after the prompting
Example:
fields.file({
title: 'Enter the project directory',
desc: 'Any directory will do',
complete: true,
showHidden: false,
ignoreDirs: /^(\.svn|\.git|\.hg)$'/,
ignoreFiles: /^(\.gitignore|\.npmignore|\.cvsignore|\.DS_store|\._\*)$/
}).prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('You entered ' + value);
}
});
fields.Select(opts)
Creates a new Select field.
-
{object}
opts
Select field options.-
Select field specific options:
-
{boolean}
opts.autoSelectOne
If
true
and theoptions
array contains a single entry, then it will skip the prompting and immediately call the callback. Default value isfalse
. -
{string}
opts.display
Controls how autocomplete results are printed. Possible values are
'grid'
,'list'
, and'prompt'
. Default value is'list'
. -
{object}
opts.formatters
An object of specific formatting functions.
-
{function}
opts.formatters.desc(string)
Custom field description formatter.
-
{function}
opts.formatters.error(Error|string)
Error message formatter.
-
{function}
opts.formatters.option(string)
Custom select list option formatter.
-
{function}
opts.formatters.title(string)
Custom field title formatter.
-
-
{boolean}
opts.ignoreCase
When
true
, ignores the case of the value being entered. Default value isfalse
. -
{string}
opts.margin
A string to print in the left margin for each item being rendered. Default value is two spaces.
-
{boolean}
opts.numbered
If
true
, prints numbers for each list option in which the user can select the item by entering the number. Default value isfalse
. -
{array<object>}
opts.options
An array of options to display. Each option should have a label and a value. You can name these properties whatever you'd like as long as you specify their name using the
optionLabel
andoptionValue
options. -
{string}
opts.optionLabel
The name of the key in each option's object that contains the label to print for the option. Default value is
'label'
. -
{string}
opts.optionValue
The name of the key in each option's object that contains the value that is submitted if the option is selected. Default value is
'value'
. -
{boolean}
opts.relistOnError
If
true
, after a invalid option is selected, then it will re-display all available options. Default value isfalse
. -
{object}
opts.i18nStrings
An object containing internationalized strings. There currently are only two strings that would need to be translated:
-
'Invalid selection "%s"'
-
'Please select a valid option'
-
-
{boolean}
opts.suggest
If
true
, it will display a list of possible suggestions that closest match the submitted value. This uses the levenshtein algorithm to compare the value with possible values. Default value isfalse
. -
{number}
opts.suggestThreshold
A threshold for the levenshtein algorithm. Default value is
3
. You may want to use2
if matching short strings. -
{boolean}
opts.zeroSkip
If
true
andnumbered
istrue
, then allows the user to enter zero to select nothing. Default value isfalse
.
-
-
Autocomplete options:
-
{boolean}|{array<string>}
opts.complete
If a boolean and
true
, will autocomplete thevalue
when the key is entered. Default value isfalse
.If value is an array of strings of key names, then it will autocomplete the values based specified option key name values. For example, if you set
complete: ['id', 'value']
, then it will autocomplete either theid
or thevalue
. -
{boolean}
opts.completeIgnoreCase
If true, will ignore case when finding matches. Default value is
false
.
-
-
Standard options:
-
{boolean}
opts.colors
Enables text being rendered with color. Default value is
true
. -
{string}
opts.default
The default value. Returned when the user enters an empty value at the prompt.
-
{string}
opts.defaultLeft
A string displayed before the default value in the prompt. Default value is
'['
. -
{string}
opts.defaultRight
A string displayed after the default value in the prompt. Default value is
']'
. -
{string}
opts.desc
The description to print below the title, but above the prompt.
-
{boolean}
opts.hidden
When true, the value is still prompted, but it's not apart of the results. Useful for decisions in a
Set
. -
{string}
opts.mask
The character to be rendered when entering a password. The mask must be 1 character. Default value is
'*'
. -
{function}
opts.next(err, value, callback)
When this field is being prompted in a
Set
, thenext()
function is called after prompting andvalidate()
has completed to tell theSet
which field to visit next.If
validate()
fails andrepromptOnError
==true
, thennext()
is not called since the field will continue to re-prompt untilvalidate()
passes.next()
may return the name or index of the next field or call the suppliedcallback()
with the name or index of the next field to visit.If
next()
returns nothing orundefined
, it will assume you are planning on calling the suppliedcallback
function.If
next()
returnsnull
, then theSet
will proceed to the next field.If
next()
returnsfalse
, then it will tell theSet
to stop prompting. -
{boolean}
opts.password
Treat input as a secret.
-
{string}
opts.promptLabel
The label to display before prompt.
-
{array<string>}
opts.promptValues
The values to print between the
promptLabel
and the prompt input. -
{string}
opts.promptValuesLeft
A string displayed before the
promptValues
. Default value is'('
. -
{string}
opts.promptValuesRight
A string displayed after the
promptValues
. Default value is')'
. -
{string}
opts.promptValuesSeparator
A string used to separate the prompt values. Default value is
'|'
. -
{boolean}
opts.repromptOnError
If the field has a
validate()
function, validation fails, andrepromptOnError
istrue
(default), then it will reprompt for the value again.If
repromptOnError
is false, then it will stop prompting. This is useful when you have aSet
and you need to prompt for multiple values, then possibly return to a previous field if validation fails.For example, you prompt for a username and password, but authentication fails, you may want to re-prompt for the username again.
Default value is
true
. -
{string}
opts.separator
A string displayed after the prompt, but before the prompt input. Default value is
': '
. -
{string}
opts.title
The title to print above the prompt.
-
{boolean}
opts.trim
Trim the input after entered. Default value is
true
. -
{function}
opts.validate(value, callback(err, value), field)
A function to be called when a value is submitted. The
validate()
function is passed in thevalue
and acallback
.If the
validate()
function returnstrue
, validation passes.If it returns
false
, validation fails.If it returns
undefined
, then it will wait for thecallback()
parameter to be called. Thecallback(err, value)
function MUST pass thevalue
back. This allows thecallback()
to not only validate, but modify the value.
-
-
Returns a Select
field instance with the following properties:
-
{function}
prompt(callback)
-
{function}
callback(err, value)
A function that is called when prompting has completed.
-
-
{Set}
set
If the field is apart of a
Set
, then this property will reference the set, otherwiseset
will benull
.
If an option label contains double underscores that wrap a character like
some__t__hing
, then t
will become an accelerator that automatically maps t
with something
. Use the accelerator
style to style it.
Events:
-
pre-prompt
Emitted before the current field is prompted.
{object}
field
The current field
-
post-prompt
Emitted after the current field has been prompted.
{object}
field
The current field{anything}
err
The error if something failed{string}
result
The result after the prompting
Simple example:
var list = new fields.Select({
title: 'What is your favorite milkshake?',
options: [
'__v__anilla',
'stra__w__berry',
'cho__c__olate'
],
complete: true,
suggest: true
});
list.prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('Your favorite milkshake is ' + value + '. Yum!');
}
});
Slightly more complex example:
fields.select({
title: 'Select a UUID by number or name',
formatters: {
option: function (opt, idx, num) {
return ' ' + num + opt.value.cyan + ' ' + opt.name;
}
},
numbered: true,
relistOnError: true,
complete: true,
suggest: true,
options: {
'Available UUIDs:': [
{ name: 'uuid 1', value: '43C5E7DE-F6BB-4AEF-98F0-0A33990EA280' },
{ name: 'uuid 2', value: '4F562E96-C933-4367-B6BD-89CA7D6EE400' },
{ name: 'uuid 3', value: '31D3AC10-99F4-43E1-997B-980E70EC706B' },
{ name: 'uuid 4', value: 'E1512AE0-FEBB-43A2-9C9C-E1D2F4D6C51F' },
{ name: 'uuid 5', value: 'F624D6BA-5FF3-4E48-B9F2-BC7DD1A8EA97' },
{ name: 'uuid 6', value: '3C12C8D9-C05F-4834-BA7E-9C55CB8C9287' },
{ name: 'uuid 7', value: 'BB91EDBF-2A97-4227-B5B2-5943BAB30304' },
{ name: 'uuid 8', value: '204C6E4A-FA9C-48BB-9D84-709A10A690AB' },
{ name: 'uuid 9', value: '05282F35-42BB-40F3-8C20-3EC1739AB414' },
{ name: 'uuid 10', value: '5EC586D9-7E2B-4F55-834D-CD8199DD92B8' },
{ name: 'uuid 11', value: 'A4BD1980-8C4B-4DBB-8FBE-5A52E36DFA63' },
{ name: 'uuid 12', value: '99C49052-E280-48D3-B881-E8112B7DFCF1' },
{ name: 'uuid 13', value: 'A057301B-B38D-40B6-A6A4-B582AE5EAABE' },
{ name: 'uuid 14', value: 'D39B019B-3EF0-4BCA-A1E9-FC2F5063097F' },
{ name: 'uuid 15', value: 'C9A11E0C-5FF4-4B55-890F-F7715194CAB3' },
{ name: 'uuid 16', value: 'B1E31DD0-8968-4A32-B210-A0558302F65B' }
]
}
}).prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('You selected ' + value);
}
});
fields.Set(fields, opts)
Creates a new field Set. Sets batch prompt several fields including other sets.
-
{object|array}
fields
An object or array of field instances to prompt for. -
{object}
opts
Select field options.-
{string}
opts.fieldSeparator
A string to render between each field being prompted. Default value is
'\n'
. -
{boolean}
opts.stopOnError
If
true
and a field'svalidate()
fails, then theSet
will stop prompting, otherwise iffalse
, it will continue to the next field. Default value istrue
. You may want to set thisfalse
when usingrepromptOnError=false
(seerepromptOnError
).
-
Returns a Set
field instance with the following properties:
-
{function}
prompt(callback)
-
{function}
callback(err, value)
A function that is called when prompting has completed.
-
Events:
-
pre-prompt
Emitted before the current field is prompted.
{object}
field
The current field
-
post-prompt
Emitted after the current field has been prompted.
{object}
field
The current field{anything}
err
The error if something failed{string}
result
The result after the prompting
Object-based example:
fields.set({
something: fields.text({
promptLabel: 'Username',
validate: function (value, callback) {
callback(!value.length && new Error('Please enter a username'), value);
}
}),
changePass: fields.select({
promptLabel: 'Change password?',
display: 'prompt',
options: [ 'yes', 'no' ],
next: function (value) {
if (value == 'no') {
return 'favfood';
}
}
}),
password: fields.text({
promptLabel: 'Enter a password',
password: true,
validate: function (value, callback) {
callback(!value.length, value);
}
}),
favfood: fields.text({
promptLabel: 'What is your favorite food?'
})
}, { stopOnError: true }).prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('You entered ' + value);
}
});
Array-based example:
fields.set([
fields.text({
promptLabel: 'Username',
validate: function (value, callback) {
callback(!value.length, value);
}
}),
fields.select({
promptLabel: 'Change password?',
display: 'prompt',
options: [ 'yes', 'no' ],
next: function (value) {
if (value == 'no') {
return 3;
}
}
}),
fields.text({
promptLabel: 'Enter a password',
password: true,
validate: function (value, callback) {
callback(!value.length, value);
}
}),
fields.text({
promptLabel: 'What is your favorite food?'
})
]).prompt(function (err, value) {
if (err) {
console.error('There was an error!\n' + err);
} else {
console.log('You entered ' + value);
}
});
License
(The MIT License)
Copyright (c) 2013-2014 Chris Barber
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.