with
In the terminalela --spec with
with changes something for the lines of its block and puts it back at end with, however the
block is left.
| Form | Changes | At end with | Example |
|---|---|---|---|
env.NAME = value | sets an environment variable | its old value, or removed when it was not set | with env.GIT_TERMINAL_PROMPT = "0" |
env.NAME = null | removes an environment variable | its old value, or left removed when it was not set | with env.KUBECONFIG = null |
dir "path" | the folder | the folder before, wherever a cd in the block went | with dir "build" |
usage.bar = on or off | shows or hides ela --usage's bar | shown again when it was shown | with usage.bar = off |
run.max = N | at most N jobs at once, N a whole number, 1 or more | the limit before | with run.max = 4 |
time.block = "10m" | a time limit for every line, loop and job of the block | the limit before | with time.block = "10m" |
time.each = "30s" | a time limit for each command the block runs, on its own | the limit before | with time.each = "30s" |
screen | the terminal's alternate screen, as less and vim use it | the screen as it was before | with screen |
with env.GIT_TERMINAL_PROMPT = "0" git ls-remote $urlend with with dir "build", env.LANG = "C", time.block = "10m" cmake .. make allend with config = toml.decode(file.read("ci.toml"))with time.block = $config["timeout"] while not curl -sf localhost:8080/health > /dev/null sleep 1 end whileend with
- One
withnames several forms, separated by commas:with dir "build", env.LANG = "C", time.block = "10m". They are made in order and put back last first. - A
withinside another changes what the outer one set, and at itsend withthe outer one's value is back. - A
withblock owns the jobs started in it and waits for them atend with, before anything is put back (Process control). - What a
withchanged is put back however the block is left: at its end, bybreak,continueorreturn, by a failed command, an error or a signal. - A block's body may stand on its line after a
;, which its end closes:with dir "build"; make all. with usage.bar = offis for a command that wants the whole terminal;onshows the bar in a block that hid it. The value is the wordonoroff. Without the bar, as off a terminal, the block runs as it is (SHELL.md, The bar). The interactive shell's own bar isusage.bar = onin init.ela or at the prompt (SHELL.md, A bar at the prompt); a script refuses that line.with run.maxand$run.slotare in Process control.
with screen #
with screen shows its block on the terminal's alternate screen, the one less and vim draw
on, and at end with the terminal shows what it showed before, the block's output gone with the
screen. It is for a script that asks several questions or draws a menu, and leaves no trace of
them in the scrollback.
with screen echo "Choose what to deploy" target = ask.choose("Deploy to?", $targets) ok = ask.yes("Deploy to $target now?")end withecho "chosen: $target"
- Inside the block, what the script and its commands print goes to the alternate screen, and the
prompts of the
askpackage work there as anywhere (PACKAGES.md, Asking the user). - The screen is given back however the block is left: at its end, by an error, by
exit, and after Ctrl-C or another signal that ends the script, which waits until the screen is back, as it waits for deferred lines. An error's message is printed once the screen is back, where it can be read. - A
with screeninside another changes nothing: the outermost one enters the alternate screen and gives it back. - With no terminal (cron, CI, a pipe, a browser page) the block is an error at its
withline, as a prompt is:with screen needs a terminal to show its block on, and stdin is not one.
time.block and time.each #
with takes two time limits, both durations as text:
| Form | Ends | Then |
|---|---|---|
with time.block = "2m" | the whole block: every line of it, its loops and the jobs it starts | the script stops at the with line, exit 124 |
with time.each = "30s" | each command the block runs, on its own: one past it is ended | the command exits 124, as timeout gives; try on it gives an Error.TIMEOUT and goes on |
- The duration is text in Go's form, numbers with units
ns,us,ms,s,mandh:"90s","1.5h","1h30m". It is read when thewithline runs, as a TOML, JSON or YAML file's durations are read, so a config file'stimeout = "10m"passes straight in. Text that is no duration, a number or zero is an error at the line. - Past
time.block's limit, the command the block waits for gets TERM, with every process it started, and so does each of the block's jobs; KILL follows 3 seconds later for any still there. Then the script stops at thewithline with a message that names the limit and the line that was running, and exits 124, astimeoutdoes. The stop is a failure thattryon a call catches:err = try fetch_all()gives an Error of kindError.TIMEOUTand the script goes on. - Past
time.each's limit, the one command gets TERM, with every process it started, and KILL 3 seconds later, and exits 124.tryon that command gives an Error of kindError.TIMEOUT, its code 124, and the block goes on to its next line; withouttrythe script stops at the command, with the limit in the message. A command in a job the block starts has the limit too, in the job. time.eachlimits programs: a shell built-in such asecho, a proc's own lines and awaithave none of their own. A pipeline is one command: its stages end together.- The two nest, and a command ends at the nearer of its own limit and the block's. A nested
withof either puts the limit before back atend with; a block ends at the nearer of its own limit and the one around it, and a command at the nearer of itstime.eachand an outer one. - One command with a limit is the one-line
with, its body after a;:with time.each = "20s"; out, err = try $(git status). A variable it sets is there after the line, as blocks make no scope. with time.eachis ela's form oftimeout 30 cmd. GNU'stimeoutis still the program, and works;ela --lintgives a hint on a line that runs it.- At the prompt the same holds, and the prompt comes back.
with time.each = "30s" for repo in $repos err = try git -C $repo fetch -q if error.is($err, Error.TIMEOUT) warn "$repo: no answer in 30s" end if end forend with
Without the try:
fetch.ela:3:9: error: git ran past with time.each = "30s" and was ended; to go on, use try: err = try git ...
$ ela <<'EOF'with time.block = "2s" sleep 30end withEOFstdin:1:1: error: with time.block = "2s" ran out while line 2 was running; the block's commands and jobs were ended