ela
Contents

ManualLanguage

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.

FormChangesAt end withExample
env.NAME = valuesets an environment variableits old value, or removed when it was not setwith env.GIT_TERMINAL_PROMPT = "0"
env.NAME = nullremoves an environment variableits old value, or left removed when it was not setwith env.KUBECONFIG = null
dir "path"the folderthe folder before, wherever a cd in the block wentwith dir "build"
usage.bar = on or offshows or hides ela --usage's barshown again when it was shownwith usage.bar = off
run.max = Nat most N jobs at once, N a whole number, 1 or morethe limit beforewith run.max = 4
time.block = "10m"a time limit for every line, loop and job of the blockthe limit beforewith time.block = "10m"
time.each = "30s"a time limit for each command the block runs, on its ownthe limit beforewith time.each = "30s"
screenthe terminal's alternate screen, as less and vim use itthe screen as it was beforewith 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 with names 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 with inside another changes what the outer one set, and at its end with the outer one's value is back.
  • A with block owns the jobs started in it and waits for them at end with, before anything is put back (Process control).
  • What a with changed is put back however the block is left: at its end, by break, continue or return, 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 = off is for a command that wants the whole terminal; on shows the bar in a block that hid it. The value is the word on or off. Without the bar, as off a terminal, the block runs as it is (SHELL.md, The bar). The interactive shell's own bar is usage.bar = on in init.ela or at the prompt (SHELL.md, A bar at the prompt); a script refuses that line.
  • with run.max and $run.slot are 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 ask package 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 screen inside 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 with line, 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:

FormEndsThen
with time.block = "2m"the whole block: every line of it, its loops and the jobs it startsthe script stops at the with line, exit 124
with time.each = "30s"each command the block runs, on its own: one past it is endedthe 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, m and h: "90s", "1.5h", "1h30m". It is read when the with line runs, as a TOML, JSON or YAML file's durations are read, so a config file's timeout = "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 the with line with a message that names the limit and the line that was running, and exits 124, as timeout does. The stop is a failure that try on a call catches: err = try fetch_all() gives an Error of kind Error.TIMEOUT and 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. try on that command gives an Error of kind Error.TIMEOUT, its code 124, and the block goes on to its next line; without try the 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.each limits programs: a shell built-in such as echo, a proc's own lines and a wait have 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 with of either puts the limit before back at end with; a block ends at the nearer of its own limit and the one around it, and a command at the nearer of its time.each and 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.each is ela's form of timeout 30 cmd. GNU's timeout is still the program, and works; ela --lint gives 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