[src/trunk]: src/bin/test I have seen (way too often) uses of test(1) that ar...

[kre <kre%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/55490a39c52d
branches:  trunk
changeset: 827171:55490a39c52d
user:      kre <kre%NetBSD.org@localhost>
date:      Wed Oct 18 08:54:59 2017 +0000

description:
I have seen (way too often) uses of test(1) that are not defined to
actually work (but just happen to, today, and in some cases, even
that trusts to some luck.)

It has been recently pointed out to me that the man page (ie: this
file) doesn't give any real guidance to what is really acceptable,
and what is not.

The CAVEATS section does note that the grammar is ambiguous, but then
just says that test(1) implements what POSIX requires, and refers
readers to the relevant section of the POSIX standard for more details.
That is probably asking too much of the average reader...

So, add some extra information in the CAVEATS with what is defined to work,
and what should be avoided.   Not all of the POSIX rules are here, but this
might hopefully help script authors avoid some of the pitfalls.

diffstat:

 bin/test/test.1 |  58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 56 insertions(+), 2 deletions(-)

diffs (76 lines):

diff -r 384b32970466 -r 55490a39c52d bin/test/test.1
--- a/bin/test/test.1   Wed Oct 18 08:38:35 2017 +0000
+++ b/bin/test/test.1   Wed Oct 18 08:54:59 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: test.1,v 1.31 2017/07/03 21:33:24 wiz Exp $
+.\"    $NetBSD: test.1,v 1.32 2017/10/18 08:54:59 kre Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -32,7 +32,7 @@
 .\"
 .\"     @(#)test.1     8.1 (Berkeley) 5/31/93
 .\"
-.Dd August 12, 2016
+.Dd October 17, 2017
 .Dt TEST 1
 .Os
 .Sh NAME
@@ -328,3 +328,57 @@
 are evaluated consistently according to the rules specified in the
 standards document.
 All other cases are subject to the ambiguity in the command semantics.
+.Pp
+This means that
+.Nm
+should not be used with more than 4 operands
+(where the terminating
+.Cm \&]
+in the case of the
+.Nm \&[
+command does not count as an operand,)
+and that the obsolete
+.Fl a
+and
+.Fl o
+options should not be used.
+Instead invoke
+.Nm
+multiple times connected by the
+.Dq &&
+and
+.Dq ||
+operators from
+.Xr sh 1 .
+When those operators are not used, there is no need
+for the parentheses as grouping symbols, so those should also be
+avoided.
+Using
+.Xr sh 1 Ns 's
+.Cm \&!
+command instead of the equivalent operator from
+.Nm
+can also protect the script from future test enhancements.
+.Pp
+Most expressions with 3 or less operands will evaluate as expected,
+though be aware that with 3 operands,
+if the second is a known binary operator,
+that is always evaluated,
+regardless of what the other operands might suggest had been intended.
+If, and only if, the middle operand is not a defined binary operator
+is the first operand examined to see if it is
+.Cm \&!
+in which case the remaining operands are evaluated as a two operand test,
+and the result inverted.
+The only other defined three operand case is the meaningless
+degenerate case where parentheses (1st and 3rd operands)
+surround a one operand expression.
+.Pp
+With 4 operands there are just two defined cases, the first
+where the first operand is
+.Cm \&!
+in which case the result of the three operand test on the
+remaining operands is inverted,
+and the second is similar to the 3 operand case,
+the degenerate case of parentheses surrounding an (in this case)
+2 operand test expression.