temple 0.0.1 → 0.1.0

data/.yardopts

@@ -0,0 +1 @@
+--title Temple

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Magnus Holm
+
+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 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/README.md

@@ -0,0 +1,246 @@
+Temple
+======
+
+Temple is an abstraction and a framework for compiling templates to pure Ruby.
+It's all about making it easier to experiment, implement and optimize template
+languages. If you're interested in implementing your own template language, or
+anything else related to the internals of a template engine: You've come to
+the right place.
+
+Have a look around, and if you're still wondering: Ask on the mailing list and
+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>
+* Core abstraction: {Temple::Core}
+
+
+Overview
+--------
+
+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 
+  might change the control flow).
+
+The goal of a template engine is to take the template and eventually compile
+it into *the core abstraction*:
+
+    [:multi,
+      [:static, "Hello "],
+      [:dynamic, "@user.name"],
+      [:static, "!\n"],
+      [:block, "if @user.birthday == Date.today"],
+      [:static, "Happy birthday!"],
+      [:block, "end"]]
+
+Then you can apply some optimizations, feed it to Temple and it generates fast
+Ruby code for you:
+
+    _buf = []
+    _buf << ("Hello #{@user.name}!\n")
+    if @user.birthday == Date.today
+      _buf << "Happy birthday!"
+    end
+    _buf.join
+
+S-expression
+------------
+
+In Temple, an Sexp is simply an array (or a subclass) where the first element
+is the *type* and the rest are the *arguments*. The type must be a symbol and
+it's recommended to only use strings, symbols, arrays and numbers as
+arguments.
+
+Temple uses Sexps to represent templates because it's a simple and
+straightforward data structure, which can easily be written by hand and
+manipulated by computers.
+
+Some examples:
+    
+    [:static, "Hello World!"]
+    
+    [:multi,
+      [:static, "Hello "],
+      [:dynamic, "@world"]]
+    
+    [:html, :tag, "em", "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
+what Temple mean by "Sexp".
+
+Abstractions
+------------
+
+The idea behind Temple is that abstractions are good, and it's better to have
+too many than too few. While you should always end up with the core
+abstraction, you shouldn't stress about it. Take one step at a time, and only
+do one thing at every step.
+
+So what's an abstraction? An abstraction is when you introduce a new types:
+
+    # Instead of:
+    [:static, "<strong>Use the force</strong>"]
+    
+    # You use:
+    [:html, :tag, "strong", [:static, "Use the force"]]
+
+### Why are abstractions so important?
+
+First of all, it means that several template engines can share code. Instead
+of having two engines which goes all the way to generating HTML, you have two
+smaller engines which only compiles to the HTML abstraction together with
+something that compiles the HTML abstraction to the core abstraction.
+
+Often you also introduce abstractions because there's more than one way to do
+it. There's not a single way to generate HTML. Should it be indented? If so,
+with tabs or spaces? Or should it remove as much whitespace as possible?
+Single or double quotes in attributes? Escape all weird UTF-8 characters?
+
+With an abstraction you can easily introduce a completely new HTML compiler,
+and whatever is below doesn't have to care about it *at all*. They just
+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.
+
+
+Compilers
+---------
+
+A *compiler* is simply an object which responds a method called #compile which
+takes one argument and returns a value. It's illegal for a compiler to mutate
+the argument, and it should be possible to use the same instance several times
+(although not by several threads at the same time).
+
+While a compiler can be any object, you very often want to structure it as a
+class. Temple then assumes the initializer takes an optional option hash:
+
+    class MyCompiler
+      def initialize(options = {})
+        @options = options
+      end
+      
+      def compile(exp)
+        # do stuff
+      end
+    end
+
+### Parsers
+
+In Temple, a parser is also a compiler, because a compiler is just something
+that takes some input and produces some output. A parser is then something
+that takes a string and returns an Sexp.
+
+It's important to remember that the parser *should be dumb*. No optimization,
+no guesses. It should produce an Sexp that is as close to the source as
+possible. You should invent your own abstraction. Maybe you even want to
+separate the parsers into several parts and introduce several abstractions on
+the way?
+
+### Filters
+
+A filter is a compiler which take an Sexp and returns an Sexp. It might turn
+convert it one step closer to the core-abstraction, it might create a new
+abstraction, or it might just optimize in the current abstraction. Ultimately,
+it's still just a compiler which takes an Sexp and returns an Sexp.
+
+For instance, Temple ships with {Temple::Filters::DynamicInliner} and
+{Temple::Filters::StaticMerger} which are general optimization filters which
+works on the core abstraction.
+
+An HTML compiler would be a filter, since it would take an Sexp in the HTML
+abstraction and compile it down to the core abstraction.
+
+### Generators
+
+A generator is a compiler which takes an Sexp and returns a string which is
+valid Ruby code.
+
+Most of the time you would just use {Temple::Core::ArrayBuffer} or any of the
+other generators in {Temple::Core}, but nothing stops you from writing your
+own.
+
+In fact, one of the great things about Temple is that if you write a new
+generator which turns out to be a lot faster then the others, it's going to
+make *every single engine* based on Temple faster! So if you have any ideas,
+please share them - it's highly appreciated.
+
+Engines
+-------
+
+When you have a chain of a parsers, some filters and a generator you can finally create your *engine*. Temple provides {Temple::Engine} which makes this very easy:
+
+    class MyEngine < Temple::Engine
+      # First run MyParser, passing the :strict option
+      use MyParser, :strict
+      
+      # Then a custom filter
+      use MyFilter
+      
+      # Then some general optimizations filters
+      filter :MultiFlattener
+      filter :StaticMerger
+      filter :DynamicInliner
+      
+      # Finally the generator
+      generator :ArrayBuffer, :buffer
+    end
+    
+    engine = MyEngine.new(:strict => "For MyParser")
+    engine.compile(something)
+
+And then?
+---------
+
+You've ran the template through the parser, some filters and in the end a
+generator. What happens next?
+
+Temple's mission ends here, so it's all up to you, but we recommend using
+[Tilt](http://github.com/rtomayko/tilt), the generic interface to Ruby
+template engines. This gives you a wide range of features and your engine can
+be used right away in many projects.
+
+    require 'tilt'
+    
+    class MyTemplate < Tilt::Template
+      def prepare
+        @src = MyEngine.new(options).compile(data)
+      end
+
+      def template_source
+        @src
+      end
+    end
+    
+    # Register your file extension:
+    Tilt.register 'ext', MyTemplate
+    
+    Tilt.new('example.ext').render     # => Render a file
+    MyTemplate.new { "String" }.render # => Render a string
+    
+
+Installation
+------------
+
+    $ gem install temple
+
+    
+Acknowledgements
+----------------
+
+Thanks to [_why](http://en.wikipedia.org/wiki/Why_the_lucky_stiff) for
+creating an excellent template engine (Markaby) which is quite slow. That's
+how I started experimenting with template engines in the first place.
+
+I also owe [Ryan Davis](http://zenspider.com/) a lot for his excellent
+projects ParserTree, RubyParser, Ruby2Ruby and SexpProcessor. Temple is
+heavily inspired by how these tools work.

data/Rakefile

@@ -1,20 +1,20 @@
-task :default => :spec
-require 'spec/rake/spectask'
-Spec::Rake::SpecTask.new {|t| t.spec_opts = ['--color']}
+require 'rake/testtask'
 
+def command?(command)
+  system("type #{command} > /dev/null")
+end
 
-begin
-  project = 'temple'
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = project
-    gem.summary = "Template compilation framework in Ruby"
-    gem.email = "judofyr@gmail.com"
-    gem.homepage = "http://github.com/judofyr/#{project}"
-    gem.authors = ["Magnus Holm"]
-  end
+task :default => :test
 
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+if RUBY_VERSION[0,3] == "1.8" and command?("turn")
+  task :test do
+    suffix = "-n #{ENV['TEST']}" if ENV['TEST']
+    sh "turn test/test_*.rb test/**/test_*.rb #{suffix}"
+  end
+else
+  Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.pattern = 'test/**/test_*.rb'
+    t.verbose = false
+  end
 end

data/lib/temple.rb

@@ -1,9 +1,14 @@
 module Temple
-  VERSION = File.read( File.join(File.dirname(__FILE__),'..','VERSION') ).strip.split('.').map{|i|i.to_i}
+  VERSION = "0.0.1"
   
   autoload :Core,       'temple/core'
   autoload :Engine,     'temple/engine'
   autoload :Generator,  'temple/generator'
+  autoload :Utils,      'temple/utils'
+  
+  module Engines
+    autoload :ERB,      'temple/engines/erb'
+  end
   
   module Parsers
     autoload :ERB,      'temple/parsers/erb'
@@ -12,6 +17,7 @@ module Temple
   
   module Filters
     autoload :Mustache,       'temple/filters/mustache'
+    autoload :MultiFlattener, 'temple/filters/multi_flattener'
     autoload :StaticMerger,   'temple/filters/static_merger'
     autoload :DynamicInliner, 'temple/filters/dynamic_inliner'
     autoload :Escapable,      'temple/filters/escapable'

data/lib/temple/core.rb

@@ -1,5 +1,83 @@
 module Temple
+  # == The Core Abstraction
+  #            
+  # The core abstraction is what every template evetually should be compiled
+  # to. Currently it consists of four essential and two convenient types:
+  # multi, static, dynamic, block, 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.
+  # Every \n will be also cause a newline in the generated code. \r\n on the
+  # other hand, only causes a newline in the result.
+  #       
+  # Example:
+  #       
+  #   [:static, "Hello World"]
+  #   # is the same as:
+  #   _buf << "Hello World"
+  #         
+  #   [:static, "Hello \n World"]
+  #   # is the same as:
+  #   _buf << "Hello
+  #   World"
+  #         
+  #   [:static, "Hello \r\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. Any \n causes a newline in the generated code.
+  #     
+  # The Ruby code must be a complete expression in the sense that you can pass
+  # it to eval() and it would not raise SyntaxError.
+  #      
+  # === [:block, ruby]
+  #     
+  # Block indicates that the given Ruby code should be evaluated, and may
+  # change the control flow. Any \n causes a newline in the generated code.
+  #     
+  # === [: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
   module Core
+    # Implements an array buffer.
+    # 
     #   _buf = []
     #   _buf << "static"
     #   _buf << dynamic
@@ -8,19 +86,19 @@ module Temple
     #   end
     #   _buf.join
     class ArrayBuffer < Generator
-      def preamble;  buffer " = []\n" end
+      def preamble;  buffer " = []" end
       def postamble; buffer ".join"   end
       
       def on_static(text)
-        buffer " << #{text.inspect}\n"
+        to_ruby(text)
       end
       
       def on_dynamic(code)
-        buffer " << (#{code})\n"
+        code
       end
       
       def on_block(code)
-        code + "\n"
+        code
       end
     end
     
@@ -29,6 +107,8 @@ module Temple
       def postamble; buffer; end
     end
     
+    # Implements a string buffer.
+    # 
     #   _buf = ''
     #   _buf << "static"
     #   _buf << dynamic.to_s
@@ -37,47 +117,15 @@ module Temple
     #   end
     #   _buf
     class StringBuffer < ArrayBuffer
-      def preamble;  buffer " = ''\n" end
+      def preamble;  buffer " = ''" end
       def postamble; buffer end
       
       def on_dynamic(code)
-        buffer " << (#{code}).to_s\n"
-      end
-    end
-    
-    # Compiles into a single double-quoted string.
-    #
-    # This doesn't make so much sense when you have blocks, so it's
-    # kinda funky.  You probably want to use Filters::DynamicInliner instead.
-    # For now, check out the source for #on_multi.
-    class Interpolation < Generator
-      def preamble;  '"' end
-      def postamble; '"' end
-      
-      def on_static(text)
-        text.inspect[1..-2]
-      end
-      
-      def on_dynamic(code)
-        '#{%s}' % code
-      end
-      
-      def on_multi(*exps)
-        if exps.detect { |exp| exp[0] == :block }
-          '#{%s}' % exps.map do |exp|
-            if exp[0] == :block
-              exp[1]
-            else
-              compile(exp)
-            end
-          end.join
+        if @options[:check_literal] && Utils.literal_string?(code)
+          code
         else
-          super
-        end  
-      end
-      
-      def on_block(code)
-        '#{%s;nil}' % code
+          "(#{code}).to_s"
+        end
       end
     end
   end