macros.texinfo (15281B)
1 @node Macros 2 @section Macros 3 4 Scheme programs can define and use new derived expression types, called 5 @define{macros}. Program-defined expression types have the syntax 6 7 @display 8 @code{(}@svar{keyword} @svar{datum} @dots{}@code{)} 9 @end display 10 11 @cindex syntactic keyword 12 @cindex keyword 13 @cindex macro keyword 14 15 where @svar{keyword} is an identifier that uniquely determines the 16 expression type. This identifier is called the @define{syntactic keyword}, or 17 simply @define{keyword}, of the macro. The number of the @svar{datum}s, and 18 their syntax, depends on the expression type. 19 20 @cindex macro use 21 @cindex macro transformer 22 23 Each instance of a macro is called a @define{use} of the macro. The set of 24 rules that specifies how a use of a macro is transcribed into a more 25 primitive expression is called the @define{transformer} of the macro. 26 27 The macro definition facility consists of two parts: 28 29 @itemize 30 31 @item 32 A set of expressions used to establish that certain identifiers are macro 33 keywords, associate them with macro transformers, and control the scope 34 within which a macro is defined, and 35 36 @item 37 a pattern language for specifying macro transformers. 38 39 @end itemize 40 41 @cindex syntactic keyword 42 @cindex keyword 43 44 The syntactic keyword of a macro can shadow variable bindings, and local 45 variable bindings can shadow syntactic bindings. Two mechanisms are 46 provided to prevent unintended conflicts: 47 48 @itemize 49 50 @item 51 If a macro transformer inserts a binding for an identifier (variable or 52 keyword), the identifier will in effect be renamed throughout its scope to 53 avoid conflicts with other identifiers. Note that a global variable 54 definition may or may not introduce a binding; @xref{Variable 55 definitions}. 56 57 @item 58 If a macro transformer inserts a free reference to an identifier, the 59 reference refers to the binding that was visible where the transformer was 60 specified, regardless of any local bindings that surround the use of the 61 macro. 62 63 @end itemize 64 65 @cindex hygienic 66 @cindex referentially transparent 67 68 In consequence, all macros defined using the pattern language are 69 ``hygienic'' and ``referentially transparent'' and thus preserve Scheme's 70 lexical scoping. [@ref{Kohlbecker86}, @ref{hygienic}, @ref{Bawden88}, 71 @ref{macrosthatwork}, @ref{syntacticabstraction}] 72 73 Implementations may provide macro facilities of other types. 74 75 @menu 76 * Binding constructs for syntactic keywords:: 77 * Pattern language:: 78 * Signaling errors in macro transformers:: 79 @end menu 80 81 @node Binding constructs for syntactic keywords 82 @subsection Binding constructs for syntactic keywords 83 84 The @code{let-syntax} and @code{letrec-syntax} binding constructs are 85 analogous to @code{let} and @code{letrec}, but they bind syntactic 86 keywords to macro transformers instead of binding variables to locations 87 that contain values. Syntactic keywords can also be bound globally or 88 locally with @code{define-syntax}; @xref{Syntax definitions}. 89 90 @deffn syntax let-syntax @svar{bindings} @svar{body} 91 92 Syntax: @svar{Bindings} has the form 93 94 @display 95 @code{((}@svar{keyword} @svar{transformer spec}@code{)} @dots{}@code{)} 96 @end display 97 98 Each @svar{keyword} is an identifier, each @svar{transformer spec} 99 is an instance of @code{syntax-rules}, and @svar{body} is a sequence 100 of zero or more definitions followed by one or more expressions. It is 101 an error for a @svar{keyword} to appear more than once in the list of 102 keywords being bound. 103 104 Semantics: The @svar{body} is expanded in the syntactic environment 105 obtained by extending the syntactic environment of the @code{let-syntax} 106 expression with macros whose keywords are the @svar{keyword}s, bound 107 to the specified transformers. Each binding of a @svar{keyword} has 108 @svar{body} as its region. 109 110 @lisp 111 (let-syntax ((given-that (syntax-rules () 112 ((given-that test stmt1 stmt2 ...) 113 (if test 114 (begin stmt1 115 stmt2 ...)))))) 116 (let ((if #t)) 117 (given-that if (set! if 'now)) 118 if)) @result{} now 119 120 (let ((x 'outer)) 121 (let-syntax ((m (syntax-rules () ((m) x)))) 122 (let ((x 'inner)) 123 (m)))) @result{} outer 124 @end lisp 125 126 @end deffn 127 128 @deffn syntax letrec-syntax @svar{bindings} @svar{body} 129 130 Syntax: Same as for @code{let-syntax}. 131 132 Semantics: The @svar{body} is expanded in the syntactic 133 environment obtained by extending the syntactic environment of the 134 @code{letrec-syntax} expression with macros whose keywords are the 135 @svar{keyword}s, bound to the specified transformers. Each binding of a 136 @svar{keyword} has the @svar{transformer spec}s as well as the @svar{body} 137 within its region, so the transformers can transcribe expressions into 138 uses of the macros introduced by the @code{letrec-syntax} expression. 139 140 @lisp 141 (letrec-syntax 142 ((my-or (syntax-rules () 143 ((my-or) #f) 144 ((my-or e) e) 145 ((my-or e1 e2 ...) 146 (let ((temp e1)) 147 (if temp 148 temp 149 (my-or e2 ...))))))) 150 (let ((x #f) 151 (y 7) 152 (temp 8) 153 (let odd?) 154 (if even?)) 155 (my-or x 156 (let temp) 157 (if y) 158 y))) @result{} 7 159 @end lisp 160 161 @end deffn 162 163 @node Pattern language 164 @subsection Pattern language 165 166 @deffn syntax syntax-rules 167 @deffnx {auxiliary syntax} _ 168 @deffnx {auxiliary syntax} @dots{} 169 170 A @svar{transformer spec} has one of the following forms: 171 172 @display 173 @code{(syntax-rules (}@svar{pattern literal} @dots{}@code{)} 174 @svar{syntax rule} @dots{}@code{)} 175 @code{(syntax-rules }@svar{ellipsis} @code{(}@svar{pattern literal} @dots{}@code{)} 176 @svar{syntax rule} @dots{}@code{)} 177 @end display 178 179 Syntax: It is an error if any of the @svar{pattern literal}s, or the 180 @svar{ellipsis} in the second form, is not an identifier. It is also an 181 error if @svar{syntax rule} is not of the form 182 183 @display 184 (@svar{pattern} @svar{template}) 185 @end display 186 187 The @svar{pattern} in a @svar{syntax rule} is a list @svar{pattern} whose 188 first element is an identifier. 189 190 A @svar{pattern} is either an identifier, a constant, or one of the following 191 192 @display 193 @code{(}@svar{pattern} @dots{}@code{)} 194 @code{(}@svar{pattern} @svar{pattern} @dots{} @code{.} @svar{pattern}@code{)} 195 @code{(}@svar{pattern} @dots{} @svar{pattern} @svar{ellipsis} @svar{pattern} @dots{}@code{)} 196 @code{(}@svar{pattern} @dots{} @svar{pattern} @svar{ellipsis} @svar{pattern} @dots{} 197 @code{.} @svar{pattern}@code{)} 198 @code{#(}@svar{pattern} @dots{}@code{)} 199 @code{#(}@svar{pattern} @dots{} @svar{pattern} @svar{ellipsis} @svar{pattern} @dots{}@code{)} 200 @end display 201 202 and a @svar{template} is either an identifier, a constant, or one of the 203 following 204 205 @display 206 @code{(}@svar{element} @dots{}@code{)} 207 @code{(}@svar{element} @svar{element} @dots{} @code{.} @svar{template}@code{)} 208 @code{(}@svar{ellipsis} @svar{template}@code{)} 209 @code{#(}@svar{element} @dots{}@code{)} 210 @end display 211 212 where an @svar{element} is a @svar{template} optionally followed by 213 an @svar{ellipsis}. An @svar{ellipsis} is the identifier specified 214 in the second form of @code{syntax-rules}, or the default identifier 215 @code{@dots{}} (three consecutive periods) otherwise. 216 217 Semantics: An instance of @code{syntax-rules} produces a new macro 218 transformer by specifying a sequence of hygienic rewrite rules. A use 219 of a macro whose keyword is associated with a transformer specified by 220 @code{syntax-rules} is matched against the patterns contained in the 221 @svar{syntax rule}s, beginning with the leftmost @svar{syntax rule}. When 222 a match is found, the macro use is transcribed hygienically according 223 to the template. 224 225 An identifier appearing within a @svar{pattern} can be an underscore 226 (@code{_}), a literal identifier listed in the list of @svar{pattern 227 literal}s, or the @svar{ellipsis}. All other identifiers appearing within 228 a @svar{pattern} are @define{pattern variables}. 229 230 The keyword at the beginning of the pattern in a @svar{syntax rule} 231 is not involved in the matching and is considered neither a pattern 232 variable nor a literal identifier. 233 234 Pattern variables match arbitrary input elements and are used to refer 235 to elements of the input in the template. It is an error for the same 236 pattern variable to appear more than once in a @svar{pattern}. 237 238 Underscores also match arbitrary input elements but are not pattern 239 variables and so cannot be used to refer to those elements. If an 240 underscore appears in the @svar{pattern literal}s list, then that 241 takes precedence and underscores in the @svar{pattern} match as 242 literals. Multiple underscores can appear in a @svar{pattern}. 243 244 Identifiers that appear in @code{(}@svar{pattern literal} @dots{}@code{)} 245 are interpreted as literal identifiers to be matched against corresponding 246 elements of the input. An element in the input matches a literal 247 identifier if and only if it is an identifier and either both its 248 occurrence in the macro expression and its occurrence in the macro 249 definition have the same lexical binding, or the two identifiers are 250 the same and both have no lexical binding. 251 252 A subpattern followed by @svar{ellipsis} can match zero or more elements 253 of the input, unless @svar{ellipsis} appears in the @svar{pattern 254 literal}s, in which case it is matched as a literal. 255 256 More formally, an input expression @var{E} matches a pattern @var{P} 257 if and only if: 258 259 @itemize 260 261 @item 262 @var{P} is an underscore (@code{_}). 263 264 @item 265 @var{P} is a non-literal identifier; or 266 267 @item 268 @var{P} is a literal identifier and @var{E} is an identifier with the 269 same binding; or 270 271 @item 272 @var{P} is a list @code{(}@var{P@sub{1}} @dots{} @var{P@sub{n}}@code{)} 273 and @var{E} is a list of @var{n} elements that match @var{P@sub{1}} 274 through @var{P@sub{n}}, respectively; or 275 276 @item 277 @var{P} is an improper list 278 @code{(}@var{P@sub{1}} @var{P@sub{2}} @dots{} @var{P@sub{n}} @code{.} 279 @var{P@sub{n+1}}@code{)} and @var{E} is a list or 280 improper list of @var{n} or more elements that match @var{P@sub{1}} 281 through @var{P@sub{n}} respectively, and whose @var{n}th tail matches 282 @var{P@sub{n+1}}; or 283 284 @item 285 286 @var{P} is of the form 287 @code{(}@var{P@sub{1}} @dots{} @var{P@sub{k}} @var{P@sub{e}} 288 @svar{ellipsis} @var{P@sub{m+1}} @dots{} @var{P@sub{n}}@code{)} 289 where @var{E} is a proper list of @var{n} elements, the first @var{k} 290 of which match @var{P@sub{1}} through @var{P@sub{k}}, respectively, 291 whose next @var{m} @minus{} @var{k} elements each match @var{P@sub{e}}, 292 whose remaining @var{n} @minus{} @var{m} elements match @var{P@sub{m+1}} 293 through @var{P@sub{n}}; or 294 295 @item 296 @var{P} is of the form 297 @code{(}@var{P@sub{1}} @dots{} @var{P@sub{k}} @var{P@sub{e}} 298 @svar{ellipsis} @var{P@sub{m+1}} @dots{} @var{P@sub{n}} @code{.} 299 @var{P@sub{x}}@code{)} where @var{E} is a list or improper list of 300 @var{n} elements, the first @var{k} of which match @var{P@sub{1}} through 301 @var{P@sub{k}}, whose next @var{m} @minus{} @var{k} elements each match 302 @var{P@sub{e}}, whose remaining @var{n} @minus{} @var{m} elements match 303 @var{P@sub{m+1}} through @var{P@sub{n}}, and whose @var{n}th and final cdr 304 matches @var{P@sub{x}}; or 305 306 @item 307 @var{P} is a vector of the form @code{#(}@var{P@sub{1}} @dots{} 308 @var{P@sub{n}}@code{)} and @var{E} is a vector of @var{n} elements that 309 match @var{P@sub{1}} through @var{P@sub{n}}; or 310 311 @item 312 @var{P} is of the form @code{#(}@var{P@sub{1}} @dots{} @var{P@sub{k}} 313 @var{P@sub{e}} @svar{ellipsis} @var{P@sub{m+1}} @dots{} 314 @var{P@sub{n}}@code{)} where @var{E} is a vector of @var{n} elements the 315 first @var{k} of which match @var{P@sub{1}} through @var{P@sub{k}}, whose 316 next @var{m} @minus{} @var{k} elements each match @var{P@sub{e}}, and 317 whose remaining @var{n} @minus{} @var{m} elements match @var{P@sub{m+1}} 318 through @var{P@sub{n}}; or 319 320 @item 321 @var{P} is a constant and @var{E} is equal to @var{P} in the sense of 322 the @code{equal?} procedure. 323 324 @end itemize 325 326 It is an error to use a macro keyword, within the scope of its binding, 327 in an expression that does not match any of the patterns. 328 329 When a macro use is transcribed according to the template of the matching 330 @svar{syntax rule}, pattern variables that occur in the template are 331 replaced by the elements they match in the input. Pattern variables that 332 occur in subpatterns followed by one or more instances of the identifier 333 @svar{ellipsis} are allowed only in subtemplates that are followed by 334 as many instances of @svar{ellipsis}. They are replaced in the output by 335 all of the elements they match in the input, distributed as indicated. It 336 is an error if the output cannot be built up as specified. 337 338 Identifiers that appear in the template but are not pattern variables or 339 the identifier @svar{ellipsis} are inserted into the output as literal 340 identifiers. If a literal identifier is inserted as a free identifier 341 then it refers to the binding of that identifier within whose scope 342 the instance of @code{syntax-rules} appears. If a literal identifier is 343 inserted as a bound identifier then it is in effect renamed to prevent 344 inadvertent captures of free identifiers. 345 346 A template of the form @code{(}@svar{ellipsis} @svar{template}@code{)} 347 is identical to @svar{template}, except that ellipses within the 348 template have no special meaning. That is, any ellipses contained within 349 @svar{template} are treated as ordinary identifiers. In particular, 350 the template @code{(}@svar{ellipsis} @svar{ellipsis}@svar{)} produces 351 a single @svar{ellipsis}. This allows syntactic abstractions to expand 352 into code containing ellipses. 353 354 @lisp 355 (define-syntax be-like-begin 356 (syntax-rules () 357 ((be-like-begin name) 358 (define-syntax name 359 (syntax-rules () 360 ((name expr (... ...)) 361 (begin expr (... ...)))))))) 362 363 (be-like-begin sequence) 364 (sequence 1 2 3 4) @result{} 4 365 @end lisp 366 367 As an example, if @code{let} and @code{cond} are defined as in 368 @ref{Derived expression types formal} then they are hygienic (as 369 required) and the following is not an error. 370 371 @lisp 372 (let ((=> #f)) 373 (cond (#t => 'ok))) @result{} ok 374 @end lisp 375 376 The macro transformer for @code{cond} recognizes @code{=>} as a local 377 variable, and hence an expression, and not as the base identifier 378 @code{=>}, which the macro transformer treats as a syntactic keyword. Thus 379 the example expands into 380 381 @lisp 382 (let ((=> #f)) 383 (if #t (begin => 'ok))) 384 @end lisp 385 386 instead of 387 388 @lisp 389 (let ((=> #f)) 390 (let ((temp #t)) 391 (if temp ('ok temp)))) 392 @end lisp 393 394 which would result in an invalid procedure call. 395 396 @end deffn 397 398 @node Signaling errors in macro transformers 399 @subsection Signaling errors in macro transformers 400 401 @deffn syntax syntax-error @svar{message} @svar{args}@dots{} 402 403 syntax-error behaves similarly to error (@ref{Exceptions}) except that 404 implementations with an expansion pass separate from evaluation should 405 signal an error as soon as @code{syntax-error} is expanded. This can be 406 used as a @code{syntax-rules} @svar{template} for a @svar{pattern} that is 407 an invalid use of the macro, which can provide more descriptive error 408 messages. @svar{message} is a string literal, and @svar{args} arbitrary 409 expressions providing additional information. Applications cannot count on 410 being able to catch syntax errors with exception handlers or guards. 411 412 @lisp 413 (define-syntax simple-let 414 (syntax-rules () 415 ((simple-let ((x . y) val) body1 body2 ...) 416 (syntax-error "expected an identifier" (x . y))) 417 ((simple-let (name val) body1 body2 ...) 418 @end lisp 419 420 @end deffn