haml-edge 2.1.21 → 2.1.22

data/lib/haml/buffer.rb

@@ -1,76 +1,92 @@
 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 [Hash<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
 
     # 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
 
-    # See #active?
+    # @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 [Hash<Symbol, Object>] An options hash.
+    #   See {Haml::Engine#options\_for\_buffer}
     def initialize(upper = nil, options = {})
       @active = true
       @upper = upper
@@ -87,6 +103,13 @@ module Haml
       @real_tabs = 0
     end
 
+    # 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.
@@ -100,6 +123,10 @@ module Haml
       @real_tabs += tab_change
     end
 
+    # 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
@@ -164,8 +191,8 @@ module Haml
       <% end %>
 RUBY
 
-    # Takes the various information about the opening tag for an
-    # element, formats it, and adds it to the buffer.
+    # 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
@@ -208,6 +235,18 @@ RUBY
       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 [Hash<String, String>] The attribute hash to merge into
+    # @param from [Hash<String, String>] The attribute hash to merge from
+    # @return [Hash<String, String>] `to`, after being merged
     def self.merge_attrs(to, from)
       if to['id'] && from['id']
         to['id'] << '_' << from.delete('id')
@@ -227,11 +266,8 @@ RUBY
 
     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
@@ -240,7 +276,7 @@ RUBY
     # 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/lib/haml/engine.rb

@@ -5,58 +5,62 @@ 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
+    # The options hash.
+    # See [the Haml options documentation](../Haml.html#haml_options).
+    #
+    # @return [Hash<Symbol, Object>]
     attr_accessor :options
 
-    # This string contains the source code that is evaluated
-    # to produce the Haml document.
+    # The source code that is evaluated to produce the Haml document.
+    #
+    # @return [String]
     attr_accessor :precompiled
 
-    # A string containing the indentation used for the Haml document.
-    # nil if the indentation is ambiguous
+    # 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.
-    #
-    #--
-    # When adding options, remember to add information about them
-    # to lib/haml.rb!
-    #++
+    # Precompiles the Haml template.
     #
+    # @param template [String] The Haml template
+    # @param options [Hash<Symbol, Object>] An options hash;
+    #   see [the Haml options documentation](../Haml.html#haml_options)
+    # @raise [Haml::Error] if there's a Haml syntax error in the template
     def initialize(template, options = {})
       @options = {
         :suppress_eval => false,
@@ -108,39 +112,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.responds_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 [Hash<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)
 
@@ -173,24 +183,27 @@ END
     # 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)
@@ -203,41 +216,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
 
@@ -245,16 +261,15 @@ END
                   @options[:filename], @options[:line])
     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
+    protected
 
-    # 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 [the Haml options documentation](../Haml.html#haml_options).
+    #
+    # @return [Hash<Symbol, Object>] The options hash
     def options_for_buffer
       {
         :autoclose => @options[:autoclose],
@@ -264,5 +279,13 @@ END
         :format => @options[:format]
       }
     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

data/lib/haml/error.rb

@@ -1,22 +1,22 @@
 module Haml
   # An exception raised by Haml code.
   class Error < StandardError
-    # :stopdoc:
-
-    # By default, an error is taken to refer to the line of the template
-    # that was being processed when the exception was raised.
-    # However, if line is non-nil, it + 1 is used instead.
+    # The line of the template on which the error occurred.
+    #
+    # @return [Fixnum]
     attr_reader :line
 
+    # @param message [String] The error message
+    # @param line [Fixnum] See \{#line}
     def initialize(message = nil, line = nil)
       super(message)
       @line = line
     end
-    # :startdoc:
   end
 
   # SyntaxError is the type of exception raised when Haml encounters an
   # ill-formatted document.
-  # It's not particularly interesting, except in that it includes Haml::Error.
+  # It's not particularly interesting,
+  # except in that it's a subclass of {Haml::Error}.
   class SyntaxError < Haml::Error; end
 end