Debian Codegraph @

doc/index.html

raw
1 <p><html>
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
4 <meta name="description" content="Cosmo: Safe Templates in Lua">
5 <meta name="keywords" content="Lua, Cosmo, safe templates">
6 <title>Cosmo</title>
7 <style type="text/css">
8 body { color:#000; background:#fff; }
9 #header { width:100%;
10 text-align:center;<br/>
11 border-top:solid #aaa 1px;
12 border-bottom:solid #aaa 1px;
13 }
14 #header p { margin-left:0; }
15 p { margin-left:3px; }
16 pre { background-color:#ffe; white-space:pre; padding-left:3ex; border-left: 1px solid gray; margin-left: 10px}
17 </style>
18 </head>
19 <body>
20 <div id="header">
21 <img border=0 alt="Cosmo Logo" src="cosmo.png"/>
22 <p>Safe Templates in Lua</p>
23 <p>
24 <a href="#Overview">Overview</a> &middot;
25 <a href="#Installation">Installation</a> &middot;
26 <a href="#Using">Using Cosmo</a> &middot;
27 <a href="#Reference">API Reference</a> &middot;
28 <a href="#Contact">Contact Us</a> &middot;
29 <a href="#License">License</a></p>
30
31 <p> </p>
32 </div></p>
33
34 <h1><a name="Overview"></a> Overview</h1>
35
36 <p>Cosmo is a &ldquo;safe templates&rdquo; engine. It allows you to fill nested
37 templates, providing many of the advantages of Turing-complete
38 template engines, without without the downside of allowing arbitrary
39 code in the templates.</p>
40
41 <h1><a name="Overview"></a>Installation</h1>
42
43 <p>The current version of Cosmo is 13.01.30. This release adds Lua 5.2 support.</p>
44
45 <p>The previous version, 10.04.06, added, expressions to selectors $(&lt;exp>),
46 allowed nested [[ ]] in templates, made commas between subtemplates
47 optional, and added a second parameter to cosmo.yield that tells Cosmo
48 the first parameter is a literal to be included in the expansion instead
49 of an environment.</p>
50
51 <p>Cosmo is installed as a rock. To install the most recent release
52 do <code>luarocks install cosmo</code>. The Cosmo rock is in the standard
53 repository. Installation on UNIX-based systems need the gcc toolchain.</p>
54
55 <h1><a name="Using"></a>Using Cosmo</h1>
56
57 <h2>Simple Form Filling</h2>
58
59 <p>Let&rsquo;s start with a simple example of filling a set of scalar values
60 into a template: Here are a few examples of Cosmo in use:</p>
61
62 <pre><code>&gt; values = { rank="Ace", suit="Spades" }
63 &gt; template = "$rank of $suit"
64 &gt; require("cosmo")
65 &gt; = cosmo.fill(template, values)
66 Ace of Spades
67 </code></pre>
68
69 <p>Note that the template is a string that marks where values should
70 go. We call a template variable like <code>$rank</code> a <em>selector</em>, and <code>rank</code>
71 is the selector&rsquo;s name. The table passed to <code>cosmo.fill</code> is the
72 <em>environment</em>, and it provides the
73 values. <code>$rank</code> will get replaced by <code>value.rank</code> (&ldquo;Ace&rdquo;) and <code>$suit</code>
74 will get replaced by <code>value.suit</code> (&ldquo;Spades&rdquo;).</p>
75
76 <p><code>cosmo.fill</code> takes two parameters at once. Cosmo also provides a
77 &ldquo;shortcut&rdquo; method <code>f()</code> which takes only one parameter - the template
78 - and returns a function that then takes the second parameter. This
79 allows for a more compact notation:</p>
80
81 <pre><code>&gt; = cosmo.f(template){ rank="Ace", suit="Spades" }
82 Ace of Spades
83 </code></pre>
84
85 <p>A selector can be either a string or a Lua expression in parenthesis,
86 like <code>$("foo" .. "bar")</code> is replaced by <code>foobar</code> in the template. Any
87 variables in the expression are looked-up in the current template
88 environment, so <code>$(foo)</code> is the same as <code>$foo</code>, and <code>$(rank .. suit)</code>
89 would be replaced by <code>AceSpades</code> in the previous example.</p>
90
91 <h2>Nested Values</h2>
92
93 <p>You aren&rsquo;t restricted to scalar values; your values can be Lua tables that
94 you can destructure using a <em>$val|key1|key2|&hellip;|keyn</em> syntax. For example:</p>
95
96 <pre><code>&gt; values = { cards = { { rank = "Ace" , suit = "Spades" } } }
97 &gt; template = "$cards|1|rank of $cards|1|suit"
98 &gt; = cosmo.fill(template, values)
99 Ace of Spades
100 </code></pre>
101
102 <p>As you can see above, you can either use numbers or strings as keys.</p>
103
104 <h2>Arguments</h2>
105
106 <p>You can also pass arguments to a selector using the syntax <em>$selector{ args }</em>. The syntax
107 for the argument list is the same as a Lua table constructor, but function definitions are
108 not allowed, and you can use template selectors, which are looked up in the template environment.</p>
109
110 <p>If you pass an argument list and the selector maps to a function then Cosmo calls
111 this function with the argument list as a table, and the selector expands to what
112 the function returns. For example:</p>
113
114 <pre><code>&gt; values = { message = function (arg) return arg.rank .. " of "
115 .. arg.suit end }
116 &gt; template = "$message{ rank = 'Ace', suit = 'Spades' }"
117 &gt; = cosmo.fill(template, values)
118 Ace of Spades
119 </code></pre>
120
121 <h2>Subtemplates</h2>
122
123 <p>Now, suppose we have not just one card, but several. Cosmo allows us
124 to handle this case with &ldquo;subtemplates&rdquo;</p>
125
126 <pre><code>&gt; mycards = { {rank="Ace", suit="Spades"}, {rank="Queen", suit="Diamonds"}, {rank="10", suit="Hearts"} }
127 &gt; template = "$do_cards[[$rank of $suit, ]]"
128 &gt; = cosmo.fill(template, {do_cards = mycards})
129 Ace of Spades, Queen of Diamonds, 10 of Hearts,
130 </code></pre>
131
132 <p>The subtemplate &ldquo;$rank or $suit&rdquo; could be enclosed in <code>[[...]]</code>,
133 <code>[=[...]=]</code>, <code>[==[...]==]</code>, etc. - just like Lua&rsquo;s long-quoted
134 strings. Again, we can use the shortcut <code>f()</code>:</p>
135
136 <pre><code>&gt; = cosmo.f(template){do_cards = mycards}
137 Ace of Spades, Queen of Diamonds, 10 of Hearts,
138 </code></pre>
139
140 <h2>Subtemplates with Functions</h2>
141
142 <p>If we don&rsquo;t have a ready table that would match the template, we can
143 set the value of <code>do_cards</code> to a function, which will yield a set of
144 values for the subtemplate each time it&rsquo;s called:</p>
145
146 <pre><code>&gt; mycards = { {"Ace", "Spades"}, {"Queen", "Diamonds"}, {"10", "Hearts"} }
147 &gt; = cosmo.f(template){
148 do_cards = function()
149 for i,v in ipairs(mycards) do
150 cosmo.yield{rank=v[1], suit=v[2]}
151 end
152 end
153 }
154 Ace of Spades, Queen of Diamonds, 10 of Hearts,
155 </code></pre>
156
157 <p>You can also pass a list of arguments to this function:</p>
158
159 <pre><code>&gt; template = "$do_cards{ true, false, true }[[$rank of $suit, ]]"
160 &gt; mycards = { {"Ace", "Spades"}, {"Queen", "Diamonds"}, {"10", "Hearts"} }
161 &gt; = cosmo.f(template){
162 do_cards = function(arg)
163 for i,v in ipairs(mycards) do
164 if arg[i] then cosmo.yield{rank=v[1], suit=v[2]} end
165 end
166 end
167 }
168 Ace of Spades, 10 of Hearts,
169 </code></pre>
170
171 <p>Finally, you can pass a literal to be included in the expansion
172 instead of an environment. An example:</p>
173
174 <pre><code>&gt; template = "$do_cards{ true, false, true }[[$rank of $suit]]"
175 &gt; mycards = { {"Ace", "Spades"}, {"Queen", "Diamonds"}, {"10", "Hearts"} }
176 &gt; = cosmo.f(template){
177 do_cards = function(arg)
178 local n = #mycards
179 for i,v in ipairs(mycards) do
180 cosmo.yield{rank=v[1], suit=v[2]}
181 if i &lt; n then cosmo.yield(", ", true) end
182 end
183 end
184 }
185 Ace of Spades, Queen of Diamonds, 10 of Hearts
186 </code></pre>
187
188 <h2>Alternative Subtemplates</h2>
189
190 <p>In some cases we may want to use differente templates for different
191 items in the list. For example, we might want to use a different
192 template for the first and/or last item, or to use different templates
193 for odd and even numbers. We can do this by specifying several
194 templates, separated by a comma. In that case, cosmo will use the
195 first template in the sequence, unless the table of values for the
196 item contains a special field <code>_template</code>, in which case this field
197 will be used as an index into the list of alternative templates. For
198 instance, setting <code>_template</code> to 2 would tell cosmo to use the 2nd
199 template for this item.</p>
200
201 <pre><code>&gt; table.insert(mycards, {"2", "Clubs"})
202 &gt; template = "You have: $do_cards[[$rank of $suit]],[[, $rank of $suit]],[[, and $rank of $suit]]"
203 &gt; = cosmo.f(template){
204 do_cards = function()
205 for i,v in ipairs(mycards) do
206 local t
207 if i == #mycards then -- for the last item use the third template
208 t = 3
209 elseif i~=1 then -- use the second template for items 2...n-1
210 t = 2
211 end
212 cosmo.yield{rank=v[1], suit=v[2], _template=t}
213 end
214 end
215 }
216
217 You have: Ace of Spades, Queen of Diamonds, 10 of Heards, and 2 of Clubs
218 </code></pre>
219
220 <p>Note that the first item is formatted without preceeding &ldquo;, &rdquo;, while
221 the last item is preceeded by an extra &ldquo;and&rdquo;.</p>
222
223 <h2>Deeper Nesting</h2>
224
225 <p>Templates and subtemplates can be nested to arbitrary depth. For
226 instance, instead of formatting a set of cards, we can format a list
227 of sets of cards:</p>
228
229 <pre><code>&gt; players = {"John", "João"}
230 &gt; cards = {}
231 &gt; cards["John"] = mycards
232 &gt; cards["João"] = { {"Ace", "Diamonds"} }
233 &gt; template = "$do_players[[$player has $do_cards[[$rank of $suit]],
234 [[, $rank of $suit]],[[, and $rank of $suit]]\n]]"
235 &gt; = cosmo.f(template){
236 do_players = function()
237 for i,p in ipairs(players) do
238 cosmo.yield {
239 player = p,
240 do_cards = function()
241 for i,v in ipairs(cards[p]) do
242 local t
243 if i == #mycards then
244 t = 3
245 elseif i~=1 then -- use the second template for items 2...n-1
246 t = 2
247 end
248 cosmo.yield{rank=v[1], suit=v[2], _template=t}
249 end
250 end
251 }
252 end
253 end
254 }
255
256 John has Ace of Spades, Queen of Diamonds, 10 of Hearts, and 2 of Clubs
257 João has Ace of Diamonds
258 </code></pre>
259
260 <h2>Scope</h2>
261
262 <p>Subtemplates can see values that were set in the higher scope:</p>
263
264 <pre><code>&gt; template = "$do_players[[$do_cards[[$rank of $suit ($player), ]]]]"
265 &gt; = cosmo.f(template){
266 do_players = function()
267 for i,p in ipairs(players) do
268 cosmo.yield {
269 player = p,
270 do_cards = function()
271 for i,v in ipairs(cards[p]) do
272 cosmo.yield{rank=v[1], suit=v[2]}
273 end
274 end,
275 }
276 end
277 end
278 }
279
280 Ace of Spades (John), Queen of Diamonds (John), 10 of Hearts (John), 2 of Clubs (John), Ace of Diamonds (João),
281 </code></pre>
282
283 <p>Note that in this case the field &ldquo;player&rdquo; is set in the table of
284 values that is passed to <code>do_players</code>, but is used one level deeper -
285 in <code>do_cards</code>.</p>
286
287 <p>The scoping behavior can be overriden by setting a metatable on the environment you
288 pass to the subtemplates.</p>
289
290 <h2>If</h2>
291
292 <p>Subtemplates and arguments let you implement a more generic conditional:</p>
293
294 <pre><code>&gt; template = "$do_players[=[$player: $n card$if{ $plural }[[s]]
295 $if{ $more, $n_more }[[(needs $2 more)]],[[(no more needed)]]\n]=]"
296 &gt; = cosmo.f(template){
297 do_players = function()
298 for i,p in ipairs(players) do
299 cosmo.yield {
300 player = p,
301 n = #cards[p],
302 ["if"] = function (arg)
303 if arg[1] then arg._template = 1 else arg._template = 2 end
304 cosmo.yield(arg)
305 end,
306 plural = #cards[p] &gt; 1,
307 more = #cards[p] &lt; 3,
308 n_more = 3 - #cards[p]
309 }
310 end
311 end
312 }
313
314 John: 4 cards (no more needed)
315 João: 1 card (needs 2 more)
316 </code></pre>
317
318 <p>The conditional above is already present in Cosmo as <code>cosmo.cif</code>. Expressions in arguments
319 make it more useful:</p>
320
321 <pre><code>&gt; template = "$if{ math.fmod(x, 4) == 0, target = 'World' }[[ Hello $target! ]],
322 [[ Hi $target! ]]"
323 &gt; result = cosmo.fill(template, { math = math, x = 2, ["if"] = cosmo.cif })
324 &gt; assert(result == " Hi World! ")
325 </code></pre>
326
327 <h2>Other conditionals</h2>
328
329 <p>In some cases we want to format an set of values if some condition
330 applies, and <code>cosmo.if</code> is not enough.
331 This can be done with a function and a subtemplate by just
332 replacing a for-loop with an if-block. However, since this is a
333 common case, cosmo provides a function for it:</p>
334
335 <pre><code>&gt; template = "$do_players[[$player: $n card$if_plural[[s]] $if_needs_more[[(needs $n more)]]\n]]"
336 &gt; = cosmo.f(template){
337 do_players = function()
338 for i,p in ipairs(players) do
339 cosmo.yield {
340 player = p,
341 n = #cards[p],
342 if_plural = cosmo.cond(#cards[p] &gt; 1, {}),
343 if_needs_more = cosmo.cond(#cards[p] &lt; 3, { n = 3 - #cards[p] })
344 }
345 end
346 end
347 }
348
349 John: 4 cards
350 João: 1 card (needs 2 more)
351 </code></pre>
352
353 <p>Like <code>fill()</code>, <code>cond()</code> has a &ldquo;shortcut&rdquo; equivalent which takes only
354 one parameter (the template) and returns a function:</p>
355
356 <pre><code>&gt; = cosmo.f(template){
357 do_players = function()
358 for i,p in ipairs(players) do
359 cosmo.yield {
360 player = p,
361 n = #cards[p],
362 if_plural = cosmo.c(#cards[p] &gt; 1){},
363 if_needs_more = cosmo.c(#cards[p] &lt; 3){ n = 3-#cards[p] }
364 }
365 end
366 end
367 }
368
369 John: 4 cards
370 João: 1 card (needs 2 more)
371 </code></pre>
372
373 <h2>Map and Inject</h2>
374
375 <p>Cosmo provides two convenience functions for writing simple templates, <code>cosmo.map</code>
376 and <code>cosmo.inject</code>. Both functions have to be passed in a template&rsquo;s environment.
377 The <code>cosmo.map</code> function yields each of its arguments in sequence, and inject yields
378 its whole argument table. A simple example:</p>
379
380 <pre><code>&gt; template = "&lt;ol&gt;\n$map{ 'Spades', 'Hearts', 'Clubs', 'Diamonds'}[[&lt;li&gt;$it&lt;/li&gt;\n]]&lt;/ol&gt;"
381 &gt; = cosmo.fill(template, { map = cosmo.map })
382 &lt;ol&gt;
383 &lt;li&gt;Spades&lt;/li&gt;
384 &lt;li&gt;Hearts&lt;/li&gt;
385 &lt;li&gt;Clubs&lt;/li&gt;
386 &lt;li&gt;Diamonds&lt;/li&gt;
387 &lt;/ol&gt;
388 &gt; template = "$inject{ suit = 'Spades' }[[Ace of &lt;b&gt;$suit&lt;/b&gt;]]"
389 &gt; = cosmo.fill(template, { inject = cosmo.inject })
390 Ace of &lt;b&gt;Spades&lt;/b&gt;
391 </code></pre>
392
393 <h2>Concat</h2>
394
395 <p>Putting a delimiter between each expansion of a subtemplate is so
396 common that Cosmo provides also provides a convenience function for
397 it, <code>cosmo.concat</code>. This is an example:</p>
398
399 <pre><code>&gt; template = "$concat{ cards, ', ' }[[$1 of $2]]"
400 &gt; mycards = { {"Ace", "Spades"}, {"Queen", "Diamonds"}, {"10", "Hearts"} }
401 &gt; = cosmo.f(template){
402 cards = mycards,
403 concat = cosmo.concat
404 }
405 Ace of Spades, Queen of Diamonds, 10 of Hearts
406 </code></pre>
407
408 <h1><a name="Reference"></a> API Reference</h1>
409
410 <p><strong>cosmo.compile(<em>template</em>, <em>chunkname</em>)</strong> - compiles <em>template</em> into
411 a function that takes an environment and returns the filled
412 template. Assigns <em>chunkname</em> as the name of this function</p>
413
414 <p><strong>cosmo.fill(<em>template</em>, <em>env</em>)</strong> - same as <strong>cosmo.compile(<em>template</em>)(<em>env</em>)</strong></p>
415
416 <p><strong>cosmo.yield(<em>env</em>, <em>is_literal</em>)</strong> - fills the current subtemplate
417 with <em>env</em> if <em>is_literal</em> is <code>nil</code> or <code>false</code> and adds it to the
418 output stream; otherwise adds the the string <em>env</em> to the output
419 stream</p>
420
421 <p><strong>cosmo.cond(<em>bool</em>, <em>tab</em>)</strong> - returns a function that yields an
422 empty environment if <em>bool</em> is <code>nil</code> or <code>false</code> and <em>tab</em> otherwise</p>
423
424 <p><strong>cosmo.c(<em>bool</em>)</strong> - returns a function that takes a table <em>tab</em> and does the same thing as
425 <strong>cosmo.cond(<em>bool</em>, <em>tab</em>)</strong></p>
426
427 <p><strong>cosmo.map{ &hellip; }</strong> - has to be used inside a template; yields each
428 element of its argument in turn</p>
429
430 <p><strong>cosmo.inject(env)</strong> - has to be used inside a template; yields its
431 argument</p>
432
433 <p><strong>cosmo.cif{ <em>exp</em>, &hellip; }</strong> - has to be used inside a template; yields
434 its argument to subtemplate 2 is <em>exp</em> is <code>nil</code> or <code>false</code> and to
435 subtemplate 1 otherwise</p>
436
437 <p><strong>cosmo.concat{ <em>list</em>, [<em>delim</em>] }</strong> - has to be used inside a
438 template; for each element of <em>list</em> yields it and, if it is not the
439 last, yields the literal <em>delim</em> or &ldquo;, &rdquo; is <em>delim</em> is <code>nil</code></p>
440
441 <h1><a name="Contact"></a> Contact Us</h1>
442
443 <p>For more information please contact one of the authors,
444 <a href="mailto:[email protected]">Fabio Mascarenhas</a> and <a href="http://takhteyev.org/contact/">Yuri
445 Takhteyev</a>, or write to the
446 <a href="http://sputnik.freewisdom.org/en/Mailing_List">Sputnik Mailing List</a>.</p>
447
448 <p>Comments are welcome!</p>
449
450 <h1><a name="License"></a> License</h1>
451
452 <p>Cosmo is free software: it can be used for both academic and
453 commercial purposes at absolutely no cost. There are no royalties or
454 GNU-like &ldquo;copyleft&rdquo; restrictions. Cosmo qualifies as Open Source
455 software. Its licenses are compatible with GPL. The legal details are
456 below.</p>
457
458 <p>The spirit of the license is that you are free to use Cosmo for any
459 purpose at no cost without having to ask us. The only requirement is
460 that if you do use Cosmo, then you should give us credit by including
461 the appropriate copyright notice somewhere in your product or its
462 documentation.</p>
463
464 <p>The original Cosmo library is designed and implemented by Yuri Takhteyev, with
465 much feedback and inspiration by André Carregal. This version is a reimplementation
466 by Fabio Mascarenhas, with aditional features. The implementations
467 are not derived from licensed software.</p>
468
469 <p>Copyright © 2008-2010 Fabio Mascarenhas.
470 Copyright © 2007-2008 Yuri Takhteyev.</p>
471
472 <hr />
473
474 <p>Permission is hereby granted, free of charge, to any person obtaining
475 a copy of this software and associated documentation files (the
476 &ldquo;Software&rdquo;), to deal in the Software without restriction, including
477 without limitation the rights to use, copy, modify, merge, publish,
478 distribute, sublicense, and/or sell copies of the Software, and to
479 permit persons to whom the Software is furnished to do so, subject to
480 the following conditions:</p>
481
482 <p>The above copyright notice and this permission notice shall be
483 included in all copies or substantial portions of the Software.</p>
484
485 <p>THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND,
486 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
487 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
488 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
489 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
490 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
491 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
492
493 <p></body>
494 </html></p>