GaspardTerminal language¶
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:
\$NAMEis literal text. Use forward slashes in GFS2 paths. ;separates commands outside quotes. Expansion happens just before each command, soset X hello; echo $Xworks.#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.