From 43a1ac4f3514406da9ce2a8eb41cc178c7531eca Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 20 Dec 2022 09:46:56 +0000 Subject: Prepare for 2.9.1.0; add eltest Signed-off-by: Laurent Bercot --- doc/eltest.html | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.html | 3 +- doc/upgrade.html | 3 +- 3 files changed, 176 insertions(+), 2 deletions(-) create mode 100644 doc/eltest.html (limited to 'doc') diff --git a/doc/eltest.html b/doc/eltest.html new file mode 100644 index 0000000..068cd4c --- /dev/null +++ b/doc/eltest.html @@ -0,0 +1,172 @@ + + + + + + execline: the eltest program + + + + + + +

+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

+ + + +

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

+ + + +

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 an 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: +

+ + + +

+ 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

+ + + + + diff --git a/doc/index.html b/doc/index.html index f9c985a..5d2f402 100644 --- a/doc/index.html +++ b/doc/index.html @@ -77,7 +77,7 @@ want nsswitch-like functionality:

Download