<html><head><metahttp-equiv="content-type"content="text/html; charset=utf-8"/><title>7 ◊ command overview</title><linkrel="stylesheet"type="text/css"href="scribble.css"title="default"/><linkrel="stylesheet"type="text/css"href="racket.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-style.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-racket.css"title="default"/><scripttype="text/javascript"src="scribble-common.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><bodyid="scribble-racket-lang-org"><divclass="tocset"><divclass="tocview"><divclass="tocviewlist tocviewlisttopspace"><divclass="tocviewtitle"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><ahref="index.html"class="tocviewlink"data-pltdoc="x">Pollen:<spanclass="mywbr"> </span> the book is a program</a></td></tr></table></div><divclass="tocviewsublisttop"style="display: block;"id="tocview_0"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">1 </td><td><ahref="Installation.html"class="tocviewlink"data-pltdoc="x">Installation</a></td></tr><tr><tdalign="right">2 </td><td><ahref="quick-tour.html"class="tocviewlink"data-pltdoc="x">Quick tour</a></td></tr><tr><tdalign="right">3 </td><td><ahref="Backstory.html"class="tocviewlink"data-pltdoc="x">Backstory</a></td></tr><tr><tdalign="right">4 </td><td><ahref="System_overview.html"class="tocviewlink"data-pltdoc="x">System overview</a></td></tr><tr><tdalign="right">5 </td><td><ahref="Using_raco_pollen.html"class="tocviewlink"data-pltdoc="x">Using <spanclass="stt">raco pollen</span></a></td></tr><tr><tdalign="right">6 </td><td><ahref="File_formats.html"class="tocviewlink"data-pltdoc="x">File formats</a></td></tr><tr><tdalign="right">7 </td><td><ahref="reader.html"class="tocviewselflink"data-pltdoc="x">◊ command overview</a></td></tr><tr><tdalign="right">8 </td><td><ahref="Module_reference.html"class="tocviewlink"data-pltdoc="x">Module reference</a></td></tr><tr><tdalign="right">9 </td><td><ahref="Acknowledgments.html"class="tocviewlink"data-pltdoc="x">Acknowledgments</a></td></tr><tr><tdalign="right">10 </td><td><ahref="License___source_code.html"class="tocviewlink"data-pltdoc="x">License & source code</a></td></tr><tr><tdalign="right"></td><td><ahref="doc-index.html"class="tocviewlink"data-pltdoc="x">Index</a></td></tr></table></div></div><divclass="tocviewlist"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>7 </td><td><ahref="reader.html"class="tocviewselflink"data-pltdoc="x">◊ command overview</a></td></tr></table><divclass="tocviewsublistbottom"style="display: none;"id="tocview_1"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">7.1 </td><td><ahref="reader.html#%28part._.The_golden_rule%29"class="tocviewlink"data-pltdoc="x">The golden rule</a></td></tr><tr><tdalign="right">7.2 </td><td><ahref="reader.html#%28part._.The_lozenge_glyph____%29"class="tocviewlink"data-pltdoc="x">The lozenge glyph (◊)</a></td></tr><tr><tdalign="right">7.3 </td><td><ahref="reader.html#%28part._.The_two_command_modes__text_mode___.Racket_mode%29"class="tocviewlink"data-pltdoc="x">The two command modes:<spanclass="mywbr"> </span> text mode & Racket mode</a></td></tr><tr><tdalign="right">7.4 </td><td><ahref="reader.html#%28part._.Further_reading%29"class="tocviewlink"data-pltdoc="x">Further reading</a></td></tr></table></div></div></div><divclass="tocsub"><divclass="tocsubtitle">On this page:</div><tableclass="tocsublist"cellspacing="0"><tr><td><spanclass="tocsublink
<spanstyle="font-weight: bold">Ubuntu</span>:</p><p>Still, if you don’t want to use the lozenge as your command marker, you can use something else. Set Pollen’s <spanclass="RktSym">world:command-marker</span> value to whatever character you want.</p><blockquoteclass="refpara"><blockquoteclass="refcolumn"><blockquoteclass="refcontent"><p>Scribble uses the @ sign as a delimiter. It’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 — HTML pages especially — it gets cumbersome. So I changed it.</p></blockquote></blockquote></blockquote><p>But don’t knock the lozenge till you try it.</p><h4>7.3<tt> </tt><aname="(part._.The_two_command_modes__text_mode___.Racket_mode)"></a>The two command modes: text mode & Racket mode</h4><p>Pollen commands can be entered in one of two modes: <spanstyle="font-style: italic">text mode</span> or <spanstyle="font-style: italic">Racket mode</span>. Both modes start with a lozenge (<spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="hspace"></span></span>):</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="hspace"></span></span><spanclass="hspace"> </span><spanclass="sroman">‹<spanstyle="font-style: italic">command name</span>›</span><spanclass="hspace"> </span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">[</span><spanclass="hspace"></span></span><spanclass="hspace"> </span><spanclass="sroman">‹<spanstyle="font-style: italic">Racket arguments ...</span>›</span><spanclass="hspace"> </span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">]</span><spanclass="hspace"></span></span><spanclass="hspace"> </span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">{</span><spanclass="hspace"></span></span><spanclass="hspace"> </span><spanclass="sroman">‹<spanstyle="font-style: italic">text argument</span>›</span><spanclass="hspace"> </span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">}</span><spanclass="hspace"></span></span></td></tr><tr><td><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="hspace"></span></span><spanclass="hspace"> </span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">(</span><spanclass="hspace"></span></span><spanclass="hspace"> </span><spanclass="sroman">‹<spanstyle="font-style: italic">Racket expression</span>›</span><spanclass="hspace"> </span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">)</span><spanclass="hspace"></span></span></td></tr></table></blockquote><p><spanstyle="font-weight: bold">Text-mode commands</span></p><p>A text-mode command has the three possible parts after the <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="hspace"></span></span>:</p><ul><li><p>The <spanstyle="font-style: italic">command name</span> appears immediately after the <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="hspace"></span></span>. Typically it’s a short word.</p></li><li><p>The <spanstyle="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 — e.g., a <spanclass="stt">string of text</span> needs to be put in quotes as a <spanclass="RktVal">"string</span><spanclass="hspace"> </span><spanclass="RktVal">of</span><spanclass="hspace"> </span><spanclass="RktVal">text"</span><spanclass="RktMeta"></span>. If you like programming, you’ll end up using these frequently. If you don’t, you won’t.</
the expected number of arguments does not match the given number<br/>
  given: 1<br/>
  arguments...:<br/>
    "Fancy Sauce, $1"</span></p><p>What to do? Read on.</p><h5>7.3.1.2<tt> </tt><aname="(part._.Invoking_other_functions)"></a>Invoking other functions</h5><p>Though every command name starts out as a tag function, it doesn’t necessarily end there. You have two options for invoking other functions: defining your own , or invoking others from Racket.</p><p><spanstyle="font-weight: bold">Defining your own functions</span></p><p>Use the <spanclass="RktSym"><ahref="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’ll get the new behavior. For instance, recall this example showing the default tag-function behavior:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym">strong</span><spanclass="RktPn">{</span><spanclass="RktMeta">Fancy</span><spanclass="hspace"> </span><spanclass="RktMeta">Sauce</span><spanclass="RktMeta">,</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta">$1</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="RktOut">'(strong "Fancy Sauce, $1")</span></p><p>We can define <spanclass="stt">strong</span> to do something else, like add to the text:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktPn">(</span><spanclass="RktSym">strong</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym">text</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym"><ahref="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><spanclass="RktPn">(</span><spanclass="RktSym">strong</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/quasiquote.html#%28form._%28%28quote._~23~25kernel%29._unquote%29%29"class="RktStxLink"data-pltdoc="x">,</a></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktVal">"Hey!</span><spanclass="hspace"> </span><spanclass="RktVal">Listen</span><spanclass="hspace"> </span><spanclass="RktVal">up!</span><spanclass="hspace"> </span><spanclass="RktVal">~a"</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym">text</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclas
the expected number of arguments does not match the given number<br/>
  expected: 0<br/>
  given: 1<br/>
  arguments...:<br/>
    "Fancy Sauce, $1"</span></p><p>Whereas in this version, <spanclass="stt">strong</span> accepts an argument called <spanclass="stt">text</span>, but then ignores it:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktPn">(</span><spanclass="RktSym">strong</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym">text</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym"><ahref="http://docs.racket-lang.org/reference/quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29"class="RktStxLink"data-pltdoc="x">'</a></span><spanclass="RktPn">(</span><spanclass="RktSym">fib</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktVal">"1</span><spanclass="hspace"> </span><spanclass="RktVal">1</span><spanclass="hspace"> </span><spanclass="RktVal">2</span><spanclass="hspace"> </span><spanclass="RktVal">3</span><spanclass="hspace"> </span><spanclass="RktVal">5</span><spanclass="hspace"> </span><spanclass="RktVal">8</span><spanclass="hspace"> </span><spanclass="RktVal">13</span><spanclass="hspace"> </span><spanclass="RktVal">..."</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym">strong</span><spanclass="RktPn">{</span><spanclass="RktMeta">Fancy</span><spanclass="hspace"> </span><spanclass="RktMeta">Sauce</span><spanclass="RktMeta">,</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta">$1</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="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><spanstyle="font-weight: bold">Using Racket functions</span></p><p>You aren’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’s the function <spanclass="RktSym"><ahref="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><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym"><ahref="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><spanclass="RktPn">[</span><spanclass="RktVal">1</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktVal">20</span><spanclass="RktPn">]</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="RktOut">'(range 1 20)
expected a procedure that can be applied to arguments<br/>
  given: "bar"<br/>
  arguments...: [none]</span></p><p>The reason we can simply drop <spanclass="RktSym">◊foo</span><spanclass="RktMeta"></span> into the text argument of another Pollen command is that the variable <spanclass="RktSym">foo</span><spanclass="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><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym">zam</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktVal">42</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">The</span><spanclass="hspace"> </span><spanclass="RktMeta">value</span><spanclass="hspace"> </span><spanclass="RktMeta">of</span><spanclass="hspace"> </span><spanclass="RktMeta">zam</span><spanclass="hspace"> </span><spanclass="RktMeta">is</span><spanclass="hspace"> </span><spanclass="RktMeta">◊</span><spanclass="RktSym">zam</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="RktOut">The value of zam is 42</span></p><p>If the variable holds a container datatype (like a <spanclass="RktSym"><ahref="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>, <spanclass="RktSym"><ahref="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 <spanclass="RktSym"><ahref="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, <spanclass="stt">zam</span> is a <spanclass="RktSym"><ahref="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><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym">zam</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktVal">1</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktVal">2</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span>
'(span "Nor is this")</span></p><p>To comment out a multiline block, use the lozenge–semicolon signal <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊;</span><spanclass="hspace"></span></span> with curly braces, <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊;{</span><spanclass="hspace"></span></span>like so<spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">}</span><spanclass="hspace"></span></span>.</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktCmt">;{</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊span</span><spanclass="RktPn">{</span><spanclass="RktMeta">This</span><spanclass="hspace"> </span><spanclass="RktMeta">is</span><spanclass="hspace"> </span><spanclass="RktMeta">not</span><spanclass="hspace"> </span><spanclass="RktMeta">a</span><spanclass="hspace"> </span><spanclass="RktMeta">comment</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊span</span><spanclass="RktPn">{</span><spanclass="RktMeta">Nor</span><spanclass="hspace"> </span><spanclass="RktMeta">is</span><spanclass="hspace"> </span><spanclass="RktMeta">this</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta">◊</span><spanclass="RktCmt">;span{But</span><spanclass="hspace"> </span><spanclass="RktCmt">this</span><spanclass="hspace"> </span><spanclass="RktCmt">is}</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta"></span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">Actually</span><spanclass="RktMeta">,</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta">it</span><spanclass="RktVal">'</span><spanclass="RktMeta">s</span><spanclass="hspace"> </span><spanclass="RktMeta">all</span><spanclass="hspace"> </span><spanclass="RktMeta">a</span><spanclass="hspace"> </span><spanclass="RktMeta">comment</span><spanclass="hspace"> </span><spanclass="RktMeta">now</span></td></tr></table></blockquote><p><spanclass="RktOut">Actually, it's all a comment now</span></p><h5>7.3.2<tt> </tt><aname="(part._.The_.Racket_arguments)"></a>The Racket arguments</h5><p>The middle part of a text-mode Pollen command contains the <spanstyle="font-style: italic">Racket arguments</span><spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">[</span><spanclass="hspace"></span></span>between square brackets.<spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">]</span><spanclass="hspace"></span></span> Most often, you’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><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym"><ahref="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><spanclass="RktPn">{</span><spanclass="RktMeta">The</span><spanclass="hspace"> </span><spanclass="RktMeta">Beginning</span><spanclass="hspace"> </span><spanclass="RktMeta">of</span><spanclass="hspace"> </span><span
'(h2 "Minor league") <br/>
'(h6 "Trivial league")</span></p><h5>7.3.3<tt> </tt><aname="(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 <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">{</span><spanclass="hspace"></span></span>appears between curly braces<spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">}</span><spanclass="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><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym">div</span><spanclass="RktPn">{</span><spanclass="RktMeta">Do</span><spanclass="hspace"> </span><spanclass="RktMeta">it</span><spanclass="hspace"> </span><spanclass="RktMeta">again.</span><spanclass="hspace"> </span><spanclass="RktMeta">◊</span><spanclass="RktSym">div</span><spanclass="RktPn">{</span><spanclass="RktMeta">And</span><spanclass="hspace"> </span><spanclass="RktMeta">again.</span><spanclass="hspace"> </span><spanclass="RktMeta">◊</span><spanclass="RktSym">div</span><spanclass="RktPn">{</span><spanclass="RktMeta">And</span><spanclass="hspace"> </span><spanclass="RktMeta">yet</span><spanclass="hspace"> </span><spanclass="RktMeta">again.</span><spanclass="RktPn">}</span><spanclass="RktPn">}</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="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 <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="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 <spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊"◊"</span><spanclass="hspace"></span></span>.</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym">definition</span><spanclass="RktPn">{</span><spanclass="RktMeta">This</span><spanclass="hspace"> </span><spanclass="RktMeta">is</span><spanclass="hspace"> </span><spanclass="RktMeta">the</span><spanclass="hspace"> </span><spanclass="RktMeta">lozenge:</span><spanclass="hspace"> </span><spanclass="RktMeta">◊</span><spanclass="RktVal">"◊"</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="RktOut">'(definition "This is the lozenge: ◊")</span></p><p>Second, the whitespace-trimming policy. Here’s the short version: if there’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><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><span
the expected number of arguments does not match the given number<br/>
  expected: 1<br/>
  given: 3<br/>
  arguments...:<br/>
   "Deeply"<br/>
   "\n"<br/>
   "chastened"</span></p><p>The answer is to use a <spanstyle="font-style: italic">rest argument</span> in the function, which takes the “rest” of the arguments — however many there may be — and combines them into a single <spanclass="RktSym"><ahref="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 <spanclass="stt">jejune</span> with a rest argument, we can fix the problem:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"class="RktBlk"><tr><td><spanclass="RktMeta">#lang</span><spanclass="hspace"> </span><spanclass="RktMeta"></span><ahref="index.html"class="RktModLink"data-pltdoc="x"><spanclass="RktSym">pollen</span></a><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktPn">(</span><spanclass="RktSym"><ahref="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><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktPn">(</span><spanclass="RktSym">jejune</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktMeta">.</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym">texts</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym"><ahref="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><spanclass="RktPn">(</span><spanclass="RktSym">jejune</span><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta"></span><spanclass="RktSym"><ahref="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><spanclass="RktSym">texts</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span><spanclass="RktMeta"></span></td></tr><tr><td><spanclass="RktMeta">◊</span><spanclass="RktSym">jejune</span><spanclass="RktPn">{</span><spanclass="RktMeta">Deeply</span></td></tr><tr><td><spanclass="RktMeta"></span><spanclass="hspace"> </span><spanclass="RktMeta">chastened</span><spanclass="RktPn">}</span><spanclass="RktMeta"></span></td></tr></table></blockquote><p><spanclass="RktOut">'(jejune "Deeply" "\n" "chastened")</span></p><h4>7.4<tt> </tt><aname="(part._.Further_reading)"></a>Further reading</h4><p>The Pollen language is a variant of Racket’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 & brevity, I’ve omitted them from this summary. But if you want the full story, see <ahref="http://docs.racket-lang.org/scribble/reader.html"data-pltdoc="x">@ Syntax</a> in the Scribble documentation.</p><divclass="navsetbottom"><spanclass="navleft"> </span><spanclass="navright"> <ahref="File_formats.html"title="backward to "6 File formats""data-pltdoc="x">← prev</a> <ahref="index.html"title="up to "Pollen: the book is a program""data-pltdoc="x">up</a> <ahref="Module_reference.html"title="forward to "8 Module reference""data-pltdoc="x">next →</a></span> </div></div></div><divid="contextindicator"> </div></body></html>
