Skip to content

Latest commit

 

History

History
160 lines (117 loc) · 7.64 KB

README.md

File metadata and controls

160 lines (117 loc) · 7.64 KB
Raw

ttty

A dead simple lightweight TypeScript terminal "emulator" that mimics terminal behaviour in browser.

Features:

  • Tiny, dependency-free and built with modern JS
  • Easy-to-add custom commands
  • Events
  • Command history
  • Command arguments with validation
  • "Foreground processes" imitation

Usage

With module bundler

Add the latest release with:

npm install ttty or yarn add ttty

Initialize the terminal in a particular DOM element with:

import { initTerminal } from 'ttty'

// ...

const terminal = initTerminal({ /* settings */ })

In a browser directly

<!-- As a global JS file -->
<script src="https://unpkg.com/ttty/dist/ttty.iife.js"></script>
ttty.initTerminal({ /* settings */ })

Initialize with parameters:

const settings = {
    host: document.querySelector("#terminal"),
    prompt: "user@ttty:~$ ",
    commands: {
        echo: {
            name: "echo", 
            description: "a test command with one echo arg", 
            argDescriptions: ["a string to be echoed in console"],
            func: ({ print }, argument) => { print(argument) } 
        },
        test: {
            name: "test", 
            description: "a test command with no args", 
            func: ({ print }) => { print("foo") } 
        },
        multiply: {
            name: "multiply",
            description: "Multiply two numbers",
            argDescriptions: ["number one", "number two"],
            func: ({ print }, one, two) => { print(Number(one) * Number(two)) }
        }
    }
}

initTerminal(settings)

Working with the terminal

help - Display a list of all commands with descriptions

command - Execute a command. Will display "Usage: command [parameter 1 description] [parameter 2 description], etc.", when it requires arguments but is called without them.

API

initTerminal

Method Description Parameters
init(settings) Initialize a terminal in a given DOM element settings object.

terminal

An object that's being passed to every command function & returned by initTerminal

Method Description Parameters
print(text, isCommand) Prints a given text in the terminal (accepts raw HTML) text - String, isCommand - Boolean, optional, defaults to false. Count given string as a command (displays prompt & syntax highlight)
run(text) Emulates a command execution in a terminal (acts the same way as a user would have typed and pressed Enter) text - String
start() Starts a "foreground process": user input is blocked and command prompt never appears.
stop() Stops "foreground process".
type(text, speed, isCommand) => Promise<boolean> Prints a text with "typing" effect. Hides and blocks user input while typing. Resolves to either true or false depending on process interruption by the user. text - String, text to be printed. speed - integer, miliseconds. The higher the number, the slower. isCommand - Boolean, optional, defaults to false. Count given string as a command (displays prompt & syntax highlight)
setPrompt() Set terminal prompt newPrompt - String

settings object

Parameter Description Default
host: DOM element A DOM element to initialize terminal in.
welcomeMessage: string A welcome message that is being printed on initialization
enableHelp: boolean Toggle default help command that lists all the available commands and their descriptions. true
prompt: string Terminal prompt '$: '
historyLength: number A maximum amount of commands that can be stored in the terminal history 50
history: string[] A default value for terminal history (can be used to preserve history across sessions) []
commands: object commands object

commands object

Parameter Description
name: string Command name.
description: string Command description, used for the default help command (when enabled).
argDescriptions: string array Array of strings that describe command line arguments in order of appearance.
func: function(terminal, ...arguments) Function. Accepts an array of parameters in order of appearance (i.e. function(terminal, one, two) will correspond to two arguments passed as command one two)

Events

Event Description
onInit Terminal initialization
onCommand Existing command executed
onCommand404 Non-existing command executed
onProcessStart Process started
onProcessStop Process stopped
onProcessInterrupt Process interrupted with a keyboard

Events are being dispatched by the DOM element passed on init, for example:

const term = document.getElementById('terminal');
term.addEventListener('onCommand', e => console.log("known command executed!"));

Custom styling

You can customize the look defining custom CSS variables. If you have multiple instances, you can even have each instance in its' own style!

Variable Description
--terminal-bg-color Background color
--terminal-fg-color Text color
--terminal-font Terminal font-family
--terminal-accent-color Accent color
--terminal-error-color Error color

Browser compatibility

ttty is built and distributed with ES6 in mind (including the minified package). You can always transpile & bundle it targeting your browser set of choice.

Browsers that do not support CSS variables (IE < 11) might not be able to make use of custom themes. In order to use ttty with older browsers please rebuild this with custom properties removed.