ela
Contents

ManualShell

Running a script

In the terminalela --spec running-a-script

What a run of a script is given before the script's name:

OptionDoes
--watch script.ela [args...]runs the script, and again whenever it, a file it imports or an --also path changes, until Ctrl-C
--finishwith --watch: a change lets the run in progress end, then runs the script once more
--also PATHwith --watch: watches a file or folder the script reads as well; a folder with everything in it. Give it again for another
--clearwith --watch: empties the screen before each run, at a terminal
--usageat a terminal, a bar on the bottom row while the script runs: the task, CPU, memory and disk; when the run ends, prints on stderr its exit code, how long it took, the CPU time, the peak memory, the bytes read from and written to the disk and every byte read and written; with --watch, after each run
ela --watch --also data/ report.ela 2001ela --usage build.ela

Watching a script #

ela --watch finds the files to watch by parsing the script and every file it imports, never running them, and finds them again before each run, so an import added or removed is followed. An import that is not there yet is watched for its making. Each file is watched through the folder that holds it, so an editor that saves by writing a new file and renaming it over the old one is seen; a burst of saves, as a formatter or a checkout makes, is one change.

What --watch runs, and how a change or a read of the terminal ends a run

Each run is an ela of its own, in a process group of its own, with an empty input: the terminal stays the watching ela's, so Ctrl-C ends the watch, stopping the run in progress first, and exits with 130. A change stops the run in progress with TERM to its whole group, so its defer lines and a catch signal TERM block tidy up, then KILL to what is left of the group after 3 seconds, and starts a new run. With --finish the run in progress ends on its own, and the script runs once more after it.

A run never reads the terminal: this is a security feature. The watched files run again on every change, whoever or whatever made it: another program, a checkout, an agent, a synced folder. A line slipped into one of them must not be able to put up a password prompt or read what is typed, so:

  • A run's input is /dev/null.
  • A command that opens the terminal itself, as sudo and ssh do to ask for a password, is stopped by the system before it reads a key, since the run's process group is not the terminal's.
  • The watch sees the stop within a quarter of a second, ends the run's group with KILL, prints ela: the run tried to read the terminal; a watched run can't, for security and the run's end line, and waits for the next change.

A script that needs a password reads it from the keyring ($keyring.NAME), and one that must ask runs without --watch.

A file that does not parse prints its error, file:line:col: error: message, and the next save is waited for; nothing runs until it parses. Each run ends with a line on stderr giving the clock, the exit code and how long the run took, the jobs the run started with run that ended, as --usage counts them, when any did, and , stopped for a change when a change stopped it:

ela: 14:02:11 exit 0 after 1.2sela: 14:02:15 exit 0 after 2.8s, jobs 3 ✓ 1 ✗ela: 14:02:19 exit 143 after 3.4s, stopped for a change

What a run cost #

--usage ends a run with one line on stderr, after everything the script printed, and keeps the script's exit status. It goes before a script, -c or --watch, or alone with a script on stdin:

ela: exit 0 after 1.2s, cpu 840ms, peak 23 MiB, disk ↓ 12 MiB ↑ 3 MiB, io ↓ 1.2 GiB ↑ 40 MiB, jobs 12 ✓ 1 ✗

The CPU time is ela's own and that of every command it waited for (getrusage), user and system together. The peak memory is the largest resident size of ela or of one command it waited for. Both byte counts are ela's and those of the commands it waited for, from /proc/self/io, ↓ read and ↑ written, as the bar has them. disk is what storage saw, the bar's disk summed over the run (read_bytes, write_bytes): a read the page cache answered is not in it, and a file written is, before it is flushed. io is every read and write, files, pipes and the terminal alike (rchar, wchar), the disk's among them, so a pipeline that streams gigabytes through grep shows in io and not in disk. A kernel that keeps no I/O counts leaves them out. jobs counts the jobs the script started with run that ended, ✓ well and ✗ with an error; it is there only when a job ran, and a count of none is left out. Under --watch the line closes each run in place of the plain one, with the clock before it, and counts that run: the run, the commands it waited for, and the jobs it started, which the run counts for the watcher as they end.

The bar #

At a terminal --usage keeps the bottom row for a bar while the script runs, as apt keeps its progress line: a scroll region holds the rows above it, where the output scrolls, and the bar is redrawn in place. When the run ends the bar goes, the terminal has its full height again, and the line above is printed below the output.

Where --usage draws its bar, what the bar's process reads, and the end line

 build.ela 2:15 │ ▘ testing 0:42 │ make test 0:03     cpu ▆█▇▆▆█▇▆█▇ mem ▃▃▃▃▃▃▃▃▃▃ disk ▆██▆█▆██▆█ 
  • The script, first on the left: its name and how long it has run, build.ela 2:15. In a narrow window the name is cut before anything else is; the time stays.
  • The jobs, after a │ while the script has any: the jobs run started and not yet waited for, by what each does, 5 jobs: 1 running · 1 waiting · 1 sleeping · 1 done · 1 failed. A job is running when one of its processes is on a CPU; else waiting when one is blocked on the disk, the network or another process; else sleeping on a timer; stopped when every process of it is stopped, by kill $x STOP or a read of the terminal. Done and failed have ended, well or with an error; failed is red. A job is off the bar once waited for. A state with none is left out.
  • The task, after the jobs: a spin in progress with its frame, label and time; else a progress bar with its counts and the time left at the rate so far; else the command the script waits for, as its words were given, and how long it has run. Under a spin or a progress bar the command follows the │, and after the script and the jobs the task follows one. A command that ended stays a second, so a loop of short ones does not flicker. With none, nothing follows the script.
  • The figures, on the right: the CPU, memory and disk of the run's processes, ela and every command under it, each a sparkline of the last 30 seconds, one sample a second, and no number: the colour says how high a figure is, and the row keeps its width as the figures change. CPU is a share of the whole machine; memory is the resident size; disk is the bytes read from and written to storage a second together, not pipes or the terminal. The run's numbers are printed when it ends (below). A dash stands for a figure not known yet: rates need two samples.
  • One space at the right end, as at the left, at every width: the row ends one cell short of the window whatever it leaves out.

Each figure and each sparkline cell is coloured on a scale from green through amber to red:

FigureGreenAmberRedA sparkline's height
CPUidlehalf of every coreevery core busyits share of the busiest second in the sparkline
memoryup to half the machine'sthree quartersfullits share of the machine's, so a steady figure is a steady height
disk, network1 MiB/s32 MiB/s1 GiB/s, on a log scalea fixed log scale from 1 KiB/s to 1 GiB/s, so the same height is always the same rate

The bar takes 24-bit colour when COLORTERM is truecolor or 24bit, xterm's 256 when TERM names a 256-colour terminal, and the 16 ANSI colours otherwise. With NO_COLOR set to anything it takes none. Labels and separators are dimmed; the background is the terminal's own.

The row is built from the least that is shown: the script with its time, the number of jobs, the task, and CPU's sparkline at 5 cells. The other parts are added back in this order while each fits, and a narrow window loses them in the opposite order:

  1. the jobs' counts in short;
  2. the command after the │;
  3. memory, disk, and network where the bar has it;
  4. the sparklines at 10 cells;
  5. the counts in words.

The script's name counts as 8 cells and the task as 20 for this, each shortened with … when it needs more. What is left goes to the task first, then the command, then the name, and the rest is one gap between the left part and the right. A window of a few columns shows what fits. The counts in short take a symbol a state, 5 jobs 1▸ 1⋯ 1◌ 1✓ 1✗: ▸ running, ⋯ waiting, ◌ sleeping, ‖ stopped, ✓ done, ✗ failed.

When one row would leave a part out and there is a task or a job to show, the bar takes the bottom two rows: the script, the jobs and the task above, the figures below, each row built in the same order on its own. A part is the command, a figure or a sparkline's cells; counts in short in place of words are not one. It goes back to one row when everything fits again. A switch holds for 2 seconds, so a label that grows and shrinks does not flicker between the two. A window of fewer than 15 rows keeps one row. Taking the second row scrolls the output up a line, so the line being written is not covered; giving it back clears it.

 build.ela 2:15 │ 5 jobs 1▸ 1⋯ 1◌ 1✓ 1✗ │ ▖ testing 0:42               cpu ▆█▇▆▆█▇▆█▇ mem ▃▃▃▃▃▃▃▃▃▃ disk ▆██▆█▆██▆█ 

Under the bar, spin and progress draw there and not on the output's line: spin keeps its ✓ label 1.2s or ✗ line in the output and progress its line once the work is done, at a terminal. Without --usage they draw on the output's line (LANGUAGE.md, Progress and spinners).

With --watch the bar stays up between runs; at its right end it says the run and how it ended, run 7 ✓ or run 8 ✗ 2, and between runs waiting for a change after the script. Its figures and the script's time are those of the current run, and stay at the last run's until the next starts.

The bar is drawn once a second, and ten times a second while a spinner turns; the jobs' states are read with the figures, once a second. The region is given back, one row or two, however the run ends: at its end, by exit, an error, Ctrl-C, a signal or a crash. It goes while the run is stopped with Ctrl-Z and comes back when the run is in the foreground again, is set again when the window is resized, and is not drawn while a program has the terminal in raw mode (an editor, a pager, a prompt), whose screen it would write over. It gives its rows back while the command the script waits for is a program that keeps the bottom row with a scroll region of its own, and comes back when the command ends: apt, apt-get and aptitude, whose install progress does, found past sudo, env, nice, ionice, timeout and the like before them (sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y foo). A script hides the bar for a block with with usage.bar = off (LANGUAGE.md, with):

with usage.bar = off    ./installer.shend with

While the bar is up ELA_USAGE_BAR is set for everything the script runs, and an ela --usage among them prints only its line.

Only the line is printed, and not one escape, when stderr is not a terminal, when TERM is unset or dumb, when CI is set, or when the window has fewer than 3 rows or 20 columns.