wlang 0.10.2 → 2.0.0.beta

data/lib/wlang/template.rb

@@ -1,95 +1,25 @@
 module WLang
-  # 
-  # Template in a given wlang dialect and expecting :braces, :brackets or 
-  # :parentheses as block delimiters. A template is an abstraction over a 
-  # wlang source text. It also provides utilities to create friendly location
-  # messages for offsets in the source text.
-  #
   class Template
-  
-    # Recognized symbols for blocks
-    BLOCK_SYMBOLS = {:braces   => ['{', '}'],
-                     :brackets => ['[', ']'],
-                     :parentheses => ['(', ')']}
-  
-    # Template wlang dialect (wlang/...)
-    attr_reader :dialect
 
-    # Block symbols
-    attr_reader :block_symbols
-  
-    # Attached file source
-    attr_accessor :source_file
-  
-    # Creates a template instance.
-    def initialize(source, dialect, block_symbols = :braces)
-      dialect = WLang::dialect(dialect)
-      raise(ArgumentError, "Source is mandatory") if source.nil?
-      raise(ArgumentError, "Dialect instance expected for dialect, #{dialect} received") unless Dialect===dialect
-      @source = source
-      @dialect = dialect
-      @block_symbols = block_symbols
+    attr_reader :dialect, :inner_proc
+
+    def initialize(dialect, inner_proc)
+      @dialect    = dialect
+      @inner_proc = inner_proc
     end
-  
-    # Resolved a relative uri
-    def file_resolve(uri, exists=false)
-      require 'uri'
-      real_uri = URI::parse(uri)
-      if real_uri.absolute?
-        raise WLang::Error, "Unable to resolve #{uri}, absolute uri are not supported"
-      elsif real_uri.path[0, 1] == '/'
-        real_uri.path
+
+    def call(scope = {}, buffer = '')
+      case i = inner_proc
+      when String
+        buffer << i
       else
-        raise WLang::Error, "Unable to resolve #{uri}, this template is not attached to a file" unless @source_file
-        target = File.join(File.dirname(@source_file), uri)
-        if exists and not(File.exists?(target))
-          raise WLang::Error, "File '#{uri}' does not exists"
+        @dialect.dup.tap do |d|
+          d.send(:render, i, scope, buffer)
         end
-        target
+        buffer
       end
     end
-  
-    # Returns template's source text
-    def source_text
-      case @source
-        when String
-          @source
-        else
-          @source.to_s
-      end
-    end
-    
-    # Returns template's block endstart (typically '}{')
-    def block_endstart
-      @block_endstart ||= BLOCK_SYMBOLS[block_symbols].reverse.join
-    end
-  
-    # Instantiates the template, with optinal context and hosted language.
-    def instantiate(context = {}, hosted = ::WLang::HostedLanguage.new)
-      p = ::WLang::Parser.new(hosted, self, context)
-      p.instantiate(true)[0]
-    end
-    
-    # Returns a friendly position of an offset in the source text
-    def where(offset)
-      src = source_text
-      source_file = self.source_file ? File.expand_path(self.source_file) : "no source file"
-      "#{source_file || 'inline template'}:#{src.__wlang_line_of(offset)}:#{src.__wlang_column_of(offset)-1}"
-    end
-    
-    # Raises a WLang::Error for the given offset
-    def error(offset, msg = "")
-      raise WLang::Error, "#{where(offset)} #{msg}"
-    end
-    
-    # Raises a friendly ParseError, with positions and so on
-    def parse_error(offset, msg = "")
-      src = source_text
-      ex = ParseError.new("#{where(offset)} #{msg}")
-      ex.line, ex.column = src.__wlang_line_of(offset), src.__wlang_column_of(offset)-1
-      raise ex
-    end
-  
+    alias :render :call
+
   end # class Template
-  
-end # module WLang
+end # module WLang

data/lib/wlang/version.rb

@@ -1,14 +1,15 @@
 module WLang
   module Version
-  
-    MAJOR = 0
-    MINOR = 10
-    TINY  = 2
-  
+
+    MAJOR = 2
+    MINOR = 0
+    TINY  = 0
+    BETA  = "beta"
+
     def self.to_s
-      [ MAJOR, MINOR, TINY ].join('.')
+      [ MAJOR, MINOR, TINY, BETA ].join('.')
     end
-  
-  end 
+
+  end
   VERSION = Version.to_s
 end

data/spec/fixtures/dialect/foobar.rb

@@ -0,0 +1,31 @@
+class Foo < WLang::Dialect
+
+  def _(fn)
+    fn ? render(fn) : nil
+  end
+
+  def execution(buf, fn)
+    buf << "(foo#execution #{_ fn})"
+  end
+
+  def escaping(buf, fn)
+    buf << "(foo#escaping #{_ fn})"
+  end
+
+  tag "!", :execution
+  tag "$", :escaping
+  tag "@"  do |buf,fn| buf << "(foo#link #{_ fn})";   end
+  tag "<"  do |buf,fn| buf << "(foo#less #{_ fn})";   end
+  tag '!@' do |buf,fn| buf << "(foo#bangat #{_ fn})"; end
+end
+
+class Bar < Foo
+
+  def escaping(buf, fn)
+    buf << "(bar#escaping #{_ fn})"
+  end
+
+  tag "$", :escaping
+  tag "<" do |buf,fn| buf << "(bar#less #{_ fn})";    end
+  tag ">" do |buf,fn| buf << "(bar#greater #{_ fn})"; end
+end

data/spec/fixtures/dialect/upcasing.rb

@@ -0,0 +1,13 @@
+class Upcasing < WLang::Dialect
+
+  tag "$" do |buf, fn|
+    buf << render(fn).upcase
+  end
+
+  tag "#" do |buf, fn|
+    if x = evaluate(fn)
+      buf << x
+    end
+  end
+
+end

data/spec/fixtures/templates/hello.tpl

@@ -0,0 +1 @@
+Hello ${who}!

data/spec/integration/examples/1-basics.txt

@@ -0,0 +1,65 @@
+# Three basic tags: bang, plus and dollar
+
+Three special tags, bounded to the !, +, $ symbols allow injecting dynamic content. The difference between them is:
+
+* bang   (!) renders the result of invoking `to_s` on the evaluated expression (see later),
+* plus   (+) first tries to render the value through a `to_html` method and falls back to `to_s`
+* dollar ($) escapes html entities of the content that would be returned by +.
+
+We do not illustrate the difference between ! and + here, as it is only only useful for already advanced scenarios. The idiomatic way of using WLang::Html is to avoid ! unless strictly needed, to consider + as unsafe but useful, and $ as safe and to use it by default.
+
+Users that know Mustache can remember that $ corresponds to {{ ... }} whereas + corresponds to {{{ ... }}}, which some powerful extras (not shown here). For example,
+
+    Hello <script>injected code</script> !
+
+is clearly safe (instantiate the example to convince yourself), but the following one:
+
+    Hello <script>injected code</script> !
+
+is not safe, unless the `who` variable contains content that you can trust and which must not be escaped.
+
+The WLang::Html dialect encourages logic-less templates, but is not as strict as Mustache.  Indeed, all tags that rely on some form of variable evaluation (the three above in particular), actually allow simple expressions, restricted to argument-less getters however:
+
+    Hello wlang, released in 2012!
+
+# Ampersand as an introduction to high-level constructs
+
+A fourth basic tag is sometimes useful, and allows me to introduce higher-level wlang constructs.
+
+* ampersand (&) escapes raw html content. It does not evaluate any expression.
+
+For example, the following expression
+
+    &lt;script&gt;some attacker attempt to inject code&lt;&#47;script&gt;
+
+will simply escape its html content.
+
+Given the WLang functional semantics and the & and ! tags, one can see + and $ as shortcuts for longer expressions. For instance,
+
+    &lt;script&gt;injected code&lt;&#47;script&gt; is a shortcut for the equivalent expression &lt;script&gt;injected code&lt;&#47;script&gt;
+
+We'll come back to higher-level constructs in other examples later. For now, let just introduce some additional bacic tags.
+
+# Slash for comments
+
+The slash tag is used for comments. It simply renders nothing at all.
+
+* slash (/) can be used for comments.
+
+For instance,
+
+    
+
+And,
+
+# Modulo to disengage wlang
+
+The last useful tag allows you to simply disable wlang rendering in specific template portions. For this, use the modulo tag:
+
+* modulo (%) disables wlang inside its block.
+
+For instance, the following template renders the block text unchanged, even if it contains wlang tags:
+
+     Hello ${struct.name}, how are you?
+
+This is especially useful for writing blog posts explaining wlang, using wlang itself. Therefore, it is a feature mostly needed by me ;-)

data/spec/integration/examples/2-imperative.txt

@@ -0,0 +1,51 @@
+# Introduction
+
+WLang inspires from Mustache and encourages you to write logic-less templates. It does not mean that imperative constructions are not needed. Iterations and conditional sections, in particular are definitely something required.
+
+## Conditional and inverted sections
+
+* question (?) provides a if-then-else section, with optional else
+* caret    (^) provides a if-else-then section, with optional then
+
+The boolean evaluation is based on Ruby's conditions and has the same semantics: nil and false are FALSE, all other values are TRUE. For instance,
+
+    'Hello TRUE'   renders as 'Hello TRUE'
+    'Hello TRUE' renders as 'Hello TRUE'
+    'Hello FALSE'  renders as 'Hello FALSE'
+    'Hello FALSE'    renders as 'Hello FALSE'
+
+For inverted sections,
+
+    'Hello FALSE'   renders as 'Hello FALSE'
+    'Hello FALSE' renders as 'Hello FALSE'
+    'Hello TRUE'  renders as 'Hello TRUE'
+    'Hello TRUE'    renders as 'Hello TRUE'
+
+In both cases, the first block relies on an expression evaluation and therefore allows dotted expressions (see 1-basics.md), while also recognizing high-level constructs. Also, the third block is optional. As an example,
+
+    'Hello world' renders as 'Hello world' if `vart` contains 'true'
+
+whereas,
+
+    'Hello ' renders as 'Hello ' if `varf` contains 'false'
+
+As usual, use it with parcimony and care but enjoy its powerfulness.
+
+## Iterations
+
+A special tag allows you to perform simple iterations. More accurately, the star allows you to render a block for each value of a sequence, joining the results with an optional separator:
+
+* star (*) joins the rendering of its second block for each element of a sequence
+
+For instance,
+
+    <ul>
+      <li>Bernard</li>
+      <li>Louis</li>
+    </ul>
+
+Renders an HTML list with the authors names. A separator can be specified through the third optional block:
+
+    Bernard,Louis
+
+Will render 'Bernard, Louis'.

data/spec/integration/examples/3-partials.txt

@@ -0,0 +1,76 @@
+# Partials
+
+Partials allows defining templating sections in external variables, such as the `hobby_entry_partial` variable above. The greater tag allows you to instantiate those partials:
+
+* greater (>) renders the partial denotes by an expression in the current scope
+
+For instance,
+
+    <ul>
+      <li><a href="http:&#47;&#47;reddit.com&#47;r&#47;programming">Programming</a></li>
+      <li><a href="http:&#47;&#47;www.music.me&#47;">Music</a></li>
+    </ul>
+
+will generate the hobby list with a link for each of my hobbies. As the scope inside the iteration is based on the currently iterated element, the hobby label and url are accessible inside the partial itself.
+
+# Advanced scoping example
+
+Suppose that, in the example above, you dont statically know what are the keys of an hobby hash. For instance, for each hobby you want to display an HTML table with every (key,value) pair. You could try something like this:
+
+    <ul>
+      <table>
+  <tr>
+    <th>key</th>
+    <th>value</th>
+  </tr>
+  <tr>
+    <td>label</td>
+    <td>Programming</td>
+  </tr>
+  <tr>
+    <td>url</td>
+    <td>http:&#47;&#47;reddit.com&#47;r&#47;programming</td>
+  </tr>
+</table>
+      <table>
+  <tr>
+    <th>key</th>
+    <th>value</th>
+  </tr>
+  <tr>
+    <td>label</td>
+    <td>Music</td>
+  </tr>
+  <tr>
+    <td>url</td>
+    <td>http:&#47;&#47;www.music.me&#47;</td>
+  </tr>
+</table>
+    </ul>
+
+The `hobby_entry_table` partial above iterates the hobby hash through `self`. Following ruby's `Hash#each` The scope inside that iteration is therefore an array of two elements, accessible under `first` and `last`.
+
+Another way, that uses wlang higher-level constructions, could be as follows:
+
+    <ul>
+      <table>
+  <tr>
+    <td>label</td>
+    <td>Programming</td>
+  </tr>
+  <tr>
+    <td>url</td>
+    <td>http:&#47;&#47;reddit.com&#47;r&#47;programming</td>
+  </tr>
+</table>
+      <table>
+  <tr>
+    <td>label</td>
+    <td>Music</td>
+  </tr>
+  <tr>
+    <td>url</td>
+    <td>http:&#47;&#47;www.music.me&#47;</td>
+  </tr>
+</table>
+    </ul>

data/spec/integration/examples/4-recursion.txt

@@ -0,0 +1,16 @@
+Now that we know how to use partials, one might ask how to render a menu in a recursive way. For this, we only need another tag for explicitely manipulating the scope.
+
+* sharp (#) renders its second block, in the scope of the value evaluated in first block
+
+For the example above, our menu rendering is initiated as follows:
+    <ul>
+  <li>About</li>
+  <li>Products</li>
+  <ul>
+  <li>WLang</li>
+  <li>Alf</li>
+  <li>Viiite</li>
+</ul>
+</ul>
+
+Note that it is important to keep empty menus in the source data to avoid infinite recursions due the parent scope that already binds a value under `menu`.

data/spec/integration/html/test_ampersand.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+require 'wlang/html'
+module WLang
+  describe Html, "&{...}" do
+
+    def render(tpl, scope = {})
+      Html.render(tpl, scope, "")
+    end
+
+    it 'escapes html' do
+      render("&{<script>}", binding).should eq("&lt;script&gt;")
+    end
+
+  end
+end

data/spec/integration/html/test_bang.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+require 'wlang/html'
+module WLang
+  describe Html, "!{...}" do
+
+    def render(tpl, scope = {})
+      Html.render(tpl, scope, "")
+    end
+
+    it 'invokes to_s' do
+      s = Struct.new(:to_s).new("World")
+      render("!{hello}", {:hello => s}).should eq("World")
+    end
+
+    it 'works with Numbers' do
+      render("!{hello}", {:hello => 12}).should eq("12")
+    end
+
+    it 'does not escape html' do
+      render("!{hello}", {:hello => "<script>"}).should eq("<script>")
+    end
+
+    it 'is not too sensitive to spacing' do
+      render("!{ hello }", {:hello => "World"}).should eq("World")
+    end
+
+    it 'supports a binding' do
+      hello = "World"
+      render("!{hello}", binding).should eq("World")
+    end
+
+    it 'supports chain invocations' do
+      s = Struct.new(:hello).new("World")
+      render("!{s.hello}", binding).should eq("World")
+    end
+
+  end
+end