commit 178c1502056aa29225b2e63af1200a4f13523904
parent c0b3b4b465684f41d25a103af674b8d1e58fbe1e
Author: Greg Hendershott <greghendershott@gmail.com>
Date: Thu, 15 Aug 2013 14:27:16 -0400
Add more rationale for syntax parameters.
As suggested by @stchang in issue #1.
Diffstat:
6 files changed, 22 insertions(+), 18 deletions(-)
diff --git a/Robust_macros__syntax-parse.html b/Robust_macros__syntax-parse.html
@@ -22,7 +22,7 @@ classes". There are predefined syntax classes, plus we can define our
own.</p><h4>7.3<tt> </tt><a name="(part._.Using_syntax_parse)"></a>Using <span class="RktSym">syntax/parse</span></h4><p>November 1, 2012: So here’s the deal. After writing everything up to
this point, I sat down to re-read the documentation for
<span class="RktSym">syntax/parse</span>. It was...very understandable. I didn’t feel
-confused.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktSym"><span</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">style=</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym">accent:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Kenau-Reeves"</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._~3e%29%29" class="RktValLink" data-pltdoc="x">></a></span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym">Whoa.</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym"></span></span><span class="RktMeta"></span></td></tr></table></blockquote><p>Why? The documentation is written very well. Also, everything up to
+confused.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktSym"><span</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">style=</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym">accent:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Keanu-Reeves"</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._~3e%29%29" class="RktValLink" data-pltdoc="x">></a></span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym">Whoa.</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym"></span></span><span class="RktMeta"></span></td></tr></table></blockquote><p>Why? The documentation is written very well. Also, everything up to
this point prepared me to appreciate what <span class="RktSym">syntax/parse</span> does,
and why. That leaves the "how" of using it, which seems pretty
straightforward, so far.</p><p>This might well be a temporary state of me "not knowing what I don’t
diff --git a/Syntax_parameters.html b/Syntax_parameters.html
@@ -10,9 +10,9 @@ Bindings</a>, has a good explanation and example. Basically, syntax
has "marks" to preserve lexical scope. This makes your macro behave
like a normal function, for lexical scoping.</p><p>If a normal function defines a variable named <span class="RktSym">x</span>, it won’t
conflict with a variable named <span class="RktSym">x</span> in an outer scope:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29" class="RktStxLink" data-pltdoc="x">let</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktVal">"outer"</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29" class="RktStxLink" data-pltdoc="x">let</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktVal">"inner"</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"The inner `x' is ~s\n"</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"The outer `x' is ~s\n"</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><table cellspacing="0"><tr><td><p><span class="RktOut">The inner `x' is "inner"</span></p></td></tr><tr><td><p><span class="RktOut">The outer `x' is "outer"</span></p></td></tr></table></td></tr></table></blockquote><p>When our macros also respect lexical scoping, it’s easier to write
-reliable macros that behave predictably.</p><p>So that’s wonderful default behavior. But <span style="font-style: italic">sometimes</span> we want
-to introduce a magic variable on purpose—<wbr></wbr>such as <span class="RktSym">it</span> for
-<span class="RktSym">aif</span>.</p><p>The way to do this is with a "syntax parameter", using
+reliable macros that behave predictably.</p><p>So that’s wonderful default behavior. But sometimes we want to
+introduce a magic variable on purpose—<wbr></wbr>such as <span class="RktSym">it</span> for
+<span class="RktSym">aif</span>.</p><p>There’s a bad way to do this and a good way.</p><p>The bad way is to use <span class="RktSym"><a href="http://docs.racket-lang.org/reference/stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29" class="RktValLink" data-pltdoc="x">datum->syntax</a></span>, which is tricky to use correctly. <span class="refelem"><span class="refcolumn"><span class="refcontent">See <a href="http://www.schemeworkshop.org/2011/papers/Barzilay2011.pdf">Keeping it Clean with Syntax Parameters (PDF)</a>.</span></span></span></p><p>The good way is with a syntax parameter, using
<span class="RktSym"><a href="http://docs.racket-lang.org/reference/stxparam.html#%28form._%28%28lib._racket%2Fstxparam..rkt%29._define-syntax-parameter%29%29" class="RktStxLink" data-pltdoc="x">define-syntax-parameter</a></span> and
<span class="RktSym"><a href="http://docs.racket-lang.org/reference/stxparam.html#%28form._%28%28lib._racket%2Fstxparam..rkt%29._syntax-parameterize%29%29" class="RktStxLink" data-pltdoc="x">syntax-parameterize</a></span>. You’re probably familiar with regular
parameters in Racket:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">current-foo</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/parameters.html#%28def._%28%28quote._~23~25kernel%29._make-parameter%29%29" class="RktValLink" data-pltdoc="x">make-parameter</a></span><span class="hspace"> </span><span class="RktVal">"some default value"</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">current-foo</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">"some default value"</span></p></td></tr><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/parameters.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%29%29" class="RktStxLink" data-pltdoc="x">parameterize</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">current-foo</span><span class="hspace"> </span><span class="RktVal">"I have a new value, for now"</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">current-foo</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><p><span class="RktRes">"I have a new value, for now"</span></p></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">current-foo</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">"some default value"</span></p></td></tr></table></blockquote><p>That’s a normal parameter. The syntax variation works similarly. The
diff --git a/Transform_.html b/Transform_.html
@@ -17,8 +17,8 @@ string literal. How about returning <span class="RktPn">(</span><span class="Rkt
<span class="RktPn">(</span><span class="RktSym">say-hi</span><span class="RktPn">)</span>, and sees it has a transformer function for that. It
calls our function with the old syntax, and we return the new syntax,
which is used to evaluate and run our program.</p><h4>3.2<tt> </tt><a name="(part._.What_s_the_input_)"></a>What’s the input?</h4><p>Our examples so far have ignored the input syntax and output some
-fixed syntax. But typically we will want to transform in the input
-syntax into somehing else.</p><p>Let’s start by looking closely at what the input actually <span style="font-style: italic">is</span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define-syntax%29%29" class="RktStxLink" data-pltdoc="x">define-syntax</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktRdr">#'</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29" class="RktValLink" data-pltdoc="x">void</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">+</span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktOut">#<syntax:10:0 (show-me (quote (+ 1 2)))></span></p></td></tr></table></blockquote><p>The <span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="stt"> </span><span class="RktSym">stx</span><span class="RktPn">)</span> shows what our transformer is given: a syntax
+fixed syntax. But typically we will want to transform the input syntax
+into something else.</p><p>Let’s start by looking closely at what the input actually <span style="font-style: italic">is</span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define-syntax%29%29" class="RktStxLink" data-pltdoc="x">define-syntax</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktRdr">#'</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29" class="RktValLink" data-pltdoc="x">void</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">+</span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktOut">#<syntax:10:0 (show-me (quote (+ 1 2)))></span></p></td></tr></table></blockquote><p>The <span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="stt"> </span><span class="RktSym">stx</span><span class="RktPn">)</span> shows what our transformer is given: a syntax
object.</p><p>A syntax object consists of several things. The first part is the
S-expression representing the code, such as <span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">+</span><span class="stt"> </span><span class="RktVal">1</span><span class="stt"> </span><span class="RktVal">2</span><span class="RktVal">)</span>.</p><p>Racket syntax is also decorated with some interesting information such
as the source file, line number, and column. Finally, it has
diff --git a/all.html b/all.html
@@ -1,6 +1,6 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8" /><title>Fear of Macros</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default" /><link rel="stylesheet" type="text/css" href="racket.css" title="default" /><link rel="stylesheet" type="text/css" href="scribble-style.css" title="default" /><link rel="stylesheet" type="text/css" href="gh.css" title="default" /><script type="text/javascript" src="scribble-common.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--><meta name="keywords" content="Racket,macros,Scheme"><meta name="description" content="Practical Racket macros"><meta name="author" content="Greg Hendershott"><meta name="charset" content="utf-8"><link href='http://fonts.googleapis.com/css?family=Fenix' rel='stylesheet' type='text/css'><script type="text/javascript">var _gaq = _gaq || [];_gaq.push(['_setAccount', 'UA-29709446-1']);_gaq.push(['_setDomainName', 'greghendershott.com']);_gaq.push(['_trackPageview']);(function() {var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);})();</script></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist" style="margin-bottom: 1em;"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="" class="tocviewselflink" data-pltdoc="x">Fear of Macros</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="#%28part._.Preface%29" class="tocviewlink" data-pltdoc="x">Preface</a></td></tr><tr><td align="right">2 </td><td><a href="#%28part._.Our_plan_of_attack%29" class="tocviewlink" data-pltdoc="x">Our plan of attack</a></td></tr><tr><td align="right">3 </td><td><a href="#%28part._.Transform_%29" class="tocviewlink" data-pltdoc="x">Transform!</a></td></tr><tr><td align="right">4 </td><td><a href="#%28part._pattern-matching%29" class="tocviewlink" data-pltdoc="x">Pattern matching:<span class="mywbr"> </span> syntax-<wbr></wbr>case and syntax-<wbr></wbr>rules</a></td></tr><tr><td align="right">5 </td><td><a href="#%28part._.Syntax_parameters%29" class="tocviewlink" data-pltdoc="x">Syntax parameters</a></td></tr><tr><td align="right">6 </td><td><a href="#%28part._.What_s_the_point_of_splicing-let_%29" class="tocviewlink" data-pltdoc="x">What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-<wbr></wbr>let</span></span>?</a></td></tr><tr><td align="right">7 </td><td><a href="#%28part._.Robust_macros__syntax-parse%29" class="tocviewlink" data-pltdoc="x">Robust macros:<span class="mywbr"> </span> syntax-<wbr></wbr>parse</a></td></tr><tr><td align="right">8 </td><td><a href="#%28part._.References_and_.Acknowledgments%29" class="tocviewlink" data-pltdoc="x">References and Acknowledgments</a></td></tr><tr><td align="right">9 </td><td><a href="#%28part._.Epilogue%29" class="tocviewlink" data-pltdoc="x">Epilogue</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">1<tt> </tt></span><a href="#(part._.Preface)" class="tocsubseclink" data-pltdoc="x">Preface</a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#(part._.Our_plan_of_attack)" class="tocsubseclink" data-pltdoc="x">Our plan of attack</a></td></tr><tr><td><span class="tocsublinknumber">3<tt> </tt></span><a href="#(part._.Transform_)" class="tocsubseclink" data-pltdoc="x">Transform!</a></td></tr><tr><td><span class="tocsublinknumber">3.1<tt> </tt></span><a href="#(part._.What_is_a_syntax_transformer_)" class="tocsubseclink" data-pltdoc="x">What is a syntax transformer?</a></td></tr><tr><td><span class="tocsublinknumber">3.2<tt> </tt></span><a href="#(part._.What_s_the_input_)" class="tocsubseclink" data-pltdoc="x">What’s the input?</a></td></tr><tr><td><span class="tocsublinknumber">3.3<tt> </tt></span><a href="#(part._.Actually_transforming_the_input)" class="tocsubseclink" data-pltdoc="x">Actually transforming the input</a></td></tr><tr><td><span class="tocsublinknumber">3.4<tt> </tt></span><a href="#(part._.Compile_time_vs__run_time)" class="tocsubseclink" data-pltdoc="x">Compile time vs. run time</a></td></tr><tr><td><span class="tocsublinknumber">3.5<tt> </tt></span><a href="#(part._begin-for-syntax)" class="tocsubseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">begin-<wbr></wbr>for-<wbr></wbr>syntax</span></span></a></td></tr><tr><td><span class="tocsublinknumber">4<tt> </tt></span><a href="#(part._pattern-matching)" class="tocsubseclink" data-pltdoc="x">Pattern matching:<span class="mywbr"> </span> syntax-<wbr></wbr>case and syntax-<wbr></wbr>rules</a></td></tr><tr><td><span class="tocsublinknumber">4.1<tt> </tt></span><a href="#(part._.Pattern_variable_vs__template---fight_)" class="tocsubseclink" data-pltdoc="x">Pattern variable vs. template—<wbr></wbr>fight!</a></td></tr><tr><td><span class="tocsublinknumber">4.1.1<tt> </tt></span><a href="#(part._with-syntax)" class="tocsubseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">with-<wbr></wbr>syntax</span></span></a></td></tr><tr><td><span class="tocsublinknumber">4.1.2<tt> </tt></span><a href="#(part._with-syntax_)" class="tocsubseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">with-<wbr></wbr>syntax*</span></span></a></td></tr><tr><td><span class="tocsublinknumber">4.1.3<tt> </tt></span><a href="#(part._format-id)" class="tocsubseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">format-<wbr></wbr>id</span></span></a></td></tr><tr><td><span class="tocsublinknumber">4.1.4<tt> </tt></span><a href="#(part._.Another_example)" class="tocsubseclink" data-pltdoc="x">Another example</a></td></tr><tr><td><span class="tocsublinknumber">4.2<tt> </tt></span><a href="#(part._.Making_our_own_struct)" class="tocsubseclink" data-pltdoc="x">Making our own <span class="RktSym"><span class="RktStxLink">struct</span></span></a></td></tr><tr><td><span class="tocsublinknumber">4.3<tt> </tt></span><a href="#(part._hash..refs)" class="tocsubseclink" data-pltdoc="x">Using dot notation for nested hash lookups</a></td></tr><tr><td><span class="tocsublinknumber">5<tt> </tt></span><a href="#(part._.Syntax_parameters)" class="tocsubseclink" data-pltdoc="x">Syntax parameters</a></td></tr><tr><td><span class="tocsublinknumber">6<tt> </tt></span><a href="#(part._.What_s_the_point_of_splicing-let_)" class="tocsubseclink" data-pltdoc="x">What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-<wbr></wbr>let</span></span>?</a></td></tr><tr><td><span class="tocsublinknumber">7<tt> </tt></span><a href="#(part._.Robust_macros__syntax-parse)" class="tocsubseclink" data-pltdoc="x">Robust macros:<span class="mywbr"> </span> syntax-<wbr></wbr>parse</a></td></tr><tr><td><span class="tocsublinknumber">7.1<tt> </tt></span><a href="#(part._.Error-handling_strategies_for_functions)" class="tocsubseclink" data-pltdoc="x">Error-<wbr></wbr>handling strategies for functions</a></td></tr><tr><td><span class="tocsublinknumber">7.2<tt> </tt></span><a href="#(part._.Error-handling_strategies_for_macros)" class="tocsubseclink" data-pltdoc="x">Error-<wbr></wbr>handling strategies for macros</a></td></tr><tr><td><span class="tocsublinknumber">7.3<tt> </tt></span><a href="#(part._.Using_syntax_parse)" class="tocsubseclink" data-pltdoc="x">Using <span class="RktSym">syntax/<span class="mywbr"> </span>parse</span></a></td></tr><tr><td><span class="tocsublinknumber">8<tt> </tt></span><a href="#(part._.References_and_.Acknowledgments)" class="tocsubseclink" data-pltdoc="x">References and Acknowledgments</a></td></tr><tr><td><span class="tocsublinknumber">9<tt> </tt></span><a href="#(part._.Epilogue)" class="tocsubseclink" data-pltdoc="x">Epilogue</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><h2><a name="(part._.Fear_of_.Macros)"></a>Fear of Macros</h2><div class="SAuthorListBox"><span class="SAuthorList"><p class="author"><a href="http://www.greghendershott.com">Greg Hendershott</a></p></span></div><p><div class="SIntrapara"></div><div class="SIntrapara"><img src="fear-of-macros.jpg" alt="" />
-</div><div class="SIntrapara"><span class="Smaller">Copyright (c) 2012-2013 by Greg Hendershott. All rights reserved.</span></div><div class="SIntrapara"><span class="Smaller">Last updated 2013-08-15T13:36:35</span></div><div class="SIntrapara">Feedback and corrections are <a href="https://github.com/greghendershott/fear-of-macros/issues">welcome here</a>.</div></p><p>Contents:</p><table cellspacing="0"><tr><td><p><span class="hspace"> </span><a href="#%28part._.Preface%29" class="toptoclink" data-pltdoc="x">1<span class="hspace"> </span>Preface</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Our_plan_of_attack%29" class="toptoclink" data-pltdoc="x">2<span class="hspace"> </span>Our plan of attack</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Transform_%29" class="toptoclink" data-pltdoc="x">3<span class="hspace"> </span>Transform!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.What_is_a_syntax_transformer_%29" class="toclink" data-pltdoc="x">3.1<span class="hspace"> </span>What is a syntax transformer?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.What_s_the_input_%29" class="toclink" data-pltdoc="x">3.2<span class="hspace"> </span>What’s the input?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Actually_transforming_the_input%29" class="toclink" data-pltdoc="x">3.3<span class="hspace"> </span>Actually transforming the input</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Compile_time_vs__run_time%29" class="toclink" data-pltdoc="x">3.4<span class="hspace"> </span>Compile time vs. run time</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._begin-for-syntax%29" class="toclink" data-pltdoc="x">3.5<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">begin-for-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._pattern-matching%29" class="toptoclink" data-pltdoc="x">4<span class="hspace"> </span>Pattern matching: syntax-case and syntax-rules</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Pattern_variable_vs__template---fight_%29" class="toclink" data-pltdoc="x">4.1<span class="hspace"> </span>Pattern variable vs. template—<wbr></wbr>fight!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._with-syntax%29" class="toclink" data-pltdoc="x">4.1.1<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._with-syntax_%29" class="toclink" data-pltdoc="x">4.1.2<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax*</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._format-id%29" class="toclink" data-pltdoc="x">4.1.3<span class="hspace"> </span><span class="RktSym"><span class="RktValLink">format-id</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Another_example%29" class="toclink" data-pltdoc="x">4.1.4<span class="hspace"> </span>Another example</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Making_our_own_struct%29" class="toclink" data-pltdoc="x">4.2<span class="hspace"> </span>Making our own <span class="RktSym"><span class="RktStxLink">struct</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._hash..refs%29" class="toclink" data-pltdoc="x">4.3<span class="hspace"> </span>Using dot notation for nested hash lookups</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Syntax_parameters%29" class="toptoclink" data-pltdoc="x">5<span class="hspace"> </span>Syntax parameters</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.What_s_the_point_of_splicing-let_%29" class="toptoclink" data-pltdoc="x">6<span class="hspace"> </span>What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-let</span></span>?</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Robust_macros__syntax-parse%29" class="toptoclink" data-pltdoc="x">7<span class="hspace"> </span>Robust macros: syntax-parse</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Error-handling_strategies_for_functions%29" class="toclink" data-pltdoc="x">7.1<span class="hspace"> </span>Error-handling strategies for functions</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Error-handling_strategies_for_macros%29" class="toclink" data-pltdoc="x">7.2<span class="hspace"> </span>Error-handling strategies for macros</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Using_syntax_parse%29" class="toclink" data-pltdoc="x">7.3<span class="hspace"> </span>Using <span class="RktSym">syntax/parse</span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.References_and_.Acknowledgments%29" class="toptoclink" data-pltdoc="x">8<span class="hspace"> </span>References and Acknowledgments</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Epilogue%29" class="toptoclink" data-pltdoc="x">9<span class="hspace"> </span>Epilogue</a></p></td></tr></table><h3>1<tt> </tt><a name="(part._.Preface)"></a>Preface</h3><p>I learned Racket after 25 years of mostly using C and C++.</p><p>Some psychic whiplash resulted.</p><p>"All the parentheses" was actually not a big deal. Instead, the first
+</div><div class="SIntrapara"><span class="Smaller">Copyright (c) 2012-2013 by Greg Hendershott. All rights reserved.</span></div><div class="SIntrapara"><span class="Smaller">Last updated 2013-08-15T14:15:12</span></div><div class="SIntrapara">Feedback and corrections are <a href="https://github.com/greghendershott/fear-of-macros/issues">welcome here</a>.</div></p><p>Contents:</p><table cellspacing="0"><tr><td><p><span class="hspace"> </span><a href="#%28part._.Preface%29" class="toptoclink" data-pltdoc="x">1<span class="hspace"> </span>Preface</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Our_plan_of_attack%29" class="toptoclink" data-pltdoc="x">2<span class="hspace"> </span>Our plan of attack</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Transform_%29" class="toptoclink" data-pltdoc="x">3<span class="hspace"> </span>Transform!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.What_is_a_syntax_transformer_%29" class="toclink" data-pltdoc="x">3.1<span class="hspace"> </span>What is a syntax transformer?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.What_s_the_input_%29" class="toclink" data-pltdoc="x">3.2<span class="hspace"> </span>What’s the input?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Actually_transforming_the_input%29" class="toclink" data-pltdoc="x">3.3<span class="hspace"> </span>Actually transforming the input</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Compile_time_vs__run_time%29" class="toclink" data-pltdoc="x">3.4<span class="hspace"> </span>Compile time vs. run time</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._begin-for-syntax%29" class="toclink" data-pltdoc="x">3.5<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">begin-for-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._pattern-matching%29" class="toptoclink" data-pltdoc="x">4<span class="hspace"> </span>Pattern matching: syntax-case and syntax-rules</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Pattern_variable_vs__template---fight_%29" class="toclink" data-pltdoc="x">4.1<span class="hspace"> </span>Pattern variable vs. template—<wbr></wbr>fight!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._with-syntax%29" class="toclink" data-pltdoc="x">4.1.1<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._with-syntax_%29" class="toclink" data-pltdoc="x">4.1.2<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax*</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._format-id%29" class="toclink" data-pltdoc="x">4.1.3<span class="hspace"> </span><span class="RktSym"><span class="RktValLink">format-id</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Another_example%29" class="toclink" data-pltdoc="x">4.1.4<span class="hspace"> </span>Another example</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Making_our_own_struct%29" class="toclink" data-pltdoc="x">4.2<span class="hspace"> </span>Making our own <span class="RktSym"><span class="RktStxLink">struct</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._hash..refs%29" class="toclink" data-pltdoc="x">4.3<span class="hspace"> </span>Using dot notation for nested hash lookups</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Syntax_parameters%29" class="toptoclink" data-pltdoc="x">5<span class="hspace"> </span>Syntax parameters</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.What_s_the_point_of_splicing-let_%29" class="toptoclink" data-pltdoc="x">6<span class="hspace"> </span>What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-let</span></span>?</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Robust_macros__syntax-parse%29" class="toptoclink" data-pltdoc="x">7<span class="hspace"> </span>Robust macros: syntax-parse</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Error-handling_strategies_for_functions%29" class="toclink" data-pltdoc="x">7.1<span class="hspace"> </span>Error-handling strategies for functions</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Error-handling_strategies_for_macros%29" class="toclink" data-pltdoc="x">7.2<span class="hspace"> </span>Error-handling strategies for macros</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Using_syntax_parse%29" class="toclink" data-pltdoc="x">7.3<span class="hspace"> </span>Using <span class="RktSym">syntax/parse</span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.References_and_.Acknowledgments%29" class="toptoclink" data-pltdoc="x">8<span class="hspace"> </span>References and Acknowledgments</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="#%28part._.Epilogue%29" class="toptoclink" data-pltdoc="x">9<span class="hspace"> </span>Epilogue</a></p></td></tr></table><h3>1<tt> </tt><a name="(part._.Preface)"></a>Preface</h3><p>I learned Racket after 25 years of mostly using C and C++.</p><p>Some psychic whiplash resulted.</p><p>"All the parentheses" was actually not a big deal. Instead, the first
mind warp was functional programming. Before long I wrapped my brain
around it, and went on to become comfortable and effective with many
other aspects and features of Racket.</p><p>But two final frontiers remained: Macros and continuations.</p><p>I found that simple macros were easy and understandable, plus there
@@ -60,8 +60,8 @@ string literal. How about returning <span class="RktPn">(</span><span class="Rkt
<span class="RktPn">(</span><span class="RktSym">say-hi</span><span class="RktPn">)</span>, and sees it has a transformer function for that. It
calls our function with the old syntax, and we return the new syntax,
which is used to evaluate and run our program.</p><h4>3.2<tt> </tt><a name="(part._.What_s_the_input_)"></a>What’s the input?</h4><p>Our examples so far have ignored the input syntax and output some
-fixed syntax. But typically we will want to transform in the input
-syntax into somehing else.</p><p>Let’s start by looking closely at what the input actually <span style="font-style: italic">is</span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define-syntax%29%29" class="RktStxLink" data-pltdoc="x">define-syntax</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktRdr">#'</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29" class="RktValLink" data-pltdoc="x">void</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">+</span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktOut">#<syntax:10:0 (show-me (quote (+ 1 2)))></span></p></td></tr></table></blockquote><p>The <span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="stt"> </span><span class="RktSym">stx</span><span class="RktPn">)</span> shows what our transformer is given: a syntax
+fixed syntax. But typically we will want to transform the input syntax
+into something else.</p><p>Let’s start by looking closely at what the input actually <span style="font-style: italic">is</span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define-syntax%29%29" class="RktStxLink" data-pltdoc="x">define-syntax</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="hspace"> </span><span class="RktSym">stx</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktRdr">#'</span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29" class="RktValLink" data-pltdoc="x">void</a></span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">show-me</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">+</span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktOut">#<syntax:10:0 (show-me (quote (+ 1 2)))></span></p></td></tr></table></blockquote><p>The <span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._print%29%29" class="RktValLink" data-pltdoc="x">print</a></span><span class="stt"> </span><span class="RktSym">stx</span><span class="RktPn">)</span> shows what our transformer is given: a syntax
object.</p><p>A syntax object consists of several things. The first part is the
S-expression representing the code, such as <span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">+</span><span class="stt"> </span><span class="RktVal">1</span><span class="stt"> </span><span class="RktVal">2</span><span class="RktVal">)</span>.</p><p>Racket syntax is also decorated with some interesting information such
as the source file, line number, and column. Finally, it has
@@ -272,9 +272,9 @@ Bindings</a>, has a good explanation and example. Basically, syntax
has "marks" to preserve lexical scope. This makes your macro behave
like a normal function, for lexical scoping.</p><p>If a normal function defines a variable named <span class="RktSym">x</span>, it won’t
conflict with a variable named <span class="RktSym">x</span> in an outer scope:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29" class="RktStxLink" data-pltdoc="x">let</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktVal">"outer"</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29" class="RktStxLink" data-pltdoc="x">let</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktVal">"inner"</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"The inner `x' is ~s\n"</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"The outer `x' is ~s\n"</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><table cellspacing="0"><tr><td><p><span class="RktOut">The inner `x' is "inner"</span></p></td></tr><tr><td><p><span class="RktOut">The outer `x' is "outer"</span></p></td></tr></table></td></tr></table></blockquote><p>When our macros also respect lexical scoping, it’s easier to write
-reliable macros that behave predictably.</p><p>So that’s wonderful default behavior. But <span style="font-style: italic">sometimes</span> we want
-to introduce a magic variable on purpose—<wbr></wbr>such as <span class="RktSym">it</span> for
-<span class="RktSym">aif</span>.</p><p>The way to do this is with a "syntax parameter", using
+reliable macros that behave predictably.</p><p>So that’s wonderful default behavior. But sometimes we want to
+introduce a magic variable on purpose—<wbr></wbr>such as <span class="RktSym">it</span> for
+<span class="RktSym">aif</span>.</p><p>There’s a bad way to do this and a good way.</p><p>The bad way is to use <span class="RktSym"><a href="http://docs.racket-lang.org/reference/stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29" class="RktValLink" data-pltdoc="x">datum->syntax</a></span>, which is tricky to use correctly. <span class="refelem"><span class="refcolumn"><span class="refcontent">See <a href="http://www.schemeworkshop.org/2011/papers/Barzilay2011.pdf">Keeping it Clean with Syntax Parameters (PDF)</a>.</span></span></span></p><p>The good way is with a syntax parameter, using
<span class="RktSym"><a href="http://docs.racket-lang.org/reference/stxparam.html#%28form._%28%28lib._racket%2Fstxparam..rkt%29._define-syntax-parameter%29%29" class="RktStxLink" data-pltdoc="x">define-syntax-parameter</a></span> and
<span class="RktSym"><a href="http://docs.racket-lang.org/reference/stxparam.html#%28form._%28%28lib._racket%2Fstxparam..rkt%29._syntax-parameterize%29%29" class="RktStxLink" data-pltdoc="x">syntax-parameterize</a></span>. You’re probably familiar with regular
parameters in Racket:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktSym">current-foo</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/parameters.html#%28def._%28%28quote._~23~25kernel%29._make-parameter%29%29" class="RktValLink" data-pltdoc="x">make-parameter</a></span><span class="hspace"> </span><span class="RktVal">"some default value"</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">current-foo</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">"some default value"</span></p></td></tr><tr><td><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/parameters.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%29%29" class="RktStxLink" data-pltdoc="x">parameterize</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">current-foo</span><span class="hspace"> </span><span class="RktVal">"I have a new value, for now"</span><span class="RktPn">]</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPlain"><span class="hspace"> </span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">current-foo</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><p><span class="RktRes">"I have a new value, for now"</span></p></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">current-foo</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">"some default value"</span></p></td></tr></table></blockquote><p>That’s a normal parameter. The syntax variation works similarly. The
@@ -316,7 +316,7 @@ classes". There are predefined syntax classes, plus we can define our
own.</p><h4>7.3<tt> </tt><a name="(part._.Using_syntax_parse)"></a>Using <span class="RktSym">syntax/parse</span></h4><p>November 1, 2012: So here’s the deal. After writing everything up to
this point, I sat down to re-read the documentation for
<span class="RktSym">syntax/parse</span>. It was...very understandable. I didn’t feel
-confused.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktSym"><span</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">style=</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym">accent:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Kenau-Reeves"</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._~3e%29%29" class="RktValLink" data-pltdoc="x">></a></span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym">Whoa.</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym"></span></span><span class="RktMeta"></span></td></tr></table></blockquote><p>Why? The documentation is written very well. Also, everything up to
+confused.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktSym"><span</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">style=</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym">accent:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Keanu-Reeves"</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29" class="RktStxLink" data-pltdoc="x">'</a></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._~3e%29%29" class="RktValLink" data-pltdoc="x">></a></span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym">Whoa.</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktSym"></span></span><span class="RktMeta"></span></td></tr></table></blockquote><p>Why? The documentation is written very well. Also, everything up to
this point prepared me to appreciate what <span class="RktSym">syntax/parse</span> does,
and why. That leaves the "how" of using it, which seems pretty
straightforward, so far.</p><p>This might well be a temporary state of me "not knowing what I don’t
diff --git a/index.html b/index.html
@@ -1,3 +1,3 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8" /><title>Fear of Macros</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default" /><link rel="stylesheet" type="text/css" href="racket.css" title="default" /><link rel="stylesheet" type="text/css" href="scribble-style.css" title="default" /><link rel="stylesheet" type="text/css" href="gh.css" title="default" /><script type="text/javascript" src="scribble-common.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--><meta name="keywords" content="Racket,macros,Scheme"><meta name="description" content="Practical Racket macros"><meta name="author" content="Greg Hendershott"><meta name="charset" content="utf-8"><link href='http://fonts.googleapis.com/css?family=Fenix' rel='stylesheet' type='text/css'><script type="text/javascript">var _gaq = _gaq || [];_gaq.push(['_setAccount', 'UA-29709446-1']);_gaq.push(['_setDomainName', 'greghendershott.com']);_gaq.push(['_trackPageview']);(function() {var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);})();</script></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist" style="margin-bottom: 1em;"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="" class="tocviewselflink" data-pltdoc="x">Fear of Macros</a></td></tr></table></div><div class="tocviewsublistonly" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="Preface.html" class="tocviewlink" data-pltdoc="x">Preface</a></td></tr><tr><td align="right">2 </td><td><a href="Our_plan_of_attack.html" class="tocviewlink" data-pltdoc="x">Our plan of attack</a></td></tr><tr><td align="right">3 </td><td><a href="Transform_.html" class="tocviewlink" data-pltdoc="x">Transform!</a></td></tr><tr><td align="right">4 </td><td><a href="pattern-matching.html" class="tocviewlink" data-pltdoc="x">Pattern matching:<span class="mywbr"> </span> syntax-<wbr></wbr>case and syntax-<wbr></wbr>rules</a></td></tr><tr><td align="right">5 </td><td><a href="Syntax_parameters.html" class="tocviewlink" data-pltdoc="x">Syntax parameters</a></td></tr><tr><td align="right">6 </td><td><a href="What_s_the_point_of_splicing-let_.html" class="tocviewlink" data-pltdoc="x">What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-<wbr></wbr>let</span></span>?</a></td></tr><tr><td align="right">7 </td><td><a href="Robust_macros__syntax-parse.html" class="tocviewlink" data-pltdoc="x">Robust macros:<span class="mywbr"> </span> syntax-<wbr></wbr>parse</a></td></tr><tr><td align="right">8 </td><td><a href="References_and_Acknowledgments.html" class="tocviewlink" data-pltdoc="x">References and Acknowledgments</a></td></tr><tr><td align="right">9 </td><td><a href="Epilogue.html" class="tocviewlink" data-pltdoc="x">Epilogue</a></td></tr></table></div></div></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"> </span><span class="navright"> <span class="nonavigation">← prev</span> <span class="nonavigation">up</span> <a href="Preface.html" title="forward to "1 Preface"" data-pltdoc="x">next →</a></span> </div><h2><a name="(part._.Fear_of_.Macros)"></a>Fear of Macros</h2><div class="SAuthorListBox"><span class="SAuthorList"><p class="author"><a href="http://www.greghendershott.com">Greg Hendershott</a></p></span></div><p><div class="SIntrapara"></div><div class="SIntrapara"><img src="fear-of-macros.jpg" alt="" />
-</div><div class="SIntrapara"><span class="Smaller">Copyright (c) 2012-2013 by Greg Hendershott. All rights reserved.</span></div><div class="SIntrapara"><span class="Smaller">Last updated 2013-08-15T13:36:30</span></div><div class="SIntrapara">Feedback and corrections are <a href="https://github.com/greghendershott/fear-of-macros/issues">welcome here</a>.</div></p><p>Contents:</p><table cellspacing="0"><tr><td><p><span class="hspace"> </span><a href="Preface.html" class="toptoclink" data-pltdoc="x">1<span class="hspace"> </span>Preface</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Our_plan_of_attack.html" class="toptoclink" data-pltdoc="x">2<span class="hspace"> </span>Our plan of attack</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html" class="toptoclink" data-pltdoc="x">3<span class="hspace"> </span>Transform!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.What_is_a_syntax_transformer_%29" class="toclink" data-pltdoc="x">3.1<span class="hspace"> </span>What is a syntax transformer?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.What_s_the_input_%29" class="toclink" data-pltdoc="x">3.2<span class="hspace"> </span>What’s the input?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.Actually_transforming_the_input%29" class="toclink" data-pltdoc="x">3.3<span class="hspace"> </span>Actually transforming the input</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.Compile_time_vs__run_time%29" class="toclink" data-pltdoc="x">3.4<span class="hspace"> </span>Compile time vs. run time</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._begin-for-syntax%29" class="toclink" data-pltdoc="x">3.5<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">begin-for-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html" class="toptoclink" data-pltdoc="x">4<span class="hspace"> </span>Pattern matching: syntax-case and syntax-rules</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._.Pattern_variable_vs__template---fight_%29" class="toclink" data-pltdoc="x">4.1<span class="hspace"> </span>Pattern variable vs. template—<wbr></wbr>fight!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._with-syntax%29" class="toclink" data-pltdoc="x">4.1.1<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._with-syntax_%29" class="toclink" data-pltdoc="x">4.1.2<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax*</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._format-id%29" class="toclink" data-pltdoc="x">4.1.3<span class="hspace"> </span><span class="RktSym"><span class="RktValLink">format-id</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._.Another_example%29" class="toclink" data-pltdoc="x">4.1.4<span class="hspace"> </span>Another example</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._.Making_our_own_struct%29" class="toclink" data-pltdoc="x">4.2<span class="hspace"> </span>Making our own <span class="RktSym"><span class="RktStxLink">struct</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._hash..refs%29" class="toclink" data-pltdoc="x">4.3<span class="hspace"> </span>Using dot notation for nested hash lookups</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Syntax_parameters.html" class="toptoclink" data-pltdoc="x">5<span class="hspace"> </span>Syntax parameters</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="What_s_the_point_of_splicing-let_.html" class="toptoclink" data-pltdoc="x">6<span class="hspace"> </span>What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-let</span></span>?</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html" class="toptoclink" data-pltdoc="x">7<span class="hspace"> </span>Robust macros: syntax-parse</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html#%28part._.Error-handling_strategies_for_functions%29" class="toclink" data-pltdoc="x">7.1<span class="hspace"> </span>Error-handling strategies for functions</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html#%28part._.Error-handling_strategies_for_macros%29" class="toclink" data-pltdoc="x">7.2<span class="hspace"> </span>Error-handling strategies for macros</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html#%28part._.Using_syntax_parse%29" class="toclink" data-pltdoc="x">7.3<span class="hspace"> </span>Using <span class="RktSym">syntax/parse</span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="References_and_Acknowledgments.html" class="toptoclink" data-pltdoc="x">8<span class="hspace"> </span>References and Acknowledgments</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Epilogue.html" class="toptoclink" data-pltdoc="x">9<span class="hspace"> </span>Epilogue</a></p></td></tr></table><div class="navsetbottom"><span class="navleft"> </span><span class="navright"> <span class="nonavigation">← prev</span> <span class="nonavigation">up</span> <a href="Preface.html" title="forward to "1 Preface"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
-\ No newline at end of file
+</div><div class="SIntrapara"><span class="Smaller">Copyright (c) 2012-2013 by Greg Hendershott. All rights reserved.</span></div><div class="SIntrapara"><span class="Smaller">Last updated 2013-08-15T14:15:07</span></div><div class="SIntrapara">Feedback and corrections are <a href="https://github.com/greghendershott/fear-of-macros/issues">welcome here</a>.</div></p><p>Contents:</p><table cellspacing="0"><tr><td><p><span class="hspace"> </span><a href="Preface.html" class="toptoclink" data-pltdoc="x">1<span class="hspace"> </span>Preface</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Our_plan_of_attack.html" class="toptoclink" data-pltdoc="x">2<span class="hspace"> </span>Our plan of attack</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html" class="toptoclink" data-pltdoc="x">3<span class="hspace"> </span>Transform!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.What_is_a_syntax_transformer_%29" class="toclink" data-pltdoc="x">3.1<span class="hspace"> </span>What is a syntax transformer?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.What_s_the_input_%29" class="toclink" data-pltdoc="x">3.2<span class="hspace"> </span>What’s the input?</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.Actually_transforming_the_input%29" class="toclink" data-pltdoc="x">3.3<span class="hspace"> </span>Actually transforming the input</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._.Compile_time_vs__run_time%29" class="toclink" data-pltdoc="x">3.4<span class="hspace"> </span>Compile time vs. run time</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Transform_.html#%28part._begin-for-syntax%29" class="toclink" data-pltdoc="x">3.5<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">begin-for-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html" class="toptoclink" data-pltdoc="x">4<span class="hspace"> </span>Pattern matching: syntax-case and syntax-rules</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._.Pattern_variable_vs__template---fight_%29" class="toclink" data-pltdoc="x">4.1<span class="hspace"> </span>Pattern variable vs. template—<wbr></wbr>fight!</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._with-syntax%29" class="toclink" data-pltdoc="x">4.1.1<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._with-syntax_%29" class="toclink" data-pltdoc="x">4.1.2<span class="hspace"> </span><span class="RktSym"><span class="RktStxLink">with-syntax*</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._format-id%29" class="toclink" data-pltdoc="x">4.1.3<span class="hspace"> </span><span class="RktSym"><span class="RktValLink">format-id</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._.Another_example%29" class="toclink" data-pltdoc="x">4.1.4<span class="hspace"> </span>Another example</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._.Making_our_own_struct%29" class="toclink" data-pltdoc="x">4.2<span class="hspace"> </span>Making our own <span class="RktSym"><span class="RktStxLink">struct</span></span></a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="pattern-matching.html#%28part._hash..refs%29" class="toclink" data-pltdoc="x">4.3<span class="hspace"> </span>Using dot notation for nested hash lookups</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Syntax_parameters.html" class="toptoclink" data-pltdoc="x">5<span class="hspace"> </span>Syntax parameters</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="What_s_the_point_of_splicing-let_.html" class="toptoclink" data-pltdoc="x">6<span class="hspace"> </span>What’s the point of <span class="RktSym"><span class="RktStxLink">splicing-let</span></span>?</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html" class="toptoclink" data-pltdoc="x">7<span class="hspace"> </span>Robust macros: syntax-parse</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html#%28part._.Error-handling_strategies_for_functions%29" class="toclink" data-pltdoc="x">7.1<span class="hspace"> </span>Error-handling strategies for functions</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html#%28part._.Error-handling_strategies_for_macros%29" class="toclink" data-pltdoc="x">7.2<span class="hspace"> </span>Error-handling strategies for macros</a></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Robust_macros__syntax-parse.html#%28part._.Using_syntax_parse%29" class="toclink" data-pltdoc="x">7.3<span class="hspace"> </span>Using <span class="RktSym">syntax/parse</span></a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="References_and_Acknowledgments.html" class="toptoclink" data-pltdoc="x">8<span class="hspace"> </span>References and Acknowledgments</a></p></td></tr><tr><td><p><span class="hspace"></span></p></td></tr><tr><td><p><span class="hspace"> </span><a href="Epilogue.html" class="toptoclink" data-pltdoc="x">9<span class="hspace"> </span>Epilogue</a></p></td></tr></table><div class="navsetbottom"><span class="navleft"> </span><span class="navright"> <span class="nonavigation">← prev</span> <span class="nonavigation">up</span> <a href="Preface.html" title="forward to "1 Preface"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
+\ No newline at end of file
diff --git a/index.rkt b/index.rkt
@@ -1305,11 +1305,15 @@ conflict with a variable named @racket[x] in an outer scope:
When our macros also respect lexical scoping, it's easier to write
reliable macros that behave predictably.
-So that's wonderful default behavior. But @italic{sometimes} we want
-to introduce a magic variable on purpose---such as @racket[it] for
+So that's wonderful default behavior. But sometimes we want to
+introduce a magic variable on purpose---such as @racket[it] for
@racket[aif].
-The way to do this is with a "syntax parameter", using
+There's a bad way to do this and a good way.
+
+The bad way is to use @racket[datum->syntax], which is tricky to use correctly. @margin-note*{See @hyperlink["http://www.schemeworkshop.org/2011/papers/Barzilay2011.pdf" "Keeping it Clean with Syntax Parameters (PDF)"].}
+
+The good way is with a syntax parameter, using
@racket[define-syntax-parameter] and
@racket[syntax-parameterize]. You're probably familiar with regular
parameters in Racket:
