INCLUDING FILES AND NAMESPACES

A small program fits in one file. A bigger one is easier to live with in pieces: one file of greetings, one of sums, one for the program itself. satellite puts the pieces together with satellite.include, and it keeps them tidy with one simple rule: every file you include is reached through its own name.

Including a file of your own

You have been writing satellite.include(satellite) at the top of every program. That line takes in the language itself. The same word takes in a file of yours: satellite.include("greetings") reads greetings.satl, and its capsules are then yours to call as greetings.hello(...).

Here are three files. The first is a file of greetings. It has no satellite.include(satellite) line, which makes it a spaceship: a file for other files to include, which satl will not start on its own.

satellite.capsule hello(satellite.variable.string name)
{
    satellite.console.display("hello, " + name)
}

satellite.namespace polite
{
    satellite.capsule goodbye(satellite.variable.string name)
    {
        satellite.console.display("goodbye, " + name + ", and thank you")
    }
}

satellite.spacesuit badge()
{
    satellite.protected
    {
        satellite.variable.string text = ""
    }

    satellite.constructor(satellite.variable.string given)
    {
        text = given
    }

    satellite.public
    {
        satellite.capsule call_text()
        {
            satellite.return("[ " + text + " ]")
        }
    }
}

The second lives in a folder called tools, beside the other two. This one is a whole program, with its own satellite.main, so it can also be run by itself:

satellite.include(satellite)

satellite.capsule double(satellite.variable.number n)
{
    satellite.return(n * 2)
}

satellite.capsule satellite.main()
{
    satellite.console.display("sums.satl on its own")
    satellite.console.display(double(4))
    satellite.return(satellite)
}

sums.satl on its own
8

The third is the program, which includes both:

satellite.include(satellite)
satellite.include("greetings")
satellite.include("tools/sums")

satellite.capsule hello(satellite.variable.string name)
{
    satellite.console.display("hi " + name + ", from main.satl")
}

satellite.capsule satellite.main()
{
    hello("mum")
    greetings.hello("mum")
    greetings.polite.goodbye("mum")
    satellite.console.display(sums.double(21))
    greetings.badge b("visitor")
    satellite.console.display(b.call_text())
    satellite.return(satellite)
}

With all three files in place, satl main.satl prints:

hi mum, from main.satl
hello, mum
goodbye, mum, and thank you
42
[ visitor ]

What to notice:

• A bare name is always this file’s own. main.satl and greetings.satl both have a hello, and there is no clash. hello("mum") is main’s own, and greetings.hello("mum") is the one in greetings.
• A file is reached by its name, without the folder or the .satl. tools/sums.satl is reached as sums.double(21). A spacesuit in another file is made the same way: greetings.badge b("visitor").
• An included file’s satellite.main never runs. Including sums.satl gave main its double, and “sums.satl on its own” was not printed.
• Paths are relative to the file that holds the include line, wherever you run satl from. ".." goes up a folder, and the .satl on the end is optional.

A bare name never reaches into another file. Writing double(21) in main.satl is refused before anything runs, and the report tells you to write sums.double(...). A file also reaches only the files it includes itself: if sums.satl included a third file, main.satl would not reach that file by its name.

When the file is not there

If an included file cannot be found, satl stops before running anything and names the file it looked for:

satellite.include(satellite)
satellite.include("recipes")

satellite.capsule satellite.main()
{
    satellite.console.display("this never prints")
    satellite.return(satellite)
}

[satellite] cannot locate file: recipes.satl, included by missing.satl (machine_code: 8 missing_satl_file)

Namespaces: rooms inside one file

Sometimes one file holds two groups of capsules that want the same names: an oven that beeps and a kettle that beeps. satellite.namespace makes a named group inside a file, and satellite.space is its second spelling. A namespace can hold capsules, spacesuits and other namespaces, but not variables. Variables belong to a capsule or a spacesuit.

satellite.include(satellite)

satellite.namespace oven
{
    satellite.capsule heat(satellite.variable.number degrees)
    {
        satellite.console.display("oven heating to " + degrees.to_string())
        beep()
    }

    satellite.capsule beep()
    {
        satellite.console.display("oven: beep")
    }
}

satellite.space kettle
{
    satellite.capsule beep()
    {
        satellite.console.display("kettle: beep")
    }

    satellite.space lid
    {
        satellite.capsule open()
        {
            satellite.console.display("kettle lid open")
        }
    }
}

satellite.capsule beep()
{
    satellite.console.display("my own beep")
}

satellite.capsule satellite.main()
{
    oven.heat(180)
    kettle.beep()
    kettle.lid.open()
    beep()
    satellite.return(satellite)
}

oven heating to 180
oven: beep
kettle: beep
kettle lid open
my own beep

Inside oven, heat calls beep() bare, and it gets the oven’s beep, its neighbour in the same namespace. From satellite.main you name the group first: oven.heat(180), kettle.lid.open(). The plain beep() at the end is the file’s own.

A namespace in an included file is reached through the file’s name first, as greetings.polite.goodbye showed above. Every name you give a file, a namespace or a capsule is a bare name, and bare names are yours. Only the dotted paths that begin with satellite belong to the language.

Where next

The FULL REFERENCE has the include and namespace rules in full. A file can also carry fixed values for every capsule to read: see SATELLITE.LIBRARY. For the capsules themselves, see CAPSULES.