FULL REFERENCE

This is the complete reference for satellite 004, revision 08: every word the language has today, what it does, how it is written, and what satl refuses. Every example on this page was run with satl, and the box under each one is exactly what it printed. If you are new to programming, BEGINNERS and the TUTORIAL are gentler places to start. Come back here when you want the whole story of one word.

One rule runs through all of it. A dotted path that starts with satellite names something the language owns: satellite.console.display, satellite.variable.number, satellite.statement.if. A bare name is something you own: total, greet, sky_blue. You never have to guess whether a word is yours or the language’s. The spelling tells you.

satl writes its own title (the language, its version and its build) at the top of every run. The boxes on this page leave that out and show only what the program printed. When satl refuses a program, the box shows its error report instead. Reading an error report explains every part of one.

PROGRAM SHAPE

Every satellite program has the same frame. Its first line is satellite.include(satellite). Its work happens inside satellite.capsule satellite.main(). And main ends with satellite.return(satellite). satl looks for all three before it runs a single line. satellite.console.display puts a line of text on the screen; it has a post of its own, displaying text.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display("Hello, World!")
    satellite.return(satellite)
}

Hello, World!

Lines, braces and names

A satellite file is read one line at a time, and a few simple rules decide how lines are written.

• One statement is one line. There is no semicolon at the end, and two statements on one line are refused.
• A bracket closes on the same line it opened on.
• { and } each go on a line of their own. A { at the end of an if line is refused.
• Indentation and blank lines are free. Four spaces a level is the custom.
• A bare name is made of English letters, digits and _, and does not start with a digit. Capitals count: Apples and apples are two different names.
• A name that reads as a value is taken as that value. b101 is a binary and xbeef is a hex, so neither can be a name. beef, b2 and x_count are fine.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number Apples = 3
    satellite.variable.number apples = 4
    satellite.variable.number x_count = Apples + apples

    satellite.console.display(x_count)
    satellite.return(satellite)
}

7

satellite.include(satellite)

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

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(check): in satellite.main, satellite.console.display(...) is followed by
something that is not a method call -- a call's answer cannot be given a value,
a bracket must close on its line, and one statement is one line

directory: one_line_each.satl:5
syntax: satellite.console.display("one") satellite.console.display("two")
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

//

// starts a comment, and the comment runs to the end of the line. satl skips it. A comment can have a line to itself, sit above everything else in the file, or follow a statement. Inside a string, // is just two characters of text. It is the only kind of comment: /* */ and # are not comments in satellite, and a line that starts with either is refused.

// comments.satl -- a comment can even come before the first line
satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number apples = 5 // five apples
    // satellite.console.display("this line is switched off")
    satellite.console.display(apples)
    satellite.console.display("a // inside a string is text")
    satellite.return(satellite)
}

5
a // inside a string is text

satellite.include(satellite)

satellite.include(satellite) is the first line of every program (comments aside). It says: this file is a program, and it uses the language. A file without it is a spaceship, a file that other files include, and satl will not start it. The refusal comes before anything runs.

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

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S101: FILE_HAS_NO_INCLUDE
satl.file(check): this file has no satellite.include(satellite), so it is a
spaceship and not a program

directory: spaceship.satl

a program's first line is satellite.include(satellite). Without it the file is a
SPACESHIP -- something another file includes -- and satl will not start it. Add
this as the first line:

    satellite.include(satellite)
machine code 10 satl_file_missing_satellite_include_satellite -- satl exits with
this.

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

satellite.include

satellite.include also brings in another file of yours. Write the file’s name bare, or its path in double quotes:

• satellite.include(shapes) and satellite.include("shapes.satl") both find shapes.satl in the same folder as your program. The .satl on the end may be left off.
• satellite.include("parts/greetings.satl") reaches into a folder, and .. and ./ work too. A path is read from the folder of the file that holds the include, wherever you ran satl from.
• A full path that starts with / is not found today: satl reads it without its first slash and reports the file missing. Keep the files you include beside your program or in folders near it, and reach them with a relative path.
• An include is written outside every capsule. The custom is to put them all at the top, under satellite.include(satellite). Inside a capsule, satl refuses one.

Everything in an included file is reached through that file’s own name: shapes.area(4, 5), not area(4, 5). A bare area(4, 5) is refused, and the report tells you the spelling that works. An included file may be a spaceship, or a whole program with a main of its own so that it can also run by itself. When it is included, its main never runs.

Here is a file that works both ways. On its own it is a complete program:

satellite.include(satellite)

satellite.capsule area(satellite.variable.number wide, satellite.variable.number tall)
{
    satellite.return(wide * tall)
}

satellite.capsule satellite.main()
{
    satellite.console.display("shapes.satl, run on its own")
    satellite.console.display(area(2, 3))
    satellite.return(satellite)
}

shapes.satl, run on its own
6

And here is a program that includes it. Put the two files in one folder and run satl garden.satl. The box shows what it prints with shapes.satl beside it; notice that shapes.satl’s own main does not run:

satellite.include(satellite)
satellite.include(shapes)

satellite.capsule satellite.main()
{
    satellite.console.display(shapes.area(4, 5))
    satellite.return(satellite)
}

20

A file that is not there is refused before anything runs:

satellite.include(satellite)
satellite.include(fences)

satellite.capsule satellite.main()
{
    satellite.return(satellite)
}

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

Namespaces, and how names reach across files, are in including files and namespaces.

satellite.main

satellite.main is where a program begins: satellite’s version of C’s int main(). It is a capsule, declared satellite.capsule satellite.main(), and your program starts on its first line and ends when it reaches satellite.return(satellite).

There are no globals in satellite. A line written outside every capsule has nowhere to keep its result and no moment to run in, so everything a program does starts from a line in main, or from a capsule that main calls. (Values written once at the top of a file are a different thing, satellite.library, with a post of its own: satellite.library.)

• main is written once, at the top level of its file. A second one is refused as declared twice (S202), and one inside a satellite.namespace is refused (S110).
• Only the file you run has its main run. Including a file gives you its capsules, never its main.
• A file with no main is refused before anything runs (S102). Leave off satellite.capsule and satellite.main() is not a capsule at all: satl stops with “no satellite.main to begin in”.

satellite.include(satellite)

satellite.capsule start()
{
    satellite.console.display("never shown")
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S102: FILE_HAS_NO_MAIN
satl.file(check): this file has no satellite.main -- there are no globals, so
there is nowhere else to begin

directory: no_main.satl

there are no globals in satellite, so a statement outside a capsule has nowhere
to put its result and no moment to run in -- which means there is nowhere to
begin. Add:

    satellite.capsule satellite.main()
    {
        ...
    }
machine code 11 satl_file_missing_satellite_main -- satl exits with this.

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

satellite.variable.arguments

main takes nothing, satellite.main(), or one parameter: the arguments variable. Declare it as satellite.variable.arguments and give it any name you like. It holds everything satl knows as it starts: the words your program was started with, satl’s own settings, and facts about the machine, each read by name after a dot. The older spelling, satellite.container.list<satellite.variable.string> arguments, is the same variable.

• arguments.program is the file you ran, and arguments.length counts the words on the command line, the program included.
• satl main_arguments.satl one two gives arguments.argument_1 = one, arguments.argument_2 = two and arguments.length = 3.
• A name that is not one of its rows is refused where it is read.

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments arguments)
{
    satellite.console.display(arguments.program)
    satellite.console.display(arguments.length)
    satellite.return(satellite)
}

main_arguments.satl
1

Every row it has, and how to add your own, is in the arguments variable.

CAPSULES

A capsule is satellite’s word for a function: a named piece of program that you can run from anywhere by calling its name. Capsules is the gentle introduction.

satellite.capsule

A capsule is declared at the top level of a file, or inside a satellite.namespace, with its name, its parameters in brackets, and its body between { and }:

• A parameter is a type and then a name, the way every declaration in satellite is written, with commas between them: (satellite.variable.string who, satellite.variable.number times).
• A capsule that takes nothing has empty brackets: hello().
• The order capsules are written in does not matter. main can call a capsule written below it.
• A capsule declared inside another capsule is refused (S110), and so is a name declared twice in one file (S202).

satellite.include(satellite)

satellite.capsule satellite.main()
{
    greet("world", 2)
    satellite.console.display(twice(21))
    satellite.return(satellite)
}

satellite.capsule greet(satellite.variable.string who, satellite.variable.number times)
{
    satellite.variable.number i = 0
    satellite.statement.while (i < times)
    {
        satellite.console.display("hello, " + who)
        i = i + 1
    }
}

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

hello, world
hello, world
42

A capsule runs in a frame of its own. It cannot see the caller’s variables, and a parameter is the capsule’s own copy: changing it inside does not change the caller’s name. What you hand a capsule is all it has.

satellite.include(satellite)

satellite.capsule bump(satellite.variable.number n)
{
    n = n + 1
    satellite.console.display(n)
}

satellite.capsule satellite.main()
{
    satellite.variable.number n = 1
    bump(n)
    satellite.console.display(n)
    satellite.return(satellite)
}

2
1

Each call is checked twice. The number of arguments is checked before anything runs; the type of each one is checked when the call is reached.

satellite.include(satellite)

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

satellite.capsule satellite.main()
{
    satellite.console.display(twice(1, 2))
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(check): in satellite.main, twice takes 1 argument, and was given 2

directory: wrong_count.satl:10
syntax: satellite.console.display(twice(1, 2))
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

satellite.include(satellite)

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

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

[satellite] satl(run): twice's n was declared satellite.variable.number, and it holds a string (machine_code: 27 types_do_not_meet)

What a capsule answers

A capsule answers whatever its satellite.return(...) hands back. Nothing after its brackets says what kind of value that is: only line ends and comments stand between a capsule’s ) and its {.

• One whose answer is used, and that can never hand one back, is refused before anything runs (S240).
• One whose answer is used, and that ended without handing one back, is refused when it happens (S240).
• satellite.returns(type) after the brackets is refused by name. It was taken out of the language on 2026-09-24: delete it, and the capsule answers exactly as it did.

satellite.include(satellite)

satellite.capsule sign_of(satellite.variable.number n)
{
    satellite.statement.if (n < 0)
    {
        satellite.return("below zero")
    }
    satellite.statement.if (n == 0)
    {
        satellite.return("zero")
    }
    satellite.return("above zero")
}

satellite.capsule satellite.main()
{
    satellite.console.display(sign_of(-5))
    satellite.console.display(sign_of(0))
    satellite.console.display(sign_of(7))
    satellite.return(satellite)
}

below zero
zero
above zero

satellite.include(satellite)

satellite.capsule name_of() satellite.returns(satellite.variable.string)
{
    satellite.return("satellite")
}

satellite.capsule satellite.main()
{
    satellite.console.display(name_of())
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(check): satellite.capsule name_of -- satellite.returns was taken out of
satellite: a capsule answers whatever its satellite.return(...) hands back, so
delete satellite.returns(...) from this line

directory: returns_taken_out.satl:3
syntax: satellite.capsule name_of() satellite.returns(satellite.variable.string)
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

Calling a capsule

A capsule is called by its name and its arguments in brackets. The arguments are worked out where the call is, before the capsule starts.

• On a line of its own, for what it does: greet("world", 2).
• Inside a line, for what it answers: satellite.variable.number area = square(4), square(3) + 1, square(square(2)).
• A capsule in an included file is called through the file’s name, shapes.area(4, 5), and one inside a satellite.namespace tools is called tools.twice(21).

satellite.include(satellite)

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

satellite.capsule satellite.main()
{
    satellite.variable.number area = square(4)
    satellite.console.display(area)
    satellite.console.display(square(3) + 1)
    satellite.console.display(square(square(2)))
    satellite.return(satellite)
}

16
10
16

Using the answer of a capsule that can never give one is refused before anything runs:

satellite.include(satellite)

satellite.capsule say_hi()
{
    satellite.console.display("hi")
}

satellite.capsule satellite.main()
{
    satellite.variable.number n = say_hi()
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S240: CAPSULE_GAVE_NO_ANSWER
satl(check): in satellite.main, say_hi() is used where its answer would be, and
it never hands one back -- no satellite.return(...) in it has a value

directory: no_answer.satl:10
syntax: satellite.variable.number n = say_hi()
        /\

this capsule's answer was used, and the way it went reached no
satellite.return(...) -- so there was nothing to hand back.
machine code 53 capsule_gave_no_answer -- satl exits with this.

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

A capsule that calls itself

A capsule may call itself. How far it can go depends on where the call stands.

• A call that is the last thing the capsule does (the last line of an if or an else, or followed only by satellite.return) is run as a loop. It can go as deep as you like: a hundred thousand turns is nothing.
• A call with work still to do after it, such as n * factorial(n - 1), is an ordinary call. So is a call written inside satellite.return(...), such as satellite.return(gcd(b, a % b)), because handing the answer back is work left after it. Each level takes a few kilobytes while it waits. There is no depth limit but memory: when a program fills the room it started with, satl moves on to fresh room and carries on, and a million levels deep is a few gigabytes. A call written last takes none of that.

satellite.include(satellite)

satellite.capsule count_down(satellite.variable.number n)
{
    satellite.statement.if (n == 0)
    {
        satellite.console.display("lift off")
    }
    satellite.statement.else
    {
        count_down(n - 1)
    }
}

satellite.capsule factorial(satellite.variable.number n)
{
    satellite.statement.if (n < 2)
    {
        satellite.return(1)
    }
    satellite.return(n * factorial(n - 1))
}

satellite.capsule satellite.main()
{
    count_down(100000)
    satellite.console.display(factorial(25))
    satellite.return(satellite)
}

lift off
15511210043330985984000000

satellite.return

satellite.return(...) ends the capsule it is written in, from wherever it stands, even inside an if, a while or a for, and hands back what is between its brackets.

• In main, satellite.return(satellite) ends the program, and satl exits with 0 (success).
• satellite.return() and satellite.return(satellite) hand back nothing.
• A capsule other than main may leave it out. Reaching its closing } ends it the same way, with nothing handed back.
• A program needs at least one. A file with none is refused before anything runs (S103). Its place is the last line of main.

satellite.include(satellite)

satellite.capsule first_square_over(satellite.variable.number limit)
{
    satellite.statement.for (satellite.variable.number i = 1; i < limit; i++)
    {
        satellite.statement.if (i * i > limit)
        {
            satellite.return(i * i)
        }
    }
    satellite.return(0)
}

satellite.capsule count_until(satellite.variable.number stop)
{
    satellite.variable.number n = 0
    satellite.statement.while (n < 10)
    {
        satellite.statement.if (n == stop)
        {
            satellite.return()
        }
        satellite.console.display(n)
        n = n + 1
    }
}

satellite.capsule satellite.main()
{
    satellite.console.display(first_square_over(50))
    count_until(2)
    satellite.statement.if (1 == 1)
    {
        satellite.console.display("ending early")
        satellite.return(satellite)
    }
    satellite.console.display("never shown")
    satellite.return(satellite)
}

64
0
1
ending early

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display("never shown")
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S103: FILE_HAS_NO_RETURN
satl.file(check): this file has no satellite.return -- execution ends inside
main

directory: no_return.satl

execution ends inside main, and main has to say so. Add this as main's last
line, just before its closing }:

    satellite.return(satellite)
machine code 12 satl_file_missing_satellite_return_satellite -- satl exits with
this.

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

STATEMENTS

The statements are satellite.statement.if, satellite.statement.else, satellite.statement.while and satellite.statement.for. Each is followed by its body between { and }, each brace on a line of its own. If, while and for walks through them slowly.

• A condition must answer true or false. A number where a condition goes is refused when the line is reached.
• A body shares the variables of the capsule around it: a name changed inside is changed outside.
• To use a name after an if or a loop, declare it before.
• A statement with no body is refused before anything runs (S110).

satellite.statement.if

satellite.statement.if (condition) runs its body when the condition is true, and skips it when it is false.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number temperature = 30
    satellite.statement.if (temperature > 25)
    {
        satellite.console.display("warm")
    }
    satellite.statement.if (temperature > 35)
    {
        satellite.console.display("hot")
    }
    satellite.return(satellite)
}

warm

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.statement.if (5)
    {
        satellite.console.display("never shown")
    }
    satellite.return(satellite)
}

[satellite] satl(run): satellite.statement.if was given a number and needs a true or false (machine_code: 27 types_do_not_meet)

satellite.statement.else

satellite.statement.else comes straight after an if‘s body and runs when that if did not. Write satellite.statement.else satellite.statement.if (condition) to test another condition, as many times as you need; the first one that is true runs, and the rest are skipped. An else with no if before it is refused (S110).

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number score = 72
    satellite.statement.if (score >= 90)
    {
        satellite.console.display("top marks")
    }
    satellite.statement.else satellite.statement.if (score >= 50)
    {
        satellite.console.display("a pass")
    }
    satellite.statement.else
    {
        satellite.console.display("try again")
    }
    satellite.return(satellite)
}

a pass

satellite.statement.while

satellite.statement.while (condition) runs its body again and again for as long as the condition is true. The condition is read before every turn, so a condition that is false at the start runs the body no times at all.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number n = 1
    satellite.statement.while (n < 100)
    {
        satellite.console.display(n)
        n = n * 3
    }
    satellite.return(satellite)
}

1
3
9
27
81

satellite.statement.for

satellite.statement.for counts. It has three parts between its brackets, divided by two semicolons:

1. A declaration of its counter, always a satellite.variable.number: satellite.variable.number i = 0.
2. A condition, read before every turn: i < 3. It cannot be left empty.
3. A step, run after every turn. It is written without an =, because the loop puts the counter’s own name in front of it: i + 1, i - 4, i * 2, i / 3, i % 5, i ^ 2 or i ** 2, with a space on both sides of the sign, or i++ and i--. The step may be left empty, and then the body moves the counter itself.

The counter belongs to the loop: after the loop it is gone, and the same name can be declared again. There is no for over the items of a list today; satl refuses (satellite.variable.string name : names).

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.statement.for (satellite.variable.number i = 1; i <= 3; i++)
    {
        satellite.console.display(i)
    }
    satellite.statement.for (satellite.variable.number i = 10; i > 0; i - 4)
    {
        satellite.console.display(i)
    }
    satellite.statement.for (satellite.variable.number i = 2; i < 300; i ^ 2)
    {
        satellite.console.display(i)
    }
    satellite.return(satellite)
}

1
2
3
10
6
2
2
4
16
256

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.statement.for (satellite.variable.number i = 1; i < 20; i = i + 1)
    {
        satellite.console.display(i)
    }
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(check): in satellite.main, satellite.statement.for's step does not move i
-- a for's step is i and one of + - * / % ^ ** with a space on both sides, or
i++ or i--

directory: for_step.satl:5
syntax: satellite.statement.for (satellite.variable.number i = 1; i < 20; i = i + 1)
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

OPERATORS

Operators introduces them one at a time. This is the complete list, with every rule.

The space rule

Every operator is written with a space on both sides of its sign: 4 + 3, never 4+3. That frees the touching spellings to mean something else:

• A touching - in front of a number or a name makes it negative: -7, -n.
• A touching / between two numbers makes a fraction: 1/3.
• A touching % straight after digits makes a percentage: 50%.
• A touching b or x in front of digits makes a binary or a hex: b1010, xFF.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(4+3)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(run): every math operation is written with a space on both sides of the
sign, and this + has none

directory: spaces.satl:5
syntax: satellite.console.display(4+3)
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

+ – * / %

Add, take away, multiply, divide and remainder.

• / between two whole numbers is whole-number division: 20 / 3 is 6. It cuts toward zero, so -7 / 2 is -3. Write a float, 10.0 / 4, to keep the part after the point.
• % is what is left over, and it takes the sign of the number being divided: -7 % 2 is -1.
• Dividing by zero, with / or %, is refused (S401).
• A whole number has no size limit and never wraps around.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(2 + 3)
    satellite.console.display(10 - 4)
    satellite.console.display(6 * 7)
    satellite.console.display(20 / 3)
    satellite.console.display(20 % 3)
    satellite.console.display(-7 / 2)
    satellite.console.display(-7 % 2)
    satellite.console.display(10.0 / 4)
    satellite.console.display(99999999999999999999999 + 1)
    satellite.return(satellite)
}

5
6
42
6
2
-3
-1
2.5
100000000000000000000000

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(1 / 0)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S401: DIVISION_BY_ZERO
satl(run): the / of 1 and 0 is a division by zero

directory: divide_by_zero.satl:5
syntax: satellite.console.display(1 / 0)
                                    /\

a divisor worked out to 0. There is no number this could answer, so it answers
nothing rather than something.
machine code 22 division_by_zero -- satl exits with this.

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

^ and **

^ is power, and ** is its second spelling. Both group right to left, so 2 ^ 3 ^ 2 is 2 ^ 9. A negative power answers a float, because a whole number cannot hold the answer: 2 ^ -1 is 0.5. The power must be a whole number; 2 ^ 0.5 is refused (S210). ^ is never “exclusive or” in satellite.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(2 ^ 10)
    satellite.console.display(2 ** 10)
    satellite.console.display(2 ^ 3 ^ 2)
    satellite.console.display(2 ^ -1)
    satellite.console.display(2 ^ 100)
    satellite.return(satellite)
}

1024
1024
512
0.5
1267650600228229401496703205376

== != < > <= >=

Equal, not equal, less than, greater than, less than or equal, greater than or equal. Each answers true or false.

• Numbers compare with numbers, and a whole number, a float, a binary and a hex all compare by what they are worth: b1010 == 10 and 2.0 == 2 are both true.
• Strings compare with strings, in satellite’s own character order: a to z, then A to Z, then the digits, then the signs, then the space. So "a" < "B" is true.
• Two different kinds, such as a number and a string, are refused (S301).
• Comparisons do not chain: 1 < 2 < 3 is refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number n = 87
    satellite.console.display(n > 50)
    satellite.console.display(n == 87)
    satellite.console.display(n != 87)
    satellite.console.display(3 <= 3)
    satellite.console.display("apple" < "banana")
    satellite.console.display("a" < "B")
    satellite.console.display(b1010 == 10)
    satellite.console.display(2.0 == 2)
    satellite.return(satellite)
}

true
true
false
true
true
true
true
true

satellite.include(satellite)

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

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(run): a comparison was given a number and a string, and there is no
scenario for that pair

directory: compare_kinds.satl:5
syntax: satellite.console.display(5 == "5")
                                    /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

!

! in front of a true-or-false turns it over: !raining is true when raining is false. It goes only in front of a satellite.bool or a comparison in brackets, !(3 > 2); in front of a number it is refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.bool raining = satellite.bool.false
    satellite.statement.if (!raining)
    {
        satellite.console.display("no umbrella needed")
    }
    satellite.console.display(!(3 > 2))
    satellite.return(satellite)
}

no umbrella needed
false

&& || & | ~ << >> .and() .or() .xor()

None of these is part of satellite 004 today, and satl refuses every one: && and || in a condition, the bit operators &, |, ~, << and >>, and the methods .and(), .or(), .xor() and .not(). To ask for two things at once, put one if inside another. To ask for either of two, use else if.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number age = 30
    satellite.statement.if (age >= 18)
    {
        satellite.statement.if (age < 65)
        {
            satellite.console.display("working age")
        }
    }
    satellite.return(satellite)
}

working age

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number age = 30
    satellite.statement.if (age >= 18 && age < 65)
    {
        satellite.console.display("working age")
    }
    satellite.return(satellite)
}

[satellite] satl(run): satellite.statement.if's condition could not be read to the end -- it stops at something with no meaning there yet (& | << >> !! are undecided), so the part before it is not the whole value (machine_code: 13 satl_line_not_understood)

+ between text and numbers

+ joins two strings, and a string with a number added to it joins the number as the text its own .string gives: "n = " + 4 is n = 4, and "f " + 1.5, "p " + 50%, "b " + b1010, "h " + x1F and "q " + 1/3 join the same way. With the number first, text that spells a number — whole, like "2", or with a decimal point, like "2.5" — IS that number, and + adds: 4 + "2" is the number 6 and 1.5 + "2" is 3.5. Any other text is joined after the number: 4 + "abc" is 4abc. A bool joins as true or false with one space between — "flag:" + satellite.bool.true is flag: true — and a colour or any other kind added to a string is refused (S301): write its .string.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number n = 4
    satellite.console.display("n = " + n.string)
    satellite.console.display("n = " + n.to_string())
    satellite.return(satellite)
}

n = 4
n = 4

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number n = 4
    satellite.console.display(n + "2")
    satellite.console.display(1.5 + "2")
    satellite.console.display(n + " apples")
    satellite.return(satellite)
}

6
3.5
4 apples

The order of operations

When a line has more than one operator, satellite works them out in this order:

1. Brackets, from the inside out.
2. A touching - and a !, which belong to the value they touch. So -2 ^ 2 is 4; write 0 - 2 ^ 2 for -4.
3. ^ and **, right to left.
4. *, / and %, left to right.
5. + and -, left to right.
6. The comparisons, last of all, so 1 + 2 < 2 + 2 compares 3 with 4.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(2 + 3 * 4)
    satellite.console.display((2 + 3) * 4)
    satellite.console.display(10 - 3 - 2)
    satellite.console.display(2 * (3 + 4) ^ 2)
    satellite.console.display(-2 ^ 2)
    satellite.console.display(0 - 2 ^ 2)
    satellite.console.display(1 + 2 < 2 + 2)
    satellite.return(satellite)
}

14
20
5
98
4
-4
true

=

name = value gives a new value to a name already declared. The new value must be the name’s own kind; see satellite.variable, below. There is one spelling: n += 1, -=, *=, /= and %= are refused by name (S210), and so is n++ outside a for‘s step. Write n = n + 1.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number total
    total = 10
    total = total + 5
    satellite.console.display(total)
    satellite.return(satellite)
}

15

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number total = 10
    total += 5
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S210: NOT_BUILT_YET
satl(check): in satellite.main, total += ... is not built yet -- write total =
total + ...

directory: plus_equals.satl:6
syntax: total += 5
        /\

this word is numbered in the language and the library behind it does not exist
yet. The word is right; there is nothing yet to run.
machine code 14 not_built_yet -- satl exits with this.

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

VALUES

satellite.variable

A name is declared with its kind in front of it: satellite.variable.number count = 3. The value is optional; a name declared without one holds nothing until it is given one, and showing nothing is refused.

The kinds described here are satellite.variable.bool, which holds satellite.bool.true or satellite.bool.false, and satellite.variable.number, .string, .float, .infinity, .fraction, .percent, .binary, .hex and .color. Lists, indexes and the other containers, files, windows and threads come later on this page.

• A name is declared once in a capsule. A second declaration is refused (S202).
• A name used without a declaration is refused (S201).
• A name holds only its own kind. Giving it another is refused (machine code 27), with a few friendly exceptions listed below, under converting between values.
• satellite.variable on its own, with no kind, is refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number count = 3
    satellite.variable.string name = "Ada"
    satellite.variable.bool ready = satellite.bool.true
    satellite.console.display(count)
    satellite.console.display(name)
    satellite.console.display(ready)
    satellite.return(satellite)
}

3
Ada
true

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number count = "three"
    satellite.return(satellite)
}

[satellite] satl(run): count was declared satellite.variable.number, and it holds a string (machine_code: 27 types_do_not_meet)

satellite.bool

satellite.bool.true and satellite.bool.false are the two truth values, and satellite.variable.bool is a name that holds one. Every comparison answers one, so satellite.variable.bool ready = 3 > 2 holds true.

• == and != compare two bools, and ! turns one over. < and > are refused: there is no order between true and false.
• A bool is not a number and not a string: satellite.bool.true + 1 and "a" + satellite.bool.true are refused, and a bool name refuses 1 and "true".
• .string (also .to_string and .str) is its text, true or false. Write it on a name, ready.string, or on something in brackets, (3 > 2).string; straight after the word, satellite.bool.true.string is refused. .number, .binary, .hex and .reverse() are refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.bool ready = 3 > 2
    satellite.console.display(ready)
    satellite.console.display(satellite.bool.false)
    satellite.console.display(ready == satellite.bool.true)
    satellite.console.display(!ready)
    satellite.return(satellite)
}

true
false
true
false

satellite.variable.number

A whole number of any size. You write it as digits, with a touching - in front for below zero: 34587, -7. It has no size limit but your computer’s memory, and it never wraps around. A number with a point in it, 12.34, is a float, and a number name refuses one, even 2.0. Numbers is the gentle introduction.

Its operators are all of the ones above. Its methods:

• .string (also .to_string and .str): its digits as text.
• .number (also .to_number and .as_number): the number itself.
• .binary (also .bin and .as_binary): its base-2 digits as text.
• .hex (also .as_hex and .to_hex): its base-16 digits as text.
• .reverse(): its digits turned round, sign kept.
• .add(x): the same as + x.

A method that takes nothing may be written with or without (), and methods chain left to right: n.binary.find("111"). A number in brackets takes methods too: (12).binary.

These words are numbered in the language but have nothing behind them yet, and satl refuses them: .max, .min, .abs, .clamp, .floor, .ceil, .round, .truncate, .sqrt, .modulus, .digits, .shift_left, .shift_right, .power (and .power_of, .to_the_power_of), and satellite.variable.number(x) as a call.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number n = 87
    satellite.console.display(n + 13)
    satellite.console.display(n.string)
    satellite.console.display(n.binary)
    satellite.console.display(n.hex)
    satellite.console.display(n.reverse())
    satellite.console.display(n.add(13))
    satellite.console.display(-n)
    satellite.console.display(2 ^ 70)
    satellite.return(satellite)
}

100
87
1010111
57
78
100
-87
1180591620717411303424

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number n = 87
    satellite.console.display(n.round)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(check): in satellite.main, n is satellite.variable.number, and round is not
one of its methods -- only an object of a satellite.spacesuit has capsules to
call

directory: round.satl:6
syntax: satellite.console.display(n.round)
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

satellite.variable.string

Text, written between double quotes: "hello world". satellite keeps a string as characters, not bytes, so an accent or an arrow is one character, and .reverse() turns a string round by character. Six escapes are read inside a string: \" a double quote, \\ a backslash, \n a new line, \t a tab, \r a carriage return and \' an apostrophe. Any other backslash stays in the text as it is written, so "a\qb" is a, a backslash, q and b. Strings is the gentle introduction.

Its operators:

• + joins two strings.
• - takes out the first place the right-hand string occurs, and leaves the string as it was when it is not there: "banana" - "an" is "bana".
• == and != compare two strings, and <, >, <= and >= put them in satellite’s character order: a to z, then A to Z, then the digits, then the signs, then the space.

Its methods:

• .find(x): where x first begins, counting from 0, so "abc".find("b") is 1. A string that is not there is refused (S420) rather than answered with -1.
• .add(x): the same as + x.
• .reverse(): the characters back to front.
• .string (also .str and .to_string): the text, unchanged.
• .number (also .to_number and .as_number): reads a whole number out of the text, and refuses anything else, "3.5" and " 42" included (S120).
• .binary (also .bin and .as_binary) and .hex (also .as_hex and .to_hex): read that same whole number and answer its base-2 or base-16 digits as text. So "1010".bin is the bits of one thousand and ten, not of ten.
• .foreground(c) and .background(c): the string in a colour. See below.

These words are numbered but have nothing behind them yet, and satl refuses them: .size, .empty, .contains (and .contain), .replace(a, b), .append(x), .clear, .at(n), .substring(start, end), .starts_with(x), .ends_with(x), .lower, .upper, .split(separator), .trim, .resolved, reading one character with s[n], and satellite.variable.string(x) as a call.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.string s = "hello world"
    satellite.console.display(s + "!")
    satellite.console.display(s.add("!"))
    satellite.console.display(s - "o")
    satellite.console.display(s.find("world"))
    satellite.console.display(s.reverse())
    satellite.console.display("héllo→".reverse())
    satellite.console.display("42".number + 1)
    satellite.console.display("255".hex)
    satellite.console.display(s == "hello world")
    satellite.console.display("a" < "B")
    satellite.console.display("tab\there")
    satellite.return(satellite)
}

hello world!
hello world!
hell world
6
dlrow olleh
→olléh
43
FF
true
true
tab	here

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.string s = "hello world"
    satellite.console.display(s.find("moon"))
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S420: TEXT_NOT_FOUND
satl(run): s.find did not find it

directory: find_missing.satl:6
syntax: satellite.console.display(s.find("moon"))
        /\

the text looked for is not in this string.
machine code 15 text_not_found -- satl exits with this.

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

.foreground(c) and .background(c)

"OK".foreground(x00FF00) is the string OK drawn in green, and .background(c) sets the colour behind it. c is six hex digits with their x, like xFF8800, or a satellite.variable.color. The colour becomes part of the string, as the terminal’s own colour codes, so .find and == see them: a coloured "OK" is not equal to a plain one. satellite.console.display shows the colours on a terminal, and leaves them out when its output goes into a file or another program, which is why the box below shows plain text. Color on the console has the rest.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color warning = xFF8800
    satellite.console.display("status: " + "OK".foreground(x00FF00))
    satellite.console.display("careful".foreground(warning).background(x000000))
    satellite.console.display("OK".foreground(x00FF00) == "OK")
    satellite.return(satellite)
}

status: OK
careful
false

satellite.variable.float

A number with a point in it: 12.34, 0.5, -2.75. satellite.variable.double is its second spelling. There is no scientific notation (1.0e5 is refused), a float needs a digit on both sides of its point (.5 and 5. are refused), and there is no limit on its size. Floats is the gentle introduction.

• A float is decimal all the way down, so nothing is rounded that you did not ask for: 0.1 + 0.2 == 0.3 is true.
• It keeps 128 places after the point and 4096 digits before it. Those are arguments.float.decimal and arguments.float.whole, and you can change either for your machine in ~/.satl/config.ini, with a line such as float.decimal = 4096; any count of 1 or more works. Where a result has more places than that, the last one kept is rounded half away from zero.
• A float shows at most 32 places, however many it holds. 12.50 shows 12.5, and 2.0 shows 2.0.
• + - * / % and ^ work between two floats, and between a float and a whole number either way round. 4 / 3 is still whole-number division; write 4.0 / 3 for the float. ^ takes a whole-number power only.
• A whole number given to a float name becomes a float: satellite.variable.float f = 3 holds 3.0. A float given to a number name is refused.
• .string (also .to_string and .str) is its text. .number (also .to_number and .as_number) is the whole number when there is nothing after the point; 12.5.number is refused (S402), because satellite rounds nothing on its own.
• Not built yet, and refused: .binary, .hex, .reverse() and .add(x) on a float, and a float meeting a percentage, a binary, a hex, a fraction or an infinity.

satellite.include(satellite)

satellite.capsule satellite.main(satellite.variable.arguments arguments)
{
    satellite.variable.float price = 12.05
    satellite.variable.double half = 0.5
    satellite.console.display(price * 2)
    satellite.console.display(price + half)
    satellite.console.display(4.0 / 3)
    satellite.console.display(4 / 3)
    satellite.console.display(0.1 + 0.2 == 0.3)
    satellite.console.display(12.50)
    satellite.variable.float whole = 3
    satellite.console.display(whole)
    satellite.console.display(whole.number)
    satellite.console.display(arguments.float.decimal)
    satellite.return(satellite)
}

24.1
12.55
1.33333333333333333333333333333333
1
true
12.5
3.0
3
128

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(12.5.number)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S402: ANSWER_IS_NOT_WHOLE
satl(run): that float.number: 12.5 is not a whole number, so there is no number
to make of it -- satellite rounds nothing on its own

directory: float_number.satl:5
syntax: satellite.console.display(12.5.number)
        /\

the answer exists and is not a whole number -- 2 ^ -1 is one half.
satellite.variable.number holds whole numbers, so this has nowhere to go.
machine code 24 answer_is_not_whole -- satl exits with this.

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

satellite.variable.infinity and satellite.infinity()

satellite.infinity() makes an infinity, and satellite.variable.infinity is a name that holds one. It shows as (infinity), and a minus in front turns it over: (-infinity). Infinity is the gentle introduction.

• It is larger than every number, and (-infinity) is smaller than every number. It compares with == != < > <= >= against a whole number, a binary and another infinity.
• An infinity name also takes a plain whole number. It refuses a string, a binary, a hex, a float and a percentage, and a number name refuses an infinity.
• .string is how it shows. .number, .binary and .hex are refused, because an infinity is larger than every number, and .reverse() is refused because it has no digits to turn round.
• Not built yet, and refused (S210): arithmetic with an infinity (+ - * / ^ **), .power_of(x), .resize(n), .nines(), satellite.infinity(x) with something in its brackets, and an infinity meeting a float or a hex.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.infinity sky = satellite.infinity()
    satellite.console.display(sky)
    satellite.console.display(-sky)
    satellite.console.display(sky > 10 ^ 100)
    satellite.console.display(-sky < 0 - 10 ^ 300)
    satellite.console.display(b1010 < sky)
    satellite.console.display(sky == -sky)
    satellite.console.display(sky.string)
    satellite.return(satellite)
}

(infinity)
(-infinity)
true
true
true
false
(infinity)

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(satellite.infinity().number)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(run): satellite.infinity.number was written on an infinity, and an infinity
is larger than every number -- there is no number to make of it

directory: infinity_number.satl:5
syntax: satellite.console.display(satellite.infinity().number)
        /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

satellite.variable.fraction

Two numbers tied together, one above the line and one below it. You write it with a slash that touches both numbers: 1/3. That is the whole difference between a fraction and division: 1 / 3, with spaces, is whole-number division and answers 0. Fractions is the gentle introduction.

• A fraction stays as it was written: 2/4 shows 2/4. But two fractions compare by what they are worth, so 2/4 == 1/2 is true and 1/3 < 1/2 is true. A fraction also compares with a whole number: 1/3 < 1 is true.
• Each part may have a point in it: 1.5/2 shows 1.5/2.
• The sign goes on top: -1/3. A bottom number of 0 is refused (S401).
• A whole number given to a fraction name becomes that number over 1: 3 shows 3/1.
• .numerator and .denominator are its two parts, and .string is how it shows.
• Not built yet, and refused: arithmetic with a fraction (1/3 + 1/3), a fraction of two names (a/b), a fraction meeting a float or a percentage, and .number, .binary, .hex and .reverse().

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.fraction third = 1/3
    satellite.variable.fraction half = 2/4
    satellite.console.display(third)
    satellite.console.display(half)
    satellite.console.display(half == 1/2)
    satellite.console.display(third < half)
    satellite.console.display(third.numerator)
    satellite.console.display(third.denominator)
    satellite.console.display(1.5/2)
    satellite.console.display(-1/3)
    satellite.console.display(1 / 3)
    satellite.variable.fraction whole = 3
    satellite.console.display(whole)
    satellite.return(satellite)
}

1/3
2/4
true
true
1
3
1.5/2
-1/3
0
3/1

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.fraction third = 1 / 3
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(check): in satellite.main, 1 / 3 is whole-number division -- a fraction is
written with a touching slash: 1/3

directory: fraction_spaced.satl:5
syntax: satellite.variable.fraction third = 1 / 3
        /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

satellite.variable.percent

A percentage, written with its % touching the digits: 50%, 12.5%, -50%, 1000000000000%. The word is satellite.variable.percentage, and satellite.variable.percent is its second spelling; both declare the same kind. Percentages is the gentle introduction.

• It keeps exactly 32 places after the point, so 0.1% + 0.2% is 0.3% and 100% / 3 is 33.33333333333333333333333333333333%. There is no ceiling above.
• The % is required. A percentage name given 50 is refused before anything runs: ERROR: expected 50%.
• A percentage compares only with another percentage: 50% < 75% is true, and 50% == 50 is refused.

What each pair answers:

• 50% + 25% is 75%, and 50% - 25% is 25%: two percentages stay a percentage.
• 50% * 50% is 25%: a percentage of a percentage.
• 50% / 4 is 12.5%: a share of it.
• 200 * 50% and 50% * 200 are both 100: a number and a percentage answer a number.
• 200 - 50% is 100 (reduced by it), and 200 + 50% is 300 (grown by it).
• 200 / 50% is 400: what 200 is 50% of.
• For + and - the number goes first. 50% + 5 is refused: write 5 + 50%.
• % and ^ with a percentage are refused, and so is 50% / 50%.
• An answer that is not a whole number, such as 3 * 50%, is refused (S402), and so is a percentage meeting a float.
• A percentage name holds only a percentage, so half = half * 2 is refused when it runs, because that answers a number.
• .string is its text. .number, .binary, .hex and .reverse() are refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.percent half = 50%
    satellite.variable.percentage tax = 20%
    satellite.console.display(half)
    satellite.console.display(200 * half)
    satellite.console.display(200 - half)
    satellite.console.display(80 + tax)
    satellite.console.display(half + 25%)
    satellite.console.display(half / 4)
    satellite.console.display(100% / 3)
    satellite.console.display(half < 75%)
    half = half - 75%
    satellite.console.display(half)
    satellite.return(satellite)
}

50%
100
100
96
75%
12.5%
33.33333333333333333333333333333333%
true
-25%

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(50% + 5)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(run): 50% + 5: a percentage is taken off or added onto a number, so the
number goes first -- 5 + 50%

directory: percent_first.satl:5
syntax: satellite.console.display(50% + 5)
                                      /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

satellite.variable.binary

A number written in bits, with a b in front: b1010. satellite.variable.bin is its second spelling. Binary and hexadecimal is the gentle introduction.

• The width is part of the value. A binary shows exactly as you wrote it, leading zeros and all, and b0011 is not b11. There is no length limit.
• The b is required. A binary name given 1010, or C’s 0b1010, is refused before anything runs: ERROR: expected b1010. b12 is refused: a binary digit is 0 or 1.
• A binary keeps a sign: -b0101 is worth -5, keeps its width, and is not equal to b0101. -b0000 is b0000, because zero has no sign.
• Arithmetic reads a binary by what it is worth, and answers a plain number: b1000 + b0101 is 13, and b1010 == 10 is true. A number name given b0011 holds 3. Keeping a sum in a binary name is refused, because the sum is a number.
• .number (also .to_number and .as_number) is what the bits are worth. .string (also .to_string and .str) is the binary as text, b and all. .binary (also .bin and .as_binary) is the digits without the b. .hex (also .as_hex and .to_hex) is its worth in base 16, as text. .reverse() turns the bits round and keeps the width. .add(x) is + x.
• Refused: .width, .digits and .clear, reading one bit with [n], and a binary meeting a float.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.binary flags = b0010
    satellite.console.display(flags)
    satellite.console.display(flags == b10)
    satellite.console.display(flags.number)
    satellite.console.display(flags.string)
    satellite.console.display(flags.bin)
    satellite.console.display(b10101010.hex)
    satellite.console.display(b1000.reverse())
    satellite.console.display(b1000 + b0101)
    satellite.variable.bin below = -b0101
    satellite.console.display(below)
    satellite.console.display(below.number)
    satellite.console.display(below < b0001)
    satellite.return(satellite)
}

b0010
false
2
b0010
0010
AA
b0001
13
-b0101
-5
true

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.binary flags = 1010
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(check): in satellite.main, ERROR: expected b1010

directory: binary_without_b.satl:5
syntax: satellite.variable.binary flags = 1010
        /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

satellite.variable.hex

A number written in base 16, with an x in front: x1F, x00FF, xDEADBEEF. satellite.variable.hexadecimal is its second spelling. The digits are 0 to 9 and A to F; a lower-case digit is read the same, and always shown in capitals.

• The x is required. A hex name given 1F is refused before anything runs: ERROR: expected x1F. C’s 0xFF is refused too.
• A hex keeps the width it was written with, so x00FF and xFF are two different values worth the same. It keeps a sign: -x1F is worth -31.
• In a sum a hex counts as what its digits are worth, and the answer is a number: x1F + 1 is 32, and x1F == 31 is true. So a hex name holds only a hex: h = h + x01 is refused, and the refusal tells you what to write instead. A hex given to a number name keeps its worth.
• .number (also .to_number and .as_number) is what it is worth. .string (also .to_string and .str) is how it shows. .hex (also .as_hex and .to_hex) is its digits, without the x. .binary (also .bin and .as_binary) is its bits, four for every digit. .width counts those bits. .reverse() turns its digits round, width and sign kept. .add(x) is + x.
• Refused: .digits, .clear and .to_binary, and a hex meeting a float, a percentage or a colour.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.hex mask = x00ff
    satellite.variable.hexadecimal red = xFF
    satellite.console.display(mask)
    satellite.console.display(mask + 1)
    satellite.console.display(mask == red)
    satellite.console.display(mask.number)
    satellite.console.display(mask.hex)
    satellite.console.display(mask.binary)
    satellite.console.display(mask.width)
    satellite.console.display(mask.reverse())
    satellite.console.display(-x1F)
    satellite.return(satellite)
}

x00FF
256
false
255
00FF
0000000011111111
16
xFF00
-x1F

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.hex h = x01
    h = h + x01
    satellite.return(satellite)
}

[satellite] satl(run): h was declared satellite.variable.hex, and it was given the number 2 -- a hex name holds only a hex, and arithmetic on a hex answers a number, so keep that in a satellite.variable.number or write the hex it should be: x2 (machine_code: 27 types_do_not_meet)

satellite.variable.color

A colour: exactly six hex digits, two each for red, green and blue. satellite.variable.colour is its second spelling. It shows in capitals with its x: x87CEEB. Colors is the gentle introduction.

• On the line that declares it, the x is optional: 000000, x000000, ff00aa and 00ff00 all work. Five or seven digits are refused before anything runs.
• On a later line, c = x00ff00 always works, and so do c = 123456 and c = abcdef. Digits that start with a number and hold a letter, like c = 00ff00, need their x, and the refusal says so.
• A colour can be see-through. Its transparency is a whole number from 0 (solid) to 99 (almost clear), set with c.transparency(50) or with a comma after the colour: c = x000000, 50. c.transparency reads it back, and a colour with one shows as x000000, 50. 100 or more, or below 0, is refused.
• == and != compare the digits and the transparency. A colour has no order, no arithmetic and no sign.
• .number is what the six digits are worth, .hex is the six digits, .binary is its 24 bits, and .string is how it shows. Each has the same second spellings as a number’s.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color sky = 87ceeb
    satellite.variable.colour ink = x000000, 50
    satellite.console.display(sky)
    satellite.console.display(ink)
    sky.transparency(40)
    satellite.console.display(sky.transparency)
    satellite.console.display(sky)
    satellite.console.display(sky.number)
    satellite.console.display(sky.hex)
    satellite.console.display(sky.binary)
    satellite.console.display(sky == ink)
    satellite.return(satellite)
}

x87CEEB
x000000, 50
40
x87CEEB, 40
8900331
87CEEB
100001111100111011101011
false

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color sky = 87ceb
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(check): in satellite.main, ERROR: 87ceb is 5 hex digits -- a color is
exactly six hex digits, like x00FF00

directory: color_digits.satl:5
syntax: satellite.variable.color sky = 87ceb
        /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

CONVERTING BETWEEN VALUES

satellite converts nothing behind your back. When you want a value as another kind, you ask for it with a method, and the method’s name says what you get. Four methods do all the converting. Each has three spellings, every spelling works on every kind that has the conversion, and any of them may be written with or without ().

.string

.string, also spelled .to_string and .str, answers a value as text, exactly as satellite.console.display would show it. Every kind of value described here has one.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color sky = 87ceeb
    satellite.console.display((87).string + "!")
    satellite.console.display(12.5.string + "!")
    satellite.console.display(b0010.string + "!")
    satellite.console.display(x00FF.string + "!")
    satellite.console.display((1/3).string + "!")
    satellite.console.display((50%).string + "!")
    satellite.console.display(satellite.infinity().string + "!")
    satellite.console.display(sky.string + "!")
    satellite.return(satellite)
}

87!
12.5!
b0010!
x00FF!
1/3!
50%!
(infinity)!
x87CEEB!

.number

.number, also spelled .to_number and .as_number, answers a whole number you can do sums with.

• On a string, it reads the text as a whole number, sign included. Anything else is refused (S120), a point or a space included.
• On a binary, a hex or a colour, it is what the digits are worth.
• On a float, it is the whole number when there is nothing after the point, and refused otherwise (S402).
• On a fraction, a percentage, an infinity or a bool, it is refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color sky = 87ceeb
    satellite.console.display("42".number + 1)
    satellite.console.display("-42".number)
    satellite.console.display(b0010.number + 1)
    satellite.console.display(x00FF.number + 1)
    satellite.console.display(sky.number)
    satellite.console.display(12.0.number)
    satellite.return(satellite)
}

43
-42
3
256
8900331
12

satellite.include(satellite)

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

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S120: NUMBER_NOT_READ
satl(run): that string.number: that text is not a whole number this can read

directory: text_not_a_number.satl:5
syntax: satellite.console.display("3.5".number)
        /\

this is not a number satellite can read. A number is an optional '-' then
digits, with no spaces or separators, and a float has one point in it: 12.34.
machine code 3 int_error -- satl exits with this.

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

.binary

.binary, also spelled .bin and .as_binary, answers base-2 digits as text, with no b in front. It does not make a satellite.variable.binary.

• On a number, its bits. On a string, the bits of the whole number the text holds.
• On a binary, its digits without the b, width kept. On a hex, four bits for every digit. On a colour, its 24 bits.
• On a float, a fraction, a percentage, an infinity or a bool, it is refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color sky = 87ceeb
    satellite.console.display((12).binary)
    satellite.console.display("42".bin)
    satellite.console.display(b0010.binary)
    satellite.console.display(x00FF.binary)
    satellite.console.display(sky.binary)
    satellite.console.display((87).binary.find("111"))
    satellite.return(satellite)
}

1100
101010
0010
0000000011111111
100001111100111011101011
4

.hex

.hex, also spelled .as_hex and .to_hex, answers base-16 digits as text, in capitals, with no x in front. It does not make a satellite.variable.hex.

• On a number, its base-16 digits. On a string, those of the whole number the text holds.
• On a binary, its worth in base 16. On a hex, its digits without the x, width kept. On a colour, its six digits.
• On a float, a fraction, a percentage, an infinity or a bool, it is refused.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.color sky = 87ceeb
    satellite.console.display((255).hex)
    satellite.console.display("255".to_hex)
    satellite.console.display(b10101010.hex)
    satellite.console.display(x00ff.hex)
    satellite.console.display(sky.hex)
    satellite.return(satellite)
}

FF
FF
AA
00FF
87CEEB

Giving a value to a name of another kind

A name holds only its own kind, but a few values fit another kind’s name without any loss, and those are taken:

• A number name given a binary or a hex keeps what it is worth: b0011 becomes 3.
• A float name given a whole number holds it as a float: 3 becomes 3.0.
• A fraction name given a whole number holds it over 1: 3 becomes 3/1.
• An infinity name given a whole number holds that number.

Everything else is refused (machine code 27), including a float given to a number name, even 2.0.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number from_bits = b0011
    satellite.variable.number from_hex = xFF
    satellite.variable.float from_whole = 3
    satellite.variable.fraction over_one = 3
    satellite.variable.infinity plain = 5
    satellite.console.display(from_bits)
    satellite.console.display(from_hex)
    satellite.console.display(from_whole)
    satellite.console.display(over_one)
    satellite.console.display(plain)
    satellite.return(satellite)
}

3
255
3.0
3/1
5

The call forms

Converting is written as a method on the value, never as a call around it. string(87), number("42"), binary(87) and hex(87) are refused, because satl looks for a capsule of yours by that name. satellite.variable.number(x), satellite.variable.string(x), satellite.variable.binary(x) and satellite.variable.hex(x) are numbered words with nothing behind them yet, and satl refuses them too (S210). Write (87).string, "42".number, (87).binary and (87).hex.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display(string(87))
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S110: LINE_NOT_UNDERSTOOD
satl(check): in satellite.main, no capsule named string

directory: call_form.satl:5
syntax: satellite.console.display(string(87))
        /\

satellite has no scenario for this line -- it is spelled in a shape the language
does not have a meaning for.
machine code 13 satl_line_not_understood -- satl exits with this.

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

CONTAINERS

A container holds other values. There is one family of them, and you always say which kind you want. Remember the language’s rule while you read: a dotted path that starts with satellite names something the language owns, like satellite.container.list, and a bare name, like names, is something you own.

satellite.container

satellite.container is the family name, not a type. A line that declares a plain satellite.container is refused, so you always name the kind:

• satellite.container.list: values in a row, counted from 1.
• satellite.container.map: keys and the values filed under them, kept in the order they went in. satellite.container.index is a second word for the same container.
• satellite.container.multiple: one name that may hold any one of several types.

satellite.container.arguments and satellite.container.result are numbered in the language but not built yet. A line that declares one is refused with S110 before anything runs.

These rules hold for every container:

• Braces make a list wherever a value goes: {1, 2} is a list of two, and {} is an empty one. With key: value entries they make a map: {"zoe": 30, "al": 4}.
• A container can hold any other container, to any depth: a list of lists, a map of lists, a list of maps of lists. satellite.access(name) shows the way into every level of one.
• What you write between < and > says what a container holds, and it is checked every time something goes in. With no <>, a container holds anything.
• A container is a value, not a reference. b = a copies it, so changing b leaves a alone. The copy costs nothing until one of them is written to.
• == and != compare what two containers hold. < and > are refused, because there is no order between two containers.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list a = {1, 2}
    satellite.container.list b = a
    b.append(3)
    satellite.console.display(a)
    satellite.console.display(b)
    satellite.console.display(b == {1, 2, 3})
    satellite.console.display(a != b)
    satellite.return(satellite)
}

{1, 2}
{1, 2, 3}
true
true

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list a = {1, 2}
    satellite.container.list b = {3}
    satellite.console.display(a < b)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S301: TYPES_DO_NOT_MEET
satl(run): < was given two lists, and only == and != compare those -- there is
no order between two containers

directory: no_order.satl:7
syntax: satellite.console.display(a < b)
                                    /\

this operator has no scenario for the two kinds it was given. Nothing was
guessed at, because a guess here is an answer that is wrong and does not say so.
machine code 27 types_do_not_meet -- satl exits with this.

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

More in LISTS.

satellite.container.list

A list is a row of values, kept in the order you put them in. You write one with braces: {1, 2, 3} is a list, {} is a list of nothing, {1, "two"} is a list of mixed items, and {{1, 2}, {3}} is a list of lists.

How it is written:

• satellite.container.list name = {...} holds anything.
• satellite.container.list<satellite.variable.string> name = {...} holds strings only, and every way in is checked: the declaration, a[n] = x, .append and .insert.

Items count from 1, the same way a file’s lines do. There is no for-each loop yet, so you walk a list with satellite.statement.for and a[i].

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.list<satellite.variable.string> names = {"zoe", "al"}
    names.append("bo")
    satellite.console.display(names)
    satellite.console.display(names[1])
    satellite.console.display(names.size)

    satellite.container.list row = {30, 4, 100}
    satellite.statement.for(satellite.variable.number i = 1; i <= row.size; i++)
    {
        satellite.console.display(row[i] + 1)
    }
    satellite.return(satellite)
}