Files
In the terminalela --spec files
- Bash redirects stay:
>overwrites stdout's file,>>appends to it,<reads stdin from a file,2>and2>>do the same for stderr. 2>&1sends stderr wherever stdout goes (a file, a pipe, a$( )), and>&2sends stdout wherever stderr goes, for any command; a message of the script's own iswarn "text"(SHELL.md, Built-ins). A command's redirects apply left to right, as in bash:make > all.log 2>&1puts both streams inall.log, andmake 2>&1 > /dev/nullsends stderr where stdout was and drops stdout, soerrors = $(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-in | Does |
|---|---|
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.sizefails there, so a test for a file with something in it isfile.exists(path) and file.size(path) > 0. file.chmodtakes 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 GNUchmodkeeps 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 arer,wandx,sfor set-user-ID withuand set-group-ID withg, andtfor sticky witho:"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 GNUchmoddoes: underumask 022,"+x"on"600"gives"711", and underumask 077it 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".
- Octal digits set the mode as written:
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 offile.info("notes.md")0.02 s, about a hundred times less (atnice -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'] > 1000works, 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 program | Built in |
|---|---|
cp, mv, ln -s, ln | file.copy, file.move, file.link, file.link(…, hard = true) |
stat, touch, mktemp, mktemp -d | file.info, file.touch, file.temp, dir.temp |
du -sb, find | dir.size, dir.walk |
chmod, chown, stat -c %a | file.chmod, file.chown, file.mode |
cmp -s, sha256sum | file.same, hash.sha256 |
realpath, readlink, basename, dirname | path.real, path.link, path.base, path.dir |
test -f, test -d, test -e | file.is_file, file.is_dir, file.exists |
grep on text already in a variable | str.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-in | Program | Does |
|---|---|---|
file.copy(from, to) | cp | Copies 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) | mv | A 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, ln | Makes 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) | stat | A 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) | touch | Sets 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 -d | A 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 -sb | The 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) | find | Every 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, chgrp | Sets 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 -s | Whether 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