ela
Contents

ManualLanguage

catch

In the terminalela --spec catch

A catch block takes what stops the lines above it: a signal, or a failed job.

FormCatchesWhereExample
catch signal INT TERM ... end catchthe signals it names, while the lines it covers runscriptscatch signal INT TERM then file.delete($tmp), exit 130
catch signal INT TERM; exit 130the same, its body on its linescriptscatch signal INT; exit 130
catch run ... end catchthe failure of any job the lines it covers started, at its waitscriptscatch run then echo "$job failed: $code"
catch run deploy make ... end catchthe failures of jobs running those procs or programsscriptscatch run deploy then failed = list.append($failed, $job)

Which lines a catch covers #

  • A catch covers 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.
  • catch works in scripts only. At the interactive prompt, Ctrl-C stops the running command (SHELL.md, Errors and interrupts), and try wait $job says 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 exit itself: the work after the block still runs, but nobody is told a stopped script succeeded. exit 0 in the block says it did.
  • fail ends a block as exit does, with its message on stderr: catch signal TERM; fail "stopped before the upload", 8 exits 8, not 128 plus the signal, once the deferred lines have run.
  • TERM is how kill and a system shutdown ask a program to stop, so a TERM block normally ends with exit; 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 make names procs (an imported one as git.clone) and programs, the program's name without its folder and past sudo, doas, env, nice, ionice, timeout, stdbuf, time, nohup and command. A bare catch run takes any job.
  • When wait meets a covered failure, the block runs once for that job, with $job, $code and $output set ($job reads in a string as what the job runs, make test or deploy("api")); the job's value is null, 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't return, break or continue, as it runs inside the wait.

catch, try and defer #

  • There is no try block: try runs one command or one call and gives its failure as a value, and a catch sits below the lines it covers.
  • err = try wait $job gives null, or the job's failure as an Error, and no catch run block runs for it.
  • defer lines run whatever a catch did: 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.

What runs when a proc, a with block or the script ends, and in which order