READING INPUT

A program that only talks is half a conversation. satellite.console.input is the other half: it waits for the person at the keyboard to type a line and press Enter, then hands that line to your program as a string.

Asking a question

Put a prompt in the brackets, and satl writes it with no line break after it, so the cursor waits right beside your question. The answer comes back as a satellite.variable.string, without the Enter at the end. Leave the brackets empty, satellite.console.input(), and it waits without writing a prompt.

This program waits for the keyboard, so it has no output box:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.string name = satellite.console.input("What is your name? ")
    satellite.console.display("Hello, " + name + "!")
    satellite.return(satellite)
}

At a terminal, typing Ada and pressing Enter looks like this:

What is your name? Ada
Hello, Ada!

The prompt also takes the same style options as display: foreground=, background=, bold= and italic=. So satellite.console.input("Your move? ", foreground=xFF8800, bold=satellite.bool.true) asks in bold orange. COLOR ON THE CONSOLE has the details.

Turning an answer into a number

What a person types is always text, even when it is digits. Satellite never converts a value behind your back, so "41" + "1" joins two strings into "411". To do arithmetic, read the number out of the text first with .number:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.string typed = "41"
    satellite.console.display(typed + "1")
    satellite.variable.number n = typed.number
    satellite.console.display(n + 1)
    satellite.return(satellite)
}

411
42

.number reads a whole number: an optional minus sign, then digits. Anything else is refused rather than guessed at, and the report says what happened:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.string typed = "forty-two"
    satellite.console.display(typed.number)
    satellite.return(satellite)
}

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

directory: not_a_number.satl:6
syntax: satellite.console.display(typed.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.

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

Putting both together, you can read the number straight off the call. Again, this one waits for the keyboard:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number first = satellite.console.input("first number: ").number
    satellite.variable.number second = satellite.console.input("second number: ").number
    satellite.console.display("together they make " + (first + second).to_string())
    satellite.return(satellite)
}

Input from a file or a pipe

satellite.console.input reads standard input, so the lines do not have to come from a keyboard. You can pipe them in, which is handy for testing a program without typing the same answers again and again:

printf '12\n30\n' | satl add_two.satl

first number: second number: together they make 42

The prompts run together here because nobody typed anything: at a terminal, your own typing and the Enter key are what move the cursor to the next line.

When the input runs out

A piped file ends, and a person can press Ctrl-D to say “no more”. Either way there will never be another line, so satl stops with S830 INPUT_ENDED and exits with 55. It does not answer an empty line forever. Here is greet.satl again, run with nothing to read, as it is when you run satl greet.satl < /dev/null:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.string name = satellite.console.input("What is your name? ")
    satellite.console.display("Hello, " + name + "!")
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S830: INPUT_ENDED
satl(run): in name = ..., satellite.console.input(prompt) waited for a line, and
the input has ended

directory: greet_nothing.satl:5
syntax: satellite.variable.string name = satellite.console.input("What is your name? ")
                                                                                       /\

satellite.console.input() waited for a line and the input has ended -- a file
piped in ran out, or Ctrl-D was pressed. There will never be another line, so
this stops rather than answering an empty one forever.
machine code 55 input_ended -- satl exits with this.

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

An empty line is different: a person pressing Enter on its own gives your program the empty string "", and the program carries on.

Where next

Every console word is in the FULL REFERENCE. To keep asking until the person is done, see IF, WHILE AND FOR, and for what you can do with the text you get back, STRINGS.