summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKaz Kylheku <kaz@kylheku.com>2021-02-09 18:06:39 -0800
committerKaz Kylheku <kaz@kylheku.com>2021-02-09 18:06:39 -0800
commit39b06f31618dd82637dc7385fc335cf457b35d3a (patch)
treea64956554ddf7b1dcc89494bde90b588841dc826
parenta52a10871b45806db86476fc17092368bcc5b1c3 (diff)
downloadtxr-39b06f31618dd82637dc7385fc335cf457b35d3a.tar.gz
txr-39b06f31618dd82637dc7385fc335cf457b35d3a.tar.bz2
txr-39b06f31618dd82637dc7385fc335cf457b35d3a.zip
doc: fixes in pattern matching introduction.
* txr.1: Improving text about variables. Removing obsolete reference to parallel scoping behavior of @(and) and mentioning that @(as) binds fresh variables, which could cause multiple occurrences of a variable in the same patter not to refer to the same variable.
-rw-r--r--txr.132
1 files changed, 17 insertions, 15 deletions
diff --git a/txr.1 b/txr.1
index 4b14fca9..7b2717c4 100644
--- a/txr.1
+++ b/txr.1
@@ -39806,19 +39806,19 @@ a match for a variable, which is then back-referenced in another
sub-pattern.
A pattern can contain multiple occurrences of the same variable.
-Except in the case when these variables occur in different branches
-of an
+Except in the case when these variables occur in different
+branches of an
.code @(or)
-or
-.code @(and)
-pattern operator, those repeated variables denote one variable.
-The left-most, or in the case of
+pattern operator, or a fresh binding under the
.code @(as)
-nesting, outermost, occurrence of the variable binds to the corresponding
-element of the object. The remaining occurrences of the variable must
-correspond to objects which are
+operator those repeated variables refer to one variable.
+If the variable does not exist in the scope surrounding the pattern,
+then the leftmost occurrence of the variable establishes a binding,
+taking the value from is corresponding object being matched by that
+occurrence of the variable. The remaining
+occurrences of the variable must correspond to objects which are
.code equal
-to that object, or else there is no match.
+to that value, or else there is no match.
For instance, the pattern
.code "(@a @a)"
matches a list like
@@ -39832,12 +39832,14 @@ Pattern variables exist in the same namespace as Lisp variables,
and are fully integrated in it. Patterns not only bind variables,
but have visibility to existing variables in scope, including
lexical variables and special/global variables. When a variable
-is mentioned in a pattern, if it already has a binding as a Lisp variable, then
-it denotes a reference to that variable in exactly the same way that a pattern
-variable back-references itself in a pattern: the Lisp variable
-is require to compare
+is mentioned in a pattern, and is not freshly bound in that pattern
+using the
+.code as
+operator, if it already has a binding a variable outside the pattern, then
+it denotes a reference to that variable. That occurrence of the variable
+must match an object which compares equal
.code equal
-to the corresponding object being examined by the pattern. For instance,
+to the variable's existing value. For instance,
the following function returns the third element of a list, if the
first two elements are repetitions of the
.code x