summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPádraig Brady <P@draigBrady.com>2015-12-21 17:57:30 +0000
committerPádraig Brady <P@draigBrady.com>2015-12-22 16:54:18 +0000
commit3205bb178c9228b7002ebcb59b01cf52a95d6ca4 (patch)
tree087fdefd2763b7dc38ec48ee1887ca7359b5898b
parentf8a9c8c343b073f92d9cf149fbf6c1d0e425bfb3 (diff)
downloadcoreutils-3205bb178c9228b7002ebcb59b01cf52a95d6ca4.tar.xz
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
-rw-r--r--cfg.mk1
-rw-r--r--doc/coreutils.texi32
2 files changed, 32 insertions, 1 deletions
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