ela
Contents

ManualPackages

Files

In the terminalela --spec files

  • Bash redirects stay: > overwrites stdout's file, >> appends to it, < reads stdin from a file, 2> and 2>> do the same for stderr.
  • 2>&1 sends stderr wherever stdout goes (a file, a pipe, a $( )), and >&2 sends stdout wherever stderr goes, for any command; a message of the script's own is warn "text" (SHELL.md, Built-ins). A command's redirects apply left to right, as in bash: make > all.log 2>&1 puts both streams in all.log, and make 2>&1 > /dev/null sends stderr where stdout was and drops stdout, so errors = $(make 2>&1 > /dev/null) captures stderr alone.
  • One redirect per stream on a command. 1> is written >, and other descriptors (3>) are refused.
  • Built-ins work on whole files: there are no open and close handles.
Built-inDoes
file.read(path)Returns the contents as a string
file.write(path, text)Creates or overwrites
file.append(path, text)Appends
file.delete(path)Deletes a file; a directory is dir.delete
file.exists(path)Returns a boolean
file.is_dir(path)Whether a folder is at the path, through a link too
file.is_link(path)Whether the path is a symbolic link, one that points nowhere too
file.is_executable(path)Whether a file at the path, through a link too, is one this user may run; a folder is not
file.is_file(path)Whether a regular file is at the path, through a link too, as test -f has it; a folder, a device or a pipe is not
file.is_readable(path)Whether what is at the path, through a link too, is one this user may read, a folder too, as test -r has it
file.is_writable(path)Whether what is at the path, through a link too, is one this user may write, a folder too, as test -w has it; a read-only mount is not
file.size(path)The size in bytes of what is at the path, through a link; nothing there is an error
file.mode(path)The mode of what is at the path, through a link, in octal as chmod takes it and stat -c %a prints it: "644", and four digits with a set-user-ID, set-group-ID or sticky bit set, "4755" or "1777"; nothing there is an error
file.chmod(path, mode)Sets the mode of what is at the path, through a link, as GNU chmod does: octal such as "755" or "1777", or a change such as "+x" or "g-w,o="; nothing there is an error
file.copy(from, to)Copies a file's bytes and permission bits, as cp does; a folder as to takes it under its own name
file.move(from, to)Renames a file or folder, as mv does; across disks a file is copied, then deleted
file.link(target, name, hard = false)Makes name a symbolic link holding target as written, as ln -s does, or a hard link, as ln does
file.info(path, follow = true)A map of what is at the path, as stat gives it
file.touch(path, time = null)Sets the modified time, now unless a time is given; makes the file empty when it is missing
file.temp()A new empty file in the temporary folder, as mktemp makes one, removed when the script ends
file.chown(path, owner = "", group = "")Sets the owner, the group or both, by name or number, as chown does
file.same(a, b)Whether two files hold the same bytes, as cmp -s answers
  • The tests read the path's metadata by name and never open it, so a named pipe with no writer answers at once. Each is false when nothing is at the path; file.size fails there, so a test for a file with something in it is file.exists(path) and file.size(path) > 0.
  • file.chmod takes the mode as text, in one of two forms:
    • Octal digits set the mode as written: "644", "4755", "1777". On a folder, fewer than five digits keep its set-user-ID and set-group-ID bits, as GNU chmod keeps them, and five clear them: "755" on a set-group-ID folder leaves it "2755", and "00755" makes it "755".
    • A change is a who, then an operator and the bits it acts on. The who is u (the owner), g (the group), o (others), a (all three) or a mix of them. + adds the bits, - takes them away and = sets the who's bits to exactly these. The bits are r, w and x, s for set-user-ID with u and set-group-ID with g, and t for sticky with o: "u+x", "go-w", "a=r", "ug+s", "o+t". A change with no who, "+x", reaches all three but leaves alone the bits the umask holds, as GNU chmod does: under umask 022, "+x" on "600" gives "711", and under umask 077 it gives "700".
    • Changes go one after another, separated by commas, and one change may hold several operators: "u+rwx,o=", "u+r-w".
    • Anything else is an error that says so, before the path is looked at: "8", "+X", "u=g" and "17777".
file.chmod("deploy.sh", "+x")file.chmod("/srv/drop", "1777")file.chmod("notes.md", "g-w,o=")echo ${file.mode("/srv/drop")}

prints 1777, and file.chmod("x", "8") stops with file.chmod: "8" is not a mode: give octal digits such as "644" or "1777", or a change such as "+x" or "g-w".

if not file.is_dir($dest)    dir.create($dest)end ifif file.is_executable("/usr/sbin/update-grub")    update-grubend ifif file.exists($log) and file.size($log) > 10_000_000    gzip $logend ifif file.is_file($key) and file.mode($key) != "600"    chmod 600 $keyend if

File programs #

A built-in or a command #

A job on files can be done with a command or with a built-in proc, and both work: ela runs stat, cp or grep as any shell does. The built-in starts no process, and it gives an ela value, a number, a list or a map, where the command gives text to parse.

# a command: works, starts a process, gives textout = $(stat -c '%a %s' notes.md)# built in: no process, gives ela valuesinfo = file.info("notes.md")echo "$info['mode'] $info['size']"
  • A process costs time. On this build, 1,000 runs of $(stat -c '%a %s' notes.md) took 2.1 s, and 1,000 calls of file.info("notes.md") 0.02 s, about a hundred times less (at nice -n 19). In a loop over many files, or at every start of a tool, that is the difference.
  • The value needs no parsing: $info['size'] is a number, so $info['size'] > 1000 works, where the command's text is split and converted first, and a file name with a space breaks a split.
  • A command stays the choice where no built-in does the job, or where a flag the built-in lacks is wanted: cp -a, find -newer, du -h.
A programBuilt in
cp, mv, ln -s, lnfile.copy, file.move, file.link, file.link(…, hard = true)
stat, touch, mktemp, mktemp -dfile.info, file.touch, file.temp, dir.temp
du -sb, finddir.size, dir.walk
chmod, chown, stat -c %afile.chmod, file.chown, file.mode
cmp -s, sha256sumfile.same, hash.sha256
realpath, readlink, basename, dirnamepath.real, path.link, path.base, path.dir
test -f, test -d, test -efile.is_file, file.is_dir, file.exists
grep on text already in a variablestr.contains, re.match, re.find_all

The ten programs #

Ten GNU programs a script called for one system call's worth of work are built in, through amber-lib's amber_fs, so a script starts no process for them and ela and the house's own programs behave alike. Each acts as the program does without flags, and a failure stops the script with the path and the reason, which try catches:

copy.ela:3:1: error: file.copy: "notes.txt" is missing
Built-inProgramDoes
file.copy(from, to)cpCopies a file's bytes and permission bits through a temporary file renamed into place, so a reader of to sees the old file or the whole new one. A folder as to takes the file under its own name, as cp f dir/ does; a file there is replaced. A folder as from is an error that says to run cp -r, and a file copied onto itself, by any name, is an error
file.move(from, to)mvA rename on the same disk, of a folder too, replacing what is at to; across disks a file is copied with its mode and modified time, then deleted, and a link is made again. A folder across disks is an error that says to run mv. A folder as to takes from under its own name
file.link(target, name, hard = false)ln -s, lnMakes name a symbolic link holding target as written, which path.link reads back, or with hard = true a second name for the file. A name already there is an error, as for ln without -f
file.info(path, follow = true)statA map: kind ("file", "dir", "link", "missing" or "other"), size, mode as file.mode gives it, modified as a time, as time.now() gives one, owner and group as names, their numbers as text where no name is known, links and inode. A link is followed unless follow = false; nothing there is kind "missing", with the rest empty
file.touch(path, time = null)touchSets the modified time, and the access time with it, to time, now when it is left out; a missing file is made empty first
file.temp(), dir.temp()mktemp, mktemp -dA new empty file or folder under $TMPDIR, else /tmp, that only its owner may read: its path. It is removed when the script ends, after an error or a signal too; a script that wants it kept moves it
dir.size(path)du -sbThe bytes the files below the folder hold, as du -sb counts them: each hard-linked file once, a link's own few bytes and a folder's none, links not followed, other disks not entered
dir.walk(path, fold = false)findEvery path below the folder, as a list built whole: each folder before what is in it, the names at each level sorted as dir.list sorts them, fold = true too, links listed and not followed
file.chown(path, owner = "", group = "")chown, chgrpSets the owner, the group or both, by name, from /etc/passwd and /etc/group, or by number; an empty one is left as it is. On a link, the file it points to. A name neither file has is an error, said before the path is looked at
file.same(a, b)cmp -sWhether two files hold the same bytes, sizes compared first; a missing file or a folder is an error
file.copy("ela.toml", "/home/ada/backup/")echo ${file.mode("/home/ada/backup/ela.toml")}file.move("build/out.deb", "dist/")file.link("../ela/roots.ela", "scripts/roots")echo ${path.link("scripts/roots")}info = file.info("/tmp")echo "$info['kind'] $info['mode'] $info['owner']"

prints 644, ../ela/roots.ela and dir 1777 root. json.encode(file.info("/tmp")) gives the whole map as text:

{  "kind": "dir",  "size": 4096,  "mode": "1777",  "modified": 981169506.7,  "owner": "root",  "group": "root",  "links": 18,  "inode": 2}

A scratch folder, a stamp and a filter over a tree, with ela's own for and if in find's place:

work = dir.temp()file.touch("$work/.stamp")for p in dir.walk("src")    if path.ext($p) == ".odin" and file.size($p) > 100000        echo $p    end ifend forecho ${text.bytes(dir.size("build"))}file.chown("/srv/site", group = "www-data")if not file.same("ela.toml", "/home/ada/backup/ela.toml")    echo "changed"end if