On this page:
quasiquote
unquote
unquote-splicing

3.20 Quasiquoting: quasiquote, unquote, and unquote-splicing

+Quasiquoting: quasiquote and in The Racket Guide introduces quasiquote.

syntax

(quasiquote datum)

The same as 'datum if datum does not include (unquote expr) or (unquote-splicing expr). An (unquote expr) form escapes from the quote, however, and the result of the expr takes the place of the (unquote expr) form in the quasiquote result. An (unquote-splicing expr) similarly escapes, but the expr produces a list whose elements are spliced as multiple values place of the (unquote-splicing expr).

An unquote or unquote-splicing form is recognized in any of the following escaping positions within datum: in a pair, in a vector, in a box, in a prefab structure field after the name position, and in hash table value position (but not in a hash table key position). Such escaping positions can be nested to an arbitrary depth.

An unquote-splicing form must appear as the car of a quoted pair, as an element of a quoted vector, or as an element of a quoted prefab structure. In the case of a pair, if the cdr of the relevant quoted pair is empty, then expr need not produce a list, and its result is used directly in place of the quoted pair (in the same way that append accepts a non-list final argument).

If unquote or unquote-splicing appears within quasiquote in an escaping position but in a way other than as (unquote expr) or (unquote-splicing expr), a syntax error is reported.

Examples:
> (quasiquote (0 1 2))

'(0 1 2)

> (quasiquote (0 (unquote (+ 1 2)) 4))

'(0 3 4)

> (quasiquote (0 (unquote-splicing (list 1 2)) 4))

'(0 1 2 4)

> (quasiquote (0 (unquote-splicing 1) 4))

unquote-splicing: contract violation

  expected: list?

  given: 1

> (quasiquote (0 (unquote-splicing 1)))

'(0 . 1)

A quasiquote, unquote, or unquote-splicing form is typically abbreviated with `, ,, or ,@, respectively. See also Reading Quotes.

Examples:
> `(0 1 2)

'(0 1 2)

> `(1 ,(+ 1 2) 4)

'(1 3 4)

> `#s(stuff 1 ,(+ 1 2) 4)

'#s(stuff 1 3 4)

> `#hash(("a" . ,(+ 1 2)))

'#hash(("a" . 3))

> `#hash((,(+ 1 2) . "a"))

'#hash((,(+ 1 2) . "a"))

> `(1 ,@(list 1 2) 4)

'(1 1 2 4)

> `#(1 ,@(list 1 2) 4)

'#(1 1 2 4)

A quasiquote form within the original datum increments the level of quasiquotation: within the quasiquote form, each unquote or unquote-splicing is preserved, but a further nested unquote or unquote-splicing escapes. Multiple nestings of quasiquote require multiple nestings of unquote or unquote-splicing to escape.

Examples:
> `(1 `,(+ 1 ,(+ 2 3)) 4)

'(1 `,(+ 1 5) 4)

> `(1 ```,,@,,@(list (+ 1 2)) 4)

'(1 ```,,@,3 4)

The quasiquote form allocates only as many fresh cons cells, vectors, and boxes as are needed without analyzing unquote and unquote-splicing expressions. For example, in

`(,1 2 3)

a single tail '(2 3) is used for every evaluation of the quasiquote expression. When allocating fresh data, the quasiquote form allocates mutable vectors, mutable boxes and immutable hashes.

Examples:
> (immutable? `#(,0))

#f

> (immutable? `#hash((a . ,0)))

#t

syntax

unquote

See quasiquote, where unquote is recognized as an escape. An unquote form as an expression is a syntax error.

See quasiquote, where unquote-splicing is recognized as an escape. An unquote-splicing form as an expression is a syntax error.