From 3205bb178c9228b7002ebcb59b01cf52a95d6ca4 Mon Sep 17 00:00:00 2001 From: Pádraig Brady
Date: Mon, 21 Dec 2015 17:57:30 +0000 Subject: doc: describe test operator precedence and associativity * doc/coreutils.texi (Connectives for test): Add notes on precedence and associativity. Also mention the portability caveats with these operators. * cfg.mk: Avoid sc_prohibit_test_minus_ao for coreutils.texi. Fixes http://bugs.gnu.org/22216 --- cfg.mk | 1 + doc/coreutils.texi | 32 +++++++++++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/cfg.mk b/cfg.mk index 23f166189..69ffc44c9 100644 --- a/cfg.mk +++ b/cfg.mk @@ -799,6 +799,7 @@ exclude_file_name_regexp--sc_prohibit_always_true_header_tests = \ ^m4/stat-prog\.m4$$ exclude_file_name_regexp--sc_prohibit_fail_0 = \ (^.*/git-hooks/commit-msg|^tests/init\.sh|Makefile\.am|\.mk|.*\.texi)$$ +exclude_file_name_regexp--sc_prohibit_test_minus_ao = *\.texi$$ exclude_file_name_regexp--sc_prohibit_atoi_atof = ^lib/euidaccess-stat\.c$$ # longlong.h is maintained elsewhere. diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 33be4d8ac..64419c769 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -12638,25 +12638,55 @@ test 0x100 -eq 1 @cindex logical connectives @cindex connectives, logical -The usual logical connectives. +Note it's preferred to use shell logical primitives +rather than these logical connectives internal to @command{test}, +because an expression may become ambiguous +depending on the expansion of its parameters. + +For example, this becomes ambiguous when @samp{$1} +is set to @samp{'!'} and @samp{$2} to the empty string @samp{''}: + +@example +test "$1" -a "$2" +@end example + +and should be written as: + +@example +test "$1" && test "$2" +@end example + +Note the shell logical primitives also benefit from +short circuit operation, which can be significant +for file attribute tests. @table @samp @item ! @var{expr} @opindex ! True if @var{expr} is false. +@samp{!} has lower precedence than all parts of @var{expr}. +Note @samp{!} needs to be specified to the left +of a binary expression, I.e., @samp{'!' 1 -gt 2} +rather than @samp{1 '!' -gt 2}. +Also @samp{!} is often a shell special character +and is best used quoted. + @item @var{expr1} -a @var{expr2} @opindex -a @cindex logical and operator @cindex and operator True if both @var{expr1} and @var{expr2} are true. +@samp{-a} is left associative, +and has a higher precedence than @samp{-o}. @item @var{expr1} -o @var{expr2} @opindex -o @cindex logical or operator @cindex or operator True if either @var{expr1} or @var{expr2} is true. +@samp{-o} is left associative. @end table -- cgit v1.2.3-70-g09d2