wlang 0.8.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (73) hide show
  1. data/LICENCE.rdoc +25 -0
  2. data/README.rdoc +111 -0
  3. data/bin/wlang +24 -0
  4. data/doc/specification/about.rdoc +61 -0
  5. data/doc/specification/dialects.wtpl +0 -0
  6. data/doc/specification/examples.rb +3 -0
  7. data/doc/specification/glossary.wtpl +14 -0
  8. data/doc/specification/hosting.rdoc +0 -0
  9. data/doc/specification/overview.rdoc +116 -0
  10. data/doc/specification/rulesets.wtpl +87 -0
  11. data/doc/specification/specification.css +52 -0
  12. data/doc/specification/specification.html +1361 -0
  13. data/doc/specification/specification.js +8 -0
  14. data/doc/specification/specification.wtpl +41 -0
  15. data/doc/specification/specification.yml +430 -0
  16. data/doc/specification/symbols.wtpl +16 -0
  17. data/lib/wlang.rb +186 -0
  18. data/lib/wlang/basic_object.rb +19 -0
  19. data/lib/wlang/dialect.rb +230 -0
  20. data/lib/wlang/dialect_dsl.rb +136 -0
  21. data/lib/wlang/dialect_loader.rb +69 -0
  22. data/lib/wlang/dialects/coderay_dialect.rb +35 -0
  23. data/lib/wlang/dialects/plain_text_dialect.rb +75 -0
  24. data/lib/wlang/dialects/rdoc_dialect.rb +33 -0
  25. data/lib/wlang/dialects/ruby_dialect.rb +35 -0
  26. data/lib/wlang/dialects/sql_dialect.rb +38 -0
  27. data/lib/wlang/dialects/standard_dialects.rb +113 -0
  28. data/lib/wlang/dialects/xhtml_dialect.rb +40 -0
  29. data/lib/wlang/encoder.rb +66 -0
  30. data/lib/wlang/encoder_set.rb +117 -0
  31. data/lib/wlang/errors.rb +37 -0
  32. data/lib/wlang/intelligent_buffer.rb +94 -0
  33. data/lib/wlang/parser.rb +251 -0
  34. data/lib/wlang/parser_context.rb +146 -0
  35. data/lib/wlang/ruby_extensions.rb +21 -0
  36. data/lib/wlang/rule.rb +66 -0
  37. data/lib/wlang/rule_set.rb +93 -0
  38. data/lib/wlang/rulesets/basic_ruleset.rb +75 -0
  39. data/lib/wlang/rulesets/buffering_ruleset.rb +103 -0
  40. data/lib/wlang/rulesets/context_ruleset.rb +115 -0
  41. data/lib/wlang/rulesets/encoding_ruleset.rb +73 -0
  42. data/lib/wlang/rulesets/imperative_ruleset.rb +132 -0
  43. data/lib/wlang/rulesets/ruleset_utils.rb +296 -0
  44. data/lib/wlang/template.rb +79 -0
  45. data/lib/wlang/wlang_command.rb +54 -0
  46. data/lib/wlang/wlang_command_options.rb +158 -0
  47. data/test/sandbox.rb +1 -0
  48. data/test/test_all.rb +8 -0
  49. data/test/wlang/anagram_bugs_test.rb +111 -0
  50. data/test/wlang/basic_ruleset_test.rb +52 -0
  51. data/test/wlang/buffering_ruleset_test.rb +102 -0
  52. data/test/wlang/buffering_template1.wtpl +1 -0
  53. data/test/wlang/buffering_template2.wtpl +1 -0
  54. data/test/wlang/buffering_template3.wtpl +1 -0
  55. data/test/wlang/buffering_template4.wtpl +1 -0
  56. data/test/wlang/buffering_template5.wtpl +1 -0
  57. data/test/wlang/context_ruleset_test.rb +32 -0
  58. data/test/wlang/data.rb +3 -0
  59. data/test/wlang/encoder_set_test.rb +42 -0
  60. data/test/wlang/imperative_ruleset_test.rb +107 -0
  61. data/test/wlang/intelligent_buffer_test.rb +194 -0
  62. data/test/wlang/othersymbols_test.rb +16 -0
  63. data/test/wlang/parser_context_test.rb +29 -0
  64. data/test/wlang/parser_test.rb +89 -0
  65. data/test/wlang/plain_text_dialect_test.rb +21 -0
  66. data/test/wlang/ruby_dialect_test.rb +100 -0
  67. data/test/wlang/ruby_expected.rb +3 -0
  68. data/test/wlang/ruby_template.wrb +3 -0
  69. data/test/wlang/ruleset_utils_test.rb +245 -0
  70. data/test/wlang/specification_examples_test.rb +52 -0
  71. data/test/wlang/test_utils.rb +25 -0
  72. data/test/wlang/wlang_test.rb +80 -0
  73. metadata +136 -0
data/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
+ }