Skip to content
Browse files

Enhance README, add section about sinatra.

  • Loading branch information...
1 parent de55385 commit 50b1c987c8db3f31743623ad225a2cfdd650618d @blambeau committed Jun 13, 2012
Showing with 105 additions and 54 deletions.
  1. +31 −54 README.md
  2. +54 −0 doc/semantics.md
  3. +20 −0 examples/2-sinatra/app.rb
View
85 README.md
@@ -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(hello_path.to_s, :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
-```
-
-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.
+ get '/' do
+ wlang :index, :locals => {:who => "world"}
+ end
-# Tilt integration
+ __END__
-WLang 2.0 has built-in support for [Tilt](https://github.com/rtomayko/tilt) facade to templating engines. In order to use that API:
+ @@layout
+ <html>
+ >{yield}
+ </html>
-```ruby
-require 'tilt' # needed in your bundle, not a wlang dependency
-require 'wlang' # loads Tilt support provided Tilt has already been required
+ @@index
+ Hello from a partial: >{partial}
-template = Tilt.new("path/to/a/template.wlang") # suppose 'Hello ${who}!'
-template.render(:who => "world")
-# => Hello world!
+ @@partial
+ yeah, a partial!
-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!</html>
View
54 doc/semantics.md
@@ -0,0 +1,54 @@
+## 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.
+
View
20 examples/2-sinatra/app.rb
@@ -0,0 +1,20 @@
+require 'sinatra'
+require 'wlang'
+
+get '/' do
+ wlang :index, :locals => {:who => "world"}
+end
+
+__END__
+
+@@layout
+ <html>
+ >{yield}
+ </html>
+
+@@index
+ Hello from a partial: >{partial}
+
+@@partial
+ yeah, a partial!
+

0 comments on commit 50b1c98

Please sign in to comment.
Something went wrong with that request. Please try again.