Author: Claude Code

satl is the satellite interpreter: the program that reads a .satl file and runs it. Most of the time you only need one way to start it, satl hello.satl. This post covers the rest: the banner, the words you can hand a program, the prompt, satl’s own console window, and the options that do other jobs.

Running a program

Give satl the file, and it checks the whole program and then runs it:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display("hello")
    satellite.return(satellite)
}

hello

In a terminal, satl hello.satl shows four lines before hello. This is the banner:

THE SATELLITE PROGRAMMING LANGUAGE
VERSION 004 REVISION 08 BUILD 0043
CLANG++ 24 ALMALINUX 10.2
---------------------------------------------------------------

The second line is the version, the revision and the build number of the satl you are running. The third names the compiler that built it and the system it was built on, so yours may read differently.

The banner goes to the terminal’s error stream, not to its normal output. Your program’s output stays exactly what your program printed, which matters when you save it to a file or hand it to another program. To see the output alone, send the error stream away:

satl hello.satl 2> /dev/null

Handing words to a program

Everything after the file name belongs to the program, even words that look like satl’s own options. The program reads them through the arguments variable.

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments args)
{
    satellite.console.display(args.program + " was given " + (args.length - 1).to_string() + " words")
    satellite.statement.for(satellite.variable.number i = 1; i < args.length; i++)
    {
        satellite.console.display(args["argument_" + i.to_string()])
    }
    satellite.return(satellite)
}

echo_words.satl was given 0 words

satl echo_words.satl --version --debug

echo_words.satl was given 2 words
--version
--debug

Every option

satl --help lists these, and it is the one to trust if this page and your satl ever disagree:

• satl on its own prints the banner and three lines on how to start.
• satl <file.satl> [words...] runs a program, handing it the words.
• satl --run <file> [words...] does the same, for a file whose name begins with -.
• satl --debug <file.satl> [words...] runs it and shows every state and every argument as satl starts.
• satl --repl opens the prompt: type a line, see it run.
• satl --console [file.satl] [words...] does the same in a console window of satl’s own: the program, or with no file, the prompt.
• satl --rebuild folds the switches in your ~/.satl/config.ini into the one line satl reads when it starts.
• satl --config [most] measures, once, what this machine can do, such as how many threads it can hold, and keeps the answer for later runs.
• satl --feedback shows what satellite.feedback has kept on this machine.
• satl --license [n|name|all] shows the licences: satellite’s own, and those of the projects built into satl. --licence, --licenses and --licences work too.
• satl --version or -V shows the version, revision and build.
• satl --help or -h shows the list.

--debug and --console come before the file, --run or --repl. --version and --help must be the whole command line. A word satl does not know is refused, and it names the word:

satl --rum hello.satl
[satellite] satl(command line): "--rum" is not a word satl takes (a file whose name begins with - runs as satl --run --rum) -- satl --help lists every way to start satl (machine_code: 23 command_line_not_understood)

How a run ends: the exit status

When a program runs to its end, satl exits with 0. When something stops it, satl prints a report and exits with the report’s machine code, so a script that runs satl can tell what happened.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list<satellite.variable.number> scores = {7, 9}
    satellite.console.display(scores[3])
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S501: LINE_PAST_THE_END
satl(run): scores[3]: there is no such item -- the list holds 2 items, counting
from 1

directory: stop.satl:6
syntax: satellite.console.display(scores[3])
                                        /\

a line was read by its number and the file has no line with that number. Lines
count from 1, and the last one is the file's size.
machine code 47 line_past_the_end -- satl exits with this.

--------------------------------------------------------------------------------

The last line of the report says it: machine code 47. In a terminal, echo $? straight afterwards prints 47. A code that does not fit an exit status is written in full and satl exits 255. READING AN ERROR REPORT goes through a report line by line.

The prompt

satl --repl opens the prompt. It greets you with one line of instructions, then shows three things in square brackets, satellite, your user name and the folder you are in, followed by >>. Type a statement and press Enter, and it runs at once:

satellite.console.display(6 * 7)
42
run hello.satl
THE SATELLITE PROGRAMMING LANGUAGE
VERSION 004 REVISION 08 BUILD 0043
CLANG++ 24 ALMALINUX 10.2
---------------------------------------------------------------

hello
exit

The prompt runs a statement a line, and keeps what you declare until you leave: a variable declared on one line is there on the next.

It takes a whole block too. Type a line that opens one — satellite.capsule twice(satellite.variable.number n), satellite.statement.if(x > 3), a while or a for — and press Enter, and the prompt writes the { for you and starts the next line one step in. Type the body, then } (it steps back under the line that opened the block). A spacesuit gets more: satellite.spacesuit dog() and Enter writes its {, satellite.constructor() and the constructor’s {, and after each } you type it writes the next section, satellite.protected and then satellite.public, each with its {. What a block declares — a capsule, a spacesuit — is kept for the session, so later lines can call it or make objects of it. An if, a while or a for runs as soon as its last } is typed; an if waits for one more line, in case it is an else.

satellite.capsule twice(satellite.variable.number n)
... {
...     satellite.return(n * 2)
... }
satellite.console.display(twice(21))
42

run hello.satl, or interpret hello.satl, runs a whole program just as satl hello.satl would, banner and all. exit, quit or Ctrl-D leaves. The prompt is also where you ask for help: see THE HELP SYSTEM.

satl’s own console window

satl can open a console window of its own, so it works even where there is no terminal. satl --console hello.satl runs the program in that window, and satl --console with no file opens the prompt there.

satl also opens its console by itself when it is started with no terminal to write to, for example by double-clicking a .satl file or choosing satellite from a menu, as long as there is a screen to show a window on. If the output is going to a file or into another program, satl writes there instead and opens nothing.

When a program ends cleanly, its console closes. When it stops on an error, the window stays open with the report, and a last line says which machine code it stopped on and to press any key to close. A prompt session in the console ends the same way, with “the session is over — press any key to close”.

The options that print something and exit, --rebuild, --config, --feedback and --license, do not take --console: run them in a terminal. A script or a launcher that must never get a window can set the environment variable SATL_NO_WINDOW=1, and satl then never opens a console by itself.

Where next

The FULL REFERENCE lists everything satl understands. The words a program is handed are covered in THE ARGUMENTS VARIABLE, and installing satl is on the INSTALL page.