v0.4.0
Errors · Lesson 9.12

Fallible main

Source
Declare func Main() throws E (or func Main() -> int throws E) so plain try works at the top level, and see that an error ends the program with exit status 1 without printing anything.
You'll need: Unit fallible, Propagate

Every program so far ended with return 0; from func Main() -> int. That made plain try useless at the top level: Main could not throw, so an error had nowhere to go, and every step had to be caught by hand.

Main may also throw. Then plain try works at the top level too, and an error that reaches Main ends the program.

Main may throw

The installer in this lesson reserves disk space for two programs. Reserve throws a SpaceError when there is not enough room, and Main declares the same error:

func Main() throws SpaceError {
    var free = 100;
    PrintLine("Installing the editor (40 MB of {} MB free)", free);
    free = try Reserve(40, free);

Main now has no return type, like the functions in Unit fallible, so it follows the same rules: falling off its end is success, and it has no return 0;. The second reservation asks for 90 MB with only 60 free, so its try passes the error out of Main and ends the program — the last PrintLine never runs.

How the program ends

The operating system receives a number when a program ends, its exit status. 0 means success; anything else means something went wrong.

Main is declaredand ends byExit status
-> intreturn n;n
throws Ereaching its end0
-> int throws Ereturn n;n
throws E or -> int throws Ea throw, or an error from try1

An error still runs the program's ordinary cleanup on the way out — every defer and destructor, just as a return would — unlike a panic, which stops at once.

An error prints nothing

The surprise is what an error does not do: it prints nothing. The SpaceError value is not shown anywhere, so a user only sees the program stop after the second line.

The exit status is for whoever started the program — a script, a build tool or a shell. In PowerShell, echo $LASTEXITCODE shows it right after the program ends; in a POSIX shell such as bash, it is echo $?. That 1 is the last line of the output below.

If a person should learn why the program stopped, print a message yourself before throwing. A catch arm can do both — print, then throw the same error on:

free = try Reserve(90, free) catch {
    e => {
        PrintLine("Not enough space: {} MB needed, {} MB free", e.needed, e.free);
        throw e;
    }
};

The arm e => ... binds the whole error, and its block ends by leaving, so it never has to produce a value.

The program

The whole lesson is one package in the Examples repository. Its comments explain every step.

Src/Main.rux
// Every program so far ended with `return 0;` from `func Main() -> int`. `Main`
// may also throw, with or without an `int` result:
//
//     func Main() throws SpaceError
//     func Main() -> int throws SpaceError
//
// Now plain `try` works at the top level too: an error that reaches `Main`
// leaves it like any other error leaves a throwing function. Falling off the
// end of a `Main` with no result is success, and the program exits with
// status 0. An error — from a `throw` in `Main` or passed on by a `try` —
// ends the program with exit status 1, after every `defer` and destructor on
// the way out has run.
//
// The surprise is what an error does *not* do: it prints nothing. The error
// value is not shown anywhere, so a user only sees the program stop. If they
// should learn why, print a message yourself before throwing. The exit status
// is for whoever started the program: a script, a build tool or a shell. In
// PowerShell, `echo $LASTEXITCODE` shows it right after the program ends.
//
// This program fails on purpose: the second install does not fit.
import Io::PrintLine;

struct SpaceError {
    needed: int;
    free: int;
}

func Reserve(needed: int, free: int) -> int throws SpaceError {
    if needed > free {
        throw SpaceError { needed: needed, free: free };
    }
    return free - needed;
}

func Main() throws SpaceError {
    var free = 100;
    PrintLine("Installing the editor (40 MB of {} MB free)", free);
    free = try Reserve(40, free);

    PrintLine("Installing the compiler (90 MB of {} MB free)", free);
    free = try Reserve(90, free);

    // Never printed: the `try` above passed the error out of `Main`, which
    // ended the program with status 1.
    PrintLine("Everything is installed, {} MB left", free);
}

Run it

cd Examples/Errors/FallibleMain
rux run
echo $?

The program fails on purpose, so it stops after the second line, and echo $? prints its exit status, 1. In PowerShell, use echo $LASTEXITCODE instead.

Installing the editor (40 MB of 100 MB free)
Installing the compiler (90 MB of 60 MB free)
1

Common mistakes

Try it yourself

  1. Change the compiler's 90 MB to 50 and run again. What does echo $LASTEXITCODE show now?
  2. Replace the second try with the catch above, so the user learns why the install stopped.
  3. Declare func Main() -> int throws SpaceError, end it with return 2;, and check the exit status when everything fits.

Learn more