tilt 0.5 → 1.0

data/COPYING

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Ryan Tomayko <http://tomayko.com/about>
+Copyright (c) 2010 Ryan Tomayko <http://tomayko.com/about>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

data/README.md

@@ -13,7 +13,8 @@ feature is relevant to the engine):
  * Ability to pass locals to template evaluation
  * Support for passing a block to template evaluation for "yield"
  * Backtraces with correct filenames and line numbers
- * Template compilation caching and reloading
+ * Template file caching and reloading
+ * Fast, method-based template source compilation
 
 The primary goal is to get all of the things listed above right for all
 template engines included in the distribution.
@@ -29,9 +30,16 @@ Support for these template engines is included with the package:
     Less CSS                   .less             less
     Builder                    .builder          builder
     Liquid                     .liquid           liquid
-    Mustache                   .mustache         mustache
     RDiscount                  .markdown         rdiscount
     RedCloth                   .textile          redcloth
+    RDoc                       .rdoc             rdoc
+    Radius                     .radius           radius
+
+See [TEMPLATES.md][t] for detailed information on template engine
+options and supported features.
+
+[t]: http://github.com/rtomayko/tilt/blob/master/TEMPLATES.md
+   "Tilt Template Engine Documentation"
 
 Basic Usage
 -----------
@@ -139,8 +147,49 @@ Or, use BlueCloth for markdown instead of RDiscount:
 
     Tilt.register 'markdown', Tilt::BlueClothTemplate
 
+Template Compilation
+--------------------
+
+Tilt can compile generated Ruby source code produced by template engines and
+reuse on subsequent template invocations. Benchmarks show this yields a 5x-10x
+performance increase over evaluating the Ruby source on each invocation.
+
+Template compilation is currently supported for these template engines:
+StringTemplate, ERB, Erubis, Haml, and Builder.
+
+To enable template compilation, the `Tilt::CompileSite` module must be mixed in
+to the scope object passed to the template's `#render` method. This can be
+accomplished by including (with `Module#include`) the module in the class used
+for scope objects or by extending (with `Object#extend`) scope objects before
+passing to `Template#render`:
+
+    require 'tilt'
+
+    template = Tilt::ERBTemplate.new('foo.erb')
+
+    # Slow. Uses Object#instance_eval to process template
+    class Scope
+    end
+    scope = Scope.new
+    template.render(scope)
+
+    # Fast. Uses compiled template and Object#send to process template
+    class Scope
+      include Tilt::CompileSite
+    end
+    scope = Scope.new
+    template.render(scope)
+
+    # Also fast, though a bit a slower due to having to extend each time
+    scope = Object.new
+    scope.extend Tilt::CompileSite
+    template.render(scope)
+
+When the `Tilt::CompileSite` module is not present, template execution falls
+back to evaluating the template from source on each invocation.
+
 LICENSE
 -------
 
-Tilt is Copyright (c) 2009 [Ryan Tomayko](http://tomayko.com/about) and
-distributed under the MIT license. See the COPYING file for more info.
+Tilt is Copyright (c) 2010 [Ryan Tomayko](http://tomayko.com/about) and
+distributed under the MIT license. See the `COPYING` file for more info.

data/Rakefile

@@ -11,43 +11,50 @@ end
 desc 'Run tests (default)'
 Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/*_test.rb']
-  t.ruby_opts = ['-rubygems'] if defined? Gem
+  t.ruby_opts = ['-Itest']
+  t.ruby_opts << '-rubygems' if defined? Gem
 end
 
 # PACKAGING =================================================================
 
-require 'rubygems/specification'
-$spec ||= eval(File.read('tilt.gemspec'))
-
-def package(ext='')
-  "dist/tilt-#{$spec.version}" + ext
+begin
+  require 'rubygems'
+rescue LoadError
 end
 
-desc 'Build packages'
-task :package => %w[.gem .tar.gz].map {|e| package(e)}
+if defined?(Gem)
+  SPEC = eval(File.read('tilt.gemspec'))
 
-desc 'Build and install as local gem'
-task :install => package('.gem') do
-  sh "gem install #{package('.gem')}"
-end
+  def package(ext='')
+    "pkg/tilt-#{SPEC.version}" + ext
+  end
 
-directory 'dist/'
+  desc 'Build packages'
+  task :package => %w[.gem .tar.gz].map {|e| package(e)}
 
-file package('.gem') => %w[dist/ tilt.gemspec] + $spec.files do |f|
-  sh "gem build tilt.gemspec"
-  mv File.basename(f.name), f.name
-end
+  desc 'Build and install as local gem'
+  task :install => package('.gem') do
+    sh "gem install #{package('.gem')}"
+  end
 
-file package('.tar.gz') => %w[dist/] + $spec.files do |f|
-  sh "git archive --format=tar HEAD | gzip > #{f.name}"
-end
+  directory 'pkg/'
+
+  file package('.gem') => %w[pkg/ tilt.gemspec] + SPEC.files do |f|
+    sh "gem build tilt.gemspec"
+    mv File.basename(f.name), f.name
+  end
 
-desc 'Upload gem and tar.gz distributables to rubyforge'
-task :release => [package('.gem'), package('.tar.gz')] do |t|
-  sh <<-SH
-    rubyforge add_release sinatra tilt #{$spec.version} #{package('.gem')} &&
-    rubyforge add_file    sinatra tilt #{$spec.version} #{package('.tar.gz')}
-  SH
+  file package('.tar.gz') => %w[pkg/] + SPEC.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
+  desc 'Upload gem and tar.gz distributables to rubyforge'
+  task :release => [package('.gem'), package('.tar.gz')] do |t|
+    sh <<-SH
+      rubyforge add_release sinatra tilt #{SPEC.version} #{package('.gem')} &&
+      rubyforge add_file    sinatra tilt #{SPEC.version} #{package('.tar.gz')}
+    SH
+  end
 end
 
 # GEMSPEC ===================================================================
@@ -71,26 +78,3 @@ file 'tilt.gemspec' => FileList['{lib,test}/**','Rakefile'] do |f|
   File.open(f.name, 'w') { |io| io.write(spec) }
   puts "updated #{f.name}"
 end
-
-# DOC =======================================================================
-
-# requires the hanna gem:
-#   gem install mislav-hanna --source=http://gems.github.com
-desc 'Build API documentation (doc/api)'
-task 'rdoc' => 'rdoc/index.html' 
-file 'rdoc/index.html' => FileList['lib/**/*.rb'] do |f|
-  rm_rf 'rdoc'
-  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
-  hanna
-    --op doc/api
-    --promiscuous
-    --charset utf8
-    --fmt html
-    --inline-source
-    --line-numbers
-    --accessor option_accessor=RW
-    --main Tilt
-    --title 'Tilt API Documentation'
-    #{f.prerequisites.join(' ')}
-  SH
-end

data/TEMPLATES.md

@@ -9,7 +9,6 @@ documentation on each supported template engine is provided below.
  * [Erubis](#erubis) - `Tilt::ErubisTemplate`
  * [Haml](#haml) - `Tilt::HamlTemplate`
  * [Liquid](#liquid) - `Tilt::LiquidTemplate`
- * [Mustache](#mustache) - `Tilt::MustachTemplate`
 
 Tilt includes support for CSS processors like [lesscss](http://lesscss.org)
 and [sass](http://sass-lang.com/), in addition, it also supports simple
@@ -67,6 +66,12 @@ of any combination of the following characters:
 The `$SAFE` level; when set, ERB code will be run in a
 separate thread with `$SAFE` set to the provided level.
 
+#### `:outvar => '_erbout'`
+
+The name of the variable used to accumulate template output. This can be
+any valid Ruby expression but must be assignable. By default a local
+variable named `_erbout` is used.
+
 ### See also
 
   * [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
@@ -88,9 +93,22 @@ the extensions as follows:
 
 ### Options
 
-#### `:trim => true`
+#### `:engine_class => Erubis::Eruby`
 
-Delete spaces around '<% %>'. (But, spaces around '<%= %>' are preserved.)
+Allows you to specify a custom engine class to use instead of the
+default which is `Erubis::Eruby`.
+
+#### `:escape_html => false`
+
+When `true`, `Erubis::EscapedEruby` will be used as the engine class
+instead of the default. All content within `<%= %>` blocks will be
+automatically html escaped.
+
+#### `:outvar => '_erbout'`
+
+The name of the variable used to accumulate template output. This can be
+any valid Ruby expression but must be assignable. By default a local
+variable named `_erbout` is used.
 
 #### `:pattern => '<% %>'`
 
@@ -98,14 +116,17 @@ Set pattern for embedded Ruby code.
 
 See the [ERB](#erb) template documentation for examples, usage, and options.
 
-__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
-using this template engine within a threaded environment.
+#### `:trim => true`
+
+Delete spaces around '<% %>'. (But, spaces around '<%= %>' are preserved.)
 
 ### See also
 
   * [Erubis Home](http://www.kuwata-lab.com/erubis/)
   * [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
 
+__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
+using this template engine within a threaded environment.
 
 <a name='haml'></a>
 Haml (`haml`)
@@ -282,53 +303,6 @@ time when using this template engine within a threaded environment.
   * [Liquid Docs](http://liquid.rubyforge.org/)
   * GitHub: [tobi/liquid](http://github.com/tobi/liquid/)
 
-<a name='mustache'></a>
-Mustache (`mustache`)
----------------------
-
-Mustache is a framework-agnostic way to render logic-free views.
-
-__NOTE:__ It's suggested that your program `require 'mustache'` at load time
-when using this template engine in a threaded environment.
-
-### Options
-
-#### `:path => Dir.pwd`
-
-The base path where mustache templates (`.html` files) are located.  Defaults to
-the current working directory.
-
-#### `:template_extension => 'html'`
-
-The file extension used on mustache templates. Default is `'html'`.
-
-#### `:namespace => Object`
-
-The class or module where View classes are located. If you have
-`Hurl::App::Views`, namespace should be `Hurl:App`. This defaults to `Object`,
-causing `::Views` to be searched for classes.
-
-#### `:mustaches => nil`
-
-Where mustache views (.rb files) are located, or nil to disable auto-requiring
-of views based on template names. By default, the view file is assumed to be in
-the same directory as the template file.
-
-All other options are assumed to be attribute writer's on the Mustache
-class and are set when a template is compiled. They are:
-
-#### `:view => nil`
-
-The Mustache subclass that should be used a the view. When this option is
-specified, the template file will be determined from the view class, and the
-`:namespace` and `:mustaches` options are irrelevant.
-
-### See also
-
-  * [Mustache Docs](http://defunkt.github.com/mustache/)
-  * GitHub: [defunkt/mustache](http://github.com/defunkt/mustache)
-
-
 <a name='markdown'></a>
 Markdown (`markdown`, `md`, `mkd`)
 ----------------------------------
@@ -410,3 +384,56 @@ engine in a threaded environment.
 ### See also
 
  * [RDoc](http://rdoc.sourceforge.net/doc/index.html)
+
+
+<a name='radius'></a>
+Radius (`radius`)
+-----------------
+
+Radius is the template language used by Radiant CMS. It is a tag
+language designed to be valid XML/HTML.
+
+### Example
+
+    <html>
+    <body>
+      <h1><r:title /></h1>
+      <ul class="<r:type />">
+      <r:repeat times="3">
+        <li><r:hello />!</li>
+      </r:repeat>
+      </ul>
+      <r:yield />
+    </body>
+    </html>
+
+### Usage
+
+To render a template such as the one above.
+
+    scope = OpenStruct.new
+    scope.title = "Radius Example"
+    scope.hello = "Hello, World!"
+
+    require 'radius'
+    template = Tilt::RadiusTemplate.new('example.radius', :tag_prefix=>'r')
+    template.render(scope, :type=>'hlist'){ "Jackpot!" }
+
+The result will be:
+
+    <html>
+    <body>
+      <h1>Radius Example</h1>
+      <ul class="hlist">
+        <li>Hello, World!</li>
+        <li>Hello, World!</li>
+        <li>Hello, World!</li>
+      </ul>
+      Jackpot!
+    </body>
+    </html>
+
+### See also
+
+* [Radius](http://radius.rubyforge.org/)
+* [Radiant](http://radiantcms.org/)

data/bin/tilt

@@ -3,17 +3,21 @@ require 'ostruct'
 require 'optparse'
 require 'tilt'
 
-usage = <<EOF
-Usage: tilt [OPTIONS] [FILE]
-Process template FILE and generate output. With no FILE or when FILE
-is '-', read template from stdin and use the --type option to determine
-the template's type.
+usage = <<USAGE
+Usage: tilt <options> <file>
+Process template <file> and write output to stdout. With no <file> or
+when <file> is '-', read template from stdin and use the --type option
+to determine the template's type.
 
 Options
-  -l, --list           List supported template engines + file patterns and exit.
-  -t, --type=PATTERN   Use this template engine; required when FILE is stdin.
+  -l, --list           List template engines + file patterns and exit
+  -t, --type=<pattern> Use this template engine; required if no <file>
+  -y, --layout=<file>  Use <file> as a layout template
 
-  -h, --help           Show this help message.
+  -D<name>=<value>     Define variable <name> as <value>
+  -o, --vars=<ruby>    Evaluate <ruby> to Hash and use for variables
+
+  -h, --help           Show this help message
 
 Convert markdown to HTML:
   $ tilt foo.markdown > foo.html
@@ -21,11 +25,18 @@ Convert markdown to HTML:
 Process ERB template:
   $ echo "Answer: <%= 2 + 2 %>" | tilt -t erb
   Answer: 4
-EOF
+
+Define variables:
+  $ echo "Answer: <%= 2 + n %>" | tilt --locals="{:n=>40, :x=>0}"
+  Answer: 42
+  $ echo "Answer: <%= 2 + n %>" | tilt -Dn=40 -Dx=0
+  Answer: 42
+USAGE
 
 script_name = File.basename($0)
 pattern = nil
 layout = nil
+locals = {}
 
 ARGV.options do |o|
   o.program_name = script_name
@@ -44,18 +55,31 @@ ARGV.options do |o|
   end
 
   # the template type / pattern
-  o.on("-t", "--type=PATTERN") do |val|
-    fail "unknown template type: #{val}" if Tilt[val].nil?
+  o.on("-t", "--type=PATTERN", String) do |val|
+    abort "unknown template type: #{val}" if Tilt[val].nil?
     pattern = val
   end
 
   # pass template output into the specified layout template
-  o.on("-y", "--layout=FILE")  do |file|
+  o.on("-y", "--layout=FILE", String)  do |file|
     paths = [file, "~/.tilt/#{file}", "/etc/tilt/#{file}"]
     layout = paths.
       map  { |p| File.expand_path(p) }.
       find { |p| File.exist?(p) }
-    fail "no such layout: #{file}" if layout.nil?
+    abort "no such layout: #{file}" if layout.nil?
+  end
+
+  # define a local variable
+  o.on("-D", "--define=PAIR", String) do |pair|
+    key, value = pair.split(/[=:]/, 2)
+    locals[key.to_sym] = value
+  end
+
+  # define local variables using a Ruby hash
+  o.on("--vars=RUBY") do |ruby|
+    hash = eval(ruby)
+    abort "vars must be a Hash, not #{hash.inspect}" if !hash.is_a?(Hash)
+    hash.each { |key, value| locals[key.to_sym] = value }
   end
 
   o.on_tail("-h", "--help") { puts usage; exit }
@@ -65,17 +89,22 @@ end
 
 file = ARGV.first || '-'
 pattern = file if pattern.nil?
+abort "template type not given. see: #{$0} --help" if ['-', ''].include?(pattern)
+
+engine = Tilt[pattern]
+abort "template engine not found for: #{pattern}" if engine.nil?
+
 template =
-  Tilt[pattern].new(file) {
+  engine.new(file) {
     if file == '-'
       $stdin.read
     else
       File.read(file)
     end
   }
-output = template.render
+output = template.render(self, locals)
 
 # process layout
-output = Tilt.new(layout).render { output } if layout
+output = Tilt.new(layout).render(self, locals) { output } if layout
 
 $stdout.write(output)