# @lvchengbin/interactive

> A simple utility for building togglable interactive cli tool easily in node.js.

Latest version **0.0.2** (published 2018-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @lvchengbin/interactive
pnpm add @lvchengbin/interactive
yarn add @lvchengbin/interactive
bun add @lvchengbin/interactive
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2018-09-07 |
| First published | 2018-09-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 16.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | LvChengbin |
| Maintainers | lvchengbin |
| Keywords | interactive, cli, command, readline, stdin |

## Links

- npm: https://www.npmjs.com/package/@lvchengbin/interactive
- Repository: https://github.com/LvChengbin/interactive
- Homepage: https://github.com/LvChengbin/interactive#readme
- Issues: https://github.com/LvChengbin/interactive/issues
- npm.io page: https://npm.io/package/@lvchengbin/interactive

## Dependencies (4)

- [cli-style](https://npm.io/package/cli-style.md) 0.0.3
- [strip-ansi](https://npm.io/package/strip-ansi.md) ^4.0.0
- [@lvchengbin/is](https://npm.io/package/@lvchengbin/is.md) 0.0.22
- [@lvchengbin/escape](https://npm.io/package/@lvchengbin/escape.md) 0.0.3

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.0.2 (latest) — 2018-09-07
- 0.0.1 — 2018-09-07
- 0.0.0 — 2018-09-07

## README

# Interactive

A simple utility for building togglable interactive cli tool easily in node.js.

<!-- vim-markdown-toc GFM -->

* [Installation](#installation)
* [Usage](#usage)
    * [Command Completion](#command-completion)
    * [Toggle Interactive Mode](#toggle-interactive-mode)
    * [Shortcut Keys](#shortcut-keys)
* [API](#api)
    * [new Interactive( options )](#new-interactive-options-)
    * [start()](#start)
    * [pause()](#pause)
    * [toggle()](#toggle)
    * [close()](#close)
    * [prompt( tag )](#prompt-tag-)
* [Events](#events)
    * [Event:start](#eventstart)
    * [Event:pause](#eventpause)
    * [Event:close](#eventclose)
    * [Event:command](#eventcommand)
    * [Event:keypress](#eventkeypress)

<!-- vim-markdown-toc -->

## Installation

```bash
$ npm i @lvchengbin/interactive --save
```
## Usage

An example is always a better way for starting:

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

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

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

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

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

---
_Source: https://npm.io/package/@lvchengbin/interactive · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._