ela
Contents

ManualLanguage

Error handling

In the terminalela --spec error-handling

  • The script stops on any failed command: it fails fast.
  • A yes-or-no question to a command is a condition, with no try: if cmd runs its block when the command exits 0, and if not cmd when it exits with any other code. else if and while take the same, while not test -f done. A condition's command that fails is an answer, not a failure, so the script goes on either way.
  • try is for a value: which failure it was (err = try grep -q x f, where grep's 1 is "not found" and 2 a broken file), the output of a command that may fail (out, err = try $(cmd)), why a call failed (data, err = try f()), or running a command and going on whatever happens (try rm old.log). Every form gives null when nothing failed, and an Error (Errors as values) when something did. There is no try block (catch, try and defer).
  • try covers a command that ran and exited with a code, a call that failed on its way, and a fail at any depth below the call; nothing else. A mistake in the script, such as a command not found, a glob that matches nothing or an undefined variable, stops the script even under try, so a typo is never hidden. An expression is no command: n = try $count + 1 stops before line 1 and says to write n = $count + 1. Nor is a variable's key, position or field alone: try $m["k"] stops before line 1 and names map.get($m, "k", fallback) and has($m, "k"), which ask for a key that may be missing. try $cmd, alone or with words after it, runs the program cmd holds, and so does try $m["k"] args.
  • No hidden status variable like Bash's $?. The interactive prompt asks how its last line went with last_status(), which is an error in a script (SHELL.md, Startup config and prompt).
if git pull    echo "ok"end if err = try grep -q TODO notes.mdif error.is($err, 2)    echo "notes.md can't be read: $err.stderr" >&2end if

ela --lint points if try cmd == null to if cmd, and if try cmd != null to if not cmd.

try takes four forms, each giving what the failure was instead of stopping:

FormGives
err = try cmdnull when the command exits 0; otherwise an Error with its exit code and its stderr
out, err = try $(cmd)The output, trimmed as $( ) trims it, then null or the Error
value, err = try call(...)The call's values and null; or, when the call fails, its Error, with the values left unset
err = try wait $jobnull or the job's Error; for a list of jobs, a list of them in the list's order
with time.each = "30s"; out, err = try $(git ls-remote $url)if $err != null    echo "could not ask: $err" >&2end if data, err = try json.decode($body)n, err = try int($word)
  • try $( ) and try on a call are each the whole value of an assignment; anywhere else, as in if try $(cmd) == null, they are an error when the script is read. try $(cmd) | wc -l and try $(cmd) args run a command.
  • The number of names matches what the form gives, as every assignment does: one for a command, two for $( ), the call's values and one more for a call. _ drops one. A call's count is known before it runs, from its proc's return⁠s or the built-in's catalogue entry, and is checked then, whether the call fails or not; a call that returns nothing takes one name, err = try cleanup().
  • try on a call catches what the call ran into on its way: a fail in it or in any proc it calls, however deep, a failed command, a built-in or package proc refusing its input (json.decode, int, file.read, an http call with no answer). A mistake in the script still stops it: an unknown name, a wrong argument, an undefined variable, a missing key or a position out of range, which has and len check first.
  • err = try cmd and out, err = try $(cmd) take the command's stderr, where no redirect sends it elsewhere, into the Error rather than onto the terminal: $err.stderr holds all of it, and the message its last line. 2>&1 puts it in the output instead. A bare try cmd, which goes on whatever happens, leaves stderr on the terminal.
  • A value left unset by a failed call is an error to read, until it is assigned again.
  • What try gave is compared with null, never with a number or text: if $err != "" or if $code != 0 on a name only try assigns, and try cmd == 0, stop before line 1 and name $err != null and error.is. An Error compared with a string or a number as the script runs is the same error.

Errors as values #

An Error is a value: what try gives when something failed, and what fail raises. It prints, in echo, in a string and on stderr when nothing catches it, as its chain: its message, then each cause's, joined with : .

proc read_config(path)    if not file.exists($path)        fail "reading $path: not found", Error.NOT_FOUND    end if    return file.read($path)end proc proc load_site()    text, err = try read_config("config.toml")    if $err != null        fail "loading the site", $err    end if    return $textend proc site, err = try load_site()if error.is($err, Error.NOT_FOUND)    echo "no config yet: $err"end if
no config yet: loading the site: reading config.toml: not found
FieldHolds
kindOne of the Error enum's kinds, below
messageIts own message, without those of its causes
causeThe Error it wraps, or null
codeThe exit code the script stops with when nothing catches it: a command's exit status, the number fail named, otherwise 1
stderrWhat a command run by try wrote to stderr; "" for any other

The kinds are the values of the built-in enum Error, written as Type's are: Error.NOT_FOUND.

KindWhat failed
NOT_FOUNDA file, folder, secret or program that isn't there: file.read of a missing file, a command that exits 127
PERMISSIONSomething not allowed: permission denied, a read-only file system, a command that exits 126
INVALIDInput a built-in refuses: int("x"), a json.decode or toml.decode of broken text
UNAVAILABLEA service that isn't there or won't answer: no keyring on the session, a package not built yet
TIMEOUTA time limit: with time.block ran out, a command past with time.each, a command that exits 124
FAILEDAny other failure: a plain fail, a command's other exit codes, a full disk
  • error.is($err) is true for any Error; error.is($err, Error.NOT_FOUND) when that kind is the Error's or any cause's; error.is($err, 2) when that exit code is. All three are false for null, never an error (PACKAGES.md, Error values). $err != null asks the same as the first.
  • A failed command's Error reads grep -q x f: exited 2: grep: f: No such file or directory, the command as it ran, its exit code, then the last line of its stderr when try took it; its kind is NOT_FOUND for 127, PERMISSION for 126, TIMEOUT for 124 and FAILED for any other code.
  • An Error's fields are read with a dot and never written: context is added by wrapping it, fail "loading the site", $err. Error{...} is no literal: fail makes one.
  • Error as a parameter's type takes an Error: proc report(err: Error), and err: Error? takes null too. type_name calls a kind an Error kind.

fail #

fail "message" raises an Error with that message. The try on the nearest call above it catches it, however many calls down it was raised; with none, the script stops: the lines deferred so far run (defer), ela: and the Error's chain go to stderr, and the script exits 1.

fail takes the message first, then at most one more value, told apart by its type:

FormRaises
fail "no config at $path"An Error of kind Error.FAILED
fail "no config at $path", Error.NOT_FOUNDAn Error of that kind
fail "loading the site", $errAn Error that wraps $err as its cause, and takes its kind
fail "no input file given", 2An Error of kind Error.FAILED that, caught by nothing, exits 2; from 1 to 255
path = "/etc/app.toml"if not file.exists($path)    fail "no config at $path", Error.NOT_FOUNDend ifif len($args) == 0    fail "no input file given", 2end if
ela: no config at /etc/app.toml
  • An Error nothing catches exits 1 whatever its kind, unless fail named a number: the kind is for the script that catches it, and the exit code for the program that ran it. A wrap is its own fail, so fail "loading the site", $err exits 1 whatever code $err held; error.is($err, 2) still finds a cause's code.
  • A second extra value, fail "x", Error.NOT_FOUND, 3, stops before line 1; so does a value of any other type, fail "x", "y", a literal number outside 1 to 255, or a literal null. A cause that is null as the script runs, from a try that went well, is an error naming if $err != null.
  • In a catch signal block, fail sets the exit code, as exit there does, rather than 128 plus the signal. At the interactive prompt, an Error nothing catches is said as ela: and its chain, and the prompt carries on.
  • warn writes a message and the script goes on; exit stops it with no message and no Error, which no try catches. The message is text and the code a failure's: fail 42 and fail "x", 0 stop the script before line 1.
  • There is no die. Written where it is no proc of the script's and no program on PATH, it stops the script before line 1: ela stops a script with fail "…". A script's own proc die is its own, and so is a program die. error is the package of error.is; a command error that is no program is a command not found.