paolo-projects / terminal-emulator

A nodeJs browser library for emulating a terminal, with command and argument parsing

Terminal Emulator

A nodeJs browser library for emulating a terminal, with command and argument parsing, and definition of schemes with callbacks.

Guide

To build your terminal-like interface for web or nodejs based applications, you start from the TerminalEmulator class.

You create an instance of it and set it up with the necessary parameters.

Another important player is the OutputStream class. You have to create your own subclass implementing two methods:

• abstract write(message: string): void;
• abstract clear(): void;

The implementation of these methods depends upon whether you're using an HTML div element, a plain string, a console for output, etc.

After you istantiated the class you provide command schemes to it.

A command scheme can be added through the .command(...) method on the emulator class and by providing a combination of command name, parameter types and a callback, you define a scheme.

After you defined your schemes with your callbacks, you then call the .parse(string) method on the emulator, and it will tokenize the command line, parse the tokens and assign them to the appropriate category (command name, positional argument, flag argument, value argument). It will then check the schemes and when a match is found it will call the callback defined into the scheme, which is defined like so:

type CommandSchemeMatchCallback = (
    command: string,
    args: ArgumentList,
    outputStream: OutputStream
) => Promise<boolean>;

The callback returns a promise to support async operations. This is needed when a command executes an HTTP request, or file I/O, to correctly signal the end of the operation to the caller. For instance, it is needed when you want to disable the terminal input while the command is executing.

An example

This is an example OutputStream subclass that prints to the debug console.

class ConsoleOutputStream extends OutputStream {
    constructor() {
        super(''); // No end of line character as console.log prints a newline by default
    }
    write(message: string): void {
        console.log(message);
    }
    clear(): void {
        console.clear();
    }
}

You then istantiate the TerminalEmulator class and set it up with the OutputStream istance.

const stream = new ConsoleOutputStream();
const emulator = new TerminalEmulator(stream, new DefaultLocalization());

The localization parameter object consists of the strings to support localization of the error messages shown to the user.

Now you can start adding schemes to the emulator instance.

const callback = async (
    command: string,
    args: ArgumentList,
    outputStream: OutputStream
) => {
    const name = args.getArgument('name', ValueArgument<string>)?.value;
    outputStream.writeLine(`Hello, ${name}`);

    return true;
};

emulator.command('hello')
    .withValueArgument('name')
    .callback(callback);

You then parse your terminal input.

const cmdLine = 'hello --name John';
emulator.parse(cmdLine);

Output:

> hello --name John
  Hello, John

Argument types

The supported argument types are:

• Positional arguments

  Positional arguments don't require a flag indicating the parameter name, you just place them next to the command like this:

  command arg1 arg2 arg3 ...

  .command('hello').withPositionalArgument();

• Flag arguments

  Flag arguments are like a switch. When added to the command, the application knows that something has to be done. Example:

  command --arg

  .command('hello').withFlagArgument('arg');

• Value arguments

  Value arguments are key/value type arguments. They're essentially a flag argument followed by a positional argument. Equivalent to options passed to the application, they specify how something has to be done, like in this example:

  bake --food bread --temperature high

  .command('hello').withValueArgument('food');

Help message

An help message is displayed every time a command is invoked with the --help flag argument. If more schemes sharing the same command are added, make sure you add the help message, through the .withHelpMessage(message) function on the builder class, to only one of the entries. Otherwise only the first entry with the help message will be displayed.

The help text will also be displayed when the command is invoked with wrong arguments.