HOW SATELLITE 004 RUNS

You do not need to know how satl works inside to write satellite. But it is not a secret either, and knowing the shape of it explains a few things you will notice, such as a .sate file appearing beside your program, and reports that say satl(check). This post walks through what happens when you type satl hello.satl.

Every word has a number

Satellite’s rule is that a dotted path starting with satellite names something the language owns, and a bare name is something you own. The language’s words are all written down in one table, and each has a number. The number is built the simple way: at every level of the path, a word takes the first number that was free.

• satellite.include(satellite) is 1 1 1
• satellite.capsule is 1 2, and satellite.main is 1 3
• satellite.console.display is 1 5 1
• satellite.variable.string is 1 6 1
• satellite.return(satellite) is 1 15 1

Today the table holds 436 words. A word’s number is how satl finds it while running, which is quicker than looking up its name.

Words as compiled libraries

The work of a word can live in a small compiled C++ library of its own, named after the word’s number. satellite.console.display is 1.5.1.so, and the libraries are installed together in ~/.satl/satellite-numbers/. Each library holds the word’s *likely scenarios*: separate code for the shapes the word is most often used in, so the common case takes the most direct path.

satl loads these libraries once, when it starts. After that, running a word is a call into code that is already in memory. Today 62 of the 436 words have a library of their own, and satl itself carries out the rest, such as files, windows and threads.

A program becomes codes

When you run a program, satl reads each of its files once, and turns each into a list of sixteen-bit codes. The codes come in three families. The low ones are characters, a middle range is the program’s own alphabet of brackets, operators, names and the like, and every satellite word has a code of its own from 4096 up.

By default satl also saves those codes beside your program, in a file with the same name ending .sate. It is plain text, sixteen binary digits a line, with a > line naming the file the codes came from. A program can even read its own:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(satellite.file.exists("what_satl_saved.sate"))
    satellite.variable.file codes = satellite.file.open("what_satl_saved.sate")
    satellite.statement.for(satellite.variable.number i = 1; i <= 6; i + 1)
    {
        satellite.console.display(codes[i])
    }
    satellite.return(satellite)
}

true
>what_satl_saved.satl
0001000000000010
0000001000000010
0001000000000001
0000001000000011
0000000100000000

Those five codes are the program’s first line, satellite.include(satellite): the word satellite.include, an opening bracket, the word satellite, a closing bracket, and the end of the line. The file was already there when the first line of satellite.main ran, because saving it comes before running.

The whole program is checked first

Before any line runs, satl checks the whole program: that it has its include, its satellite.main and its return, that every name was declared, and that each word is given the number of arguments it takes. A mistake the check can see stops the program before it starts, and the report says satl(check):

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display("this line never runs")
    satellite.console.display(the_answer)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S201: NAME_NOT_DECLARED
satl(check): in satellite.main, the_answer has no satellite.variable line
declaring it

directory: checked_first.satl:6
syntax: satellite.console.display(the_answer)
        /\

this name was used and no satellite.variable line ever declared it. A name has
to be given a type before it can hold anything.
machine code 25 name_not_declared -- satl exits with this.

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

Line 5 printed nothing, because nothing ran. Problems that depend on values, like dividing by a number that turns out to be zero, can only be found while running, and those reports say satl(run). READING AN ERROR REPORT covers both.

The program runs from memory

Once checked, the program runs from the codes in memory, never from the file on the disk. So a program can open its own .satl file and rewrite it while it runs, and what is running does not change. This one counts its own runs by rewriting one of its own lines:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number runs = 1
    satellite.console.display("this is run " + runs.to_string())
    satellite.variable.number next = runs + 1
    satellite.variable.file me = satellite.file.open("run_count.satl")
    satellite.variable.number at = me.search("satellite.variable.number runs = ")
    me.replace(at, "    satellite.variable.number runs = " + next.to_string())
    me.close()
    satellite.variable.file again = satellite.file.open("run_count.satl")
    satellite.console.display(again[at])
    satellite.console.display("and this run still says " + runs.to_string())
    satellite.return(satellite)
}

this is run 1
    satellite.variable.number runs = 2
and this run still says 1

Run it again and it says run 2. If it stops on an error, its report quotes the line as it was loaded, not the rewritten one.

Threads, settings and the build

• Threads. When satl starts, it also starts a pool of threads for its own work, 1024 of them by default. A thread your program makes with satellite.thread.new gets a fresh thread of its own. See THREADS.
• Settings. The limits satl works within, such as how many threads it may run or how large an object may grow, are settings with defaults, not numbers fixed in the code. satl --debug program.satl lists every setting as it starts, then each library as it loads, the program as it is loaded, saved and checked, and the state of each step as it runs.
• The build. make builds satl and every numbered library, then installs them into ~/.satl. satl and its libraries are linked dynamically on purpose, so that all of them share one C++ runtime. The BUILD page has the details.

Where next

Every word, with its meaning, is in the FULL REFERENCE. For the command itself, read THE SATL COMMAND, and for what the file words can do, FILES.