gavin/terminal-lab

Fork 0

Files

douboer@gmail.com 3b7c1d558a first commit

2026-03-03 13:23:14 +08:00

13 KiB

Raw Blame History

API Reference

XEventEmitter

Event emitter

Type

// Event Identifier
type IEventName = string | symbol;

// Event Listener
type IEventListener = (...args: unknown[]) => void;

type IEventHandler = (ev: IEventName, listener: IEventListener) => void;

interface IEventEmitter {
    on: IEventHandler;
    once: IEventHandler;
    off: IEventHandler;
    emit(ev: IEventName, ...args: unknown[]): void;
}

Details

Methods

on: Appends a event listener to the specified event

once: Appends a one-time event listener to the specified event

off: Removes an event listener from the specified event

emit: Triggers an event with arguments if any
See also: Guide - Events

XTerminal

Creates a terminal instance

Type

interface XTerminal {
    // ...
}

interface TerminalOptions {
    target: HTMLElement | string;
}

class Terminal extends XEventEmitter implements XTerminal {
    constructor(options: TerminalOptions);
}

Details

The constructor takes one argument, options containing the target element reference.

If the target element is provided, the term.mount() method is called automatically.

Example

import XTerminal from 'xterminal';

const term = new XTerminal({/* options */});

See also: Guide - Creating a Terminal

XTerminal.version

The version number

Type

interface XTerminal {
    readonly version: string;
}

Details

This is a static property that stores the version used. It is important when reporting bugs or issues.

Example

import XTerminal from 'xterminal';

console.log(XTerminal.version);

XTerminal.XEventEmitter

The event emitter class

Type

Same as XEventEmitter.
Details

This is a static property (class) that can be used to create independent instances of the event emitter

Example

const emitter = new XTerminal.XEventEmitter();

XTerminal.escapeHTML()

Escapes user input so it can be safely rendered as HTML text.

Type

interface XTerminal {
    static escapeHTML(data?: string): string;
}

Details

It preserves all characters by converting them to HTML entities where needed. This is recommended for use on user input or any arbitrary data.

Example

XTerminal.escapeHTML("<b>hello</b>");
// => &lt;b&gt;hello&lt;/b&gt;

See also: Guide - Safe Output

term.mount()

Mounts the terminal instance structure to the specified DOM element.

Type

interface XTerminal {
    mount(target: HTMLElement | string): void;
}

Details

It takes one argument that must be an actual DOM element or a CSS selector. The element's innerHTML is cleared first and then the terminal structure is rendered.

If no argument is passed, it throws an error and nothing is rendered.

The term.mount() method should only be called once for each terminal instance only if the target element option in the constructor is not provided.

Example

import XTerminal from 'xterminal';

const term = new XTerminal();
term.mount('#app');

or mount to an actual DOM element directly:

term.mount(
    document.getElementById('app')
);

See also: Guide - Creating a Terminal

term.dispose()

Gracefully close the terminal instance.

Type

interface XTerminal {
    dispose(): void;
}

Details

This detaches all event listeners, unmounts the terminal from the DOM and clears the backing functionality of the terminal.

The terminal should not be used again once disposed.

Example

Dispose on window unload event

window.onunload = () => term.dispose();

See also: Guide - Disposal

term.focus()

Focus the terminal input component - ready for input.

Type

interface XTerminal {
    focus(): void;
}

Details

This method takes no argument. It focuses the underlying input component of the terminal.

Clicking or tapping in the terminal also invokes the method.
Example

After mounting the terminal instance
```
term.focus();
```

term.blur()

Blurs the terminal input component.

Type

interface XTerminal {
    blur(): void;
}

Details

This method blurs the input component of the terminal.
Example
```
term.blur();
```

term.pause()

Deactivate the terminal input component.

Type

interface XTerminal {
    pause(): void;
}

Details

This method will stop events and input from being written to the terminal but rather input will be buffered.

NB: It is used in conjuction with term.resume().
Example

Prevent a user from sending input (non-interactive mode)
```
term.pause();
```
See also: Guide - Pause & Resume

term.resume()

Activate the terminal input component

Type

interface XTerminal {
    resume(): void;
}

Details

This method will enable events dispatch and user input if they were deactivate using term.pause().

Example

Pause the terminal until user input is required

term.pause();
// ...
// do something
// ...
term.resume();

See also: Guide - Pause & Resume

term.setInput()

Sets the value of the terminal input buffer

Type

interface XTerminal {
    setInput(value: string): void;
}

Details

This method will set/modify the contents of the input buffer.
Example

Presetting some input when the terminal is loaded or resumed
```
term.setInput("echo 'Hello World'");
```
See also: Guide - Set & Clear

term.clearInput()

Clears the terminal input buffer

Type

interface XTerminal {
    clearInput(): void;
}

Details

This method will empty/clear the contents of the input buffer.
Example

Clearing the input buffer when the terminal resumes
```
term.clearInput();
```
See also: Guide - Set & Clear

term.setCompleter()

Sets the autocomplete function that is invoked on Tab key.

Type

interface XTerminal {
    setCompleter(fn: (data: string) => string): void;
}

Details

This method take one argument that is a function which takes a string parameter and returns a string.

The autocomplete functionality depends highly on the completer function fn.

The fn parameter should return a better match for the input data string.

Example

term.setCompleter(data => {
    const options = ['.help', '.clear', '.exit'];
    return options.filter(s => s.startsWith(data))[0] || '';
});

See also: Guide - Autocomplete

term.write()

Write data to the terminal.

Type

interface XTerminal {
    write(data: string | number, callback?: () => void): void;
}

Details

data: The data to write to the terminal

callback: Optional function invoked on successful write

Example

term.write('John: Hello ');
term.write('from the Eastside', () => console.log('Done!'));

See also: Guide - Output

term.writeln()

Write data to the terminal, followed by a break line character (\n).

Type

interface XTerminal {
    writeln(data: string | number, callback?: () => void): void;
}

Details

data: The data to write to the terminal

callback: Optional function invoked on successful write

Example

term.writeln('Hello World!');
term.writeln('Welcome!', () => console.log('Done!'));

See also: Guide - Output

term.writeSafe()

Securely write data to the terminal.

Type

interface XTerminal {
    writeSafe(data: string | number, callback?: () => void): void;
}

Details

data: The data to write to the terminal

callback: Optional function invoked on successful write

Example

term.writeSafe('<h1>hello</h1>');
// &lt;h1&gt;hello&lt;/h1&gt;

See also: Guide - Output

term.writelnSafe()

Securely write data to the terminal, followed by a break line character (\n).

Type

interface XTerminal {
    writelnSafe(data: string | number, callback?: () => void): void;
}

Details

data: The data to write to the terminal

callback: Optional function invoked on successful write

Example

term.writelnSafe('<h1>hello</h1>');
// &lt;h1&gt;hello&lt;/h1&gt;<br/>

See also: Guide - Output

term.clear()

Clear the entire terminal.

Type

interface XTerminal {
    clear(): void;
}

Details

When invoked, the entire terminal output is cleared.

This method also triggers the clear event.

Example

Clear on CTRL+L using keypress event

term.on('keypress', e => {
    if (e.key == 'l' && e.ctrlKey) {
        term.clear();
    }
});

See also: Guide - Example using events
See also: Guide - Output

term.clearLast()

Remove the element containing the previous output.

Type

interface XTerminal {
    clearLast(): void;
}

Details

This is like the undo for only one write operation.

Example

Greet with Hello World and replace it with Hello Dev after 5 seconds

term.writeln('Hello World!');
setTimeout(() => {
    term.clearLast();
    term.write('Hello Dev!');
}, 5000);

See also: Guide - Output

term.history

Access the history stack.

Type

interface XTerminal {
    history: string[];
}

Details

Manages an array of entries in the history stack.

Example

Log the history whenever a new entry is added

term.on('data', () => console.log(term.history));

See also: History

term.clearHistory()

Clear the entire history stack.

Type

interface XTerminal {
    clearHistory(): void;
}

Details

It take no argument as its sole role is to clear the entire local history of inputs which are accessible iteratively using ArrowUp and ArrowDown keys.

Example

Clear history on CTRL+H using keypress event

term.on('keypress', e => {
    if (e.ctrlKey && e.key == 'h') {
        term.clearHistory();
    }
});

See also: History

13 KiB Raw Blame History

API Reference

Application

Input

Output

History

XEventEmitter

XTerminal

XTerminal.version

XTerminal.XEventEmitter

XTerminal.escapeHTML()

term.mount()

term.dispose()

term.focus()

term.blur()

term.pause()

term.resume()

term.setInput()

term.clearInput()

term.setCompleter()

term.write()

term.writeln()

term.writeSafe()

term.writelnSafe()

term.clear()

term.clearLast()

term.history

term.clearHistory()

13 KiB

Raw Blame History