The manual
Everything ela does, in its own words.
The language, its packages, the shell, the editors and the agent guide, one page per section. It is the text the binary carries: ela --spec jobs in a terminal prints the part this site has at /docs/jobs/.
Written by an agent
A script an agent hands ela through its shell tool, in a quoted here-document: checked with ela --lint - before it runs, its jobs owned with run and wait, and each one bounded by with time.block, so nothing polls and nothing hangs. See Calling ela in the manual.
# check.ela: build and test two worktrees at once, as an# agent hands it over:# ela --lint - <<'EOF' ... EOF first,# then ela <<'EOF' ... EOF TREES :: ["wk-api-fix", "wk-web-fix"] # Runs make ci in a worktree, its output kept in a log; the# limit ends it, and its commands.proc check(tree: string) -> (log: string) with dir $tree, time.block = "20m" make ci > ci.log 2>&1 end with return "$tree/ci.log"end proc # A job for each worktree. wait gives their results in# order, and stops at a failed one, with its exit code and# the line it failed at.jobs = []for tree in $TREES jobs = list.append($jobs, run check($tree))end forlogs = wait $jobs for log in $logs; echo "passed: $log"Kubernetes manifests
A stream of YAML documents read, changed and written back: every deployment's image to a new tag, a check on its replicas, then kubectl. See Config formats in the manual.
# bump.ela: give every deployment in a manifest the new# image tag, then apply it.# Run as: ela bump.ela deploy.yaml 1.4.0 FILE :: $args[0]TAG :: $args[1] # One file, several documents between ---,# as kubectl takes them.docs = yaml.decode_all(file.read($FILE))changed = 0for d, doc in $docs if $doc["kind"] != "Deployment"; continue # A loop's value is a copy: # a change goes back through the index. containers = $doc["spec"]["template"]["spec"]["containers"] for i, c in $containers image = str.split($c["image"], ":")[0] containers[$i]["image"] = "${image}:${TAG}" changed = $changed + 1 end for docs[$d]["spec"]["template"]["spec"]["containers"] = $containers # A key the manifest lacks is an error that names it, # not an empty value. if $doc["spec"]["replicas"] < 2 warn "${$doc["metadata"]["name"]}: one replica" end ifend for file.write($FILE, yaml.encode_all($docs))echo "$changed containers now on $TAG"kubectl apply -f $FILEIn place of a Bash script
A backup with Bash's traps closed: a variable is one argument, a failed command stops the line, a glob matching nothing is an error, and the tidying up runs however it ends. See Error handling in the manual.
# backup.ela: what a Bash backup script does,# with its traps closed.# Run as: ela backup.ela /srv/photos SRC :: $args[0]DEST :: path.join($env.HOME, "backups", path.base($SRC)) # A variable is always one argument: a folder name with# spaces needs no quotes.dir.create($DEST)stamp = $(date +%Y%m%d)archive = path.join($DEST, "${stamp}.tar.gz") # Tidied up however the script ends:# an error, Ctrl-C or the end.tmp = $(mktemp)defer rm -f $tmp # A failed command stops the script at its line, with its# exit code: no set -e.tar -czf $tmp -C $SRC .mv $tmp $archive # A glob that matches nothing is an error, never the pattern# passed on as a file name.ls -l $DEST/*.tar.gz # Two checks at once, as jobs; wait takes both, and catch# run any that fails.jobs = [run gzip -t $archive, run sha256sum $archive]wait $jobscatch run; warn "$job failed with $code" # try gives the failure as a value instead of stopping:# null, or an Error. Here a missing remote is fine.err = try rsync -a $archive backup.example:/backups/if $err != null; echo "offsite copy skipped: $err"Errors and failures
Each kind of failure handled where it happens: a failed line that stops the script, try turning one into a value, a failed job taken by catch run, Ctrl-C by catch signal, and a defer that tidies up after all of them. See Error handling in the manual.
# fetch.ela: mirror a list of files, with every kind of# failure handled where it happens.# Run as: ela fetch.ela urls.txt LIST :: $args[0] # Undone however the script ends:# the end, an error, or a signal.work = $(mktemp -d)defer rm -rf $work # A failed command stops the script at its line, with its# exit code; nothing to switch on.urls = str.fields(file.read($LIST)) # try turns a failure into a value: null, or an Error with# what failed, a command's exit code and its stderr.err = try ping -c 1 -W 2 mirror.exampleif $err != null warn "mirror unreachable, using the origin: $err"end if # fail with an Error wraps it: "reading PORT: int(...)".port, err = try int(env.get("PORT", "443"))if $err != null; fail "reading PORT", $err # Each download runs as a job;# wait takes them all, in order.failed = 0jobs = []for url in $urls jobs = list.append($jobs, run curl -fsS -o $work/${path.base($url)} $url)end forwait $jobs # A job that fails is taken here, by the block below the# lines that started it.catch run curl failed = $failed + 1 warn "$job failed with $code"end catch # Ctrl-C or kill while the lines above run: the block runs,# then the defer.catch signal INT TERM warn "stopped, nothing copied" exit 130end catch mv $work/* .got = len($urls) - $failedecho "$got of ${len($urls)} files, port $port"