wlang 0.10.2 → 2.0.0.beta

data/CHANGELOG.md

@@ -1,123 +1,5 @@
-# Version 0.10.2 / 2011-02-25
+# 2.0.0 / FIX ME
 
-* Bug fixes
+* Enhancements
 
-  * Fixed a bug that led to applying dialect post-transformation too many times in multi 
-    block syntaxes. Post-transformation rules related strategies are now:
-      - Parser#instantiate now takes an optional boolean argument to set/unset dialect
-        post transformation (defaults to true, for backward compatibility). 
-      - Invoking Template.instantiate always invoke Parser#instantiate(true)
-      - Buffering's <<+{...} always apply post-transformation as well
-      - Otherwise, post-transformation is only applied when the dialect explicitely changes
-        when invoking Parser#parse and Parser#parse_block
-
-* Other enhancements
-
-  * Added a bluecloth/xhtml dialect and encoder.
-
-# Version 0.10.1 / 2011-01-17
-
-* Bug fixes
-
-  * Fixed a bug when using multi-block syntaxes with another delimiter than braces.
-
-* Other enhancements
-
-  * WLang source code follows the ruby.noe template that comes bundled with Noe
-
-# Version 0.10.0 / 2011-01-14
-
-* New features
-
-  * Introduced a wlang/hosted language which parses blocks as actually described in the specification
-  * Introduced a semantics +{...} in wlang/ruby that prints literals.
-  * wlang/ruby now includes the Buffering ruleset
-  * Introduced a wlang/active-text dialect which includes Basic, Imperative, Buffering and Context rulesets.
-  * Introduced a wlang/yaml dialect with special inclusion +{...} operator 
-
-* Broken features and APIs
-
-  * Due to the wlang/ruby <-> wlang/hosted changes and the fact that wlang/ruby now includes the 
-    Buffering ruleset, users that generate ruby (a few) may have broken templates and should probably
-    be pessimist and require wlang 0.9.x
-  * For the same reason, users that make complex wlang meta-constructions ala +{+{...}} could observe
-    problems due to the change of +{...} in wlang/ruby. The wlang/hosted dialect is introduced to limit
-    such problems, but not encountering them is not guaranteed.
-
-* Other enhancements
-
-  * Moved to rspec 2.4.0
-  * Moved from rdoc to yard for generating the documentation
-  * README, CHANGELOG and LICENCE are now in Mardown instead of rdoc
-
-# Version 0.9.2
-
-* New features (by order of importance)
-
-  * Implements main transformer on dialects
-  * Makes coderay encoders available without options using a bit of meta programming
-  * System-local absolute paths (i.e. starting with '/') are recognized by buffer rulesets
-
-# Version 0.9.1
-
-* Bug fixes
-
-  * #307, about HashScope.has_key? which returned nil instead of false in some situations
-
-* Broken features and APIs (by order of importance)
-
-  * HostedLanguage::DSL is strictly private and should be reopened. Methods added to this class
-    will never be available in templates. Use HostedLanguage.variable_missing instead. 
-  * ::WLang::BasicObject has been removed. HostedLanguage::DSL implements its own strategy, which
-    is spec tested in test/spec/basic_object.spec
-
-* New features (by order of importance)
-
-  * WLang does not requires the rdoc gem by default
-  * A new encoder redcloth/xhtml allows using Textile markups easily
-  * The wlang/xhtml dialect provides a tag helper for links @{...}{...}
-  * The parser class returns friendly messages when a rule is ill-implemented
-
-# Version 0.9.0
-
-* Broken features and APIs (by order of importance)
-
-  * Major broken API in WLang.instantiate and WLang.file_instantiate which do not allow passing
-    buffers anymore
-  * Hash are not methodized by default anymore (major broken feature with 0.8.x versions)
-  * Expressions 'a la' PHP w@w (sections/.../.../id) are not supported anymore
-  * The default hosted language raises a WLang::UndefinedVariableError when a variable cannot be
-    found in the current template scope (0.8.x versions returned nil in this case)
-  * Template.initialize does not take a default context anymore
-  * WLang::Parser.context_xxx do not exist anymore. Use branch(...) instead
-  * WLang::Parser::Context removed, and WLang::HashScope introduced
-  * WLang::Parser instance variables are all made protected
-
-* New features (by order of importance)
-
-  * WLang::HostingLanguage introduced, with a default one for Ruby. The hosting language
-    is the way to provide a main scope, accessible to all templates at once.
-  * WLang::HostingLanguage is not sensitive to the difference between symbol keys and strings
-  * Buffering and Context rulesets now branch the current parser instead of creating a new one
-  * WLang::Error and subclasses propose a backtrace information
-  * WLang::Parser refactored to encapsulate the whole state in another class (WLang::Parser::State)
-  * WLang facade has been made much more robust as it now checks all its arguments.
-  * WLang::dialect may now be used to ensure dialect instances from both Dialect args and qualified names.
-  * Introduction of WLang.template and WLang.file_template
-  * plain-text dialect proposes new camel-based encoders
-  * wlang/active-string dialect has the imperative rule set included
-  * sql dialect has been added
-  * ruby dialect proposes a method-case encoder
-
-# Version 0.8.5
-
-* Enhances error messages a lot
-* Some bug fixes for ruby 0.8.7
-
-# Version 0.8.4
-
-* Migration from svn.chefbe.net to github.com
-
-# Version 0.8.0
-
-* First public version
+  * Birthday!

data/Gemfile

@@ -1,2 +1,24 @@
 source 'http://rubygems.org'
-gemspec :name => "wlang"
+
+group :runtime do
+  gem "citrus", "~> 2.4.1"
+  gem "temple", "~> 0.4.0"
+  gem "backports", "~> 2.6.1", :platforms => ["ruby_18", "mri_18", "mingw_18", 'jruby']
+  gem "quickl", "~> 0.4.3"
+  gem "awesome_print", "~> 1.0.2"
+end
+
+group :profiling do
+  gem "ruby-prof", "~> 0.11.2"
+  gem "mustache", "~> 0.99.4"
+  #gem "viiite", :git => "git://github.com/blambeau/viiite.git"
+end
+
+group :development do
+  gem "rake", "~> 0.9.2"
+  gem "bundler", "~> 1.0"
+  gem "rspec", "~> 2.10.0"
+  gem "epath", "~> 0.1.0"
+  gem "yard", "~> 0.8.1"
+  gem "bluecloth", "~> 2.2.0"
+end

data/Gemfile.lock

@@ -1,37 +1,41 @@
-PATH
-  remote: .
-  specs:
-    wlang (0.10.2)
-
 GEM
   remote: http://rubygems.org/
   specs:
-    RedCloth (4.2.7)
-    bluecloth (2.0.11)
-    coderay (0.9.7)
-    diff-lcs (1.1.2)
-    rake (0.8.7)
-    rdoc (3.5.3)
-    rspec (2.4.0)
-      rspec-core (~> 2.4.0)
-      rspec-expectations (~> 2.4.0)
-      rspec-mocks (~> 2.4.0)
-    rspec-core (2.4.0)
-    rspec-expectations (2.4.0)
-      diff-lcs (~> 1.1.2)
-    rspec-mocks (2.4.0)
-    yard (0.6.4)
+    awesome_print (1.0.2)
+    backports (2.6.1)
+    bluecloth (2.2.0)
+    citrus (2.4.1)
+    diff-lcs (1.1.3)
+    epath (0.1.1)
+    mustache (0.99.4)
+    quickl (0.4.3)
+    rake (0.9.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    ruby-prof (0.11.2)
+    temple (0.4.0)
+    yard (0.8.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  RedCloth
-  bluecloth (~> 2.0.9)
+  awesome_print (~> 1.0.2)
+  backports (~> 2.6.1)
+  bluecloth (~> 2.2.0)
   bundler (~> 1.0)
-  coderay
-  rake (~> 0.8.7)
-  rdoc
-  rspec (~> 2.4.0)
-  wlang!
-  yard (~> 0.6.4)
+  citrus (~> 2.4.1)
+  epath (~> 0.1.0)
+  mustache (~> 0.99.4)
+  quickl (~> 0.4.3)
+  rake (~> 0.9.2)
+  rspec (~> 2.10.0)
+  ruby-prof (~> 0.11.2)
+  temple (~> 0.4.0)
+  yard (~> 0.8.1)

data/LICENCE.md

@@ -1,25 +1,22 @@
-# Licence
+# The MIT Licence
 
-	The MIT License
+    Copyright (c) 2012 - Bernard Lambeau, Louis Lambeau
 
-	Copyright (c) 2009-2011 Bernard & Louis Lambeau and the University of Louvain 
-	(Universite Catholique de Louvain, Louvain-la-Neuve, Belgium)
-	
-	Permission is hereby granted, free of charge, to any person obtaining a copy
-	of this software and associated documentation files (the "Software"), to deal
-	in the Software without restriction, including without limitation the rights
-	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-	copies of the Software, and to permit persons to whom the Software is
-	furnished to do so, subject to the following conditions:
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
 
-	The above copyright notice and this permission notice shall be included in
-	all copies or substantial portions of the Software.
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
 
-	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-	THE SOFTWARE.
-	
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -1,9 +1,10 @@
-bin/**/*
+wlang.gemspec
+wlang.noespec
+.gemtest
 CHANGELOG.md
-doc/specification/**/*
-example/**/*
 Gemfile
 Gemfile.lock
+bin/**/*
 lib/**/*
 LICENCE.md
 Manifest.txt
@@ -12,5 +13,3 @@ README.md
 spec/**/*
 tasks/**/*
 test/**/*
-wlang.gemspec
-wlang.noespec

data/README.md

@@ -1,174 +1,100 @@
-# What is _wlang_ ?
-
-WLang is a general-purpose *code generation*/*templating engine*. It's main aim is to help you generating
-web pages, sql queries, ruby code (that is, generating code in general) without having to worry too much 
-about html entities encoding, sql back quoting, string escaping and the like. WLang proposes a generic 
-engine that you can extend to fit your needs. It also proposes standard instantiations of this engine 
-for common tasks such as creating SQL queries, instantiating web pages, and so on.
-
-Basic concepts and usage is illustrated below. Also have a look at the [detailed specification](http://blambeau.github.com/wlang).
-
-## A collection of typical encoders
-
-The first basic usage of WLang is to provide a collection of text encoders:
-
-    WLang::encode('&',      'xhtml/entities-encoding')      # &
-    WLang::encode("O'Neil", 'sql/single-quoting')           # O\'Neil   
-    WLang::encode("O'Neil", 'sql/sybase/single-quoting')    # O''Neil   
-    ...
-    WLang::encode("hello world",  'plain-text/camel')        # HelloWorld  
-    WLang::encode("hello world",  'plain-text/lower-camel')  # helloWorld  
-    ...
-    WLang::encode("helloWorld",   'ruby/method-case')        # hello_world
-  
-## A powerful alternative to ruby string interpolation
-
-The second usage is to have shortcuts for using these encoders in typical 
-situations:
-
-    # Hello world!
-    "Hello ${who}!".wlang(:who => 'world')                          
-
-    # Hello cruel & world!
-    "Hello ${who}!".wlang({:who => 'cruel & world'}, 'wlang/xhtml') 
-  
-    # Hello blambeau, llambeau
-    "Hello *{authors as a}{${a}}{, }".wlang(:authors => ['blambeau', 'llambeau'])
-  
-    # INSERT INTO people VALUES ('O\'Neil')
-    INSERT INTO people VALUES ('{who}')".wlang(:who => "O'Neil")
-
-## A powerful templating engine
-
-But the main usage of _wlang_ is as follows (for bold words, see terminology later): 
-you have a *template* file (written in a given _wlang_ *dialect*), you have some 
-instantiation *context* (data provided through a Ruby Hash or a yaml file for 
-example) and you would like to instantiate the template with that data.
-
-Example: a template.whtml as follows
-    <html>
-      <head>
-        <title>${title}</title>
-      </head>
-      <body>
-        <h1>Hello ${who} !</h1>
-      </body>
-    </html>
-  
-Instantiation data is a hash containing values for _title_ and _who_. Instantiating 
-the template is straightforward:
-
-    require 'wlang'
-    context = {"title" => "Hello world in WLang", "who" => "Alice"}
-    STDOUT << WLang.file_instantiate("template.whtml", context)
-  
-## Behind the scene
-
-- WLang helps you avoiding SQL injection and XSS attacks through the same tags reacting differently
-  in different contexts.
-- WLang understands your context (and its dialect) from the template file extension
-- WLang provides a rich collection of pre-defined tags and dialects
-- WLang allows you to create your own encoders, tags and dialects while reusing existing ones
-- WLang may change the current dialect during the template instantiation itself (generating
-  html with embedded javascript is easy and natural)
-- WLang is able to generate wlang code without any perturabation
-
-## Additional examples (availability of the tags may depend on the dialect)
-
-* Include text files on the fly
-
-      <<{my_file.html}
-
-* Instantiate sub-templates on the fly, passing data as arguments
-
-      <<+{my_sub_template.whtml using who: 'wlang'}
-
-* Load data from yaml or ruby files on the fly
-
-      <<={resources.yaml as resources}{
-        *{resources as r}{ ${r} }
-      }
-
-* WLang instrospection (basic example)
-
-      context = {:varname => 'who', :who => 'wlang'}
-      "Hello ${${varname}}!".wlang(context)                     # => Hello wlang!
-
-* Generate a wlang template and instantiate it after that
-    
-      dialect = 'wlang/active-string'
-      tpl = "Hello $(${varname})!"                              # => Hello $(${varname})
-      tpl = tpl.wlang(:varname => 'who')                        # => Hello $(who)!
-      tpl = tpl.wlang({:who => 'wlang'}, dialect, :parentheses) # => Hello wlang!
-
-## Roadmap
-
-- For terminology and a quick overview of _wlang_ for generating code, read on.
-- For the current cheatsheet/specification see the file doc/specification/specification.html
-- If you want to learn _wlang_ quickly, see the example directory or read examples
-  in the specification file (if you understand all examples in the specification file, then you 
-  probably master wlang.
-- If you want a killer example (but simple) see the way the specification.html file
-  is generated in doc/specification directory
-- If you want to know which dialects are available (that is, in which target languages 
-  you can generate code), see the specification as well or read the file 
-  lib/wlang/dialects/standard_dialects.rb in the source distribution.
-- If you want to create your own wlang dialect, see WLang::Dialect::DSL
-- If you think that your own dialect is of generic purpose and well-designed, if
-  you have any question or want to contribute join us on {github}[http://github.com/blambeau/wlang].
-  
-## Terminology
-
-_wlang_ comes with a well-defined terminology for the underlying abstractions. As 
-the documentation uses it, you'll probably be happy to learn about the main abstractions
-and associated terms.
-
-_template_ : Source code respecting the wlang grammar, and attached to a given <em>wlang 
-dialect</em>. Asbtraction implemented by WLang::Template.
-
-_dialect_ : 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_. Abstraction implemented by WLang::Dialect. 
-
-_wlang dialect_ : 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_. Abstraction implemented by WLang::Dialect as well as
-WLang::EncoderSet and WLang::RuleSet. 
-
-_encoder set_ : Reusable set of <em>encoders</em>, attached to a dialect. Abstraction
-implemented by WLang::EncoderSet.
-
-_encoder_ : 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: 
-xhtml/entities-encoding and sql/back-quoting in the examples. Abstraction implemented by 
-WLang::Encoder.
-
-_ruleset_ : Reusable set of <em>tags</em> associated to <em>rule</em>s. Abstraction
-implemented by WLang::RuleSet.
-
-_wlang tag_ : Special tags in the template, starting with wlang symbols and a number of wlang 
-blocks. A tag is associated with a wlang rule. Examples: <tt>${...}</tt> is a 
-tag with only one block, while <tt>?{...}{...}{...}</tt> is another tag but with 
-three blocks.  
-
-_rule_ : 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 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> (also known as 'encoding') 
-instantiates #1, looking for an encoder qualified name. Instantiates #2 in 
-the current dialect. Encode #2's instantiation using encoder found in (#1)
-
-_context_ : 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. Abstraction implemented in WLang::Parser::Context.
-
-_hosting language_ : language (or framework) that executes wlang. In this case, it will be
-<tt>ruby</tt>.
+# WLang
+
+[![Build Status](https://secure.travis-ci.org/blambeau/wlang.png?branch=wlang2)](http://travis-ci.org/blambeau/wlang)
+
+WLang is a powerful code generation and templating engine.
+
+This is the README of wlang2, a fresh new implementation of the [wlang templating language concept](http://revision-zero.org/wlang), this one implemented on top of [temple](https://github.com/judofyr/temple) and much inspired by the excellent [mustache](http://mustache.github.com/). (For users of wlang 1.0 (formaly 0.10.2), this rewrite cleans most concepts as well as the abstract wlang semantics; it also uses a simple compiler architecture to gain huge perfomance gains in comparison to early wlang days).
+
+**WLang2 is work in progress**. It does not support rubinius so far, due to an incompatibility with the Citrus parser generator. It also have some issues with spacing; not a big issue for HTML rendering but might prevent certain generation tasks.
+
+## Links
+
+* http://github.com/blambeau/wlang
+* http://blambeau.github.com/wlang
+* http://rubygems.org/gems/wlang
+* http://revision-zero.org/wlang
+
+## A user-defined templating engine
+
+WLang is a templating engine, written in ruby. In that, it is similar to ERB, Mustache and the like:
+
+```ruby
+WLang::Html.render 'Hello to ${who}!', who: 'you & the world'
+# => "Hello you &amp; the world!"
+```
+
+To output HTML pages, WLang does not provides you with killer features or extraordinary shortcus. It supports escaping, as shown above, but many other templating engines do. For such HTML tasks, WLang does a pretty good job but many other engines perform faster and have nicer features. See the examples folder that documents WLang::Html.
+
+WLang is designed to help you for other uses cases, user-defined ones in particular, such as generating code or whatever text generation task for which other engines quickly become inappropriate. WLang helps there because it allows you to create your own _dialect_, that is, you can define your own tags and their behavior. For instance,
+
+```ruby
+class Highlighter < WLang::Dialect
+
+  def highlight(buf, fn)
+    var_name  = render(fn)
+    var_value = evaluate(var_name)
+    buf << var_value.to_s.upcase
+  end
+
+  tag '$', :highlight
+end
+Highlighter.render('Hello ${who}!'), who: 'you & the world'
+# => "Hello YOU & THE WORLD !"
+```
+
+WLang already provides a few useful dialects, such as WLang::Mustang (mimicing mustache) and WLang::Html (a bit more powerful in my opinion). If they don't match your needs, it is up to you to define you own dialect for making your generation task easy. Have a look at the implementation of WLang's ones, it's pretty simple to get started!
+
+## Abstract semantics
+
+WLang has a powerful semantics in terms of concatenation of strings and high-order functions (i.e. functions that take other functions as parameters). Let take the following template as an example:
+
+```
+Hello ${who} !
+```
+
+The functional semantics of this template is as follows:
+
+```clojure
+(fn (concat "Hello", ($ (fn "who")), " !"))
+```
+
+That is, the compilation of this template yields a function that concatenates the
+string `"Hello"` with the result of the higher-order function `($ )` (that itself takes another function as a parameter, corresponding to the sub-template in its brackets delimited blocks) and then the string `" !"`. Providing a concrete semantics to those high-order functions yields so called WLang _dialects_, as we've seen before.
+
+Having a well-defined semantics allows wlang to properly compile your user-defined dialect and its instantiation engine so as to preserve decent performances. The WLang architecture is a typical compiler chain. This means that, provided some additional coding, you could even define your own language/syntax and reuse the compilation mechanism, provided that you preserve the semantics above.
+
+## Higher-order constructs
+
+A feature that distinguishes WLang from most templating engines is the fact that higher-level constructions are permitted. In addition to tag functions that accept multiple arguments, thus multiple blocks in the source text, those blocks may be complex templates themselves.
+
+For instance, the following behavior is perfectly implementable:
+
+```ruby
+HighLevel.render 'Hello *{ ${collection} }{ ${self} }{ and } !',
+                 collection: 'whos', whos: [ "you", "wlang", "world" ]
+# => "Hello you and wlang and world"
+```
+
+An implementation of `HighLevel` might be as follows:
+
+```ruby
+class HighLevel < WLang::Dialect
+
+  def join(buf, expr, main, between)
+    evaluate(expr).each_with_index do |val,i|
+      buf << render(between, val) unless i==0
+      buf << render(main, val).strip
+    end
+  end
+
+  def print(buf, fn)
+    buf << evaluate(fn).to_s
+  end
+
+  tag '*', :join
+  tag '$', :print
+end
+```
+
+Use at your own risk, though, as it might lead to dialects that are difficult to understand and/or use and present serious injections risks! Otherwise, higher-order constructions provides you with very powerful tools.