THE ARGUMENTS VARIABLE

When satl starts a program, it already knows a great deal: the words you typed after the file name, its own settings, and facts about the machine it is running on, such as your user name, how much memory there is and what the processor can do. The arguments variable hands all of it to your program as one variable.

Asking for it

satellite.main hands the variable over when you declare it between main’s brackets. The type is satellite.variable.arguments, and the name is yours to choose: arguments, args, anything.

satellite.capsule satellite.main(satellite.variable.arguments args)

A program whose main is written satellite.main(), with nothing between the brackets, simply does not ask for it. The older spelling, satellite.container.list<satellite.variable.string> arguments, gives you the same variable.

Each piece of information is a row, read by its name after the variable’s name, with no brackets: args.program, args.username, args.memory.total.

The words you started it with

satl greet.satl mum dad runs greet.satl and hands it two words. The program sees them as rows:

• args.program is the file’s name, greet.satl.
• args.argument_1 is mum, and args.argument_2 is dad.
• args.length counts them all, the program included, so here it is 3.

A row that is not there is refused, so check args.length before you read a word that may not have been given:

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments args)
{
    satellite.console.display(args.program)
    satellite.console.display(args.length)
    satellite.statement.if (args.length > 1)
    {
        satellite.console.display("hello, " + args.argument_1)
    }
    satellite.statement.else
    {
        satellite.console.display("hello, whoever you are")
    }
    satellite.return(satellite)
}

Run with no words, satl greet.satl prints:

greet.satl
1
hello, whoever you are

and with two:

satl greet.satl mum dad

greet.satl
3
hello, mum

satl’s settings and the machine’s facts

The same variable holds satl’s own settings and what satl found out about the machine. satellite.console.display(args) shows every row there is, several dozen of them. A few you may like:

• args.version and args.revision, the satellite you are running
• args.username, args.session.home and args.session.shell
• args.memory.total, args.memory.used and args.memory.free, in bytes
• args.machine.cores, args.machine.cpu and args.machine.pointer_bits
• args.cpu.architecture and args.cpu.features, what the processor can run
• args.system.distribution and args.disk.free
• args.float.decimal, how many digits a float keeps after the point

Most rows are gathered once, when satl starts. A few, such as memory.used and memory.free, are read fresh every time you ask, so they tell you what the machine is using right now.

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments args)
{
    satellite.console.display(args.version)
    satellite.console.display(args.revision)
    satellite.console.display(args.float.decimal)
    satellite.console.display(args.memory.used > 0)
    satellite.console.display(args.machine.pointer_bits)
    satellite.console.display(args.cpu.features.contains("sse2"))
    satellite.console.display(satellite.library.main.arguments.machine.pointer_bits)
    satellite.return(satellite)
}

4
8
128
true
64
true
64

args.cpu.features is a list, so every list word works on it. The last line shows that the same facts are also words of the language, spelled in full: satellite.library.main.arguments.machine.pointer_bits needs no variable at all.

satl --debug greet.satl mum dad prints every row as satl starts, with the program’s own words among them. It is a quick way to see what your machine says.

Rows of your own

A row whose name is your own can be written, just like a variable. args.score = 5 adds a row, and a second args.score = 6 changes it. A row can hold a list too.

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments args)
{
    args.score = 5
    args.score = args.score + 1
    satellite.console.display(args.score)

    args.visitors = satellite.container.list()
    args.visitors.append("ann")
    args.visitors.append("bo")
    satellite.console.display(args.visitors)
    satellite.console.display(args.visitors[2])
    satellite.return(satellite)
}

6
{"ann", "bo"}
bo

A row that satl holds, such as username, memory.total, argument_1 or float.decimal, is read and never written. The machine, the command line or your settings file says what it is, and a line that tries to write one is refused before the program runs:

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments args)
{
    args.username = "someone else"
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S220: WORD_TAKES_NO_ASSIGNMENT
satl(check): in satellite.main, args.username is a row satl holds, and a program
reads it but does not write it -- the machine, the command line or config.ini
says what it is. A name of the program's own is written: args.my_username = ...

directory: rename.satl:5
syntax: args.username = "someone else"
        /\

this is not a place a program can write: a word that is not a setting and not a
variable, or a row of the arguments that the machine, the command line or
config.ini says -- a program reads it, and gives a name of its own a value
instead.
machine code 35 word_takes_no_assignment -- satl exits with this.

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

Changing satl’s settings: config.ini

satl’s settings that you may change live in a plain text file of your own, ~/.satl/config.ini: one key = value a line, with # for a comment. The rows satl reads from it today include float.whole and float.decimal, the digits a float keeps before and after its point, directory.default, the folder satl’s own console starts in, and the switch access.

# keep 64 digits after a float's point instead of 128
float.decimal = 64
access = true

Save the file, and the next program you run reads args.float.decimal as 64 and keeps floats to 64 digits. A missing config.ini is fine: satl prints a notice, S010, and uses its built-in settings. satl --rebuild writes one for you.

access is the one setting a program can also write: args.access = satellite.bool.false rewrites that row in your config.ini, and leaves every other line of the file as it was. That change lasts after the program ends, so only write it when you mean it. HISTORY AND ACCESS says what the switch is for.

Where next

Every row satl holds is listed in the FULL REFERENCE. For how to start satl with words after the file name, and its other options, see THE SATL COMMAND.