tilt 0.6 → 0.9

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.
@@ -33,6 +34,12 @@ Support for these template engines is included with the package:
     RDiscount                  .markdown         rdiscount
     RedCloth                   .textile          redcloth
 
+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 +146,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

@@ -16,38 +16,44 @@ 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 +77,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

@@ -67,6 +67,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 +94,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 +117,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`)

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)