Interactive
A simple utility for building togglable interactive cli tool easily in node.js.
Installation
$ npm i @lvchengbin/interactive --save
Usage
An example is always a better way for starting:
const Interactive = require( '@lvchengbin/interactive' );
const interactive = new Interactive( {
title : 'Interactive Mode',
prompt : '~~> ',
instructions : {
start : 'Start Interactive Mode',
pause : 'Pause Interactive Mode'
},
oo : 'CTRL+Y',
keys : {
'show .' : '\b'
},
completions : [ 'show', 'hide' ],
exit : true,
help : {
show : 'Help information for "show" command.',
hide : 'Help information for "hide" command.'
}
} );
interactive.on( 'command', command => {
console.log( 'command: ', command );
if( command === 'change prompt' ) {
interactive.prompt( 'New Prompt> ' );
} else {
interactive.prompt();
}
} );
interactive.start();
Command Completion
You can provide a completion
list in options, and this list will be used in completor
function:
const Interactive = require( '@lvchengbin/interactive' );
const interactive = new Interactive( {
title : 'Interactive Mode',
prompt : '~~> ',
completions : [ 'command1', 'command2' ],
} );
interactive.start();
Toggle Interactive Mode
The interactive mode can be started and paused by calling interactive.start()
and interactive.pause()
, and even you can use interactive.close()
to close it throughly.
There are another two ways for switching between active(started) and inactive(paused) mode:
- instructions.start and instructions.pause
- on-off option
For example:
const Interactive = require( '@lvchengbin/interactive' );
const interactive = new Interactive( {
instructions : {
start : 'Start Interactive Mode',
pause : 'Pause Interactive Mode'
},
oo : 'CTRL+Y'
} );
interactive.start();
In the code above, instructions.start
is set to Start Interactive Mode
and instructions.pause
is set to Pause Interactive Mode
. That means you can start or pause the interactive mode by typing these two commands. The oo
option specified a shortcutkey for toggle the interactive mode.
Shortcut Keys
You can specify some shortcut keys for particular commands, for example:
const Interactive = require( '@lvchengbin/interactive' );
const interactive = new Interactive( {
keys : {
'command arg1 arg2' : [ 'CTRL+Y', '\u000c' ]
}
} );
interactive.on( 'command', () => { } );
interactive.start();
With the code above, while the input equal to CTRL
+Y
or equal to \u000c
, the command event will be emitted with command command arg1 arg2
.
API
new Interactive( options )
To create a new instance, and it will start to listen to the input.
options
-
title
String
The title of the application. -
prompt
String
The default prompt string. -
instructions
Object
To specify special instructions:- start: start the interactive mode
- pause: pause the interactive mode
-
oo
String
Array
A shortcut key used to toggle interactive mode. -
keys
Object
A map for defining shortcut keys for particular comamnds that the key should be the command, and the value should be aString
or anArray
of keys. -
completions
Array
A command list which will be used for completion. Thehelp
,man
and?
commands will be append into the completion list if thehelp
option is set. Theexit
andquit
commands will be append into the completion list if theexit
option is set totrue
. -
completor
Function
To speciy your own completor. -
exit
Boolean
By setting this options to true, the interactive mode will be exited with commandexit
andquit
. -
help
String
Object
The help information which will be shown withhelp
command. If this option is an object, thehelp <key>
command will show the information of corresponding value of thekey
.
start()
To start the interactive mode.
pause()
To pause the interactive mode.
toggle()
To toggle the interactive mode.
close()
To close the interactive mode throughly, this method will close the readline.Interface
.
prompt( tag )
To set and show the prompt.
Events
Event:start
The 'start'
event is emitted when the interactive mode start.
Event:pause
The 'pause'
event is emitted when the interactive mode pause.
Event:close
The 'close'
event is emitted when the interactive mode close
Event:command
The 'command'
event is emitted while getting new command.
Event:keypress
The 'keypress'
event is emitted while any keys are pressed. The callback function will accept two arguments, the chunk
and the key
object.