execline: the eltest program
Keywords: execline command eltest test

execline
Software
skarnet.org

# The `eltest` program

eltest evaluates an expression and indicates the result via its exit status.

## Interface

         eltest expression...

`eltest` acts as the generic POSIX test utility, but it diverges from the specification on how it parses ambiguous arguments, see below.

`eltest` supports all the standard test operands, plus all the extensions from GNU test, plus a few extensions from the `test` builtin from bash. The extensions to POSIX `test` are listed below.

`eltest` accepts an arbitrary number of arguments and, if the expression is valid, always returns the result of the expression no matter how complex it is.

## Exit codes

- 0: the test is true
- 1: the test is false
- 100: wrong usage
- 101: internal error (should never happen, warrants a bug-report)
- 111: system call failure

## Posixness

`eltest` is not suitable as a Single Unix test program, due to the way it disambiguates between arguments and operators, see below. However, if you never use arguments that start with a backslash, or that have the same name as an existing operator, then `eltest` exhibits the same behaviour as `test`.

## Extensions to POSIX

- `expr1 -a expr2` : tests whether expr1 and expr2 are true. If expr1 is false, then expr2 is not evaluated.
- `expr1 -o expr2` : tests whether expr1 or expr2 is true. If expr1 is true, then expr2 is not evaluated.
- `-k file` : tests whether file has the sticky bit.
- `-O file` : tests whether file is owned by the effective uid of the current process.
- `-U file` : same.
- `-G file` : tests whether file's gid is the effective gid of the current process.
- `-N file` : tests whether file exists and has been modified since it was last read.
- `file1 -nt file2` : tests whether file1 has a (strictly) newer modification date than file2.
- `file1 -ot file2` : tests whether file1 has a (strictly) older modification date than file2.
- `file1 -ef file2` : tests whether file1 and file2 are physically the same file (same device and inode numbers).
- `-v var` : tests whether the var variable is defined in the current environment.
- `string =~ pattern` : tries to match string against extended regular expression pattern. True if any part of string matches pattern; in order to match whole strings, you must anchor pattern with `^` and `$` markers.

## Argument disambiguation

Unlike test, which has different fixed syntax trees depending on the number of arguments it receives and has undefined behaviour when called with more than 5 arguments, `eltest` accepts any number of arguments and builds its syntax trees on the fly. This means that expressions such as `-n = -n` cannot be automatically disambiguated: `eltest` does not know that there are 3 arguments, so when it reads the first `-n` it assumes that it is a unary operator, then when it reads `=` it assumes it is the argument to `-n`, then when it reads the second `-n` it exits with a syntax error.

Doing otherwise would result in a combinatory explosion of possible syntax trees, making it easy for users to trigger unbounded RAM consumption, and turning a simple utility into a programming nightmare. This is why POSIX test is so restricted. But we don't want the same restrictions.

So, instead, `eltest` provides the user with a mechanism to make sure that operands are never mistaken for operators:

- A word that looks like an operator will always be interpreted like an operator. So, expressions like `-n = -n` will result in a syntax error, because the first `-n` will never be understood as data for the `=` operator.
- A word that starts with a `\` (backslash) will always be interpreted like data, never like an operator, and the backslash will be removed. This means: `\-n = \-n` is a valid expression testing the equality between the strings `-n` and -n.
  - Be aware that execline as well as the shell use one backlash for their own unquoting mechanism, so when using backslashes in an execline or shell script, they must be doubled. You would probably need to type something like `\\-n = \\-n`.
- So, if your script tests equality between `$a` and `$b`, and there's a possiblity that the contents of these variables look like `eltest` operators, the proper syntax would be: `eltest \\${a} = \\${b}`.

Note that these details are irrelevant to a huge majority of `eltest` use cases, because most of the time users only need a simple test such as `eltest -r ${file}` to check that `$file` is readable, and there's no possible ambiguity. So, don't panic over this.

## Notes

- `eltest` is a replacement for the ill-named, and now deprecated, s6-test program, part of the (just as ill-named) s6-portable-utils package. It is too valuable a utility to be part of a marginal package, and has nothing to do with s6.