ela
Contents

ManualShell

From bash

In the terminalela --spec from-bash

ela --translate bash reads a bash script, or one line of bash, and writes it as ela: the same commands, with ela's if, for, switch, procs, try and with in place of bash's forms. What it writes parses and is laid out as ela --fmt lays it out. POSIX sh is bash's subset, so a #!/bin/sh script translates too; zsh, fish and other languages are refused.

ela --translate bash deploy.sh > deploy.ela      # a script, as ela on stdoutela --translate bash 'make && make install'      # a lineela --translate bash - < deploy.sh               # a script on stdinela --translate bash --report deploy.sh          # only the counts and the list
  • An argument that names a file is a script, and any other is a line of bash, unless it is one word that ends in .sh or holds a /: that is a script's path, and one that is not there is an error that says so, exit 1, rather than a command to translate.

  • A line with no ela form is kept at its place as a # bash: ... comment, and named on stderr with its line and what to write instead: deploy.sh:12: bash's shopt has no ela form: rewrite it by hand. The exit status is 0 when everything translated, 1 when something was left for hand.

  • A block keeps what translates: a line inside an if that has no ela form is a comment inside the if. A block whose own line has none (an if testing [ -p x ]) is kept whole.

  • Comments and blank lines stay where they were. A script's first line, #!/bin/sh, becomes #!/usr/bin/env ela.

  • --report prints, in place of the script, the lines of code read, how many translated and how many were left for hand, the forms left for hand and the places ela does otherwise, each with a count, then every entry and every variable renamed. Several scripts may be given with --report, for a folder of them: a line each, then the totals by form.

backup.sh is a script of 28 lines without set -e; one of its lines, a shopt, is kept for hand:

ela --translate bash --report backup.sh# backup.sh: 20 lines of code, 19 translated (95%), 1 left for hand## left for hand, by form:#       1  shopt## where ela does otherwise:#       5  a failed command## backup.sh:8: bash went on if this failed; ela stops: write try cmd to go on# backup.sh:9: bash went on if this failed; ela stops: write try cmd to go on# backup.sh:13: bash went on if this failed; ela stops: write try cmd to go on# backup.sh:17: bash went on if this failed; ela stops: write try cmd to go on# backup.sh:26: bash's shopt has no ela form: rewrite it by hand# backup.sh:27: bash went on if this failed; ela stops: write try cmd to go on## renamed: DEST is dest, as an ela variable's name is lower case# renamed: LIST is list, as an ela variable's name is lower case

Failures #

A translated script stops at its first failed command, as every ela script does, whether the bash had set -e or not. bash without set -e goes on after a failed command, which is how cd /srv/old; rm -rf * deletes in the wrong folder when the cd fails; in ela the failure is seen at its line. A failure a script means to pass over is written so in bash, cmd || true or a command in an if, and translates to its ela form, try cmd or a condition, so it goes on as before. For a script without set -e the list names every other command whose failure bash would have passed over: deploy.sh:7: bash went on if this failed; ela stops: write try cmd to go on. set -e and set -o pipefail themselves are left out: they are what ela does.

What it maps #

bashela
a && b, a; ba and b on lines of their own
[ -f x ] && bif file.is_file("x"); b
a || bif not a; b
a || truetry a
out=$(cmd) || exit 1out, err = try $(cmd) and if $err != null; exit 1
! cmd in a conditionnot cmd
NAME=valuename = "value"; a name the script exports is the environment's, env.NAME
export NAME=valueenv.NAME = "value"
NAME=x cmdwith env.NAME = "x"; cmd
$NAME of a variable the script never sets$env.NAME
"$var", ${var}$var
${NAME:-x} of the environmentenv.get("NAME", "x")
${#var}, ${var%.txt}, ${var#v}len($var), str.trim_suffix, str.trim_prefix
${f##*/}, ${f%/*}, ${f%.*}path.base($f), path.dir($f), str.trim_suffix($f, path.ext($f))
${var#*/} and other patternsre.replace with the pattern as a regular expression
${var//a/b}, ${var/a/b}str.replace, and re.replace for the first only
${var^^}, ${var,,}, ${var:1:3}str.upper, str.lower, $var[1:1 + 3]
$(cmd), `cmd`$(cmd)
$((n + 1))${$n + 1} in a word, $n + 1 in an assignment; a name read in arithmetic is a number
$1, $@, $#$args[0], $args, len($args); in a function its parameters
[ -z "$2" ]len($args) < 2
[[ -e x ]], [ -f x ], test -n "$x"file.exists("x"), file.is_file("x"), $x != ""
[ -d x ], [ -x x ], [ -r x ], [ -w x ], [ -L x ] or -hfile.is_dir("x"), file.is_executable("x"), file.is_readable("x"), file.is_writable("x"), file.is_link("x")
[ -s x ]file.exists("x") and file.size("x") > 0
command -v x >/dev/null, which x >/dev/null 2>&1 in a conditionpath.program("x") != ""
$(command -v x), $(which x)path.program("x")
[[ $a == $b ]], -eq, -lt, =~==, ==, <, re.match
[[ $f == *.txt ]]str.match("*.txt", $f)
if … then … elif … else … fiif … else if … else … end if
for x in a b cfor x in ["a", "b", "c"]
for f in *.logfor f in *.log
for x in $listfor x in str.fields($list)
for x in {1..5}for x in range(1, 6)
for ((i=0; i<n; i++))for i in range($n)
while read -r line; do … done < filefor line in $(cat file)
cmd | while read -r linefor line in $(cmd)
until cmdwhile not cmd
case $x in a|b) … ;; *) … ;; esacswitch $x, case "a", "b", case, end switch
case $f in *.txt) …an if with str.match for each pattern
name() { … }, function name { … }proc name(arg1 = "") … end proc, its $1 the parameter; local x="$1" at its start names it x
name a bname("a", "b")
local x=1x = "1" inside the proc
arr=(a b), "${arr[@]}", ${#arr[@]}arr = ["a", "b"], $arr, len($arr)
declare -A m; m[k]=vm = {}, m["k"] = "v"
cmd &, wait $!job = run cmd, wait $job
trap 'rm -f $tmp' EXITdefer rm -f $tmp
trap '…' INT TERMcatch signal INT TERM … end catch at the script's end
(cd dir && make)with dir "dir" … end with
cmd &> f, 2>&1, > /dev/nullcmd > f 2>&1, as written, as written
cmd 2>&1 > /dev/nullas written: both apply redirects left to right
cmd <<EOF … EOFprintf '%s' """ … """ | cmd, or ''' for <<'EOF'
cmd <<< "text"echo "text" | cmd
. lib.sh, source lib.shimport "lib.ela" when lib.ela is beside lib.sh, its functions called as lib.name()
exit 1, return 2, break, continueas written; a return 2 whose status a call reads is left for hand
echo -e "a\tb"echo "a\tb"
printfthe program, as written

A variable's name is lower-cased, RETRIES to retries, unless the script exports it, and one named as an ela word, or as bash's then, do, elif, fi, done or esac, takes a _: done is done_. --report lists each rename. A variable that a function reads and the script sets once, at its top level, is a constant, NAME :: value, which a proc may read.

Left for hand #

These are left for hand, each named in the list with what to write instead.

  • bash's own commands: eval, shopt, select, coproc, getopts, shift, mapfile, aliases, read outside a while read loop, set -x and set +e, and command -v and which other than as a condition with their output dropped or in a $( ), as ela's which is its own.
  • bash's own values: $?, $0, $$, $RANDOM, $IFS and the rest of bash's variables; ${x:+y}, ${x:=y}, ${!x} and a default on the script's own variable.
  • A [ ] test the file package has none for: -r, -w, -p and the like.
  • Process substitution <( ), and a subshell ( ) whose cd or variables must not leak; one that only changes folder is a with dir block.
  • A function in a pipeline, a capture or with a redirect, its exit status used as a condition, or one that reads or sets the script's variables.
  • A return N other than 0 in a function whose status a call reads: in an if or a while, a && or || list, a $? after it, or a bare call under set -e. bash's return 1 makes the call fail; ela's gives a value and the proc never fails. One in a function no call reads stays as written.
  • source of a file with no .ela beside it.

An unquoted $var or $( ) that bash would have split into words is translated as one word and named in the list: bash split $files into words; ela passes it as one, with str.fields to write where the words were meant.

Bash completion files are not translated: each is a function bash runs at each Tab, built on bash's own completion machinery.