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/LICENCE.rdoc ADDED
@@ -0,0 +1,25 @@
1
+ = Licence
2
+
3
+ The MIT License
4
+
5
+ Copyright (c) 2009 Bernard & Louis Lambeau and the University of Louvain
6
+ (Universite Catholique de Louvain, Louvain-la-Neuve, Belgium)
7
+
8
+ Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ of this software and associated documentation files (the "Software"), to deal
10
+ in the Software without restriction, including without limitation the rights
11
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ copies of the Software, and to permit persons to whom the Software is
13
+ furnished to do so, subject to the following conditions:
14
+
15
+ The above copyright notice and this permission notice shall be included in
16
+ all copies or substantial portions of the Software.
17
+
18
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24
+ THE SOFTWARE.
25
+
data/README.rdoc ADDED
@@ -0,0 +1,111 @@
1
+ = What is _wlang_ ?
2
+
3
+ _wlang_ is a simple, powerful, robust and secure <b>code generation</b>/<b>templating engine</b>
4
+ (at least, authors hope so ;-) Motivation for it can be found at http://www.revision-zero.org/wlang.
5
+ It's main aim is to help you creating web pages, sql queries, ruby code (that is, generating code in
6
+ general) without having to worry too much about html entities encoding, sql back quoting, string
7
+ escaping and the like. WLang proposes a generic engine that you can extend to fit your needs. It also
8
+ proposes standard instantiations of this engine for common tasks such as creating SQL queries,
9
+ instantiating web pages, etc.
10
+
11
+ == Roadmap
12
+
13
+ - For terminology and a quick overview of _wlang_ for generating code, read on.
14
+ - For the current cheatsheet/specification see the file doc/specification/specification.html
15
+ - If you want to learn _wlang_ quickly, see the example directory or read examples
16
+ in the specification file (if you understand all examples in the specification file, then you
17
+ probably master wlang.
18
+ - If you want a killer example (but simple) see the way the specification.html file
19
+ is generated in doc/specification directory
20
+ - If you want to know which dialects are available (that is, in which target languages
21
+ you can generate code), see the specification as well or read the file
22
+ lib/wlang/dialects/standard_dialects.rb in the source distribution.
23
+ - If you want to create your own wlang dialect, see WLang::Dialect::DSL
24
+ - If you think that your own dialect is of generic purpose and well-designed, if
25
+ you have any question or want to contribute join us on {github}[http://github.com/blambeau/wlang].
26
+
27
+ == Overview
28
+
29
+ (for bold words, see terminology later) Basic usage of _wlang_ is as follows:
30
+ you have a *template* file (written in a given _wlang_ *dialect*), you have some
31
+ instantiation *context* (data provided through a Ruby Hash or a yaml file for
32
+ example) and you would like to instantiate the template with that data.
33
+
34
+ Example: a template.whtml as follows
35
+ <html>
36
+ <head>
37
+ <title>${title}</title>
38
+ </head>
39
+ <body>
40
+ <h1>Hello ${who} !</h1>
41
+ </body>
42
+ </html>
43
+
44
+ Instantiation data is a hash containing values for _title_ and _who_. Instantiating
45
+ the template is straightforward:
46
+
47
+ require 'wlang'
48
+ context = {"title" => "Hello world in WLang", "who" => "Alice"}
49
+ WLang.file_instantiate("template.whtml", context, STDOUT)
50
+
51
+ === Seems magic ... but is not!
52
+
53
+ - first of all, it <b>does not allow XSS attacks</b>: even if _who_ is a value
54
+ like <tt>'<script>[some javascript code]</script>'</tt>, it will be automatically
55
+ entities-encoded and will appear for itself, not allowing the browser to interpret
56
+ it as javascript code.
57
+ - <b>it is not hardcoded</b>, but uses _wlang_ shortcuts:
58
+ - as you did not specify the _wlang_ dialect of your template, it has been infered
59
+ as 'wlang/xhtml' from the file extension.
60
+ - in this dialect, the wlang rule associated with the tag ${...} (<tt>${who}</tt>
61
+ for example) automatically replaces the tag by the context data under 'who' (in
62
+ the hash), while taking care of applying entities-encoding.
63
+ - <b>${...} is only one available tag</b>. Actuall _wlang_ dialects come with a lot
64
+ of useful tags that provide shortuct to common tasks ... entities-encoding is only one !
65
+
66
+ == Terminology
67
+
68
+ _wlang_ comes with a well-defined terminology for the underlying abstractions. As
69
+ the documentation uses it, you'll probably be happy to learn about the main abstractions
70
+ and associated terms.
71
+
72
+ [template] Source code respecting the wlang grammar, and attached to a given <em>wlang
73
+ dialect</em>. Asbtraction implemented by WLang::Template.
74
+ [dialect] Basically, <em>dialect</em> is used as a synonym for (programming) <em>language</em>.
75
+ However _wlang_ uses a tree of dialects, allowing specializations: <tt>sql/sybase</tt>
76
+ for example is the qualified name of a sub-dialect 'sybase' of the 'sql' dialect.
77
+ Dialects come with associated _encoders_. Abstraction implemented by WLang::Dialect.
78
+ [wlang dialect] When we talk about a <em>wlang dialect</em>, we are actually refering to some
79
+ specialization of the wlang tag-based grammar: <tt>wlang/xhtml</tt> for example
80
+ is the templating language _wlang_ proposes to generate xhtml pages. An
81
+ example of source code in that dialect has been shown before.
82
+ In addition to its encoders a <em>wlang dialect</em> comes with its sets of _tags_
83
+ and associated _rules_. Abstraction implemented by WLang::Dialect as well as
84
+ WLang::EncoderSet and WLang::RuleSet.
85
+ [encoder set] Reusable set of <em>encoders</em>, attached to a dialect. Abstraction
86
+ implemented by WLang::EncoderSet.
87
+ [encoder] Text transformation (algorithm) applying some encoding conventions of a portion
88
+ of a the target language generated by a dialect. HTML entities-encoding, SQL's back-quoting
89
+ are examples of encoders. Encoders are accessible through their qualified name:
90
+ xhtml/entities-encoding and sql/back-quoting in the examples. Abstraction implemented by
91
+ WLang::Encoder.
92
+ [ruleset] Reusable set of <em>tags</em> associated to <em>rule</em>s. Abstraction
93
+ implemented by WLang::RuleSet.
94
+ [wlang tag] Special tags in the template, starting with wlang symbols and a number of wlang
95
+ blocks. A tag is associated with a wlang rule. Examples: <tt>${...}</tt> is a
96
+ tag with only one block, while <tt>?{...}{...}{...}</tt> is another tag but with
97
+ three blocks.
98
+ [rule] Transformation semantics of a given <em>tag</em>. When wlang instantiates a
99
+ template it simply replaces <em>wlang tags</em> by some <em>replacement value</em>
100
+ (which is always a string). This value is computed by the rule attached to
101
+ the tag. Rule definition explicitly describes the number of blocks it expects, in which dialect they
102
+ are parsed and instantiated and the way the replacement value is computed.
103
+ Example: <tt>^{wlang/active-string}{...}</tt> (also known as 'encoding')
104
+ instantiates #1, looking for an encoder qualified name. Instantiates #2 in
105
+ the current dialect. Encode #2's instantiation using encoder found in (#1)
106
+ [context] Some rules allow code to be executed in the <em>hosting language</em> (the
107
+ definition explicitly announce it by putting <tt>wlang/hosted</tt> in the corresponding
108
+ block). When doing so, this code is in fact executed in a given context that
109
+ provides the execution semantics. Abstraction implemented in WLang::Parser::Context.
110
+ [hosting language] language (or framework) that executes wlang. In this case, it will be
111
+ <tt>ruby</tt>.
data/bin/wlang ADDED
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env ruby
2
+ #
3
+ # WLang: Code generation/Templating engine tool
4
+ # (see lib/wlang/wlang.rb for more information)
5
+ #
6
+ # Copyright (c) 2009 University of Louvain, Bernard & Louis Lambeau
7
+ # Released under a MIT or Ruby licence
8
+ #
9
+ require 'wlang/wlang_command'
10
+
11
+ begin
12
+ r = WLang::WLangCommand.new
13
+ r.run ARGV
14
+ rescue Interrupt => e
15
+ $stderr.puts
16
+ $stderr.puts "Interrupted"
17
+ raise e
18
+ rescue OptionParser::ParseError => e
19
+ $stderr.puts e.message
20
+ raise e
21
+ rescue => e
22
+ $stderr.puts e.message
23
+ raise e
24
+ end
data/doc/specification/about.rdoc ADDED
@@ -0,0 +1,61 @@
1
+ WLang is a a reusable and extensible <em>code generator</em>, also known as a
2
+ <em>templating engine</em>. Motivation for it can be found at http://www.revision-zero.org/wlang.
3
+ The current file is the reference of the tool.
4
+
5
+ === Topics
6
+
7
+ [Short overview] Probably the first section to read! Basic usage of _wlang_ is explained here and
8
+ pointers are given to continue your learning.
9
+ [Rulesets] Standard rulesets are specified. As most of them are included in standard dialects,
10
+ looking at standard rulesets is the quickest way to learn all of them at once.
11
+ [Dialects] Standard dialects are described. This page also provides useful cheatsheets of
12
+ available tags in standard dialects.
13
+ [Hosting language] Somewhat more tricky but powerful. The notion of hosting language is explained
14
+ more deeply. Implementing you own hosting language abstraction (advanced topic)
15
+ sometimes leads to cleaner and cross-implementation templates.
16
+ [Glossary] _wlang_ comes with a terminology, knowing it will make your reading easier.
17
+ [Symbols] If you plan to create your own tags, it can be useful to know what is allowed and what is
18
+ not. This pages covers this topic.
19
+
20
+ === About this document
21
+
22
+ This document is a simple .html file without external dependencies (embedded CSS and javascript).
23
+ As it contains several cheatsheets, you can simply save it on your harddisk without having to be
24
+ online to browse the documentation. It has been generated using _wlang_ itself using the following
25
+ command:
26
+
27
+ wlang specification.wtpl
28
+
29
+ The file 'specification.wtpl' is almost empty and other files next to it are all kept simple
30
+ and written in the most appropriate format for the task at hand (YAML for structured parts, RDoc for
31
+ text sections, sometimes YAML embedding short sentences writted in RDoc style, etc.).
32
+ One way to learn _wlang_ quickly is to download the source distribution and to look how this is made
33
+ possible ;-)
34
+
35
+ This reference document is under a {Creative Commons Licence 2.0}[http://creativecommons.org/licenses/by/2.0/be/]
36
+ contract. You can use it, redistribute it and modify it providing that you keep a reference to the
37
+ original licensor (namely, the 'University of Louvain' or 'Bernard and Louis Lambeau').
38
+
39
+ Enjoy _wlang_ !
40
+
41
+ === Distribution
42
+
43
+ - The reference implementation of _wlang_, implemented in Ruby, is freely available as a 'wlang' gem
44
+ (under MIT licence). <br/> Use <tt>'gem install wlang'</tt> to install it. For repository and
45
+ bug tracker visit us on {github}[http://github.com/blambeau/wlang]
46
+ - We don't have another implementation up to now. If you plan to start one in another language, let
47
+ us know!
48
+
49
+ === Authors
50
+
51
+ _wlang_ has been initially designed by Bernard and Louis Lambeau during the implementation of w@w, yet another
52
+ web framework (proof of concept). They are also maintainers of the reference implementation.
53
+
54
+ === Credits
55
+
56
+ This work is supported by the {department of computer science}[http://www.uclouvain.be/en-ingi.html] of the
57
+ {University of Louvain}[http://www.uclouvain.be/en-index.html] (EPL/INGI, Universite Catholique de Louvain,
58
+ UCL, Louvain-la-Neuve, Belgium).
59
+
60
+ This work was also partially supported by the Regional Government of Wallonia (ReQuest project, RW Conv. 315592
61
+ and GISELE project, RW Conv. 616425) and the MoVES project (PAI program of the Belgian government).
data/doc/specification/dialects.wtpl ADDED
File without changes
data/doc/specification/examples.rb ADDED
@@ -0,0 +1,3 @@
1
+ {"name" => "O'Neil",
2
+ "author" => "blambeau",
3
+ "authors" => ["blambeau", "llambeau", "ancailliau"]}
data/doc/specification/glossary.wtpl ADDED
@@ -0,0 +1,14 @@
1
+ <table class="glossary">
2
+ <tr>
3
+ <th class="term">term</th>
4
+ <th class="definition">definition</th>
5
+ <th class="example">example</th>
6
+ </tr>
7
+ *{spec/glossary as t}{
8
+ <tr>
9
+ <td><em>${t/term}</em></td>
10
+ <td>^{rdoc/nop}{+{t/definition}}</td>
11
+ <td style="font-size: 90%;">^{rdoc/nop}{+{t/example}}</td>
12
+ </tr>
13
+ }
14
+ </table>
data/doc/specification/hosting.rdoc ADDED
File without changes
data/doc/specification/overview.rdoc ADDED
@@ -0,0 +1,116 @@
1
+ === What is _wlang_ designed for?
2
+
3
+ _wlang_ helps you <b>generating code</b>, in a broad sense. It was originally the templating engine of
4
+ w@w, a proof-of-concept web framework. While more powerful than the original version, the <b>templating
5
+ engine</b> ability of _wlang_ has been kept unchanged. For this reason, generating html code with _wlang_
6
+ is probably a bit more mature than generating ruby, java or sql code, to take some examples of what
7
+ _wlang_ can do. It is the author opinion that _wlang_ will also become mature quiclky for these tasks
8
+ because of its foundations: <b>its engine is generic</b> (in a sense, _wlang_ does not really care about
9
+ what it generates) but is <b>fully and easily configurable</b>. Generation of html files is mature because
10
+ _wlang_ has been used a lot for such a job; thus its authors have acquired experience of what is
11
+ useful when generating simple as well as complex html files. This experience led us to a mature
12
+ configuration of the _wlang_ engine for generating html files, as the following paragraph illustrates
13
+ (for people interested in generating code in other languages than html, don't stop your reading here:
14
+ the paragraph immediately following contains information for you!)
15
+
16
+ Consider this file for example, which is completely self-contained. It consists of several parts, some
17
+ of them being structured - the tables for example - while others are not. It also embeds a complete CSS
18
+ stylesheet and some javascript functions. We have not written this file manually, nor do we maintain it
19
+ this way. In fact, this reference document is entirely generated by _wlang_ itself from separated parts
20
+ written mainly in yaml and rdoc files. Also, the cheatsheets given later contains a lot of examples. To
21
+ ensure that all of them are correct, we simply ask _wlang_ to compute them during generation (technically,
22
+ we say that <b>_wlang_ naturally allows metaprogramming</b>). Lastly, if _wlang_ can be used inside a web
23
+ framework, it can also be used as a standalone (commandline) tool for generating single files like this
24
+ one or multiple files, even if all of them are of different nature.
25
+
26
+ <b>Maybe you are looking for a code generator for another language than html</b> (which one does not really care,
27
+ unless really specific; we call it the <em>target language</em>)?
28
+ Don't be affraid by our previous words about _wlang_'s maturity: even in such a case, _wlang_ is your friend.
29
+ Start with an existing dialect (see later about dialects), which will provide basic utilities for starting and try
30
+ to identify common patterns when you use them. Then simply create special shortcuts that are more friendly to
31
+ use than combining several existing utils ... you are on the way of creating your own mature and reusable dialect
32
+ for that target language. In this case, don't forget to share it ...
33
+
34
+ === Template and instantiation
35
+
36
+ The _wlang_ grammar used to write a _template_ is generic and simple: every character stands for itself
37
+ (meaning that it is reproduced exactly when the template is instantiated) except <em>tags</em> (and
38
+ their associated <em>blocks</em>, enclosed between '{' and '}') that are replaced by what is called the
39
+ <em>replacement value</em>. Consider the following example:
40
+ <html>
41
+ <head>
42
+ <title>${title}</title>
43
+ </head>
44
+ <body>
45
+ <h1>Hello *{authors as who}{${who}}{, } !</h1>
46
+ </body>
47
+ </html>
48
+ Assume that we have some instantitation data through the following hash (or something similar, like
49
+ a YAML file):
50
+ {"title" => "Short overview of wlang", "authors" => ["blambeau", "llambeau", "ancailliau"]}
51
+ When instantiated this template will produce exactly the same html file except for special tags <tt>${title}</tt>
52
+ and <tt>*{whos as who}{${who}}{, }</tt> that will be replaced by <tt>'Short overview of wlang'</tt> and
53
+ <tt>'blambeau, llambeau, ancailliau'</tt>, respectively. A lot of tags is available, each of them being
54
+ designed for a specific task: inserting the value of a variable, iterating over collections, including another
55
+ file, dynamically loading instantiation data, etc. All of these things are commonly proposed by templating
56
+ engines and _wlang_ is one of them ... However, _wlang_ is a bit different as will quickly appear.
57
+
58
+ Indeed (and maybe surprisingly) _wlang_ can also behave really differently on the same template:
59
+ replacing <tt>${title}</tt> but not <tt>*{...}</tt> or the converse, or not replacing anything, or replacing
60
+ both tags but not <tt>${who}</tt>, etc. All of this is possible in _wlang_. The magic relies under the notion
61
+ of _dialect_, which you need to understand.
62
+
63
+ === Dialects and Rulesets
64
+
65
+ The notion of dialect drives the recognition of tags as well as their replacement during instantiation.
66
+ Dialects are what makes _wlang_ really powerful: if instantiated as being written in the <tt>wlang/xhtml</tt>
67
+ dialect, the template above will give the result mentionned previously. In contrast, if written in
68
+ <tt>wlang/dummy</tt> the template will be reproduced whitout any change (no tag replacement at all).
69
+ This behavior is not hardcoded; it results from the definition of wlang (standard) dialects: <tt>wlang/xhtml</tt>
70
+ define special meanings for <tt>${...}</tt> and <tt>*{...}{...}{...}</tt> while <tt>wlang/dummy</tt> does not.
71
+
72
+ The replacement of a given _tag_ during instantiation is computed by what we call the _rule_ attached to the tag
73
+ (keeping rules and tags as different concepts leads to another feature of _wlang_: you can reuse rule
74
+ implementations and attach them to other tags than those proposed). A dialect comes with a set of (tag, rule)
75
+ pairs that determine its replacement behavior. Such a set is called a _ruleset_; for easier reuse, standard
76
+ rulesets are already implemented. A dialect is a packaging of standard rulesets (and maybe implements specific
77
+ tag/rule pairs) designed for generating code in a given target language.
78
+
79
+ A complete _wlang_ implementation already provides standard dialects for common tasks: creating html pages,
80
+ building SQL queries, generating code in Ruby or in another language, etc. Each dialect comes with special
81
+ tags that are useful for the task at hand (a tag for back-quoting values is useful for creating SQL queries
82
+ but does not really makes sense
83
+ for generating an html page where, in contrast, a tag for encoding entities is probably welcome). Such an
84
+ implementation also allows you to extend standard dialects and to create your own dialect by implementing
85
+ specific tags and rules or by reusing existing ones. Lastlty, the dialect in used during instantiation can be changed
86
+ dynamically (_explicitly_, by using the <tt>%{dialect/qualified/name}{...}</tt> standard tag and _implicitly_,
87
+ when rules parse their blocks).
88
+
89
+ To learn more about standard dialects and reusable rules, read the 'Dialects' and 'Rulesets' pages of this
90
+ documentation.
91
+
92
+ === Grammar
93
+
94
+ The (abstract) _wlang_ grammar rules what forms a valid template. At first glance, this grammar does not depend on the
95
+ dialect that is used for instantiation. It is simple, but comes with some constraints that are explained below:
96
+ - block delimiters are '{' and '}' by default; _wlang_ can be configured to use '(' and ')' or '[' and ']' instead.
97
+ However, block <b>delimiters are template-specific</b>: only one kind of delimiters can be used inside the same template.
98
+ - block delimiters <b>must always be paired</b>, even when not used for delimiting blocks. If an opening or closing delimiter
99
+ is not paired, it must be escaped with a backslash, which will not be reproduced. If you want a backslash to appear before
100
+ a block delimiter in the instantiation result, use a double backslash.
101
+ - if a given tag has a special meaning in the current dialect and you don't want it to be replaced by _wlang_ you can escape
102
+ it with a backslash as well (the backslash will not be reproduced).
103
+ - some tags (precisely: some rules associated with tags) require multiple blocks (like <tt>*{...}{...}{...}</tt> in
104
+ <tt>wlang/xhtml</tt> for example, with the third block bein optional). In such a case no character is allowed between
105
+ the end of a block '}' and the start of the next one '{', not even spaces or
106
+ a carriage return. In other words, multiple blocks (that must be interpreted as such) must touch each others using '}{' precisely,
107
+ as ilustrated below. If a non-optional block is missing a parse error is raised by the _wlang_ implementation.
108
+
109
+ *{authors as who}{${who}}{, } -> blambeau, llambeau, ancailliau
110
+ *{authors as who}{${who}} {, } -> blambeaullambeauancailliau {, }
111
+ *{authors as who} {${who}}{, } -> parse error 1:18, missing block 2 in *{...}{...}
112
+
113
+ In addition to these constraints, dialects and the hosting language may impose restrictions on what can be put inside specific
114
+ blocks of tags/rules (for example, 'authors as who' is valid as first tag of <tt>*{...}{...}</tt> but not every string is, of course).
115
+ These constraints are not specific to the wlang grammar <em>per se</em> and are explained in the 'Rulesets', 'Dialects' and 'Hosting
116
+ language' pages of this document.
data/doc/specification/rulesets.wtpl ADDED
@@ -0,0 +1,87 @@
1
+ ^{rdoc/div}{%{wlang/dummy}{
2
+ Standard ruleset are designed to be reusable: including them in your own dialect is made
3
+ easy by a typical _wlang_ implementation. Some of them are also included by standard dialects.
4
+
5
+ === How to read this cheatsheet?
6
+
7
+ First of all, focus on the examples; they are written to let you learn _wlang_ quickly and
8
+ deeply. Some of them are a bit difficult to understand but they are representative of _wlang_
9
+ powerfulness (don't be affraid: in practice, some constructions are never used). Don't forget
10
+ that the <tt>wlang/dummy</tt> dialect does not recognize any tag. We also assume instantiation
11
+ data to be the following hash:
12
+ {"name" => "O'Neil",
13
+ "author" => "blambeau"
14
+ "authors" => ["blambeau", "llambeau", "ancailliau"]}
15
+
16
+ Moreover, the dialect column in the examples is important; _wlang_ behaves differently
17
+ in different dialects. When the dialect does not care, we use <tt>wlang/*</tt> which means
18
+ 'in any dialect that includes this ruleset'.
19
+
20
+ Next, certain rule definitions are given as shortcuts for longer expressions, involving other tags.
21
+ This is somewhat representative of _wlang_ usage, even if these rules are not actually implemented
22
+ this way (mainly for efficiency concerns). Once again, understanding shortcuts will help you
23
+ mastering wlang! In definitions (textual as well as shortcuts), we use #1, #2, and #3 to refer to
24
+ the content of the blocks. Those identifiers are not real _wlang_ constructs, but are only used here for
25
+ easier explanations (for those who know this kind of vocabulary: they are part of the meta-language,
26
+ not the language <em>per se</em>).
27
+
28
+ Lastly, dialect names that appear in rule signatures are to be interpreted as an implicit dialect
29
+ modulation: the corresponding block (often the first one) is not instantiated in the current dialect
30
+ but in the one specified by the signature. In contrast, when we use '...' it means that the
31
+ corresponding block is simply instantiated in the current dialect. Implicit dialect modulation is
32
+ in fact natural: if a block expects an uri for example, the easiest way is to give
33
+ it exactly: <tt><<{a/file/to/include.txt}</tt>. But you can even compute it using _wlang_, as illustrated
34
+ by the example below. In complex situations you will probably be happy to use a dialect that helps you
35
+ doing so (think at all blocks that expect an expression in the hosting language, for example)!
36
+
37
+ # Concatenates all files of the 'files' array variable
38
+ *{files as f}{<<{+{f}}}
39
+
40
+ }}
41
+ <<={examples.rb as examples}
42
+ *{spec/rulesets as ruleset}{
43
+ <h3 id="${ruleset/name}">${ruleset/name}</h3>
44
+ ^{rdoc/div}{${ruleset/description}}
45
+ <table class="ruleset">
46
+ <tr>
47
+ <th class="signature">signature</th>
48
+ <th class="name">name</th>
49
+ <th class="definition">definition</th>
50
+ </tr>
51
+ *{ruleset/rules as rule}{
52
+ <tr>
53
+ <td class="signature"><tt>${rule/signature}</tt></td>
54
+ <td class="name">+{rule/name}</td>
55
+ <td class="definition">^{rdoc/nop}{+{rule/definition}}</td>
56
+ </tr>
57
+ }
58
+ </table>
59
+
60
+ ?{ruleset/examples}{
61
+ <br/>
62
+ <h4>Examples:</h4>
63
+ <table class="examples">
64
+ <tr>
65
+ <th>dialect</th>
66
+ <th>wlang expression</th>
67
+ <th>replacement value</th>
68
+ </tr>
69
+ *{ruleset/examples as example}{
70
+ <tr>
71
+ <td class="dialect">
72
+ <tt>${example[0]}</tt>
73
+ </td>
74
+ <td class="expression">
75
+ <tt>${example[1]}</tt>
76
+ </td>
77
+ <td class="replacement">
78
+ #={dialect}{?{example[0] == "wlang/*"}{wlang/xhtml}{+{example[0]}}}{
79
+ <tt>%!{+{dialect} using examples}{+{example[1]}}</tt>
80
+ }
81
+ </td>
82
+ </tr>
83
+ }
84
+ </table>
85
+ <div style="clear: both;"></div>
86
+ }
87
+ }