radiant 0.8.2 → 0.9.0.rc2

data/vendor/plugins/haml/lib/haml/buffer.rb

@@ -1,80 +1,97 @@
 module Haml
-  # This class is used only internally. It holds the buffer of XHTML that
-  # is eventually output by Haml::Engine's to_html method. It's called
-  # from within the precompiled code, and helps reduce the amount of
-  # processing done within instance_eval'd code.
+  # This class is used only internally. It holds the buffer of HTML that
+  # is eventually output as the resulting document.
+  # It's called from within the precompiled code,
+  # and helps reduce the amount of processing done within `instance_eval`ed code.
   class Buffer
     include Haml::Helpers
+    include Haml::Util
 
-    # The string that holds the compiled XHTML. This is aliased as
-    # _erbout for compatibility with ERB-specific code.
+    # The string that holds the compiled HTML. This is aliased as
+    # `_erbout` for compatibility with ERB-specific code.
+    #
+    # @return [String]
     attr_accessor :buffer
 
-    # The options hash passed in from Haml::Engine.
+    # The options hash passed in from {Haml::Engine}.
+    #
+    # @return [{String => Object}]
+    # @see Haml::Engine#options_for_buffer
     attr_accessor :options
 
-    # The Buffer for the enclosing Haml document.
+    # The {Buffer} for the enclosing Haml document.
     # This is set for partials and similar sorts of nested templates.
-    # It's nil at the top level (see #toplevel?).
+    # It's `nil` at the top level (see \{#toplevel?}).
+    #
+    # @return [Buffer]
     attr_accessor :upper
 
-    # See #active?
+    # nil if there's no capture_haml block running,
+    # and the position at which it's beginning the capture if there is one.
+    #
+    # @return [Fixnum, nil]
+    attr_accessor :capture_position
+
+    # @return [Boolean]
+    # @see #active?
     attr_writer :active
 
-    # True if the format is XHTML
+    # @return [Boolean] Whether or not the format is XHTML
     def xhtml?
       not html?
     end
 
-    # True if the format is any flavor of HTML
+    # @return [Boolean] Whether or not the format is any flavor of HTML
     def html?
       html4? or html5?
     end
 
-    # True if the format is HTML4
+    # @return [Boolean] Whether or not the format is HTML4
     def html4?
       @options[:format] == :html4
     end
 
-    # True if the format is HTML5
+    # @return [Boolean] Whether or not the format is HTML5.
     def html5?
       @options[:format] == :html5
     end
 
-    # True if this buffer is a top-level template,
-    # as opposed to a nested partial.
+    # @return [Boolean] Whether or not this buffer is a top-level template,
+    #   as opposed to a nested partial
     def toplevel?
       upper.nil?
     end
 
-    # True if this buffer is currently being used to render a Haml template.
-    # However, this returns false if a subtemplate is being rendered,
+    # Whether or not this buffer is currently being used to render a Haml template.
+    # Returns `false` if a subtemplate is being rendered,
     # even if it's a subtemplate of this buffer's template.
+    #
+    # @return [Boolean]
     def active?
       @active
     end
 
-    # Gets the current tabulation of the document.
+    # @return [Fixnum] The current indentation level of the document
     def tabulation
       @real_tabs + @tabulation
     end
 
     # Sets the current tabulation of the document.
+    #
+    # @param val [Fixnum] The new tabulation
     def tabulation=(val)
       val = val - @real_tabs
       @tabulation = val > -1 ? val : 0
     end
 
-    # Creates a new buffer.
+    # @param upper [Buffer] The parent buffer
+    # @param options [{Symbol => Object}] An options hash.
+    #   See {Haml::Engine#options\_for\_buffer}
     def initialize(upper = nil, options = {})
       @active = true
       @upper = upper
-      @options = {
-        :attr_wrapper => "'",
-        :ugly => false,
-        :format => :xhtml
-      }.merge options
-      @buffer = ""
+      @options = options
+      @buffer = ruby1_8? ? "" : "".encode(Encoding.find(options[:encoding]))
       @tabulation = 0
 
       # The number of tabs that Engine thinks we should have
@@ -82,10 +99,15 @@ module Haml
       @real_tabs = 0
     end
 
-    # Renders +text+ with the proper tabulation. This also deals with
-    # making a possible one-line tag one line or not.
-    def push_text(text, dont_tab_up = false, tab_change = 0)
-      if @tabulation > 0 && !@options[:ugly]
+    # Appends text to the buffer, properly tabulated.
+    # Also modifies the document's indentation.
+    #
+    # @param text [String] The text to append
+    # @param tab_change [Fixnum] The number of tabs by which to increase
+    #   or decrease the document's indentation
+    # @param dont_tab_up [Boolean] If true, don't indent the first line of `text`
+    def push_text(text, tab_change, dont_tab_up)
+      if @tabulation > 0
         # Have to push every line in by the extra user set tabulation.
         # Don't push lines with just whitespace, though,
         # because that screws up precompiled indentation.
@@ -95,65 +117,85 @@ module Haml
 
       @buffer << text
       @real_tabs += tab_change
-      @dont_tab_up_next_line = false
     end
 
-    # Properly formats the output of a script that was run in the
-    # instance_eval.
-    def push_script(result, preserve_script, in_tag = false, preserve_tag = false,
-                    escape_html = false, nuke_inner_whitespace = false)
-      tabulation = @real_tabs
-
-      result = result.to_s.rstrip
-      result = result.lstrip if nuke_inner_whitespace
-      result = html_escape(result) if escape_html
+    # Modifies the indentation of the document.
+    #
+    # @param tab_change [Fixnum] The number of tabs by which to increase
+    #   or decrease the document's indentation
+    def adjust_tabs(tab_change)
+      @real_tabs += tab_change
+    end
 
-      if preserve_tag
+    Haml::Util.def_static_method(self, :format_script, [:result],
+                                 :preserve_script, :in_tag, :preserve_tag, :escape_html,
+                                 :nuke_inner_whitespace, :interpolated, :ugly, <<RUBY)
+      <% # Escape HTML here so that the safety of the string is preserved in Rails
+         result_name = escape_html ? "html_escape(result.to_s)" : "result.to_s" %>
+      <% unless ugly %>
+        # If we're interpolated,
+        # then the custom tabulation is handled in #push_text.
+        # The easiest way to avoid it here is to reset @tabulation.
+        <% if interpolated %>
+          old_tabulation = @tabulation
+          @tabulation = 0
+        <% end %>
+
+        tabulation = @real_tabs
+        result = <%= result_name %>.<% if nuke_inner_whitespace %>strip<% else %>rstrip<% end %>
+      <% else %>
+        result = <%= result_name %><% if nuke_inner_whitespace %>.strip<% end %>
+      <% end %>
+
+      <% if preserve_tag %>
         result = Haml::Helpers.preserve(result)
-      elsif preserve_script
+      <% elsif preserve_script %>
         result = Haml::Helpers.find_and_preserve(result, options[:preserve])
-      end
-
-      has_newline = result.include?("\n")
-      if in_tag && !nuke_inner_whitespace && (@options[:ugly] || !has_newline || preserve_tag)
-        @buffer << result
-        @real_tabs -= 1
-        return
-      end
-
-      @buffer << "\n" if in_tag && !nuke_inner_whitespace
-
-      # Precompiled tabulation may be wrong
-      if @tabulation > 0 && !in_tag
-        result = tabs + result
-      end
-
-      if has_newline && !@options[:ugly]
-        result = result.gsub "\n", "\n" + tabs(tabulation)
-
-        # Add tabulation if it wasn't precompiled
-        result = tabs(tabulation) + result if in_tag && !nuke_inner_whitespace
-      end
-      @buffer << "#{result}"
-      @buffer << "\n" unless nuke_inner_whitespace
-
-      if in_tag && !nuke_inner_whitespace
-        # We never get here if @options[:ugly] is true
-        @buffer << tabs(tabulation-1)
-        @real_tabs -= 1
-      end
-      nil
-    end
-
-    # Takes the various information about the opening tag for an
-    # element, formats it, and adds it to the buffer.
+      <% end %>
+
+      <% if ugly %>
+        return result
+      <% else %>
+
+        has_newline = result.include?("\\n") 
+        <% if in_tag && !nuke_inner_whitespace %>
+          <% unless preserve_tag %> if !has_newline <% end %>
+          @real_tabs -= 1
+          <% if interpolated %> @tabulation = old_tabulation <% end %>
+          return result
+          <% unless preserve_tag %> end <% end %>
+        <% end %>
+
+        # Precompiled tabulation may be wrong
+        <% if !interpolated && !in_tag %>
+          result = tabs + result if @tabulation > 0
+        <% end %>
+
+        if has_newline
+          result = result.gsub "\\n", "\\n" + tabs(tabulation)
+
+          # Add tabulation if it wasn't precompiled
+          <% if in_tag && !nuke_inner_whitespace %> result = tabs(tabulation) + result <% end %>
+        end
+
+        <% if in_tag && !nuke_inner_whitespace %>
+          result = "\\n\#{result}\\n\#{tabs(tabulation-1)}"
+          @real_tabs -= 1
+        <% end %>
+        <% if interpolated %> @tabulation = old_tabulation <% end %>
+        result
+      <% end %>
+RUBY
+
+    # Takes the various information about the opening tag for an element,
+    # formats it, and appends it to the buffer.
     def open_tag(name, self_closing, try_one_line, preserve_tag, escape_html, class_id,
                  nuke_outer_whitespace, nuke_inner_whitespace, obj_ref, content, *attributes_hashes)
       tabulation = @real_tabs
 
       attributes = class_id
       attributes_hashes.each do |old|
-        self.class.merge_attrs(attributes, old.inject({}) {|h, (key, val)| h[key.to_s] = val; h})
+        self.class.merge_attrs(attributes, to_hash(old.map {|k, v| [k.to_s, v]}))
       end
       self.class.merge_attrs(attributes, parse_object_ref(obj_ref)) if obj_ref
 
@@ -178,16 +220,39 @@ module Haml
       @real_tabs += 1 unless self_closing || nuke_inner_whitespace
     end
 
+    # Remove the whitespace from the right side of the buffer string.
+    # Doesn't do anything if we're at the beginning of a capture_haml block.
+    def rstrip!
+      if capture_position.nil?
+        buffer.rstrip!
+        return
+      end
+
+      buffer << buffer.slice!(capture_position..-1).rstrip
+    end
+
+    # Merges two attribute hashes.
+    # This is the same as `to.merge!(from)`,
+    # except that it merges id and class attributes.
+    #
+    # ids are concatenated with `"_"`,
+    # and classes are concatenated with `" "`.
+    #
+    # Destructively modifies both `to` and `from`.
+    #
+    # @param to [{String => String}] The attribute hash to merge into
+    # @param from [{String => String}] The attribute hash to merge from
+    # @return [{String => String}] `to`, after being merged
     def self.merge_attrs(to, from)
       if to['id'] && from['id']
-        to['id'] << '_' << from.delete('id')
+        to['id'] << '_' << from.delete('id').to_s
       elsif to['id'] || from['id']
         from['id'] ||= to['id']
       end
 
       if to['class'] && from['class']
         # Make sure we don't duplicate class names
-        from['class'] = (from['class'].split(' ') | to['class'].split(' ')).join(' ')
+        from['class'] = (from['class'].split(' ') | to['class'].split(' ')).sort.join(' ')
       elsif to['class'] || from['class']
         from['class'] ||= to['class']
       end
@@ -197,11 +262,8 @@ module Haml
 
     private
 
-    # Some of these methods are exposed as public class methods
-    # so they can be re-used in helpers.
-
     @@tab_cache = {}
-    # Gets <tt>count</tt> tabs. Mostly for internal use.
+    # Gets `count` tabs. Mostly for internal use.
     def tabs(count = 0)
       tabs = [count + @tabulation, 0].max
       @@tab_cache[tabs] ||= '  ' * tabs
@@ -210,7 +272,7 @@ module Haml
     # Takes an array of objects and uses the class and id of the first
     # one to create an attributes hash.
     # The second object, if present, is used as a prefix,
-    # just like you can do with dom_id() and dom_class() in Rails
+    # just like you can do with `dom_id()` and `dom_class()` in Rails
     def parse_object_ref(ref)
       prefix = ref[1]
       ref = ref[0]

data/vendor/plugins/haml/lib/haml/engine.rb

@@ -5,98 +5,112 @@ require 'haml/filters'
 require 'haml/error'
 
 module Haml
-  # This is the class where all the parsing and processing of the Haml
-  # template is done. It can be directly used by the user by creating a
-  # new instance and calling <tt>to_html</tt> to render the template. For example:
+  # This is the frontend for using Haml programmatically.
+  # It can be directly used by the user by creating a
+  # new instance and calling \{#render} to render the template.
+  # For example:
   #
-  #   template = File.read('templates/really_cool_template.haml')
-  #   haml_engine = Haml::Engine.new(template)
-  #   output = haml_engine.to_html
-  #   puts output
+  #     template = File.read('templates/really_cool_template.haml')
+  #     haml_engine = Haml::Engine.new(template)
+  #     output = haml_engine.render
+  #     puts output
   class Engine
     include Precompiler
 
-    # Allow reading and writing of the options hash
-    attr :options, true
+    # The options hash.
+    # See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.
+    #
+    # @return [{Symbol => Object}]
+    attr_accessor :options
 
-    # This string contains the source code that is evaluated
-    # to produce the Haml document.
-    attr :precompiled, true
+    # The indentation used in the Haml document,
+    # or `nil` if the indentation is ambiguous
+    # (for example, for a single-level document).
+    #
+    # @return [String]
+    attr_accessor :indentation
 
-    # True if the format is XHTML
+    # @return [Boolean] Whether or not the format is XHTML.
     def xhtml?
       not html?
     end
 
-    # True if the format is any flavor of HTML
+    # @return [Boolean] Whether or not the format is any flavor of HTML.
     def html?
       html4? or html5?
     end
 
-    # True if the format is HTML4
+    # @return [Boolean] Whether or not the format is HTML4.
     def html4?
       @options[:format] == :html4
     end
 
-    # True if the format is HTML5
+    # @return [Boolean] Whether or not the format is HTML5.
     def html5?
       @options[:format] == :html5
     end
 
-    # Creates a new instace of Haml::Engine that will compile the given
-    # template string when <tt>render</tt> is called.
-    # See the Haml module documentation for available options.
+    # The source code that is evaluated to produce the Haml document.
+    #
+    # In Ruby 1.9, this is automatically converted to the correct encoding
+    # (see {file:HAML_REFERENCE.md#encoding-option the `:encoding` option}).
     #
-    #--
-    # When adding options, remember to add information about them
-    # to lib/haml.rb!
-    #++
+    # @return [String]
+    def precompiled
+      return @precompiled if ruby1_8?
+      encoding = Encoding.find(@options[:encoding])
+      return @precompiled.force_encoding(encoding) if encoding == Encoding::BINARY
+      return @precompiled.encode(encoding)
+    end
+
+    # Precompiles the Haml template.
     #
+    # @param template [String] The Haml template
+    # @param options [{Symbol => Object}] An options hash;
+    #   see {file:HAML_REFERENCE.md#haml_options the Haml options documentation}
+    # @raise [Haml::Error] if there's a Haml syntax error in the template
     def initialize(template, options = {})
       @options = {
         :suppress_eval => false,
         :attr_wrapper => "'",
 
-        # Don't forget to update the docs in lib/haml.rb if you update these
+        # Don't forget to update the docs in doc-src/HAML_REFERENCE.md
+        # if you update these
         :autoclose => %w[meta img link br hr input area param col base],
-        :preserve => %w[textarea pre],
+        :preserve => %w[textarea pre code],
 
         :filename => '(haml)',
         :line => 1,
         :ugly => false,
         :format => :xhtml,
-        :escape_html => false
+        :escape_html => false,
       }
-      @options.merge! options
+      unless ruby1_8?
+        @options[:encoding] = Encoding.default_internal || "utf-8"
+      end
+      @options.merge! options.reject {|k, v| v.nil?}
       @index = 0
 
       unless [:xhtml, :html4, :html5].include?(@options[:format])
         raise Haml::Error, "Invalid format #{@options[:format].inspect}"
       end
 
-      @template = template.rstrip + "\n-#\n-#"
+      if @options[:encoding] && @options[:encoding].is_a?(Encoding)
+        @options[:encoding] = @options[:encoding].name
+      end
+
+      # :eod is a special end-of-document marker
+      @template = (template.rstrip).split(/\r\n|\r|\n/) + [:eod, :eod]
+      @template_index = 0
       @to_close_stack = []
       @output_tabs = 0
       @template_tabs = 0
-      @flat_spaces = -1
       @flat = false
       @newlines = 0
       @precompiled = ''
-      @merged_text = ''
+      @to_merge = []
       @tab_change  = 0
 
-      if @template =~ /\A(\s*\n)*[ \t]+\S/
-        raise SyntaxError.new("Indenting at the beginning of the document is illegal.", ($1 || "").count("\n"))
-      end
-
-      if @options[:filters]
-        warn <<END
-DEPRECATION WARNING:
-The Haml :filters option is deprecated and will be removed in version 2.2.
-Filters are now automatically registered.
-END
-      end
-
       precompile
     rescue Haml::Error => e
       e.backtrace.unshift "#{@options[:filename]}:#{(e.line ? e.line + 1 : @index) + @options[:line] - 1}" if @index
@@ -105,39 +119,45 @@ END
 
     # Processes the template and returns the result as a string.
     #
-    # +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.
+    # `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").
+    # (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:
     #
-    #   s = "foobar"
-    #   Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"
+    #     s = "foobar"
+    #     Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"
     #
-    #   # s now extends Haml::Helpers
-    #   s.responds_to?(:html_attrs) #=> true
+    #     # s now extends Haml::Helpers
+    #     s.respond_to?(:html_attrs) #=> true
     #
-    # +locals+ is a hash of local variables to make available to the template.
+    # `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>"
+    #     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
+    # 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,
+    # 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.
+    # In particular, it's equivalent to passing `eval("self", scope)` 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,
+    # but if you're relying on local variables defined in the context of `scope`,
     # they won't work.
+    #
+    # @param scope [Binding, Proc, Object] The context in which the template is evaluated
+    # @param locals [{Symbol => Object}] Local variables that will be made available
+    #   to the template
+    # @param block [#to_proc] A block that can be yielded to within the template
+    # @return [String] The rendered template
     def render(scope = Object.new, locals = {}, &block)
       buffer = Haml::Buffer.new(scope.instance_variable_get('@haml_buffer'), options_for_buffer)
 
@@ -156,38 +176,40 @@ END
         @haml_buffer = buffer
       end
 
-      eval(@precompiled, scope, @options[:filename], @options[:line])
-
+      eval(precompiled + ";" + precompiled_method_return_value,
+        scope, @options[:filename], @options[:line])
+    ensure
       # Get rid of the current buffer
       scope_object.instance_eval do
         @haml_buffer = buffer.upper
       end
-
-      buffer.buffer
     end
     alias_method :to_html, :render
 
     # Returns a proc that, when called,
     # renders the template and returns the result as a string.
     #
-    # +scope+ works the same as it does for render.
+    # `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.
+    # 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 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'
+    #     # 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.
+    # The proc doesn't take a block; any yields in the template will fail.
+    #
+    # @param scope [Binding, Proc, Object] The context in which the template is evaluated
+    # @param local_names [Array<Symbol>] The names of the locals that can be passed to the proc
+    # @return [Proc] The proc that will run the template
     def render_proc(scope = Object.new, *local_names)
       if scope.is_a?(Binding) || scope.is_a?(Proc)
         scope_object = eval("self", scope)
@@ -200,41 +222,44 @@ END
            precompiled_with_ambles(local_names) + "}\n", scope, @options[:filename], @options[:line])
     end
 
-    # Defines a method on +object+
-    # with the given name
+    # 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,
+    # 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"
+    #     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"
+    #     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.
+    # 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 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'
+    #     # 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").
+    # (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_`).
+    #
+    # @param object [Object, Module] The object on which to define the method
+    # @param name [String, Symbol] The name of the method to define
+    # @param local_names [Array<Symbol>] The names of the locals that can be passed to the proc
     def def_method(object, name, *local_names)
       method = object.is_a?(Module) ? :module_eval : :instance_eval
 
@@ -242,24 +267,33 @@ END
                   @options[:filename], @options[:line])
     end
 
-    private
+    protected
 
-    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 from #inspect.
+    # Returns a subset of \{#options}: those that {Haml::Buffer} cares about.
+    # All of the values here are such that when `#inspect` is called on the hash,
+    # it can be `Kernel#eval`ed to get the same result back.
+    #
+    # See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.
+    #
+    # @return [{Symbol => Object}] The options hash
     def options_for_buffer
       {
         :autoclose => @options[:autoclose],
         :preserve => @options[:preserve],
         :attr_wrapper => @options[:attr_wrapper],
         :ugly => @options[:ugly],
-        :format => @options[:format]
+        :format => @options[:format],
+        :encoding => @options[:encoding],
+        :escape_html => @options[:escape_html],
       }
     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
   end
 end