Cline and creating an interactive command line application

Regardless of how great your love for the command line is, agree that the simple and convenient console interface, history support, auto addition, simple commands are quite impressive. Without going into discussions about the advantages and disadvantages of the “darkness”, I want to submit to the Habra community a small craft from the world of Node.js, whose main task is to improve the life of the developer who decided to write a console utility.

Cline Overview

Cline is a small library based on the readline nodovsky module, so we have history support, auto addition, user interrogation and, with my light hand, additions in the form of a password input mask, the ability to listen to user input as separate commands described as simple or regular expressions, help output, simplified work with history, interactive mode.

With all this, creating an application that, once launched, will wait for commands from the user to be entered at times easier.

')

Example

For those who have enough code to understand the library’s capabilities, here’s an example:

Using

Cline uses Interface or something similar to it in its work, if you have your own implementation of Interface, you can pass it as a parameter (testing support):

 var cli = require('cline')(myInterface); 

The central cline feature is the addition of commands.

 cli.command(expression, description, parameters, callback); 

expression is an expression that we expect from the user, can contain dynamic parameters, for example, kill {id}, here id is the name of the dynamic parameter, I will remind about it later.

description - additional explanation for the command, used to generate help.

parameters - an object containing the names of dynamic parameters referred to in expressions, as keys, and regular expressions, as values. For example, {id: '\\ d +'} - id would mean any number.

callback is the function that will be called when the user enters the string corresponding to expression. It is called with two arguments: a string from the user and an object with the values ​​of dynamic parameters.

 cli.command('kill {id}', 'kill task by id', {id: '\\d{1,3}'}, function (input, args) { console.log(input) // kill 12 console.log(args.id) // 12 }); 

All cli.command parameters, except for expression, are optional, with which you can skip as you please.

 cli.command(expression, description, callback); cli.command(expression, parameters, callback); cli.command(expression, description); cli.command(expression, parameters); 

All these options are absolutely valid.

User interaction

You can expect 3 things from the user:

1. Input

 cli.prompt('Your turn:'); 

2. Confirmation

 cli.confirm('Sure?', function (ok) {}); 

3. Password

 cli.password('Password:', '*', function (pass) {}); 

And also you can just go online

 cli.interact('>'); 

In this mode, the library waits for input from the user and tries to interpret each line as a command, looking for matches in the list of described commands, and after executing the listener function on the command, again waits for input. Recalling the interactive mode will simply change the prompt.

System commands, history and events

Without any additional manipulations when using cline, 3 commands are immediately available:
clear or \ c - clears the screen

help or \? - displays help

exit or \ q - exit

Everything is simple with history, no files or streams, just fill in the history like this:

 cli.history(['start', 'stop']); 

the order of the elements corresponds to the age; the first element in the list will be the oldest.
Well, you can read the story like this:

 cli.history(); 

get the list. You can also subscribe to the event of adding an item to the history. Well, then you decide how to save this list.

Since the cline inherits from EventEmitter, the event model is widely used here, you can subscribe to such events:
close - the user called an exit command or stopped the process using Ctrl + C

history - when a new item is added to the history, the new item is passed to the listener as a parameter.

command - the user's input coincided from one of the commands (except system), the string from the user and the command expression are passed as a parameter to the listener.

At last

If you do not want to be silent silently when the user enters something other than the commands that you described, do this:

 cli.command('*', function (input) { console.log(input + ' is not correct'); cli.usage(); }); 

Thank you very much for your attention, I hope you find cline useful, or maybe even inspire you to write your console utility, or at least a fork in a githaba .

PS Special thanks to UFO for an invite.