Add more rationale for syntax parameters.
As suggested by @stchang in issue #1.
This commit is contained in:
Greg Hendershott
parent
c0b3b4b465
commit
178c150205
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
10
index.rkt
10
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user