doc/specification/specification.html in wlang-0.9.2 vs doc/specification/specification.html in wlang-0.10.0

- old
+ new

@@ -1,1424 +1,1660 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <title>WLang (version 0.9.1)</title> + <title>WLang (version 0.10.0)</title> <style type="text/css"> body { - font-family: arial, verdana, sans-serif; - font-size: 14px; - width: 1024px; - margin: auto; - margin-top: 20px; - } - .clear { clear: both; } - p { margin: 0px; margin-bottom: 10px; text-align: justify; } - #title { float: left; margin: 10px 0px 20px 0px; } - #tabs { float: right; margin: 15px 0px; } - #tabs li { display: block; float: right; cursor: pointer; margin: 0px 0px 0px 5px; padding: 5px; border: 1px solid black; } - #tabs li.focus { background-color: #A00000; color: white; } - dl dt { margin-top: 10px; font-weight: bold; } - div.header { border-bottom: 1px solid black; margin: 10px 0px; } - h2 { float: left; margin: 0px; padding: 0px; } - h3 { margin-top: 20px; margin-bottom: 10px; text-decoration: underline;} - dl { padding-left: 35px; } - ul { padding: 0px 0px 0px 25px; } - ul li { margin: 5px;} - ul.links { float: right; margin: 0px; padding: 0px; } - ul.links li { cursor: pointer; margin: 0px 0px 0px 10px; padding: 0px; padding-top: 5px; display: block; float: right; } - ul.links li a, ul.links li a:visited { color: black; text-decoration: none; } - ul.links li a:hover { color: #A00000; } - h3 { margin-bottom: 5px; } - h4 { margin-bottom: 3px; float: left; margin-top: 0px; } - table { border-collapse: collapse; border: 1px solid black; } - table th { font-size: 12px; } - table th, table td { padding: 4px; } - table.glossary { margin-top: 20px; } - table.glossary th { background: green; color: white; border-bottom: 1px solid black; } - table.glossary th.term { width: 100px; } - table.glossary td { border-bottom: 1px dashed black; } - table.symbols { font-size: 12px; margin-top: 20px; width: 100%; } - table.symbols th { background: green; color: white; border-bottom: 1px solid black; } - table.symbols th.name { width: 150px; } - table.symbols th.symbol { width: 50px; } - table.symbols th.meaning { width: 250px; } - table.symbols td { border-bottom: 1px dashed black; } - table.ruleset { font-size: 12px; } - table.ruleset th { background: green; color: white; } - table.ruleset td { border-bottom: 1px dashed black; } - th.signature, td.signature { width: 300px; } - th.name, td.name { width: 120px; } - th.definition, td.definition { width: 580px; } - table.examples { float: right; font-size: 12px; } - table.examples th { background: #A00000; color: white; border-bottom: 1px solid black; } - table.examples th, table.examples td { padding: 4px; } - table.examples td { border-bottom: 1px dashed black; } - th.dialect, td.dialect { width: 150px; } - th.expression, td.expression { width: 350px; } - th.replacement, td.replacement { width: 350px; } - div.dialect {padding-left: 20px;} + font-family: arial, verdana, sans-serif; + font-size: 14px; + width: 1024px; + margin: auto; + margin-top: 20px; +} +.clear { clear: both; } +p { margin: 0px; margin-bottom: 10px; text-align: justify; } +#title { float: left; margin: 10px 0px 20px 0px; } +#tabs { float: right; margin: 15px 0px; } +#tabs li { display: block; float: right; cursor: pointer; margin: 0px 0px 0px 5px; padding: 5px; border: 1px solid black; } +#tabs li.focus { background-color: #A00000; color: white; } +dl dt { margin-top: 10px; font-weight: bold; } +div.header { border-bottom: 1px solid black; margin: 10px 0px; } +h2 { float: left; margin: 0px; padding: 0px; } +h3 { margin-top: 20px; margin-bottom: 10px; text-decoration: underline;} +dl { padding-left: 35px; } +ul { padding: 0px 0px 0px 25px; } +ul li { margin: 5px;} +ul.links { float: right; margin: 0px; padding: 0px; } +ul.links li { cursor: pointer; margin: 0px 0px 0px 10px; padding: 0px; padding-top: 5px; display: block; float: right; } +ul.links li a, ul.links li a:visited { color: black; text-decoration: none; } +ul.links li a:hover { color: #A00000; } +h3 { margin-bottom: 5px; } +h4 { margin-bottom: 3px; float: left; margin-top: 0px; } +table { border-collapse: collapse; border: 1px solid black; } +table th { font-size: 12px; } +table th, table td { padding: 4px; } +table.glossary { margin-top: 20px; } +table.glossary th { background: green; color: white; border-bottom: 1px solid black; } +table.glossary th.term { width: 100px; } +table.glossary td { border-bottom: 1px dashed black; } +table.symbols { font-size: 12px; margin-top: 20px; width: 100%; } +table.symbols th { background: green; color: white; border-bottom: 1px solid black; } +table.symbols th.name { width: 150px; } +table.symbols th.symbol { width: 50px; } +table.symbols th.meaning { width: 250px; } +table.symbols td { border-bottom: 1px dashed black; } +table.ruleset { font-size: 12px; } +table.ruleset th { background: green; color: white; } +table.ruleset td { border-bottom: 1px dashed black; } +th.signature, td.signature { width: 300px; } +th.name, td.name { width: 120px; } +th.definition, td.definition { width: 580px; } +table.examples { float: right; font-size: 12px; } +table.examples th { background: #A00000; color: white; border-bottom: 1px solid black; } +table.examples th, table.examples td { padding: 4px; } +table.examples td { border-bottom: 1px dashed black; } +th.dialect, td.dialect { width: 150px; } +th.expression, td.expression { width: 350px; } +th.replacement, td.replacement { width: 350px; } +div.dialect {padding-left: 20px;} </style> <script type="text/javascript" language="JavaScript"><!-- var current = 'about' - function show(who) { - document.getElementById(current).style.display = "none"; - document.getElementById(current + 'focus').className = "unfocus"; - document.getElementById(who).style.display = "block"; - document.getElementById(who + 'focus').className = "focus"; - current = who; - } +function show(who) { + document.getElementById(current).style.display = "none"; + document.getElementById(current + 'focus').className = "unfocus"; + document.getElementById(who).style.display = "block"; + document.getElementById(who + 'focus').className = "focus"; + current = who; +} //--></script> </head> <body onload="show('about')"> - <h1 id="title">WLang (version 0.9.1)</h1> + <h1 id="title">WLang (version 0.10.0)</h1> <ul id="tabs"> - <li id="symbolsfocus" onclick="show('symbols')">Tag symbols</li> - <li id="glossaryfocus" onclick="show('glossary')">Glossary</li> - <li id="hostingfocus" onclick="show('hosting')">Hosting language</li> - <li id="dialectsfocus" onclick="show('dialects')">Dialects</li> - <li id="rulesetsfocus" onclick="show('rulesets')">Rulesets</li> - <li id="overviewfocus" onclick="show('overview')">Overview</li> - <li id="aboutfocus" onclick="show('about')">About</li> - + + <li id="symbolsfocus" onclick="show('symbols')">Tag symbols</li> + + <li id="glossaryfocus" onclick="show('glossary')">Glossary</li> + + <li id="hostingfocus" onclick="show('hosting')">Hosting language</li> + + <li id="dialectsfocus" onclick="show('dialects')">Dialects</li> + + <li id="rulesetsfocus" onclick="show('rulesets')">Rulesets</li> + + <li id="overviewfocus" onclick="show('overview')">Overview</li> + + <li id="aboutfocus" onclick="show('about')">About</li> + </ul> <div class="clear"></div> - <div id="about" style="display: none;"> - <div class="header"> - <h2>About</h2> - - <div class="clear"></div> - </div> - <p> - WLang is a a reusable and extensible <em>code generator</em>, also known as - a <em>templating engine</em>. Motivation for it can be found at <a - href="http://www.revision-zero.org/wlang">www.revision-zero.org/wlang</a>. - The current file is the reference of the tool. - </p> - <h3>Topics</h3> - <dl> - <dt>Short overview</dt><dd>Probably the first section to read! Basic usage of <em>wlang</em> is - explained here and pointers are given to continue your learning. - </dd> - <dt>Rulesets</dt><dd>Standard rulesets are specified. As most of them are included in standard - dialects, looking at standard rulesets is the quickest way to learn all of - them at once. + <div id="about" style="display: none;"> + <div class="header"> + <h2>About</h2> + + <div class="clear"></div> + </div> + + <p> +WLang is a a reusable and extensible <em>code generator</em>, also known as +a <em>templating engine</em>. Motivation for it can be found at <a +href="http://www.revision-zero.org/wlang">www.revision-zero.org/wlang</a>. +The current file is the reference of the tool. +</p> +<h3>Topics</h3> +<dl> +<dt>Short overview</dt><dd>Probably the first section to read! Basic usage of <em>wlang</em> is +explained here and pointers are given to continue your learning. + +</dd> +<dt>Rulesets</dt><dd>Standard rulesets are specified. As most of them are included in standard +dialects, looking at standard rulesets is the quickest way to learn all of +them at once. + +</dd> +<dt>Dialects</dt><dd>Standard dialects are described. This page also provides useful cheatsheets +of available tags in standard dialects. + +</dd> +<dt>Hosting language</dt><dd>Somewhat more tricky but powerful. The notion of hosting language is +explained more deeply. Implementing you own hosting language abstraction +(advanced topic) sometimes leads to cleaner and cross-implementation +templates. + +</dd> +<dt>Glossary</dt><dd><em>wlang</em> comes with a terminology, knowing it will make your reading +easier. + +</dd> +<dt>Symbols</dt><dd>If you plan to create your own tags, it can be useful to know what is +allowed and what is not. This pages covers this topic. + +</dd> +</dl> +<h3>About this document</h3> +<p> +This document is a simple .html file without external dependencies +(embedded CSS and javascript). As it contains several cheatsheets, you can +simply save it on your harddisk without having to be online to browse the +documentation. It has been generated using <em>wlang</em> itself using the +following command: +</p> +<pre> + wlang specification.wtpl +</pre> +<p> +The file &#8216;specification.wtpl&#8217; is almost empty and other files +next to it are all kept simple and written in the most appropriate format +for the task at hand (YAML for structured parts, RDoc for text sections, +sometimes YAML embedding short sentences writted in RDoc style, etc.). One +way to learn <em>wlang</em> quickly is to download the source distribution +and to look how this is made possible ;-) +</p> +<p> +This reference document is under a <a +href="http://creativecommons.org/licenses/by/2.0/be/">Creative Commons +Licence 2.0</a> contract. You can use it, redistribute it and modify it +providing that you keep a reference to the original licensor (namely, the +&#8216;University of Louvain&#8217; or &#8216;Bernard and Louis +Lambeau&#8217;). +</p> +<p> +Enjoy <em>wlang</em> ! +</p> +<h3>Distribution</h3> +<ul> +<li>The reference implementation of <em>wlang</em>, implemented in Ruby, is +freely available as a &#8216;wlang&#8217; gem (under MIT licence). <br/> +Use <tt>'gem install wlang'</tt> to install it. For repository and bug +tracker visit us on <a href="http://github.com/blambeau/wlang">github</a> + +</li> +<li>We don&#8217;t have another implementation up to now. If you plan to start +one in another language, let us know! + +</li> +</ul> +<h3>Authors</h3> +<p> +<em>wlang</em> has been initially designed by Bernard and Louis Lambeau +during the implementation of w@w, yet another web framework (proof of +concept). They are also maintainers of the reference implementation. +</p> +<h3>Credits</h3> +<p> +This work is supported by the <a +href="http://www.uclouvain.be/en-ingi.html">department of computer +science</a> of the <a +href="http://www.uclouvain.be/en-index.html">University of Louvain</a> +(EPL/INGI, Universite Catholique de Louvain, UCL, Louvain-la-Neuve, +Belgium). +</p> +<p> +This work was also partially supported by the Regional Government of +Wallonia (ReQuest project, RW Conv. 315592 and GISELE project, RW Conv. +616425) and the MoVES project (PAI program of the Belgian government). +</p> + + + </div> - </dd> - <dt>Dialects</dt><dd>Standard dialects are described. This page also provides useful cheatsheets - of available tags in standard dialects. + <div id="overview" style="display: none;"> + <div class="header"> + <h2>Overview</h2> + + <div class="clear"></div> + </div> + + <h3>What is <em>wlang</em> designed for?</h3> +<p> +<em>wlang</em> helps you <b>generating code</b>, in a broad sense. It was +originally the templating engine of w@w, a proof-of-concept web framework. +While more powerful than the original version, the <b>templating engine</b> +ability of <em>wlang</em> has been kept unchanged. For this reason, +generating html code with <em>wlang</em> is probably a bit more mature than +generating ruby, java or sql code, to take some examples of what +<em>wlang</em> can do. It is the author opinion that <em>wlang</em> will +also become mature quiclky for these tasks because of its foundations: +<b>its engine is generic</b> (in a sense, <em>wlang</em> does not really +care about what it generates) but is <b>fully and easily configurable</b>. +Generation of html files is mature because <em>wlang</em> has been used a +lot for such a job; thus its authors have acquired experience of what is +useful when generating simple as well as complex html files. This +experience led us to a mature configuration of the <em>wlang</em> engine +for generating html files, as the following paragraph illustrates (for +people interested in generating code in other languages than html, +don&#8217;t stop your reading here: the paragraph immediately following +contains information for you!) +</p> +<p> +Consider this file for example, which is completely self-contained. It +consists of several parts, some of them being structured - the tables for +example - while others are not. It also embeds a complete CSS stylesheet +and some javascript functions. We have not written this file manually, nor +do we maintain it this way. In fact, this reference document is entirely +generated by <em>wlang</em> itself from separated parts written mainly in +yaml and rdoc files. Also, the cheatsheets given later contains a lot of +examples. To ensure that all of them are correct, we simply ask +<em>wlang</em> to compute them during generation (technically, we say that +<b><em>wlang</em> naturally allows metaprogramming</b>). Lastly, if +<em>wlang</em> can be used inside a web framework, it can also be used as a +standalone (commandline) tool for generating single files like this one or +multiple files, even if all of them are of different nature. +</p> +<p> +<b>Maybe you are looking for a code generator for another language than +html</b> (which one does not really care, unless really specific; we call +it the <em>target language</em>)? Don&#8217;t be affraid by our previous +words about <em>wlang</em>&#8217;s maturity: even in such a case, +<em>wlang</em> is your friend. Start with an existing dialect (see later +about dialects), which will provide basic utilities for starting and try to +identify common patterns when you use them. Then simply create special +shortcuts that are more friendly to use than combining several existing +utils &#8230; you are on the way of creating your own mature and reusable +dialect for that target language. In this case, don&#8217;t forget to share +it &#8230; +</p> +<h3>Template and instantiation</h3> +<p> +The <em>wlang</em> grammar used to write a <em>template</em> is generic and +simple: every character stands for itself (meaning that it is reproduced +exactly when the template is instantiated) except <em>tags</em> (and their +associated <em>blocks</em>, enclosed between &#8217;{&#8217; and +&#8217;}&#8217;) that are replaced by what is called the <em>replacement +value</em>. Consider the following example: +</p> +<pre> + &lt;html&gt; + &lt;head&gt; + &lt;title&gt;${title}&lt;/title&gt; + &lt;/head&gt; + &lt;body&gt; + &lt;h1&gt;Hello *{authors as who}{${who}}{, } !&lt;/h1&gt; + &lt;/body&gt; + &lt;/html&gt; +</pre> +<p> +Assume that we have some instantitation data through the following hash (or +something similar, like a YAML file): +</p> +<pre> + {&quot;title&quot; =&gt; &quot;Short overview of wlang&quot;, &quot;authors&quot; =&gt; [&quot;blambeau&quot;, &quot;llambeau&quot;, &quot;ancailliau&quot;]} +</pre> +<p> +When instantiated this template will produce exactly the same html file +except for special tags <tt>${title}</tt> and <tt>*{whos as who}{${who}}{, +}</tt> that will be replaced by <tt>'Short overview of wlang'</tt> and +<tt>'blambeau, llambeau, ancailliau'</tt>, respectively. A lot of tags is +available, each of them being designed for a specific task: inserting the +value of a variable, iterating over collections, including another file, +dynamically loading instantiation data, etc. All of these things are +commonly proposed by templating engines and <em>wlang</em> is one of them +&#8230; However, <em>wlang</em> is a bit different as will quickly appear. +</p> +<p> +Indeed (and maybe surprisingly) <em>wlang</em> can also behave really +differently on the same template: replacing <tt>${title}</tt> but not +<tt>*{...}</tt> or the converse, or not replacing anything, or replacing +both tags but not <tt>${who}</tt>, etc. All of this is possible in +<em>wlang</em>. The magic relies under the notion of <em>dialect</em>, +which you need to understand. +</p> +<h3>Dialects and Rulesets</h3> +<p> +The notion of dialect drives the recognition of tags as well as their +replacement during instantiation. Dialects are what makes <em>wlang</em> +really powerful: if instantiated as being written in the +<tt>wlang/xhtml</tt> dialect, the template above will give the result +mentionned previously. In contrast, if written in <tt>wlang/dummy</tt> the +template will be reproduced whitout any change (no tag replacement at all). +This behavior is not hardcoded; it results from the definition of wlang +(standard) dialects: <tt>wlang/xhtml</tt> define special meanings for +<tt>${...}</tt> and <tt>*{...}{...}{...}</tt> while <tt>wlang/dummy</tt> +does not. +</p> +<p> +The replacement of a given <em>tag</em> during instantiation is computed by +what we call the <em>rule</em> attached to the tag (keeping rules and tags +as different concepts leads to another feature of <em>wlang</em>: you can +reuse rule implementations and attach them to other tags than those +proposed). A dialect comes with a set of (tag, rule) pairs that determine +its replacement behavior. Such a set is called a <em>ruleset</em>; for +easier reuse, standard rulesets are already implemented. A dialect is a +packaging of standard rulesets (and maybe implements specific tag/rule +pairs) designed for generating code in a given target language. +</p> +<p> +A complete <em>wlang</em> implementation already provides standard dialects +for common tasks: creating html pages, building SQL queries, generating +code in Ruby or in another language, etc. Each dialect comes with special +tags that are useful for the task at hand (a tag for back-quoting values is +useful for creating SQL queries but does not really makes sense for +generating an html page where, in contrast, a tag for encoding entities is +probably welcome). Such an implementation also allows you to extend +standard dialects and to create your own dialect by implementing specific +tags and rules or by reusing existing ones. Lastlty, the dialect in used +during instantiation can be changed dynamically (<em>explicitly</em>, by +using the <tt>%{dialect/qualified/name}{...}</tt> standard tag and +<em>implicitly</em>, when rules parse their blocks). +</p> +<p> +To learn more about standard dialects and reusable rules, read the +&#8216;Dialects&#8217; and &#8216;Rulesets&#8217; pages of this +documentation. +</p> +<h3>Grammar</h3> +<p> +The (abstract) <em>wlang</em> grammar rules what forms a valid template. At +first glance, this grammar does not depend on the dialect that is used for +instantiation. It is simple, but comes with some constraints that are +explained below: +</p> +<ul> +<li>block delimiters are &#8217;{&#8217; and &#8217;}&#8217; by default; +<em>wlang</em> can be configured to use &#8217;(&#8217; and &#8217;)&#8217; +or &#8217;[&#8217; and &#8217;]&#8217; instead. However, block +<b>delimiters are template-specific</b>: only one kind of delimiters can be +used inside the same template. + +</li> +<li>block delimiters <b>must always be paired</b>, even when not used for +delimiting blocks. If an opening or closing delimiter is not paired, it +must be escaped with a backslash, which will not be reproduced. If you want +a backslash to appear before a block delimiter in the instantiation result, +use a double backslash. + +</li> +<li>if a given tag has a special meaning in the current dialect and you +don&#8217;t want it to be replaced by <em>wlang</em> you can escape it with +a backslash as well (the backslash will not be reproduced). + +</li> +<li>some tags (precisely: some rules associated with tags) require multiple +blocks (like <tt>*{...}{...}{...}</tt> in <tt>wlang/xhtml</tt> for example, +with the third block bein optional). In such a case no character is allowed +between the end of a block &#8217;}&#8217; and the start of the next one +&#8217;{&#8217;, not even spaces or a carriage return. In other words, +multiple blocks (that must be interpreted as such) must touch each others +using &#8217;}{&#8217; precisely, as ilustrated below. If a non-optional +block is missing a parse error is raised by the <em>wlang</em> +implementation. + +<pre> + *{authors as who}{${who}}{, } -&gt; blambeau, llambeau, ancailliau + *{authors as who}{${who}} {, } -&gt; blambeaullambeauancailliau {, } + *{authors as who} {${who}}{, } -&gt; parse error 1:18, missing block 2 in *{...}{...} +</pre> +</li> +</ul> +<p> +In addition to these constraints, dialects and the hosting language may +impose restrictions on what can be put inside specific blocks of tags/rules +(for example, &#8216;authors as who&#8217; is valid as first tag of +<tt>*{...}{...}</tt> but not every string is, of course). These constraints +are not specific to the wlang grammar <em>per se</em> and are explained in +the &#8216;Rulesets&#8217;, &#8216;Dialects&#8217; and &#8216;Hosting +language&#8217; pages of this document. +</p> + + + </div> - </dd> - <dt>Hosting language</dt><dd>Somewhat more tricky but powerful. The notion of hosting language is - explained more deeply. Implementing you own hosting language abstraction - (advanced topic) sometimes leads to cleaner and cross-implementation - templates. + <div id="rulesets" style="display: none;"> + <div class="header"> + <h2>Rulesets</h2> + + <ul class="links"> + <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> + </ul> + + <div class="clear"></div> + </div> + + <p> +Standard ruleset are designed to be reusable: including them in your own +dialect is made easy by a typical <em>wlang</em> implementation. Some of +them are also included by standard dialects. +</p> +<h3>How to read this cheatsheet?</h3> +<p> +First of all, focus on the examples; they are written to let you learn +<em>wlang</em> quickly and deeply. Some of them are a bit difficult to +understand but they are representative of <em>wlang</em> powerfulness +(don&#8217;t be affraid: in practice, some constructions are never used). +Don&#8217;t forget that the <tt>wlang/dummy</tt> dialect does not recognize +any tag. We also assume instantiation data to be the following hash: +</p> +<pre> + {&quot;name&quot; =&gt; &quot;O'Neil&quot;, + &quot;author&quot; =&gt; &quot;blambeau&quot; + &quot;authors&quot; =&gt; [&quot;blambeau&quot;, &quot;llambeau&quot;, &quot;ancailliau&quot;]} +</pre> +<p> +Moreover, the dialect column in the examples is important; <em>wlang</em> +behaves differently in different dialects. When the dialect does not care, +we use <tt>wlang/*</tt> which means &#8216;in any dialect that includes +this ruleset&#8217;. +</p> +<p> +Next, certain rule definitions are given as shortcuts for longer +expressions, involving other tags. This is somewhat representative of +<em>wlang</em> usage, even if these rules are not actually implemented this +way (mainly for efficiency concerns). Once again, understanding shortcuts +will help you mastering wlang! In definitions (textual as well as +shortcuts), we use #1, #2, and #3 to refer to the content of the blocks. +Those identifiers are not real <em>wlang</em> constructs, but are only used +here for easier explanations (for those who know this kind of vocabulary: +they are part of the meta-language, not the language <em>per se</em>). +</p> +<p> +Lastly, dialect names that appear in rule signatures are to be interpreted +as an implicit dialect modulation: the corresponding block (often the first +one) is not instantiated in the current dialect but in the one specified by +the signature. In contrast, when we use &#8217;&#8230;&#8217; it means that +the corresponding block is simply instantiated in the current dialect. +Implicit dialect modulation is in fact natural: if a block expects an uri +for example, the easiest way is to give it exactly: +<tt>&lt;&lt;{a/file/to/include.txt}</tt>. But you can even compute it using +<em>wlang</em>, as illustrated by the example below. In complex situations +you will probably be happy to use a dialect that helps you doing so (think +at all blocks that expect an expression in the hosting language, for +example)! +</p> +<pre> + # Concatenates all files of the 'files' array variable + *{files as f}{&lt;&lt;{+{f}}} +</pre> + + + + <h3 id="Basic">Basic</h3> + <p> +The Basic ruleset is commonly installed on any dialect and provides access +to <em>wlang</em> foundations inside your template: requesting the hosting +language to execute some expression, changing the current dialect and +encoding text. +</p> + + <table class="ruleset"> + <tr> + <th class="signature">signature</th> + <th class="name">name</th> + <th class="definition">definition</th> + </tr> - </dd> - <dt>Glossary</dt><dd><em>wlang</em> comes with a terminology, knowing it will make your reading - easier. - - </dd> - <dt>Symbols</dt><dd>If you plan to create your own tags, it can be useful to know what is - allowed and what is not. This pages covers this topic. - - </dd> - </dl> - <h3>About this document</h3> - <p> - This document is a simple .html file without external dependencies - (embedded CSS and javascript). As it contains several cheatsheets, you can - simply save it on your harddisk without having to be online to browse the - documentation. It has been generated using <em>wlang</em> itself using the - following command: - </p> - <pre> - wlang specification.wtpl - </pre> - <p> - The file &#8216;specification.wtpl&#8217; is almost empty and other files - next to it are all kept simple and written in the most appropriate format - for the task at hand (YAML for structured parts, RDoc for text sections, - sometimes YAML embedding short sentences writted in RDoc style, etc.). One - way to learn <em>wlang</em> quickly is to download the source distribution - and to look how this is made possible ;-) - </p> - <p> - This reference document is under a <a - href="http://creativecommons.org/licenses/by/2.0/be/">Creative Commons - Licence 2.0</a> contract. You can use it, redistribute it and modify it - providing that you keep a reference to the original licensor (namely, the - &#8216;University of Louvain&#8217; or &#8216;Bernard and Louis - Lambeau&#8217;). - </p> - <p> - Enjoy <em>wlang</em> ! - </p> - <h3>Distribution</h3> - <ul> - <li>The reference implementation of <em>wlang</em>, implemented in Ruby, is - freely available as a &#8216;wlang&#8217; gem (under MIT licence). <br/> - Use <tt>'gem install wlang'</tt> to install it. For repository and bug - tracker visit us on <a href="http://github.com/blambeau/wlang">github</a> - - </li> - <li>We don&#8217;t have another implementation up to now. If you plan to start - one in another language, let us know! - - </li> - </ul> - <h3>Authors</h3> - <p> - <em>wlang</em> has been initially designed by Bernard and Louis Lambeau - during the implementation of w@w, yet another web framework (proof of - concept). They are also maintainers of the reference implementation. - </p> - <h3>Credits</h3> - <p> - This work is supported by the <a - href="http://www.uclouvain.be/en-ingi.html">department of computer - science</a> of the <a - href="http://www.uclouvain.be/en-index.html">University of Louvain</a> - (EPL/INGI, Universite Catholique de Louvain, UCL, Louvain-la-Neuve, - Belgium). - </p> - <p> - This work was also partially supported by the Regional Government of - Wallonia (ReQuest project, RW Conv. 315592 and GISELE project, RW Conv. - 616425) and the MoVES project (PAI program of the Belgian government). - </p> - - - </div> - <div id="overview" style="display: none;"> - <div class="header"> - <h2>Overview</h2> - - <div class="clear"></div> - </div> - <h3>What is <em>wlang</em> designed for?</h3> - <p> - <em>wlang</em> helps you <b>generating code</b>, in a broad sense. It was - originally the templating engine of w@w, a proof-of-concept web framework. - While more powerful than the original version, the <b>templating engine</b> - ability of <em>wlang</em> has been kept unchanged. For this reason, - generating html code with <em>wlang</em> is probably a bit more mature than - generating ruby, java or sql code, to take some examples of what - <em>wlang</em> can do. It is the author opinion that <em>wlang</em> will - also become mature quiclky for these tasks because of its foundations: - <b>its engine is generic</b> (in a sense, <em>wlang</em> does not really - care about what it generates) but is <b>fully and easily configurable</b>. - Generation of html files is mature because <em>wlang</em> has been used a - lot for such a job; thus its authors have acquired experience of what is - useful when generating simple as well as complex html files. This - experience led us to a mature configuration of the <em>wlang</em> engine - for generating html files, as the following paragraph illustrates (for - people interested in generating code in other languages than html, - don&#8217;t stop your reading here: the paragraph immediately following - contains information for you!) - </p> - <p> - Consider this file for example, which is completely self-contained. It - consists of several parts, some of them being structured - the tables for - example - while others are not. It also embeds a complete CSS stylesheet - and some javascript functions. We have not written this file manually, nor - do we maintain it this way. In fact, this reference document is entirely - generated by <em>wlang</em> itself from separated parts written mainly in - yaml and rdoc files. Also, the cheatsheets given later contains a lot of - examples. To ensure that all of them are correct, we simply ask - <em>wlang</em> to compute them during generation (technically, we say that - <b><em>wlang</em> naturally allows metaprogramming</b>). Lastly, if - <em>wlang</em> can be used inside a web framework, it can also be used as a - standalone (commandline) tool for generating single files like this one or - multiple files, even if all of them are of different nature. - </p> - <p> - <b>Maybe you are looking for a code generator for another language than - html</b> (which one does not really care, unless really specific; we call - it the <em>target language</em>)? Don&#8217;t be affraid by our previous - words about <em>wlang</em>&#8217;s maturity: even in such a case, - <em>wlang</em> is your friend. Start with an existing dialect (see later - about dialects), which will provide basic utilities for starting and try to - identify common patterns when you use them. Then simply create special - shortcuts that are more friendly to use than combining several existing - utils &#8230; you are on the way of creating your own mature and reusable - dialect for that target language. In this case, don&#8217;t forget to share - it &#8230; - </p> - <h3>Template and instantiation</h3> - <p> - The <em>wlang</em> grammar used to write a <em>template</em> is generic and - simple: every character stands for itself (meaning that it is reproduced - exactly when the template is instantiated) except <em>tags</em> (and their - associated <em>blocks</em>, enclosed between &#8217;{&#8217; and - &#8217;}&#8217;) that are replaced by what is called the <em>replacement - value</em>. Consider the following example: - </p> - <pre> - &lt;html&gt; - &lt;head&gt; - &lt;title&gt;${title}&lt;/title&gt; - &lt;/head&gt; - &lt;body&gt; - &lt;h1&gt;Hello *{authors as who}{${who}}{, } !&lt;/h1&gt; - &lt;/body&gt; - &lt;/html&gt; - </pre> - <p> - Assume that we have some instantitation data through the following hash (or - something similar, like a YAML file): - </p> - <pre> - {&quot;title&quot; =&gt; &quot;Short overview of wlang&quot;, &quot;authors&quot; =&gt; [&quot;blambeau&quot;, &quot;llambeau&quot;, &quot;ancailliau&quot;]} - </pre> - <p> - When instantiated this template will produce exactly the same html file - except for special tags <tt>${title}</tt> and <tt>*{whos as who}{${who}}{, - }</tt> that will be replaced by <tt>'Short overview of wlang'</tt> and - <tt>'blambeau, llambeau, ancailliau'</tt>, respectively. A lot of tags is - available, each of them being designed for a specific task: inserting the - value of a variable, iterating over collections, including another file, - dynamically loading instantiation data, etc. All of these things are - commonly proposed by templating engines and <em>wlang</em> is one of them - &#8230; However, <em>wlang</em> is a bit different as will quickly appear. - </p> - <p> - Indeed (and maybe surprisingly) <em>wlang</em> can also behave really - differently on the same template: replacing <tt>${title}</tt> but not - <tt>*{...}</tt> or the converse, or not replacing anything, or replacing - both tags but not <tt>${who}</tt>, etc. All of this is possible in - <em>wlang</em>. The magic relies under the notion of <em>dialect</em>, - which you need to understand. - </p> - <h3>Dialects and Rulesets</h3> - <p> - The notion of dialect drives the recognition of tags as well as their - replacement during instantiation. Dialects are what makes <em>wlang</em> - really powerful: if instantiated as being written in the - <tt>wlang/xhtml</tt> dialect, the template above will give the result - mentionned previously. In contrast, if written in <tt>wlang/dummy</tt> the - template will be reproduced whitout any change (no tag replacement at all). - This behavior is not hardcoded; it results from the definition of wlang - (standard) dialects: <tt>wlang/xhtml</tt> define special meanings for - <tt>${...}</tt> and <tt>*{...}{...}{...}</tt> while <tt>wlang/dummy</tt> - does not. - </p> - <p> - The replacement of a given <em>tag</em> during instantiation is computed by - what we call the <em>rule</em> attached to the tag (keeping rules and tags - as different concepts leads to another feature of <em>wlang</em>: you can - reuse rule implementations and attach them to other tags than those - proposed). A dialect comes with a set of (tag, rule) pairs that determine - its replacement behavior. Such a set is called a <em>ruleset</em>; for - easier reuse, standard rulesets are already implemented. A dialect is a - packaging of standard rulesets (and maybe implements specific tag/rule - pairs) designed for generating code in a given target language. - </p> - <p> - A complete <em>wlang</em> implementation already provides standard dialects - for common tasks: creating html pages, building SQL queries, generating - code in Ruby or in another language, etc. Each dialect comes with special - tags that are useful for the task at hand (a tag for back-quoting values is - useful for creating SQL queries but does not really makes sense for - generating an html page where, in contrast, a tag for encoding entities is - probably welcome). Such an implementation also allows you to extend - standard dialects and to create your own dialect by implementing specific - tags and rules or by reusing existing ones. Lastlty, the dialect in used - during instantiation can be changed dynamically (<em>explicitly</em>, by - using the <tt>%{dialect/qualified/name}{...}</tt> standard tag and - <em>implicitly</em>, when rules parse their blocks). - </p> - <p> - To learn more about standard dialects and reusable rules, read the - &#8216;Dialects&#8217; and &#8216;Rulesets&#8217; pages of this - documentation. - </p> - <h3>Grammar</h3> - <p> - The (abstract) <em>wlang</em> grammar rules what forms a valid template. At - first glance, this grammar does not depend on the dialect that is used for - instantiation. It is simple, but comes with some constraints that are - explained below: - </p> - <ul> - <li>block delimiters are &#8217;{&#8217; and &#8217;}&#8217; by default; - <em>wlang</em> can be configured to use &#8217;(&#8217; and &#8217;)&#8217; - or &#8217;[&#8217; and &#8217;]&#8217; instead. However, block - <b>delimiters are template-specific</b>: only one kind of delimiters can be - used inside the same template. - - </li> - <li>block delimiters <b>must always be paired</b>, even when not used for - delimiting blocks. If an opening or closing delimiter is not paired, it - must be escaped with a backslash, which will not be reproduced. If you want - a backslash to appear before a block delimiter in the instantiation result, - use a double backslash. - - </li> - <li>if a given tag has a special meaning in the current dialect and you - don&#8217;t want it to be replaced by <em>wlang</em> you can escape it with - a backslash as well (the backslash will not be reproduced). - - </li> - <li>some tags (precisely: some rules associated with tags) require multiple - blocks (like <tt>*{...}{...}{...}</tt> in <tt>wlang/xhtml</tt> for example, - with the third block bein optional). In such a case no character is allowed - between the end of a block &#8217;}&#8217; and the start of the next one - &#8217;{&#8217;, not even spaces or a carriage return. In other words, - multiple blocks (that must be interpreted as such) must touch each others - using &#8217;}{&#8217; precisely, as ilustrated below. If a non-optional - block is missing a parse error is raised by the <em>wlang</em> - implementation. - - <pre> - *{authors as who}{${who}}{, } -&gt; blambeau, llambeau, ancailliau - *{authors as who}{${who}} {, } -&gt; blambeaullambeauancailliau {, } - *{authors as who} {${who}}{, } -&gt; parse error 1:18, missing block 2 in *{...}{...} - </pre> - </li> - </ul> - <p> - In addition to these constraints, dialects and the hosting language may - impose restrictions on what can be put inside specific blocks of tags/rules - (for example, &#8216;authors as who&#8217; is valid as first tag of - <tt>*{...}{...}</tt> but not every string is, of course). These constraints - are not specific to the wlang grammar <em>per se</em> and are explained in - the &#8216;Rulesets&#8217;, &#8216;Dialects&#8217; and &#8216;Hosting - language&#8217; pages of this document. - </p> - - - </div> - <div id="rulesets" style="display: none;"> - <div class="header"> - <h2>Rulesets</h2> - <ul class="links"> - <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> - </ul> - - <div class="clear"></div> - </div> - <p> - Standard ruleset are designed to be reusable: including them in your own - dialect is made easy by a typical <em>wlang</em> implementation. Some of - them are also included by standard dialects. - </p> - <h3>How to read this cheatsheet?</h3> - <p> - First of all, focus on the examples; they are written to let you learn - <em>wlang</em> quickly and deeply. Some of them are a bit difficult to - understand but they are representative of <em>wlang</em> powerfulness - (don&#8217;t be affraid: in practice, some constructions are never used). - Don&#8217;t forget that the <tt>wlang/dummy</tt> dialect does not recognize - any tag. We also assume instantiation data to be the following hash: - </p> - <pre> - {&quot;name&quot; =&gt; &quot;O'Neil&quot;, - &quot;author&quot; =&gt; &quot;blambeau&quot; - &quot;authors&quot; =&gt; [&quot;blambeau&quot;, &quot;llambeau&quot;, &quot;ancailliau&quot;]} - </pre> - <p> - Moreover, the dialect column in the examples is important; <em>wlang</em> - behaves differently in different dialects. When the dialect does not care, - we use <tt>wlang/*</tt> which means &#8216;in any dialect that includes - this ruleset&#8217;. - </p> - <p> - Next, certain rule definitions are given as shortcuts for longer - expressions, involving other tags. This is somewhat representative of - <em>wlang</em> usage, even if these rules are not actually implemented this - way (mainly for efficiency concerns). Once again, understanding shortcuts - will help you mastering wlang! In definitions (textual as well as - shortcuts), we use #1, #2, and #3 to refer to the content of the blocks. - Those identifiers are not real <em>wlang</em> constructs, but are only used - here for easier explanations (for those who know this kind of vocabulary: - they are part of the meta-language, not the language <em>per se</em>). - </p> - <p> - Lastly, dialect names that appear in rule signatures are to be interpreted - as an implicit dialect modulation: the corresponding block (often the first - one) is not instantiated in the current dialect but in the one specified by - the signature. In contrast, when we use &#8217;&#8230;&#8217; it means that - the corresponding block is simply instantiated in the current dialect. - Implicit dialect modulation is in fact natural: if a block expects an uri - for example, the easiest way is to give it exactly: - <tt>&lt;&lt;{a/file/to/include.txt}</tt>. But you can even compute it using - <em>wlang</em>, as illustrated by the example below. In complex situations - you will probably be happy to use a dialect that helps you doing so (think - at all blocks that expect an expression in the hosting language, for - example)! - </p> - <pre> - # Concatenates all files of the 'files' array variable - *{files as f}{&lt;&lt;{+{f}}} - </pre> - - - <h3 id="Basic">Basic</h3> - <p> - The Basic ruleset is commonly installed on any dialect and provides access - to <em>wlang</em> foundations inside your template: requesting the hosting - language to execute some expression, changing the current dialect and - encoding text. - </p> - - <table class="ruleset"> <tr> - <th class="signature">signature</th> - <th class="name">name</th> - <th class="definition">definition</th> - </tr> - <tr> <td class="signature"><tt>!{wlang/hosted}</tt></td> <td class="name">execution</td> <td class="definition">Instantiates #1, looking for an expression of the hosting language. - Evaluates it, looking for any object. Converts it to a string (using to_s - for example if Ruby is the hosting language) and returns the result as - replacement value.</td> +Evaluates it, looking for any object. Converts it to a string (using to_s +for example if Ruby is the hosting language) and returns the result as +replacement value.</td> </tr> + <tr> <td class="signature"><tt>%{wlang/active-string}{...}</tt></td> <td class="name">modulation</td> <td class="definition">Instantiates #1, looking for a dialect qualified name. Instantiates #2 - according to the rules defined by that dialect and returns the #2&#8217;s - instantiation as replacement value.</td> +according to the rules defined by that dialect and returns the #2&#8217;s +instantiation as replacement value.</td> </tr> + <tr> <td class="signature"><tt>^{wlang/active-string}{...}</tt></td> <td class="name">encoding</td> <td class="definition">Instantiates #1, looking for an encoder qualified name. Instantiates #2 in - the current dialect. Encode #2&#8217;s instantiation using encoder found in - (#1) and returns encoding as replacement value.</td> +the current dialect. Encode #2&#8217;s instantiation using encoder found in +(#1) and returns encoding as replacement value.</td> </tr> + <tr> <td class="signature"><tt>%!{wlang/active-string &lt;using&gt;? &lt;with&gt;?}{...}</tt></td> <td class="name">recursive-application</td> <td class="definition">Instantiates #1, looking for a dialect qualified name. Instantiates #2 in - the current dialect. Instantiates #2&#8217;s instantiation in the dialect - found in #1, using context installed by &#8216;using &#8230;&#8217; and - &#8216;with &#8230;&#8217;. Returns this instantiation as replacement value - (this really advanced rule allows metaprogramming).</td> +the current dialect. Instantiates #2&#8217;s instantiation in the dialect +found in #1, using context installed by &#8216;using &#8230;&#8217; and +&#8216;with &#8230;&#8217;. Returns this instantiation as replacement value +(this really advanced rule allows metaprogramming).</td> </tr> + <tr> <td class="signature"><tt>${wlang/hosted}</tt></td> <td class="name">injection</td> <td class="definition">Same semantics as execution (intended to be overrided).</td> </tr> + <tr> <td class="signature"><tt>+{wlang/hosted}</tt></td> <td class="name">inclusion</td> <td class="definition">Same semantics as execution (intended to be overrided).</td> </tr> - </table> - + </table> + + <br/> <h4>Examples:</h4> <table class="examples"> <tr> <th>dialect</th> <th>wlang expression</th> <th>replacement value</th> </tr> - <tr> - <td class="dialect"> - <tt>wlang/active-string</tt> - </td> - <td class="expression"> - <tt>Hello !{name}</tt> - </td> - <td class="replacement"> - <tt>Hello O'Neil</tt> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/active-string</tt> - </td> - <td class="expression"> - <tt>Hello %{wlang/dummy}{!{name}}</tt> - </td> - <td class="replacement"> - <tt>Hello !{name}</tt> + <tr> + <td class="dialect"> + <tt>wlang/active-string</tt> + </td> + <td class="expression"> + <tt>Hello !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello O'Neil</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/dummy</tt> - </td> - <td class="expression"> - <tt>Hello %{wlang/dummy}{!{name}}</tt> - </td> - <td class="replacement"> - <tt>Hello %{wlang/dummy}{!{name}}</tt> + <tr> + <td class="dialect"> + <tt>wlang/active-string</tt> + </td> + <td class="expression"> + <tt>Hello %{wlang/dummy}{!{name}}</tt> + </td> + <td class="replacement"> + + <tt>Hello !{name}</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/active-string</tt> - </td> - <td class="expression"> - <tt>Hello ^{plain-text/upcase}{${name}}</tt> - </td> - <td class="replacement"> - <tt>Hello O'NEIL</tt> + <tr> + <td class="dialect"> + <tt>wlang/dummy</tt> + </td> + <td class="expression"> + <tt>Hello %{wlang/dummy}{!{name}}</tt> + </td> + <td class="replacement"> + + <tt>Hello %{wlang/dummy}{!{name}}</tt> + + </td> + </tr> - </td> - </tr> - + <tr> + <td class="dialect"> + <tt>wlang/active-string</tt> + </td> + <td class="expression"> + <tt>Hello ^{plain-text/upcase}{${name}}</tt> + </td> + <td class="replacement"> + + <tt>Hello O'NEIL</tt> + + </td> + </tr> + + <tr> + <td class="dialect"> + <tt>wlang/ruby</tt> + </td> + <td class="expression"> + <tt>puts +{name}</tt> + </td> + <td class="replacement"> + + <tt>puts "O'Neil"</tt> + + </td> + </tr> + + <tr> + <td class="dialect"> + <tt>wlang/ruby</tt> + </td> + <td class="expression"> + <tt>puts +{authors}</tt> + </td> + <td class="replacement"> + + <tt>puts ["blambeau", "llambeau", "ancailliau"]</tt> + + </td> + </tr> + </table> <div style="clear: both;"></div> - <h3 id="Encoding">Encoding</h3> - <p> - Almost all languages require escaping/encoding in specific situations: - quoted string literals always come with an escaping mechanism - (unfortunately different from one language to another), html requires - entities-encoding, etc. The Encoding ruleset proposes shortcut tags for - encoding. Note that these shortcuts are written in such a way that they - don&#8217;t depend on the effective dialect. <em>wlang</em> hides language - and vendors differences! - </p> + + + <h3 id="Encoding">Encoding</h3> + <p> +Almost all languages require escaping/encoding in specific situations: +quoted string literals always come with an escaping mechanism +(unfortunately different from one language to another), html requires +entities-encoding, etc. The Encoding ruleset proposes shortcut tags for +encoding. Note that these shortcuts are written in such a way that they +don&#8217;t depend on the effective dialect. <em>wlang</em> hides language +and vendors differences! +</p> + + <table class="ruleset"> + <tr> + <th class="signature">signature</th> + <th class="name">name</th> + <th class="definition">definition</th> + </tr> - <table class="ruleset"> <tr> - <th class="signature">signature</th> - <th class="name">name</th> - <th class="definition">definition</th> - </tr> - <tr> <td class="signature"><tt>&amp;{...}</tt></td> <td class="name">main-encoding</td> <td class="definition"><tt>^{+{@parser.current_dialect}/main-encoding}{#1}</tt></td> </tr> + <tr> <td class="signature"><tt>&amp;;{...}</tt></td> <td class="name">entities-encoding</td> <td class="definition"><tt>^{+{@parser.current_dialect}/entities-encoding}{#1}</tt></td> </tr> + <tr> <td class="signature"><tt>&amp;'{...}</tt></td> <td class="name">single-quoting</td> <td class="definition"><tt>^{+{@parser.current_dialect}/single-quoting}{#1}</tt></td> </tr> + <tr> <td class="signature"><tt>&amp;&quot;{...}</tt></td> <td class="name">double-quoting</td> <td class="definition"><tt>^{+{@parser.current_dialect}/double-quoting}{#1}</tt></td> </tr> + <tr> <td class="signature"><tt>${wlang/hosted}</tt></td> <td class="name">injection</td> <td class="definition"><tt>&amp;{+{#1}}</tt></td> </tr> + <tr> <td class="signature"><tt>'{wlang/hosted}</tt></td> <td class="name">single-quoted</td> <td class="definition"><tt>'&amp;'{+{#1}}</tt> (first single quote is kept in the result)</td> </tr> + <tr> <td class="signature"><tt>&quot;{wlang/hosted}</tt></td> <td class="name">double-quoted</td> <td class="definition"><tt>&quot;&amp;&quot;{+{#1}}</tt> (first double quote is kept in the - result)</td> +result)</td> </tr> - </table> - + </table> + + <br/> <h4>Examples:</h4> <table class="examples"> <tr> <th>dialect</th> <th>wlang expression</th> <th>replacement value</th> </tr> - <tr> - <td class="dialect"> - <tt>wlang/xhtml</tt> - </td> - <td class="expression"> - <tt>Hello &amp;{name}</tt> - </td> - <td class="replacement"> - <tt>Hello name</tt> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/xhtml</tt> - </td> - <td class="expression"> - <tt>Hello &amp;{&lt;script&gt;}</tt> - </td> - <td class="replacement"> - <tt>Hello &lt;script&gt;</tt> + <tr> + <td class="dialect"> + <tt>wlang/xhtml</tt> + </td> + <td class="expression"> + <tt>Hello &amp;{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello name</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/xhtml</tt> - </td> - <td class="expression"> - <tt>Hello &amp;;{&lt;script&gt;}</tt> - </td> - <td class="replacement"> - <tt>Hello &lt;script&gt;</tt> + <tr> + <td class="dialect"> + <tt>wlang/xhtml</tt> + </td> + <td class="expression"> + <tt>Hello &amp;{&lt;script&gt;}</tt> + </td> + <td class="replacement"> + + <tt>Hello &lt;script&gt;</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/ruby</tt> - </td> - <td class="expression"> - <tt>puts 'Hello &amp;'{name}'</tt> - </td> - <td class="replacement"> - <tt>puts 'Hello name'</tt> + <tr> + <td class="dialect"> + <tt>wlang/xhtml</tt> + </td> + <td class="expression"> + <tt>Hello &amp;;{&lt;script&gt;}</tt> + </td> + <td class="replacement"> + + <tt>Hello &lt;script&gt;</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/ruby</tt> - </td> - <td class="expression"> - <tt>puts 'Hello &amp;'{!{name}}'</tt> - </td> - <td class="replacement"> - <tt>puts 'Hello O\'Neil'</tt> + <tr> + <td class="dialect"> + <tt>wlang/ruby</tt> + </td> + <td class="expression"> + <tt>puts 'Hello &amp;'{name}'</tt> + </td> + <td class="replacement"> + + <tt>puts 'Hello name'</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/ruby</tt> - </td> - <td class="expression"> - <tt>puts 'Hello ' &lt;&lt; '{name}'</tt> - </td> - <td class="replacement"> - <tt>puts 'Hello ' << 'O\'Neil'</tt> + <tr> + <td class="dialect"> + <tt>wlang/ruby</tt> + </td> + <td class="expression"> + <tt>puts 'Hello &amp;'{!{name}}'</tt> + </td> + <td class="replacement"> + + <tt>puts 'Hello O\'Neil'</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/sql</tt> - </td> - <td class="expression"> - <tt>... WHERE name='{name}'</tt> - </td> - <td class="replacement"> - <tt>... WHERE name='O\'Neil'</tt> + <tr> + <td class="dialect"> + <tt>wlang/ruby</tt> + </td> + <td class="expression"> + <tt>puts 'Hello ' &lt;&lt; '{name}'</tt> + </td> + <td class="replacement"> + + <tt>puts 'Hello ' << 'O\'Neil'</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/sql/sybase</tt> - </td> - <td class="expression"> - <tt>... WHERE name='{name}'</tt> - </td> - <td class="replacement"> - <tt>... WHERE name='O''Neil'</tt> + <tr> + <td class="dialect"> + <tt>wlang/sql</tt> + </td> + <td class="expression"> + <tt>... WHERE name='{name}'</tt> + </td> + <td class="replacement"> + + <tt>... WHERE name='O\'Neil'</tt> + + </td> + </tr> - </td> - </tr> - + <tr> + <td class="dialect"> + <tt>wlang/sql/sybase</tt> + </td> + <td class="expression"> + <tt>... WHERE name='{name}'</tt> + </td> + <td class="replacement"> + + <tt>... WHERE name='O''Neil'</tt> + + </td> + </tr> + </table> <div style="clear: both;"></div> - <h3 id="Imperative">Imperative</h3> - <p> - Instantiating conditionally and iterating collection elements are common - code generation tasks. The Imperative dialect provides these features. - </p> + + + <h3 id="Imperative">Imperative</h3> + <p> +Instantiating conditionally and iterating collection elements are common +code generation tasks. The Imperative dialect provides these features. +</p> + + <table class="ruleset"> + <tr> + <th class="signature">signature</th> + <th class="name">name</th> + <th class="definition">definition</th> + </tr> - <table class="ruleset"> <tr> - <th class="signature">signature</th> - <th class="name">name</th> - <th class="definition">definition</th> - </tr> - <tr> <td class="signature"><tt>?{wlang/hosted}{...}{...}</tt></td> <td class="name">conditional<br/>(third block is optional)</td> <td class="definition">Instantiates #1, looking for an expression in the hosting language. - Evaluates it, looking for a boolean value (according to boolean semantics - of the hosting language). If true, instantiates #2, otherwise instantiates - #3 if present, returning instantiation as replacement value.</td> +Evaluates it, looking for a boolean value (according to boolean semantics +of the hosting language). If true, instantiates #2, otherwise instantiates +#3 if present, returning instantiation as replacement value.</td> </tr> + <tr> <td class="signature"><tt>*{wlang/hosted &lt;as x&gt;?}{...}{...}</tt></td> <td class="name">enumeration<br/>(third block is optional)</td> <td class="definition">Instantiates #1, looking for an expression in the hosting language. - Evaluates it, looking for an enumerable. Iterates all its elements, - instantiating #2 for each of them (the iterated value is set under name x - in the scope). If #3 is present, it is instantiated between elements. - Replacement is the concatenation of all these instantiations.</td> +Evaluates it, looking for an enumerable. Iterates all its elements, +instantiating #2 for each of them (the iterated value is set under name x +in the scope). If #3 is present, it is instantiated between elements. +Replacement is the concatenation of all these instantiations.</td> </tr> - </table> - + </table> + + <br/> <h4>Examples:</h4> <table class="examples"> <tr> <th>dialect</th> <th>wlang expression</th> <th>replacement value</th> </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>?{true}{then}{else}</tt> - </td> - <td class="replacement"> - <tt>then</tt> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>?{/th/ =~ &quot;not tat&quot;}{then}{else}</tt> - </td> - <td class="replacement"> - <tt>else</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>?{true}{then}{else}</tt> + </td> + <td class="replacement"> + + <tt>then</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>?{authors.include? &quot;blambeau&quot;}{yes}{no}</tt> - </td> - <td class="replacement"> - <tt>yes</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>?{/th/ =~ &quot;not tat&quot;}{then}{else}</tt> + </td> + <td class="replacement"> + + <tt>else</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>[*{authors as a}{&quot;{a}&quot;}{, }]</tt> - </td> - <td class="replacement"> - <tt>["blambeau", "llambeau", "ancailliau"]</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>?{authors.include? &quot;blambeau&quot;}{yes}{no}</tt> + </td> + <td class="replacement"> + + <tt>yes</tt> + + </td> + </tr> - </td> - </tr> - + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>[*{authors as a}{&quot;{a}&quot;}{, }]</tt> + </td> + <td class="replacement"> + + <tt>["blambeau", "llambeau", "ancailliau"]</tt> + + </td> + </tr> + </table> <div style="clear: both;"></div> - <h3 id="Context">Context</h3> - <p> - Complex templates come with specific needs. The ability to manipulate the - context and the current scope is provided by the Context ruleset. All are - variants of &#8216;saving previous instantiations&#8217; in scope - variables&#8230; - </p> + + + <h3 id="Context">Context</h3> + <p> +Complex templates come with specific needs. The ability to manipulate the +context and the current scope is provided by the Context ruleset. All are +variants of &#8216;saving previous instantiations&#8217; in scope +variables&#8230; +</p> + + <table class="ruleset"> + <tr> + <th class="signature">signature</th> + <th class="name">name</th> + <th class="definition">definition</th> + </tr> - <table class="ruleset"> <tr> - <th class="signature">signature</th> - <th class="name">name</th> - <th class="definition">definition</th> - </tr> - <tr> <td class="signature"><tt>={wlang/hosted &lt;as x&gt;}{...}</tt></td> <td class="name">assignment<br/>(second block is optional)</td> <td class="definition">Instantiates #1, looking for an expression in the hosting language. - Evaluates it, looking for any object. Without second block, expands the - current scope with &#8216;x&#8217; being bound to evaluation result. - Otherwise, branches the current scope for the second block instantiation - only and bind &#8216;x&#8217; the same way (i.e. x will not be available - outside the second block). Returns an empty string as replacement value.</td> +Evaluates it, looking for any object. Without second block, expands the +current scope with &#8216;x&#8217; being bound to evaluation result. +Otherwise, branches the current scope for the second block instantiation +only and bind &#8216;x&#8217; the same way (i.e. x will not be available +outside the second block). Returns an empty string as replacement value.</td> </tr> + <tr> <td class="signature"><tt>%={wlang/active-string &lt;as x&gt;}{...}{...}</tt></td> <td class="name">modulo-assignment<br/>(third block is optional)</td> <td class="definition">Instantiates #1, looking for a dialect qualified name. Instantiates #2 - according to the rules defined by that dialect. Without third block, - expands the current scope with &#8216;x&#8217; being bound to #2&#8217;s - instantiation. Otherwise, branches the current scope for the third block - instantiation only and binds &#8216;x&#8217; the same way (i.e. x will not - be available outside the third block). Returns an empty string as - replacement value.</td> +according to the rules defined by that dialect. Without third block, +expands the current scope with &#8216;x&#8217; being bound to #2&#8217;s +instantiation. Otherwise, branches the current scope for the third block +instantiation only and binds &#8216;x&#8217; the same way (i.e. x will not +be available outside the third block). Returns an empty string as +replacement value.</td> </tr> + <tr> <td class="signature"><tt>#={wlang/active-string}{...}{...}</tt></td> <td class="name">block-assignment<br/>(third block is optional)</td> <td class="definition"><tt>%={+{@parser.current_dialect} as #1}{#2}{#3}</tt></td> </tr> + <tr> <td class="signature"><tt>^={wlang/active-string &lt;as x&gt;}{...}{...}</tt></td> <td class="name">encoding-assignment<br/>(third block is optional)</td> <td class="definition"><tt>%={+{@parser.current_dialect} as x}{^{#1}{#2}}{#3}</tt></td> </tr> - </table> - + </table> + + <br/> <h4>Examples:</h4> <table class="examples"> <tr> <th>dialect</th> <th>wlang expression</th> <th>replacement value</th> </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>={name as n}{Hello +{n}}</tt> - </td> - <td class="replacement"> - <tt>Hello O'Neil</tt> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>={name as n}Hello +{n}</tt> - </td> - <td class="replacement"> - <tt>Hello O'Neil</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>={name as n}{Hello !{n}}</tt> + </td> + <td class="replacement"> + + <tt>Hello O'Neil</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>#={name}{blambeau}{Hello +{name}} and +{name}</tt> - </td> - <td class="replacement"> - <tt>Hello blambeau and O'Neil</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>={name as n}Hello !{n}</tt> + </td> + <td class="replacement"> + + <tt>Hello O'Neil</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>#={name}{blambeau}Hello +{name} and +{name}</tt> - </td> - <td class="replacement"> - <tt>Hello blambeau and blambeau</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>#={name}{blambeau}{Hello !{name}} and !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello blambeau and O'Neil</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>={author as name}{Hello +{name}} and +{name}</tt> - </td> - <td class="replacement"> - <tt>Hello blambeau and O'Neil</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>#={name}{blambeau}Hello !{name} and !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello blambeau and blambeau</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>={author as name}Hello +{name} and +{name}</tt> - </td> - <td class="replacement"> - <tt>Hello blambeau and blambeau</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>={author as name}{Hello !{name}} and !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello blambeau and O'Neil</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>%={wlang/dummy as hello}{Hello +{name}}{+{hello}}</tt> - </td> - <td class="replacement"> - <tt>Hello +{name}</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>={author as name}Hello !{name} and !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello blambeau and blambeau</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>^={plain-text/upcase as name}{+{author}}{Hello +{name}} and +{name}</tt> - </td> - <td class="replacement"> - <tt>Hello BLAMBEAU and O'Neil</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>%={wlang/dummy as hello}{Hello !{name}}{!{hello}}</tt> + </td> + <td class="replacement"> + + <tt>Hello !{name}</tt> + + </td> + </tr> - </td> - </tr> - <tr> - <td class="dialect"> - <tt>wlang/*</tt> - </td> - <td class="expression"> - <tt>^={plain-text/upcase as name}{+{author}}Hello +{name} and +{name}</tt> - </td> - <td class="replacement"> - <tt>Hello BLAMBEAU and BLAMBEAU</tt> + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>^={plain-text/upcase as name}{!{author}}{Hello !{name}} and !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello BLAMBEAU and O'Neil</tt> + + </td> + </tr> - </td> - </tr> - + <tr> + <td class="dialect"> + <tt>wlang/*</tt> + </td> + <td class="expression"> + <tt>^={plain-text/upcase as name}{!{author}}Hello !{name} and !{name}</tt> + </td> + <td class="replacement"> + + <tt>Hello BLAMBEAU and BLAMBEAU</tt> + + </td> + </tr> + </table> <div style="clear: both;"></div> - <h3 id="Buffering">Buffering</h3> - <p> - The Buffering ruleset is probably one of the more useful. It allows you to - load text and data files, to change the current output buffer (for - generating multiple files for example) and even to start the instantiation - on other templates. - </p> + + + <h3 id="Buffering">Buffering</h3> + <p> +The Buffering ruleset is probably one of the more useful. It allows you to +load text and data files, to change the current output buffer (for +generating multiple files for example) and even to start the instantiation +on other templates. +</p> + + <table class="ruleset"> + <tr> + <th class="signature">signature</th> + <th class="name">name</th> + <th class="definition">definition</th> + </tr> - <table class="ruleset"> <tr> - <th class="signature">signature</th> - <th class="name">name</th> - <th class="definition">definition</th> - </tr> - <tr> <td class="signature"><tt>&lt;&lt;{wlang/uri}</tt></td> <td class="name">input</td> <td class="definition">Instantiates #1, looking for an uri. Returns the text content of the found - uri (#1) as replacement value.</td> +uri (#1) as replacement value.</td> </tr> + <tr> <td class="signature"><tt>&gt;&gt;{wlang/uri}{...}</tt></td> <td class="name">output</td> <td class="definition">Instantiates #1, looking for an uri. Instantiates #2 in the current - dialect, using the file found in #1 as output buffer. Returns an empty - string as replacement value.</td> +dialect, using the file found in #1 as output buffer. Returns an empty +string as replacement value.</td> </tr> + <tr> <td class="signature"><tt>&lt;&lt;={wlang/uri &lt;as x&gt;}{...}</tt></td> <td class="name">data-assignment</td> <td class="definition">Instantiates #1, looking for an uri. Loads data provided by this uri, based - on the file extension (typically .yml or .rb). Without second block, - expands the current scope with &#8216;x&#8217; being bound to the data. - Otherwise, branches the current scope for the second block instantiation - only and binds &#8216;x&#8217; the same way (i.e. x will not be available - outside the second block). Returns an empty string as replacement value.</td> +on the file extension (typically .yml or .rb). Without second block, +expands the current scope with &#8216;x&#8217; being bound to the data. +Otherwise, branches the current scope for the second block instantiation +only and binds &#8216;x&#8217; the same way (i.e. x will not be available +outside the second block). Returns an empty string as replacement value.</td> </tr> + <tr> <td class="signature"><tt>&lt;&lt;+{wlang/uri &lt;using&gt;? &lt;with&gt;?}</tt></td> <td class="name">input-inclusion</td> <td class="definition">Instantiates #1, looking for an uri. Instantiates the <em>wlang</em> - template at this location (the dialect is infered from the file extension) - in a fresh new scope built from the <em>with</em> expression. Returns this - instantiation as replacement value.</td> +template at this location (the dialect is infered from the file extension) +in a fresh new scope built from the <em>with</em> expression. Returns this +instantiation as replacement value.</td> </tr> - </table> + </table> + + + + + + </div> + <div id="dialects" style="display: none;"> + <div class="header"> + <h2>Dialects</h2> + + <div class="clear"></div> + </div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/hosted</h3> - </div> - <div id="dialects" style="display: none;"> - <div class="header"> - <h2>Dialects</h2> - - <div class="clear"></div> - </div> - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/uri</h3> + <p style="display: inline">Includes Basic, Encoding, Imperative, Context, Hosted</p> + + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/uri</h3> + <p style="display: inline">Includes Basic</p> - </div> + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/active-text</h3> + <p style="display: inline">Includes Basic, Imperative, Buffering, Context</p> - </div> - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/sql</h3> + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/sql</h3> + <p style="display: inline">Includes Basic, Encoding, Imperative, SQL</p> - </div> + </div> + + - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/sql/sybase</h3> - <p style="display: inline">Includes Basic, Encoding, Imperative, SQL</p> + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/sql/sybase</h3> - </div> - - - </div> + <p style="display: inline">Includes Basic, Encoding, Imperative, SQL</p> + </div> + + +</div> + - </div> - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/active-string</h3> + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/active-string</h3> + <p style="display: inline">Includes Basic, Imperative</p> - </div> + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/xhtml</h3> - - </div> - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/xhtml</h3> <p style="display: inline">Includes Basic, Encoding, Imperative, Buffering, Context, XHtml</p> - </div> + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/yaml</h3> + <p style="display: inline">Includes Basic, Encoding, Imperative, Buffering, Context, YAML</p> - </div> - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/ruby</h3> - <p style="display: inline">Includes Basic, Encoding, Imperative, Context, Ruby</p> + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/ruby</h3> - </div> + <p style="display: inline">Includes Basic, Encoding, Imperative, Buffering, Context, Ruby</p> + </div> + + +</div> + + + <div class="dialect"> + <div style="margin-bottom: 20px"> + <h3 style="display: inline">wlang/dummy</h3> - </div> - <div class="dialect"> - <div style="margin-bottom: 20px"> - <h3 style="display: inline">wlang/dummy</h3> - - </div> + </div> + + +</div> + + + + </div> + <div id="hosting" style="display: none;"> + <div class="header"> + <h2>Hosting language</h2> + + <div class="clear"></div> + </div> + + + + </div> - </div> + <div id="glossary" style="display: none;"> + <div class="header"> + <h2>Glossary</h2> + + <div class="clear"></div> + </div> + + <table class="glossary"> + <tr> + <th class="term">term</th> + <th class="definition">definition</th> + <th class="example">example</th> + </tr> + + <tr> + <td><em>template</em></td> + <td>Source code respecting the wlang grammar, and attached to a given <em>wlang +dialect</em>.</td> + <td style="font-size: 90%;"><tt>Hello ${name}</tt></td> + </tr> + + <tr> + <td><em>dialect</em></td> + <td>Basically, <em>dialect</em> is used as a synonym for (programming) +<em>language</em>. However <em>wlang</em> uses a tree of dialects, allowing +specializations: <tt>sql/sybase</tt> for example is the qualified name of a +sub-dialect &#8216;sybase&#8217; of the &#8216;sql&#8217; dialect. Dialects +come with associated <em>encoders</em>.</td> + <td style="font-size: 90%;"><tt>sql/sybase</tt></td> + </tr> + + <tr> + <td><em>wlang dialect</em></td> + <td>When we talk about a <em>wlang dialect</em>, we are actually refering to +some specialization of the wlang tag-based grammar: <tt>wlang/xhtml</tt> +for example is the templating language <em>wlang</em> proposes to generate +xhtml pages. An example of source code in that dialect has been shown +before. In addition to its encoders a <em>wlang dialect</em> comes with its +sets of <em>tags</em> and associated <em>rules</em>.</td> + <td style="font-size: 90%;"><tt>wlang/xhtml</tt></td> + </tr> + + <tr> + <td><em>encoder</em></td> + <td>Text transformation (algorithm) applying some encoding conventions of a +portion of a the target language generated by a dialect. HTML +entities-encoding, SQL&#8217;s back-quoting are examples of encoders. +Encoders are accessible through their qualified name (dialect/encoder).</td> + <td style="font-size: 90%;"><tt>xhtml/entities-encoding</tt><br/><tt>sql/single-quoting</tt></td> + </tr> + + <tr> + <td><em>ruleset</em></td> + <td>Reusable set of <em>tags</em> associated to <em>rule</em>s.</td> + <td style="font-size: 90%;"><tt>Imperative ruleset</tt><br/><tt>Encoding rulset</tt></td> + </tr> + + <tr> + <td><em>wlang tag</em></td> + <td>Special tags in the template, starting with wlang symbols and a number of +wlang blocks. A tag is associated with a wlang rule.</td> + <td style="font-size: 90%;"><tt>${...}</tt><br/><tt>?{...}{...}{...}</tt></td> + </tr> + + <tr> + <td><em>rule</em></td> + <td>Transformation semantics of a given <em>tag</em>. When wlang instantiates a +template it simply replaces <em>wlang tags</em> by some <em>replacement +value</em> (which is always a string). This value is computed by the rule +attached to the tag. Rule definition (see Rulesets tab on top of the page) +explicitly describes the number of blocks it expects, in which dialect they +are parsed and instantiated and the way the replacement value is computed.</td> + <td style="font-size: 90%;"><tt>^{wlang/active-string}{...}</tt><br/> Instantiates #1, looking for an +encoder qualified name. Instantiates #2 in the current dialect. Encode +#2&#8217;s instantiation using encoder found in (#1) and return the result +as replacement value.</td> + </tr> + + <tr> + <td><em>context</em></td> + <td>Some rules allow code to be executed in the <em>hosting language</em> (the +definition explicitly announce it by putting <tt>wlang/hosted</tt> in the +corresponding block). When doing so, this code is in fact executed in a +given context that provides the execution semantics.</td> + <td style="font-size: 90%;"></td> + </tr> + + <tr> + <td><em>hosting language</em></td> + <td>language (or framework) that executes wlang. More precisely, the hosting +language is the one that rules what is considered as an executable +expression in tags that relies on some execution semantics (like !{&#8230;} +for example). See the &#8216;Hosting language&#8217; section to learn more.</td> + <td style="font-size: 90%;">ruby</td> + </tr> + +</table> + + + </div> - - </div> - <div id="hosting" style="display: none;"> - <div class="header"> - <h2>Hosting language</h2> - - <div class="clear"></div> - </div> - - - </div> - <div id="glossary" style="display: none;"> - <div class="header"> - <h2>Glossary</h2> - - <div class="clear"></div> - </div> - <table class="glossary"> + <div id="symbols" style="display: none;"> + <div class="header"> + <h2>Tag symbols</h2> + + <div class="clear"></div> + </div> + + <table class="symbols"> + <tr> + <th class="name">name</th> + <th class="symbol">symbol</th> + <th class="meaning">meaning</th> + <th class="remark">remark</th> + </tr> + <tr> - <th class="term">term</th> - <th class="definition">definition</th> - <th class="example">example</th> - </tr> - <tr> - <td><em>template</em></td> - <td>Source code respecting the wlang grammar, and attached to a given <em>wlang - dialect</em>.</td> - <td style="font-size: 90%;"><tt>Hello ${name}</tt></td> - </tr> - <tr> - <td><em>dialect</em></td> - <td>Basically, <em>dialect</em> is used as a synonym for (programming) - <em>language</em>. However <em>wlang</em> uses a tree of dialects, allowing - specializations: <tt>sql/sybase</tt> for example is the qualified name of a - sub-dialect &#8216;sybase&#8217; of the &#8216;sql&#8217; dialect. Dialects - come with associated <em>encoders</em>.</td> - <td style="font-size: 90%;"><tt>sql/sybase</tt></td> - </tr> - <tr> - <td><em>wlang dialect</em></td> - <td>When we talk about a <em>wlang dialect</em>, we are actually refering to - some specialization of the wlang tag-based grammar: <tt>wlang/xhtml</tt> - for example is the templating language <em>wlang</em> proposes to generate - xhtml pages. An example of source code in that dialect has been shown - before. In addition to its encoders a <em>wlang dialect</em> comes with its - sets of <em>tags</em> and associated <em>rules</em>.</td> - <td style="font-size: 90%;"><tt>wlang/xhtml</tt></td> - </tr> - <tr> - <td><em>encoder</em></td> - <td>Text transformation (algorithm) applying some encoding conventions of a - portion of a the target language generated by a dialect. HTML - entities-encoding, SQL&#8217;s back-quoting are examples of encoders. - Encoders are accessible through their qualified name (dialect/encoder).</td> - <td style="font-size: 90%;"><tt>xhtml/entities-encoding</tt><br/><tt>sql/single-quoting</tt></td> - </tr> - <tr> - <td><em>ruleset</em></td> - <td>Reusable set of <em>tags</em> associated to <em>rule</em>s.</td> - <td style="font-size: 90%;"><tt>Imperative ruleset</tt><br/><tt>Encoding rulset</tt></td> - </tr> - <tr> - <td><em>wlang tag</em></td> - <td>Special tags in the template, starting with wlang symbols and a number of - wlang blocks. A tag is associated with a wlang rule.</td> - <td style="font-size: 90%;"><tt>${...}</tt><br/><tt>?{...}{...}{...}</tt></td> - </tr> - <tr> - <td><em>rule</em></td> - <td>Transformation semantics of a given <em>tag</em>. When wlang instantiates a - template it simply replaces <em>wlang tags</em> by some <em>replacement - value</em> (which is always a string). This value is computed by the rule - attached to the tag. Rule definition (see Rulesets tab on top of the page) - explicitly describes the number of blocks it expects, in which dialect they - are parsed and instantiated and the way the replacement value is computed.</td> - <td style="font-size: 90%;"><tt>^{wlang/active-string}{...}</tt><br/> Instantiates #1, looking for an - encoder qualified name. Instantiates #2 in the current dialect. Encode - #2&#8217;s instantiation using encoder found in (#1) and return the result - as replacement value.</td> - </tr> - <tr> - <td><em>context</em></td> - <td>Some rules allow code to be executed in the <em>hosting language</em> (the - definition explicitly announce it by putting <tt>wlang/hosted</tt> in the - corresponding block). When doing so, this code is in fact executed in a - given context that provides the execution semantics.</td> - <td style="font-size: 90%;"></td> - </tr> - <tr> - <td><em>hosting language</em></td> - <td>language (or framework) that executes wlang. More precisely, the hosting - language is the one that rules what is considered as an executable - expression in tags that relies on some execution semantics (like !{&#8230;} - for example). See the &#8216;Hosting language&#8217; section to learn more.</td> - <td style="font-size: 90%;">ruby</td> - </tr> - - </table> - - - </div> - <div id="symbols" style="display: none;"> - <div class="header"> - <h2>Tag symbols</h2> - - <div class="clear"></div> - </div> - <table class="symbols"> - <tr> - <th class="name">name</th> - <th class="symbol">symbol</th> - <th class="meaning">meaning</th> - <th class="remark">remark</th> - </tr> - <tr> <td><em>exclamation mark</em></td> <td>!</td> <td>execution</td> <td>should never be overrided as single</td> </tr> + <tr> <td><em>caret/circumflex</em></td> <td>^</td> <td>explicit encoding</td> <td>should never be overrided as single</td> </tr> + <tr> <td><em>percent</em></td> <td>%</td> <td>modulation</td> <td>should never be overrided as single</td> </tr> + <tr> <td><em>double quote</em></td> <td>&quot;</td> <td>double-quoting</td> <td></td> </tr> + <tr> <td><em>dollar</em></td> <td>$</td> <td>main-encoding</td> <td></td> </tr> + <tr> <td><em>ampersand</em></td> <td>&amp;</td> <td>encoding</td> <td></td> </tr> + <tr> <td><em>single quote</em></td> <td>'</td> <td>single-quoting</td> <td></td> </tr> + <tr> <td><em>asterisk</em></td> <td>*</td> <td>iteration</td> <td></td> </tr> + <tr> <td><em>plus</em></td> <td>+</td> <td>inclusion</td> <td></td> </tr> + <tr> <td><em>question mark</em></td> <td>?</td> <td>condition</td> <td></td> </tr> + <tr> <td><em>at symbol</em></td> <td>@</td> <td>linking</td> <td></td> </tr> + <tr> <td><em>tilde</em></td> <td>~</td> <td>matching</td> <td></td> </tr> + <tr> <td><em>number sign</em></td> <td>#</td> <td></td> <td></td> </tr> + <tr> <td><em>comma</em></td> <td>,</td> <td></td> <td></td> </tr> + <tr> <td><em>minus (dash)</em></td> <td>-</td> <td></td> <td></td> </tr> + <tr> <td><em>dot</em></td> <td>.</td> <td></td> <td></td> </tr> + <tr> <td><em>forward slash</em></td> <td>/</td> <td></td> <td></td> </tr> + <tr> <td><em>colon</em></td> <td>:</td> <td></td> <td></td> </tr> + <tr> <td><em>semi-colon</em></td> <td>;</td> <td></td> <td></td> </tr> + <tr> <td><em>equal sign</em></td> <td>=</td> <td></td> <td></td> </tr> + <tr> <td><em>less than</em></td> <td>&lt;</td> <td></td> <td></td> </tr> + <tr> <td><em>greater than</em></td> <td>&gt;</td> <td></td> <td></td> </tr> + <tr> <td><em>vertical bar</em></td> <td>|</td> <td></td> <td></td> </tr> + <tr> <td><em>underscore</em></td> <td>_</td> <td></td> <td>cannot be used as tag symbol; reserved for escaping in future versions</td> </tr> + <tr> <td><em>back slash</em></td> <td>\</td> <td></td> <td>cannot be used as tag symbol; reserved for escaping in current version</td> </tr> + <tr> <td><em>left parenthesis</em></td> <td>(</td> <td></td> <td>cannot be used as tag symbol; reserved for block delimiter</td> </tr> + <tr> <td><em>right parenthesis</em></td> <td>)</td> <td></td> <td>cannot be used as tag symbol; reserved for block delimiter</td> </tr> + <tr> <td><em>left bracket</em></td> <td>[</td> <td></td> <td>cannot be used as tag symbol; reserved for block delimiter</td> </tr> + <tr> <td><em>right bracket</em></td> <td>]</td> <td></td> <td>cannot be used as tag symbol; reserved for block delimiter</td> </tr> + <tr> <td><em>left brace</em></td> <td>{</td> <td></td> <td>cannot be used as tag symbol; reserved for block delimiter</td> </tr> + <tr> <td><em>right brace</em></td> <td>}</td> <td></td> <td>cannot be used as tag symbol; reserved for block delimiter</td> </tr> - - </table> - - - </div> + +</table> + + </div> + </body> </html>