EXECLINE-GRAMMAR(7)

📦 version 2.9.9.2, in nixpkgs unstable

💖 EXECLINE-GRAMMAR(7) 💖

okay so this is execline-grammar(7) from the Miscellaneous Information Manual section — it's the page that explains, like, why the execline language exists and how its grammar works. come learn with me bestie 🫶

✨ NAME ✨

execline-grammar — the execline language design and grammar

🌸 DESCRIPTION 🌸

🎀 execline principles

okay so first, some basic Unix facts that we literally have to get through, and then it all makes sense, i promise:

  • Unix programs are started with the execve(2) system call, which takes 3 arguments: the command name (which we won't discuss here because it's redundant in most cases), the command line argv, which specifies the program name and its arguments, and the environment envp.
  • The argv structure makes it easy to read some arguments at the beginning of argv, perform some action, then execve(2) into the rest of argv. For instance, the nice(1) command works that way: nice -10 echo blah will read nice and -10 from the argv, change the process' nice value, then exec(3) into the command echo blah. Some people call this chain loading[1], others call it Bernstein chaining[2]. iconic behaviour tbh ✨
  • The purpose of the environment is to preserve some state across execve(2) calls. This state is usually small: most programs keep their information in the filesystem.
  • A script is basically a text file whose meaning is a sequence of actions, i.e. calls to Unix programs, with some control over the execution flow. You need a program to interpret your script. Traditionally, this program is /bin/sh: scripts are written in the shell language.
  • The shell reads and interprets the script command after command. That means it must preserve a state, and stay in memory while the script is running. 😭
  • Standard shells have lots of built-in features and commands, so they are big. Spawning (i.e. fork(2)ing then exec(3)ing) a shell script takes time, because the shell program itself must be initialized. For simple programs like nice -10 echo blah, a shell is overpowered — we only need a way to make an argv from the "nice -10 echo blah" string, and execve(2) into that argv.
  • Unix systems have a size limit for argv + envp, but it is high. POSIX states that this limit must not be inferior to 4KB — and most simple scripts are smaller than that. Modern systems have a much higher limit: for instance, it is 64KB on FreeBSD 4.6, and 128KB on Linux. 💀

so knowing all that, and wanting lightweight and efficient scripts, the author was like: "Why should the interpreter stay in memory while the script is executing? Why not parse the script once and for all, put it all into one argv, and just execute into that argv, relying on external commands (which will be called from within the script) to control the execution flow?"

and that's how execline was born. periodt. 👑

execline is the first script language to rely entirely on chain loading. An execline script is a single argv, made of a chain of programs designed to perform their action then exec(3) into the next one.

The execlineb(1) command is a launcher: it reads and parses a text file, converting it to an argv, then executes into that argv. It does nothing more. that's it. that's the whole job. main character energy fr fr.

Straightforward scripts like nice -10 echo blah will be run just as they are, without the shell overhead. Here is what the script could look like:

#!/command/execlineb -P
nice -10
echo blah

More complex scripts will include calls to other execline commands, which are meant to provide some control over the process state and execution flow from inside an argv.

🦋 Grammar of an execline script

An execline script can be parsed as follows:

<instruction> = <> |
                external options <arglist> <instruction> |
                builtin options <arglist> <blocklist> <instruction>
<arglist> = <> | arg <arglist>
<blocklist> = <> | <block> <blocklist>
<block> = { <arglist> } | { <instrlist> }
<instrlist> = <> | <instruction> <instrlist>

(This grammar is ambivalent, but much simpler to understand than the non-ambivalent ones.) lowkey a tradeoff but we move 💅

An execline script is valid if it reduces to an instruction.

The empty instruction is the same as the true(1) command: when an execline component must exec into the empty instruction, it exits 0.

Basically, every non-empty instruction, be it "builtin" — an execline command — or "external" — a program such as echo(1) or cp(1) — takes a number of arguments, the arglist, then executes into a (possibly empty) instruction.

Some builtins are special because they also take a non-empty blocklist after their arglist. For instance, the foreground(1) command takes an empty arglist and one block:

#!/command/execlineb -P
foreground { sleep 1 } echo blah

is a valid execlineb(1) script. The foreground(1) command uses the sleep 1 block then exec(3)s into the remaining echo blah instruction. see how it all clicks?? obsessed 🧚

🌈 execline features

execline commands can perform some transformations on their argv, to emulate some aspects of a shell. Here are descriptions of these features:

⭐ SEE ALSO ⭐

cp(1), echo(1), execlineb(1), foreground(1), nice(1), true(1), execve(2), fork(2), exec(3), execline-block(7), execline-substitute(7)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/execline/grammar.html

👑 AUTHORS 👑

Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)

aaaand that's the whole page bestie, you ate that 💅💖 this was the Debian build, dated March 13, 2022 — go forth and chain-load responsibly, ily 🎀✨

📦 where this page comes from