temple 0.2.0 → 0.3.0

data/.yardopts

@@ -1 +1,2 @@
---title Temple
+--title Temple
+--files EXPRESSIONS.md,CHANGES,LICENSE

data/CHANGES

@@ -0,0 +1,63 @@
+master
+
+  * Compiled expression dispatching
+  * Method temple_dispatch is obsolete
+  * EscapeHTML renamed to Escapable
+  * Control flow filter added
+  * HTML filter: Tag and attribute expressions changed
+  * Expression grammar added
+  * Expression validator added
+  * Debugger filter removed (Validator is better replacement)
+
+0.2.0
+
+  * Add mutable/immutable hashes for option inheritance
+  * Rails template support added
+  * Rename Filter#compile to Filter#call
+  * Engine chain reconfiguration (append, prepend, replace, ...)
+  * HTML filter: Don't output empty attributes
+  * Escape expression changed [:escape, true/false, Expression]
+
+0.1.8
+
+  * HTML filter: Support :format => :html (alias for :html5)
+
+0.1.7
+
+  * HTML::Pretty indents dynamic content only if it doesn't contain
+    preformatted tags
+
+0.1.6
+
+  * Flexible chain building
+
+0.1.5
+
+  * Default options for engines
+
+0.1.4
+
+  * HTML::Pretty added
+  * Tilt-based template class added
+  * Escaping filter added
+  * Filter base class added
+  * Fix capturing (Issue #15)
+
+0.1.3
+
+  * Close issue #10
+  * Refactoring
+
+0.1.2
+
+  * Add HTML filter
+  * Remove Escapable filter
+  * Add method for checking if expression is empty
+
+0.1.1
+
+  * Test added  
+
+0.1.0
+
+  * Initial release

data/EXPRESSIONS.md

@@ -0,0 +1,250 @@
+Temple expression documentation
+===============================
+
+Temple uses S-expressions to represent the parsed template code. The S-expressions
+are passed from filter to filter until the generator. The generator transforms
+the S-expression to a ruby code string. See the {file:README.md README} for an introduction.
+
+In this document we documented all the expressions which are used by Temple. There is also
+a formal grammar which can validate expressions.
+
+The Core Abstraction
+--------------------
+
+The core abstraction is what every template evetually should be compiled
+to. Currently it consists of six types:
+multi, static, dynamic, code, newline and capture.
+
+When compiling, there's two different strings we'll have to think about.
+First we have the generated code. This is what your engine (from Temple's
+point of view) spits out. If you construct this carefully enough, you can
+make exceptions report correct line numbers, which is very convenient.
+
+Then there's the result. This is what your engine (from the user's point
+of view) spits out. It's what happens if you evaluate the generated code.
+
+### [:multi, *sexp]
+
+Multi is what glues everything together. It's simply a sexp which combines
+several others sexps:
+
+    [:multi,
+      [:static, "Hello "],
+      [:dynamic, "@world"]]
+
+### [:static, string]
+
+Static indicates that the given string should be appended to the result.
+
+Example:
+
+    [:static, "Hello World"]
+is the same as:
+    _buf << "Hello World"
+
+    [:static, "Hello \n World"]
+is the same as
+    _buf << "Hello\nWorld"
+
+### [:dynamic, ruby]
+
+Dynamic indicates that the given Ruby code should be evaluated and then
+appended to the result.
+
+The Ruby code must be a complete expression in the sense that you can pass
+it to eval() and it would not raise SyntaxError.
+
+Example:
+
+     [:dynamic, 'Math::PI * r**2']
+
+### [:code, ruby]
+
+Code indicates that the given Ruby code should be evaluated, and may
+change the control flow. Any \n causes a newline in the generated code.
+
+Example:
+
+     [:code, 'area = Math::PI * r**2']
+
+### [:newline]
+
+Newline causes a newline in the generated code, but not in the result.
+
+### [:capture, variable_name, sexp]
+
+Evaluates the Sexp using the rules above, but instead of appending to the
+result, it sets the content to the variable given.
+
+Example:
+
+    [:multi,
+      [:static, "Some content"],
+      [:capture, "foo", [:static, "More content"]],
+      [:dynamic, "foo.downcase"]]
+is the same as:
+    _buf << "Some content"
+    foo = "More content"
+    _buf << foo.downcase
+
+Control flow abstraction
+------------------------
+
+Control flow abstractions can be used to write common ruby control flow constructs.
+These expressions are compiled to [:code, ruby] by Temple::Filters::ControlFlow
+
+### [:if, condition, if-sexp, optional-else-sexp]
+
+Example:
+
+    [:if,
+     "1+1 == 2",
+     [:static, "Yes"],
+     [:static, "No"]]
+is the same as:
+    if 1+1 == 2
+      _buf << "Yes"
+    else
+      _buf << "No"
+    end
+
+### [:block, ruby, sexp]
+
+Example:
+
+    [:block,
+     '10.times do',
+     [:static, 'Hello']]
+is the same as:
+    10.times do
+      _buf << 'Hello'
+    end
+
+### [:case, argument, [condition, sexp], [condition, sexp], ...]
+
+Example:
+
+    [:case,
+     'value',
+     ["1",   "value is 1"],
+     ["2",   "value is 2"],
+     [:else, "don't know"]]
+is the same as:
+    case value
+    when 1
+      _buf << "value is 1"
+    when 2
+      _buf << "value is 2"
+    else
+      _buf << "don't know"
+    end
+
+### [:cond, [condition, sexp], [condition, sexp], ...]
+
+    [:cond,
+     ["a",   "a is true"],
+     ["b",   "b is true"],
+     [:else, "a and b are false"]]
+is the same as:
+    case
+    when a
+      _buf << "a is true"
+    when b
+      _buf << "b is true"
+    else
+      _buf << "a and b are false"
+    end
+
+Escape abstraction
+------------------
+
+The Escape abstraction is processed by Temple::Filters::Escapable.
+
+### [:escape, bool, sexp]
+
+The boolean flag switches escaping on or off for the content sexp. Dynamic and static
+expressions are manipulated.
+
+Example:
+
+    [:escape, true,
+     [:multi,
+      [:dynamic, "code"],
+      [:static, "<"],
+      [:escape, false, [:static, ">"]]]]
+is transformed to
+    [:multi,
+     [:dynamic, 'escape_html(code)'],
+     [:static, '&lt;'],
+     [:static, '>']]
+
+HTML abstraction
+----------------
+
+The HTML abstraction is processed by the html filters (Temple::HTML::Fast and Temple::HTML::Pretty).
+
+### [:html, :doctype, string]
+
+Example:
+    [:html, :doctype, '5']
+generates
+    <!DOCTYPE html5>
+
+Supported doctypes:
+
+<table>
+<tr><td><b>Name</b></td><td><b>Generated doctype</b></td></tr>
+<tr><td>1.1</td><td>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"&gt;</td></tr>
+<tr><td>html, 5</td><td>&lt;!DOCTYPE html></td></tr>
+<tr><td>strict</td><td>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;</td></tr>
+<tr><td>frameset</td><td>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd"&gt;</td></tr>
+<tr><td>mobile</td><td>&lt;!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd"&gt;</td></tr>
+<tr><td>basic</td><td>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"&gt;</td></tr>
+<tr><td>transitional</td><td>&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;</td></tr>
+</table>
+
+### [:html, :comment, sexp]
+
+Example:
+    [:html, :comment, [:static, 'comment']]
+generates:
+    <!--comment-->
+
+### [:html, :tag, identifier, attributes, optional-sexp]
+
+HTML tag abstraction. Identifier can be a String or a Symbol. If the optional content Sexp is omitted
+the tag is closed (e.g. <br/> <img/>). The tag is also closed if the content Sexp is empty
+(consists only of :multi and :newline expressions) and the tag is registered as auto-closing.
+
+Example:
+    [:html, :tag, 'img', [:html, :attrs, [:html, :attr, 'src', 'image.png']]]
+    [:html, :tag, 'p', [:multi], [:static, 'Content']]
+generates:
+    <img src="image.png"/>
+    <p>Content</p>
+
+### [:html, :attrs, attributes]
+
+List of html attributes [:html, :attr, identifier, sexp]
+
+### [:html, :attr, identifier, sexp]
+
+HTML attribute abstraction. Identifier can be a String or a Symbol.
+
+Formal grammar
+--------------
+
+Validate expressions with Temple::Grammar.match? and Temple::Grammar.validate!
+
+    Temple::Grammar.match? [:multi, [:static, 'Valid Temple Expression']]
+    Temple::Grammar.validate! [:multi, 'Invalid Temple Expression']
+
+The formal grammar is given in a Ruby DSL similar to EBNF and should be easy to understand if you know EBNF. Repeated tokens
+are given by appending ?, * or + as in regular expressions.
+
+* ? means zero or one occurence
+* \* means zero or more occurences
+* \+ means one or more occurences
+
+<!-- Find a better way to include the grammar -->
+<script src="http://gist-it.appspot.com/github/judofyr/temple/raw/master/lib/temple/grammar.rb"></script>

data/README.md

@@ -12,13 +12,15 @@ we'll try to do our best. In fact, it doesn't have to be related to Temple at
 all. As long as it has something to do with template languages, we're
 interested: <http://groups.google.com/group/guardians-of-the-temple>.
 
-Meta
-----
-
-* Home: <http://github.com/judofyr/temple>
-* Bugs: <http://github.com/judofyr/temple/issues>
-* List: <http://groups.google.com/group/guardians-of-the-temple>
+Links
+-----
 
+* Source: <http://github.com/judofyr/temple>
+* Bugs:   <http://github.com/judofyr/temple/issues>
+* List:   <http://groups.google.com/group/guardians-of-the-temple>
+* API documentation:
+    * Latest Gem: <http://rubydoc.info/gems/temple/frames>
+    * GitHub master: <http://rubydoc.info/github/judofyr/temple/master/frames>
 
 Overview
 --------
@@ -27,7 +29,7 @@ Temple is built on a theory that every template consists of three elements:
 
 * Static text
 * Dynamic text (pieces of Ruby which are evaluated and sent to the client)
-* Blocks (pieces of Ruby which are evaluated and *not* sent to the client, but
+* Codes (pieces of Ruby which are evaluated and *not* sent to the client, but
   might change the control flow).
 
 The goal of a template engine is to take the template and eventually compile
@@ -37,9 +39,9 @@ it into *the core abstraction*:
       [:static, "Hello "],
       [:dynamic, "@user.name"],
       [:static, "!\n"],
-      [:block, "if @user.birthday == Date.today"],
+      [:code, "if @user.birthday == Date.today"],
       [:static, "Happy birthday!"],
-      [:block, "end"]]
+      [:code, "end"]]
 
 Then you can apply some optimizations, feed it to Temple and it generates fast
 Ruby code for you:
@@ -71,7 +73,7 @@ Some examples:
       [:static, "Hello "],
       [:dynamic, "@world"]]
 
-    [:html, :tag, "em", "Hey hey"]
+    [:html, :tag, "em", [:html, :attrs], [:static, "Hey hey"]]
 
 *NOTE:* SexpProcessor, a library written by Ryan Davis, includes a `Sexp`
 class. While you can use this class (since it's a subclass of Array), it's not
@@ -91,7 +93,7 @@ So what's an abstraction? An abstraction is when you introduce a new types:
     [:static, "<strong>Use the force</strong>"]
 
     # You use:
-    [:html, :tag, "strong", [:static, "Use the force"]]
+    [:html, :tag, "strong", [:html, :attrs], [:static, "Use the force"]]
 
 ### Why are abstractions so important?
 
@@ -111,6 +113,7 @@ continue to use the HTML abstraction. Maybe you even want to write your
 compiler in another language? Sexps are easily serialized and if you don't
 mind working across processes, it's not a problem at all.
 
+All abstractions used by Temple are documented in {file:EXPRESSIONS.md EXPRESSIONS}.
 
 Compilers
 ---------
@@ -214,12 +217,21 @@ Rails.
     Tilt.new('example.ext').render     # => Render a file
     MyTemplate.new { "String" }.render # => Render a string
 
-
 Installation
 ------------
 
+You need Ruby 1.8.7 or Ruby 1.9.2 to work with Temple. Temple is published as a Ruby Gem which can be installed
+as following:
+
     $ gem install temple
 
+Engines using Temple
+--------------------
+
+* Temple ERB example implementation (Temple::ERB::Template)
+* [Slim](http://github.com/stonean/slim)
+* [Sal](http://github.com/stonean/sal.rb)
+* [Temple-Mustache (Example implementation)](https://github.com/minad/temple-mustache)
 
 Acknowledgements
 ----------------

data/lib/temple.rb

@@ -1,31 +1,47 @@
 require 'temple/version'
 
 module Temple
-  autoload :Generator,        'temple/generators'
-  autoload :Generators,       'temple/generators'
-  autoload :Engine,           'temple/engine'
-  autoload :Utils,            'temple/utils'
-  autoload :Mixins,           'temple/mixins'
-  autoload :Filter,           'temple/filter'
-  autoload :Templates,        'temple/templates'
+  autoload :InvalidExpression, 'temple/generators'
+  autoload :Generator,         'temple/generators'
+  autoload :Generators,        'temple/generators'
+  autoload :Engine,            'temple/engine'
+  autoload :Utils,             'temple/utils'
+  autoload :Filter,            'temple/filter'
+  autoload :Templates,         'temple/templates'
+  autoload :Grammar,           'temple/grammar'
+  autoload :ImmutableHash,     'temple/hash'
+  autoload :MutableHash,       'temple/hash'
+
+  module Mixins
+    autoload :Dispatcher,      'temple/mixins/dispatcher'
+    autoload :EngineDSL,       'temple/mixins/engine_dsl'
+    autoload :GrammarDSL,      'temple/mixins/grammar_dsl'
+    autoload :Options,         'temple/mixins/options'
+    autoload :DefaultOptions,  'temple/mixins/options'
+    autoload :Template,        'temple/mixins/template'
+  end
 
   module ERB
-    autoload :Engine,         'temple/erb/engine'
-    autoload :Parser,         'temple/erb/parser'
-    autoload :Trimming,       'temple/erb/trimming'
+    autoload :Engine,          'temple/erb/engine'
+    autoload :Parser,          'temple/erb/parser'
+    autoload :Trimming,        'temple/erb/trimming'
+    autoload :Template,        'temple/erb/template'
   end
 
   module Filters
-    autoload :MultiFlattener, 'temple/filters/multi_flattener'
-    autoload :StaticMerger,   'temple/filters/static_merger'
-    autoload :DynamicInliner, 'temple/filters/dynamic_inliner'
-    autoload :EscapeHTML,     'temple/filters/escape_html'
-    autoload :Debugger,       'temple/filters/debugger'
+    autoload :ControlFlow,     'temple/filters/control_flow'
+    autoload :MultiFlattener,  'temple/filters/multi_flattener'
+    autoload :StaticMerger,    'temple/filters/static_merger'
+    autoload :DynamicInliner,  'temple/filters/dynamic_inliner'
+    autoload :Escapable,       'temple/filters/escapable'
+    autoload :Eraser,          'temple/filters/eraser'
+    autoload :Validator,       'temple/filters/validator'
   end
 
   module HTML
-    autoload :Dispatcher,     'temple/html/dispatcher'
-    autoload :Fast,           'temple/html/fast'
-    autoload :Pretty,         'temple/html/pretty'
+    autoload :Dispatcher,      'temple/html/dispatcher'
+    autoload :Filter,          'temple/html/filter'
+    autoload :Fast,            'temple/html/fast'
+    autoload :Pretty,          'temple/html/pretty'
   end
 end