wlang 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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>