Execline

execline is an interpreter and a collection of utilities for composing Unix commands into scripts. The syntax of execline makes it better suited for code generation from Nix than interactive shell languages like Bash.

execlineb

execlineb is the interpreter for execline scripts. It reads a file, produces a command-line, and executes into that command line. execlineb manages the environment of the command that it executes and optionally substitutes the arguments a script receives into the command-line. execlineb also handles the quoting of strings using "" and blocks using {}. Blocks are described later in this article.

Wrappers

Consider the scenario of wrapping a program to override or set a default value for the EDITOR enviroment variable.

The following example is a script that uses the export program to set EDITOR. Here the -s0 option is used to replace $1 and $@ within the command-line with the first and remaining arguments received by the script.

≡︎ wrap-editor.el

#! /usr/bin/env execlineb -s1
export EDITOR $1
$@

If the script is executed as wrap-editor.el nano mutt then the command-line executed by execlineb would be export nano mutt.

To create a wrapper that would provide a default EDITOR the importas program would be used. In the following example the EDITOR value is imported from the calling enviroment, with a default value specified by -D, and any instance of $editor is replaced by that value. The export program exports the value of $editor after substitution.

≡︎ wrap-default-editor.el

#! /usr/bin/env execlineb -s1
importas -D $1 EDITOR $editor
export EDITOR $editor
$@

Generating a wapper from Nix

To generate a wrapper with a fixed default for EDITOR the Nix function at execline.passthru.writeScript can be used:

{ pkgs ? import <nixpkgs> { } }:

pkgs.execline.passthru.writeScript "wrap-nano" "-s0" ''
  importas -D ${pkgs.nano}/bin/nano EDITOR E
  export EDITOR $E
  $@
''

Blocks

Some execline programs take code blocks as their arguments. Blocks are delimited by {} in execlineb scripts. In the following example the pipeline program executes a block of commands in the background with a pipe connecting the stdin of that block to the stdout of the command-line following the block.

{ pkgs ? import <nixpkgs> { } }:

pkgs.execline.passthru.writeScript "wrap-cowsay" "-s0" ''
  pipeline -w { ${pkgs.lib.getExe pkgs.cowsay} "-r" }
  $@
''

Block quoting

execlineb parses {} blocks and constructs a command-line where each block item is prepended with a whitespace (\x20) and terminated with an empty string. This quoting can be done in pure Nix.

Given the function quoteExecline as

builtins.foldl' (acc: arg: acc ++ (
  if builtins.isList arg
    then map (_: " ${_}") (quoteExecline arg) ++ [ "" ]
    else [ arg ]
  )) [ ];

then the expression

args: lib.escapeShellArgs (quoteExecline [ "pipeline" "-w" [ (lib.getExe pkgs.cowsay) "-r" ] ] ++ args)

would produce the command-line executed by execlineb in the previous "wrap-cowsay" example when given the same arguments.

See also

execline scripts can be found in the following repositories:

• Spectrum
• Finix