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.
pollen/doc/reader.html

28 lines
113 KiB
HTML

11 years ago
<!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>7&nbsp;◊ command overview</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><!--[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;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,&quot;tocview_0&quot;);">&#9660;</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Pollen:<span class="mywbr"> &nbsp;</span> the book is a program</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1&nbsp;</td><td><a href="Installation.html" class="tocviewlink" data-pltdoc="x">Installation</a></td></tr><tr><td align="right">2&nbsp;</td><td><a href="quick-tour.html" class="tocviewlink" data-pltdoc="x">Quick tour</a></td></tr><tr><td align="right">3&nbsp;</td><td><a href="Backstory.html" class="tocviewlink" data-pltdoc="x">Backstory</a></td></tr><tr><td align="right">4&nbsp;</td><td><a href="System_overview.html" class="tocviewlink" data-pltdoc="x">System overview</a></td></tr><tr><td align="right">5&nbsp;</td><td><a href="Using_raco_pollen.html" class="tocviewlink" data-pltdoc="x">Using <span class="stt">raco pollen</span></a></td></tr><tr><td align="right">6&nbsp;</td><td><a href="File_formats.html" class="tocviewlink" data-pltdoc="x">File formats</a></td></tr><tr><td align="right">7&nbsp;</td><td><a href="reader.html" class="tocviewselflink" data-pltdoc="x">&#9674; command overview</a></td></tr><tr><td align="right">8&nbsp;</td><td><a href="Module_reference.html" class="tocviewlink" data-pltdoc="x">Module reference</a></td></tr><tr><td align="right">9&nbsp;</td><td><a href="Acknowledgments.html" class="tocviewlink" data-pltdoc="x">Acknowledgments</a></td></tr><tr><td align="right">10&nbsp;</td><td><a href="License___source_code.html" class="tocviewlink" data-pltdoc="x">License &amp; source code</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,&quot;tocview_1&quot;);">&#9658;</a></td><td>7&nbsp;</td><td><a href="reader.html" class="tocviewselflink" data-pltdoc="x">&#9674; command overview</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">7.1&nbsp;</td><td><a href="reader.html#%28part._.The_golden_rule%29" class="tocviewlink" data-pltdoc="x">The golden rule</a></td></tr><tr><td align="right">7.2&nbsp;</td><td><a href="reader.html#%28part._.The_lozenge_glyph____%29" class="tocviewlink" data-pltdoc="x">The lozenge glyph (&#9674;)</a></td></tr><tr><td align="right">7.3&nbsp;</td><td><a href="reader.html#%28part._.The_two_command_modes__text_mode___.Racket_mode%29" class="tocviewlink" data-pltdoc="x">The two command modes:<span class="mywbr"> &nbsp;</span> text mode &amp; Racket mode</a></td></tr><tr><td align="right">7.4&nbsp;</td><td><a href="reader.html#%28part._.Further_reading%29" class="tocviewlink" data-pltdoc="x">Further reading</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublink
11 years ago
<br/>
<span style="font-weight: bold">Windows</span>:
<br/>
<span style="font-weight: bold">Ubuntu</span>:</p><p>Still, if you don&rsquo;t want to use the lozenge as your command marker, you can use something else. Set Pollen&rsquo;s <span class="RktSym">world:command-marker</span> value to whatever character you want.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>Scribble uses the @ sign as a delimiter. It&rsquo;s not a bad choice if you only work with Racket files. But as you use Pollen to work on other kinds of text-based files that commonly contain @ signs &#8212; HTML pages especially &#8212; it gets cumbersome. So I changed it.</p></blockquote></blockquote></blockquote><p>But don&rsquo;t knock the lozenge till you try it.</p><h4>7.3<tt>&nbsp;</tt><a name="(part._.The_two_command_modes__text_mode___.Racket_mode)"></a>The two command modes: text mode &amp; Racket mode</h4><p>Pollen commands can be entered in one of two modes: <span style="font-style: italic">text mode</span> or <span style="font-style: italic">Racket mode</span>. Both modes start with a lozenge (<span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;</span><span class="hspace"></span></span>):</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;</span><span class="hspace"></span></span><span class="hspace">&nbsp;</span><span class="sroman">&#8249;<span style="font-style: italic">command name</span>&#8250;</span><span class="hspace">&nbsp;</span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">[</span><span class="hspace"></span></span><span class="hspace">&nbsp;</span><span class="sroman">&#8249;<span style="font-style: italic">Racket arguments ...</span>&#8250;</span><span class="hspace">&nbsp;</span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">]</span><span class="hspace"></span></span><span class="hspace">&nbsp;</span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">{</span><span class="hspace"></span></span><span class="hspace">&nbsp;</span><span class="sroman">&#8249;<span style="font-style: italic">text argument</span>&#8250;</span><span class="hspace">&nbsp;</span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">}</span><span class="hspace"></span></span></td></tr><tr><td><span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;</span><span class="hspace"></span></span><span class="hspace">&nbsp;</span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">(</span><span class="hspace"></span></span><span class="hspace">&nbsp;</span><span class="sroman">&#8249;<span style="font-style: italic">Racket expression</span>&#8250;</span><span class="hspace">&nbsp;</span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">)</span><span class="hspace"></span></span></td></tr></table></blockquote><p><span style="font-weight: bold">Text-mode commands</span></p><p>A text-mode command has the three possible parts after the <span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;</span><span class="hspace"></span></span>:</p><ul><li><p>The <span style="font-style: italic">command name</span> appears immediately after the <span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;</span><span class="hspace"></span></span>. Typically it&rsquo;s a short word.</p></li><li><p>The <span style="font-style: italic">Racket arguments</span> appear between square brackets. Pollen is partly an interface to the Racket programming language. These arguments are entered using Racket conventions &#8212;&#160;e.g., a <span class="stt">string of text</span> needs to be put in quotes as a <span class="RktVal">"string</span><span class="hspace">&nbsp;</span><span class="RktVal">of</span><span class="hspace">&nbsp;</span><span class="RktVal">text"</span><span class="RktMeta"></span>. If you like programming, you&rsquo;ll end up using these frequently. If you don&rsquo;t, you won&rsquo;t.</
the expected number of arguments does not match the given number<br/>
&#160;&#160;given: 1<br/>
&#160;&#160;arguments...:<br/>
&#160;&#160;&#160;&#160;"Fancy Sauce, $1"</span></p><p>What to do? Read on.</p><h5>7.3.1.2<tt>&nbsp;</tt><a name="(part._.Invoking_other_functions)"></a>Invoking other functions</h5><p>Though every command name starts out as a tag function, it doesn&rsquo;t necessarily end there. You have two options for invoking other functions: defining your own , or invoking others from Racket.</p><p><span style="font-weight: bold">Defining your own functions</span></p><p>Use the <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> command to create your own function for a command name. After that, when you use the command name, you&rsquo;ll get the new behavior. For instance, recall this example showing the default tag-function behavior:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace">&nbsp;</span><span class="RktMeta">Sauce</span><span class="RktMeta">,</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">'(strong "Fancy Sauce, $1")</span></p><p>We can define <span class="stt">strong</span> to do something else, like add to the text:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</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="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quasiquote.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._quasiquote%29%29" class="RktStxLink" data-pltdoc="x">`</a></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quasiquote.html#%28form._%28%28quote._~23~25kernel%29._unquote%29%29" class="RktStxLink" data-pltdoc="x">,</a></span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29" class="RktValLink" data-pltdoc="x">format</a></span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktVal">"Hey!</span><span class="hspace">&nbsp;</span><span class="RktVal">Listen</span><span class="hspace">&nbsp;</span><span class="RktVal">up!</span><span class="hspace">&nbsp;</span><span class="RktVal">~a"</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span clas
the expected number of arguments does not match the given number<br/>
&#160;&#160;expected: 0<br/>
&#160;&#160;given: 1<br/>
&#160;&#160;arguments...:<br/>
&#160;&#160;&#160;&#160;"Fancy Sauce, $1"</span></p><p>Whereas in this version, <span class="stt">strong</span> accepts an argument called <span class="stt">text</span>, but then ignores it:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</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="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></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="RktPn">(</span><span class="RktSym">fib</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktVal">"1</span><span class="hspace">&nbsp;</span><span class="RktVal">1</span><span class="hspace">&nbsp;</span><span class="RktVal">2</span><span class="hspace">&nbsp;</span><span class="RktVal">3</span><span class="hspace">&nbsp;</span><span class="RktVal">5</span><span class="hspace">&nbsp;</span><span class="RktVal">8</span><span class="hspace">&nbsp;</span><span class="RktVal">13</span><span class="hspace">&nbsp;</span><span class="RktVal">..."</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace">&nbsp;</span><span class="RktMeta">Sauce</span><span class="RktMeta">,</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">'(fib "1 1 2 3 5 8 13 ...")</span></p><p>You can attach any behavior to a command name. As your project evolves, you can also update the behavior of a command name. In that way, Pollen commands become a set of hooks to which you can attach more elaborate processing.</p><p><span style="font-weight: bold">Using Racket functions</span></p><p>You aren&rsquo;t limited to functions you define. Any function from Racket, or any Racket library, can be invoked directly by using it as a command name. Here&rsquo;s the function <span class="RktSym"><a href="http://docs.racket-lang.org/reference/pairs.html#%28def._%28%28lib._racket%2Flist..rkt%29._range%29%29" class="RktValLink" data-pltdoc="x">range</a></span>, which creates a list of numbers:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/pairs.html#%28def._%28%28lib._racket%2Flist..rkt%29._range%29%29" class="RktValLink" data-pltdoc="x">range</a></span><span class="RktPn">[</span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktVal">20</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">'(range 1 20)
expected a procedure that can be applied to arguments<br/>
&#160;&#160;given: "bar"<br/>
&#160;&#160;arguments...: [none]</span></p><p>The reason we can simply drop <span class="RktSym">&#9674;foo</span><span class="RktMeta"></span> into the text argument of another Pollen command is that the variable <span class="RktSym">foo</span><span class="RktMeta"></span> holds a string (i.e., a text value). When appropriate, Pollen will convert a variable to a string in a sensible way. For instance, numbers are easily converted:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</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="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktVal">42</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">The</span><span class="hspace">&nbsp;</span><span class="RktMeta">value</span><span class="hspace">&nbsp;</span><span class="RktMeta">of</span><span class="hspace">&nbsp;</span><span class="RktMeta">zam</span><span class="hspace">&nbsp;</span><span class="RktMeta">is</span><span class="hspace">&nbsp;</span><span class="RktMeta">&#9674;</span><span class="RktSym">zam</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">The value of zam is 42</span></p><p>If the variable holds a container datatype (like a <span class="RktSym"><a href="http://docs.racket-lang.org/reference/pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span>, <span class="RktSym"><a href="http://docs.racket-lang.org/reference/hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash%29%29" class="RktValLink" data-pltdoc="x">hash</a></span>, or <span class="RktSym"><a href="http://docs.racket-lang.org/reference/vectors.html#%28def._%28%28quote._~23~25kernel%29._vector%29%29" class="RktValLink" data-pltdoc="x">vector</a></span>), Pollen will produce the Racket text representation of the item. Here, <span class="stt">zam</span> is a <span class="RktSym"><a href="http://docs.racket-lang.org/reference/pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span> of integers:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</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="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktVal">2</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span>
'(span "Nor is this")</span></p><p>To comment out a multiline block, use the lozenge&#8211;semicolon signal <span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;;</span><span class="hspace"></span></span> with curly braces, <span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;;{</span><span class="hspace"></span></span>like so<span class="RktInBG"><span class="hspace"></span><span class="RktIn">}</span><span class="hspace"></span></span>.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktCmt">;{</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;span</span><span class="RktPn">{</span><span class="RktMeta">This</span><span class="hspace">&nbsp;</span><span class="RktMeta">is</span><span class="hspace">&nbsp;</span><span class="RktMeta">not</span><span class="hspace">&nbsp;</span><span class="RktMeta">a</span><span class="hspace">&nbsp;</span><span class="RktMeta">comment</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;span</span><span class="RktPn">{</span><span class="RktMeta">Nor</span><span class="hspace">&nbsp;</span><span class="RktMeta">is</span><span class="hspace">&nbsp;</span><span class="RktMeta">this</span><span class="RktPn">}</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta">&#9674;</span><span class="RktCmt">;span{But</span><span class="hspace">&nbsp;</span><span class="RktCmt">this</span><span class="hspace">&nbsp;</span><span class="RktCmt">is}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">Actually</span><span class="RktMeta">,</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta">it</span><span class="RktVal">'</span><span class="RktMeta">s</span><span class="hspace">&nbsp;</span><span class="RktMeta">all</span><span class="hspace">&nbsp;</span><span class="RktMeta">a</span><span class="hspace">&nbsp;</span><span class="RktMeta">comment</span><span class="hspace">&nbsp;</span><span class="RktMeta">now</span></td></tr></table></blockquote><p><span class="RktOut">Actually, it's all a comment now</span></p><h5>7.3.2<tt>&nbsp;</tt><a name="(part._.The_.Racket_arguments)"></a>The Racket arguments</h5><p>The middle part of a text-mode Pollen command contains the <span style="font-style: italic">Racket arguments</span> <span class="RktInBG"><span class="hspace"></span><span class="RktIn">[</span><span class="hspace"></span></span>between square brackets.<span class="RktInBG"><span class="hspace"></span><span class="RktIn">]</span><span class="hspace"></span></span> Most often, you&rsquo;ll see these used to pass extra information to commands that operate on text.</p><p>For instance, tag functions. Recall from before that any not-yet-defined command name in Pollen is treated as a tag function:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym"><a href="http://docs.racket-lang.org/scribble/base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._title%29%29" class="RktValLink" data-pltdoc="x">title</a></span><span class="RktPn">{</span><span class="RktMeta">The</span><span class="hspace">&nbsp;</span><span class="RktMeta">Beginning</span><span class="hspace">&nbsp;</span><span class="RktMeta">of</span><span class="hspace">&nbsp;</span><span
'(h2 "Minor league") <br/>
'(h6 "Trivial league")</span></p><h5>7.3.3<tt>&nbsp;</tt><a name="(part._.The_text_argument)"></a>The text argument</h5><p>The third part of a text-mode Pollen command is the text argument. The text argument <span class="RktInBG"><span class="hspace"></span><span class="RktIn">{</span><span class="hspace"></span></span>appears between curly braces<span class="RktInBG"><span class="hspace"></span><span class="RktIn">}</span><span class="hspace"></span></span>. It can contain any text you want. The text argument can also contain other Pollen commands with their own text arguments. And they can contain other Pollen commands ... and so on, all the way down.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">Do</span><span class="hspace">&nbsp;</span><span class="RktMeta">it</span><span class="hspace">&nbsp;</span><span class="RktMeta">again.</span><span class="hspace">&nbsp;</span><span class="RktMeta">&#9674;</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">And</span><span class="hspace">&nbsp;</span><span class="RktMeta">again.</span><span class="hspace">&nbsp;</span><span class="RktMeta">&#9674;</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">And</span><span class="hspace">&nbsp;</span><span class="RktMeta">yet</span><span class="hspace">&nbsp;</span><span class="RktMeta">again.</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">'(div "Do it again. " (div "And again. " (div "And yet again.")))</span></p><p>Three small details to know about the text argument.</p><p>First, the only character that needs special handling in a text argument is the lozenge <span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;</span><span class="hspace"></span></span>. A lozenge ordinarily marks a new command. So if you want an actual lozenge to appear in the text, you have to escape it by typing <span class="RktInBG"><span class="hspace"></span><span class="RktIn">&#9674;"&#9674;"</span><span class="hspace"></span></span>.</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym">definition</span><span class="RktPn">{</span><span class="RktMeta">This</span><span class="hspace">&nbsp;</span><span class="RktMeta">is</span><span class="hspace">&nbsp;</span><span class="RktMeta">the</span><span class="hspace">&nbsp;</span><span class="RktMeta">lozenge:</span><span class="hspace">&nbsp;</span><span class="RktMeta">&#9674;</span><span class="RktVal">"&#9674;"</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">'(definition "This is the lozenge: &#9674;")</span></p><p>Second, the whitespace-trimming policy. Here&rsquo;s the short version: if there&rsquo;s a carriage return at either end of the text argument, it is trimmed, and whitespace at the end of each line is selectively trimmed in an intelligent way. So this text argument, with carriage returns on the ends:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span
the expected number of arguments does not match the given number<br/>
&#160;&#160;expected: 1<br/>
&#160;&#160;given: 3<br/>
&#160;&#160;arguments...:<br/>
&#160;&#160;&#160;"Deeply"<br/>
&#160;&#160;&#160;"\n"<br/>
&#160;&#160;&#160;"chastened"</span></p><p>The answer is to use a <span style="font-style: italic">rest argument</span> in the function, which takes the &ldquo;rest&rdquo; of the arguments &#8212;&#160;however many there may be &#8212;&#160;and combines them into a single <span class="RktSym"><a href="http://docs.racket-lang.org/reference/pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span>. If we rewrite <span class="stt">jejune</span> with a rest argument, we can fix the problem:</p><blockquote class="SCodeFlow"><table cellspacing="0" class="RktBlk"><tr><td><span class="RktMeta">#lang</span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</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="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktMeta">.</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym">texts</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace">&nbsp;&nbsp;&nbsp;</span><span class="RktMeta"></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quasiquote.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._quasiquote%29%29" class="RktStxLink" data-pltdoc="x">`</a></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace">&nbsp;</span><span class="RktMeta"></span><span class="RktSym"><a href="http://docs.racket-lang.org/reference/quasiquote.html#%28form._%28%28quote._~23~25kernel%29._unquote-splicing%29%29" class="RktStxLink" data-pltdoc="x">,@</a></span><span class="RktSym">texts</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta">&#9674;</span><span class="RktSym">jejune</span><span class="RktPn">{</span><span class="RktMeta">Deeply</span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="RktMeta">chastened</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p><span class="RktOut">'(jejune "Deeply" "\n" "chastened")</span></p><h4>7.4<tt>&nbsp;</tt><a name="(part._.Further_reading)"></a>Further reading</h4><p>The Pollen language is a variant of Racket&rsquo;s own text-processing language, called Scribble. So many things that are true about Scribble are also true about Pollen. For the sake of clarity &amp; brevity, I&rsquo;ve omitted them from this summary. But if you want the full story, see <a href="http://docs.racket-lang.org/scribble/reader.html" data-pltdoc="x">@ Syntax</a> in the Scribble documentation.</p><div class="navsetbottom"><span class="navleft">&nbsp;&nbsp;</span><span class="navright">&nbsp;&nbsp;<a href="File_formats.html" title="backward to &quot;6 File formats&quot;" data-pltdoc="x">&larr; prev</a>&nbsp;&nbsp;<a href="index.html" title="up to &quot;Pollen: the book is a program&quot;" data-pltdoc="x">up</a>&nbsp;&nbsp;<a href="Module_reference.html" title="forward to &quot;8 Module reference&quot;" data-pltdoc="x">next &rarr;</a></span>&nbsp;</div></div></div><div id="contextindicator">&nbsp;</div></body></html>