You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2 lines
23 KiB
HTML
2 lines
23 KiB
HTML
<!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"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>Top</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="manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-racket.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><script type="text/javascript" src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;">•</td><td></td><td><a href="file:///Users/MB/git/pollen/pollen/scribblings/top.html" class="tocviewselflink" data-pltdoc="x">Top</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._.Top%29" class="tocsubseclink" data-pltdoc="x">Top</a></td></tr><tr><td><a href="#%28form._%28%28lib._pollen%2Ftop..rkt%29._~23~25top%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span></a></td></tr><tr><td><a href="#%28form._%28%28lib._pollen%2Ftop..rkt%29._def%2Fc%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym">def/<span class="mywbr"> </span>c</span></a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="versionNoNav">7.1.0.6</span></div><h2><a name="(part._.Top)"></a><a name="(mod-path._pollen/top)"></a>Top</h2><p><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="stt"> </span><a href="file:///Users/MB/git/pollen/pollen/scribblings/top.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/top</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <a href="https://pkgs.racket-lang.org/package/pollen" title="Install this package using `raco pkg install pollen`"><span class="stt">pollen</span></a></span></td></tr></table></p><p>You’ll probably never invoke this module directly. But it’s implicitly imported into every Pollen markup file. And if you don’t know what it does, you might end up surprised by some of the behavior you get.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._pollen/top..rkt)._~23~25top))"></a><span title="Provided from: pollen/top | Package: pollen"><span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktVar">id</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">In standard Racket, <span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span> is the function of last resort, called when <span class="RktVar">id</span> is not bound to any value. As such, it typically reports a syntax error.</div></p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">Let</span><span class="RktCmt">'</span><span class="RktCmt">s call em without defining it</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">em</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">em: undefined;</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">cannot reference an identifier before its definition</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">in module: top-level</span></p></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">(em "Bonjour") is being converted to ((#%top . em) "Bonjour")</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">So calling ((#%top . em) "Bonjour") will give the same result</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">em</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">em: undefined;</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">cannot reference an identifier before its definition</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">in module: top-level</span></p></td></tr></table></blockquote></div></p><p>In the Pollen markup environment, however, this behavior is annoying. Because when you’re writing X-expressions, you don’t necessarily want to define all your tags ahead of time.</p><p>So Pollen redefines <span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span>. For convenience, Pollen’s version of <span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span> assumes that an undefined tag should just refer to an X-expression beginning with that tag (and uses <span class="RktSym"><span class="badlink"><span class="RktValLink">default-tag-function</span></span></span> to provide this behavior):</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">Again, let</span><span class="RktCmt">'</span><span class="RktCmt">s call em without defining it, but using pollen/top</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="hspace"> </span><span class="RktSym">pollen/top</span><span class="RktPn">)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">em</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'(em "Bonjour")</span></p></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">(em "Bonjour") is still being converted to ((#%top . em) "Bonjour")</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">But now, ((#%top . em) "Bonjour") gives a different result</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">em</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'(em "Bonjour")</span></p></td></tr></table></blockquote></div></p><p>The good news is that this behavior means you use any tag you want in your markup without defining it in advance. You can still attach a function to the tag later, which will automatically supersede <span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span>.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">em</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">span</span><span class="hspace"> </span><span class="RktVal">(</span><span class="RktVal">(</span><span class="RktVal">style</span><span class="hspace"> </span><span class="RktVal">"font-size:100px"</span><span class="RktVal">)</span><span class="RktVal">)</span><span class="hspace"> </span><span class="RktRdr">,</span><span class="RktSym">x</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">em</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'(span ((style "font-size:100px")) "Bonjour")</span></p></td></tr></table></blockquote></div></p><p>The bad news is that you’ll never get an “unbound identifier” error. These unbound identifiers will happily sail through and be converted to tags.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="hspace"> </span><span class="RktSym">pollen/top</span><span class="RktPn">)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">em</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">xs</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">span</span><span class="hspace"> </span><span class="RktVal">(</span><span class="RktVal">(</span><span class="RktVal">style</span><span class="hspace"> </span><span class="RktVal">"font-size:100px"</span><span class="RktVal">)</span><span class="RktVal">)</span><span class="hspace"> </span><span class="RktRdr">,@</span><span class="RktSym">xs</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">There</span><span class="RktCmt">'</span><span class="RktCmt">s a typo in my tag</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">erm</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'(erm "Bonjour")</span></p></td></tr></table></blockquote></div></p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>If you prefer the ordinary Racket-style behavior where unbound identifiers raise an error, define <span class="RktSym"><span class="badlink"><span class="RktValLink">setup:allow-unbound-ids?</span></span></span> in your project as <span class="RktVal">#false</span>.</p></blockquote></blockquote></blockquote><p>This isn’t a bug. It’s just a natural consequence of how Pollen’s <span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span> works. It can, however, make debugging difficult sometimes. Let’s suppose my markup depends on <span class="RktSym">very-important-function</span>, which I don’t import correctly.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="hspace"> </span><span class="RktSym">pollen/top</span><span class="RktPn">)</span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">module</span></span></span><span class="hspace"> </span><span class="RktSym">vif</span><span class="hspace"> </span><span class="RktSym">racket/base</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">xs</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">secrets-of-universe</span><span class="hspace"> </span><span class="RktRdr">,@</span><span class="RktSym">xs</span><span class="RktVal">)</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">Forgot to (require </span><span class="RktCmt">'</span><span class="RktCmt">vif)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'(very-important-function "Bonjour")</span></p></td></tr></table></blockquote></div></p><p>So the undefined-function bug goes unreported. Again, that’s not a bug in Pollen — there’s just no way for it to tell the difference between an identifier that’s deliberately undefined and one that’s inadvertently undefined. If you want to guarantee that you’re invoking a defined identifier, use <span class="RktSym">def/c</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._pollen/top..rkt)._def/c))"></a><span title="Provided from: pollen/top | Package: pollen"><span class="RktSym"><span class="RktSymDef RktSym">def/c</span></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Invoke <span class="RktVar">id</span> if it’s a defined identifier, otherwise raise an error. This form reverses the behavior of <span class="RktSym"><span class="badlink"><span class="RktValLink">#%top</span></span></span> (in other words, it restores default Racket behavior).</div></p><p>Recall this example from before. In standard Racket, you get an undefined-identifier error.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">module</span></span></span><span class="hspace"> </span><span class="RktSym">vif</span><span class="hspace"> </span><span class="RktSym">racket/base</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">xs</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">secrets-of-universe</span><span class="hspace"> </span><span class="RktRdr">,@</span><span class="RktSym">xs</span><span class="RktVal">)</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">Forgot to (require </span><span class="RktCmt">'</span><span class="RktCmt">vif)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">very-important-function: undefined;</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">cannot reference an identifier before its definition</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">in module: top-level</span></p></td></tr></table></blockquote></div></p><p>But with <a href="file:///Users/MB/git/pollen/pollen/scribblings/top.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/top</span></a>, the issue is not treated as an error.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="hspace"> </span><span class="RktSym">pollen/top</span><span class="RktPn">)</span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">module</span></span></span><span class="hspace"> </span><span class="RktSym">vif</span><span class="hspace"> </span><span class="RktSym">racket/base</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">xs</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">secrets-of-universe</span><span class="hspace"> </span><span class="RktRdr">,@</span><span class="RktSym">xs</span><span class="RktVal">)</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">Forgot to (require </span><span class="RktCmt">'</span><span class="RktCmt">vif)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">'(very-important-function "Bonjour")</span></p></td></tr></table></blockquote></div></p><p>By adding <span class="RktSym">def/c</span>, we restore the usual behavior, guaranteeing that we get the defined version of <span class="RktSym">very-important-function</span> or nothing.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="hspace"> </span><span class="RktSym">pollen/top</span><span class="RktPn">)</span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">module</span></span></span><span class="hspace"> </span><span class="RktSym">vif</span><span class="hspace"> </span><span class="RktSym">racket/base</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">very-important-function</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym">xs</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">secrets-of-universe</span><span class="hspace"> </span><span class="RktRdr">,@</span><span class="RktSym">xs</span><span class="RktVal">)</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">Forgot to (require </span><span class="RktCmt">'</span><span class="RktCmt">vif)</span></td></tr><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym">def/c</span><span class="hspace"> </span><span class="RktSym">very-important-function</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">"Bonjour"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktErr">very-important-function: undefined;</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">cannot reference an identifier before its definition</span></p></td></tr><tr><td><p><span class="RktErr"></span><span class="hspace"> </span><span class="RktErr">in module: top-level</span></p></td></tr></table></blockquote></div></p></div></div><div id="contextindicator"> </div></body></html> |