Skip to content

GaspardTerminal language

Français · Source files

GaspardTerminal is a C++98 graphical terminal with a small, extensible command language. Type help to display the available commands and language syntax. Commands and variables are local to this terminal session.

set APP /AHCIDISK0/apps/Gaspard3D.elf
echo "Starting ${APP}"
run "$APP"
cd /AHCIDISK0/documents
ls
cd ..
cd -
repeat 3 "echo hello"
history
!!

Variables

set NAME value assigns a variable. Multiple value arguments are joined with a single space; quote a value to preserve its spaces. set NAME prints its value, set lists user variables, and unset NAME removes one. An empty value is written as set NAME "".

Names are case-sensitive, at most 64 characters, and follow [A-Za-z_][A-Za-z0-9_]*. Expand a value with $NAME or ${NAME}. An undefined variable is an error. Expansion always produces one argument, even if it contains spaces or semicolons; expanded text is not evaluated as another command.

$PWD is the current language directory. $STATUS is the previous command's status (zero for success). These variables are read-only. Variables are not exported to the environment of launched programs.

set NAME "hello world"
echo $NAME
echo '${NAME}'
set EMPTY ""
echo "a${EMPTY}b"

Quoting and command batches

  • Space and tab separate arguments.
  • Single quotes preserve their contents literally; double quotes allow variables.
  • Backslash quotes the following character outside single quotes: \$NAME is literal text. Use forward slashes in GFS2 paths.
  • ; separates commands outside quotes. Expansion happens just before each command, so set X hello; echo $X works.
  • # starts a comment at a token boundary outside quotes.
  • Unclosed quotes or a trailing escape reject the entire input before execution. A command error stops the remaining batch; earlier changes remain in effect.

Command names ignore ASCII case. There are no pipes, redirections, wildcard expansion, arithmetic expressions, command substitution or implicit program runs. Use run explicitly.

Command reference

Command Behavior
help [command] Display help generated from the command registry.
set [NAME [value ...]] List, inspect or assign variables.
unset NAME Remove a user variable.
echo [text ...] Print arguments separated by spaces.
pwd Print the current directory.
cd path Enter an existing directory; relative paths use $PWD.
cd .. Go to the parent directory, stopping at /.
cd - Return to the previous directory; subsequent calls toggle.
cd Return to the virtual root /.
ls [path] List a directory asynchronously; / lists mounted volumes.
run file.elf [arguments ...] Queue loading and launch an ELF64 program asynchronously.
history Show the last 64 submitted lines and their IDs.
!! Submit the most recent historical line again.
!N Submit the line with history ID N again, if still available.
repeat N "command" Execute a quoted batch 1..1000 times.
clear Clear the visible scrollback.
exit Close GaspardTerminal.

History and repetition

Up/Down recall input without executing it; press Enter to run the recalled line. !! and !N apply to an entire input line and re-evaluate its variables. History is kept in memory and disappears when the terminal closes.

repeat queues work instead of recursively invoking the parser. Double-quoted variables expand when the repeat command is read; single-quoted variables expand in each repeated command:

repeat 3 'echo $PWD'
repeat 2 'set X updated; echo $X'

One command runs per UI iteration. A batch has a 2048-command budget and at most 16 nested pending jobs. A new input is refused while an earlier batch is pending. These limits keep accidental self-repetition from freezing the UI.

Program execution

run resolves the executable relative to $PWD, loads it from GFS2 and calls the kernel's process extension (150–152). The application accepts ELF files up to 4 MiB and at most 20 arguments including the program path, with at most 1023 bytes per argument and 8192 bytes including terminators in total. The kernel validates the ELF and copies its image and arguments before returning a task token.

cd /AHCIDISK0/apps
run program.elf "argument with spaces"

The terminal remains interactive while children run. Their console output is read through a private kernel channel; another terminal cannot read it. The window shows the count of children not yet reaped. Closing the terminal leaves launched programs running and discards their later console output.

$STATUS reports acceptance of a command, not the later exit status of a child. Loading and launch failures are printed asynchronously. There is no foreground wait, child keyboard input, ANSI terminal emulation or child exit-code API. cd changes path resolution in this language; it does not change a child's newlib working directory. Programs must use a CRT that decodes GO64_StartInfo to receive arguments; rebuild/relink older applications with the updated CRT.

Interface and bounds

Enter executes input; Up/Down browse history; PgUp/PgDn scroll output; Esc clears input; Tab inserts four spaces. Input editing accepts UTF-8 through the existing desktop text widget. Scrollback keeps 512 logical lines, with bounded line length.

Input is limited to 4095 bytes, 32 commands per line and 32 arguments per command. There are at most 128 user variables with 65536 bytes of values in total.

Extending the language

The parser, registry, command modules and platform backend are separate. To add a command, implement a handler and register its descriptor during startup:

#include "language.hpp"

static int hello(terminal::Engine& engine, const terminal::Arguments& arguments)
{
    if (arguments.size() != 1)
        return -22;
    engine.line("Hello from a command module");
    return 0;
}

void registerExampleCommands(terminal::Engine& engine)
{
    engine.registerCommand(terminal::Command("hello", "hello", "Print a greeting", hello));
}

Call registerExampleCommands(engine) alongside registerDefaultCommands(engine) in application initialization. help then includes it automatically. Handlers receive expanded arguments including the command name at index zero. Return zero for success and a nonzero error to stop the batch. Reject invalid arity before accessing arguments. Long operations belong in a backend job advanced by tick, not a blocking loop inside a command.

Source modules: include/language.hpp documents the grammar contract; src/language.cpp parses and schedules; src/commands.cpp registers the standard commands; src/native.cpp implements GFS2 and process jobs. The interface uses src/main.cpp and bounded scrollback from include/console.hpp.

Build

From the repository root in MSYS2 MINGW64:

make -C GaspardTerminal -j4 check
make -C GaspardTerminal test

The output is GaspardTerminal/build/GaspardTerminal.elf, for GaspardOS rather than Windows. Native program launch/output requires the rebuilt kernel with syscalls 150–152. The language itself is independently testable on the host.

make -C GaspardTerminal integration runs the real application under QEMU using a disposable GFS2 image containing a child ELF. It checks set, cd, repeat, ELF loading, CRT argument delivery, captured output and child cleanup.