From 92f1e3fed2902774cbed773352a7f609a8b1b1de Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 1 Aug 2007 21:45:14 +0000
Subject: [PATCH] quasiquote in new reference

svn: r6995
---
 .../scribblings/reference/contracts.scrbl     |  2 +-
 collects/scribblings/reference/syntax.scrbl   | 66 +++++++++++++++++++
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/collects/scribblings/reference/contracts.scrbl b/collects/scribblings/reference/contracts.scrbl
index 535d1aa126..ffb8c32697 100644
--- a/collects/scribblings/reference/contracts.scrbl
+++ b/collects/scribblings/reference/contracts.scrbl
@@ -123,7 +123,7 @@ Returns a flat contract that requires the input to be a real number
 between @scheme[n] and @scheme[m], inclusive.}
 
 
-@defproc[(integer-in [j exact-integer?][k exact-integer?]) flat-contract?]
+@defproc[(integer-in [j exact-integer?][k exact-integer?]) flat-contract?]{
 
 Returns a flat contract that requires the input to be an exact integer
 between @scheme[j] and @scheme[k], inclusive.}
diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl
index c509cd74fa..f41e11a347 100644
--- a/collects/scribblings/reference/syntax.scrbl
+++ b/collects/scribblings/reference/syntax.scrbl
@@ -897,6 +897,72 @@ expression).
 
 @moreref["mz:contmarks"]{continuation marks}}
 
+@;------------------------------------------------------------------------
+@section[#:tag "mz:quasiquote"]{Quasiquoting: @scheme[quasiquote], @scheme[unquote], and @scheme[unquote-splicing]}
+
+@defform[(quasiquote datum)]{
+
+The same as @scheme[(quote datum)] if @scheme[datum] does not include
+@scheme[(unquote _expr)] or @scheme[(unquote-splicing _expr)]. An
+@scheme[(unquote _expr)] expression escapes from the quote, however,
+and the result of the @scheme[_expr] takes the place of the
+@scheme[(unquote _expr)] form in the @scheme[quasiquote] result. An
+@scheme[(unquote-splicing _expr)] similarly escapes, but the
+@scheme[_expr] must produce a list, and its elements are spliced as
+multiple values place of the @scheme[(unquote-splicing _expr)], which
+must appear as the @scheme[car] or a quoted pair.
+
+@examples[
+(eval:alts (#,(scheme quasiquote) (0 1 2)) `(0 1 2))
+(eval:alts (#,(scheme quasiquote) (0 (#,(scheme unquote) (+ 1 2)) 4)) `(1 ,(+ 1 2) 4))
+(eval:alts (#,(scheme quasiquote) (0 (#,(scheme unquote-splicing) (list 1 2)) 4)) `(1 ,@(list 1 2) 4))
+]
+
+A @scheme[quasiquote], @scheme[unquote], or @scheme[unquote-splicing]
+form is typically abbreviated with @litchar{`}, @litchar{,}, or
+@litchar[",@"], respectively. See also @secref["mz:parse-quote"].
+
+@examples[
+`(0 1 2)
+`(1 ,(+ 1 2) 4)
+`(1 ,@(list 1 2) 4)
+]
+
+A @scheme[quasiquote] form within the original @scheme[datum]
+increments the level of quasiquotation: within the @scheme[quasiquote]
+form, each @scheme[unquote] or @scheme[unquote-splicing] is preserved,
+but a further nested @scheme[unquote] or @scheme[unquote-splicing]
+escapes.  Multiple nestings of @scheme[quasiquote] require multiple
+nestings of @scheme[unquote] or @scheme[unquote-splicing] to escape.
+
+@examples[
+`(1 `,(+ 1 ,(+ 2 3)) 4)
+`(1 ```,,@,,@(list (+ 1 2)) 4)
+]
+
+The @scheme[quasiquote] form allocates only as many fresh cons cells,
+vectors, and boxes as are needed without analyzing @scheme[unquote]
+and @scheme[unquote-splicing] expressions. For example, in
+
+@schemeblock[
+`(,1 2 3)
+]
+
+a single tail @scheme['(2 3)] is used for every evaluation of the
+@scheme[quasiquote] expression.
+
+}
+
+@defidform[unquote]{
+
+See @scheme[quasiquote], where @scheme[unquote] is recognized as an
+escape. An @scheme[unquote] form as an expression is a syntax error.}
+
+@defidform[unquote-splicing]{
+
+See @scheme[quasiquote], where @scheme[unquote-splicing] is recognized as an
+escape. An @scheme[unquote-splicing] form as an expression is a syntax error.}
+
 @;------------------------------------------------------------------------
 @section{Syntax Quoting: @scheme[quote-syntax]}