RubyGems - wlang - Versions diffs - 0.8.4 - Mend

wlang 0.8.4

Files changed (73) hide show

data/LICENCE.rdoc +25 -0
data/README.rdoc +111 -0
data/bin/wlang +24 -0
data/doc/specification/about.rdoc +61 -0
data/doc/specification/dialects.wtpl +0 -0
data/doc/specification/examples.rb +3 -0
data/doc/specification/glossary.wtpl +14 -0
data/doc/specification/hosting.rdoc +0 -0
data/doc/specification/overview.rdoc +116 -0
data/doc/specification/rulesets.wtpl +87 -0
data/doc/specification/specification.css +52 -0
data/doc/specification/specification.html +1361 -0
data/doc/specification/specification.js +8 -0
data/doc/specification/specification.wtpl +41 -0
data/doc/specification/specification.yml +430 -0
data/doc/specification/symbols.wtpl +16 -0
data/lib/wlang.rb +186 -0
data/lib/wlang/basic_object.rb +19 -0
data/lib/wlang/dialect.rb +230 -0
data/lib/wlang/dialect_dsl.rb +136 -0
data/lib/wlang/dialect_loader.rb +69 -0
data/lib/wlang/dialects/coderay_dialect.rb +35 -0
data/lib/wlang/dialects/plain_text_dialect.rb +75 -0
data/lib/wlang/dialects/rdoc_dialect.rb +33 -0
data/lib/wlang/dialects/ruby_dialect.rb +35 -0
data/lib/wlang/dialects/sql_dialect.rb +38 -0
data/lib/wlang/dialects/standard_dialects.rb +113 -0
data/lib/wlang/dialects/xhtml_dialect.rb +40 -0
data/lib/wlang/encoder.rb +66 -0
data/lib/wlang/encoder_set.rb +117 -0
data/lib/wlang/errors.rb +37 -0
data/lib/wlang/intelligent_buffer.rb +94 -0
data/lib/wlang/parser.rb +251 -0
data/lib/wlang/parser_context.rb +146 -0
data/lib/wlang/ruby_extensions.rb +21 -0
data/lib/wlang/rule.rb +66 -0
data/lib/wlang/rule_set.rb +93 -0
data/lib/wlang/rulesets/basic_ruleset.rb +75 -0
data/lib/wlang/rulesets/buffering_ruleset.rb +103 -0
data/lib/wlang/rulesets/context_ruleset.rb +115 -0
data/lib/wlang/rulesets/encoding_ruleset.rb +73 -0
data/lib/wlang/rulesets/imperative_ruleset.rb +132 -0
data/lib/wlang/rulesets/ruleset_utils.rb +296 -0
data/lib/wlang/template.rb +79 -0
data/lib/wlang/wlang_command.rb +54 -0
data/lib/wlang/wlang_command_options.rb +158 -0
data/test/sandbox.rb +1 -0
data/test/test_all.rb +8 -0
data/test/wlang/anagram_bugs_test.rb +111 -0
data/test/wlang/basic_ruleset_test.rb +52 -0
data/test/wlang/buffering_ruleset_test.rb +102 -0
data/test/wlang/buffering_template1.wtpl +1 -0
data/test/wlang/buffering_template2.wtpl +1 -0
data/test/wlang/buffering_template3.wtpl +1 -0
data/test/wlang/buffering_template4.wtpl +1 -0
data/test/wlang/buffering_template5.wtpl +1 -0
data/test/wlang/context_ruleset_test.rb +32 -0
data/test/wlang/data.rb +3 -0
data/test/wlang/encoder_set_test.rb +42 -0
data/test/wlang/imperative_ruleset_test.rb +107 -0
data/test/wlang/intelligent_buffer_test.rb +194 -0
data/test/wlang/othersymbols_test.rb +16 -0
data/test/wlang/parser_context_test.rb +29 -0
data/test/wlang/parser_test.rb +89 -0
data/test/wlang/plain_text_dialect_test.rb +21 -0
data/test/wlang/ruby_dialect_test.rb +100 -0
data/test/wlang/ruby_expected.rb +3 -0
data/test/wlang/ruby_template.wrb +3 -0
data/test/wlang/ruleset_utils_test.rb +245 -0
data/test/wlang/specification_examples_test.rb +52 -0
data/test/wlang/test_utils.rb +25 -0
data/test/wlang/wlang_test.rb +80 -0
metadata +136 -0

data/doc/specification/specification.js ADDED Viewed

@@ -0,0 +1,8 @@
+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;
+}

data/doc/specification/specification.wtpl ADDED Viewed

@@ -0,0 +1,41 @@
+<<={specification.yml as spec}
+<!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>${spec/title} (version ${spec/version})</title>
+    <style type="text/css">
+      <<{specification.css}
+    </style>
+	  <script type="text/javascript" language="JavaScript"><!--
+	    <<{specification.js}
+	  //--></script>
+  </head>
+  <body onload="show('about')">
+    <h1 id="title">${spec/title} (version ${spec/version})</h1>
+    <ul id="tabs">
+      *{spec["sections"].reverse as section}{
+        <li id="+{section/id}focus" onclick="show('{section/id}')">${section/name}</li>
+      }
+    </ul>
+    <div class="clear"></div>
+    *{spec/sections as section}{
+	  <div id="{section/id}" style="display: none;">
+	    <div class="header">
+		  <h2>${section/name}</h2>
+		  ?{section/links}{
+		    <ul class="links">
+		      *{+{section/links} as link}{<li><a href="#${link/name}">${link/name}</a></li>}
+		    </ul>
+		  }
+		  <div class="clear"></div>
+		</div>
+		?{/rdoc$/ =~ "{section/file}"}{
+		  ^{rdoc/div}{<<{+{section/file}}}
+		}{
+		  <<+{+{section/file} with spec: spec}
+		}
+      </div>
+    }
+  </body>
+</html>

data/doc/specification/specification.yml ADDED Viewed

@@ -0,0 +1,430 @@
+---
+title: WLang
+version: 0.8.4
+sections:
+  - id: about
+    name: About
+    file: about.rdoc
+  - id: overview
+    name: Overview
+    file: overview.rdoc
+  - id: rulesets
+    name: Rulesets
+    file: rulesets.wtpl
+    links: 'spec["rulesets"].reverse'
+  - id: dialects
+    name: Dialects
+    file: dialects.wtpl
+  - id: hosting
+    name: Hosting language
+    file: hosting.rdoc
+  - id: glossary
+    name: Glossary
+    file: glossary.wtpl
+  - id: symbols
+    name: Tag symbols
+    file: symbols.wtpl
+glossary:
+  - term: template
+    definition: |-
+      Source code respecting the wlang grammar, and attached to a given <em>wlang
+      dialect</em>.
+    example: |-
+      <tt>Hello ${name}</tt>
+  - term: dialect
+    definition: |-
+      Basically, <em>dialect</em> is used as a synonym for (programming) <em>language</em>.
+      However _wlang_ uses a tree of dialects, allowing specializations: <tt>sql/sybase</tt>
+      for example is the qualified name of a sub-dialect 'sybase' of the 'sql' dialect.
+      Dialects come with associated _encoders_.
+    example: |-
+      <tt>sql/sybase</tt>
+  - term: wlang dialect
+    definition: |-
+      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 _wlang_ 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 _tags_
+      and associated _rules_.
+    example: |-
+      <tt>wlang/xhtml</tt>
+  - term: encoder
+    definition: |-
+      Text transformation (algorithm) applying some encoding conventions of a portion
+      of a the target language generated by a dialect. HTML entities-encoding, SQL's back-quoting
+      are examples of encoders. Encoders are accessible through their qualified name (dialect/encoder).
+    example: |-
+      <tt>xhtml/entities-encoding</tt><br/><tt>sql/single-quoting</tt>
+  - term: ruleset
+    definition: |-
+      Reusable set of <em>tags</em> associated to <em>rule</em>s.
+    example: |-
+      <tt>Imperative ruleset</tt><br/><tt>Encoding rulset</tt>
+  - term: wlang tag
+    definition: |-
+      Special tags in the template, starting with wlang symbols and a number of wlang
+      blocks. A tag is associated with a wlang rule.
+    example: |-
+      <tt>${...}</tt><br/><tt>?{...}{...}{...}</tt>
+  - term: rule
+    definition: |-
+      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.
+    example: |-
+      <tt>^{wlang/active-string}{...}</tt><br/>
+      Instantiates #1, looking for an encoder qualified name. Instantiates #2 in
+      the current dialect. Encode #2's instantiation using encoder found in (#1)
+      and return the result as replacement value.
+  - term: context
+    definition: |-
+      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.
+  - term: hosting language
+    definition: |-
+      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 !{...} for example). See the 'Hosting language'
+      section to learn more.
+    example: |-
+      ruby
+rulesets:
+  - name: Basic
+    description: |-
+      The Basic ruleset is commonly installed on any dialect and provides access to _wlang_
+      foundations inside your template: requesting the hosting language to execute some expression,
+      changing the current dialect and encoding text.
+    examples:
+      - ["wlang/active-string", "Hello !{name}",                       "Hello O'Neil"]
+      - ["wlang/active-string", "Hello %{wlang/dummy}{!{name}}",       "Hello !{name}"]
+      - ["wlang/dummy",         "Hello %{wlang/dummy}{!{name}}",       "Hello %{wlang/dummy}{!{name}}"]
+      - ["wlang/active-string", "Hello ^{plain-text/upcase}{${name}}", "Hello O'NEIL"]
+    rules:
+      # !{wlang/hosted}
+      - name:      "execution"
+        symbol:    "!"
+        signature: "!{wlang/hosted}"
+        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.
+      # %{wlang/active-string}{...}
+      - name:      "modulation"
+        symbol:    "%"
+        signature: "%{wlang/active-string}{...}"
+        definition: |-
+          Instantiates #1, looking for a dialect qualified name. Instantiates #2
+          according to the rules defined by that dialect and returns the #2's
+          instantiation as replacement value.
+      # ^{wlang/active-string}{...}
+      - name:      "encoding"
+        symbol:    "^"
+        signature: "^{wlang/active-string}{...}"
+        definition: |-
+          Instantiates #1, looking for an encoder qualified name. Instantiates #2 in
+          the current dialect. Encode #2's instantiation using encoder found in (#1) and
+          returns encoding as replacement value.
+      # %!{wlang/active-string using ... with ...}{...}
+      - name:      "recursive-application"
+        symbol:    "%!"
+        signature: "%!{wlang/active-string <using>? <with>?}{...}"
+        definition: |-
+          Instantiates #1, looking for a dialect qualified name. Instantiates #2
+          in the current dialect. Instantiates #2's instantiation in the dialect found
+          in #1, using context installed by 'using ...' and 'with ...'. Returns this
+          instantiation as replacement value (this really advanced rule allows
+          metaprogramming).
+      # ${wlang/hosted}
+      - name:      "injection"
+        symbol:    "$"
+        signature: "${wlang/hosted}"
+        definition: Same semantics as execution (intended to be overrided).
+      # +{wlang/hosted}
+      - name:      "inclusion"
+        symbol:    "+"
+        signature: "+{wlang/hosted}"
+        definition: Same semantics as execution (intended to be overrided).
+  - name: Encoding
+    description: |-
+      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't depend on the effective
+      dialect. _wlang_ hides language and vendors differences!
+    examples:
+      - ["wlang/xhtml", "Hello &{name}",                       "Hello name"]
+      - ["wlang/xhtml", "Hello &{<script>}",                   "Hello &lt;script&gt;"]
+      - ["wlang/xhtml", "Hello &;{<script>}",                  "Hello &lt;script&gt;"]
+      - ["wlang/ruby",  "puts 'Hello &'{name}'",               "puts 'Hello name'"]
+      - ["wlang/ruby",  "puts 'Hello &'{!{name}}'",            "puts 'Hello O\'Neil'"]
+      - ["wlang/ruby",  "puts 'Hello ' << '{name}'",           "puts 'Hello ' << 'O\'Neil'"]
+      - ["wlang/sql",   "... WHERE name='{name}'",             "... WHERE name='O\'Neil'"]
+      - ["wlang/sql/sybase",  "... WHERE name='{name}'",       "... WHERE name='O''Neil'"]
+    rules:
+      # &{...}
+      - name:       "main-encoding"
+        symbol:     "&"
+        signature:  "&{...}"
+        definition: "<tt>^{+{@parser.current_dialect}/main-encoding}{#1}</tt>"
+      # &;{...}
+      - name:       "entities-encoding"
+        symbol:     "&;"
+        signature:  "&;{...}"
+        definition: "<tt>^{+{@parser.current_dialect}/entities-encoding}{#1}</tt>"
+      # &'{...}
+      - name:       "single-quoting"
+        symbol:     "&'"
+        signature:  "&'{...}"
+        definition: "<tt>^{+{@parser.current_dialect}/single-quoting}{#1}</tt>"
+      # &;{...}
+      - name:       "double-quoting"
+        symbol:     '&"'
+        signature:  '&"{...}'
+        definition: "<tt>^{+{@parser.current_dialect}/double-quoting}{#1}</tt>"
+      # ${wlang/hosted}
+      - name:      "injection"
+        symbol:    "$"
+        signature: "${wlang/hosted}"
+        definition: "<tt>&{+{#1}}</tt>"
+      # '{wlang/hosted}
+      - name:      "single-quoted"
+        symbol:    "'"
+        signature: "'{wlang/hosted}"
+        definition: |-
+          <tt>'&'{+{#1}}</tt> (first single quote is kept in the result)
+      # "{wlang/hosted}
+      - name:      "double-quoted"
+        symbol:    '"'
+        signature: '"{wlang/hosted}'
+        definition: |-
+          <tt>"&"{+{#1}}</tt> (first double quote is kept in the result)
+  - name: Imperative
+    description: |-
+      Instantiating conditionally and iterating collection elements are common code generation tasks.
+      The Imperative dialect provides these features.
+    examples:
+      - ["wlang/*", '?{true}{then}{else}',                         'then']
+      - ["wlang/*", '?{/th/ =~ "not tat"}{then}{else}',            'else']
+      - ["wlang/*", '?{authors.include? "blambeau"}{yes}{no}',    'yes']
+      - ["wlang/*", '[*{authors as a}{"{a}"}{, }]', '["blambeau", "llambeau", "ancailliau"]']
+    rules:
+      # ?{wlang/hosted}{...}{...}
+      - name:      "conditional<br/>(third block is optional)"
+        symbol:    "?"
+        signature: "?{wlang/hosted}{...}{...}"
+        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.
+      # *{wlang/hosted as x}{...}{...}
+      - name:      "enumeration<br/>(third block is optional)"
+        symbol:    "*"
+        signature: "*{wlang/hosted <as x>?}{...}{...}"
+        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.
+  - name: Context
+    description: |-
+      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 'saving previous instantiations' in
+      scope variables...
+    examples:
+      - ["wlang/*", '={name as n}{Hello +{n}}',                      "Hello O'Neil"]
+      - ["wlang/*", '={name as n}Hello +{n}',                        "Hello O'Neil"]
+      - ["wlang/*", '#={name}{blambeau}{Hello +{name}} and +{name}', "Hello blambeau and O'Neil"]
+      - ["wlang/*", '#={name}{blambeau}Hello +{name} and +{name}',   "Hello blambeau and blambeau"]
+      - ["wlang/*", '={author as name}{Hello +{name}} and +{name}', "Hello blambeau and O'Neil"]
+      - ["wlang/*", '={author as name}Hello +{name} and +{name}',   "Hello blambeau and blambeau"]
+      - ["wlang/*", '%={wlang/dummy as hello}{Hello +{name}}{+{hello}}', "Hello +{name}"]
+      - ["wlang/*", '^={plain-text/upcase as name}{+{author}}{Hello +{name}} and +{name}', "Hello BLAMBEAU and O'Neil"]
+      - ["wlang/*", '^={plain-text/upcase as name}{+{author}}Hello +{name} and +{name}', "Hello BLAMBEAU and BLAMBEAU"]
+    rules:
+      # ={wlang/hosted as x}{...}
+      - name:      "assignment<br/>(second block is optional)"
+        symbol:    "="
+        signature: "={wlang/hosted <as x>}{...}"
+        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
+            'x' being bound to evaluation result. Otherwise, branches the current scope for
+            the second block instantiation only and bind 'x' the same way (i.e. x will not be
+            available outside the second block). Returns an empty string as replacement value.
+      # %={wlang/active-string as x}{...}{...}
+      - name:      "modulo-assignment<br/>(third block is optional)"
+        symbol:    "%="
+        signature: "%={wlang/active-string <as x>}{...}{...}"
+        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 'x' being bound to #2's instantiation. Otherwise, branches the current
+            scope for the third block instantiation only and binds 'x' the same way (i.e. x will
+            not be available outside the third block). Returns an empty string as replacement
+            value.
+      # #={wlang/active-string}{...}{...}
+      - name:      "block-assignment<br/>(third block is optional)"
+        symbol:    "="
+        signature: "#={wlang/active-string <as x>}{...}{...}"
+        definition: |-
+          <tt>%={+{@parser.current_dialect} as #1}{#2}{#3}</tt>
+      # ^={wlang/active-string as x}{...}{...}
+      - name:      "encoding-assignment<br/>(third block is optional)"
+        symbol:    "^="
+        signature: "^={wlang/active-string <as x>}{...}{...}"
+        definition: |-
+          <tt>%={+{@parser.current_dialect} as x}{^{#1}{#2}}{#3}</tt>
+  - name: Buffering
+    description: |-
+      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.
+    rules:
+      # <<{wlang/uri}
+      - name:      "input"
+        symbol:    "<<"
+        signature: "<<{wlang/uri}"
+        definition: |-
+          Instantiates #1, looking for an uri. Returns the text content of the found
+          uri (#1) as replacement value.
+      # >>{wlang/uri}
+      - name:      "output"
+        symbol:    ">>"
+        signature: ">>{wlang/uri}{...}"
+        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.
+      # <<={wlang/uri as x}{...}
+      - name:      "data-assignment"
+        symbol:    "<<="
+        signature: "<<={wlang/uri <as x>}{...}"
+        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 'x' being bound to the data. Otherwise, branches the current scope for the second
+          block instantiation only and binds 'x' the same way (i.e. x will not be available outside
+          the second block). Returns an empty string as replacement value.
+      # <<+{wlang/uri with ...}
+      - name:      "input-inclusion"
+        symbol:    "<<+"
+        signature: "<<+{wlang/uri <using>? <with>?}"
+        definition: |-
+          Instantiates #1, looking for an uri. Instantiates the _wlang_ template at this location
+          (the dialect is infered from the file extension) in a fresh new scope built from the _with_
+          expression. Returns this instantiation as replacement value.
+symbols:
+  - name: exclamation mark
+    symbol: '!'
+    meaning: execution
+    remark: should never be overrided as single
+  - name: 'caret/circumflex'
+    symbol: '^'
+    meaning: explicit encoding
+    remark: should never be overrided as single
+  - name: percent
+    symbol: '%'
+    meaning: modulation
+    remark: should never be overrided as single
+  - name: double quote
+    symbol: '"'
+    meaning: double-quoting
+  - name: dollar
+    symbol: '$'
+    meaning: 'main-encoding'
+  - name: ampersand
+    symbol: '&'
+    meaning: encoding
+  - name: single quote
+    symbol: "'"
+    meaning: single-quoting
+  - name: asterisk
+    symbol: '*'
+    meaning: iteration
+  - name: plus
+    symbol: '+'
+    meaning: inclusion
+  - name: question mark
+    symbol: '?'
+    meaning: condition
+  - name: at symbol
+    symbol: '@'
+    meaning: linking
+  - name: tilde
+    symbol: '~'
+    meaning: matching
+  - name: number sign
+    symbol: '#'
+  - name: comma
+    symbol: ','
+  - name: minus (dash)
+    symbol: '-'
+  - name: dot
+    symbol: '.'
+  - name: forward slash
+    symbol: '/'
+  - name: colon
+    symbol: ':'
+  - name: 'semi-colon'
+    symbol: ';'
+  - name: equal sign
+    symbol: '='
+  - name: less than
+    symbol: '<'
+  - name: greater than
+    symbol: '>'
+  - name: vertical bar
+    symbol: '|'
+  - name: underscore
+    symbol: '_'
+    remark: cannot be used as tag symbol; reserved for escaping in future versions
+  - name: back slash
+    symbol: \
+    remark: cannot be used as tag symbol; reserved for escaping in current version
+  - name: left parenthesis
+    symbol: '('
+    remark: cannot be used as tag symbol; reserved for block delimiter
+  - name: right parenthesis
+    symbol: ')'
+    remark: cannot be used as tag symbol; reserved for block delimiter
+  - name: left bracket
+    symbol: '['
+    remark: cannot be used as tag symbol; reserved for block delimiter
+  - name: right bracket
+    symbol: ']'
+    remark: cannot be used as tag symbol; reserved for block delimiter
+  - name: left brace
+    symbol: '{'
+    remark: cannot be used as tag symbol; reserved for block delimiter
+  - name: right brace
+    symbol: '}'
+    remark: cannot be used as tag symbol; reserved for block delimiter