@lvchengbin/interactive NPM

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 a String or an Array of keys.
completions Array A command list which will be used for completion. The help, man and ? commands will be append into the completion list if the help option is set. The exit and quit commands will be append into the completion list if the exit option is set to true.
completor Function To speciy your own completor.
exit Boolean By setting this options to true, the interactive mode will be exited with command exit and quit.
help String Object The help information which will be shown with help command. If this option is an object, the help <key> command will show the information of corresponding value of the key.