catch
In the terminalela --spec catch
A catch block takes what stops the lines above it: a signal, or a failed job.
| Form | Catches | Where | Example |
|---|---|---|---|
catch signal INT TERM ... end catch | the signals it names, while the lines it covers run | scripts | catch signal INT TERM then file.delete($tmp), exit 130 |
catch signal INT TERM; exit 130 | the same, its body on its line | scripts | catch signal INT; exit 130 |
catch run ... end catch | the failure of any job the lines it covers started, at its wait | scripts | catch run then echo "$job failed: $code" |
catch run deploy make ... end catch | the failures of jobs running those procs or programs | scripts | catch run deploy then failed = list.append($failed, $job) |
Which lines a catch covers #
- A
catchcovers the lines above it, back to the previous block at the same level that catches the same thing, or to the start of the file, proc or block it is in. A line is covered by the first block below it that catches its signal, or its job's name. - A proc or a loop with no block of its own is covered by the block that covers its call or the loop: a signal leaves them on its way up, and a job started in them is covered where the call is.
- ela reads the whole script before it runs, so which block covers which line is known from the start.
- A script that reaches a block with nothing to catch skips it.
catchworks in scripts only. At the interactive prompt, Ctrl-C stops the running command (SHELL.md, Errors and interrupts), andtry wait $jobsays how a job ended.
catch signal #
catch signal replaces Bash's trap. It names one or more of INT, TERM, HUP, QUIT, USR1, USR2
and WINCH, by name and in capitals; KILL and STOP can't be caught. A number, catch signal 15,
stops the script before line 1 with its name, 15 is signal TERM: write catch signal TERM, and
term or sigterm with write it in capitals: catch signal TERM.
- When the signal arrives, the running command gets it too (Ctrl-C stops
make), the rest of the covered lines are skipped, the block runs, and the script carries on after the block. - A signal no block covers ends the script by that signal, as without any handler, once the lines deferred so far have run (defer): the shell that started it sees 128 plus the signal (130 for INT).
- The same signal again while its block runs ends the script at once, so a second Ctrl-C always works.
- A script that reaches its end after a block caught a signal exits with 128 plus that signal, unless a block ran
exititself: the work after the block still runs, but nobody is told a stopped script succeeded.exit 0in the block says it did. failends a block asexitdoes, with its message on stderr:catch signal TERM; fail "stopped before the upload", 8exits 8, not 128 plus the signal, once the deferred lines have run.- TERM is how
killand a system shutdown ask a program to stop, so a TERM block normally ends withexit; one that carries on keeps the script running until it is killed outright.
One block at the end of the script catches the signal anywhere above it, in procs called from there too:
proc build() make allend proc build()cp build/app /srv/app catch signal INT TERM echo "stopped, tidying up" file.delete("/srv/app.partial")end catch
Blocks in the middle cover the lines since the block before them, and the script carries on after each:
make all # covered by the first blockcatch signal INT echo "build stopped"end catchmail -s report ops < log # covered by the second blockcatch signal INT echo "report not sent"end catchecho done # covered by no block: Ctrl-C here exits with 130
catch run #
catch run takes the failures of the jobs started by the lines it covers. A job is covered by the
block that covers the line that started it.
failed = []jobs = []for host in $hosts jobs = list.append($jobs, run deploy($host))end forversions = wait $jobs # null for each host whose deploy failedecho "deployed; ${len($failed)} failed" catch run deploy failed = list.append($failed, $code) echo "$job failed with $code:\n$output" >&2end catch
catch run deploy makenames procs (an imported one asgit.clone) and programs, the program's name without its folder and pastsudo,doas,env,nice,ionice,timeout,stdbuf,time,nohupandcommand. A barecatch runtakes any job.- When
waitmeets a covered failure, the block runs once for that job, with$job,$codeand$outputset ($jobreads in a string as what the job runs,make testordeploy("api")); the job's value isnull, and the wait carries on, so several failures run the block once each, in the list's order. The script then carries on after the wait, not after the block. The block can'treturn,breakorcontinue, as it runs inside the wait.
catch, try and defer #
- There is no
tryblock:tryruns one command or one call and gives its failure as a value, and acatchsits below the lines it covers. err = try wait $jobgives null, or the job's failure as an Error, and nocatch runblock runs for it.deferlines run whatever acatchdid: a caught signal leaves the script running, and they run at its end; a signal no block covers runs them before it ends the script.