ela
Contents

ManualLanguage

Progress and spinners

In the terminalela --spec progress-and-spinners

What a long script shows while it works, drawn on the line it is on, at a terminal only: written to a file or a pipe, neither prints anything but the command's own output.

Built-inDoes
progress(count, total, label = "")Draws label ███░░░ 42% over the line, and ends the line once count reaches total; with no label the line starts at the bar
spin "label" cmd args...Runs the command behind a spinner, its output held back; ends with ✓ label 1.2s or ✗ label 1.2s
spin "label" ... end spinRuns the block's lines behind one spinner and one timer, their output held back; ends the same way
files = path.glob("*.iso")for i, f in $files    cp $f /srv/images/    progress($i + 1, len($files), label = "copying")end forspin "building" makeif not spin "testing" make test    echo "tests failed; the output is above"end ifspin "release"    make test    make lint    scp dist/*.deb $host:end spinspin "fetching"; git fetch; git status --short
  • spin is written before the command, as try is, and runs alone on its line: not in a pipeline, $( ) or run. The command's stdout and stderr are held while it runs; if it fails they are printed in full after the ✗ line. Off a terminal the command runs as it would without spin, its output where it goes.
  • A command that fails under spin stops the script, as it would without it; err = try spin ... gives its failure as an Error instead. A redirect on the line is the command's: spin "x" make > log.
  • spin "label" with nothing after the label on its line is a block, closed by end spin, or by the line's end after a ; like any one-line block. Every line in it runs as it would without spin, ela's own output (echo, warn) and every command's held together; the block ends with one ✓ or ✗ line and its time, and a failed block prints what it held after the ✗, before the error. A failure stops the script there as anywhere else; a catch around the block takes it. The label is any text: spin "deploying $host".
  • A spin inside a spin block, block or command, draws nothing of its own: one spinner a line, and on --usage's bar the outer label with the command running under it.
  • progress draws its bar to fit the terminal, 10 to 40 columns. count is 0 or more and total above 0; the percentage is rounded down, so the line says 100% only when the work is done.
  • Under ela --usage at a terminal both draw in its bar (SHELL.md, The bar).
  • ELA_NO_PROGRESS, set to anything but empty, turns both off for whoever runs the script, with no change to it: ELA_NO_PROGRESS=1 ./release.ela. spin then draws nothing and its command or block runs as it does off a terminal, as without spin, its output where it goes and no ✓ or ✗ line; progress draws nothing. A failure still stops the script, and try spin ... still gives the Error. ela --doctor says when it is set.