---
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
+
+
+ - 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 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:
+
+
+
+ - An 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.
+
+
+
+
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
- - The current released version of execline is 2.9.0.2.
+ - The current released version of execline is 2.9.1.0.
- Alternatively, you can checkout a copy of the
execline
git repository:
@@ -194,6 +194,7 @@ the previous versions of execline and the current one.
(Miscellaneous)