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.
3 lines
168 KiB
HTML
3 lines
168 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"/><title>Pollen command syntax</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"/><link rel="stylesheet" type="text/css" href="mb.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;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html" class="tocviewselflink" data-pltdoc="x">Pollen command syntax</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28part._.The_golden_rule%29" class="tocviewlink" data-pltdoc="x">The golden rule</a></td></tr><tr><td align="right">2 </td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28part._.The_lozenge_glyph____%29" class="tocviewlink" data-pltdoc="x">The lozenge glyph (◊)</a></td></tr><tr><td align="right">3 </td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28part._the-two-command-modes%29" class="tocviewlink" data-pltdoc="x">The two command modes:<span class="mywbr"> </span> Pollen mode & Racket mode</a></td></tr><tr><td align="right">4 </td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28part._.Embedding_character_entities%29" class="tocviewlink" data-pltdoc="x">Embedding character entities</a></td></tr><tr><td align="right">5 </td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28part._.Adding_.Pollen-mode_commands_to_a_.Racket_file%29" class="tocviewlink" data-pltdoc="x">Adding Pollen-<wbr></wbr>mode commands to a Racket file</a></td></tr><tr><td align="right">6 </td><td><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28part._.Further_reading%29" class="tocviewlink" data-pltdoc="x">Further reading</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._pollen-command-syntax%29" class="tocsubseclink" data-pltdoc="x">Pollen command syntax</a></td></tr><tr><td><span class="tocsublinknumber">1<tt> </tt></span><a href="#%28part._.The_golden_rule%29" class="tocsubseclink" data-pltdoc="x">The golden rule</a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#%28part._.The_lozenge_glyph____%29" class="tocsubseclink" data-pltdoc="x">The lozenge glyph (◊)</a></td></tr><tr><td><span class="tocsublinknumber">2.1<tt> </tt></span><a href="#%28part._.Lozenge_helpers%29" class="tocsubseclink" data-pltdoc="x">Lozenge helpers</a></td></tr><tr><td><span class="tocsublinknumber">2.1.1<tt> </tt></span><a href="#%28part._.A.H.K_script%29" class="tocsubseclink" data-pltdoc="x">AHK script</a></td></tr><tr><td><span class="tocsublinknumber">2.1.2<tt> </tt></span><a href="#%28part._.Emacs_script%29" class="tocsubseclink" data-pltdoc="x">Emacs script</a></td></tr><tr><td><span class="tocsublinknumber">3<tt> </tt></span><a href="#%28part._the-two-command-modes%29" class="tocsubseclink" data-pltdoc="x">The two command modes:<span class="mywbr"> </span> Pollen mode & Racket mode</a></td></tr><tr><td><span class="tocsublinknumber">3.1<tt> </tt></span><a href="#%28part._.The_command_name%29" class="tocsubseclink" data-pltdoc="x">The command name</a></td></tr><tr><td><span class="tocsublinknumber">3.1.1<tt> </tt></span><a href="#%28part._.Invoking_tag_functions%29" class="tocsubseclink" data-pltdoc="x">Invoking tag functions</a></td></tr><tr><td><span class="tocsublinknumber">3.1.2<tt> </tt></span><a href="#%28part._.Invoking_other_functions%29" class="tocsubseclink" data-pltdoc="x">Invoking other functions</a></td></tr><tr><td><span class="tocsublinknumber">3.1.3<tt> </tt></span><a href="#%28part._.Inserting_the_value_of_a_variable%29" class="tocsubseclink" data-pltdoc="x">Inserting the value of a variable</a></td></tr><tr><td><span class="tocsublinknumber">3.1.4<tt> </tt></span><a href="#%28part._.Inserting_metas%29" class="tocsubseclink" data-pltdoc="x">Inserting metas</a></td></tr><tr><td><span class="tocsublinknumber">3.1.5<tt> </tt></span><a href="#%28part._.Retrieving_metas%29" class="tocsubseclink" data-pltdoc="x">Retrieving metas</a></td></tr><tr><td><span class="tocsublinknumber">3.1.6<tt> </tt></span><a href="#%28part._.Inserting_a_comment%29" class="tocsubseclink" data-pltdoc="x">Inserting a comment</a></td></tr><tr><td><span class="tocsublinknumber">3.2<tt> </tt></span><a href="#%28part._.The_.Racket_arguments%29" class="tocsubseclink" data-pltdoc="x">The Racket arguments</a></td></tr><tr><td><span class="tocsublinknumber">3.3<tt> </tt></span><a href="#%28part._.The_text_argument%29" class="tocsubseclink" data-pltdoc="x">The text argument</a></td></tr><tr><td><span class="tocsublinknumber">4<tt> </tt></span><a href="#%28part._.Embedding_character_entities%29" class="tocsubseclink" data-pltdoc="x">Embedding character entities</a></td></tr><tr><td><span class="tocsublinknumber">5<tt> </tt></span><a href="#%28part._.Adding_.Pollen-mode_commands_to_a_.Racket_file%29" class="tocsubseclink" data-pltdoc="x">Adding Pollen-<wbr></wbr>mode commands to a Racket file</a></td></tr><tr><td><span class="tocsublinknumber">6<tt> </tt></span><a href="#%28part._.Further_reading%29" class="tocsubseclink" data-pltdoc="x">Further reading</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="versionNoNav">6.2.900.15</span></div><h2><a name="(part._pollen-command-syntax)"></a>Pollen command syntax</h2><h3>1<tt> </tt><a name="(part._.The_golden_rule)"></a>The golden rule</h3><p>Pollen uses a special character — the <span style="font-style: italic">lozenge</span>, which looks like this: ◊ — to mark commands within a Pollen source file. So when you put a ◊ in your source, whatever comes next will be treated as a command. If you don’t, it will just be interpreted as plain text.</p><h3>2<tt> </tt><a name="(part._.The_lozenge_glyph____)"></a>The lozenge glyph (◊)</h3><p>I chose the lozenge as the command character because a) it appears in almost every font, b) it’s barely used in ordinary typesetting, c) it’s not used in any programming language that I know of, and d) its shape and color allow it to stand out easily in code without being distracting.</p><p>Here’s how you type it:</p><p><span style="font-weight: bold">Mac</span>: option + shift + V</p><p><span style="font-weight: bold">Windows</span>: holding down alt, type 9674 on the num pad</p><p><span style="font-weight: bold">Ubuntu</span>: ctrl + shift + U, then 25CA</p><p>Still, if you don’t want to use the lozenge as your command character, you can set Pollen’s <span class="RktSym"><span class="badlink"><span class="RktValLink">world:command-char</span></span></span> value to whatever character you want (see also <font class="badlink">(part "settable-values")</font>).</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="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>2.1<tt> </tt><a name="(part._.Lozenge_helpers)"></a>Lozenge helpers</h4><h5>2.1.1<tt> </tt><a name="(part._.A.H.K_script)"></a>AHK script</h5><p>Courtesy of <a href="https://github.com/maphew">Matt Wilkie</a>: “Here’s a working AHK script to have double-tap backtick send the lozenge character. It took way more time than I want to think about, once started I couldn’t let go.”</p><div class="fileblock"><div class="SIntrapara"><div class="fileblock_filetitle"><span class="fileblock_filename"><span class="stt">"tick-tick-lozenge.ahk"</span></span></div></div><div class="SIntrapara"><div class="fileblock_filecontent"><div class="SIntrapara"><div class="foreign-code"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">;</span></p></td></tr><tr><td><p><span class="stt">; Double-tap backtick sends Pollen command character (◊)</span></p></td></tr><tr><td><p><span class="stt">; For some reason I needed to use Unicode 'U+25CA'</span></p></td></tr><tr><td><p><span class="stt">; instead of the standard alt-code '9674'</span></p></td></tr><tr><td><p><span class="stt">;</span></p></td></tr><tr><td><p><span class="stt">; Adapted from http://ahkscript.org/docs/commands/SetTimer.htm</span></p></td></tr><tr><td><p><span class="stt">; and http://www.autohotkey.com/board/topic/145507-how-to-use-double-tap-backtick-with-pass-through/</span></p></td></tr><tr><td><p><span class="stt">;</span></p></td></tr><tr><td><p><span class="stt">#EscapeChar \</span></p></td></tr><tr><td><p><span class="stt">$`::</span></p></td></tr><tr><td><p><span class="stt">if winc_presses > 0</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">{winc_presses += 1</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">return</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">}</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span></p></td></tr><tr><td><p><span class="stt">winc_presses = 1</span></p></td></tr><tr><td><p><span class="stt">SetTimer, TheKey, 250 ; Wait for more presses, in milliseconds</span></p></td></tr><tr><td><p><span class="stt">return</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span></p></td></tr><tr><td><p><span class="stt">TheKey:</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">SetTimer, TheKey, off</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">if winc_presses = 1 ; The key was pressed once.</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">{Send `</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">}</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">else if winc_presses = 2 ; The key was pressed twice.</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">{Send {U+25CA}</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">}</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span></p></td></tr><tr><td><p><span class="stt">; Regardless of which action above was triggered, reset the count to</span></p></td></tr><tr><td><p><span class="stt">; prepare for the next series of presses:</span></p></td></tr><tr><td><p><span class="stt">winc_presses = 0</span></p></td></tr><tr><td><p><span class="stt">return</span></p></td></tr></table></div></div></div></div></div></div><h5>2.1.2<tt> </tt><a name="(part._.Emacs_script)"></a>Emacs script</h5><p>Courtesy of <a href="https://github.com/lerichard95">Richard Le</a>: “If you’re using Emacs, I tried to write a tiny function that inserts the lozenge character. I chose M-\ because that’s the key for the lambda character in DrRacket.”</p><div class="foreign-code"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">;; Put this in your Emacs .init file:</span></p></td></tr><tr><td><p><span class="stt">;; enable lozenge for Pollen</span></p></td></tr><tr><td><p><span class="stt">;; ◊◊◊◊◊◊◊◊◊◊◊◊◊</span></p></td></tr><tr><td><p><span class="stt">;; 'mule-unicode part from</span></p></td></tr><tr><td><p><span class="stt">;; https://lists.gnu.org/archive/html//emacs-devel/2005-03/msg01187.html</span></p></td></tr><tr><td><p><span class="stt">(defun insert-lozenge ()</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">"inserts the lozenge character for use with Pollen"</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">;; enables function through M-x</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(interactive)</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">;; insert the proper character</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(insert (make-char</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">'mule-unicode-2500-33ff 34 42)))</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span></p></td></tr><tr><td><p><span class="stt">;; Bind key to M-\ a la DrRacket for lambda</span></p></td></tr><tr><td><p><span class="stt">(global-set-key "\M-\\" 'insert-lozenge)</span></p></td></tr></table></div></div><h3>3<tt> </tt><a name="(part._the-two-command-modes)"></a>The two command modes: Pollen mode & Racket mode</h3><p>Pollen commands can be entered in one of two modes: <span style="font-style: italic">Pollen 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">◊</span><span class="hspace"></span></span>):</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊</span><span class="hspace"></span></span><span class="hspace"> </span><span class="sroman">‹<span style="font-style: italic">command name</span>›</span><span class="hspace"> </span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">[</span><span class="hspace"></span></span><span class="hspace"> </span><span class="sroman">‹<span style="font-style: italic">Racket arguments ...</span>›</span><span class="hspace"> </span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">]</span><span class="hspace"></span></span><span class="hspace"> </span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">{</span><span class="hspace"></span></span><span class="hspace"> </span><span class="sroman">‹<span style="font-style: italic">text argument</span>›</span><span class="hspace"> </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">◊</span><span class="hspace"></span></span><span class="hspace"> </span><span class="RktInBG"><span class="hspace"></span><span class="RktIn">(</span><span class="hspace"></span></span><span class="hspace"> </span><span class="sroman">‹<span style="font-style: italic">Racket expression</span>›</span><span class="hspace"> </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">Pollen-mode commands</span></p><p>A Pollen-mode command has the three possible parts after the <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊</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">◊</span><span class="hspace"></span></span>. Typically it’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 — e.g., a <span class="RktSym"><span class="badlink"><span class="RktValLink">string</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">of</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktMeta"></span> needs to be put in quotes as a <span class="RktVal">"string</span><span class="hspace"> </span><span class="RktVal">of</span><span class="hspace"> </span><span class="RktVal">text"</span><span class="RktMeta"></span>. If you like programming, you’ll end up using these frequently. If you don’t, you won’t.</p></li><li><p>The <span style="font-style: italic">text argument</span> appears between braces (aka curly brackets). You can put any ordinary text here. Unlike with the Racket arguments, you don’t put quotes around the text.</p></li></ul><p>Each of the three parts is optional. You can also nest commands within each other. However:</p><ul><li><p>You can never have spaces between the three parts.</p></li><li><p>Whatever parts you use must always appear in the order above.</p></li></ul><p>Here are a few examples of correct Pollen-mode commands:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">variable-name</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktPn">{</span><span class="RktMeta">Text</span><span class="hspace"> </span><span class="RktMeta">inside</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">tag.</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktPn">[</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">attr:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"value"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Text</span><span class="hspace"> </span><span class="RktMeta">inside</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">tag</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">get-customer-id</span><span class="RktPn">[</span><span class="RktVal">"Brennan</span><span class="hspace"> </span><span class="RktVal">Huff"</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktPn">{</span><span class="RktMeta">His</span><span class="hspace"> </span><span class="RktMeta">ID</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">get-customer-id</span><span class="RktPn">[</span><span class="RktVal">"Brennan</span><span class="hspace"> </span><span class="RktVal">Huff"</span><span class="RktPn">]</span><span class="RktMeta">.</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p>And some incorrect examples:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">{Text</span><span class="hspace"> </span><span class="RktMeta">inside</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">tag.}</span><span class="hspace"> </span><span class="RktMeta">;</span><span class="hspace"> </span><span class="RktMeta">space</span><span class="hspace"> </span><span class="RktMeta">between</span><span class="hspace"> </span><span class="RktMeta">first</span><span class="hspace"> </span><span class="RktMeta">and</span><span class="hspace"> </span><span class="RktMeta">second</span><span class="hspace"> </span><span class="RktMeta">parts</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktPn">[</span><span class="RktSym">Text</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">inside</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">the</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktPn">]</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">;</span><span class="hspace"> </span><span class="RktMeta">text</span><span class="hspace"> </span><span class="RktMeta">argument</span><span class="hspace"> </span><span class="RktMeta">needs</span><span class="hspace"> </span><span class="RktMeta">to</span><span class="hspace"> </span><span class="RktMeta">be</span><span class="hspace"> </span><span class="RktMeta">within</span><span class="hspace"> </span><span class="RktMeta">braces</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">tag</span></span></span><span class="RktPn">{</span><span class="RktMeta">Text</span><span class="hspace"> </span><span class="RktMeta">inside</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">tag</span><span class="RktPn">}</span><span class="RktMeta">['attr:</span><span class="hspace"> </span><span class="RktMeta">"value"]</span><span class="hspace"> </span><span class="RktMeta">;</span><span class="hspace"> </span><span class="RktMeta">wrong</span><span class="hspace"> </span><span class="RktMeta">order</span><span class="RktMeta"></span></td></tr></table></blockquote><p>The next section describes each of these parts in detail.</p><p><span style="font-weight: bold">Racket-mode commands</span></p><p>If you’re familiar with Racket expressions, you can use the Racket-mode commands to embed them within Pollen source files. It’s simple: any Racket expression can become a Pollen command by adding <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊</span><span class="hspace"></span></span> to the front. So in Racket, this code:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">racket</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Revolution"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"~a</span><span class="hspace"> </span><span class="RktVal">#~a"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">*</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><p>Can be converted to Pollen like so:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Revolution"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"~a</span><span class="hspace"> </span><span class="RktVal">#~a"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">*</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><p>And in DrRacket, they produce the same output:</p><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">Revolution #9</span></span></p></blockquote><p>Beyond that, there’s not much to say about Racket mode — any valid expression you can write in Racket will also be a valid Racket-mode Pollen command.</p><p><span style="font-weight: bold">The relationship of Pollen mode and Racket mode</span></p><p>Even if you don’t plan to write a lot of Racket-mode commands, you should be aware that under the hood, Pollen is converting all commands in Pollen mode to Racket mode. So a Pollen-mode command that looks like this:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">headline</span><span class="RktPn">[</span><span class="RktPn">#:size</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">enormous</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Man</span><span class="hspace"> </span><span class="RktMeta">Bites</span><span class="hspace"> </span><span class="RktMeta">Dog!</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p>Is actually being turned into a Racket-mode command like this:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">headline</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">#:size</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">enormous</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Man</span><span class="hspace"> </span><span class="RktVal">Bites</span><span class="hspace"> </span><span class="RktVal">Dog!"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><p>Thus a Pollen-mode command is just an alternate way of writing a Racket-mode command. (More broadly, all of Pollen is just an alternate way of using Racket.)</p><p>The corollary is that you can always write Pollen commands using whichever mode is more convenient or readable. For instance, the earlier example, written in the Racket mode:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Revolution"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"~a</span><span class="hspace"> </span><span class="RktVal">#~a"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">*</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><p>Can be rewritten using Pollen mode:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktPn">[</span><span class="RktSym">song</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Revolution</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktPn">[</span><span class="RktVal">"~a</span><span class="hspace"> </span><span class="RktVal">#~a"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">song</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">*</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr></table></blockquote><p>And it will work the same way.</p><h4>3.1<tt> </tt><a name="(part._.The_command_name)"></a>The command name</h4><p>In Pollen, you’ll typically use the command name for one of four purposes:</p><ul><li><p>To invoke a tag function.</p></li><li><p>To invoke another function.</p></li><li><p>To insert the value of a variable.</p></li><li><p>To insert a <span class="RktSym">meta</span><span class="RktMeta"></span> value.</p></li><li><p>To insert a comment.</p></li></ul><h5>3.1.1<tt> </tt><a name="(part._.Invoking_tag_functions)"></a>Invoking tag functions</h5><p>By default, Pollen treats every command name as a <span style="font-style: italic">tag function</span>. The default tag function creates a tagged X-expression with the command name as the tag, and the text argument as the content.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace"> </span><span class="RktMeta">Sauce,</span><span class="hspace"> </span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(strong "Fancy Sauce, $1")</span></span></p></blockquote><p>To streamline markup, Pollen doesn’t restrict you to a certain set of tags, nor does it make you define your tags ahead of time. Just type a tag, and you can start using it.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">utterlyridiculoustagname</span><span class="RktPn">{</span><span class="RktMeta">Oh</span><span class="hspace"> </span><span class="RktMeta">really?</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(utterlyridiculoustagname "Oh really?")</span></span></p></blockquote><p>The one restriction is that you can’t invent names for tags that are already being used for other commands. For instance, <span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span><span class="RktMeta"></span> is a name permanently reserved by the Racket function <span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span>. It’s also a rarely-used HTML tag. But gosh, you really want to use it. Problem is, if you invoke it directly, Pollen will think you mean the other <span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace"> </span><span class="RktMeta">Sauce,</span><span class="hspace"> </span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">map: arity mismatch;<br/>the expected number of arguments does not match the given number<br/>  given: 1<br/>  arguments...:<br/>    "Fancy Sauce, $1"</span></span></p></blockquote><p>What to do? Read on.</p><h5>3.1.2<tt> </tt><a name="(part._.Invoking_other_functions)"></a>Invoking other functions</h5><p>Though every command name starts out as a default 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><span style="font-weight: bold">Defining your own functions</span></p><p>Use the <span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></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><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace"> </span><span class="RktMeta">Sauce,</span><span class="hspace"> </span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(strong "Fancy Sauce, $1")</span></span></p></blockquote><p>We can define <span class="RktSym">strong</span><span class="RktMeta"></span> to do something else, like add to the text:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">`</span></span></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,</span></span></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Hey!</span><span class="hspace"> </span><span class="RktVal">Listen</span><span class="hspace"> </span><span class="RktVal">up!</span><span class="hspace"> </span><span class="RktVal">~a"</span><span class="RktMeta"></span><span class="hspace"> </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 class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace"> </span><span class="RktMeta">Sauce,</span><span class="hspace"> </span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(strong "Hey! Listen up! Fancy Sauce, $1")</span></span></p></blockquote><p>The replacement function has to accept any arguments that might get passed along, but it doesn’t have to do anything with them. For instance, this function definition won’t work because <span class="RktSym">strong</span><span class="RktMeta"></span> is going to get a text argument that it’s not defined to handle:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktPn">(</span><span class="RktSym">fib</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"1</span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="hspace"> </span><span class="RktVal">3</span><span class="hspace"> </span><span class="RktVal">5</span><span class="hspace"> </span><span class="RktVal">8</span><span class="hspace"> </span><span class="RktVal">13</span><span class="hspace"> </span><span class="RktVal">..."</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace"> </span><span class="RktMeta">Sauce,</span><span class="hspace"> </span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">strong: arity mismatch;<br/>the expected number of arguments does not match the given number<br/>  expected: 0<br/>  given: 1<br/>  arguments...:<br/>    "Fancy Sauce, $1"</span></span></p></blockquote><p>Whereas in this version, <span class="RktSym">strong</span><span class="RktMeta"></span> accepts an argument called <span class="RktSym">text</span><span class="RktMeta"></span>, but then ignores it:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">strong</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktPn">(</span><span class="RktSym">fib</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"1</span><span class="hspace"> </span><span class="RktVal">1</span><span class="hspace"> </span><span class="RktVal">2</span><span class="hspace"> </span><span class="RktVal">3</span><span class="hspace"> </span><span class="RktVal">5</span><span class="hspace"> </span><span class="RktVal">8</span><span class="hspace"> </span><span class="RktVal">13</span><span class="hspace"> </span><span class="RktVal">..."</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">strong</span><span class="RktPn">{</span><span class="RktMeta">Fancy</span><span class="hspace"> </span><span class="RktMeta">Sauce,</span><span class="hspace"> </span><span class="RktMeta">$1</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(fib "1 1 2 3 5 8 13 ...")</span></span></p></blockquote><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’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 <span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span>, which creates a list of numbers:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span><span class="RktPn">[</span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">20</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(range 1 20)</span></span></p></blockquote><p><div class="SIntrapara">Hold on — that’s not what we want. Where’s the list of numbers? The problem here is that we didn’t explicitly import the <font class="badlink"><span class="RktModLink"><span class="RktSym">racket/list</span></span></font> library, which contains the definition for <span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span>. (If you need to find out what library contains a certain function, the Racket documentation will tell you.) Without <font class="badlink"><span class="RktModLink"><span class="RktSym">racket/list</span></span></font>, Pollen just thinks we’re trying to use <span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span><span class="RktMeta"></span> as a tag function (and if we had been, then </div><div class="SIntrapara"><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(range 1 20)</span></span></p></blockquote></div><div class="SIntrapara"> would’ve been the right result).</div></p><p>We fix this by using the <span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span> command to bring in the <font class="badlink"><span class="RktModLink"><span class="RktSym">racket/list</span></span></font> library, which contains the <span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span> we want:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">racket/list</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span><span class="RktPn">[</span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">20</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19)</span></span></p></blockquote><p>Of course, you can also invoke Racket functions indirectly, by attaching them to functions you define for command names:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">racket/list</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">rick</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">start</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">finish</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">range</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">start</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">finish</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">rick</span><span class="RktPn">[</span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">20</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19)</span></span></p></blockquote><p>Let’s return to the problem that surfaced in the last section — the fact that some command names can’t be used as tag functions because they’re already being used for other things. You can work around this by defining your own tag function with a non-conflicting name.</p><p>For instance, suppose we want to use <span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span><span class="RktMeta"></span> as a tag even though Racket is using it for its own function called <span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span>. First, we invent a command name that doesn’t conflict. Let’s call it <span class="RktSym">my-map</span><span class="RktMeta"></span>. As you learned above, Pollen will treat a new command name as a tag function by default:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">my-map</span><span class="RktPn">{</span><span class="RktMeta">How</span><span class="hspace"> </span><span class="RktMeta">I</span><span class="hspace"> </span><span class="RktMeta">would</span><span class="hspace"> </span><span class="RktMeta">love</span><span class="hspace"> </span><span class="RktMeta">this</span><span class="hspace"> </span><span class="RktMeta">to</span><span class="hspace"> </span><span class="RktMeta">be</span><span class="hspace"> </span><span class="RktMeta">a</span><span class="hspace"> </span><span class="RktMeta">map.</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(my-map "How I would love this to be a map.")</span></span></p></blockquote><p>But <span class="RktSym">my-map</span><span class="RktMeta"></span> is not the tag we want. We need to define <span class="RktSym">my-map</span><span class="RktMeta"></span> to be a tag function for <span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span><span class="RktMeta"></span>. We can do this with the Pollen helper <span class="RktSym">make-default-tag-function</span>. That function lives in <span class="RktSym">pollen/tag</span>, so we <span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span> that too:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">pollen/tag</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">my-map</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">make-default-tag-function</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">my-map</span><span class="RktPn">{</span><span class="RktMeta">How</span><span class="hspace"> </span><span class="RktMeta">I</span><span class="hspace"> </span><span class="RktMeta">would</span><span class="hspace"> </span><span class="RktMeta">love</span><span class="hspace"> </span><span class="RktMeta">this</span><span class="hspace"> </span><span class="RktMeta">to</span><span class="hspace"> </span><span class="RktMeta">be</span><span class="hspace"> </span><span class="RktMeta">a</span><span class="hspace"> </span><span class="RktMeta">map.</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(map "How I would love this to be a map.")</span></span></p></blockquote><p>Problem solved.</p><h5>3.1.3<tt> </tt><a name="(part._.Inserting_the_value_of_a_variable)"></a>Inserting the value of a variable</h5><p>A Pollen command name usually refers to a function, but it can also refer to a <span style="font-style: italic">variable</span>, which is a data value. Once you define the variable, you can insert it into your source by using the ◊ notation without any other arguments:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">foo</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"bar"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">foo</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">foo</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">The value of foo is bar</span></span></p></blockquote><p>Be careful — if you include arguments, even blank ones, Pollen will treat the command name as a function. This won’t work, because a variable is not a function:</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>To understand what happens here, recall the relationship between Pollen’s command modes. The Pollen-mode command <span class="RktSym">◊foo</span><span class="RktPn">[</span><span class="RktPn">]</span><span class="RktMeta"></span> becomes the Racket-mode command <span class="RktPn">(</span><span class="RktSym">foo</span><span class="RktPn">)</span><span class="RktMeta"></span>, which after variable substitution becomes <span class="RktPn">(</span><span class="RktVal">"bar"</span><span class="RktPn">)</span><span class="RktMeta"></span>. If you try to evaluate <span class="RktPn">(</span><span class="RktVal">"bar"</span><span class="RktPn">)</span><span class="RktMeta"></span> — e.g., in DrRacket — you’ll get the same error.</p></blockquote></blockquote></blockquote><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">foo</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"bar"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">foo</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">foo</span><span class="RktPn">[</span><span class="RktPn">]</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">application: not a procedure;<br/>expected a procedure that can be applied to arguments<br/>  given: "bar"<br/>  arguments...: [none]</span></span></p></blockquote><p>The reason we can simply drop <span class="RktSym">◊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).</p><p>In preprocessor source files, 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" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace"> </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"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">zam</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">zam</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">The value of zam is 42</span></span></p></blockquote><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>In an unsaved DrRacket file, or a file without a special Pollen source extension, the <span class="stt">#lang pollen</span> designation invokes the Pollen preprocessor by default. You can explicitly invoke preprocessor mode by starting a file with <span class="stt">#lang pollen/pre</span>. See also <font class="badlink">(part "Preprocessor___pp_extension_")</font>.</p></blockquote></blockquote></blockquote><p>If the variable holds a container datatype (like a <span class="RktSym"><span class="badlink"><span class="RktValLink">list</span></span></span>, <span class="RktSym"><span class="badlink"><span class="RktValLink">hash</span></span></span>, or <span class="RktSym"><span class="badlink"><span class="RktValLink">vector</span></span></span>), Pollen will produce the Racket text representation of the item. Here, <span class="RktSym">zam</span><span class="RktMeta"></span> is a <span class="RktSym"><span class="badlink"><span class="RktValLink">list</span></span></span> of integers:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">list</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">2</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">zam</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">zam</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">The value of zam is '(1 2 3)</span></span></p></blockquote><p>This feature is included for your convenience. But in general, your readers won’t want to see the Racket representation of a container. So in these cases, you should convert to a string manually in some sensible way. Here, the integers in the list are converted to strings, which are then combined using <span class="RktSym"><span class="badlink"><span class="RktValLink">string-join</span></span></span> from the <font class="badlink"><span class="RktModLink"><span class="RktSym">racket/string</span></span></font> library:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">racket/string</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">list</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">2</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">zam</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string-join</span></span></span><span class="RktPn">[</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">map</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">number->string</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktPn">)</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">and</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">The value of zam is 1 and 2 and 3</span></span></p></blockquote><p>Pollen will still produce an error if you try to convert an esoteric value to a string. Here, <span class="RktSym">zam</span><span class="RktMeta"></span> is the addition function (<span class="RktSym"><span class="badlink"><span class="RktValLink">+</span></span></span>):</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">+</span></span></span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">zam</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">zam</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">Pollen decoder: can't convert #<procedure:+> to string</span></span></p></blockquote><p>Moreover, Pollen will not perform <span style="font-style: italic">any</span> automatic text conversion in Pollen markup source files. Suppose we take the example above — which worked as a preprocessor source file — and change the language to <span class="RktSym">pollen/markup</span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen/markup</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">zam</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">list</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">2</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">3</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">zam</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">zam</span><span class="RktMeta"></span></td></tr></table></blockquote><p>This time, the file will produce an error:</p><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">pollen markup error: in '(root "The value of zam is " (1 2 3)), '(1 2 3) is not a valid element (must be txexpr, string, symbol, XML char, or cdata)</span></span></p></blockquote><p>One special case to know about. In the examples above, there’s a word space between the variable and the other text. But suppose you need to insert a variable into text so that there’s no space in between. The simple ◊ notation won’t work, because it won’t be clear where the variable name ends and the text begins.</p><p>For instance, suppose we want to use a variable <span class="RktSym">edge</span><span class="RktMeta"></span> next to the string <span class="RktSym">px</span><span class="RktMeta"></span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">edge</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">100</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">p</span><span class="hspace"> </span><span class="RktMeta">{</span><span class="hspace"> </span><span class="RktMeta">margin-left:</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">edgepx</span><span class="RktMeta">;</span><span class="hspace"> </span><span class="RktMeta">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">Pollen decoder: can't convert #<procedure:...t/pollen/tag.rkt:6:2> to string</span></span></p></blockquote><p>The example fails because Pollen reads the whole string after the <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊</span><span class="hspace"></span></span> as the single variable name <span class="RktSym">edgepx</span><span class="RktMeta"></span>. Since <span class="RktSym">edgepx</span><span class="RktMeta"></span> isn’t defined, it’s treated as a tag function, and since Pollen can’t convert a function to a string, we get an error.</p><p>In these situations, surround the variable name with vertical bars <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊|</span><span class="hspace"></span></span>like so<span class="RktInBG"><span class="hspace"></span><span class="RktIn">|</span><span class="hspace"></span></span> to explicitly indicate where the variable name ends. The bars are not treated as part of the name, nor are they included in the result. Once we do that, we get what we intended:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">edge</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">100</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">p</span><span class="hspace"> </span><span class="RktMeta">{</span><span class="hspace"> </span><span class="RktMeta">margin-left:</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊|</span><span class="RktSym">edge</span><span class="RktPn">|</span><span class="RktMeta">px;</span><span class="hspace"> </span><span class="RktMeta">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">p { margin-left: 100px; }</span></span></p></blockquote><p>If you use this notation when you don’t need to, nothing bad will happen. The vertical bars are always ignored.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">edge</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">100</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">value</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">edge</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊|</span><span class="RktSym">edge</span><span class="RktPn">|</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">pixels}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">The value of edge is 100 pixels</span></span></p></blockquote><h5>3.1.4<tt> </tt><a name="(part._.Inserting_metas)"></a>Inserting metas</h5><p><span style="font-style: italic">Metas</span> are key–value pairs embedded in a source file that are not included in the main output when the source is compiled. Rather, they’re gathered and exported as a separate hash table called, unsurprisingly, <span class="RktSym">metas</span>. This hashtable is a good place to store information about the document that you might want to use later (for instance, a list of topic categories that the document belongs to).</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>Pollen occasionally uses metas internally. For instance, the <span class="RktSym"><span class="badlink"><span class="RktValLink">get-template-for</span></span></span> function will look in the metas of a source file to see if a template is explicitly specified. The <span class="RktSym">pollen/template</span> module also contains functions for working with metas, such as <span class="RktSym"><span class="badlink"><span class="RktValLink">select-from-metas</span></span></span>.</p></blockquote></blockquote></blockquote><p>To make a meta, you create a tag with the special <span class="RktSym">define-meta</span><span class="RktMeta"></span> name. Then you have two choices: you can either embed the key-value pair as an attribute, or as a tagged X-expression within the meta (using the key as the tag, and the value as the body):</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">define-meta</span><span class="RktPn">[</span><span class="RktSym">dog</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Roxy</span><span class="RktPn">}</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">;</span><span class="hspace"> </span><span class="RktMeta">Pollen-mode</span><span class="hspace"> </span><span class="RktMeta">syntax</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">some-tag</span><span class="RktPn">[</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">key:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"value"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Normal</span><span class="hspace"> </span><span class="RktMeta">tag</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">cat</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Chopper"</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">;</span><span class="hspace"> </span><span class="RktMeta">equivalent</span><span class="hspace"> </span><span class="RktMeta">Racket-mode</span><span class="hspace"> </span><span class="RktMeta">syntax</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">some-tag</span><span class="RktPn">[</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">key:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"value"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Another</span><span class="hspace"> </span><span class="RktMeta">normal</span><span class="hspace"> </span><span class="RktMeta">tag</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p>When you run a source file with metas in it, two things happen. First, the metas are removed from the output:</p><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(some-tag ((key "value")) "Normal tag")<br/><br/>'(some-tag ((key "value")) "Another normal tag")</span></span></p></blockquote><p>Second, the metas are collected into a hash table that is exported with the name <span class="RktSym">metas</span><span class="RktMeta"></span>. To see this hash table, run the file above in DrRacket, then switch to the interactions window and type <span class="stt">metas</span> at the prompt:</p><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> metas</span></p></td></tr><tr><td><p><span class="stt">'#hash((dog . "Roxy") (cat . "Chopper") (here-path . "unsaved-editor"))</span></p></td></tr></table></div></div><p>The only key that’s automatically defined in every meta table is <span class="RktSym">here-path</span><span class="RktMeta"></span>, which is the absolute path to the source file. (In this case, because the file hasn’t been saved, you’ll see the <span class="RktSym">unsaved-editor</span><span class="RktMeta"></span> name instead.)</p><p>Still, you can override this too:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">define-meta</span><span class="RktPn">[</span><span class="RktSym">dog</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Roxy</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">some-tag</span><span class="RktPn">[</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">key:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"value"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Normal</span><span class="hspace"> </span><span class="RktMeta">tag</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">cat</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Chopper"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">some-tag</span><span class="RktPn">[</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">key:</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"value"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Another</span><span class="hspace"> </span><span class="RktMeta">normal</span><span class="hspace"> </span><span class="RktMeta">tag</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">here-path</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"tesseract"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><p>When you run this code, the result will be the same as before, but this time the metas will be different:</p><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> metas</span></p></td></tr><tr><td><p><span class="stt">'#hash((dog . "Roxy") (cat . "Chopper") (here-path . "tesseract"))</span></p></td></tr></table></div></div><p>It doesn’t matter how many metas you put in a source file, nor where you put them. They’ll all be extracted into the <span class="RktSym">metas</span><span class="RktMeta"></span> hash table. The order of the metas is not preserved (because order is not preserved in a hash table). But if you have two metas with the same key, the later one will supersede the earlier one:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">define-meta</span><span class="RktPn">[</span><span class="RktSym">dog</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Roxy</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">dog</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Lex"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><p>In this case, though there are two metas named <span class="RktSym">dog</span> (and they use different forms) only the second one persists:</p><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> metas</span></p></td></tr><tr><td><p><span class="stt">'#hash((dog . "Lex") (here-path . "unsaved-editor"))</span></p></td></tr></table></div></div><p><span style="font-weight: bold">Pro tip</span>: the <span class="RktSym">metas</span> hashtable is available when you import a Pollen source file in the usual way, but it’s also made available through a submodule called, unsurprisingly, <span class="RktSym">metas</span>.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">racket/base</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"pollen-source.rkt"</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktCmt">;</span><span class="hspace"> </span><span class="RktCmt">doc</span><span class="hspace"> </span><span class="RktCmt">and</span><span class="hspace"> </span><span class="RktCmt">metas</span><span class="hspace"> </span><span class="RktCmt">and</span><span class="hspace"> </span><span class="RktCmt">everything</span><span class="hspace"> </span><span class="RktCmt">else</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">submod</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"pollen-source.rkt"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">metas</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktCmt">;</span><span class="hspace"> </span><span class="RktCmt">just</span><span class="hspace"> </span><span class="RktCmt">metas</span><span class="RktMeta"></span></td></tr></table></blockquote><p>The <span class="RktSym">metas</span> submodule is useful because it gives you access to the <span class="RktSym">metas</span> hashtable <span style="font-style: italic">without</span> compiling the rest of the file. So if you need to collect metas from a set of source files — for instance, page titles (for a table of contents) or categories — getting the metas through the submodule is likely to be faster.</p><h5>3.1.5<tt> </tt><a name="(part._.Retrieving_metas)"></a>Retrieving metas</h5><p>The <span class="RktSym">metas</span> hashtable is available immediately within the body of your source file. You can use <span class="RktSym"><span class="badlink"><span class="RktValLink">hash-ref</span></span></span> to get values out of <span class="RktSym">metas</span>.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">dog</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Roxy"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">hash-ref</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">metas</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">dog</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">Roxy</span></p></td></tr></table></div></div><p>Because the metas are collected first, you can actually invoke a meta before you define it:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">hash-ref</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">metas</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">dog</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">dog</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Roxy"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">dog</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Spooky"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr></table></blockquote><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">Spooky</span></p></td></tr></table></div></div><p>This can be useful for setting up fields that you want to include in <span class="RktSym">metas</span> but also have visible in the body of a document, like a title.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen/markup</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym">define-meta</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"The</span><span class="hspace"> </span><span class="RktVal">Amazing</span><span class="hspace"> </span><span class="RktVal">Truth"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">h1</span><span class="RktPn">{</span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">hash-ref</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">metas</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktPn">)</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><p>The result of this file will be:</p><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">'(root (h1 "The Amazing Truth"))</span></p></td></tr></table></div></div><p><div class="SIntrapara">And the metas:
|
|
</div><div class="SIntrapara"><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> metas</span></p></td></tr><tr><td><p><span class="stt">'#hash((title . "The Amazing Truth") (here-path . "unsaved-editor"))</span></p></td></tr></table></div></div></div><div class="SIntrapara">You cannot, however, use <span class="RktSym"><span class="badlink"><span class="RktValLink">hash-set!</span></span></span> or other similar functions, because <span class="RktSym">metas</span> is an immutable hash.</div></p><h5>3.1.6<tt> </tt><a name="(part._.Inserting_a_comment)"></a>Inserting a comment</h5><p>Two options.</p><p>To comment out the rest of a single line, use a lozenge followed by a semicolon <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊;</span><span class="hspace"></span></span>.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">span</span><span class="RktPn">{</span><span class="RktMeta">This</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta">not</span><span class="hspace"> </span><span class="RktMeta">a</span><span class="hspace"> </span><span class="RktMeta">comment</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">span</span><span class="RktPn">{</span><span class="RktMeta">Nor</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta">this</span><span class="RktPn">}</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktCmt">◊;span{But</span><span class="hspace"> </span><span class="RktCmt">this</span><span class="hspace"> </span><span class="RktCmt">is}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(span "This is not a comment")<br/>'(span "Nor is this")</span></span></p></blockquote><p>To comment out a multiline block, use the lozenge–semicolon signal <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊;</span><span class="hspace"></span></span> with curly braces, <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊;{</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" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktCmt">◊;</span><span class="RktPn">{</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktMeta">span</span><span class="RktPn">{</span><span class="RktMeta">This</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta">not</span><span class="hspace"> </span><span class="RktMeta">a</span><span class="hspace"> </span><span class="RktMeta">comment</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktMeta">span</span><span class="RktPn">{</span><span class="RktMeta">Nor</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta">this</span><span class="RktPn">}</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktCmt">◊;span{But</span><span class="hspace"> </span><span class="RktCmt">this</span><span class="hspace"> </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"></span><span class="RktMeta">Actually,</span><span class="hspace"> </span><span class="RktMeta">it's</span><span class="hspace"> </span><span class="RktMeta">all</span><span class="hspace"> </span><span class="RktMeta">a</span><span class="hspace"> </span><span class="RktMeta">comment</span><span class="hspace"> </span><span class="RktMeta">now</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">Actually, it's all a comment now</span></span></p></blockquote><h4>3.2<tt> </tt><a name="(part._.The_.Racket_arguments)"></a>The Racket arguments</h4><p>The middle part of a Pollen-mode 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’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" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktPn">{</span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">Beginning</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">End</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(title "The Beginning of the End")</span></span></p></blockquote><p>But what if you wanted to add attributes to this tag, so that it comes out like this?</p><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(title ((class "red")(id "first")) "The Beginning of the End")</span></span></p></blockquote><p>You can do it with Racket arguments.</p><p>Here’s the hard way. You can type out your list of attributes in Racket format and drop them into the brackets as a single argument:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktPn">[</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">class</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"red"</span><span class="RktPn">)</span><span class="RktPn">(</span><span class="RktSym">id</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"first"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">Beginning</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">End</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(title ((class "red") (id "first")) "The Beginning of the End")</span></span></p></blockquote><p>But that’s a lot of parentheses to think about. So here’s the easy way. Anytime you use a tag function, there’s a shortcut for inserting attributes. You can enter them as a series of <span style="font-style: italic">keyword arguments</span> between the Racket-argument brackets. The only caveat is that the values for these keyword arguments have to be strings. So taken together, they look like this:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktPn">[</span><span class="RktPn">#:class</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"red"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">#:id</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"first"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">Beginning</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">End</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(title ((class "red") (id "first")) "The Beginning of the End")</span></span></p></blockquote><p>The string arguments can be any valid Racket expressions that produce strings. For instance, this will also work:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktPn">[</span><span class="RktPn">#:class</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"~a"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">*</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">6</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">7</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">#:id</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"first"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">Beginning</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">End</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(title ((class "42") (id "first")) "The Beginning of the End")</span></span></p></blockquote><p>Since Pollen commands are really just Racket arguments underneath, you can use those too. Here, we’ll define a variable called <span class="RktSym">name</span><span class="RktMeta"></span> and use it in the Racket arguments of <span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktMeta"></span>:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">name</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Brennan"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">title</span></span></span><span class="RktPn">[</span><span class="RktPn">#:class</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"red"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">#:id</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">name</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">The</span><span class="hspace"> </span><span class="RktMeta">Beginning</span><span class="hspace"> </span><span class="RktMeta">of</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">End</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(title ((class "read") (id "Brennan")) "The Beginning of the End")</span></span></p></blockquote><p>When used in custom tag functions, keyword arguments don’t have to represent attributes. Instead, they can be used to provide options for a particular Pollen command, to avoid redundancy. Suppose that instead of using the <span class="RktSym">h1</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">...</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">h6</span><span class="RktMeta"></span> tags, you want to consolidate them into one command called <span class="RktSym">heading</span><span class="RktMeta"></span> and select the level separately. You can do this with a keyword, in this case <span class="RktPn">#:level</span>, which is passed as a Racket argument:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">heading</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">#:level</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">which</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">`</span></span></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">,</span></span></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->symbol</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">format</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"h~a"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">which</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,</span></span></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">heading</span><span class="RktPn">[</span><span class="RktPn">#:level</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">1</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Major</span><span class="hspace"> </span><span class="RktMeta">league</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">heading</span><span class="RktPn">[</span><span class="RktPn">#:level</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">2</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Minor</span><span class="hspace"> </span><span class="RktMeta">league</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">heading</span><span class="RktPn">[</span><span class="RktPn">#:level</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">6</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Trivial</span><span class="hspace"> </span><span class="RktMeta">league</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(h1 "Major league")<br/>'(h2 "Minor league")<br/>'(h6 "Trivial league")</span></span></p></blockquote><h4>3.3<tt> </tt><a name="(part._.The_text_argument)"></a>The text argument</h4><p>The third part of a Pollen-mode 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" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">Do</span><span class="hspace"> </span><span class="RktMeta">it</span><span class="hspace"> </span><span class="RktMeta">again.</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">And</span><span class="hspace"> </span><span class="RktMeta">again.</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">And</span><span class="hspace"> </span><span class="RktMeta">yet</span><span class="hspace"> </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><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div "Do it again. " (div "And again. " (div "And yet again.")))</span></span></p></blockquote><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">◊</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">◊"◊"</span><span class="hspace"></span></span>.</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">definition</span><span class="RktPn">{</span><span class="RktMeta">This</span><span class="hspace"> </span><span class="RktMeta">is</span><span class="hspace"> </span><span class="RktMeta">the</span><span class="hspace"> </span><span class="RktMeta">lozenge:</span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktVal">"◊"</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(definition "This is the lozenge: ◊")</span></span></p></blockquote><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><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">Roomy!</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">I</span><span class="hspace"> </span><span class="RktMeta">agree.</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div "Roomy!" "\n" "\n" "I agree.")</span></span></p></blockquote><p>Yields the same result as this one:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">Roomy!</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta">I</span><span class="hspace"> </span><span class="RktMeta">agree.</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div "Roomy!" "\n" "\n" "I agree.")</span></span></p></blockquote><p>For the long version, please see [future link: Spaces, Newlines, and Indentation].</p><p>Third, within a multiline text argument, newline characters become individual strings that are not merged with adjacent text. So what you end up with is a list of strings, not a single string. That’s why in the last example, we got this:</p><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div "Roomy!" "\n" "\n" "I agree.")</span></span></p></blockquote><p>Instead of this:</p><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div "Roomy!\n\nI agree.")</span></span></p></blockquote><p>Under most circumstances, these two tagged X-expressions will behave the same way. The biggest exception is with functions. A function that operates on multiline text arguments needs to be able to handle an indefinite number of strings. For instance, this <span class="RktSym">jejune</span><span class="RktMeta"></span> function only accepts a single argument. It will work with a single-line text argument, because that produces a single string:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">`</span></span></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,</span></span></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">jejune</span><span class="RktPn">{</span><span class="RktMeta">Irrational</span><span class="hspace"> </span><span class="RktMeta">confidence</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(jejune "Irrational confidence")</span></span></p></blockquote><p>But watch what happens with a multiline text argument:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">`</span></span></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,</span></span></span><span class="RktSym">text</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">jejune</span><span class="RktPn">{</span><span class="RktMeta">Deeply</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktMeta">chastened</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktErr"><span class="stt">jejune: arity mismatch;<br/>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></span></p></blockquote><p>The answer is to use a <span style="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 <span class="RktSym"><span class="badlink"><span class="RktValLink">list</span></span></span>. If we rewrite <span class="RktSym">jejune</span><span class="RktMeta"></span> with a rest argument, we can fix the problem:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktMeta">.</span><span class="RktMeta"></span><span class="hspace"> </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"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">`</span></span></span><span class="RktPn">(</span><span class="RktSym">jejune</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,@</span></span></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"></span><span class="RktPn">◊</span><span class="RktSym">jejune</span><span class="RktPn">{</span><span class="RktMeta">Deeply</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktMeta">chastened</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(jejune "Deeply" "\n" "chastened")</span></span></p></blockquote><h3>4<tt> </tt><a name="(part._.Embedding_character_entities)"></a>Embedding character entities</h3><p>XML and HTML support <span style="font-style: italic">character entities</span>, a way of encoding Unicode characters with a name or number. For instance, in HTML, the copyright symbol <span class="RktInBG"><span class="hspace"></span><span class="RktIn">©</span><span class="hspace"></span></span> can be encoded by name as <span class="stt">&copy;</span> or by number as <span class="stt">&#169;</span>.</p><p>Entities originated as a way of embedding Unicode characters in an ASCII data stream. Pollen and Racket, however, support Unicode directly. So does every major web browser (though your document may need a Unicode character-set declaration to trigger it). So usually, your best bet is insert Unicode characters directly into your source rather than use entities.</p><p>But if you really need entities, here’s what to do. Pollen treats everything as text by default, so you can’t insert entities merely by typing them, because they’ll just be converted to text:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">copy</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktMeta">169</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div "copy" "\n" "169")</span></span></p></blockquote><p>Instead, named entities are handled as <font class="badlink">(part ("(lib scribblings/guide/guide.scrbl)" "symbols"))</font> and numeric entities are, unsurprisingly, <font class="badlink">(part ("(lib scribblings/guide/guide.scrbl)" "numbers"))</font>. So you can use the <span class="RktSym"><span class="badlink"><span class="RktValLink">string->symbol</span></span></span> and <span class="RktSym"><span class="badlink"><span class="RktValLink">string->number</span></span></span> functions to convert your entity input:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->symbol</span></span></span><span class="RktPn">{</span><span class="RktMeta">copy</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->number</span></span></span><span class="RktPn">{</span><span class="RktMeta">169</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div copy "\n" 169)</span></span></p></blockquote><p>Notice that in the output, there are no more quote marks around <span class="stt">copy</span> and <span class="stt">169</span>, indicating that they’re not strings. When you pass this result to a converter like <span class="RktSym"><span class="badlink"><span class="RktValLink">->html</span></span></span>, the entities will be escaped correctly:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">pollen/template</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">->html</span></span></span><span class="RktPn">{</span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktMeta">copy</span><span class="hspace"> </span><span class="RktMeta">169</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktMeta"> </span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">->html</span></span></span><span class="RktPn">{</span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->symbol</span></span></span><span class="RktPn">{</span><span class="RktMeta">copy</span><span class="RktPn">}</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->number</span></span></span><span class="RktPn">{</span><span class="RktMeta">169</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt"><div>copy 169</div><br/><br/><div>&copy; &#169;</div></span></span></p></blockquote><p>For numeric entities, you can also use a four-digit Unicode hex number by prefacing it with <span class="RktInBG"><span class="hspace"></span><span class="RktIn">#x</span><span class="hspace"></span></span>, which is the standard Racket prefix for a hex number:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><font class="badlink"><span class="RktModLink"><span class="RktSym">pollen</span></span></font><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym">div</span><span class="RktPn">{</span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->number</span></span></span><span class="RktPn">{</span><span class="RktMeta">169</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">string->number</span></span></span><span class="RktPn">{</span><span class="RktMeta">#x00a9</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr></table></blockquote><blockquote class="SubFlow"><p><span class="RktVal"><span class="stt">'(div 169 "\n" 169)</span></span></p></blockquote><p>Of course, you don’t need to use <span class="RktSym"><span class="badlink"><span class="RktValLink">string->symbol</span></span></span> and <span class="RktSym"><span class="badlink"><span class="RktValLink">string->number</span></span></span> directly in your source. You can also define tag functions that generate entities. The key point is that to be treated as an entity, the return value must be a symbol or number, rather than a string.</p><h3>5<tt> </tt><a name="(part._.Adding_.Pollen-mode_commands_to_a_.Racket_file)"></a><a name="(mod-path._pollen/exp)"></a>Adding Pollen-mode commands to a Racket file</h3><p><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="hspace"> </span><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">pollen</span></span></td></tr></table></p><p>Just as you can embed any Racket-mode command in a Pollen source file, you can go the other way and embed Pollen-mode commands in a Racket file. For instance, in your <font class="badlink">(part "The__pollen_rkt__file")</font>, you may find it convenient to use Pollen mode for certain values.</p><p>You enable Pollen mode within your source file by adding <a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a> to your <span class="stt">#lang</span> line at the top of your source:</p><div class="fileblock"><div class="SIntrapara"><div class="fileblock_filetitle"><span class="fileblock_filename"><span class="stt">"pollen.rkt"</span></span></div></div><div class="SIntrapara"><div class="fileblock_filecontent"><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">racket/base</span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">pollen/tag</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">link</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">make-default-tag-function</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">a</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">home-link</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">link</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">#:href</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"index.html"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"Click</span><span class="hspace"> </span><span class="RktVal">to</span><span class="hspace"> </span><span class="RktVal">go</span><span class="hspace"> </span><span class="RktVal">home"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">home-link-pollen-mode</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">link</span></span></span><span class="RktPn">[</span><span class="RktPn">#:href</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"index.html"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">Click</span><span class="hspace"> </span><span class="RktMeta">to</span><span class="hspace"> </span><span class="RktMeta">go</span><span class="hspace"> </span><span class="RktMeta">home</span><span class="RktPn">}</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr></table></blockquote></div></div></div></div><p>Here, both <span class="stt">(home-link)</span> and <span class="stt">(home-link-pollen-mode)</span> will produce the same X-expression as a result:</p><div class="terminal"><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">'(a ((href "index.html")) "Click to go home")</span></p></td></tr></table></div></div><p>Of course, you can use <a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a> in any Racket source file, not just <span class="stt">"pollen.rkt"</span>.</p><p>Keep in mind that <a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a> is just a syntactic convenience. It doesn’t change any of the underlying semantics of your Racket source file. Your Pollen-mode commands are being translated into Racket commands and compiled along with everything else.</p><p>Another good way to use Pollen-mode commands in Racket is for unit tests with <font class="badlink"><span class="RktModLink"><span class="RktSym">rackunit</span></span></font>. With <a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a>, you can write your unit tests in Pollen mode or Racket mode (or mix them).</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>Unit tests are little one-line tests you put into your code to verify it does what you expect. You do this with the <font class="badlink"><span class="RktModLink"><span class="RktSym">rackunit</span></span></font> library, which is beloved by all Racket programmers. For more, see <font class="badlink">(part ("(lib rackunit/scribblings/rackunit.scrbl)" "quick-start"))</font>.</p></blockquote></blockquote></blockquote><div class="fileblock"><div class="SIntrapara"><div class="fileblock_filetitle"><span class="fileblock_filename"><span class="stt">"pollen.rkt"</span></span></div></div><div class="SIntrapara"><div class="fileblock_filecontent"><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><font class="badlink"><span class="RktModLink"><span class="RktMod">#lang</span></span></font><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="file:///Users/mb/git/pollen/scribblings/command.html#%28mod-path._pollen%2Fexp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen/exp</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">racket/base</span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">require</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">rackunit</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">define</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">tag-fn</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">arg</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktMeta">.</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym">text-args</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">`</span></span></span><span class="RktPn">(</span><span class="RktSym">div</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">class</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,</span></span></span><span class="RktSym">arg</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">,@</span></span></span><span class="RktSym">text-args</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">check-equal?</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">◊</span><span class="RktSym">tag-fn</span><span class="RktPn">[</span><span class="RktVal">"42"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">hello</span><span class="hspace"> </span><span class="RktMeta">world</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktPn">(</span><span class="RktSym">div</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">class</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"42"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"hello</span><span class="hspace"> </span><span class="RktVal">world"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">check-equal?</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym">tag-fn</span><span class="RktMeta"> </span><span class="RktVal">"42"</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"hello</span><span class="hspace"> </span><span class="RktVal">world"</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktPn">(</span><span class="RktSym">div</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">class</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"42"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"hello</span><span class="hspace"> </span><span class="RktVal">world"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr><tr><td><span class="RktMeta"></span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">check-equal?</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">◊</span><span class="RktSym">tag-fn</span><span class="RktPn">[</span><span class="RktVal">"42"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">hello</span><span class="hspace"> </span><span class="RktMeta">world</span><span class="RktPn">}</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta">◊</span><span class="RktSym"><span class="badlink"><span class="RktValLink">'</span></span></span><span class="RktSym">div</span><span class="RktPn">[</span><span class="RktPn">(</span><span class="RktPn">(</span><span class="RktSym"><span class="badlink"><span class="RktValLink">class</span></span></span><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><span class="RktVal">"42"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktMeta">hello</span><span class="hspace"> </span><span class="RktMeta">world</span><span class="RktPn">}</span><span class="RktPn">)</span><span class="RktMeta"></span></td></tr><tr><td><span class="RktMeta"> </span></td></tr></table></blockquote></div></div></div></div><h3>6<tt> </tt><a name="(part._.Further_reading)"></a>Further reading</h3><p>The Pollen language is a variant of Racket’s own text-processing language, called Scribble. Thus, most things that can be done with Scribble syntax can also be done with Pollen syntax. For the sake of clarity & brevity, I’ve only shown you the highlights here. But if you want the full story, see <font class="badlink">(part ("(lib scribblings/scribble/scribble.scrbl)" "reader"))</font> in the Scribble documentation.</p></div></div><div id="contextindicator"> </div></body></html> |