Class Shell
Source: shell.ts
A Unix-like shell emulator that handles command parsing, environment management, autocompletion, and process I/O.
Constructors
Constructor
new Shell(
config:ShellConfig):Shell
Parameters
config
Returns
Properties
state
state:
ShellState
The reactive state of this shell.
config
config:
ShellConfig
The configuration used to initialize this shell.
env
env:
ShellEnvironment
The environment variable manager for this shell.
interpreter
interpreter:
ShellInterpreter
The logic handler for parsing and executing command strings.
MISSING_ARGS_ERROR
readonlystaticMISSING_ARGS_ERROR:"requires at least 1 argument"="requires at least 1 argument"
MISSING_OPTIONS_ERROR
readonlystaticMISSING_OPTIONS_ERROR:"requires at least 1 option"="requires at least 1 option"
COMMAND_FAILED_ERROR
readonlystaticCOMMAND_FAILED_ERROR:"Command failed"="Command failed"
USAGE_ERROR
readonlystaticUSAGE_ERROR:"Incorrect usage"="Incorrect usage"
INVALID_PATH_ERROR
readonlystaticINVALID_PATH_ERROR:"No such file or directory"="No such file or directory"
SUDO_COMMAND
readonlystaticSUDO_COMMAND:"sudo"="sudo"
Methods
handleKeyDown()
handleKeyDown(
event:Pick<KeyboardEvent<Element>,"key"|"preventDefault"> &Partial<Pick<KeyboardEvent<Element>,"ctrlKey"|"metaKey"|"shiftKey">>):Promise<void>
Parameters
event
Pick<KeyboardEvent<Element>, "key" | "preventDefault"> & Partial<Pick<KeyboardEvent<Element>, "ctrlKey" | "metaKey" | "shiftKey">>
Returns
Promise<void>
setRawMode()
setRawMode(
rawMode:boolean):void
Toggles raw mode, which forwards all keystrokes directly to the active stream.
Parameters
rawMode
boolean
Whether to enable raw mode.
Returns
void
terminate()
terminate(
signal?:StreamSignal):void
Sends a signal to the shell or the currently active foreground process.
Parameters
signal?
StreamSignal = "SIGTERM"
The signal to send. Defaults to "SIGTERM".
Returns
void
interrupt()
interrupt():
void
Convenience method to send the SIGINT (Interrupt) signal.
Returns
void
See
kill()
kill():
void
Convenience method to send the SIGKILL (Kill) signal, closing the shell.
Returns
void
See
updatePrompt()
updatePrompt():
Promise<void>
Refreshes the prompt string based on the current user, hostname, and working directory.
Returns
Promise<void>
setLine()
setLine(
value:string| ((prev:string) =>string)):void
Updates the text in the current input line.
Parameters
value
string | ((prev: string) => string)
The new string value or a function that receives the previous value.
Returns
void
pushHistory()
pushHistory(
entry:HistoryEntry):void
Appends a new entry to the terminal history.
Parameters
entry
The history entry to add.
Returns
void
write()
write(
text:string):void
Writes raw text to the shell, handling ANSI escape codes for screen clearing and alt buffers.
Parameters
text
string
The string data to write to the TTY.
Returns
void
run()
run(
input:string):Promise<number>
Submits the current input line and executes the given command string.
Parameters
input
string
The command string to execute.
Returns
Promise<number>
A promise that resolves with the final exit code of the execution.
clearLine()
clearLine():
void
Clears the current input line and resets the history search offset.
Returns
void
historySearch()
historySearch(
direction:number):void
Navigates through command history.
Parameters
direction
number
Positive to go back in time, negative to go forward.
Returns
void
setWorkingDirectory()
setWorkingDirectory(
directory:VirtualFolder):void
Changes the current working directory and updates PWD/OLDPWD environment variables.
Parameters
directory
The virtual folder to switch to.
Returns
void
getCompletions()
getCompletions():
string[]
Calculates possible completions for the current input based on commands and file paths.
Returns
string[]
An array of string suggestions.
autoComplete()
autoComplete():
void
Performs an auto-completion action. If one match is found, it completes the line. If multiple are found, it lists them in the history.
Returns
void
readRawInput()
readRawInput(
stdin:Stream,onData: (data:string) =>void|Promise<void>):Promise<void>
Sets the shell to raw mode, listens for input on stdin.
Parameters
stdin
The standard input stream.
onData
(data: string) => void | Promise<void>
The callback to handle incoming data chunks.
Returns
Promise<void>
readFiles()
readFiles(
__namedParameters: {paths:string[];workingDirectory:VirtualFolder;commandName:string;onContent: (content:string) =>void|Promise<void>;onStdinData: (data:string) =>void|Promise<void>; } &Pick<ProcessIO,"stdin"|"stderr">):Promise<number>
Processes a list of paths, falling back to standard input if the list is empty or contains "-".
Parameters
__namedParameters
{ paths: string[]; workingDirectory: VirtualFolder; commandName: string; onContent: (content: string) => void | Promise<void>; onStdinData: (data: string) => void | Promise<void>; } & Pick<ProcessIO, "stdin" | "stderr">
Returns
Promise<number>
writeError()
staticwriteError(stream:Stream,commandName:string,error?:string|string[],exitCode?:number):Promise<number>
Utility to write a formatted error message to a stream and return an exit code.
Parameters
stream
The stream to receive the error output.
commandName
string
The name of the command reporting the error.
error?
string | string[]
A single string or array of strings representing the error message.
exitCode?
number = EXIT_CODE.generalError
The numerical exit code to return.
Returns
Promise<number>
exitCode.
loop()
staticloop(__namedParameters:Pick<ProcessIO,"stdin"|"stdout"> & {task: () =>string;delay?:number;maxIterations?:number; }):Promise<0>
Executes a task repeatedly and writes its output to stdout.
Parameters
__namedParameters
Pick<ProcessIO, "stdin" | "stdout"> & { task: () => string; delay?: number; maxIterations?: number; }
Returns
Promise<0>
A promise that resolves when the loop is finished.
animate()
staticanimate(__namedParameters:Pick<ProcessIO,"stdin"|"stdout"> & {render: (frame:number) =>string;delay:number;clear?:boolean;stopOnBlank?:boolean;useAltBuffer?:boolean; }):Promise<0>
Executes a frame-based animation in the terminal using the Alternate Screen Buffer.
Parameters
__namedParameters
Pick<ProcessIO, "stdin" | "stdout"> & { render: (frame: number) => string; delay: number; clear?: boolean; stopOnBlank?: boolean; useAltBuffer?: boolean; }
Returns
Promise<0>
A promise that resolves when the animation is stopped.
readInput()
staticreadInput(rawLine:string,stdin:Stream,callback: (data:string) =>CommandOutput|Promise<CommandOutput>):Promise<CommandOutput>
Reads input data. If rawLine is provided, it processes it immediately via the callback. Otherwise, it waits for data from the stdin stream.
Parameters
rawLine
string
The pre-provided input string.
stdin
The input stream to fall back on.
callback
(data: string) => CommandOutput | Promise<CommandOutput>
Function to process the collected input data.
Returns
printLn()
staticprintLn(stream:Stream,text?:string):Promise<void>
Utility function that writes text followed by a newline ("\n") to stream.
Parameters
stream
The stream to write to.
text?
string = ""
The text to write.
Returns
Promise<void>