awk macro: support regexes better in ranges.

* share/txr/stdlib/awk.tl (sys:awk-compile-time): New slot,
rng-rec-temp. Specifies the name of a temporary variable
which is scoped over the evaluation of ranges, and which
caches a reference to the current record string.
(sys:range-test): New function.
(awk:let): Rename the original rng macrolet to sys:rng,
and introduce rng as a wrapper around it which inserts
the logic for calling the regex or function that might
emerge from the evaluation of from-expr or to-expr.
(awk): If ranges are present in the syntax, then bind
the temporary variable which caches the record around
the evaluations of the ranges.

* txr.1: Document new special behavior of rng w.r.t
functions and regexes. Add admonition against modifying
rec and some other awk variables from range expressions.

1 files changed, 29 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index 58506358..a47e776f 100644
--- a/txr.1
+++ b/txr.1
@@ -38771,7 +38771,25 @@ The expressions
 .meta from-condition
 and
 .meta to-condition
-are ordinary expressions which are evaluated; however, the are evaluated
+are ordinary expressions which are evaluated. However, their
+evaluation is unusual in two ways.
+
+Firstly, if either expression
+produces, as its result, a function or regular expression object,
+then that function or regular expression object is applied to
+the current record (value of the
+.code rec
+variable), and the result of that application is then taken
+as the result of the condition. This allows for expressions like
+.code "(rng (f^ #/start/) #/end/)"
+which denotes a range which begins with a record which
+begins with the prefix
+.str start
+and ends with a record which contains
+.str end
+as a substring.
+
+Secondly, the conditions are evaluated
 out of order with respect to the surrounding expression
 in which they occur.  Ranges and their constituent
 .meta from-condition
@@ -38813,6 +38831,16 @@ itself is evaluated, the
 expression merely fetches a previously computed Boolean value which indicates
 whether the range is active for this record.
 
+Also, the behavior is unspecified if range expressions attempt to modify
+the awk-special variables.
+.codn rec ,
+.codn f ,
+.codn fs ,
+.code ft
+or
+.codn kfs .
+It is not recommended to place any side effects into range expressions.
+
 Evaluation of ranges obeys the following logic, which is applied to
 each range, prior to the processing of condition-action clauses.
 If a range is not currently active, its