Merge branch 'master' into gh-pages
* master: Regen HTML
This commit is contained in:
Greg Hendershott
commit
09577114cd
|
|
@ -6,8 +6,7 @@ message from <span class="RktSym"><a href="http://docs.racket-lang.org/reference
|
|||
could probably guess what’s happening, but in most cases they won’t.</p><p>2. Write some error handling code.</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%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">misuse</span><span class="hspace"> </span><span class="RktSym">s</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/when_unless.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._unless%29%29" class="RktStxLink" data-pltdoc="x">unless</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span><span class="RktSym">s</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/exns.html#%28def._%28%28quote._~23~25kernel%29._error%29%29" class="RktValLink" data-pltdoc="x">error</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">misuse</span><span class="hspace"> </span><span class="RktVal">"expected a string, but got ~a"</span><span class="hspace"> </span><span class="RktSym">s</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/strings.html#%28def._%28%28quote._~23~25kernel%29._string-append%29%29" class="RktValLink" data-pltdoc="x">string-append</a></span><span class="hspace"> </span><span class="RktSym">s</span><span class="hspace"> </span><span class="RktVal">" snazzy suffix"</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">User of the function:</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">misuse</span><span class="hspace"> </span><span class="RktVal">0</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">misuse: expected a string, but got 0</span></p></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">I goofed, and understand why! It</span><span class="RktCmt">'</span><span class="RktCmt">s a shame the writer of the</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">function had to work so hard to tell me.</span></td></tr></table></blockquote><p>Unfortunately the error code tends to overwhelm and/or obscure our
|
||||
function definition. Also, the error message is good but not
|
||||
great. Improving it would require even more error code.</p><p>3. Use a contract.</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/attaching-contracts-to-values.html#%28form._%28%28lib._racket%2Fcontract%2Fregion..rkt%29._define%2Fcontract%29%29" class="RktStxLink" data-pltdoc="x">define/contract</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">misuse</span><span class="hspace"> </span><span class="RktSym">s</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/strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></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/strings.html#%28def._%28%28quote._~23~25kernel%29._string-append%29%29" class="RktValLink" data-pltdoc="x">string-append</a></span><span class="hspace"> </span><span class="RktSym">s</span><span class="hspace"> </span><span class="RktVal">" snazzy suffix"</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">User of the function:</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">misuse</span><span class="hspace"> </span><span class="RktVal">0</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">misuse: contract violation</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">expected: string?</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">given: 0</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">in: the 1st argument of</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">(-> string? string?)</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">contract from: (function misuse)</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">blaming: program</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">at: eval:131.0</span></p></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">I goofed, and understand why! I</span><span class="RktCmt">'</span><span class="RktCmt">m happier, and I hear the writer of</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">the function is happier, too.</span></td></tr></table></blockquote><p>This is the best of both worlds.</p><p>The contract is a simple and concise. Even better, it’s
|
||||
declarative. We say what we want, without needing to spell out what to
|
||||
do.</p><p>On the other hand the user of our function gets a very detailed error
|
||||
declarative. We say what we want to happen, not how.</p><p>On the other hand the user of our function gets a very detailed error
|
||||
message. Plus, the message is in a standard, familiar format.</p><p>4. Use Typed Racket.</p><p><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/ts-reference/index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">typed/racket</span></a><span class="RktMeta"></span></td></tr></table></blockquote></div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">:</span><span class="hspace"> </span><span class="RktSym">misuse</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">String</span><span class="hspace"> </span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="hspace"> </span><span class="RktSym">String</span><span class="RktPn">)</span><span class="RktPn">)</span></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/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="RktPn">(</span><span class="RktSym">misuse</span><span class="hspace"> </span><span class="RktSym">s</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/strings.html#%28def._%28%28quote._~23~25kernel%29._string-append%29%29" class="RktValLink" data-pltdoc="x">string-append</a></span><span class="hspace"> </span><span class="RktSym">s</span><span class="hspace"> </span><span class="RktVal">" snazzy suffix"</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">misuse</span><span class="hspace"> </span><span class="RktVal">0</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">eval:3:0: Type Checker: Expected String, but got Zero</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">in: 0</span></p></td></tr></table></blockquote></div></p><p>Even better, Typed Racket can catch usage mistakes up-front at compile
|
||||
time.</p><h4>7.2<tt> </tt><a name="(part._.Error-handling_strategies_for_macros)"></a>Error-handling strategies for macros</h4><p>For macros, we have similar choices.</p><p>1. Ignore the possibility of misuse. This choice is even worse for
|
||||
macros. The default error messages are even less likely to make sense,
|
||||
|
|
@ -27,8 +26,8 @@ confused.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"
|
|||
with many simple examples, followed by an
|
||||
<a href="http://docs.racket-lang.org/syntax/stxparse-examples.html">Examples</a>
|
||||
section illustrating many real-world scenarios.</p><p>Furthermore, everything I’d learned up to this point prepared me to
|
||||
appreciate what <span class="RktSym"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#%28form._%28%28lib._syntax%2Fparse..rkt%29._syntax-parse%29%29" class="RktStxLink" data-pltdoc="x">syntax-parse</a></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
|
||||
appreciate what <span class="RktSym"><a href="http://docs.racket-lang.org/syntax/Parsing_Syntax.html#%28form._%28%28lib._syntax%2Fparse..rkt%29._syntax-parse%29%29" class="RktStxLink" data-pltdoc="x">syntax-parse</a></span> does, and why. The details of
|
||||
how to use it seem pretty straightforward, so far.</p><p>This might well be a temporary state of me "not knowing what I don’t
|
||||
know". As I dig in and use it more, maybe I’ll discover something
|
||||
confusing or tricky. If/when I do, I’ll come back here and update
|
||||
this.</p><p>But for now I’ll focus on improving the previous parts.</p><div class="navsetbottom"><span class="navleft"> </span><span class="navright"> <a href="What_s_the_point_of_splicing-let_.html" title="backward to "6 What's the point of splicing-let?"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Fear of Macros"" data-pltdoc="x">up</a> <a href="References_and_Acknowledgments.html" title="forward to "8 References and Acknowledgments"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|
||||
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue
Block a user