RubyGems - haml - Versions diffs - 1.7.2 → 1.8.0 - Mend

haml 1.7.2 → 1.8.0

Potentially problematic release.

This version of haml might be problematic. Click here for more details.

Files changed (71) hide show

data/README +17 -9
data/Rakefile +12 -4
data/VERSION +1 -1
data/init.rb +1 -6
data/lib/haml.rb +65 -7
data/lib/haml/buffer.rb +49 -84
data/lib/haml/engine.rb +155 -797
data/lib/haml/error.rb +3 -33
data/lib/haml/exec.rb +86 -65
data/lib/haml/filters.rb +57 -27
data/lib/haml/helpers.rb +52 -9
data/lib/haml/helpers/action_view_mods.rb +1 -1
data/lib/haml/html.rb +20 -5
data/lib/haml/precompiler.rb +671 -0
data/lib/haml/template.rb +20 -73
data/lib/haml/template/patch.rb +51 -0
data/lib/haml/template/plugin.rb +21 -0
data/lib/sass.rb +78 -3
data/lib/sass/constant.rb +45 -19
data/lib/sass/constant.rb.rej +42 -0
data/lib/sass/constant/string.rb +4 -0
data/lib/sass/css.rb +162 -39
data/lib/sass/engine.rb +38 -14
data/lib/sass/plugin.rb +79 -44
data/lib/sass/tree/attr_node.rb +12 -11
data/lib/sass/tree/comment_node.rb +9 -3
data/lib/sass/tree/directive_node.rb +51 -0
data/lib/sass/tree/node.rb +13 -6
data/lib/sass/tree/rule_node.rb +34 -12
data/test/benchmark.rb +85 -52
data/test/haml/engine_test.rb +172 -84
data/test/haml/helper_test.rb +31 -3
data/test/haml/html2haml_test.rb +60 -0
data/test/haml/markaby/standard.mab +52 -0
data/test/haml/results/eval_suppressed.xhtml +4 -1
data/test/haml/results/helpers.xhtml +15 -4
data/test/haml/results/just_stuff.xhtml +9 -1
data/test/haml/results/standard.xhtml +0 -1
data/test/haml/rhtml/_av_partial_1.rhtml +12 -0
data/test/haml/rhtml/_av_partial_2.rhtml +8 -0
data/test/haml/rhtml/action_view.rhtml +62 -0
data/test/haml/rhtml/standard.rhtml +0 -1
data/test/haml/template_test.rb +41 -21
data/test/haml/templates/_av_partial_1.haml +9 -0
data/test/haml/templates/_av_partial_2.haml +5 -0
data/test/haml/templates/action_view.haml +47 -0
data/test/haml/templates/eval_suppressed.haml +1 -0
data/test/haml/templates/helpers.haml +9 -3
data/test/haml/templates/just_stuff.haml +10 -1
data/test/haml/templates/partials.haml +1 -1
data/test/haml/templates/standard.haml +0 -1
data/test/profile.rb +2 -2
data/test/sass/engine_test.rb +113 -3
data/test/sass/engine_test.rb.rej +18 -0
data/test/sass/plugin_test.rb +34 -11
data/test/sass/results/compact.css +1 -1
data/test/sass/results/complex.css +1 -1
data/test/sass/results/compressed.css +1 -0
data/test/sass/results/constants.css +3 -1
data/test/sass/results/expanded.css +2 -1
data/test/sass/results/import.css +2 -0
data/test/sass/results/nested.css +2 -1
data/test/sass/templates/_partial.sass +2 -0
data/test/sass/templates/compact.sass +2 -0
data/test/sass/templates/complex.sass +1 -0
data/test/sass/templates/compressed.sass +15 -0
data/test/sass/templates/constants.sass +9 -0
data/test/sass/templates/expanded.sass +2 -0
data/test/sass/templates/import.sass +1 -1
data/test/sass/templates/nested.sass +2 -0
metadata +22 -2

data/README CHANGED

@@ -233,16 +233,24 @@ the documentation for the Sass module.
 == Authors
-Haml and Sass are designed by Hampton Catlin (hcatlin).
-Help with the Ruby On Rails implementation and much of the documentation
-by Jeff Hardy (packagethief).
+Haml and Sass are designed by Hampton Catlin (hcatlin) and he is the author
+of the original implementation. However, Hampton doesn't even know his way
+around the code anymore and mostly just concentrates on the language issues.
+Hampton lives in Toronto, Ontario (though he's an American by birth) and
+is a partner at Unspace Interactive.
-Nathan Weizenbaum (Nex3) contributed the buffered-engine code to Haml,
-along with many other enhancements
-(including the silent-line syntax: "-").
-He continues to actively work on both Haml and Sass.
+Nathan Weizenbaum is the primary maintainer and architect of the "modern" Ruby
+implementation of Haml. His hard work has kept the project alive by endlessly
+answering forum posts, fixing bugs, refactoring, finding speed improvements,
+writing documentation, implementing new features, and getting Hampton
+coffee (a fitting task for a boy-genius). Nathan lives in Seattle, Washington and
+while not being a student at University of Washington he consults for
+Unspace Interactive and Microsoft.
+If you use this software, you must pay Hampton a compliment. And
+buy Nathan some jelly beans. Maybe pet a kitten. Yeah. Pet that kitty.
+Some of the work on Haml was supported by Unspace Interactive.
-If you use this software, you must pay Hampton a compliment.
-Say something nice about it.
 Beyond that, the implementation is licensed under the MIT License.
 Ok, fine, I guess that means compliments aren't *required*.

data/Rakefile CHANGED

@@ -22,11 +22,9 @@ desc temp_desc.chomp
 task :benchmark do
   require 'test/benchmark'
-  puts '-'*51, "Benchmark: Haml vs. ERb", '-'*51
-  puts "Running benchmark #{ENV['TIMES']} times..." if ENV['TIMES']
+  puts "Running benchmarks #{ENV['TIMES']} times..." if ENV['TIMES']
   times = ENV['TIMES'].to_i if ENV['TIMES']
-  benchmarker = Haml::Benchmarker.new
-  puts benchmarker.benchmark(times || 100)
+  Haml.benchmark(times || 100)
   puts '-'*51
 end
@@ -99,6 +97,16 @@ unless ARGV[0] == 'benchmark'
     sh %{gem install --no-ri pkg/haml-#{File.read('VERSION').strip}}
   end
+  task :release => [:package] do
+    name, version = ENV['NAME'], ENV['VERSION']
+    raise "Must supply NAME and VERSION for release task." unless name && version
+    sh %{rubyforge login}
+    sh %{rubyforge add_release haml haml "#{name} (v#{version})" pkg/haml-#{version}.gem}
+    sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.tar.gz}
+    sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.tar.bz2}
+    sh %{rubyforge add_file    haml haml "#{name} (v#{version})" pkg/haml-#{version}.zip}
+  end
   # ----- Documentation -----
   require 'rake/rdoctask'

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 1.7.2
1	+ 1.8.0

data/init.rb CHANGED

@@ -1,7 +1,2 @@
 require 'haml'
-require 'haml/template'
-require 'sass'
-require 'sass/plugin'
-ActionView::Base.register_template_handler('haml', Haml::Template)
-Sass::Plugin.update_stylesheets
+Haml.init_rails(binding)

data/lib/haml.rb CHANGED

@@ -143,6 +143,45 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #     <script src='javascripts/script_9' type='text/javascript'>
 #     </script>
 #   </head>
+#
+# A Ruby method call that returns a hash
+# can be substituted for the hash contents.
+# For example, Haml::Helpers defines the following method:
+#
+#   def html_attrs(lang = 'en-US')
+#     {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
+#   end
+#
+# This can then be used in Haml, like so:
+#
+#   %html{html_attrs('fr-fr')}
+#
+# This is compiled to:
+#
+#   <html lang='fr-fr' xml:lang='fr=fr' xmlns='http://www.w3.org/1999/xhtml'>
+#   </html>
+#
+# You can use as many such attribute methods as you want
+# by separating them with commas,
+# like a Ruby argument list.
+# All the hashes will me merged together, from left to right.
+# For example, if you defined
+#
+#   def hash1
+#     {:bread => 'white', :filling => 'peanut butter and jelly'}
+#   end
+#
+#   def hash2
+#     {:bread => 'whole wheat'}
+#   end
+#
+# then
+#
+#   %sandwich{hash1, hash2, :delicious => true}/
+#
+# would compile to:
+#
+#   <sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
 #
 # ==== []
 #
@@ -583,7 +622,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #   <p>
 #     hello there you!
 #   </p>
-#
+#
 # ===== Blocks
 #
 # Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
@@ -650,6 +689,21 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 # <p>foo</p>
 # <p>bar</p>
+#
+# You can also nest text beneath a silent comment.
+# None of this text will be rendered.
+# For example:
+#
+# %p foo
+# -#
+#   This won't be displayed
+#     Nor will this
+# %p bar
+#
+# is compiled to:
+#
+# <p>foo</p>
+# <p>bar</p>
 #
 # == Other Useful Things
 #
@@ -693,16 +747,20 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #                           * An +initialize+ method that accepts one parameter,
 #                             the text to be filtered.
 #                           * A +render+ method that returns the result of the filtering.
-#
-# [<tt>:locals</tt>]        The local variables that will be available within the
-#                           template. For instance, if <tt>:locals</tt> is
-#                           <tt>{ :foo => "bar" }</tt>, then within the template,
-#                           <tt>= foo</tt> will produce <tt>bar</tt>.
 #
 # [<tt>:autoclose</tt>]     A list of tag names that should be automatically self-closed
 #                           if they have no content.
 #                           Defaults to <tt>['meta', 'img', 'link', 'script', 'br', 'hr']</tt>.
 #
-module Haml; end
+module Haml
+  # This method is called by init.rb,
+  # which is run by Rails on startup.
+  # We use it rather than putting stuff straight into init.rb
+  # so we can change the initialization behavior
+  # without modifying the file itself.
+  def self.init_rails(binding)
+    %w[haml/template sass sass/plugin].each(&method(:require))
+  end
+end
 require 'haml/engine'

data/lib/haml/buffer.rb CHANGED

@@ -15,6 +15,9 @@ module Haml
     # _erbout for compatibility with ERB-specific code.
     attr_accessor :buffer
+    # The options hash passed in from Haml::Engine.
+    attr_accessor :options
     # Gets the current tabulation of the document.
     def tabulation
       @real_tabs + @tabulation
@@ -28,11 +31,10 @@ module Haml
     # Creates a new buffer.
     def initialize(options = {})
-      @options = options
-      @quote_escape = options[:attr_wrapper] == '"' ? "&quot;" : "&apos;"
-      @other_quote_char = options[:attr_wrapper] == '"' ? "'" : '"'
+      @options = {
+        :attr_wrapper => "'"
+      }.merge options
       @buffer = ""
-      @one_liner_pending = false
       @tabulation = 0
       # The number of tabs that Engine thinks we should have
@@ -42,63 +44,80 @@ module Haml
     # Renders +text+ with the proper tabulation. This also deals with
     # making a possible one-line tag one line or not.
-    def push_text(text, tabulation)
-      if @one_liner_pending && Buffer.one_liner?(text)
-        @buffer << text
-      else
-        if @one_liner_pending
-          @buffer << "\n"
-          @one_liner_pending = false
-        end
-        @buffer << "#{tabs(tabulation)}#{text}\n"
+    def push_text(text, tab_change = 0)
+      if(@tabulation > 0)
+        # Have to push every line in by the extra user set tabulation
+        text.gsub!(/^/m, '  ' * @tabulation)
       end
+      @buffer << "#{text}"
+      @real_tabs += tab_change
     end
     # Properly formats the output of a script that was run in the
     # instance_eval.
-    def push_script(result, tabulation, flattened)
+    def push_script(result, flattened, close_tag = nil)
+      tabulation = @real_tabs
       if flattened
         result = Haml::Helpers.find_and_preserve(result)
       end
       result = result.to_s
-      while result[-1] == 10 # \n
+      while result[-1] == ?\n
         # String#chomp is slow
         result = result[0...-1]
       end
-      result = result.gsub("\n", "\n#{tabs(tabulation)}")
-      push_text result, tabulation
+      if close_tag && Buffer.one_liner?(result)
+        @buffer << result
+        @buffer << "</#{close_tag}>\n"
+        @real_tabs -= 1
+      else
+        if close_tag
+          @buffer << "\n"
+        end
+        result = result.gsub(/^/m, tabs(tabulation))
+        @buffer << "#{result}\n"
+        if close_tag
+          @buffer << "#{tabs(tabulation-1)}</#{close_tag}>\n"
+          @real_tabs -= 1
+        end
+      end
       nil
     end
-    def open_prerendered_tag(tag, tabulation)
-      @buffer << "#{tabs(tabulation)}#{tag}"
-      @real_tabs += 1
-    end
     # Takes the various information about the opening tag for an
     # element, formats it, and adds it to the buffer.
-    def open_tag(name, tabulation, atomic, try_one_line, class_id, obj_ref, attributes_hash)
+    def open_tag(name, atomic, try_one_line, class_id, obj_ref, content, *attributes_hashes)
+      tabulation = @real_tabs
       attributes = class_id
-      if attributes_hash
+      attributes_hashes.each do |attributes_hash|
         attributes_hash.keys.each { |key| attributes_hash[key.to_s] = attributes_hash.delete(key) }
         self.class.merge_attrs(attributes, attributes_hash)
       end
       self.class.merge_attrs(attributes, parse_object_ref(obj_ref)) if obj_ref
-      @one_liner_pending = false
       if atomic
         str = " />\n"
       elsif try_one_line
-        @one_liner_pending = true
         str = ">"
       else
         str = ">\n"
       end
-      @buffer << "#{tabs(tabulation)}<#{name}#{build_attributes(attributes)}#{str}"
-      @real_tabs += 1
+      @buffer << "#{tabs(tabulation)}<#{name}#{Precompiler.build_attributes(@options[:attr_wrapper], attributes)}#{str}"
+      if content
+        if Buffer.one_liner?(content)
+          @buffer << "#{content}</#{name}>\n"
+        else
+          @buffer << "\n#{tabs(@real_tabs+1)}#{content}\n#{tabs(@real_tabs)}</#{name}>\n"
+        end
+      else
+        @real_tabs += 1
+      end
     end
     def self.merge_attrs(to, from)
@@ -114,62 +133,9 @@ module Haml
       to.merge!(from)
     end
-    # Creates a closing tag with the given name.
-    def close_tag(name, tabulation)
-      if @one_liner_pending
-        @buffer << "</#{name}>\n"
-        @one_liner_pending = false
-      else
-        push_text("</#{name}>", tabulation)
-      end
-    end
-    # Opens an XHTML comment.
-    def open_comment(try_one_line, conditional, tabulation)
-      conditional << ">" if conditional
-      @buffer << "#{tabs(tabulation)}<!--#{conditional.to_s} "
-      if try_one_line
-        @one_liner_pending = true
-      else
-        @buffer << "\n"
-        @real_tabs += 1
-      end
-    end
-    # Closes an XHTML comment.
-    def close_comment(has_conditional, tabulation)
-      close_tag = has_conditional ? "<![endif]-->" : "-->"
-      if @one_liner_pending
-        @buffer << " #{close_tag}\n"
-        @one_liner_pending = false
-      else
-        push_text(close_tag, tabulation)
-      end
-    end
     # Some of these methods are exposed as public class methods
     # so they can be re-used in helpers.
-    # Takes a hash and builds a list of XHTML attributes from it, returning
-    # the result.
-    def build_attributes(attributes = {})
-      result = attributes.collect do |a,v|
-        v = v.to_s
-        unless v.nil? || v.empty?
-          attr_wrapper = @options[:attr_wrapper]
-          if v.include? attr_wrapper
-            if v.include? @other_quote_char
-              v = v.gsub(attr_wrapper, @quote_escape)
-            else
-              attr_wrapper = @other_quote_char
-            end
-          end
-          " #{a}=#{attr_wrapper}#{v}#{attr_wrapper}"
-        end
-      end
-      result.compact.sort.join
-    end
     # Returns whether or not the given value is short enough to be rendered
     # on one line.
     def self.one_liner?(value)
@@ -181,7 +147,6 @@ module Haml
     @@tab_cache = {}
     # Gets <tt>count</tt> tabs. Mostly for internal use.
     def tabs(count)
-      @real_tabs = count
       tabs = count + @tabulation
       '  ' * tabs
       @@tab_cache[tabs] ||= '  ' * tabs

data/lib/haml/engine.rb CHANGED

@@ -1,5 +1,6 @@
 require 'haml/helpers'
 require 'haml/buffer'
+require 'haml/precompiler'
 require 'haml/filters'
 require 'haml/error'
 require 'haml/util'
@@ -14,101 +15,11 @@ module Haml
   #   output = haml_engine.to_html
   #   puts output
   class Engine
+    include Precompiler
     # Allow reading and writing of the options hash
     attr :options, true
-    # Designates an XHTML/XML element.
-    ELEMENT         = ?%
-    # Designates a <tt><div></tt> element with the given class.
-    DIV_CLASS       = ?.
-    # Designates a <tt><div></tt> element with the given id.
-    DIV_ID          = ?#
-    # Designates an XHTML/XML comment.
-    COMMENT         = ?/
-    # Designates an XHTML doctype.
-    DOCTYPE         = ?!
-    # Designates script, the result of which is output.
-    SCRIPT          = ?=
-    # Designates script, the result of which is flattened and output.
-    FLAT_SCRIPT     = ?~
-    # Designates script which is run but not output.
-    SILENT_SCRIPT   = ?-
-    # When following SILENT_SCRIPT, designates a comment that is not output.
-    SILENT_COMMENT  = ?#
-    # Designates a non-parsed line.
-    ESCAPE          = ?\\
-    # Designates a block of filtered text.
-    FILTER          = ?:
-    # Designates a non-parsed line. Not actually a character.
-    PLAIN_TEXT      = -1
-    # Keeps track of the ASCII values of the characters that begin a
-    # specially-interpreted line.
-    SPECIAL_CHARACTERS   = [
-      ELEMENT,
-      DIV_CLASS,
-      DIV_ID,
-      COMMENT,
-      DOCTYPE,
-      SCRIPT,
-      FLAT_SCRIPT,
-      SILENT_SCRIPT,
-      ESCAPE,
-      FILTER
-    ]
-    # The value of the character that designates that a line is part
-    # of a multiline string.
-    MULTILINE_CHAR_VALUE = ?|
-    # Characters that designate that a multiline string may be about
-    # to begin.
-    MULTILINE_STARTERS   = SPECIAL_CHARACTERS - [?/]
-    # Keywords that appear in the middle of a Ruby block with lowered
-    # indentation. If a block has been started using indentation,
-    # lowering the indentation  with one of these won't end the block.
-    # For example:
-    #
-    #   - if foo
-    #     %p yes!
-    #   - else
-    #     %p no!
-    #
-    # The block is ended after <tt>%p no!</tt>, because <tt>else</tt>
-    # is a member of this array.
-    MID_BLOCK_KEYWORDS   = ['else', 'elsif', 'rescue', 'ensure', 'when']
-    # The Regex that matches an HTML comment command.
-    COMMENT_REGEX = /\/(\[[\w\s\.]*\])?(.*)/
-    # The Regex that matches a Doctype command.
-    DOCTYPE_REGEX = /(\d\.\d)?[\s]*([a-z]*)/i
-    # The Regex that matches an HTML tag command.
-    TAG_REGEX = /[%]([-:\w]+)([-\w\.\#]*)(\{.*\})?(\[.*\])?([=\/\~]?)?(.*)?/
-    # The Regex that matches a literal string or symbol value
-    LITERAL_VALUE_REGEX = /^\s*(:(\w*)|(('|")([^\\\#'"]*?)\4))\s*$/
-    FLAT_WARNING = <<END
-Haml deprecation warning:
-The ~ command is deprecated and will be removed in future Haml versions.
-Use the :preserve filter, the preserve helper, or the find_and_preserve
-helper instead.
-END
     # Creates a new instace of Haml::Engine that will compile the given
     # template string when <tt>render</tt> is called.
     # See README for available options.
@@ -118,30 +29,21 @@ END
     # to README!
     #++
     #
-    def initialize(template, l_options = {})
+    def initialize(template, options = {})
       @options = {
         :suppress_eval => false,
         :attr_wrapper => "'",
-        :locals => {},
         :autoclose => ['meta', 'img', 'link', 'br', 'hr', 'input', 'area'],
         :filters => {
           'sass' => Sass::Engine,
           'plain' => Haml::Filters::Plain,
-          'preserve' => Haml::Filters::Preserve }
-      }
-      if !NOT_LOADED.include? 'redcloth'
-        @options[:filters].merge!({
-          'redcloth' => RedCloth,
+          'preserve' => Haml::Filters::Preserve,
+          'redcloth' => Haml::Filters::RedCloth,
           'textile' => Haml::Filters::Textile,
-          'markdown' => Haml::Filters::Markdown
-        })
-      end
-      if !NOT_LOADED.include? 'bluecloth'
-        @options[:filters]['markdown'] = Haml::Filters::Markdown
-      end
-      @options.rec_merge! l_options
+          'markdown' => Haml::Filters::Markdown },
+        :filename => '(haml)'
+      }
+      @options.rec_merge! options
       unless @options[:suppress_eval]
         @options[:filters].merge!({
@@ -149,728 +51,184 @@ END
           'ruby' => Haml::Filters::Ruby
         })
       end
-      @options[:filters].rec_merge! l_options[:filters] if l_options[:filters]
+      @options[:filters].rec_merge! options[:filters] if options[:filters]
+      if @options[:locals]
+        warn <<END
+DEPRECATION WARNING:
+The Haml :locals option is deprecated and will be removed in version 2.0.
+Use the locals option for Haml::Engine#render instead.
+END
+      end
       @template = template.strip #String
       @to_close_stack = []
       @output_tabs = 0
       @template_tabs = 0
       @index = 0
-      # This is the base tabulation of the currently active
-      # flattened block. -1 signifies that there is no such block.
       @flat_spaces = -1
-      begin
-        # Only do the first round of pre-compiling if we really need to.
-        # They might be passing in the precompiled string.
-        requires_precompile = true
-        if @@method_names[@template]
-          # Check that the compiled method supports a superset of the local assigns we want to do
-          supported_assigns = @@supported_local_assigns[@template]
-          requires_precompile = !@options[:locals].keys.all? {|var| supported_assigns.include? var}
-        end
-        do_precompile if requires_precompile
-      rescue Haml::Error => e
-        e.add_backtrace_entry(@index, @options[:filename])
-        raise e
-      end
+      precompile
+    rescue Haml::Error
+      $!.backtrace.unshift "#{@options[:filename]}:#{@index}"
+      raise
     end
     # Processes the template and returns the result as a string.
-    def render(scope = Object.new, &block)
-      @scope_object = scope
-      @buffer = Haml::Buffer.new(@options)
-      # Run the compiled evaluator function
-      compile &block
-      # Return the result string
-      @buffer.buffer
-    end
-    alias_method :to_html, :render
-    # This method is deprecated and shouldn't be used.
-    def precompiled
-      $stderr.puts <<END
-The Haml precompiled method and :precompiled option
-are deprecated and will be removed in version 2.0.
-Haml::Engine now automatically handles caching.
-END
-      nil
-    end
-   private
-    #Precompile each line
-    def do_precompile
-      @precompiled = ''
-      method_name = assign_method_name(@template, options[:filename])
-      push_silent <<-END
-        def #{method_name}(_haml_local_assigns)
-          @haml_is_haml = true
-          _hamlout = @haml_stack[-1]
-          _erbout = _hamlout.buffer
-      END
-      supported_local_assigns = {}
-      @@supported_local_assigns[@template] = supported_local_assigns
-      @options[:locals].each do |k,v|
-        supported_local_assigns[k] = true
-        push_silent "#{k} = _haml_local_assigns[:#{k}]"
-      end
-      old_line = nil
-      old_index = nil
-      old_spaces = nil
-      old_tabs = nil
-      old_uline = nil
-      (@template + "\n-#\n-#").each_with_index do |line, index|
-        spaces, tabs = count_soft_tabs(line)
-        uline = line.lstrip.chomp
-        line = uline.rstrip
-        if !line.empty?
-          if old_line
-            block_opened = tabs > old_tabs && !line.empty?
-            suppress_render = handle_multiline(old_tabs, old_line, old_index) unless @flat_spaces != -1
-            if !suppress_render
-              line_empty = old_line.empty?
-              process_indent(old_tabs, old_line) unless line_empty
-              flat = @flat_spaces != -1
-              if !flat && old_spaces != old_tabs * 2
-                raise SyntaxError.new("Illegal Indentation: Only two space characters are allowed as tabulation.")
-              end
-              if flat
-                push_flat(old_uline, old_spaces)
-              elsif !line_empty && !@haml_comment
-                process_line(old_line, old_index, block_opened)
-              end
-              if @flat_spaces == -1 && tabs - old_tabs > 1
-                raise SyntaxError.new("Illegal Indentation: Indenting more than once per line is illegal.")
-              end
-            end
-          end
-          old_line = line
-          old_index = index
-          old_spaces = spaces
-          old_tabs = tabs
-          old_uline = uline
-        elsif @flat_spaces != -1
-          process_indent(old_tabs, old_line) unless old_line.empty?
-          if @flat_spaces != -1
-            push_flat(old_line, old_spaces)
-            old_line = ''
-            old_uline = ''
-            old_spaces = 0
-          end
-        end
-      end
-      # Close all the open tags
-      @template_tabs.times { close }
-      push_silent "@haml_is_haml = false\nend\n"
-    end
-    # Processes and deals with lowering indentation.
-    def process_indent(count, line)
-      if count <= @template_tabs && @template_tabs > 0
-        to_close = @template_tabs - count
-        to_close.times do |i|
-          offset = to_close - 1 - i
-          unless offset == 0 && mid_block_keyword?(line)
-            close
-          end
-        end
-      end
-    end
-    # Processes a single line of Haml.
     #
-    # This method doesn't return anything; it simply processes the line and
-    # adds the appropriate code to <tt>@precompiled</tt>.
-    def process_line(line, index, block_opened)
-      @index = index + 1
-      @block_opened = block_opened
-      case line[0]
-      when DIV_CLASS, DIV_ID
-        render_div(line)
-      when ELEMENT
-        render_tag(line)
-      when COMMENT
-        render_comment(line)
-      when SCRIPT
-        sub_line = line[1..-1]
-        if sub_line[0] == SCRIPT
-          push_script(unescape_interpolation(sub_line[1..-1].strip), false)
-        else
-          push_script(sub_line, false)
-        end
-      when FLAT_SCRIPT
-        push_flat_script(line[1..-1])
-      when SILENT_SCRIPT
-        sub_line = line[1..-1]
-        unless sub_line[0] == SILENT_COMMENT
-          mbk = mid_block_keyword?(line)
-          push_silent(sub_line, !mbk, true)
-          if (@block_opened && !mbk) || line[1..-1].split(' ', 2)[0] == "case"
-            push_and_tabulate([:script])
-          end
-        else
-          start_haml_comment
-        end
-      when FILTER
-        name = line[1..-1].downcase
-        start_filtered(options[:filters][name.to_s] || name)
-      when DOCTYPE
-        if line[0...3] == '!!!'
-          render_doctype(line)
-        else
-          push_plain line
-        end
-      when ESCAPE
-        push_plain line[1..-1]
-      else
-        push_plain line
-      end
-    end
-    # Returns whether or not the line is a silent script line with one
-    # of Ruby's mid-block keywords.
-    def mid_block_keyword?(line)
-      line.length > 2 && line[0] == SILENT_SCRIPT && MID_BLOCK_KEYWORDS.include?(line[1..-1].split[0])
-    end
-    # Deals with all the logic of figuring out whether a given line is
-    # the beginning, continuation, or end of a multiline sequence.
+    # +scope+ is the context in which the template is evaluated.
+    # If it's a Binding or Proc object,
+    # Haml uses it as the second argument to Kernel#eval;
+    # otherwise, Haml just uses its #instance_eval context.
+    #
+    # Note that Haml modifies the evaluation context
+    # (either the scope object or the "self" object of the scope binding).
+    # It extends Haml::Helpers, and various instance variables are set
+    # (all prefixed with "haml").
+    # For example:
     #
-    # This returns whether or not the line should be
-    # rendered normally.
-    def handle_multiline(count, line, index)
-      suppress_render = false
-      # Multilines are denoting by ending with a `|` (124)
-      if is_multiline?(line) && @multiline_buffer
-        # A multiline string is active, and is being continued
-        @multiline_buffer += line[0...-1]
-        suppress_render = true
-      elsif is_multiline?(line) && (MULTILINE_STARTERS.include? line[0])
-        # A multiline string has just been activated, start adding the lines
-        @multiline_buffer = line[0...-1]
-        @multiline_count = count
-        @multiline_index = index
-        process_indent(count, line)
-        suppress_render = true
-      elsif @multiline_buffer
-        # A multiline string has just ended, make line into the result
-        unless line.empty?
-          process_line(@multiline_buffer, @multiline_index, count > @multiline_count)
-          @multiline_buffer = nil
-        end
+    #   s = "foobar"
+    #   Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"
+    #
+    #   # s now extends Haml::Helpers
+    #   s.responds_to?(:html_attrs) #=> true
+    #
+    # +locals+ is a hash of local variables to make available to the template.
+    # For example:
+    #
+    #   Haml::Engine.new("%p= foo").render(Object.new, :foo => "Hello, world!") #=> "<p>Hello, world!</p>"
+    #
+    # If a block is passed to render,
+    # that block is run when +yield+ is called
+    # within the template.
+    #
+    # Due to some Ruby quirks,
+    # if scope is a Binding or Proc object and a block is given,
+    # the evaluation context may not be quite what the user expects.
+    # In particular, it's equivalent to passing <tt>eval("self", scope)</tt> as scope.
+    # This won't have an effect in most cases,
+    # but if you're relying on local variables defined in the context of scope,
+    # they won't work.
+    def render(scope = Object.new, locals = {}, &block)
+      locals = (@options[:locals] || {}).merge(locals)
+      buffer = Haml::Buffer.new(options_for_buffer)
+      if scope.is_a?(Binding) || scope.is_a?(Proc)
+        scope_object = eval("self", scope)
+        scope = scope_object.instance_eval{binding} if block_given?
+      else
+        scope_object = scope
+        scope = scope_object.instance_eval{binding}
       end
-      return suppress_render
-    end
-    # Checks whether or not +line+ is in a multiline sequence.
-    def is_multiline?(line)                                          # ' '[0] == 32
-      line && line.length > 1 && line[-1] == MULTILINE_CHAR_VALUE && line[-2] == 32
-    end
-    # Method for generating compiled method names basically ripped out of ActiveView::Base
-    # If Haml is to be used as a standalone module without rails and still use the precompiled
-    # methods technique, it will end up duplicating this stuff.  I can't decide whether
-    # checking compile times to decide whether to recompile a template belongs in here or
-    # out in template.rb
-    @@method_names = {}
-    @@supported_local_assigns = {}
-    @@render_method_count = 0
-    def assign_method_name(template, file_name)
-      @@render_method_count += 1
-      @@method_names[template] = "_render_haml_#{@@render_method_count}".intern
-    end
-    module CompiledTemplates
-      # holds compiled template code
-    end
+      set_locals(locals.merge(:_hamlout => buffer, :_erbout => buffer.buffer), scope, scope_object)
-    # Takes <tt>@precompiled</tt>, a string buffer of Ruby code, and
-    # evaluates it in the context of <tt>@scope_object</tt>, after preparing
-    # <tt>@scope_object</tt>. The code in <tt>@precompiled</tt> populates
-    # <tt>@buffer</tt> with the compiled XHTML code.
-    def compile(&block)
-      # Set the local variables pointing to the buffer
-      buffer = @buffer
-      @scope_object.extend Haml::Helpers
-      @scope_object.instance_eval do
+      scope_object.instance_eval do
+        extend Haml::Helpers
         @haml_stack ||= Array.new
         @haml_stack.push(buffer)
-        class << self
-          attr :haml_lineno # :nodoc:
-        end
-      end
-      @scope_object.class.instance_eval do
-        include CompiledTemplates
+        @haml_is_haml = true
       end
-      begin
-        method_name = @@method_names[@template]
-        unless @scope_object.respond_to?(method_name)
-          CompiledTemplates.module_eval @precompiled
-        end
-        @scope_object.send(method_name, options[:locals], &block)
-      rescue Exception => e
-        class << e
-          include Haml::Error
-        end
-        lineno = @scope_object.haml_lineno
-        # Get information from the exception and format it so that
-        # Rails can understand it.
-        compile_error = e.message.scan(/\(eval\):([0-9]*):in `[-_a-zA-Z]*': compile error/)[0]
-        if compile_error
-          if @precompiled
-            eval_line = compile_error[0].to_i
-            line_marker = @precompiled.split("\n")[0...eval_line].grep(/@haml_lineno = [0-9]*/)[-1]
-            lineno = line_marker.scan(/[0-9]+/)[0].to_i if line_marker
-          else
-            lineno = -1
-          end
-        end
-        e.add_backtrace_entry(lineno, @options[:filename])
-        raise e
-      end
+      eval(@precompiled, scope, @options[:filename], 0)
       # Get rid of the current buffer
-      @scope_object.instance_eval do
+      scope_object.instance_eval do
         @haml_stack.pop
+        @haml_is_haml = false
       end
-    end
-    # Evaluates <tt>text</tt> in the context of <tt>@scope_object</tt>, but
-    # does not output the result.
-    def push_silent(text, add_index = false, can_suppress = false)
-      unless (can_suppress && options[:suppress_eval])
-        if add_index
-          @precompiled << "@haml_lineno = #{@index}\n#{text}\n"
-        else
-          # Not really DRY, but probably faster
-          @precompiled << "#{text}\n"
-        end
-      end
-    end
-    # Adds <tt>text</tt> to <tt>@buffer</tt> with appropriate tabulation
-    # without parsing it.
-    def push_text(text)
-      @precompiled << "_hamlout.push_text(#{text.dump}, #{@output_tabs})\n"
-    end
-    # Renders a block of text as plain text.
-    # Also checks for an illegally opened block.
-    def push_plain(text)
-      if @block_opened
-        raise SyntaxError.new("Illegal Nesting: Nesting within plain text is illegal.")
-      end
-      push_text text
-    end
-    # Adds +text+ to <tt>@buffer</tt> while flattening text.
-    def push_flat(text, spaces)
-      tabulation = spaces - @flat_spaces
-      tabulation = tabulation > -1 ? tabulation : 0
-      @filter_buffer << "#{' ' * tabulation}#{text}\n"
+      buffer.buffer
     end
+    alias_method :to_html, :render
-    # Causes <tt>text</tt> to be evaluated in the context of
-    # <tt>@scope_object</tt> and the result to be added to <tt>@buffer</tt>.
+    # Returns a proc that, when called,
+    # renders the template and returns the result as a string.
     #
-    # If <tt>flattened</tt> is true, Haml::Helpers#find_and_flatten is run on
-    # the result before it is added to <tt>@buffer</tt>
-    def push_script(text, flattened)
-      unless options[:suppress_eval]
-        push_silent("haml_temp = #{text}", true)
-        out = "haml_temp = _hamlout.push_script(haml_temp, #{@output_tabs}, #{flattened})\n"
-        if @block_opened
-          push_and_tabulate([:loud, out])
-        else
-          @precompiled << out
-        end
-      end
-    end
-    # Causes <tt>text</tt> to be evaluated, and Haml::Helpers#find_and_flatten
-    # to be run on it afterwards.
-    def push_flat_script(text)
-      if text.empty?
-        raise SyntaxError.new("Tag has no content.")
-      else
-        push_script(text, true)
-      end
-    end
-    def start_haml_comment
-      if @block_opened
-        @haml_comment = true
-        push_and_tabulate([:haml_comment])
-      end
-    end
-    # Closes the most recent item in <tt>@to_close_stack</tt>.
-    def close
-      tag, value = @to_close_stack.pop
-      case tag
-      when :script
-        close_block
-      when :comment
-        close_comment value
-      when :element
-        close_tag value
-      when :loud
-        close_loud value
-      when :filtered
-        close_filtered value
-      when :haml_comment
-        close_haml_comment
-      end
-    end
-    # Puts a line in <tt>@precompiled</tt> that will add the closing tag of
-    # the most recently opened tag.
-    def close_tag(tag)
-      @output_tabs -= 1
-      @template_tabs -= 1
-      @precompiled << "_hamlout.close_tag(#{tag.dump}, #{@output_tabs})\n"
-    end
-    # Closes a Ruby block.
-    def close_block
-      push_silent "end", false, true
-      @template_tabs -= 1
-    end
-    # Closes a comment.
-    def close_comment(has_conditional)
-      @output_tabs -= 1
-      @template_tabs -= 1
-      push_silent "_hamlout.close_comment(#{has_conditional}, #{@output_tabs})"
-    end
-    # Closes a loud Ruby block.
-    def close_loud(command)
-      push_silent 'end', false, true
-      @precompiled << command
-      @template_tabs -= 1
-    end
-    # Closes a filtered block.
-    def close_filtered(filter)
-      @flat_spaces = -1
-      if filter.is_a? String
-        if filter == 'redcloth' || filter == 'markdown' || filter == 'textile'
-          raise HamlError.new("You must have the RedCloth gem installed to use #{filter}")
-        else
-          raise HamlError.new("Filter \"#{filter}\" is not defined!")
-        end
-      else
-        filtered = filter.new(@filter_buffer).render
-        unless filter == Haml::Filters::Preserve
-          push_text(filtered.rstrip.gsub("\n", "\n#{'  ' * @output_tabs}"))
-        else
-          push_silent("_hamlout.buffer << #{filtered.dump} << \"\\n\"\n")
-        end
-      end
-      @filter_buffer = nil
-      @template_tabs -= 1
-    end
-    def close_haml_comment
-      @haml_comment = false
-      @template_tabs -= 1
-    end
-    # Iterates through the classes and ids supplied through <tt>.</tt>
-    # and <tt>#</tt> syntax, and returns a hash with them as attributes,
-    # that can then be merged with another attributes hash.
-    def parse_class_and_id(list)
-      attributes = {}
-      list.scan(/([#.])([-_a-zA-Z0-9]+)/) do |type, property|
-        case type
-        when '.'
-          if attributes['class']
-            attributes['class'] += " "
-          else
-            attributes['class'] = ""
-          end
-          attributes['class'] += property
-        when '#'
-          attributes['id'] = property
-        end
-      end
-      attributes
-    end
-    def parse_literal_value(text)
-      text.match(LITERAL_VALUE_REGEX)
-      # $2 holds the value matched by a symbol, but is nil for a string match
-      # $5 holds the value matched by a string
-      $2 || $5
-    end
-    def parse_literal_hash(text)
-      unless text
-        return {}
-      end
-      attributes = {}
-      if inner = text.scan(/^\{(.*)\}$/)[0]
-        inner[0].split(',').each do |attrib|
-          key, value, more = attrib.split('=>')
-          # Make sure the key and value and only the key and value exist
-          # Otherwise, it's too complicated and we'll defer it to the actual Ruby parser
-          if more || (key = parse_literal_value(key)).nil? ||
-              (value = parse_literal_value(value)).nil?
-            return nil
-          end
-          attributes[key] = value
-        end
-      end
-      attributes
-    end
-    def build_attributes(attributes = {})
-      @quote_escape = @options[:attr_wrapper] == '"' ? "&quot;" : "&apos;"
-      @other_quote_char = @options[:attr_wrapper] == '"' ? "'" : '"'
-      result = attributes.collect do |a,v|
-        v = v.to_s
-        unless v.nil? || v.empty?
-          attr_wrapper = @options[:attr_wrapper]
-          if v.include? attr_wrapper
-            if v.include? @other_quote_char
-              # An imperfection in LITERAL_VALUE_REGEX prevents this
-              # from ever actually being reached,
-              # but in case it becomes possible,
-              # I'm leaving it in.
-              v = v.gsub(attr_wrapper, @quote_escape)
-            else
-              attr_wrapper = @other_quote_char
-            end
-          end
-          " #{a}=#{attr_wrapper}#{v}#{attr_wrapper}"
-        end
-      end
-      result.sort.join
-    end
-    def prerender_tag(name, atomic, attributes)
-      if atomic
-        str = " />"
-      else
-        str = ">"
-      end
-      "<#{name}#{build_attributes(attributes)}#{str}"
-    end
-    # Parses a line that will render as an XHTML tag, and adds the code that will
-    # render that tag to <tt>@precompiled</tt>.
-    def render_tag(line)
-      matched = false
-      line.scan(TAG_REGEX) do |tag_name, attributes, attributes_hash, object_ref, action, value|
-        matched = true
-        value = value.to_s.strip
-        case action
-        when '/'
-          atomic = true
-        when '=', '~'
-          parse = true
-          if value[0] == ?=
-            value = value[1..-1].strip.dump.gsub('\\#', '#')
-          end
-        end
-        flattened = (action == '~')
-        value_exists = !value.empty?
-        literal_attributes = parse_literal_hash(attributes_hash)
-        attributes_hash = "{nil}" if attributes_hash.nil? || literal_attributes || @options[:suppress_eval]
-        object_ref = "nil" if object_ref.nil? || @options[:suppress_eval]
-        if attributes =~ /[\.#](\.|#|\z)/
-          raise SyntaxError.new("Illegal element: classes and ids must have values. Use %div instead.")
-        end
-        # Preparse the attributes hash
-        attributes = parse_class_and_id(attributes)
-        Buffer.merge_attrs(attributes, literal_attributes) if literal_attributes
-        if @block_opened
-          if atomic
-            raise SyntaxError.new("Illegal Nesting: Nesting within an atomic tag is illegal.")
-          elsif action == '=' || value_exists
-            raise SyntaxError.new("Illegal Nesting: Nesting within a tag that already has content is illegal.")
-          end
-        elsif atomic && value_exists
-          raise SyntaxError.new("Atomic tags can't have content.")
-        elsif parse && !value_exists
-          raise SyntaxError.new("Tag has no content.")
-        end
-        if !@block_opened && !value_exists && @options[:autoclose].include?(tag_name)
-          atomic = true
-        end
-        do_one_liner = value_exists && !parse && Buffer.one_liner?(value)
-        if object_ref == "nil" && attributes_hash == "{nil}" && !flattened && (do_one_liner || !value_exists)
-          # This means that we can render the tag directly to text and not process it in the buffer
-          open_tag = prerender_tag(tag_name, atomic, attributes)
-          if do_one_liner
-            open_tag += value
-            open_tag += "</#{tag_name}>"
-          end
-          open_tag += "\n"
-          push_silent "_hamlout.open_prerendered_tag(#{open_tag.dump}, #{@output_tabs})"
-          return if do_one_liner
-        else
-          push_silent "_hamlout.open_tag(#{tag_name.inspect}, #{@output_tabs}, #{atomic.inspect}, #{value_exists.inspect}, #{attributes.inspect}, #{object_ref}, #{attributes_hash[1...-1]})", true
-        end
-        unless atomic
-          push_and_tabulate([:element, tag_name])
-          @output_tabs += 1
-          if value_exists
-            if parse
-              push_script(value, flattened)
-            else
-              push_text(value)
-            end
-            close
-          elsif flattened
-            raise SyntaxError.new("Tag has no content.")
-          end
-        end
-      end
-      unless matched
-        raise SyntaxError.new("Invalid tag: \"#{line}\"")
-      end
-    end
-    # Renders a line that creates an XHTML tag and has an implicit div because of
-    # <tt>.</tt> or <tt>#</tt>.
-    def render_div(line)
-      render_tag('%div' + line)
-    end
-    # Renders an XHTML comment.
-    def render_comment(line)
-      conditional, content = line.scan(COMMENT_REGEX)[0]
-      content.strip!
-      if @block_opened && !content.empty?
-        raise SyntaxError.new('Illegal Nesting: Nesting within a tag that already has content is illegal.')
-      end
-      try_one_line = !content.empty?
-      push_silent "_hamlout.open_comment(#{try_one_line}, #{conditional.inspect}, #{@output_tabs})"
-      @output_tabs += 1
-      push_and_tabulate([:comment, !conditional.nil?])
-      if try_one_line
-        push_text content
-        close
-      end
-    end
-    # Renders an XHTML doctype or XML shebang.
-    def render_doctype(line)
-      if @block_opened
-        raise SyntaxError.new("Illegal Nesting: Nesting within a header command is illegal.")
-      end
-      line = line[3..-1].lstrip.downcase
-      if line[0...3] == "xml"
-        encoding = line.split[1] || "utf-8"
-        wrapper = @options[:attr_wrapper]
-        doctype = "<?xml version=#{wrapper}1.0#{wrapper} encoding=#{wrapper}#{encoding}#{wrapper} ?>"
+    # +scope+ works the same as it does for render.
+    #
+    # The first argument of the returned proc is a hash of local variable names to values.
+    # However, due to an unfortunate Ruby quirk,
+    # the local variables which can be assigned must be pre-declared.
+    # This is done with the +local_names+ argument.
+    # For example:
+    #
+    #   # This works
+    #   Haml::Engine.new("%p= foo").render_proc(Object.new, :foo).call :foo => "Hello!"
+    #     #=> "<p>Hello!</p>"
+    #
+    #   # This doesn't
+    #   Haml::Engine.new("%p= foo").render_proc.call :foo => "Hello!"
+    #     #=> NameError: undefined local variable or method `foo'
+    #
+    # The proc doesn't take a block;
+    # any yields in the template will fail.
+    def render_proc(scope = Object.new, *local_names)
+      if scope.is_a?(Binding) || scope.is_a?(Proc)
+        scope_object = eval("self", scope)
       else
-        version, type = line.scan(DOCTYPE_REGEX)[0]
-        if version == "1.1"
-          doctype = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">'
-        else
-          case type
-          when "strict"
-            doctype = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">'
-          when "frameset"
-            doctype = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">'
-          else
-            doctype = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">'
-          end
-        end
+        scope_object = scope
+        scope = scope_object.instance_eval{binding}
       end
-      push_text doctype
-    end
-    # Starts a filtered block.
-    def start_filtered(filter)
-      unless @block_opened
-        raise SyntaxError.new('Filters must have nested text.')
-      end
-      push_and_tabulate([:filtered, filter])
-      @flat_spaces = @template_tabs * 2
-      @filter_buffer = String.new
+      eval("Proc.new { |*_haml_locals| _haml_locals = _haml_locals[0] || {};" +
+           precompiled_with_ambles(local_names) + "}\n", scope, @options[:filename], 0)
     end
-    def unescape_interpolation(str)
-      str.dump.gsub('\\#', '#').gsub(/\#\{[^\}]+\}/) do |substr|
-        substr.gsub('\\"', '"')
-      end
-    end
-    # Counts the tabulation of a line.
-    def count_soft_tabs(line)
-      spaces = line.index(/[^ ]/)
-      if line[spaces] == ?\t
-        return nil if line.strip.empty?
-        raise SyntaxError.new("Illegal Indentation: Only two space characters are allowed as tabulation.")
-      end
-      [spaces, spaces/2]
-    end
-    # Pushes value onto <tt>@to_close_stack</tt> and increases
-    # <tt>@template_tabs</tt>.
-    def push_and_tabulate(value)
-      @to_close_stack.push(value)
-      @template_tabs += 1
+    # Defines a method on +object+
+    # with the given name
+    # that renders the template and returns the result as a string.
+    #
+    # If +object+ is a class or module,
+    # the method will instead by defined as an instance method.
+    # For example:
+    #
+    #   t = Time.now
+    #   Haml::Engine.new("%p\n  Today's date is\n  .date= self.to_s").def_method(t, :render)
+    #   t.render #=> "<p>\n  Today's date is\n  <div class='date'>Fri Nov 23 18:28:29 -0800 2007</div>\n</p>\n"
+    #
+    #   Haml::Engine.new(".upcased= upcase").def_method(String, :upcased_div)
+    #   "foobar".upcased_div #=> "<div class='upcased'>FOOBAR</div>\n"
+    #
+    # The first argument of the defined method is a hash of local variable names to values.
+    # However, due to an unfortunate Ruby quirk,
+    # the local variables which can be assigned must be pre-declared.
+    # This is done with the +local_names+ argument.
+    # For example:
+    #
+    #   # This works
+    #   obj = Object.new
+    #   Haml::Engine.new("%p= foo").def_method(obj, :render, :foo)
+    #   obj.render(:foo => "Hello!") #=> "<p>Hello!</p>"
+    #
+    #   # This doesn't
+    #   obj = Object.new
+    #   Haml::Engine.new("%p= foo").def_method(obj, :render)
+    #   obj.render(:foo => "Hello!") #=> NameError: undefined local variable or method `foo'
+    #
+    # Note that Haml modifies the evaluation context
+    # (either the scope object or the "self" object of the scope binding).
+    # It extends Haml::Helpers, and various instance variables are set
+    # (all prefixed with "haml").
+    def def_method(object, name, *local_names)
+      method = object.is_a?(Module) ? :module_eval : :instance_eval
+      object.send(method, "def #{name}(_haml_locals = {}); #{precompiled_with_ambles(local_names)}; end",
+                  @options[:filename], 0)
+    end
+    private
+    def set_locals(locals, scope, scope_object)
+      scope_object.send(:instance_variable_set, '@_haml_locals', locals)
+      set_locals = locals.keys.map { |k| "#{k} = @_haml_locals[#{k.inspect}]" }.join("\n")
+      eval(set_locals, scope)
+    end
+    # Returns a hash of options that Haml::Buffer cares about.
+    # This should remain loadable form #inspect.
+    def options_for_buffer
+      {:attr_wrapper => @options[:attr_wrapper]}
     end
   end
 end