api-macros.texi 52 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489
  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Guile Reference Manual.
  3. @c Copyright (C) 1996, 1997, 2000-2004, 2009-2015, 2018, 2021
  4. @c Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node Macros
  7. @section Macros
  8. At its best, programming in Lisp is an iterative process of building up a
  9. language appropriate to the problem at hand, and then solving the problem in
  10. that language. Defining new procedures is part of that, but Lisp also allows
  11. the user to extend its syntax, with its famous @dfn{macros}.
  12. @cindex macros
  13. @cindex transformation
  14. Macros are syntactic extensions which cause the expression that they appear in
  15. to be transformed in some way @emph{before} being evaluated. In expressions that
  16. are intended for macro transformation, the identifier that names the relevant
  17. macro must appear as the first element, like this:
  18. @lisp
  19. (@var{macro-name} @var{macro-args} @dots{})
  20. @end lisp
  21. @cindex macro expansion
  22. @cindex domain-specific language
  23. @cindex embedded domain-specific language
  24. @cindex DSL
  25. @cindex EDSL
  26. Macro expansion is a separate phase of evaluation, run before code is
  27. interpreted or compiled. A macro is a program that runs on programs, translating
  28. an embedded language into core Scheme@footnote{These days such embedded
  29. languages are often referred to as @dfn{embedded domain-specific
  30. languages}, or EDSLs.}.
  31. @menu
  32. * Defining Macros:: Binding macros, globally and locally.
  33. * Syntax Rules:: Pattern-driven macros.
  34. * Syntax Case:: Procedural, hygienic macros.
  35. * Syntax Transformer Helpers:: Helpers for use in procedural macros.
  36. * Defmacros:: Lisp-style macros.
  37. * Identifier Macros:: Identifier macros.
  38. * Syntax Parameters:: Syntax Parameters.
  39. * Eval When:: Affecting the expand-time environment.
  40. * Macro Expansion:: Procedurally expanding macros.
  41. * Hygiene and the Top-Level:: A hack you might want to know about.
  42. * Internal Macros:: Macros as first-class values.
  43. @end menu
  44. @node Defining Macros
  45. @subsection Defining Macros
  46. A macro is a binding between a keyword and a syntax transformer. Since it's
  47. difficult to discuss @code{define-syntax} without discussing the format of
  48. transformers, consider the following example macro definition:
  49. @example
  50. (define-syntax when
  51. (syntax-rules ()
  52. ((when condition exp ...)
  53. (if condition
  54. (begin exp ...)))))
  55. (when #t
  56. (display "hey ho\n")
  57. (display "let's go\n"))
  58. @print{} hey ho
  59. @print{} let's go
  60. @end example
  61. In this example, the @code{when} binding is bound with @code{define-syntax}.
  62. Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
  63. @ref{Syntax Case}.
  64. @deffn {Syntax} define-syntax keyword transformer
  65. Bind @var{keyword} to the syntax transformer obtained by evaluating
  66. @var{transformer}.
  67. After a macro has been defined, further instances of @var{keyword} in Scheme
  68. source code will invoke the syntax transformer defined by @var{transformer}.
  69. @end deffn
  70. One can also establish local syntactic bindings with @code{let-syntax}.
  71. @deffn {Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
  72. Bind each @var{keyword} to its corresponding @var{transformer} while
  73. expanding @var{exp1} @var{exp2} @enddots{}.
  74. A @code{let-syntax} binding only exists at expansion-time.
  75. @example
  76. (let-syntax ((unless
  77. (syntax-rules ()
  78. ((unless condition exp ...)
  79. (if (not condition)
  80. (begin exp ...))))))
  81. (unless #t
  82. (primitive-exit 1))
  83. "rock rock rock")
  84. @result{} "rock rock rock"
  85. @end example
  86. @end deffn
  87. A @code{define-syntax} form is valid anywhere a definition may appear: at the
  88. top-level, or locally. Just as a local @code{define} expands out to an instance
  89. of @code{letrec}, a local @code{define-syntax} expands out to
  90. @code{letrec-syntax}.
  91. @deffn {Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{}
  92. Bind each @var{keyword} to its corresponding @var{transformer} while
  93. expanding @var{exp1} @var{exp2} @enddots{}.
  94. In the spirit of @code{letrec} versus @code{let}, an expansion produced by
  95. @var{transformer} may reference a @var{keyword} bound by the
  96. same @var{letrec-syntax}.
  97. @example
  98. (letrec-syntax ((my-or
  99. (syntax-rules ()
  100. ((my-or)
  101. #t)
  102. ((my-or exp)
  103. exp)
  104. ((my-or exp rest ...)
  105. (let ((t exp))
  106. (if t
  107. t
  108. (my-or rest ...)))))))
  109. (my-or #f "rockaway beach"))
  110. @result{} "rockaway beach"
  111. @end example
  112. @end deffn
  113. @node Syntax Rules
  114. @subsection Syntax-rules Macros
  115. @code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
  116. a beauty worthy of Scheme.
  117. @deffn {Syntax} syntax-rules literals (pattern template) @dots{}
  118. Create a syntax transformer that will rewrite an expression using the rules
  119. embodied in the @var{pattern} and @var{template} clauses.
  120. @end deffn
  121. A @code{syntax-rules} macro consists of three parts: the literals (if any), the
  122. patterns, and as many templates as there are patterns.
  123. When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
  124. matches the expression against the patterns, in order, and rewrites the
  125. expression using the template from the first matching pattern. If no pattern
  126. matches, a syntax error is signalled.
  127. @subsubsection Patterns
  128. We have already seen some examples of patterns in the previous section:
  129. @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
  130. structured like the expression that it is to match. It can have nested structure
  131. as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
  132. patterns are made of lists, improper lists, vectors, identifiers, and datums.
  133. Users can match a sequence of patterns using the ellipsis (@code{...}).
  134. Identifiers in a pattern are called @dfn{literals} if they are present in the
  135. @code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
  136. building up the macro output, the expander replaces instances of a pattern
  137. variable in the template with the matched subexpression.
  138. @example
  139. (define-syntax kwote
  140. (syntax-rules ()
  141. ((kwote exp)
  142. (quote exp))))
  143. (kwote (foo . bar))
  144. @result{} (foo . bar)
  145. @end example
  146. An improper list of patterns matches as rest arguments do:
  147. @example
  148. (define-syntax let1
  149. (syntax-rules ()
  150. ((_ (var val) . exps)
  151. (let ((var val)) . exps))))
  152. @end example
  153. However this definition of @code{let1} probably isn't what you want, as the tail
  154. pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
  155. often instead of using improper lists as patterns, ellipsized patterns are
  156. better. Instances of a pattern variable in the template must be followed by an
  157. ellipsis.
  158. @example
  159. (define-syntax let1
  160. (syntax-rules ()
  161. ((_ (var val) exp ...)
  162. (let ((var val)) exp ...))))
  163. @end example
  164. This @code{let1} probably still doesn't do what we want, because the body
  165. matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
  166. case we need to assert we have at least one body expression. A common idiom for
  167. this is to name the ellipsized pattern variable with an asterisk:
  168. @example
  169. (define-syntax let1
  170. (syntax-rules ()
  171. ((_ (var val) exp exp* ...)
  172. (let ((var val)) exp exp* ...))))
  173. @end example
  174. A vector of patterns matches a vector whose contents match the patterns,
  175. including ellipsizing and tail patterns.
  176. @example
  177. (define-syntax letv
  178. (syntax-rules ()
  179. ((_ #((var val) ...) exp exp* ...)
  180. (let ((var val) ...) exp exp* ...))))
  181. (letv #((foo 'bar)) foo)
  182. @result{} bar
  183. @end example
  184. Literals are used to match specific datums in an expression, like the use of
  185. @code{=>} and @code{else} in @code{cond} expressions.
  186. @example
  187. (define-syntax cond1
  188. (syntax-rules (=> else)
  189. ((cond1 test => fun)
  190. (let ((exp test))
  191. (if exp (fun exp) #f)))
  192. ((cond1 test exp exp* ...)
  193. (if test (begin exp exp* ...)))
  194. ((cond1 else exp exp* ...)
  195. (begin exp exp* ...))))
  196. (define (square x) (* x x))
  197. (cond1 10 => square)
  198. @result{} 100
  199. (let ((=> #t))
  200. (cond1 10 => square))
  201. @result{} #<procedure square (x)>
  202. @end example
  203. A literal matches an input expression if the input expression is an identifier
  204. with the same name as the literal, and both are unbound@footnote{Language
  205. lawyers probably see the need here for use of @code{literal-identifier=?} rather
  206. than @code{free-identifier=?}, and would probably be correct. Patches
  207. accepted.}.
  208. @cindex auxiliary syntax
  209. @cindex syntax, auxiliary
  210. Although literals can be unbound, usually they are bound to allow them
  211. to be imported, exported, and renamed. @xref{Modules}, for more
  212. information on imports and exports. In Guile there are a few standard
  213. auxiliary syntax definitions, as specified by R6RS and R7RS:
  214. @deffn {Scheme Syntax} else
  215. @deffnx {Scheme Syntax} =>
  216. @deffnx {Scheme Syntax} _
  217. @deffnx {Scheme Syntax} ...
  218. Auxiliary syntax definitions.
  219. These are defined as if with a macro that never matches, e.g.:
  220. @example
  221. (define-syntax else (syntax-rules ()))
  222. @end example
  223. @end deffn
  224. If a pattern is not a list, vector, or an identifier, it matches as a literal,
  225. with @code{equal?}.
  226. @example
  227. (define-syntax define-matcher-macro
  228. (syntax-rules ()
  229. ((_ name lit)
  230. (define-syntax name
  231. (syntax-rules ()
  232. ((_ lit) #t)
  233. ((_ else) #f))))))
  234. (define-matcher-macro is-literal-foo? "foo")
  235. (is-literal-foo? "foo")
  236. @result{} #t
  237. (is-literal-foo? "bar")
  238. @result{} #f
  239. (let ((foo "foo"))
  240. (is-literal-foo? foo))
  241. @result{} #f
  242. @end example
  243. The last example indicates that matching happens at expansion-time, not
  244. at run-time.
  245. Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
  246. the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
  247. pattern must be a list (proper or improper), and the first pattern in that list
  248. must be an identifier. Incidentally it can be any identifier -- it doesn't have
  249. to actually be the name of the macro. Thus the following three are equivalent:
  250. @example
  251. (define-syntax when
  252. (syntax-rules ()
  253. ((when c e ...)
  254. (if c (begin e ...)))))
  255. (define-syntax when
  256. (syntax-rules ()
  257. ((_ c e ...)
  258. (if c (begin e ...)))))
  259. (define-syntax when
  260. (syntax-rules ()
  261. ((something-else-entirely c e ...)
  262. (if c (begin e ...)))))
  263. @end example
  264. For clarity, use one of the first two variants. Also note that since the pattern
  265. variable will always match the macro itself (e.g., @code{cond1}), it is actually
  266. left unbound in the template.
  267. @subsubsection Hygiene
  268. @code{syntax-rules} macros have a magical property: they preserve referential
  269. transparency. When you read a macro definition, any free bindings in that macro
  270. are resolved relative to the macro definition; and when you read a macro
  271. instantiation, all free bindings in that expression are resolved relative to the
  272. expression.
  273. This property is sometimes known as @dfn{hygiene}, and it does aid in code
  274. cleanliness. In your macro definitions, you can feel free to introduce temporary
  275. variables, without worrying about inadvertently introducing bindings into the
  276. macro expansion.
  277. Consider the definition of @code{my-or} from the previous section:
  278. @example
  279. (define-syntax my-or
  280. (syntax-rules ()
  281. ((my-or)
  282. #t)
  283. ((my-or exp)
  284. exp)
  285. ((my-or exp rest ...)
  286. (let ((t exp))
  287. (if t
  288. t
  289. (my-or rest ...))))))
  290. @end example
  291. A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:
  292. @example
  293. (let ((t #t))
  294. (let ((t #f))
  295. (if t t t)))
  296. @result{} #f
  297. @end example
  298. @noindent
  299. Which clearly is not what we want. Somehow the @code{t} in the definition is
  300. distinct from the @code{t} at the site of use; and it is indeed this distinction
  301. that is maintained by the syntax expander, when expanding hygienic macros.
  302. This discussion is mostly relevant in the context of traditional Lisp macros
  303. (@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
  304. adds to the expressive power of Scheme.
  305. @subsubsection Shorthands
  306. One often ends up writing simple one-clause @code{syntax-rules} macros.
  307. There is a convenient shorthand for this idiom, in the form of
  308. @code{define-syntax-rule}.
  309. @deffn {Syntax} define-syntax-rule (keyword . pattern) [docstring] template
  310. Define @var{keyword} as a new @code{syntax-rules} macro with one clause.
  311. @end deffn
  312. Cast into this form, our @code{when} example is significantly shorter:
  313. @example
  314. (define-syntax-rule (when c e ...)
  315. (if c (begin e ...)))
  316. @end example
  317. @subsubsection Reporting Syntax Errors in Macros
  318. @deffn {Syntax} syntax-error message [arg ...]
  319. Report an error at macro-expansion time. @var{message} must be a string
  320. literal, and the optional @var{arg} operands can be arbitrary expressions
  321. providing additional information.
  322. @end deffn
  323. @code{syntax-error} is intended to be used within @code{syntax-rules}
  324. templates. For example:
  325. @example
  326. (define-syntax simple-let
  327. (syntax-rules ()
  328. ((_ (head ... ((x . y) val) . tail)
  329. body1 body2 ...)
  330. (syntax-error
  331. "expected an identifier but got"
  332. (x . y)))
  333. ((_ ((name val) ...) body1 body2 ...)
  334. ((lambda (name ...) body1 body2 ...)
  335. val ...))))
  336. @end example
  337. @subsubsection Specifying a Custom Ellipsis Identifier
  338. When writing macros that generate macro definitions, it is convenient to
  339. use a different ellipsis identifier at each level. Guile allows the
  340. desired ellipsis identifier to be specified as the first operand to
  341. @code{syntax-rules}, as specified by SRFI-46 and R7RS. For example:
  342. @example
  343. (define-syntax define-quotation-macros
  344. (syntax-rules ()
  345. ((_ (macro-name head-symbol) ...)
  346. (begin (define-syntax macro-name
  347. (syntax-rules ::: ()
  348. ((_ x :::)
  349. (quote (head-symbol x :::)))))
  350. ...))))
  351. (define-quotation-macros (quote-a a) (quote-b b) (quote-c c))
  352. (quote-a 1 2 3) @result{} (a 1 2 3)
  353. @end example
  354. @subsubsection Further Information
  355. For a formal definition of @code{syntax-rules} and its pattern language, see
  356. @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
  357. Scheme}.
  358. @code{syntax-rules} macros are simple and clean, but do they have limitations.
  359. They do not lend themselves to expressive error messages: patterns either match
  360. or they don't. Their ability to generate code is limited to template-driven
  361. expansion; often one needs to define a number of helper macros to get real work
  362. done. Sometimes one wants to introduce a binding into the lexical context of the
  363. generated code; this is impossible with @code{syntax-rules}. Relatedly, they
  364. cannot programmatically generate identifiers.
  365. The solution to all of these problems is to use @code{syntax-case} if you need
  366. its features. But if for some reason you're stuck with @code{syntax-rules}, you
  367. might enjoy Joe Marshall's
  368. @uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
  369. Primer for the Merely Eccentric}.
  370. @node Syntax Case
  371. @subsection Support for the @code{syntax-case} System
  372. @code{syntax-case} macros are procedural syntax transformers, with a power
  373. worthy of Scheme.
  374. @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp) @dots{}
  375. Match the syntax object @var{syntax} against the given patterns, in order. If a
  376. @var{pattern} matches, return the result of evaluating the associated @var{exp}.
  377. @end deffn
  378. Compare the following definitions of @code{when}:
  379. @example
  380. (define-syntax when
  381. (syntax-rules ()
  382. ((_ test e e* ...)
  383. (if test (begin e e* ...)))))
  384. (define-syntax when
  385. (lambda (x)
  386. (syntax-case x ()
  387. ((_ test e e* ...)
  388. #'(if test (begin e e* ...))))))
  389. @end example
  390. Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
  391. counterpart, and equally clearly there are some differences. The
  392. @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
  393. argument; that argument is passed to the @code{syntax-case} invocation; and the
  394. ``return value'' of the macro has a @code{#'} prefix.
  395. All of these differences stem from the fact that @code{syntax-case} does not
  396. define a syntax transformer itself -- instead, @code{syntax-case} expressions
  397. provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
  398. objects as output.
  399. So the @code{lambda} wrapper is simply a leaky implementation detail, that
  400. syntax transformers are just functions that transform syntax to syntax. This
  401. should not be surprising, given that we have already described macros as
  402. ``programs that write programs''. @code{syntax-case} is simply a way to take
  403. apart and put together program text, and to be a valid syntax transformer it
  404. needs to be wrapped in a procedure.
  405. Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
  406. transform syntax objects, not raw Scheme forms. Recall the naive expansion of
  407. @code{my-or} given in the previous section:
  408. @example
  409. (let ((t #t))
  410. (my-or #f t))
  411. ;; naive expansion:
  412. (let ((t #t))
  413. (let ((t #f))
  414. (if t t t)))
  415. @end example
  416. Raw Scheme forms simply don't have enough information to distinguish the first
  417. two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
  418. of representing identifiers as symbols, the syntax expander represents
  419. identifiers as annotated syntax objects, attaching such information to those
  420. syntax objects as is needed to maintain referential transparency.
  421. @deffn {Syntax} syntax form
  422. Create a syntax object wrapping @var{form} within the current lexical context.
  423. @end deffn
  424. Syntax objects are typically created internally to the process of expansion, but
  425. it is possible to create them outside of syntax expansion:
  426. @example
  427. (syntax (foo bar baz))
  428. @result{} #<some representation of that syntax>
  429. @end example
  430. @noindent
  431. However it is more common, and useful, to create syntax objects when building
  432. output from a @code{syntax-case} expression.
  433. @example
  434. (define-syntax add1
  435. (lambda (x)
  436. (syntax-case x ()
  437. ((_ exp)
  438. (syntax (+ exp 1))))))
  439. @end example
  440. It is not strictly necessary for a @code{syntax-case} expression to return a
  441. syntax object, because @code{syntax-case} expressions can be used in helper
  442. functions, or otherwise used outside of syntax expansion itself. However a
  443. syntax transformer procedure must return a syntax object, so most uses of
  444. @code{syntax-case} do end up returning syntax objects.
  445. Here in this case, the form that built the return value was @code{(syntax (+ exp
  446. 1))}. The interesting thing about this is that within a @code{syntax}
  447. expression, any appearance of a pattern variable is substituted into the
  448. resulting syntax object, carrying with it all relevant metadata from the source
  449. expression, such as lexical identity and source location.
  450. Indeed, a pattern variable may only be referenced from inside a @code{syntax}
  451. form. The syntax expander would raise an error when defining @code{add1} if it
  452. found @var{exp} referenced outside a @code{syntax} form.
  453. Since @code{syntax} appears frequently in macro-heavy code, it has a special
  454. reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
  455. @code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}.
  456. The pattern language used by @code{syntax-case} is conveniently the same
  457. language used by @code{syntax-rules}. Given this, Guile actually defines
  458. @code{syntax-rules} in terms of @code{syntax-case}:
  459. @example
  460. (define-syntax syntax-rules
  461. (lambda (x)
  462. (syntax-case x ()
  463. ((_ (k ...) ((keyword . pattern) template) ...)
  464. #'(lambda (x)
  465. (syntax-case x (k ...)
  466. ((dummy . pattern) #'template)
  467. ...))))))
  468. @end example
  469. And that's that.
  470. @subsubsection Why @code{syntax-case}?
  471. The examples we have shown thus far could just as well have been expressed with
  472. @code{syntax-rules}, and have just shown that @code{syntax-case} is more
  473. verbose, which is true. But there is a difference: @code{syntax-case} creates
  474. @emph{procedural} macros, giving the full power of Scheme to the macro expander.
  475. This has many practical applications.
  476. A common desire is to be able to match a form only if it is an identifier. This
  477. is impossible with @code{syntax-rules}, given the datum matching forms. But with
  478. @code{syntax-case} it is easy:
  479. @deffn {Scheme Procedure} identifier? syntax-object
  480. Returns @code{#t} if @var{syntax-object} is an identifier, or @code{#f}
  481. otherwise.
  482. @end deffn
  483. @example
  484. ;; relying on previous add1 definition
  485. (define-syntax add1!
  486. (lambda (x)
  487. (syntax-case x ()
  488. ((_ var) (identifier? #'var)
  489. #'(set! var (add1 var))))))
  490. (define foo 0)
  491. (add1! foo)
  492. foo @result{} 1
  493. (add1! "not-an-identifier") @result{} error
  494. @end example
  495. With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
  496. be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
  497. something like ``invalid @code{add1!}'', because we attach the @dfn{guard
  498. clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
  499. with more complicated macros. It is necessary to use @code{identifier?}, because
  500. to the expander, an identifier is more than a bare symbol.
  501. Note that even in the guard clause, we reference the @var{var} pattern variable
  502. within a @code{syntax} form, via @code{#'var}.
  503. Another common desire is to introduce bindings into the lexical context of the
  504. output expression. One example would be in the so-called ``anaphoric macros'',
  505. like @code{aif}. Anaphoric macros bind some expression to a well-known
  506. identifier, often @code{it}, within their bodies. For example, in @code{(aif
  507. (foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.
  508. To begin with, we should mention a solution that doesn't work:
  509. @example
  510. ;; doesn't work
  511. (define-syntax aif
  512. (lambda (x)
  513. (syntax-case x ()
  514. ((_ test then else)
  515. #'(let ((it test))
  516. (if it then else))))))
  517. @end example
  518. The reason that this doesn't work is that, by default, the expander will
  519. preserve referential transparency; the @var{then} and @var{else} expressions
  520. won't have access to the binding of @code{it}.
  521. But they can, if we explicitly introduce a binding via @code{datum->syntax}.
  522. @deffn {Scheme Procedure} datum->syntax template-id datum [#:source=#f]
  523. Create a syntax object that wraps @var{datum}, within the lexical
  524. context corresponding to the identifier @var{template-id}. If
  525. @var{template-id} is false, the datum will have no lexical context
  526. information.
  527. Syntax objects have an associated source location. Internally this is
  528. represented as a 3-element vector of filename, line, and column.
  529. Usually this location ultimately is provided by @code{read-syntax};
  530. @xref{Annotated Scheme Read}.
  531. If a syntax object is passed as @var{source}, the resulting syntax
  532. object will have the source location of @var{source}. Otherwise if
  533. @var{source} is a 3-element source location vector, that vector will be
  534. the source location of the resulting syntax object. If @var{source} is
  535. a source properties alist, those will be parsed and set as the source
  536. location of the resulting syntax object. Otherwise if @var{source} is
  537. false, the source properties are looked up from @code{(source-properties
  538. @var{datum})}. @xref{Source Properties}.
  539. @end deffn
  540. For completeness, we should mention that it is possible to strip the metadata
  541. from a syntax object, returning a raw Scheme datum:
  542. @deffn {Scheme Procedure} syntax->datum syntax-object
  543. Strip the metadata from @var{syntax-object}, returning its contents as a raw
  544. Scheme datum.
  545. @end deffn
  546. In this case we want to introduce @code{it} in the context of the whole
  547. expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
  548. where @code{x} is the whole expression, as passed to the transformer procedure.
  549. Here's another solution that doesn't work:
  550. @example
  551. ;; doesn't work either
  552. (define-syntax aif
  553. (lambda (x)
  554. (syntax-case x ()
  555. ((_ test then else)
  556. (let ((it (datum->syntax x 'it)))
  557. #'(let ((it test))
  558. (if it then else)))))))
  559. @end example
  560. The reason that this one doesn't work is that there are really two
  561. environments at work here -- the environment of pattern variables, as
  562. bound by @code{syntax-case}, and the environment of lexical variables,
  563. as bound by normal Scheme. The outer let form establishes a binding in
  564. the environment of lexical variables, but the inner let form is inside a
  565. syntax form, where only pattern variables will be substituted. Here we
  566. need to introduce a piece of the lexical environment into the pattern
  567. variable environment, and we can do so using @code{syntax-case} itself:
  568. @example
  569. ;; works, but is obtuse
  570. (define-syntax aif
  571. (lambda (x)
  572. (syntax-case x ()
  573. ((_ test then else)
  574. ;; invoking syntax-case on the generated
  575. ;; syntax object to expose it to `syntax'
  576. (syntax-case (datum->syntax x 'it) ()
  577. (it
  578. #'(let ((it test))
  579. (if it then else))))))))
  580. (aif (getuid) (display it) (display "none")) (newline)
  581. @print{} 500
  582. @end example
  583. However there are easier ways to write this. @code{with-syntax} is often
  584. convenient:
  585. @deffn {Syntax} with-syntax ((pat val) @dots{}) exp @dots{}
  586. Bind patterns @var{pat} from their corresponding values @var{val}, within the
  587. lexical context of @var{exp} @enddots{}.
  588. @example
  589. ;; better
  590. (define-syntax aif
  591. (lambda (x)
  592. (syntax-case x ()
  593. ((_ test then else)
  594. (with-syntax ((it (datum->syntax x 'it)))
  595. #'(let ((it test))
  596. (if it then else)))))))
  597. @end example
  598. @end deffn
  599. As you might imagine, @code{with-syntax} is defined in terms of
  600. @code{syntax-case}. But even that might be off-putting to you if you are an old
  601. Lisp macro hacker, used to building macro output with @code{quasiquote}. The
  602. issue is that @code{with-syntax} creates a separation between the point of
  603. definition of a value and its point of substitution.
  604. @pindex quasisyntax
  605. @pindex unsyntax
  606. @pindex unsyntax-splicing
  607. So for cases in which a @code{quasiquote} style makes more sense,
  608. @code{syntax-case} also defines @code{quasisyntax}, and the related
  609. @code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
  610. @code{#`}, @code{#,}, and @code{#,@@}, respectively.
  611. For example, to define a macro that inserts a compile-time timestamp into a
  612. source file, one may write:
  613. @example
  614. (define-syntax display-compile-timestamp
  615. (lambda (x)
  616. (syntax-case x ()
  617. ((_)
  618. #`(begin
  619. (display "The compile timestamp was: ")
  620. (display #,(current-time))
  621. (newline))))))
  622. @end example
  623. Readers interested in further information on @code{syntax-case} macros should
  624. see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
  625. edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
  626. @code{syntax-case} system. The book itself is available online at
  627. @uref{http://scheme.com/tspl4/}.
  628. @subsubsection Custom Ellipsis Identifiers for syntax-case Macros
  629. When writing procedural macros that generate macro definitions, it is
  630. convenient to use a different ellipsis identifier at each level. Guile
  631. supports this for procedural macros using the @code{with-ellipsis}
  632. special form:
  633. @deffn {Syntax} with-ellipsis ellipsis body @dots{}
  634. @var{ellipsis} must be an identifier. Evaluate @var{body} in a special
  635. lexical environment such that all macro patterns and templates within
  636. @var{body} will use @var{ellipsis} as the ellipsis identifier instead of
  637. the usual three dots (@code{...}).
  638. @end deffn
  639. For example:
  640. @example
  641. (define-syntax define-quotation-macros
  642. (lambda (x)
  643. (syntax-case x ()
  644. ((_ (macro-name head-symbol) ...)
  645. #'(begin (define-syntax macro-name
  646. (lambda (x)
  647. (with-ellipsis :::
  648. (syntax-case x ()
  649. ((_ x :::)
  650. #'(quote (head-symbol x :::)))))))
  651. ...)))))
  652. (define-quotation-macros (quote-a a) (quote-b b) (quote-c c))
  653. (quote-a 1 2 3) @result{} (a 1 2 3)
  654. @end example
  655. Note that @code{with-ellipsis} does not affect the ellipsis identifier
  656. of the generated code, unless @code{with-ellipsis} is included around
  657. the generated code.
  658. @node Syntax Transformer Helpers
  659. @subsection Syntax Transformer Helpers
  660. As noted in the previous section, Guile's syntax expander operates on
  661. syntax objects. Procedural macros consume and produce syntax objects.
  662. This section describes some of the auxiliary helpers that procedural
  663. macros can use to compare, generate, and query objects of this data
  664. type.
  665. @deffn {Scheme Procedure} bound-identifier=? a b
  666. Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the
  667. same lexically-bound identifier, or @code{#f} otherwise.
  668. @end deffn
  669. @deffn {Scheme Procedure} free-identifier=? a b
  670. Return @code{#t} if the syntax objects @var{a} and @var{b} refer to the
  671. same free identifier, or @code{#f} otherwise.
  672. @end deffn
  673. @deffn {Scheme Procedure} generate-temporaries ls
  674. Return a list of temporary identifiers as long as @var{ls} is long.
  675. @end deffn
  676. @deffn {Scheme Procedure} syntax-source x
  677. Return the source properties that correspond to the syntax object
  678. @var{x}. @xref{Source Properties}, for more information.
  679. @end deffn
  680. Guile also offers some more experimental interfaces in a separate
  681. module. As was the case with the Large Hadron Collider, it is unclear
  682. to our senior macrologists whether adding these interfaces will result
  683. in awesomeness or in the destruction of Guile via the creation of a
  684. singularity. We will preserve their functionality through the 2.0
  685. series, but we reserve the right to modify them in a future stable
  686. series, to a more than usual degree.
  687. @example
  688. (use-modules (system syntax))
  689. @end example
  690. @deffn {Scheme Procedure} syntax-module id
  691. Return the name of the module whose source contains the identifier
  692. @var{id}.
  693. @end deffn
  694. @deffn {Scheme Procedure} syntax-local-binding id [#:resolve-syntax-parameters?=#t]
  695. Resolve the identifer @var{id}, a syntax object, within the current
  696. lexical environment, and return two values, the binding type and a
  697. binding value. The binding type is a symbol, which may be one of the
  698. following:
  699. @table @code
  700. @item lexical
  701. A lexically-bound variable. The value is a unique token (in the sense
  702. of @code{eq?}) identifying this binding.
  703. @item macro
  704. A syntax transformer, either local or global. The value is the
  705. transformer procedure.
  706. @item syntax-parameter
  707. A syntax parameter (@pxref{Syntax Parameters}). By default,
  708. @code{syntax-local-binding} will resolve syntax parameters, so that this
  709. value will not be returned. Pass @code{#:resolve-syntax-parameters? #f}
  710. to indicate that you are interested in syntax parameters. The value is
  711. the default transformer procedure, as in @code{macro}.
  712. @item pattern-variable
  713. A pattern variable, bound via @code{syntax-case}. The value is an
  714. opaque object, internal to the expander.
  715. @item ellipsis
  716. An internal binding, bound via @code{with-ellipsis}. The value is the
  717. (anti-marked) local ellipsis identifier.
  718. @item displaced-lexical
  719. A lexical variable that has gone out of scope. This can happen if a
  720. badly-written procedural macro saves a syntax object, then attempts to
  721. introduce it in a context in which it is unbound. The value is
  722. @code{#f}.
  723. @item global
  724. A global binding. The value is a pair, whose head is the symbol, and
  725. whose tail is the name of the module in which to resolve the symbol.
  726. @item other
  727. Some other binding, like @code{lambda} or other core bindings. The
  728. value is @code{#f}.
  729. @end table
  730. This is a very low-level procedure, with limited uses. One case in
  731. which it is useful is to build abstractions that associate auxiliary
  732. information with macros:
  733. @example
  734. (define aux-property (make-object-property))
  735. (define-syntax-rule (with-aux aux value)
  736. (let ((trans value))
  737. (set! (aux-property trans) aux)
  738. trans))
  739. (define-syntax retrieve-aux
  740. (lambda (x)
  741. (syntax-case x ()
  742. ((x id)
  743. (call-with-values (lambda () (syntax-local-binding #'id))
  744. (lambda (type val)
  745. (with-syntax ((aux (datum->syntax #'here
  746. (and (eq? type 'macro)
  747. (aux-property val)))))
  748. #''aux)))))))
  749. (define-syntax foo
  750. (with-aux 'bar
  751. (syntax-rules () ((_) 'foo))))
  752. (foo)
  753. @result{} foo
  754. (retrieve-aux foo)
  755. @result{} bar
  756. @end example
  757. @code{syntax-local-binding} must be called within the dynamic extent of
  758. a syntax transformer; to call it otherwise will signal an error.
  759. @end deffn
  760. @deffn {Scheme Procedure} syntax-locally-bound-identifiers id
  761. Return a list of identifiers that were visible lexically when the
  762. identifier @var{id} was created, in order from outermost to innermost.
  763. This procedure is intended to be used in specialized procedural macros,
  764. to provide a macro with the set of bound identifiers that the macro can
  765. reference.
  766. As a technical implementation detail, the identifiers returned by
  767. @code{syntax-locally-bound-identifiers} will be anti-marked, like the
  768. syntax object that is given as input to a macro. This is to signal to
  769. the macro expander that these bindings were present in the original
  770. source, and do not need to be hygienically renamed, as would be the case
  771. with other introduced identifiers. See the discussion of hygiene in
  772. section 12.1 of the R6RS, for more information on marks.
  773. @example
  774. (define (local-lexicals id)
  775. (filter (lambda (x)
  776. (eq? (syntax-local-binding x) 'lexical))
  777. (syntax-locally-bound-identifiers id)))
  778. (define-syntax lexicals
  779. (lambda (x)
  780. (syntax-case x ()
  781. ((lexicals) #'(lexicals lexicals))
  782. ((lexicals scope)
  783. (with-syntax (((id ...) (local-lexicals #'scope)))
  784. #'(list (cons 'id id) ...))))))
  785. (let* ((x 10) (x 20)) (lexicals))
  786. @result{} ((x . 10) (x . 20))
  787. @end example
  788. @end deffn
  789. @node Defmacros
  790. @subsection Lisp-style Macro Definitions
  791. The traditional way to define macros in Lisp is very similar to procedure
  792. definitions. The key differences are that the macro definition body should
  793. return a list that describes the transformed expression, and that the definition
  794. is marked as a macro definition (rather than a procedure definition) by the use
  795. of a different definition keyword: in Lisp, @code{defmacro} rather than
  796. @code{defun}, and in Scheme, @code{define-macro} rather than @code{define}.
  797. @fnindex defmacro
  798. @fnindex define-macro
  799. Guile supports this style of macro definition using both @code{defmacro}
  800. and @code{define-macro}. The only difference between them is how the
  801. macro name and arguments are grouped together in the definition:
  802. @lisp
  803. (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
  804. @end lisp
  805. @noindent
  806. is the same as
  807. @lisp
  808. (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
  809. @end lisp
  810. @noindent
  811. The difference is analogous to the corresponding difference between
  812. Lisp's @code{defun} and Scheme's @code{define}.
  813. Having read the previous section on @code{syntax-case}, it's probably clear that
  814. Guile actually implements defmacros in terms of @code{syntax-case}, applying the
  815. transformer on the expression between invocations of @code{syntax->datum} and
  816. @code{datum->syntax}. This realization leads us to the problem with defmacros,
  817. that they do not preserve referential transparency. One can be careful to not
  818. introduce bindings into expanded code, via liberal use of @code{gensym}, but
  819. there is no getting around the lack of referential transparency for free
  820. bindings in the macro itself.
  821. Even a macro as simple as our @code{when} from before is difficult to get right:
  822. @example
  823. (define-macro (when cond exp . rest)
  824. `(if ,cond
  825. (begin ,exp . ,rest)))
  826. (when #f (display "Launching missiles!\n"))
  827. @result{} #f
  828. (let ((if list))
  829. (when #f (display "Launching missiles!\n")))
  830. @print{} Launching missiles!
  831. @result{} (#f #<unspecified>)
  832. @end example
  833. Guile's perspective is that defmacros have had a good run, but that modern
  834. macros should be written with @code{syntax-rules} or @code{syntax-case}. There
  835. are still many uses of defmacros within Guile itself, but we will be phasing
  836. them out over time. Of course we won't take away @code{defmacro} or
  837. @code{define-macro} themselves, as there is lots of code out there that uses
  838. them.
  839. @node Identifier Macros
  840. @subsection Identifier Macros
  841. When the syntax expander sees a form in which the first element is a macro, the
  842. whole form gets passed to the macro's syntax transformer. One may visualize this
  843. as:
  844. @example
  845. (define-syntax foo foo-transformer)
  846. (foo @var{arg}...)
  847. ;; expands via
  848. (foo-transformer #'(foo @var{arg}...))
  849. @end example
  850. If, on the other hand, a macro is referenced in some other part of a form, the
  851. syntax transformer is invoked with only the macro reference, not the whole form.
  852. @example
  853. (define-syntax foo foo-transformer)
  854. foo
  855. ;; expands via
  856. (foo-transformer #'foo)
  857. @end example
  858. This allows bare identifier references to be replaced programmatically via a
  859. macro. @code{syntax-rules} provides some syntax to effect this transformation
  860. more easily.
  861. @deffn {Syntax} identifier-syntax exp
  862. Returns a macro transformer that will replace occurrences of the macro with
  863. @var{exp}.
  864. @end deffn
  865. For example, if you are importing external code written in terms of @code{fx+},
  866. the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
  867. following to replace @code{fx+} with @code{+}:
  868. @example
  869. (define-syntax fx+ (identifier-syntax +))
  870. @end example
  871. There is also special support for recognizing identifiers on the
  872. left-hand side of a @code{set!} expression, as in the following:
  873. @example
  874. (define-syntax foo foo-transformer)
  875. (set! foo @var{val})
  876. ;; expands via
  877. (foo-transformer #'(set! foo @var{val}))
  878. ;; if foo-transformer is a "variable transformer"
  879. @end example
  880. As the example notes, the transformer procedure must be explicitly
  881. marked as being a ``variable transformer'', as most macros aren't
  882. written to discriminate on the form in the operator position.
  883. @deffn {Scheme Procedure} make-variable-transformer transformer
  884. Mark the @var{transformer} procedure as being a ``variable
  885. transformer''. In practice this means that, when bound to a syntactic
  886. keyword, it may detect references to that keyword on the left-hand-side
  887. of a @code{set!}.
  888. @example
  889. (define bar 10)
  890. (define-syntax bar-alias
  891. (make-variable-transformer
  892. (lambda (x)
  893. (syntax-case x (set!)
  894. ((set! var val) #'(set! bar val))
  895. ((var arg ...) #'(bar arg ...))
  896. (var (identifier? #'var) #'bar)))))
  897. bar-alias @result{} 10
  898. (set! bar-alias 20)
  899. bar @result{} 20
  900. (set! bar 30)
  901. bar-alias @result{} 30
  902. @end example
  903. @end deffn
  904. There is an extension to identifier-syntax which allows it to handle the
  905. @code{set!} case as well:
  906. @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
  907. Create a variable transformer. The first clause is used for references
  908. to the variable in operator or operand position, and the second for
  909. appearances of the variable on the left-hand-side of an assignment.
  910. For example, the previous @code{bar-alias} example could be expressed
  911. more succinctly like this:
  912. @example
  913. (define-syntax bar-alias
  914. (identifier-syntax
  915. (var bar)
  916. ((set! var val) (set! bar val))))
  917. @end example
  918. @noindent
  919. As before, the templates in @code{identifier-syntax} forms do not need
  920. wrapping in @code{#'} syntax forms.
  921. @end deffn
  922. @node Syntax Parameters
  923. @subsection Syntax Parameters
  924. Syntax parameters@footnote{Described in the paper @cite{Keeping it Clean
  925. with Syntax Parameters} by Barzilay, Culpepper and Flatt.} are a
  926. mechanism for rebinding a macro definition within the dynamic extent of
  927. a macro expansion. This provides a convenient solution to one of the
  928. most common types of unhygienic macro: those that introduce a unhygienic
  929. binding each time the macro is used. Examples include a @code{lambda}
  930. form with a @code{return} keyword, or class macros that introduce a
  931. special @code{self} binding.
  932. With syntax parameters, instead of introducing the binding
  933. unhygienically each time, we instead create one binding for the keyword,
  934. which we can then adjust later when we want the keyword to have a
  935. different meaning. As no new bindings are introduced, hygiene is
  936. preserved. This is similar to the dynamic binding mechanisms we have at
  937. run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding
  938. only occurs during macro expansion. The code after macro expansion
  939. remains lexically scoped.
  940. @deffn {Syntax} define-syntax-parameter keyword transformer
  941. Binds @var{keyword} to the value obtained by evaluating
  942. @var{transformer}. The @var{transformer} provides the default expansion
  943. for the syntax parameter, and in the absence of
  944. @code{syntax-parameterize}, is functionally equivalent to
  945. @code{define-syntax}. Usually, you will just want to have the
  946. @var{transformer} throw a syntax error indicating that the @var{keyword}
  947. is supposed to be used in conjunction with another macro, for example:
  948. @example
  949. (define-syntax-parameter return
  950. (lambda (stx)
  951. (syntax-violation 'return "return used outside of a lambda^" stx)))
  952. @end example
  953. @end deffn
  954. @deffn {Syntax} syntax-parameterize ((keyword transformer) @dots{}) exp @dots{}
  955. Adjusts @var{keyword} @dots{} to use the values obtained by evaluating
  956. their @var{transformer} @dots{}, in the expansion of the @var{exp}
  957. @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter.
  958. @code{syntax-parameterize} differs from @code{let-syntax}, in that the
  959. binding is not shadowed, but adjusted, and so uses of the keyword in the
  960. expansion of @var{exp} @dots{} use the new transformers. This is
  961. somewhat similar to how @code{parameterize} adjusts the values of
  962. regular parameters, rather than creating new bindings.
  963. @example
  964. (define-syntax lambda^
  965. (syntax-rules ()
  966. [(lambda^ argument-list body body* ...)
  967. (lambda argument-list
  968. (call-with-current-continuation
  969. (lambda (escape)
  970. ;; In the body we adjust the 'return' keyword so that calls
  971. ;; to 'return' are replaced with calls to the escape
  972. ;; continuation.
  973. (syntax-parameterize ([return (syntax-rules ()
  974. [(return vals (... ...))
  975. (escape vals (... ...))])])
  976. body body* ...))))]))
  977. ;; Now we can write functions that return early. Here, 'product' will
  978. ;; return immediately if it sees any 0 element.
  979. (define product
  980. (lambda^ (list)
  981. (fold (lambda (n o)
  982. (if (zero? n)
  983. (return 0)
  984. (* n o)))
  985. 1
  986. list)))
  987. @end example
  988. @end deffn
  989. @node Eval When
  990. @subsection Eval-when
  991. As @code{syntax-case} macros have the whole power of Scheme available to them,
  992. they present a problem regarding time: when a macro runs, what parts of the
  993. program are available for the macro to use?
  994. The default answer to this question is that when you import a module (via
  995. @code{define-module} or @code{use-modules}), that module will be loaded up at
  996. expansion-time, as well as at run-time. Additionally, top-level syntactic
  997. definitions within one compilation unit made by @code{define-syntax} are also
  998. evaluated at expansion time, in the order that they appear in the compilation
  999. unit (file).
  1000. But if a syntactic definition needs to call out to a normal procedure at
  1001. expansion-time, it might well need need special declarations to indicate that
  1002. the procedure should be made available at expansion-time.
  1003. For example, the following code will work at a REPL, but not in a file:
  1004. @example
  1005. ;; incorrect
  1006. (use-modules (srfi srfi-19))
  1007. (define (date) (date->string (current-date)))
  1008. (define-syntax %date (identifier-syntax (date)))
  1009. (define *compilation-date* %date)
  1010. @end example
  1011. It works at a REPL because the expressions are evaluated one-by-one, in order,
  1012. but if placed in a file, the expressions are expanded one-by-one, but not
  1013. evaluated until the compiled file is loaded.
  1014. The fix is to use @code{eval-when}.
  1015. @example
  1016. ;; correct: using eval-when
  1017. (use-modules (srfi srfi-19))
  1018. (eval-when (expand load eval)
  1019. (define (date) (date->string (current-date))))
  1020. (define-syntax %date (identifier-syntax (date)))
  1021. (define *compilation-date* %date)
  1022. @end example
  1023. @deffn {Syntax} eval-when conditions exp...
  1024. Evaluate @var{exp...} under the given @var{conditions}. Valid
  1025. conditions include:
  1026. @table @code
  1027. @item expand
  1028. Evaluate during macro expansion, whether compiling or not.
  1029. @item load
  1030. Evaluate during the evaluation phase of compiled code, e.g. when loading
  1031. a compiled module or running compiled code at the REPL.
  1032. @item eval
  1033. Evaluate during the evaluation phase of non-compiled code.
  1034. @item compile
  1035. Evaluate during macro expansion, but only when compiling.
  1036. @end table
  1037. In other words, when using the primitive evaluator, @code{eval-when}
  1038. expressions with @code{expand} are run during macro expansion, and those
  1039. with @code{eval} are run during the evaluation phase.
  1040. When using the compiler, @code{eval-when} expressions with either
  1041. @code{expand} or @code{compile} are run during macro expansion, and
  1042. those with @code{load} are run during the evaluation phase.
  1043. When in doubt, use the three conditions @code{(expand load eval)}, as in
  1044. the example above. Other uses of @code{eval-when} may void your
  1045. warranty or poison your cat.
  1046. @end deffn
  1047. @node Macro Expansion
  1048. @subsection Macro Expansion
  1049. Usually, macros are expanded on behalf of the user as needed. Macro
  1050. expansion is an integral part of @code{eval} and @code{compile}. Users
  1051. can also expand macros at the REPL prompt via the @code{expand} REPL
  1052. command; @xref{Compile Commands}.
  1053. Macros can also be expanded programmatically, via @code{macroexpand},
  1054. but the details get a bit hairy for two reasons.
  1055. The first complication is that the result of macro-expansion isn't
  1056. Scheme: it's Tree-IL, Guile's high-level intermediate language.
  1057. @xref{Tree-IL}. As ``hygienic macros'' can produce identifiers that are
  1058. distinct but have the same name, the output format needs to be able to
  1059. represent distinctions between variable identities and names. Again,
  1060. @xref{Tree-IL}, for all the details. The easiest thing is to just run
  1061. @code{tree-il->scheme} on the result of macro-expansion:
  1062. @lisp
  1063. (macroexpand '(+ 1 2))
  1064. @result{}
  1065. #<tree-il (call (toplevel +) (const 1) (const 2))>
  1066. (use-modules (language tree-il))
  1067. (tree-il->scheme (macroexpand '(+ 1 2)))
  1068. @result{}
  1069. (+ 1 2)
  1070. @end lisp
  1071. The second complication involves @code{eval-when}. As an example, what
  1072. would it mean to macro-expand the definition of a macro?
  1073. @lisp
  1074. (macroexpand '(define-syntax qux (identifier-syntax 'bar)))
  1075. @result{}
  1076. ?
  1077. @end lisp
  1078. The answer is that it depends who is macro-expanding, and why. Do you
  1079. define the macro in the current environment? Residualize a macro
  1080. definition? Both? Neither? The default is to expand in ``eval'' mode,
  1081. which means an @code{eval-when} clauses will only proceed when
  1082. @code{eval} (or @code{expand}) is in its condition set. Top-level
  1083. macros will be @code{eval}'d in the top-level environment.
  1084. In this way @code{(macroexpand @var{foo})} is equivalent to
  1085. @code{(macroexpand @var{foo} 'e '(eval))}. The second argument is the
  1086. mode (@code{'e} for ``eval'') and the third is the
  1087. eval-syntax-expanders-when parameter (only @code{eval} in this default
  1088. setting).
  1089. But if you are compiling the macro definition, probably you want to
  1090. reify the macro definition itself. In that case you pass @code{'c} as
  1091. the second argument to @code{macroexpand}. But probably you want the
  1092. macro definition to be present at compile time as well, so you pass
  1093. @code{'(compile load eval)} as the @var{esew} parameter. In fact
  1094. @code{(compile @var{foo} #:to 'tree-il)} is entirely equivalent to
  1095. @code{(macroexpand @var{foo} 'c '(compile load eval))}; @xref{The Scheme
  1096. Compiler}.
  1097. It's a terrible interface; we know. The macroexpander is somewhat
  1098. tricksy regarding modes, so unless you are building a macro-expanding
  1099. tool, we suggest to avoid invoking it directly.
  1100. @node Hygiene and the Top-Level
  1101. @subsection Hygiene and the Top-Level
  1102. Consider the following macro.
  1103. @lisp
  1104. (define-syntax-rule (defconst name val)
  1105. (begin
  1106. (define t val)
  1107. (define-syntax-rule (name) t)))
  1108. @end lisp
  1109. If we use it to make a couple of bindings:
  1110. @lisp
  1111. (defconst foo 42)
  1112. (defconst bar 37)
  1113. @end lisp
  1114. The expansion would look something like this:
  1115. @lisp
  1116. (begin
  1117. (define t 42)
  1118. (define-syntax-rule (foo) t))
  1119. (begin
  1120. (define t 37)
  1121. (define-syntax-rule (bar) t))
  1122. @end lisp
  1123. As the two @code{t} bindings were introduced by the macro, they should
  1124. be introduced hygienically -- and indeed they are, inside a lexical
  1125. contour (a @code{let} or some other lexical scope). The @code{t}
  1126. reference in @code{foo} is distinct to the reference in @code{bar}.
  1127. At the top-level things are more complicated. Before Guile 2.2, a use
  1128. of @code{defconst} at the top-level would not introduce a fresh binding
  1129. for @code{t}. This was consistent with a weaselly interpretation of the
  1130. Scheme standard, in which all possible bindings may be assumed to exist,
  1131. at the top-level, and in which we merely take advantage of toplevel
  1132. @code{define} of an existing binding being equivalent to @code{set!}.
  1133. But it's not a good reason.
  1134. The solution is to create fresh names for all bindings introduced by
  1135. macros -- not just bindings in lexical contours, but also bindings
  1136. introduced at the top-level.
  1137. However, the obvious strategy of just giving random names to introduced
  1138. toplevel identifiers poses a problem for separate compilation. Consider
  1139. without loss of generality a @code{defconst} of @code{foo} in module
  1140. @code{a} that introduces the fresh top-level name @code{t-1}. If we
  1141. then compile a module @code{b} that uses @code{foo}, there is now a
  1142. reference to @code{t-1} in module @code{b}. If module @code{a} is then
  1143. expanded again, for whatever reason, for example in a simple
  1144. recompilation, the introduced @code{t} gets a fresh name; say,
  1145. @code{t-2}. Now module @code{b} has broken because module @code{a} no
  1146. longer has a binding for @code{t-1}.
  1147. If introduced top-level identifiers ``escape'' a module, in whatever
  1148. way, they then form part of the binary interface (ABI) of a module. It
  1149. is unacceptable from an engineering point of view to allow the ABI to
  1150. change randomly. (It also poses practical problems in meeting the
  1151. recompilation conditions of the Lesser GPL license, for such modules.)
  1152. For this reason many people prefer to never use identifier-introducing
  1153. macros at the top-level, instead making those macros receive the names
  1154. for their introduced identifiers as part of their arguments, or to
  1155. construct them programmatically and use @code{datum->syntax}. But this
  1156. approach requires omniscience as to the implementation of all macros one
  1157. might use, and also limits the expressive power of Scheme macros.
  1158. There is no perfect solution to this issue. Guile does a terrible thing
  1159. here. When it goes to introduce a top-level identifier, Guile gives the
  1160. identifier a pseudo-fresh name: a name that depends on the hash of the
  1161. source expression in which the name occurs. The result in this case is
  1162. that the introduced definitions expand as:
  1163. @lisp
  1164. (begin
  1165. (define t-1dc5e42de7c1050c 42)
  1166. (define-syntax-rule (foo) t-1dc5e42de7c1050c))
  1167. (begin
  1168. (define t-10cb8ce9fdddd6e9 37)
  1169. (define-syntax-rule (bar) t-10cb8ce9fdddd6e9))
  1170. @end lisp
  1171. However, note that as the hash depends solely on the expression
  1172. introducing the definition, we also have:
  1173. @lisp
  1174. (defconst baz 42)
  1175. @result{} (begin
  1176. (define t-1dc5e42de7c1050c 42)
  1177. (define-syntax-rule (baz) t-1dc5e42de7c1050c))
  1178. @end lisp
  1179. Note that the introduced binding has the same name! This is because the
  1180. source expression, @code{(define t 42)}, was the same. Probably you
  1181. will never see an error in this area, but it is important to understand
  1182. the components of the interface of a module, and that interface may
  1183. include macro-introduced identifiers.
  1184. @node Internal Macros
  1185. @subsection Internal Macros
  1186. @deffn {Scheme Procedure} make-syntax-transformer name type binding
  1187. Construct a syntax transformer object. This is part of Guile's low-level support
  1188. for syntax-case.
  1189. @end deffn
  1190. @deffn {Scheme Procedure} macro? obj
  1191. @deffnx {C Function} scm_macro_p (obj)
  1192. Return @code{#t} if @var{obj} is a syntax transformer, or @code{#f}
  1193. otherwise.
  1194. Note that it's a bit difficult to actually get a macro as a first-class object;
  1195. simply naming it (like @code{case}) will produce a syntax error. But it is
  1196. possible to get these objects using @code{module-ref}:
  1197. @example
  1198. (macro? (module-ref (current-module) 'case))
  1199. @result{} #t
  1200. @end example
  1201. @end deffn
  1202. @deffn {Scheme Procedure} macro-type m
  1203. @deffnx {C Function} scm_macro_type (m)
  1204. Return the @var{type} that was given when @var{m} was constructed, via
  1205. @code{make-syntax-transformer}.
  1206. @end deffn
  1207. @deffn {Scheme Procedure} macro-name m
  1208. @deffnx {C Function} scm_macro_name (m)
  1209. Return the name of the macro @var{m}.
  1210. @end deffn
  1211. @deffn {Scheme Procedure} macro-binding m
  1212. @deffnx {C Function} scm_macro_binding (m)
  1213. Return the binding of the macro @var{m}.
  1214. @end deffn
  1215. @deffn {Scheme Procedure} macro-transformer m
  1216. @deffnx {C Function} scm_macro_transformer (m)
  1217. Return the transformer of the macro @var{m}. This will return a procedure, for
  1218. which one may ask the docstring. That's the whole reason this section is
  1219. documented. Actually a part of the result of @code{macro-binding}.
  1220. @end deffn
  1221. @c Local Variables:
  1222. @c TeX-master: "guile.texi"
  1223. @c End: