1 05/22/81 -- Lisp Backquote ` Facility for Template-building
2
3 ** This documentation is not intended to be used with the help **
4 ** command. It is intended to be printed, dprinted, or read with**
5 ** an editor. **
6
7
8 ^L
9
10 The backquote facility defines two reader macro characters, backquote
11 "`" ASCII code 140 and comma "" ASCII code 54. These two macro
12 characters can be used together to abbreviate large compositions of
13 functions like cons, list, list* and append. It is typically used
14 to specify templates for building code or other list structure,
15 and often finds application in the construction of Lisp macros.
16
17 To use the backquote facility, the form "%include backquote"
18 should appear in your source before the first use of backquote.
19
20 Backquote has a syntax similar to that of quote "'" ascii 47. A
21 backquote is followed by a single form. If the form does not contain
22 any use of the comma macro character, then the form will simply be
23 quoted. For example:
24
25 `a b c = quote a b c = 'a b c
26
27 The comma macro character may only be used within a form following a
28 backquote. Comma also has a syntax like that of quote. The comma is
29 followed by a form, and that form is evaluated even though it is
30 inside the backquote. For example:
31
32 `a b c = cons a quote b c
33 = cons a 'b c
34
35 `a b c = list* quote a b quote c
36 = list* 'a b 'c
37
38 `a b c = list quote a quote b c
39 = list 'a 'b c
40
41 `a . rest = cons quote a rest
42 = cons 'a rest
43
44 Thus, if one wished to write the common macro "push" using backquote,
45 he or she could proceed from the standard definition
46
47 defun push macro form
48 list 'setq caddr form list 'cons cadr formcaddr form
49
50 to
51
52 defun push macro form
53 `setq caddr form cons cadr form caddr form
54
55 Note how the code to build the macro's output code begins to look
56 more like the output code itself. In fact, with a use of "let",
57 we can go all the way to
58
59 defun push macro form
60 let datum cadr form
61 list caddr form
62 `setq list cons datum list
63
64 and produce very legible code.
65
66 Backquote expands into forms that call cons, list, list* or whatever
67 other functions it deems appropriate for the task of constructing a
68 form that looks like the one following the backquote, but with the
69 values of the forms following the commas substituted in.
70
71 Since backquote's contract is specified not in terms of the code
72 that it expands into, but rather in terms of what that code produces
73 when evaluated, the user should not assume that he or she knows
74 anything about what that code might look like. The examples in this
75 document only reflect the way that backquote expands at the time of
76 writing, it is not guaranteed that this is the way they will expand
77 in the future.
78
79 If a comma inside a backquote form is followed by an "at" sign "@"
80 ASCII code 100, then the form following the ",@" should return a
81 list. Backquote arranges that the elements of that list will be
82 substituted into the resulting list structure. Frequently this
83 involves generating a call to the function append. For example,
84
85 `@a b c = append a quote b c
86 = append a 'b c
87
88 `a @b c = cons quote a append b quote c
89 = cons 'a append b 'c
90
91 `a b @c = list* quote a quote b c
92 = list* 'a 'b c
93
94 Similar to following the comma by an atsign is following the comma by
95 a dot "." ASCII code 56. The dot is a declaration to backquote
96 telling it that the list returned by the form following the ",." is
97 expendable. This allows backquote to produce code that calls
98 functions like nconc that rplac the list.
99
100 Backquote examines the forms following the commas to see if it can
101 simplify the resulting code. For example,
102
103 `a b . cons x y = list* quote a quote b x y
104 = list* 'a 'b x y
105
106 `a 3 b c 17 = list* quote a 3 b quote c 17
107 = list* 'a 3 b 'c 17
108
109 `a @b @nil = cons quote a b
110 = cons 'a b
111
112 `a .b @nconc c d = cons quote a nconc b c d
113 = cons 'a nconc b c d
114
115 These examples should convince the user that he or she really cannot
116 depend on what the code that backquote expands into will look like.
117 A simple minded backquote might expand "@a @nil" into "append a
118 'nil", but this cannot be used as a reliable way to copy a list
119 since a sophisticated backquote like this one can optimize the
120 copying away.
121
122 It is sometimes useful to nest one use of backquote within another.
123 This might happen when the user is writing some code that will cons up
124 some more code that will in turn cons up yet more code. The usual
125 example is in writing macro defining macros. When this becomes
126 necessary it is sometimes difficult to determine exactly how to use
127 comma to cause evaluation to happen at the correct times. The
128 following example exhibits all the useful combinations:
129
130 ``a b c 'd
131 = list 'list* ''a 'b c list 'quote list d
132
133 When evaluated once this yields:
134
135 list* 'a b <c-at-time-1> '<d-at-time-1>
136
137 Which when evaluated yields:
138
139 a <b-at-time-2> <<c-at-time-1>-at-time-2> <d-at-time-1>
140
141 Thus "" means never evaluate, "," means evaluate only the second time,
142 ",," means evaluate both times, and ",'," means evaluate only the
143 first time.