Tests and docs

1 files changed, 52 insertions, 7 deletions

diff --git a/doc/expr.n b/doc/expr.n
index 0210348..a7939f8 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -97,7 +97,7 @@ and the value of \fBb\fR is 6.  The command on the left side of each line
 produces the value on the right side.
 .PP
 .CS
-.ta 6c
+.ta 8c
 \fBexpr\fR 3.1 + $a	\fI6.1\fR
 \fBexpr\fR 2 + "$a.$b"	\fI5.6\fR
 \fBexpr\fR 4*[llength "6 2"]	\fI8\fR
@@ -159,7 +159,18 @@ A right shift always propagates the sign bit.
 .TP 20
 \fB<\0\0>\0\0<=\0\0>=\fR
 .
-Boolean less than, greater than, less than or equal, and greater than or equal.
+Boolean numeric-preferring comparisons: less than, greater than, less than or
+equal, and greater than or equal. If either argument is not numeric, the
+comparison is done using UNICODE string comparison, as with the string
+comparison operators below, which have the same precedence.
+.TP 20
+\fBlt\0\0gt\0\0le\0\0ge\fR
+.VS "8.7, TIP461"
+Boolean string comparisons: less than, greater than, less than or equal, and
+greater than or equal. These always compare values using their UNICODE strings
+(also see \fBstring compare\fR), unlike with the numeric-preferring
+comparisons abov, which have the same precedence.
+.VE "8.7, TIP461"
 .TP 20
 \fB==\0\0!=\fR
 .
@@ -190,16 +201,20 @@ Bit-wise OR.  Valid for integer operands.
 \fB&&\fR
 .
 Logical AND.  If both operands are true, the result is 1, or 0 otherwise.
-
+This operator evaluates lazily; it only evaluates its right-hand side if it
+must in order to determine its result.
 .TP 20
 \fB||\fR
 .
 Logical OR.  If both operands are false, the result is 0, or 1 otherwise.
+This operator evaluates lazily; it only evaluates its right-hand side if it
+must in order to determine its result.
 .TP 20
-\fIx\fB?\fIy\fB:\fIz\fR
+\fIx \fB?\fI y \fB:\fI z\fR
 .
 If-then-else, as in C.  If \fIx\fR is false , the result is the value of
 \fIy\fR.  Otherwise the result is the value of \fIz\fR.
+This operator evaluates lazily; it only evaluates one of \fIy\fR or \fIz\fR.
 .PP
 The exponentiation operator promotes types in the same way that the multiply
 and divide operators do, and the result is is the same as the result of
@@ -339,37 +354,67 @@ substitution on the value before \fBexpr\fR is called.
 In the following example, the value of the expression is 11 because the Tcl parser first
 substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR.  Enclosing the
 expression in braces would result in a syntax error.
+.PP
 .CS
 set a 3
 set b {$a + 2}
 \fBexpr\fR $b*4
 .CE
 .PP
-
-When an expression is generated at runtime, like the one above is, the bytcode
+When an expression is generated at runtime, like the one above is, the bytecode
 compiler must ensure that new code is generated each time the expression
 is evaluated.  This is the most costly kind of expression from a performance
 perspective.  In such cases, consider directly using the commands described in
 the \fBmathfunc\fR(n) or \fBmathop\fR(n) documentation instead of \fBexpr\fR.
-
+.PP
 Most expressions are not formed at runtime, but are literal strings or contain
 substitutions that don't introduce other substitutions.  To allow the bytecode
 compiler to work with an expression as a string literal at compilation time,
 ensure that it contains no substitutions or that it is enclosed in braces or
 otherwise quoted to prevent Tcl from performing substitutions, allowing
 \fBexpr\fR to perform them instead.
+.PP
+If it is necessary to include a non-constant expression string within the
+wider context of an otherwise-constant expression, the most efficient
+technique is to put the varying part inside a recursive \fBexpr\fR, as this at
+least allows for the compilation of the outer part, though it does mean that
+the varying part must itself be evaluated as a separate expression. Thus, in
+this example the result is 20 and the outer expression benefits from fully
+cached bytecode compilation.
+.PP
+.CS
+set a 3
+set b {$a + 2}
+\fBexpr\fR {[\fBexpr\fR $b] * 4}
+.CE
+.PP
+In general, you should enclose your expression in braces wherever possible,
+and where not possible, the argument to \fBexpr\fR should be an expression
+defined elsewhere as simply as possible. It is usually more efficient and
+safer to use other techniques (e.g., the commands in the \fBtcl::mathop\fR
+namespace) than it is to do complex expression generation.
 .SH EXAMPLES
 .PP
 A numeric comparison whose result is 1:
+.PP
 .CS
 \fBexpr\fR {"0x03" > "2"}
 .CE
 .PP
 A string comparison whose result is 1:
+.PP
 .CS
 \fBexpr\fR {"0y" > "0x12"}
 .CE
 .PP
+.VS "8.7, TIP461"
+A forced string comparison whose result is 0:
+.PP
+.CS
+\fBexpr\fR {"0x03" gt "2"}
+.CE
+.VE "8.7, TIP461"
+.PP
 Define a procedure that computes an
 .QW interesting
 mathematical function: