wlang 0.8.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (73) hide show
  1. data/LICENCE.rdoc +25 -0
  2. data/README.rdoc +111 -0
  3. data/bin/wlang +24 -0
  4. data/doc/specification/about.rdoc +61 -0
  5. data/doc/specification/dialects.wtpl +0 -0
  6. data/doc/specification/examples.rb +3 -0
  7. data/doc/specification/glossary.wtpl +14 -0
  8. data/doc/specification/hosting.rdoc +0 -0
  9. data/doc/specification/overview.rdoc +116 -0
  10. data/doc/specification/rulesets.wtpl +87 -0
  11. data/doc/specification/specification.css +52 -0
  12. data/doc/specification/specification.html +1361 -0
  13. data/doc/specification/specification.js +8 -0
  14. data/doc/specification/specification.wtpl +41 -0
  15. data/doc/specification/specification.yml +430 -0
  16. data/doc/specification/symbols.wtpl +16 -0
  17. data/lib/wlang.rb +186 -0
  18. data/lib/wlang/basic_object.rb +19 -0
  19. data/lib/wlang/dialect.rb +230 -0
  20. data/lib/wlang/dialect_dsl.rb +136 -0
  21. data/lib/wlang/dialect_loader.rb +69 -0
  22. data/lib/wlang/dialects/coderay_dialect.rb +35 -0
  23. data/lib/wlang/dialects/plain_text_dialect.rb +75 -0
  24. data/lib/wlang/dialects/rdoc_dialect.rb +33 -0
  25. data/lib/wlang/dialects/ruby_dialect.rb +35 -0
  26. data/lib/wlang/dialects/sql_dialect.rb +38 -0
  27. data/lib/wlang/dialects/standard_dialects.rb +113 -0
  28. data/lib/wlang/dialects/xhtml_dialect.rb +40 -0
  29. data/lib/wlang/encoder.rb +66 -0
  30. data/lib/wlang/encoder_set.rb +117 -0
  31. data/lib/wlang/errors.rb +37 -0
  32. data/lib/wlang/intelligent_buffer.rb +94 -0
  33. data/lib/wlang/parser.rb +251 -0
  34. data/lib/wlang/parser_context.rb +146 -0
  35. data/lib/wlang/ruby_extensions.rb +21 -0
  36. data/lib/wlang/rule.rb +66 -0
  37. data/lib/wlang/rule_set.rb +93 -0
  38. data/lib/wlang/rulesets/basic_ruleset.rb +75 -0
  39. data/lib/wlang/rulesets/buffering_ruleset.rb +103 -0
  40. data/lib/wlang/rulesets/context_ruleset.rb +115 -0
  41. data/lib/wlang/rulesets/encoding_ruleset.rb +73 -0
  42. data/lib/wlang/rulesets/imperative_ruleset.rb +132 -0
  43. data/lib/wlang/rulesets/ruleset_utils.rb +296 -0
  44. data/lib/wlang/template.rb +79 -0
  45. data/lib/wlang/wlang_command.rb +54 -0
  46. data/lib/wlang/wlang_command_options.rb +158 -0
  47. data/test/sandbox.rb +1 -0
  48. data/test/test_all.rb +8 -0
  49. data/test/wlang/anagram_bugs_test.rb +111 -0
  50. data/test/wlang/basic_ruleset_test.rb +52 -0
  51. data/test/wlang/buffering_ruleset_test.rb +102 -0
  52. data/test/wlang/buffering_template1.wtpl +1 -0
  53. data/test/wlang/buffering_template2.wtpl +1 -0
  54. data/test/wlang/buffering_template3.wtpl +1 -0
  55. data/test/wlang/buffering_template4.wtpl +1 -0
  56. data/test/wlang/buffering_template5.wtpl +1 -0
  57. data/test/wlang/context_ruleset_test.rb +32 -0
  58. data/test/wlang/data.rb +3 -0
  59. data/test/wlang/encoder_set_test.rb +42 -0
  60. data/test/wlang/imperative_ruleset_test.rb +107 -0
  61. data/test/wlang/intelligent_buffer_test.rb +194 -0
  62. data/test/wlang/othersymbols_test.rb +16 -0
  63. data/test/wlang/parser_context_test.rb +29 -0
  64. data/test/wlang/parser_test.rb +89 -0
  65. data/test/wlang/plain_text_dialect_test.rb +21 -0
  66. data/test/wlang/ruby_dialect_test.rb +100 -0
  67. data/test/wlang/ruby_expected.rb +3 -0
  68. data/test/wlang/ruby_template.wrb +3 -0
  69. data/test/wlang/ruleset_utils_test.rb +245 -0
  70. data/test/wlang/specification_examples_test.rb +52 -0
  71. data/test/wlang/test_utils.rb +25 -0
  72. data/test/wlang/wlang_test.rb +80 -0
  73. metadata +136 -0
data/doc/specification/specification.css ADDED
@@ -0,0 +1,52 @@
1
+ body {
2
+ font-family: arial, verdana, sans-serif;
3
+ font-size: 14px;
4
+ width: 1024px;
5
+ margin: auto;
6
+ margin-top: 20px;
7
+ }
8
+ .clear { clear: both; }
9
+ p { margin: 0px; margin-bottom: 10px; text-align: justify; }
10
+ #title { float: left; margin: 10px 0px 20px 0px; }
11
+ #tabs { float: right; margin: 15px 0px; }
12
+ #tabs li { display: block; float: right; cursor: pointer; margin: 0px 0px 0px 5px; padding: 5px; border: 1px solid black; }
13
+ #tabs li.focus { background-color: #A00000; color: white; }
14
+ dl dt { margin-top: 10px; font-weight: bold; }
15
+ div.header { border-bottom: 1px solid black; margin: 10px 0px; }
16
+ h2 { float: left; margin: 0px; padding: 0px; }
17
+ h3 { margin-top: 20px; margin-bottom: 10px; text-decoration: underline;}
18
+ dl { padding-left: 35px; }
19
+ ul { padding: 0px 0px 0px 25px; }
20
+ ul li { margin: 5px;}
21
+ ul.links { float: right; margin: 0px; padding: 0px; }
22
+ ul.links li { cursor: pointer; margin: 0px 0px 0px 10px; padding: 0px; padding-top: 5px; display: block; float: right; }
23
+ ul.links li a, ul.links li a:visited { color: black; text-decoration: none; }
24
+ ul.links li a:hover { color: #A00000; }
25
+ h3 { margin-bottom: 5px; }
26
+ h4 { margin-bottom: 3px; float: left; margin-top: 0px; }
27
+ table { border-collapse: collapse; border: 1px solid black; }
28
+ table th { font-size: 12px; }
29
+ table th, table td { padding: 4px; }
30
+ table.glossary { margin-top: 20px; }
31
+ table.glossary th { background: green; color: white; border-bottom: 1px solid black; }
32
+ table.glossary th.term { width: 100px; }
33
+ table.glossary td { border-bottom: 1px dashed black; }
34
+ table.symbols { font-size: 12px; margin-top: 20px; width: 100%; }
35
+ table.symbols th { background: green; color: white; border-bottom: 1px solid black; }
36
+ table.symbols th.name { width: 150px; }
37
+ table.symbols th.symbol { width: 50px; }
38
+ table.symbols th.meaning { width: 250px; }
39
+ table.symbols td { border-bottom: 1px dashed black; }
40
+ table.ruleset { font-size: 12px; }
41
+ table.ruleset th { background: green; color: white; }
42
+ table.ruleset td { border-bottom: 1px dashed black; }
43
+ th.signature, td.signature { width: 300px; }
44
+ th.name, td.name { width: 120px; }
45
+ th.definition, td.definition { width: 580px; }
46
+ table.examples { float: right; font-size: 12px; }
47
+ table.examples th { background: #A00000; color: white; border-bottom: 1px solid black; }
48
+ table.examples th, table.examples td { padding: 4px; }
49
+ table.examples td { border-bottom: 1px dashed black; }
50
+ th.dialect, td.dialect { width: 150px; }
51
+ th.expression, td.expression { width: 350px; }
52
+ th.replacement, td.replacement { width: 350px; }
data/doc/specification/specification.html ADDED
@@ -0,0 +1,1361 @@
1
+
2
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6
+ <title>WLang (version 0.8.4)</title>
7
+ <style type="text/css">
8
+ body {
9
+ font-family: arial, verdana, sans-serif;
10
+ font-size: 14px;
11
+ width: 1024px;
12
+ margin: auto;
13
+ margin-top: 20px;
14
+ }
15
+ .clear { clear: both; }
16
+ p { margin: 0px; margin-bottom: 10px; text-align: justify; }
17
+ #title { float: left; margin: 10px 0px 20px 0px; }
18
+ #tabs { float: right; margin: 15px 0px; }
19
+ #tabs li { display: block; float: right; cursor: pointer; margin: 0px 0px 0px 5px; padding: 5px; border: 1px solid black; }
20
+ #tabs li.focus { background-color: #A00000; color: white; }
21
+ dl dt { margin-top: 10px; font-weight: bold; }
22
+ div.header { border-bottom: 1px solid black; margin: 10px 0px; }
23
+ h2 { float: left; margin: 0px; padding: 0px; }
24
+ h3 { margin-top: 20px; margin-bottom: 10px; text-decoration: underline;}
25
+ dl { padding-left: 35px; }
26
+ ul { padding: 0px 0px 0px 25px; }
27
+ ul li { margin: 5px;}
28
+ ul.links { float: right; margin: 0px; padding: 0px; }
29
+ ul.links li { cursor: pointer; margin: 0px 0px 0px 10px; padding: 0px; padding-top: 5px; display: block; float: right; }
30
+ ul.links li a, ul.links li a:visited { color: black; text-decoration: none; }
31
+ ul.links li a:hover { color: #A00000; }
32
+ h3 { margin-bottom: 5px; }
33
+ h4 { margin-bottom: 3px; float: left; margin-top: 0px; }
34
+ table { border-collapse: collapse; border: 1px solid black; }
35
+ table th { font-size: 12px; }
36
+ table th, table td { padding: 4px; }
37
+ table.glossary { margin-top: 20px; }
38
+ table.glossary th { background: green; color: white; border-bottom: 1px solid black; }
39
+ table.glossary th.term { width: 100px; }
40
+ table.glossary td { border-bottom: 1px dashed black; }
41
+ table.symbols { font-size: 12px; margin-top: 20px; width: 100%; }
42
+ table.symbols th { background: green; color: white; border-bottom: 1px solid black; }
43
+ table.symbols th.name { width: 150px; }
44
+ table.symbols th.symbol { width: 50px; }
45
+ table.symbols th.meaning { width: 250px; }
46
+ table.symbols td { border-bottom: 1px dashed black; }
47
+ table.ruleset { font-size: 12px; }
48
+ table.ruleset th { background: green; color: white; }
49
+ table.ruleset td { border-bottom: 1px dashed black; }
50
+ th.signature, td.signature { width: 300px; }
51
+ th.name, td.name { width: 120px; }
52
+ th.definition, td.definition { width: 580px; }
53
+ table.examples { float: right; font-size: 12px; }
54
+ table.examples th { background: #A00000; color: white; border-bottom: 1px solid black; }
55
+ table.examples th, table.examples td { padding: 4px; }
56
+ table.examples td { border-bottom: 1px dashed black; }
57
+ th.dialect, td.dialect { width: 150px; }
58
+ th.expression, td.expression { width: 350px; }
59
+ th.replacement, td.replacement { width: 350px; }
60
+
61
+ </style>
62
+ <script type="text/javascript" language="JavaScript"><!--
63
+ var current = 'about'
64
+ function show(who) {
65
+ document.getElementById(current).style.display = "none";
66
+ document.getElementById(current + 'focus').className = "unfocus";
67
+ document.getElementById(who).style.display = "block";
68
+ document.getElementById(who + 'focus').className = "focus";
69
+ current = who;
70
+ }
71
+
72
+ //--></script>
73
+ </head>
74
+ <body onload="show('about')">
75
+ <h1 id="title">WLang (version 0.8.4)</h1>
76
+ <ul id="tabs">
77
+ <li id="symbolsfocus" onclick="show('symbols')">Tag symbols</li>
78
+ <li id="glossaryfocus" onclick="show('glossary')">Glossary</li>
79
+ <li id="hostingfocus" onclick="show('hosting')">Hosting language</li>
80
+ <li id="dialectsfocus" onclick="show('dialects')">Dialects</li>
81
+ <li id="rulesetsfocus" onclick="show('rulesets')">Rulesets</li>
82
+ <li id="overviewfocus" onclick="show('overview')">Overview</li>
83
+ <li id="aboutfocus" onclick="show('about')">About</li>
84
+
85
+ </ul>
86
+ <div class="clear"></div>
87
+ <div id="about" style="display: none;">
88
+ <div class="header">
89
+ <h2>About</h2>
90
+
91
+ <div class="clear"></div>
92
+ </div>
93
+ <p>
94
+ WLang is a a reusable and extensible <em>code generator</em>, also known as
95
+ a <em>templating engine</em>. Motivation for it can be found at <a
96
+ href="http://www.revision-zero.org/wlang">www.revision-zero.org/wlang</a>.
97
+ The current file is the reference of the tool.
98
+ </p>
99
+ <h3>Topics</h3>
100
+ <dl>
101
+ <dt>Short overview</dt><dd>Probably the first section to read! Basic usage of <em>wlang</em> is
102
+ explained here and pointers are given to continue your learning.
103
+
104
+ </dd>
105
+ <dt>Rulesets</dt><dd>Standard rulesets are specified. As most of them are included in standard
106
+ dialects, looking at standard rulesets is the quickest way to learn all of
107
+ them at once.
108
+
109
+ </dd>
110
+ <dt>Dialects</dt><dd>Standard dialects are described. This page also provides useful cheatsheets
111
+ of available tags in standard dialects.
112
+
113
+ </dd>
114
+ <dt>Hosting language</dt><dd>Somewhat more tricky but powerful. The notion of hosting language is
115
+ explained more deeply. Implementing you own hosting language abstraction
116
+ (advanced topic) sometimes leads to cleaner and cross-implementation
117
+ templates.
118
+
119
+ </dd>
120
+ <dt>Glossary</dt><dd><em>wlang</em> comes with a terminology, knowing it will make your reading
121
+ easier.
122
+
123
+ </dd>
124
+ <dt>Symbols</dt><dd>If you plan to create your own tags, it can be useful to know what is
125
+ allowed and what is not. This pages covers this topic.
126
+
127
+ </dd>
128
+ </dl>
129
+ <h3>About this document</h3>
130
+ <p>
131
+ This document is a simple .html file without external dependencies
132
+ (embedded CSS and javascript). As it contains several cheatsheets, you can
133
+ simply save it on your harddisk without having to be online to browse the
134
+ documentation. It has been generated using <em>wlang</em> itself using the
135
+ following command:
136
+ </p>
137
+ <pre>
138
+ wlang specification.wtpl
139
+ </pre>
140
+ <p>
141
+ The file &#8216;specification.wtpl&#8217; is almost empty and other files
142
+ next to it are all kept simple and written in the most appropriate format
143
+ for the task at hand (YAML for structured parts, RDoc for text sections,
144
+ sometimes YAML embedding short sentences writted in RDoc style, etc.). One
145
+ way to learn <em>wlang</em> quickly is to download the source distribution
146
+ and to look how this is made possible ;-)
147
+ </p>
148
+ <p>
149
+ This reference document is under a <a
150
+ href="http://creativecommons.org/licenses/by/2.0/be/">Creative Commons
151
+ Licence 2.0</a> contract. You can use it, redistribute it and modify it
152
+ providing that you keep a reference to the original licensor (namely, the
153
+ &#8216;University of Louvain&#8217; or &#8216;Bernard and Louis
154
+ Lambeau&#8217;).
155
+ </p>
156
+ <p>
157
+ Enjoy <em>wlang</em> !
158
+ </p>
159
+ <h3>Distribution</h3>
160
+ <ul>
161
+ <li>The reference implementation of <em>wlang</em>, implemented in Ruby, is
162
+ freely available as a &#8216;wlang&#8217; gem (under MIT licence). <br/>
163
+ Use <tt>'gem install wlang'</tt> to install it. For repository and bug
164
+ tracker visit us on <a href="http://github.com/blambeau/wlang">github</a>
165
+
166
+ </li>
167
+ <li>We don&#8217;t have another implementation up to now. If you plan to start
168
+ one in another language, let us know!
169
+
170
+ </li>
171
+ </ul>
172
+ <h3>Authors</h3>
173
+ <p>
174
+ <em>wlang</em> has been initially designed by Bernard and Louis Lambeau
175
+ during the implementation of w@w, yet another web framework (proof of
176
+ concept). They are also maintainers of the reference implementation.
177
+ </p>
178
+ <h3>Credits</h3>
179
+ <p>
180
+ This work is supported by the <a
181
+ href="http://www.uclouvain.be/en-ingi.html">department of computer
182
+ science</a> of the <a
183
+ href="http://www.uclouvain.be/en-index.html">University of Louvain</a>
184
+ (EPL/INGI, Universite Catholique de Louvain, UCL, Louvain-la-Neuve,
185
+ Belgium).
186
+ </p>
187
+ <p>
188
+ This work was also partially supported by the Regional Government of
189
+ Wallonia (ReQuest project, RW Conv. 315592 and GISELE project, RW Conv.
190
+ 616425) and the MoVES project (PAI program of the Belgian government).
191
+ </p>
192
+
193
+
194
+ </div>
195
+ <div id="overview" style="display: none;">
196
+ <div class="header">
197
+ <h2>Overview</h2>
198
+
199
+ <div class="clear"></div>
200
+ </div>
201
+ <h3>What is <em>wlang</em> designed for?</h3>
202
+ <p>
203
+ <em>wlang</em> helps you <b>generating code</b>, in a broad sense. It was
204
+ originally the templating engine of w@w, a proof-of-concept web framework.
205
+ While more powerful than the original version, the <b>templating engine</b>
206
+ ability of <em>wlang</em> has been kept unchanged. For this reason,
207
+ generating html code with <em>wlang</em> is probably a bit more mature than
208
+ generating ruby, java or sql code, to take some examples of what
209
+ <em>wlang</em> can do. It is the author opinion that <em>wlang</em> will
210
+ also become mature quiclky for these tasks because of its foundations:
211
+ <b>its engine is generic</b> (in a sense, <em>wlang</em> does not really
212
+ care about what it generates) but is <b>fully and easily configurable</b>.
213
+ Generation of html files is mature because <em>wlang</em> has been used a
214
+ lot for such a job; thus its authors have acquired experience of what is
215
+ useful when generating simple as well as complex html files. This
216
+ experience led us to a mature configuration of the <em>wlang</em> engine
217
+ for generating html files, as the following paragraph illustrates (for
218
+ people interested in generating code in other languages than html,
219
+ don&#8217;t stop your reading here: the paragraph immediately following
220
+ contains information for you!)
221
+ </p>
222
+ <p>
223
+ Consider this file for example, which is completely self-contained. It
224
+ consists of several parts, some of them being structured - the tables for
225
+ example - while others are not. It also embeds a complete CSS stylesheet
226
+ and some javascript functions. We have not written this file manually, nor
227
+ do we maintain it this way. In fact, this reference document is entirely
228
+ generated by <em>wlang</em> itself from separated parts written mainly in
229
+ yaml and rdoc files. Also, the cheatsheets given later contains a lot of
230
+ examples. To ensure that all of them are correct, we simply ask
231
+ <em>wlang</em> to compute them during generation (technically, we say that
232
+ <b><em>wlang</em> naturally allows metaprogramming</b>). Lastly, if
233
+ <em>wlang</em> can be used inside a web framework, it can also be used as a
234
+ standalone (commandline) tool for generating single files like this one or
235
+ multiple files, even if all of them are of different nature.
236
+ </p>
237
+ <p>
238
+ <b>Maybe you are looking for a code generator for another language than
239
+ html</b> (which one does not really care, unless really specific; we call
240
+ it the <em>target language</em>)? Don&#8217;t be affraid by our previous
241
+ words about <em>wlang</em>&#8217;s maturity: even in such a case,
242
+ <em>wlang</em> is your friend. Start with an existing dialect (see later
243
+ about dialects), which will provide basic utilities for starting and try to
244
+ identify common patterns when you use them. Then simply create special
245
+ shortcuts that are more friendly to use than combining several existing
246
+ utils &#8230; you are on the way of creating your own mature and reusable
247
+ dialect for that target language. In this case, don&#8217;t forget to share
248
+ it &#8230;
249
+ </p>
250
+ <h3>Template and instantiation</h3>
251
+ <p>
252
+ The <em>wlang</em> grammar used to write a <em>template</em> is generic and
253
+ simple: every character stands for itself (meaning that it is reproduced
254
+ exactly when the template is instantiated) except <em>tags</em> (and their
255
+ associated <em>blocks</em>, enclosed between &#8217;{&#8217; and
256
+ &#8217;}&#8217;) that are replaced by what is called the <em>replacement
257
+ value</em>. Consider the following example:
258
+ </p>
259
+ <pre>
260
+ &lt;html&gt;
261
+ &lt;head&gt;
262
+ &lt;title&gt;${title}&lt;/title&gt;
263
+ &lt;/head&gt;
264
+ &lt;body&gt;
265
+ &lt;h1&gt;Hello *{authors as who}{${who}}{, } !&lt;/h1&gt;
266
+ &lt;/body&gt;
267
+ &lt;/html&gt;
268
+ </pre>
269
+ <p>
270
+ Assume that we have some instantitation data through the following hash (or
271
+ something similar, like a YAML file):
272
+ </p>
273
+ <pre>
274
+ {&quot;title&quot; =&gt; &quot;Short overview of wlang&quot;, &quot;authors&quot; =&gt; [&quot;blambeau&quot;, &quot;llambeau&quot;, &quot;ancailliau&quot;]}
275
+ </pre>
276
+ <p>
277
+ When instantiated this template will produce exactly the same html file
278
+ except for special tags <tt>${title}</tt> and <tt>*{whos as who}{${who}}{,
279
+ }</tt> that will be replaced by <tt>'Short overview of wlang'</tt> and
280
+ <tt>'blambeau, llambeau, ancailliau'</tt>, respectively. A lot of tags is
281
+ available, each of them being designed for a specific task: inserting the
282
+ value of a variable, iterating over collections, including another file,
283
+ dynamically loading instantiation data, etc. All of these things are
284
+ commonly proposed by templating engines and <em>wlang</em> is one of them
285
+ &#8230; However, <em>wlang</em> is a bit different as will quickly appear.
286
+ </p>
287
+ <p>
288
+ Indeed (and maybe surprisingly) <em>wlang</em> can also behave really
289
+ differently on the same template: replacing <tt>${title}</tt> but not
290
+ <tt>*{...}</tt> or the converse, or not replacing anything, or replacing
291
+ both tags but not <tt>${who}</tt>, etc. All of this is possible in
292
+ <em>wlang</em>. The magic relies under the notion of <em>dialect</em>,
293
+ which you need to understand.
294
+ </p>
295
+ <h3>Dialects and Rulesets</h3>
296
+ <p>
297
+ The notion of dialect drives the recognition of tags as well as their
298
+ replacement during instantiation. Dialects are what makes <em>wlang</em>
299
+ really powerful: if instantiated as being written in the
300
+ <tt>wlang/xhtml</tt> dialect, the template above will give the result
301
+ mentionned previously. In contrast, if written in <tt>wlang/dummy</tt> the
302
+ template will be reproduced whitout any change (no tag replacement at all).
303
+ This behavior is not hardcoded; it results from the definition of wlang
304
+ (standard) dialects: <tt>wlang/xhtml</tt> define special meanings for
305
+ <tt>${...}</tt> and <tt>*{...}{...}{...}</tt> while <tt>wlang/dummy</tt>
306
+ does not.
307
+ </p>
308
+ <p>
309
+ The replacement of a given <em>tag</em> during instantiation is computed by
310
+ what we call the <em>rule</em> attached to the tag (keeping rules and tags
311
+ as different concepts leads to another feature of <em>wlang</em>: you can
312
+ reuse rule implementations and attach them to other tags than those
313
+ proposed). A dialect comes with a set of (tag, rule) pairs that determine
314
+ its replacement behavior. Such a set is called a <em>ruleset</em>; for
315
+ easier reuse, standard rulesets are already implemented. A dialect is a
316
+ packaging of standard rulesets (and maybe implements specific tag/rule
317
+ pairs) designed for generating code in a given target language.
318
+ </p>
319
+ <p>
320
+ A complete <em>wlang</em> implementation already provides standard dialects
321
+ for common tasks: creating html pages, building SQL queries, generating
322
+ code in Ruby or in another language, etc. Each dialect comes with special
323
+ tags that are useful for the task at hand (a tag for back-quoting values is
324
+ useful for creating SQL queries but does not really makes sense for
325
+ generating an html page where, in contrast, a tag for encoding entities is
326
+ probably welcome). Such an implementation also allows you to extend
327
+ standard dialects and to create your own dialect by implementing specific
328
+ tags and rules or by reusing existing ones. Lastlty, the dialect in used
329
+ during instantiation can be changed dynamically (<em>explicitly</em>, by
330
+ using the <tt>%{dialect/qualified/name}{...}</tt> standard tag and
331
+ <em>implicitly</em>, when rules parse their blocks).
332
+ </p>
333
+ <p>
334
+ To learn more about standard dialects and reusable rules, read the
335
+ &#8216;Dialects&#8217; and &#8216;Rulesets&#8217; pages of this
336
+ documentation.
337
+ </p>
338
+ <h3>Grammar</h3>
339
+ <p>
340
+ The (abstract) <em>wlang</em> grammar rules what forms a valid template. At
341
+ first glance, this grammar does not depend on the dialect that is used for
342
+ instantiation. It is simple, but comes with some constraints that are
343
+ explained below:
344
+ </p>
345
+ <ul>
346
+ <li>block delimiters are &#8217;{&#8217; and &#8217;}&#8217; by default;
347
+ <em>wlang</em> can be configured to use &#8217;(&#8217; and &#8217;)&#8217;
348
+ or &#8217;[&#8217; and &#8217;]&#8217; instead. However, block
349
+ <b>delimiters are template-specific</b>: only one kind of delimiters can be
350
+ used inside the same template.
351
+
352
+ </li>
353
+ <li>block delimiters <b>must always be paired</b>, even when not used for
354
+ delimiting blocks. If an opening or closing delimiter is not paired, it
355
+ must be escaped with a backslash, which will not be reproduced. If you want
356
+ a backslash to appear before a block delimiter in the instantiation result,
357
+ use a double backslash.
358
+
359
+ </li>
360
+ <li>if a given tag has a special meaning in the current dialect and you
361
+ don&#8217;t want it to be replaced by <em>wlang</em> you can escape it with
362
+ a backslash as well (the backslash will not be reproduced).
363
+
364
+ </li>
365
+ <li>some tags (precisely: some rules associated with tags) require multiple
366
+ blocks (like <tt>*{...}{...}{...}</tt> in <tt>wlang/xhtml</tt> for example,
367
+ with the third block bein optional). In such a case no character is allowed
368
+ between the end of a block &#8217;}&#8217; and the start of the next one
369
+ &#8217;{&#8217;, not even spaces or a carriage return. In other words,
370
+ multiple blocks (that must be interpreted as such) must touch each others
371
+ using &#8217;}{&#8217; precisely, as ilustrated below. If a non-optional
372
+ block is missing a parse error is raised by the <em>wlang</em>
373
+ implementation.
374
+
375
+ <pre>
376
+ *{authors as who}{${who}}{, } -&gt; blambeau, llambeau, ancailliau
377
+ *{authors as who}{${who}} {, } -&gt; blambeaullambeauancailliau {, }
378
+ *{authors as who} {${who}}{, } -&gt; parse error 1:18, missing block 2 in *{...}{...}
379
+ </pre>
380
+ </li>
381
+ </ul>
382
+ <p>
383
+ In addition to these constraints, dialects and the hosting language may
384
+ impose restrictions on what can be put inside specific blocks of tags/rules
385
+ (for example, &#8216;authors as who&#8217; is valid as first tag of
386
+ <tt>*{...}{...}</tt> but not every string is, of course). These constraints
387
+ are not specific to the wlang grammar <em>per se</em> and are explained in
388
+ the &#8216;Rulesets&#8217;, &#8216;Dialects&#8217; and &#8216;Hosting
389
+ language&#8217; pages of this document.
390
+ </p>
391
+
392
+
393
+ </div>
394
+ <div id="rulesets" style="display: none;">
395
+ <div class="header">
396
+ <h2>Rulesets</h2>
397
+ <ul class="links">
398
+ <li><a href="#Buffering">Buffering</a></li><li><a href="#Context">Context</a></li><li><a href="#Imperative">Imperative</a></li><li><a href="#Encoding">Encoding</a></li><li><a href="#Basic">Basic</a></li>
399
+ </ul>
400
+
401
+ <div class="clear"></div>
402
+ </div>
403
+ <p>
404
+ Standard ruleset are designed to be reusable: including them in your own
405
+ dialect is made easy by a typical <em>wlang</em> implementation. Some of
406
+ them are also included by standard dialects.
407
+ </p>
408
+ <h3>How to read this cheatsheet?</h3>
409
+ <p>
410
+ First of all, focus on the examples; they are written to let you learn
411
+ <em>wlang</em> quickly and deeply. Some of them are a bit difficult to
412
+ understand but they are representative of <em>wlang</em> powerfulness
413
+ (don&#8217;t be affraid: in practice, some constructions are never used).
414
+ Don&#8217;t forget that the <tt>wlang/dummy</tt> dialect does not recognize
415
+ any tag. We also assume instantiation data to be the following hash:
416
+ </p>
417
+ <pre>
418
+ {&quot;name&quot; =&gt; &quot;O'Neil&quot;,
419
+ &quot;author&quot; =&gt; &quot;blambeau&quot;
420
+ &quot;authors&quot; =&gt; [&quot;blambeau&quot;, &quot;llambeau&quot;, &quot;ancailliau&quot;]}
421
+ </pre>
422
+ <p>
423
+ Moreover, the dialect column in the examples is important; <em>wlang</em>
424
+ behaves differently in different dialects. When the dialect does not care,
425
+ we use <tt>wlang/*</tt> which means &#8216;in any dialect that includes
426
+ this ruleset&#8217;.
427
+ </p>
428
+ <p>
429
+ Next, certain rule definitions are given as shortcuts for longer
430
+ expressions, involving other tags. This is somewhat representative of
431
+ <em>wlang</em> usage, even if these rules are not actually implemented this
432
+ way (mainly for efficiency concerns). Once again, understanding shortcuts
433
+ will help you mastering wlang! In definitions (textual as well as
434
+ shortcuts), we use #1, #2, and #3 to refer to the content of the blocks.
435
+ Those identifiers are not real <em>wlang</em> constructs, but are only used
436
+ here for easier explanations (for those who know this kind of vocabulary:
437
+ they are part of the meta-language, not the language <em>per se</em>).
438
+ </p>
439
+ <p>
440
+ Lastly, dialect names that appear in rule signatures are to be interpreted
441
+ as an implicit dialect modulation: the corresponding block (often the first
442
+ one) is not instantiated in the current dialect but in the one specified by
443
+ the signature. In contrast, when we use &#8217;&#8230;&#8217; it means that
444
+ the corresponding block is simply instantiated in the current dialect.
445
+ Implicit dialect modulation is in fact natural: if a block expects an uri
446
+ for example, the easiest way is to give it exactly:
447
+ <tt>&lt;&lt;{a/file/to/include.txt}</tt>. But you can even compute it using
448
+ <em>wlang</em>, as illustrated by the example below. In complex situations
449
+ you will probably be happy to use a dialect that helps you doing so (think
450
+ at all blocks that expect an expression in the hosting language, for
451
+ example)!
452
+ </p>
453
+ <pre>
454
+ # Concatenates all files of the 'files' array variable
455
+ *{files as f}{&lt;&lt;{+{f}}}
456
+ </pre>
457
+
458
+
459
+ <h3 id="Basic">Basic</h3>
460
+ <p>
461
+ The Basic ruleset is commonly installed on any dialect and provides access
462
+ to <em>wlang</em> foundations inside your template: requesting the hosting
463
+ language to execute some expression, changing the current dialect and
464
+ encoding text.
465
+ </p>
466
+
467
+ <table class="ruleset">
468
+ <tr>
469
+ <th class="signature">signature</th>
470
+ <th class="name">name</th>
471
+ <th class="definition">definition</th>
472
+ </tr>
473
+ <tr>
474
+ <td class="signature"><tt>!{wlang/hosted}</tt></td>
475
+ <td class="name">execution</td>
476
+ <td class="definition">Instantiates #1, looking for an expression of the hosting language.
477
+ Evaluates it, looking for any object. Converts it to a string (using to_s
478
+ for example if Ruby is the hosting language) and returns the result as
479
+ replacement value.</td>
480
+ </tr>
481
+ <tr>
482
+ <td class="signature"><tt>%{wlang/active-string}{...}</tt></td>
483
+ <td class="name">modulation</td>
484
+ <td class="definition">Instantiates #1, looking for a dialect qualified name. Instantiates #2
485
+ according to the rules defined by that dialect and returns the #2&#8217;s
486
+ instantiation as replacement value.</td>
487
+ </tr>
488
+ <tr>
489
+ <td class="signature"><tt>^{wlang/active-string}{...}</tt></td>
490
+ <td class="name">encoding</td>
491
+ <td class="definition">Instantiates #1, looking for an encoder qualified name. Instantiates #2 in
492
+ the current dialect. Encode #2&#8217;s instantiation using encoder found in
493
+ (#1) and returns encoding as replacement value.</td>
494
+ </tr>
495
+ <tr>
496
+ <td class="signature"><tt>%!{wlang/active-string &lt;using&gt;? &lt;with&gt;?}{...}</tt></td>
497
+ <td class="name">recursive-application</td>
498
+ <td class="definition">Instantiates #1, looking for a dialect qualified name. Instantiates #2 in
499
+ the current dialect. Instantiates #2&#8217;s instantiation in the dialect
500
+ found in #1, using context installed by &#8216;using &#8230;&#8217; and
501
+ &#8216;with &#8230;&#8217;. Returns this instantiation as replacement value
502
+ (this really advanced rule allows metaprogramming).</td>
503
+ </tr>
504
+ <tr>
505
+ <td class="signature"><tt>${wlang/hosted}</tt></td>
506
+ <td class="name">injection</td>
507
+ <td class="definition">Same semantics as execution (intended to be overrided).</td>
508
+ </tr>
509
+ <tr>
510
+ <td class="signature"><tt>+{wlang/hosted}</tt></td>
511
+ <td class="name">inclusion</td>
512
+ <td class="definition">Same semantics as execution (intended to be overrided).</td>
513
+ </tr>
514
+
515
+ </table>
516
+
517
+ <br/>
518
+ <h4>Examples:</h4>
519
+ <table class="examples">
520
+ <tr>
521
+ <th>dialect</th>
522
+ <th>wlang expression</th>
523
+ <th>replacement value</th>
524
+ </tr>
525
+ <tr>
526
+ <td class="dialect">
527
+ <tt>wlang/active-string</tt>
528
+ </td>
529
+ <td class="expression">
530
+ <tt>Hello !{name}</tt>
531
+ </td>
532
+ <td class="replacement">
533
+ <tt>Hello O'Neil</tt>
534
+
535
+ </td>
536
+ </tr>
537
+ <tr>
538
+ <td class="dialect">
539
+ <tt>wlang/active-string</tt>
540
+ </td>
541
+ <td class="expression">
542
+ <tt>Hello %{wlang/dummy}{!{name}}</tt>
543
+ </td>
544
+ <td class="replacement">
545
+ <tt>Hello !{name}</tt>
546
+
547
+ </td>
548
+ </tr>
549
+ <tr>
550
+ <td class="dialect">
551
+ <tt>wlang/dummy</tt>
552
+ </td>
553
+ <td class="expression">
554
+ <tt>Hello %{wlang/dummy}{!{name}}</tt>
555
+ </td>
556
+ <td class="replacement">
557
+ <tt>Hello %{wlang/dummy}{!{name}}</tt>
558
+
559
+ </td>
560
+ </tr>
561
+ <tr>
562
+ <td class="dialect">
563
+ <tt>wlang/active-string</tt>
564
+ </td>
565
+ <td class="expression">
566
+ <tt>Hello ^{plain-text/upcase}{${name}}</tt>
567
+ </td>
568
+ <td class="replacement">
569
+ <tt>Hello O'NEIL</tt>
570
+
571
+ </td>
572
+ </tr>
573
+
574
+ </table>
575
+ <div style="clear: both;"></div>
576
+ <h3 id="Encoding">Encoding</h3>
577
+ <p>
578
+ Almost all languages require escaping/encoding in specific situations:
579
+ quoted string literals always come with an escaping mechanism
580
+ (unfortunately different from one language to another), html requires
581
+ entities-encoding, etc. The Encoding ruleset proposes shortcut tags for
582
+ encoding. Note that these shortcuts are written in such a way that they
583
+ don&#8217;t depend on the effective dialect. <em>wlang</em> hides language
584
+ and vendors differences!
585
+ </p>
586
+
587
+ <table class="ruleset">
588
+ <tr>
589
+ <th class="signature">signature</th>
590
+ <th class="name">name</th>
591
+ <th class="definition">definition</th>
592
+ </tr>
593
+ <tr>
594
+ <td class="signature"><tt>&amp;{...}</tt></td>
595
+ <td class="name">main-encoding</td>
596
+ <td class="definition"><tt>^{+{@parser.current_dialect}/main-encoding}{#1}</tt></td>
597
+ </tr>
598
+ <tr>
599
+ <td class="signature"><tt>&amp;;{...}</tt></td>
600
+ <td class="name">entities-encoding</td>
601
+ <td class="definition"><tt>^{+{@parser.current_dialect}/entities-encoding}{#1}</tt></td>
602
+ </tr>
603
+ <tr>
604
+ <td class="signature"><tt>&amp;'{...}</tt></td>
605
+ <td class="name">single-quoting</td>
606
+ <td class="definition"><tt>^{+{@parser.current_dialect}/single-quoting}{#1}</tt></td>
607
+ </tr>
608
+ <tr>
609
+ <td class="signature"><tt>&amp;&quot;{...}</tt></td>
610
+ <td class="name">double-quoting</td>
611
+ <td class="definition"><tt>^{+{@parser.current_dialect}/double-quoting}{#1}</tt></td>
612
+ </tr>
613
+ <tr>
614
+ <td class="signature"><tt>${wlang/hosted}</tt></td>
615
+ <td class="name">injection</td>
616
+ <td class="definition"><tt>&amp;{+{#1}}</tt></td>
617
+ </tr>
618
+ <tr>
619
+ <td class="signature"><tt>'{wlang/hosted}</tt></td>
620
+ <td class="name">single-quoted</td>
621
+ <td class="definition"><tt>'&amp;'{+{#1}}</tt> (first single quote is kept in the result)</td>
622
+ </tr>
623
+ <tr>
624
+ <td class="signature"><tt>&quot;{wlang/hosted}</tt></td>
625
+ <td class="name">double-quoted</td>
626
+ <td class="definition"><tt>&quot;&amp;&quot;{+{#1}}</tt> (first double quote is kept in the
627
+ result)</td>
628
+ </tr>
629
+
630
+ </table>
631
+
632
+ <br/>
633
+ <h4>Examples:</h4>
634
+ <table class="examples">
635
+ <tr>
636
+ <th>dialect</th>
637
+ <th>wlang expression</th>
638
+ <th>replacement value</th>
639
+ </tr>
640
+ <tr>
641
+ <td class="dialect">
642
+ <tt>wlang/xhtml</tt>
643
+ </td>
644
+ <td class="expression">
645
+ <tt>Hello &amp;{name}</tt>
646
+ </td>
647
+ <td class="replacement">
648
+ <tt>Hello name</tt>
649
+
650
+ </td>
651
+ </tr>
652
+ <tr>
653
+ <td class="dialect">
654
+ <tt>wlang/xhtml</tt>
655
+ </td>
656
+ <td class="expression">
657
+ <tt>Hello &amp;{&lt;script&gt;}</tt>
658
+ </td>
659
+ <td class="replacement">
660
+ <tt>Hello &lt;script&gt;</tt>
661
+
662
+ </td>
663
+ </tr>
664
+ <tr>
665
+ <td class="dialect">
666
+ <tt>wlang/xhtml</tt>
667
+ </td>
668
+ <td class="expression">
669
+ <tt>Hello &amp;;{&lt;script&gt;}</tt>
670
+ </td>
671
+ <td class="replacement">
672
+ <tt>Hello &lt;script&gt;</tt>
673
+
674
+ </td>
675
+ </tr>
676
+ <tr>
677
+ <td class="dialect">
678
+ <tt>wlang/ruby</tt>
679
+ </td>
680
+ <td class="expression">
681
+ <tt>puts 'Hello &amp;'{name}'</tt>
682
+ </td>
683
+ <td class="replacement">
684
+ <tt>puts 'Hello name'</tt>
685
+
686
+ </td>
687
+ </tr>
688
+ <tr>
689
+ <td class="dialect">
690
+ <tt>wlang/ruby</tt>
691
+ </td>
692
+ <td class="expression">
693
+ <tt>puts 'Hello &amp;'{!{name}}'</tt>
694
+ </td>
695
+ <td class="replacement">
696
+ <tt>puts 'Hello O\'Neil'</tt>
697
+
698
+ </td>
699
+ </tr>
700
+ <tr>
701
+ <td class="dialect">
702
+ <tt>wlang/ruby</tt>
703
+ </td>
704
+ <td class="expression">
705
+ <tt>puts 'Hello ' &lt;&lt; '{name}'</tt>
706
+ </td>
707
+ <td class="replacement">
708
+ <tt>puts 'Hello ' << 'O\'Neil'</tt>
709
+
710
+ </td>
711
+ </tr>
712
+ <tr>
713
+ <td class="dialect">
714
+ <tt>wlang/sql</tt>
715
+ </td>
716
+ <td class="expression">
717
+ <tt>... WHERE name='{name}'</tt>
718
+ </td>
719
+ <td class="replacement">
720
+ <tt>... WHERE name='O\'Neil'</tt>
721
+
722
+ </td>
723
+ </tr>
724
+ <tr>
725
+ <td class="dialect">
726
+ <tt>wlang/sql/sybase</tt>
727
+ </td>
728
+ <td class="expression">
729
+ <tt>... WHERE name='{name}'</tt>
730
+ </td>
731
+ <td class="replacement">
732
+ <tt>... WHERE name='O''Neil'</tt>
733
+
734
+ </td>
735
+ </tr>
736
+
737
+ </table>
738
+ <div style="clear: both;"></div>
739
+ <h3 id="Imperative">Imperative</h3>
740
+ <p>
741
+ Instantiating conditionally and iterating collection elements are common
742
+ code generation tasks. The Imperative dialect provides these features.
743
+ </p>
744
+
745
+ <table class="ruleset">
746
+ <tr>
747
+ <th class="signature">signature</th>
748
+ <th class="name">name</th>
749
+ <th class="definition">definition</th>
750
+ </tr>
751
+ <tr>
752
+ <td class="signature"><tt>?{wlang/hosted}{...}{...}</tt></td>
753
+ <td class="name">conditional<br/>(third block is optional)</td>
754
+ <td class="definition">Instantiates #1, looking for an expression in the hosting language.
755
+ Evaluates it, looking for a boolean value (according to boolean semantics
756
+ of the hosting language). If true, instantiates #2, otherwise instantiates
757
+ #3 if present, returning instantiation as replacement value.</td>
758
+ </tr>
759
+ <tr>
760
+ <td class="signature"><tt>*{wlang/hosted &lt;as x&gt;?}{...}{...}</tt></td>
761
+ <td class="name">enumeration<br/>(third block is optional)</td>
762
+ <td class="definition">Instantiates #1, looking for an expression in the hosting language.
763
+ Evaluates it, looking for an enumerable. Iterates all its elements,
764
+ instantiating #2 for each of them (the iterated value is set under name x
765
+ in the scope). If #3 is present, it is instantiated between elements.
766
+ Replacement is the concatenation of all these instantiations.</td>
767
+ </tr>
768
+
769
+ </table>
770
+
771
+ <br/>
772
+ <h4>Examples:</h4>
773
+ <table class="examples">
774
+ <tr>
775
+ <th>dialect</th>
776
+ <th>wlang expression</th>
777
+ <th>replacement value</th>
778
+ </tr>
779
+ <tr>
780
+ <td class="dialect">
781
+ <tt>wlang/*</tt>
782
+ </td>
783
+ <td class="expression">
784
+ <tt>?{true}{then}{else}</tt>
785
+ </td>
786
+ <td class="replacement">
787
+ <tt>then</tt>
788
+
789
+ </td>
790
+ </tr>
791
+ <tr>
792
+ <td class="dialect">
793
+ <tt>wlang/*</tt>
794
+ </td>
795
+ <td class="expression">
796
+ <tt>?{/th/ =~ &quot;not tat&quot;}{then}{else}</tt>
797
+ </td>
798
+ <td class="replacement">
799
+ <tt>else</tt>
800
+
801
+ </td>
802
+ </tr>
803
+ <tr>
804
+ <td class="dialect">
805
+ <tt>wlang/*</tt>
806
+ </td>
807
+ <td class="expression">
808
+ <tt>?{authors.include? &quot;blambeau&quot;}{yes}{no}</tt>
809
+ </td>
810
+ <td class="replacement">
811
+ <tt>yes</tt>
812
+
813
+ </td>
814
+ </tr>
815
+ <tr>
816
+ <td class="dialect">
817
+ <tt>wlang/*</tt>
818
+ </td>
819
+ <td class="expression">
820
+ <tt>[*{authors as a}{&quot;{a}&quot;}{, }]</tt>
821
+ </td>
822
+ <td class="replacement">
823
+ <tt>["blambeau", "llambeau", "ancailliau"]</tt>
824
+
825
+ </td>
826
+ </tr>
827
+
828
+ </table>
829
+ <div style="clear: both;"></div>
830
+ <h3 id="Context">Context</h3>
831
+ <p>
832
+ Complex templates come with specific needs. The ability to manipulate the
833
+ context and the current scope is provided by the Context ruleset. All are
834
+ variants of &#8216;saving previous instantiations&#8217; in scope
835
+ variables&#8230;
836
+ </p>
837
+
838
+ <table class="ruleset">
839
+ <tr>
840
+ <th class="signature">signature</th>
841
+ <th class="name">name</th>
842
+ <th class="definition">definition</th>
843
+ </tr>
844
+ <tr>
845
+ <td class="signature"><tt>={wlang/hosted &lt;as x&gt;}{...}</tt></td>
846
+ <td class="name">assignment<br/>(second block is optional)</td>
847
+ <td class="definition">Instantiates #1, looking for an expression in the hosting language.
848
+ Evaluates it, looking for any object. Without second block, expands the
849
+ current scope with &#8216;x&#8217; being bound to evaluation result.
850
+ Otherwise, branches the current scope for the second block instantiation
851
+ only and bind &#8216;x&#8217; the same way (i.e. x will not be available
852
+ outside the second block). Returns an empty string as replacement value.</td>
853
+ </tr>
854
+ <tr>
855
+ <td class="signature"><tt>%={wlang/active-string &lt;as x&gt;}{...}{...}</tt></td>
856
+ <td class="name">modulo-assignment<br/>(third block is optional)</td>
857
+ <td class="definition">Instantiates #1, looking for a dialect qualified name. Instantiates #2
858
+ according to the rules defined by that dialect. Without third block,
859
+ expands the current scope with &#8216;x&#8217; being bound to #2&#8217;s
860
+ instantiation. Otherwise, branches the current scope for the third block
861
+ instantiation only and binds &#8216;x&#8217; the same way (i.e. x will not
862
+ be available outside the third block). Returns an empty string as
863
+ replacement value.</td>
864
+ </tr>
865
+ <tr>
866
+ <td class="signature"><tt>#={wlang/active-string &lt;as x&gt;}{...}{...}</tt></td>
867
+ <td class="name">block-assignment<br/>(third block is optional)</td>
868
+ <td class="definition"><tt>%={+{@parser.current_dialect} as #1}{#2}{#3}</tt></td>
869
+ </tr>
870
+ <tr>
871
+ <td class="signature"><tt>^={wlang/active-string &lt;as x&gt;}{...}{...}</tt></td>
872
+ <td class="name">encoding-assignment<br/>(third block is optional)</td>
873
+ <td class="definition"><tt>%={+{@parser.current_dialect} as x}{^{#1}{#2}}{#3}</tt></td>
874
+ </tr>
875
+
876
+ </table>
877
+
878
+ <br/>
879
+ <h4>Examples:</h4>
880
+ <table class="examples">
881
+ <tr>
882
+ <th>dialect</th>
883
+ <th>wlang expression</th>
884
+ <th>replacement value</th>
885
+ </tr>
886
+ <tr>
887
+ <td class="dialect">
888
+ <tt>wlang/*</tt>
889
+ </td>
890
+ <td class="expression">
891
+ <tt>={name as n}{Hello +{n}}</tt>
892
+ </td>
893
+ <td class="replacement">
894
+ <tt>Hello O'Neil</tt>
895
+
896
+ </td>
897
+ </tr>
898
+ <tr>
899
+ <td class="dialect">
900
+ <tt>wlang/*</tt>
901
+ </td>
902
+ <td class="expression">
903
+ <tt>={name as n}Hello +{n}</tt>
904
+ </td>
905
+ <td class="replacement">
906
+ <tt>Hello O'Neil</tt>
907
+
908
+ </td>
909
+ </tr>
910
+ <tr>
911
+ <td class="dialect">
912
+ <tt>wlang/*</tt>
913
+ </td>
914
+ <td class="expression">
915
+ <tt>#={name}{blambeau}{Hello +{name}} and +{name}</tt>
916
+ </td>
917
+ <td class="replacement">
918
+ <tt>Hello blambeau and O'Neil</tt>
919
+
920
+ </td>
921
+ </tr>
922
+ <tr>
923
+ <td class="dialect">
924
+ <tt>wlang/*</tt>
925
+ </td>
926
+ <td class="expression">
927
+ <tt>#={name}{blambeau}Hello +{name} and +{name}</tt>
928
+ </td>
929
+ <td class="replacement">
930
+ <tt>Hello blambeau and blambeau</tt>
931
+
932
+ </td>
933
+ </tr>
934
+ <tr>
935
+ <td class="dialect">
936
+ <tt>wlang/*</tt>
937
+ </td>
938
+ <td class="expression">
939
+ <tt>={author as name}{Hello +{name}} and +{name}</tt>
940
+ </td>
941
+ <td class="replacement">
942
+ <tt>Hello blambeau and O'Neil</tt>
943
+
944
+ </td>
945
+ </tr>
946
+ <tr>
947
+ <td class="dialect">
948
+ <tt>wlang/*</tt>
949
+ </td>
950
+ <td class="expression">
951
+ <tt>={author as name}Hello +{name} and +{name}</tt>
952
+ </td>
953
+ <td class="replacement">
954
+ <tt>Hello blambeau and blambeau</tt>
955
+
956
+ </td>
957
+ </tr>
958
+ <tr>
959
+ <td class="dialect">
960
+ <tt>wlang/*</tt>
961
+ </td>
962
+ <td class="expression">
963
+ <tt>%={wlang/dummy as hello}{Hello +{name}}{+{hello}}</tt>
964
+ </td>
965
+ <td class="replacement">
966
+ <tt>Hello +{name}</tt>
967
+
968
+ </td>
969
+ </tr>
970
+ <tr>
971
+ <td class="dialect">
972
+ <tt>wlang/*</tt>
973
+ </td>
974
+ <td class="expression">
975
+ <tt>^={plain-text/upcase as name}{+{author}}{Hello +{name}} and +{name}</tt>
976
+ </td>
977
+ <td class="replacement">
978
+ <tt>Hello BLAMBEAU and O'Neil</tt>
979
+
980
+ </td>
981
+ </tr>
982
+ <tr>
983
+ <td class="dialect">
984
+ <tt>wlang/*</tt>
985
+ </td>
986
+ <td class="expression">
987
+ <tt>^={plain-text/upcase as name}{+{author}}Hello +{name} and +{name}</tt>
988
+ </td>
989
+ <td class="replacement">
990
+ <tt>Hello BLAMBEAU and BLAMBEAU</tt>
991
+
992
+ </td>
993
+ </tr>
994
+
995
+ </table>
996
+ <div style="clear: both;"></div>
997
+ <h3 id="Buffering">Buffering</h3>
998
+ <p>
999
+ The Buffering ruleset is probably one of the more useful. It allows you to
1000
+ load text and data files, to change the current output buffer (for
1001
+ generating multiple files for example) and even to start the instantiation
1002
+ on other templates.
1003
+ </p>
1004
+
1005
+ <table class="ruleset">
1006
+ <tr>
1007
+ <th class="signature">signature</th>
1008
+ <th class="name">name</th>
1009
+ <th class="definition">definition</th>
1010
+ </tr>
1011
+ <tr>
1012
+ <td class="signature"><tt>&lt;&lt;{wlang/uri}</tt></td>
1013
+ <td class="name">input</td>
1014
+ <td class="definition">Instantiates #1, looking for an uri. Returns the text content of the found
1015
+ uri (#1) as replacement value.</td>
1016
+ </tr>
1017
+ <tr>
1018
+ <td class="signature"><tt>&gt;&gt;{wlang/uri}{...}</tt></td>
1019
+ <td class="name">output</td>
1020
+ <td class="definition">Instantiates #1, looking for an uri. Instantiates #2 in the current
1021
+ dialect, using the file found in #1 as output buffer. Returns an empty
1022
+ string as replacement value.</td>
1023
+ </tr>
1024
+ <tr>
1025
+ <td class="signature"><tt>&lt;&lt;={wlang/uri &lt;as x&gt;}{...}</tt></td>
1026
+ <td class="name">data-assignment</td>
1027
+ <td class="definition">Instantiates #1, looking for an uri. Loads data provided by this uri, based
1028
+ on the file extension (typically .yml or .rb). Without second block,
1029
+ expands the current scope with &#8216;x&#8217; being bound to the data.
1030
+ Otherwise, branches the current scope for the second block instantiation
1031
+ only and binds &#8216;x&#8217; the same way (i.e. x will not be available
1032
+ outside the second block). Returns an empty string as replacement value.</td>
1033
+ </tr>
1034
+ <tr>
1035
+ <td class="signature"><tt>&lt;&lt;+{wlang/uri &lt;using&gt;? &lt;with&gt;?}</tt></td>
1036
+ <td class="name">input-inclusion</td>
1037
+ <td class="definition">Instantiates #1, looking for an uri. Instantiates the <em>wlang</em>
1038
+ template at this location (the dialect is infered from the file extension)
1039
+ in a fresh new scope built from the <em>with</em> expression. Returns this
1040
+ instantiation as replacement value.</td>
1041
+ </tr>
1042
+
1043
+ </table>
1044
+
1045
+
1046
+ </div>
1047
+ <div id="dialects" style="display: none;">
1048
+ <div class="header">
1049
+ <h2>Dialects</h2>
1050
+
1051
+ <div class="clear"></div>
1052
+ </div>
1053
+
1054
+
1055
+ </div>
1056
+ <div id="hosting" style="display: none;">
1057
+ <div class="header">
1058
+ <h2>Hosting language</h2>
1059
+
1060
+ <div class="clear"></div>
1061
+ </div>
1062
+
1063
+
1064
+ </div>
1065
+ <div id="glossary" style="display: none;">
1066
+ <div class="header">
1067
+ <h2>Glossary</h2>
1068
+
1069
+ <div class="clear"></div>
1070
+ </div>
1071
+ <table class="glossary">
1072
+ <tr>
1073
+ <th class="term">term</th>
1074
+ <th class="definition">definition</th>
1075
+ <th class="example">example</th>
1076
+ </tr>
1077
+ <tr>
1078
+ <td><em>template</em></td>
1079
+ <td>Source code respecting the wlang grammar, and attached to a given <em>wlang
1080
+ dialect</em>.</td>
1081
+ <td style="font-size: 90%;"><tt>Hello ${name}</tt></td>
1082
+ </tr>
1083
+ <tr>
1084
+ <td><em>dialect</em></td>
1085
+ <td>Basically, <em>dialect</em> is used as a synonym for (programming)
1086
+ <em>language</em>. However <em>wlang</em> uses a tree of dialects, allowing
1087
+ specializations: <tt>sql/sybase</tt> for example is the qualified name of a
1088
+ sub-dialect &#8216;sybase&#8217; of the &#8216;sql&#8217; dialect. Dialects
1089
+ come with associated <em>encoders</em>.</td>
1090
+ <td style="font-size: 90%;"><tt>sql/sybase</tt></td>
1091
+ </tr>
1092
+ <tr>
1093
+ <td><em>wlang dialect</em></td>
1094
+ <td>When we talk about a <em>wlang dialect</em>, we are actually refering to
1095
+ some specialization of the wlang tag-based grammar: <tt>wlang/xhtml</tt>
1096
+ for example is the templating language <em>wlang</em> proposes to generate
1097
+ xhtml pages. An example of source code in that dialect has been shown
1098
+ before. In addition to its encoders a <em>wlang dialect</em> comes with its
1099
+ sets of <em>tags</em> and associated <em>rules</em>.</td>
1100
+ <td style="font-size: 90%;"><tt>wlang/xhtml</tt></td>
1101
+ </tr>
1102
+ <tr>
1103
+ <td><em>encoder</em></td>
1104
+ <td>Text transformation (algorithm) applying some encoding conventions of a
1105
+ portion of a the target language generated by a dialect. HTML
1106
+ entities-encoding, SQL&#8217;s back-quoting are examples of encoders.
1107
+ Encoders are accessible through their qualified name (dialect/encoder).</td>
1108
+ <td style="font-size: 90%;"><tt>xhtml/entities-encoding</tt><br/><tt>sql/single-quoting</tt></td>
1109
+ </tr>
1110
+ <tr>
1111
+ <td><em>ruleset</em></td>
1112
+ <td>Reusable set of <em>tags</em> associated to <em>rule</em>s.</td>
1113
+ <td style="font-size: 90%;"><tt>Imperative ruleset</tt><br/><tt>Encoding rulset</tt></td>
1114
+ </tr>
1115
+ <tr>
1116
+ <td><em>wlang tag</em></td>
1117
+ <td>Special tags in the template, starting with wlang symbols and a number of
1118
+ wlang blocks. A tag is associated with a wlang rule.</td>
1119
+ <td style="font-size: 90%;"><tt>${...}</tt><br/><tt>?{...}{...}{...}</tt></td>
1120
+ </tr>
1121
+ <tr>
1122
+ <td><em>rule</em></td>
1123
+ <td>Transformation semantics of a given <em>tag</em>. When wlang instantiates a
1124
+ template it simply replaces <em>wlang tags</em> by some <em>replacement
1125
+ value</em> (which is always a string). This value is computed by the rule
1126
+ attached to the tag. Rule definition (see Rulesets tab on top of the page)
1127
+ explicitly describes the number of blocks it expects, in which dialect they
1128
+ are parsed and instantiated and the way the replacement value is computed.</td>
1129
+ <td style="font-size: 90%;"><tt>^{wlang/active-string}{...}</tt><br/> Instantiates #1, looking for an
1130
+ encoder qualified name. Instantiates #2 in the current dialect. Encode
1131
+ #2&#8217;s instantiation using encoder found in (#1) and return the result
1132
+ as replacement value.</td>
1133
+ </tr>
1134
+ <tr>
1135
+ <td><em>context</em></td>
1136
+ <td>Some rules allow code to be executed in the <em>hosting language</em> (the
1137
+ definition explicitly announce it by putting <tt>wlang/hosted</tt> in the
1138
+ corresponding block). When doing so, this code is in fact executed in a
1139
+ given context that provides the execution semantics.</td>
1140
+ <td style="font-size: 90%;"></td>
1141
+ </tr>
1142
+ <tr>
1143
+ <td><em>hosting language</em></td>
1144
+ <td>language (or framework) that executes wlang. More precisely, the hosting
1145
+ language is the one that rules what is considered as an executable
1146
+ expression in tags that relies on some execution semantics (like !{&#8230;}
1147
+ for example). See the &#8216;Hosting language&#8217; section to learn more.</td>
1148
+ <td style="font-size: 90%;">ruby</td>
1149
+ </tr>
1150
+
1151
+ </table>
1152
+
1153
+
1154
+ </div>
1155
+ <div id="symbols" style="display: none;">
1156
+ <div class="header">
1157
+ <h2>Tag symbols</h2>
1158
+
1159
+ <div class="clear"></div>
1160
+ </div>
1161
+ <table class="symbols">
1162
+ <tr>
1163
+ <th class="name">name</th>
1164
+ <th class="symbol">symbol</th>
1165
+ <th class="meaning">meaning</th>
1166
+ <th class="remark">remark</th>
1167
+ </tr>
1168
+ <tr>
1169
+ <td><em>exclamation mark</em></td>
1170
+ <td>!</td>
1171
+ <td>execution</td>
1172
+ <td>should never be overrided as single</td>
1173
+ </tr>
1174
+ <tr>
1175
+ <td><em>caret/circumflex</em></td>
1176
+ <td>^</td>
1177
+ <td>explicit encoding</td>
1178
+ <td>should never be overrided as single</td>
1179
+ </tr>
1180
+ <tr>
1181
+ <td><em>percent</em></td>
1182
+ <td>%</td>
1183
+ <td>modulation</td>
1184
+ <td>should never be overrided as single</td>
1185
+ </tr>
1186
+ <tr>
1187
+ <td><em>double quote</em></td>
1188
+ <td>&quot;</td>
1189
+ <td>double-quoting</td>
1190
+ <td></td>
1191
+ </tr>
1192
+ <tr>
1193
+ <td><em>dollar</em></td>
1194
+ <td>$</td>
1195
+ <td>main-encoding</td>
1196
+ <td></td>
1197
+ </tr>
1198
+ <tr>
1199
+ <td><em>ampersand</em></td>
1200
+ <td>&amp;</td>
1201
+ <td>encoding</td>
1202
+ <td></td>
1203
+ </tr>
1204
+ <tr>
1205
+ <td><em>single quote</em></td>
1206
+ <td>'</td>
1207
+ <td>single-quoting</td>
1208
+ <td></td>
1209
+ </tr>
1210
+ <tr>
1211
+ <td><em>asterisk</em></td>
1212
+ <td>*</td>
1213
+ <td>iteration</td>
1214
+ <td></td>
1215
+ </tr>
1216
+ <tr>
1217
+ <td><em>plus</em></td>
1218
+ <td>+</td>
1219
+ <td>inclusion</td>
1220
+ <td></td>
1221
+ </tr>
1222
+ <tr>
1223
+ <td><em>question mark</em></td>
1224
+ <td>?</td>
1225
+ <td>condition</td>
1226
+ <td></td>
1227
+ </tr>
1228
+ <tr>
1229
+ <td><em>at symbol</em></td>
1230
+ <td>@</td>
1231
+ <td>linking</td>
1232
+ <td></td>
1233
+ </tr>
1234
+ <tr>
1235
+ <td><em>tilde</em></td>
1236
+ <td>~</td>
1237
+ <td>matching</td>
1238
+ <td></td>
1239
+ </tr>
1240
+ <tr>
1241
+ <td><em>number sign</em></td>
1242
+ <td>#</td>
1243
+ <td></td>
1244
+ <td></td>
1245
+ </tr>
1246
+ <tr>
1247
+ <td><em>comma</em></td>
1248
+ <td>,</td>
1249
+ <td></td>
1250
+ <td></td>
1251
+ </tr>
1252
+ <tr>
1253
+ <td><em>minus (dash)</em></td>
1254
+ <td>-</td>
1255
+ <td></td>
1256
+ <td></td>
1257
+ </tr>
1258
+ <tr>
1259
+ <td><em>dot</em></td>
1260
+ <td>.</td>
1261
+ <td></td>
1262
+ <td></td>
1263
+ </tr>
1264
+ <tr>
1265
+ <td><em>forward slash</em></td>
1266
+ <td>/</td>
1267
+ <td></td>
1268
+ <td></td>
1269
+ </tr>
1270
+ <tr>
1271
+ <td><em>colon</em></td>
1272
+ <td>:</td>
1273
+ <td></td>
1274
+ <td></td>
1275
+ </tr>
1276
+ <tr>
1277
+ <td><em>semi-colon</em></td>
1278
+ <td>;</td>
1279
+ <td></td>
1280
+ <td></td>
1281
+ </tr>
1282
+ <tr>
1283
+ <td><em>equal sign</em></td>
1284
+ <td>=</td>
1285
+ <td></td>
1286
+ <td></td>
1287
+ </tr>
1288
+ <tr>
1289
+ <td><em>less than</em></td>
1290
+ <td>&lt;</td>
1291
+ <td></td>
1292
+ <td></td>
1293
+ </tr>
1294
+ <tr>
1295
+ <td><em>greater than</em></td>
1296
+ <td>&gt;</td>
1297
+ <td></td>
1298
+ <td></td>
1299
+ </tr>
1300
+ <tr>
1301
+ <td><em>vertical bar</em></td>
1302
+ <td>|</td>
1303
+ <td></td>
1304
+ <td></td>
1305
+ </tr>
1306
+ <tr>
1307
+ <td><em>underscore</em></td>
1308
+ <td>_</td>
1309
+ <td></td>
1310
+ <td>cannot be used as tag symbol; reserved for escaping in future versions</td>
1311
+ </tr>
1312
+ <tr>
1313
+ <td><em>back slash</em></td>
1314
+ <td>\</td>
1315
+ <td></td>
1316
+ <td>cannot be used as tag symbol; reserved for escaping in current version</td>
1317
+ </tr>
1318
+ <tr>
1319
+ <td><em>left parenthesis</em></td>
1320
+ <td>(</td>
1321
+ <td></td>
1322
+ <td>cannot be used as tag symbol; reserved for block delimiter</td>
1323
+ </tr>
1324
+ <tr>
1325
+ <td><em>right parenthesis</em></td>
1326
+ <td>)</td>
1327
+ <td></td>
1328
+ <td>cannot be used as tag symbol; reserved for block delimiter</td>
1329
+ </tr>
1330
+ <tr>
1331
+ <td><em>left bracket</em></td>
1332
+ <td>[</td>
1333
+ <td></td>
1334
+ <td>cannot be used as tag symbol; reserved for block delimiter</td>
1335
+ </tr>
1336
+ <tr>
1337
+ <td><em>right bracket</em></td>
1338
+ <td>]</td>
1339
+ <td></td>
1340
+ <td>cannot be used as tag symbol; reserved for block delimiter</td>
1341
+ </tr>
1342
+ <tr>
1343
+ <td><em>left brace</em></td>
1344
+ <td>{</td>
1345
+ <td></td>
1346
+ <td>cannot be used as tag symbol; reserved for block delimiter</td>
1347
+ </tr>
1348
+ <tr>
1349
+ <td><em>right brace</em></td>
1350
+ <td>}</td>
1351
+ <td></td>
1352
+ <td>cannot be used as tag symbol; reserved for block delimiter</td>
1353
+ </tr>
1354
+
1355
+ </table>
1356
+
1357
+
1358
+ </div>
1359
+
1360
+ </body>
1361
+ </html>