wlang 2.0.1 → 2.1.0

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+# 2.1.0 / 2012-11-28
+
+## Enhancements
+
+* The scoping mechanism has been clarified and enhanced (mostly private APIs).
+  In particular,
+  * Template#render and Dialect#render now accepts multiple scoping objects and chain them
+    as a unique scope. The latter is branched with template locals, which are always the
+    most-specific and therefore have highest priority.
+  * RootScope as been renamed to NullScope, Scope.root to Scope.null accordingly
+  * ProxyScope has been removed to keep scopes linear chains.
+
+* Added Dialect#context, which allows knowing the subject of the less specific scope, that
+  is the first argument of Dialect#render and Template#render. In Sinatra/Tilt situation,
+  this simply correspond to the `scope`, typically the Sinatra app.
+
+* Dialect#evaluate (through Scope#evaluate) now accepts an optional block for specifying
+  a computed default value instead of failing.
+
+* WLang::Html partial tag >{...} now recognizes a Proc and simply renders the result of
+  calling it. This allows to use >{yield} in layouts instead of the less idomatic +{yield}.
+
+## Bug fixes
+
+* Fixed a bug when parsing "hello {  ${wlang} }" constructs (typically javascript or java)
+  (wlang inner constructions was not properly parsed)
+
 # 2.0.1 / 2012-06-12
 
 * Fix support for 1.8.7 and jruby (undefined method `ord' for String)

data/Gemfile

@@ -16,4 +16,6 @@ group :development do
   gem "rspec", "~> 2.10.0"
   gem "yard", "~> 0.8.1"
   gem "bluecloth", "~> 2.2.0"
+  gem "sinatra", :git => "git://github.com/sinatra/sinatra" #">= 1.4"
+  gem "rack-test", "~> 0.6.1"
 end

data/Gemfile.lock

@@ -1,3 +1,12 @@
+GIT
+  remote: git://github.com/sinatra/sinatra
+  revision: 8752085a05c33edd13d3ec8d3187d1406456d404
+  specs:
+    sinatra (1.4.0)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+
 GEM
   remote: http://rubygems.org/
   specs:
@@ -8,6 +17,11 @@ GEM
     diff-lcs (1.1.3)
     epath (0.2.0)
     quickl (0.4.3)
+    rack (1.4.1)
+    rack-protection (1.2.0)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
     rake (0.9.2.2)
     rspec (2.10.0)
       rspec-core (~> 2.10.0)
@@ -32,8 +46,10 @@ DEPENDENCIES
   citrus (~> 2.4.1)
   epath (>= 0.2)
   quickl (~> 0.4.3)
+  rack-test (~> 0.6.1)
   rake (~> 0.9.2)
   rspec (~> 2.10.0)
+  sinatra!
   temple (~> 0.4.0)
   tilt (~> 1.3)
   yard (~> 0.8.1)

data/README.md

@@ -23,7 +23,7 @@ WLang is a powerful code generation and templating engine, implemented on top of
 WLang 2.0 also has a few remaining issues.
 
 * 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.
+* It has some issues with spacing; not a big issue for HTML rendering but might prevent certain generation tasks.
 
 ## Tunable templating engine
 
@@ -55,75 +55,52 @@ Highlighter.render('Hello ${who}!'), who: 'you & the world'
 
 WLang already provides a few useful dialects, such as WLang::Html (inspired by Mustache but 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
+# Tilt integration
 
-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:
+WLang has built-in support for [Tilt](https://github.com/rtomayko/tilt) facade to templating engines. In order to use that API:
 
-```
-Hello ${who} !
-```
+```ruby
+require 'tilt'         # needed in your bundle, not a wlang dependency
+require 'wlang'        # loads Tilt support provided Tilt has already been required
 
-The functional semantics of this template is as follows:
+template = Tilt.new("path/to/a/template.wlang")   # suppose 'Hello ${who}!'
+template.render(:who => "world")
+# => Hello world!
 
-```clojure
-(fn (concat "Hello", ($ (fn "who")), " !"))
+template = Tilt.new("path/to/a/template.wlang", :dialect => Highlighter)
+template.render(:who => "world")
+# => Hello WORLD!
 ```
 
-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.
+Please note that you should require tilt first, then wlang. Otherwise, you'll have to require `wlang/tilt` explicitely.
 
-## Higher-order constructs
+# Sinatra integration
 
-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.
+WLang comes bundled with built-in support for [Sinatra](https://github.com/sinatra/sinatra). As usual in Sinatra, you can simply invoke wlang as follows:
 
-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
+    get '/' do
+      wlang :index, :locals => { ... }
     end
-  end
 
-  def print(buf, fn)
-    buf << evaluate(fn).to_s
-  end
+As wlang encourages logic-less templates, you should always use locals. However, there is specific support for layouts and partials, as the following example demonstrates:
 
-  tag '*', :join
-  tag '$', :print
-end
-```
+    get '/' do
+      wlang :index, :locals => {:who => "world"}
+    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.
+    __END__
 
-# Tilt integration
+    @@layout
+      <html>
+        >{yield}
+      </html>
 
-WLang 2.0 has built-in support for [Tilt](https://github.com/rtomayko/tilt) facade to templating engines. In order to use that API:
+    @@index
+      Hello from a partial: >{partial}
 
-```ruby
-require 'tilt'         # needed in your bundle, not a wlang dependency
-require 'wlang'        # loads Tilt support provided Tilt has already been required
-
-template = Tilt.new("path/to/a/template.wlang")   # suppose 'Hello ${who}!'
-template.render(:who => "world")
-# => Hello world!
+    @@partial
+      yeah, a partial saying hello to '${who}'!
 
-template = Tilt.new(hello_path.to_s, :dialect => Highlighter)
-template.render(:who => "world")
-# => Hello WORLD!
-```
+Returned body will be (ignoring carriage returns):
 
-Please note that you should require tilt first, then wlang. Otherwise, you'll have to require `wlang/tilt` explicitely.
+    <html>Hello from a partial: yeah, a partial saying hello to 'world'!</html>

data/lib/wlang.rb

@@ -27,6 +27,14 @@ module WLang
   end
   module_function :dialect
 
+  SinatraApp = proc{|arg|
+    defined?(Sinatra::Base) && Sinatra::Base===arg
+  }
+
+  TiltTemplate = proc{|arg|
+    defined?(Tilt::Template) && Tilt::Template===arg
+  }
+
 end # module WLang
 require 'wlang/compiler'
 require 'wlang/source'

data/lib/wlang/compiler/grammar.citrus

@@ -1,11 +1,11 @@
 grammar WLang::Grammar
-  
+
   rule template
     (strconcat !.){
       [:template, [:fn, strconcat.value]]
     }
   end
-  
+
   rule strconcat
     (non_static | static)* {
       if matches.size == 1
@@ -15,53 +15,56 @@ grammar WLang::Grammar
       end
     }
   end
-  
+
   rule static
-    (!stop_char .)+ { 
-      [:static, to_s] 
+    (!stop_char .)+ {
+      [:static, to_s]
     }
   end
-  
+
   rule non_static
     block | wlang
   end
-  
+
   rule block
     (fn_start strconcat fn_stop){
-      [:static, to_s]
+      [:strconcat,
+        [:static, captures[:fn_start].first.to_s],
+        captures[:strconcat].first.value,
+        [:static, captures[:fn_stop].first.to_s]]
     }
   end
-  
+
   rule wlang
     (symbols functions){
       [:wlang, symbols.to_s] + functions.value
     }
   end
-  
+
   rule functions
     function+ { matches.map{|fn| [:fn, fn.value]} }
   end
-  
+
   rule function
     (fn_start strconcat fn_stop){
       strconcat.value
     }
   end
-  
+
   rule stop_char
     fn_start | fn_stop | (symbols fn_start)
   end
-  
+
   rule symbols
     /[!\^%"\$&'\*\+\?@~\#,\-\.\/:;=<>\|_]+/
   end
-  
+
   rule fn_start
     '{'
   end
-  
+
   rule fn_stop
     '}'
   end
-  
+
 end

data/lib/wlang/dialect.rb

@@ -14,8 +14,8 @@ module WLang
         Template.new source, :dialect => self
       end
 
-      def render(source, scope = {}, buffer = "")
-        compile(source).call(scope, buffer)
+      def render(source, *args)
+        compile(source).call(*args)
       end
 
       # tag installation and dispatching
@@ -139,14 +139,12 @@ module WLang
     def render(fn, scope = nil, buffer = "")
       if scope.nil?
         case fn
-        when String
-          buffer << fn
-        when Proc
-          fn.call(self, buffer)
-        when Template
-          fn.call(@scope, buffer)
-        else
-          raise ArgumentError, "Unable to render `#{fn}`"
+          when String       then buffer << fn
+          when Proc         then fn.call(self, buffer)
+          when Template     then fn.call(@scope, buffer)
+          when TiltTemplate then buffer << fn.render(@scope)
+          else
+            raise ArgumentError, "Unable to render `#{fn}`"
         end
         buffer
       else
@@ -156,9 +154,14 @@ module WLang
 
     # evaluation
 
+    # Returns the execution context, defined as the subject of the root scope.
+    def context
+      scope.root.subject
+    end
+
     # Returns the current rendering scope.
     def scope
-      @scope ||= Scope.root
+      @scope || Scope.null
     end
 
     # Yields the block with a scope branched with a sub-scope `x`.
@@ -177,17 +180,18 @@ module WLang
     # Evaluation is delegated to the scope (@see Scope#evaluate) and the result returned
     # by this method.
     #
-    def evaluate(expr, *default)
+    def evaluate(expr, *default, &bl)
       case expr
       when Symbol, String
         catch(:fail) do
-          return scope.evaluate(expr, *default)
+          return scope.evaluate(expr, self, *default, &bl)
         end
         raise NameError, "Unable to find `#{expr}`"
       else
-        evaluate(render(expr), *default)
+        evaluate(render(expr), *default, &bl)
       end
     end
+    alias :value_of :evaluate
 
   end # class Dialect
 end # module WLang

data/lib/wlang/html.rb

@@ -5,11 +5,6 @@ module WLang
 
     module Helpers
 
-      def value_of(fn, *defaults)
-        evaluate(render(fn).to_s.strip, *defaults)
-      end
-      private :value_of
-
       def to_html(val)
         val = val.to_html if val.respond_to?(:to_html)
         val = to_html(val.call) if val.is_a?(Proc)
@@ -28,12 +23,12 @@ module WLang
     module HighOrderFunctions
 
       def bang(buf, fn)
-        val = value_of(fn).to_s
+        val = evaluate(fn).to_s
         render(val, nil, buf)
       end
 
       def plus(buf, fn)
-        val = value_of(fn)
+        val = evaluate(fn)
         val = to_html(val) unless val.is_a?(Template)
         render(val, nil, buf)
       end
@@ -56,7 +51,7 @@ module WLang
       end
 
       def question(buf, fn_if, fn_then, fn_else)
-        val   = value_of(fn_if)
+        val   = evaluate(fn_if)
         val   = val.call if Proc===val
         block = val ? fn_then : fn_else
         render(block, nil, buf) if block
@@ -67,7 +62,7 @@ module WLang
       end
 
       def star(buf, coll_fn, elm_fn, between_fn)
-        collection = value_of(coll_fn)
+        collection = evaluate(coll_fn)
         collection.each_with_index do |elm,i|
           render(between_fn, elm, buf) if between_fn and (i > 0)
           render(elm_fn, elm, buf)
@@ -75,13 +70,14 @@ module WLang
       end
 
       def greater(buf, fn)
-        val = value_of(fn)
+        val = evaluate(fn)
         val = Html.compile(val) if String === val
+        val = val.call if Proc === val and val.arity<=0
         render(val, nil, buf)
       end
 
       def sharp(buf, who_fn, then_fn)
-        val = value_of(who_fn, nil)
+        val = evaluate(who_fn, nil)
         if val and not(val.respond_to?(:empty?) and val.empty?)
           render(then_fn, val, buf)
         end

data/lib/wlang/scope.rb

@@ -4,36 +4,37 @@ module WLang
     attr_reader :subject
     attr_reader :parent
 
-    def initialize(subject, parent)
-      @subject, @parent = subject, parent
+    def initialize(subject)
+      @subject = subject
+      @parent  = nil
     end
 
-    def self.root
-      @root ||= RootScope.new
+    def self.null
+      @null ||= NullScope.new
     end
 
-    def self.coerce(arg, parent = nil)
-      return arg if Scope===arg && parent.nil?
-      parent ||= root
-      clazz = case arg
-              when Binding
-                BindingScope
-              when Scope
-                ProxyScope
-              when Proc
-                ProcScope
-              else
-                ObjectScope
-              end
-      clazz.new(arg, parent)
+    def self.coerce(arg)
+      case arg
+        when Hash       then ObjectScope.new(arg)
+        when Scope      then arg
+        when SinatraApp then SinatraScope.new(arg)
+        when Binding    then BindingScope.new(arg)
+        when Proc       then ProcScope.new(arg)
+        else
+          ObjectScope.new(arg)
+      end
     end
 
     def self.chain(scopes)
-      scopes.compact.inject(nil){|parent,child| Scope.coerce(child, parent)} || root
+      scopes.compact.inject(Scope.null){|p,c| p.push(c)}
+    end
+
+    def root
+      parent ? parent.root : self
     end
 
     def push(x)
-      Scope.coerce(x, self)
+      append(Scope.coerce(x))
     end
 
     def pop
@@ -44,23 +45,62 @@ module WLang
       yield(self.push(x))
     end
 
-    def evaluate(expr, *default)
-      unfound = lambda{ default.empty? ? throw(:fail) : default.first }
-      expr    = expr.to_s.strip
-      if expr.to_s.index('.').nil?
-        fetch(expr.to_sym, &unfound)
+    def evaluate(expr, dialect, *default, &bl)
+      expr = expr.to_s.strip
+      unfound = lambda do
+        if default.empty?
+          bl ? bl.call(expr) : throw(:fail)
+        else
+          default.first
+        end
+      end
+      if expr.index('.').nil?
+        fetch(expr.to_sym, dialect, unfound)
       else
         keys = expr.split('.').map(&:to_sym)
         keys.inject(self){|scope,key|
-          Scope.coerce(scope.fetch(key, &unfound))
+          found = scope.fetch(key, dialect, unfound)
+          Scope.coerce(found)
         }.subject
       end
     end
 
+    def subjects
+      arr = []
+      visit(:top_down){|s| arr << s.subject}
+      arr
+    end
+
+    protected
+
+      def visit(mode = :top_down, &visitor)
+        visitor.call(self) unless mode == :top_down
+        parent.visit(mode, &visitor) if parent
+        visitor.call(self) if mode == :top_down
+      end
+
+      def append(x)
+        x.prepend(self)
+      end
+
+      def prepend(x)
+        newp = parent ? parent.prepend(x) : x
+        dup.with_parent!(newp)
+      end
+
+      def with_parent!(p)
+        @parent = p
+        self
+      end
+
+      def safe_parent
+        parent || Scope.null
+      end
+
   end # class Scope
 end # module WLang
-require 'wlang/scope/root_scope'
-require 'wlang/scope/proxy_scope'
+require 'wlang/scope/null_scope'
 require 'wlang/scope/object_scope'
 require 'wlang/scope/binding_scope'
 require 'wlang/scope/proc_scope'
+require 'wlang/scope/sinatra_scope'