commit d6d4cc2361943c0755d54697daa53a12ef866e63
parent 3c963cfff7918a76646ef442272c928210844b64
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Thu, 1 Feb 2024 15:13:38 -0500
Quasiquotation: Texify & tidy examples.
Diffstat:
1 file changed, 51 insertions(+), 34 deletions(-)
diff --git a/doc/r7rs-small/derived/quasiquotation.texinfo b/doc/r7rs-small/derived/quasiquotation.texinfo
@@ -1,42 +1,52 @@
@node Quasiquotation
@subsection Quasiquotation
-syntax: (quasiquote @svar{qq template})
-syntax: `@svar{qq template}
-auxiliary syntax: unquote
-auxiliary syntax: ,
-auxiliary syntax: unquote-splicing
-auxiliary syntax: ,﹫
-
-``Quasiquote''expressions are useful for constructing a list or vector structure when some
-but not all of the desired structure is known in advance. If no commasappear within the
-@svar{qq template}, the result of evaluating `@svar{qq template} is equivalent to the result of
-evaluating '@svar{qq template}. If a commaappears within the @svar{qq template}, however, the
-expression following the comma is evaluated (``unquoted'') and its result is inserted into
-the structure instead of the comma and the expression. If a comma appears followed
-without intervening whitespace by a commercial at-sign (﹫),then it is an error if the
-following expression does not evaluate to a list; the opening and closing parentheses of
-the list are then ``stripped away'' and the elements of the list are inserted in place of the
-comma at-sign expression sequence. A comma at-sign normally appears only within a list
-or vector @svar{qq template}.
+@c FIXME: deffn doesn't handle the ` line correctly.
+@deffn syntax quasiquote @svar{qq template}
+@deffnx syntax `@svar{qq template}
+@deffnx {auxiliary syntax} unquote
+@deffnx {auxiliary syntax} @comma{}
+@deffnx {auxiliary syntax} unquote-splicing
+@deffnx {auxiliary syntax} @comma{}@@
+
+``Quasiquote'' expressions are useful
+for constructing a list or vector structure when some but not all of the
+desired structure is known in advance. If no
+commas appear within the @svar{qq template}, the result of
+evaluating
+@code{`}@svar{qq template} is equivalent to the result of evaluating
+@code{'}@svar{qq template}. If a comma appears within the
+@svar{qq template}, however, the expression following the comma is
+evaluated (``unquoted'') and its result is inserted into the structure
+instead of the comma and the expression. If a comma appears followed
+without intervening whitespace by a commercial at-sign (@@), then it is an error if the following
+expression does not evaluate to a list; the opening and closing parentheses
+of the list are then ``stripped away'' and the elements of the list are
+inserted in place of the comma at-sign expression sequence. A comma
+at-sign normally appears only within a list or vector @svar{qq template}.
Note: In order to unquote an identifier beginning with @code{,} it is necessary to use either
an explicit unquote or to put whitespace after the comma, to avoid colliding with the
comma at-sign sequence.
@example
-`(list ,(+ 1 2) 4) @result{} (list 3 4)
+`(list ,(+ 1 2) 4) @result{} (list 3 4)
+
(let ((name 'a)) `(list ,name ',name))
-@result{} (list a (quote a))
+ @result{} (list a (quote a))
+
`(a ,(+ 1 2) ,@@(map abs '(4 -5 6)) b)
-@result{} (a 3 4 5 6 b)
+ @result{} (a 3 4 5 6 b)
+
`(( foo ,(- 10 3)) ,@@(cdr '(c)) . ,(car '(cons)))
-@result{} ((foo 7) . cons)
+ @result{} ((foo 7) . cons)
+
`#(10 5 ,(sqrt 4) ,@@(map sqrt '(16 9)) 8)
-@result{} #(10 5 2 4 3 8)
+ @result{} #(10 5 2 4 3 8)
+
(let ((foo '(foo bar)) (@@baz 'baz))
`(list ,@@foo , @@baz))
-@result{} (list foo bar baz)
+ @result{} (list foo bar baz)
@end example
Quasiquote expressions can be nested. Substitutions are made only
@@ -46,11 +56,12 @@ decreases by one inside each unquotation.
@example
`(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)
-@result{} (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
+ @result{} (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
+
(let ((name1 'x)
(name2 'y))
`(a `(b ,,name1 ,',name2 d) e))
-@result{} (a `(b ,x ,'y d) e)
+ @result{} (a `(b ,x ,'y d) e)
@end example
A quasiquote expression may return either newly allocated, mutable
@@ -73,18 +84,24 @@ However, it is not equivalent to this expression:
(let ((a 3)) (list (list 1 2) a 4 'five 6))
@end example
-The two notations `@svar{qq template} and (quasiquote <qq
-template>) are identical in all respects. ,@svar{expression} is identical to (unquote
-@svar{expression}), and ,@@@svar{expression} is identical to (unquote-splicing @svar{expression}). The
+The two notations @code{`}@svar{qq template} and
+@code{(quasiquote }@svar{qq template}@code{)}
+are identical in all respects. @code{,}@svar{expression} is identical to
+@code{(unquote }@svar{expression}@code{)}, and @code{,@@}@svar{expression}
+is identical to @code{(unquote-splicing }@svar{expression}@code{)}. The
write procedure may output either format.
@example
(quasiquote (list (unquote (+ 1 2)) 4))
-@result{} (list 3 4)
+ @result{} (list 3 4)
+
'(quasiquote (list (unquote (+ 1 2)) 4))
-@result{} `(list ,(+ 1 2) 4)
- i.e., (quasiquote (list (unquote (+ 1 2)) 4))
+ @result{} `(list ,(+ 1 2) 4)
+ @r{i.e.}, (quasiquote (list (unquote (+ 1 2)) 4))
@end example
-It is an error if any of the identifiers quasiquote, unquote, or unquote-splicing appear in
-positions within a @svar{qq template} otherwise than as described above.
+It is an error if any of the identifiers @code{quasiquote}, @code{unquote},
+or @code{unquote-splicing} appear in positions within a @svar{qq template}
+otherwise than as described above.
+
+@end deffn
