RubyGems - haml - Versions diffs - 1.8.2 → 2.0.0 - Mend

haml 1.8.2 → 2.0.0

Potentially problematic release.

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

Files changed (77) hide show

data/FAQ +138 -0
data/MIT-LICENSE +1 -1
data/{README → README.rdoc} +66 -3
data/Rakefile +111 -147
data/VERSION +1 -1
data/bin/css2sass +0 -0
data/bin/haml +0 -0
data/bin/html2haml +0 -0
data/bin/sass +0 -0
data/init.rb +6 -1
data/lib/haml.rb +464 -201
data/lib/haml/buffer.rb +117 -63
data/lib/haml/engine.rb +63 -44
data/lib/haml/error.rb +16 -6
data/lib/haml/exec.rb +37 -7
data/lib/haml/filters.rb +213 -68
data/lib/haml/helpers.rb +95 -60
data/lib/haml/helpers/action_view_extensions.rb +1 -1
data/lib/haml/helpers/action_view_mods.rb +54 -6
data/lib/haml/html.rb +6 -6
data/lib/haml/precompiler.rb +254 -133
data/lib/haml/template.rb +3 -6
data/lib/haml/template/patch.rb +9 -2
data/lib/haml/template/plugin.rb +52 -23
data/lib/sass.rb +157 -12
data/lib/sass/constant.rb +22 -22
data/lib/sass/constant/color.rb +13 -13
data/lib/sass/constant/literal.rb +7 -7
data/lib/sass/constant/number.rb +9 -9
data/lib/sass/constant/operation.rb +4 -4
data/lib/sass/constant/string.rb +3 -3
data/lib/sass/css.rb +104 -31
data/lib/sass/engine.rb +120 -39
data/lib/sass/error.rb +1 -1
data/lib/sass/plugin.rb +14 -3
data/lib/sass/plugin/merb.rb +6 -2
data/lib/sass/tree/attr_node.rb +5 -5
data/lib/sass/tree/directive_node.rb +2 -7
data/lib/sass/tree/node.rb +1 -12
data/lib/sass/tree/rule_node.rb +39 -31
data/lib/sass/tree/value_node.rb +1 -1
data/test/benchmark.rb +67 -80
data/test/haml/engine_test.rb +284 -84
data/test/haml/helper_test.rb +51 -15
data/test/haml/results/content_for_layout.xhtml +1 -2
data/test/haml/results/eval_suppressed.xhtml +2 -4
data/test/haml/results/filters.xhtml +44 -15
data/test/haml/results/helpers.xhtml +2 -3
data/test/haml/results/just_stuff.xhtml +2 -6
data/test/haml/results/nuke_inner_whitespace.xhtml +34 -0
data/test/haml/results/nuke_outer_whitespace.xhtml +148 -0
data/test/haml/results/original_engine.xhtml +3 -7
data/test/haml/results/partials.xhtml +1 -0
data/test/haml/results/tag_parsing.xhtml +1 -6
data/test/haml/results/very_basic.xhtml +2 -4
data/test/haml/results/whitespace_handling.xhtml +13 -21
data/test/haml/template_test.rb +8 -15
data/test/haml/templates/_partial.haml +1 -0
data/test/haml/templates/filters.haml +48 -7
data/test/haml/templates/just_stuff.haml +1 -2
data/test/haml/templates/nuke_inner_whitespace.haml +26 -0
data/test/haml/templates/nuke_outer_whitespace.haml +144 -0
data/test/haml/templates/tag_parsing.haml +0 -3
data/test/haml/test_helper.rb +15 -0
data/test/sass/engine_test.rb +80 -34
data/test/sass/plugin_test.rb +1 -1
data/test/sass/results/import.css +2 -2
data/test/sass/results/mixins.css +95 -0
data/test/sass/results/multiline.css +24 -0
data/test/sass/templates/import.sass +4 -1
data/test/sass/templates/importee.sass +4 -0
data/test/sass/templates/mixins.sass +76 -0
data/test/sass/templates/multiline.sass +20 -0
metadata +65 -51
data/lib/haml/util.rb +0 -18
data/test/haml/runner.rb +0 -16
data/test/profile.rb +0 -65

data/VERSION CHANGED

	@@ -1 +1 @@
1	- 1.8.2
1	+ 2.0.0

data/bin/css2sass CHANGED

File without changes

data/bin/haml CHANGED

File without changes

data/bin/html2haml CHANGED

File without changes

data/bin/sass CHANGED

File without changes

data/init.rb CHANGED

@@ -1,2 +1,7 @@
-require 'haml'
+begin
+  require File.join(File.dirname(__FILE__), 'lib', 'haml') # From here
+rescue LoadError
+  require 'haml' # From gem
+end
 Haml.init_rails(binding)

data/lib/haml.rb CHANGED

@@ -2,18 +2,18 @@ dir = File.dirname(__FILE__)
 $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # = Haml (XHTML Abstraction Markup Language)
-#
+#
 # Haml is a markup language
 # that's used to cleanly and simply describe the XHTML of any web document,
 # without the use of inline code.
 # Haml functions as a replacement
-# for inline page templating systems such as PHP, ERB, and ASP.
-# However, Haml avoids the need for explicitly coding XHTML into the template,
+# for inline page templating systems such as PHP, ERB, and ASP.
+# However, Haml avoids the need for explicitly coding XHTML into the template,
 # because it is actually an abstract description of the XHTML,
 # with some code to generate dynamic content.
-#
+#
 # == Features
-#
+#
 # * Whitespace active
 # * Well-formatted markup
 # * DRY
@@ -36,9 +36,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 # To enable it as a Rails plugin,
 # then run
-#
+#
 #   haml --rails path/to/rails/app
-#
+#
 # Haml is enabled in Merb by default,
 # so Merb users don't have to do anything more.
 #
@@ -50,24 +50,24 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # the same way you do in ERb templates.
 # Helper methods are also available in Haml templates.
 # For example (this example uses Rails, but the principle for Merb is the same):
-#
+#
 #   # file: app/controllers/movies_controller.rb
-#
+#
 #   class MoviesController < ApplicationController
 #     def index
 #       @title = "Teen Wolf"
 #     end
 #   end
-#
+#
 #   -# file: app/views/movies/index.haml
-#
+#
 #   #content
 #    .title
 #      %h1= @title
 #      = link_to 'Home', home_url
-#
+#
 # may be compiled to:
-#
+#
 #   <div id='content'>
 #     <div class='title'>
 #       <h1>Teen Wolf</h1>
@@ -89,41 +89,41 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #   engine.render #=> "<p>Haml code!</p>\n"
 #
 # == Characters with meaning to Haml
-#
+#
 # Various characters, when placed at a certain point in a line,
 # instruct Haml to render different types of things.
-#
+#
 # === XHTML Tags
-#
+#
 # These characters render XHTML tags.
-#
+#
 # ==== %
-#
-#
+#
+#
 # The percent character is placed at the beginning of a line.
 # It's followed immediately by the name of an element,
 # then optionally by modifiers (see below), a space,
 # and text to be rendered inside the element.
 # It creates an element in the form of <tt><element></element></tt>.
 # For example:
-#
+#
 #   %one
 #     %two
 #       %three Hey there
-#
+#
 # is compiled to:
-#
+#
 #   <one>
 #     <two>
 #       <three>Hey there</three>
 #     </two>
 #   </one>
-#
+#
 # Any string is a valid element name;
 # Haml will automatically generate opening and closing tags for any element.
-#
+#
 # ==== {}
-#
+#
 # Brackets represent a Ruby hash
 # that is used for specifying the attributes of an element.
 # It is literally evaluated as a Ruby hash,
@@ -132,18 +132,20 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # will be replaced by appropriate escape sequences.
 # The hash is placed after the tag is defined.
 # For example:
-#
+#
 #   %head{ :name => "doc_head" }
 #     %script{ 'type' => "text/" + "javascript",
 #              :src   => "javascripts/script_#{2 + 7}" }
-#
+#
 # is compiled to:
-#
+#
 #   <head name="doc_head">
 #     <script src='javascripts/script_9' type='text/javascript'>
 #     </script>
 #   </head>
 #
+# ===== Attribute Methods
+#
 # A Ruby method call that returns a hash
 # can be substituted for the hash contents.
 # For example, Haml::Helpers defines the following method:
@@ -182,9 +184,36 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # would compile to:
 #
 #   <sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
-#
+#
+# ===== Boolean Attributes
+#
+# Some attributes, such as "checked" for <tt>input</tt> tags or "selected" for <tt>option</tt> tags,
+# are "boolean" in the sense that their values don't matter -
+# it only matters whether or not they're present.
+# In HTML (but not XHTML), these attributes can be written as
+#
+#   <input selected>
+#
+# To do this in Haml, just assign a Ruby true value to the attribute:
+#
+#   %input{:selected => true}
+#
+# In XHTML, the only valid value for these attributes is the name of the attribute.
+# Thus this will render in XHTML as
+#
+#   <input selected="selected">
+#
+# To set these attributes to false, simply assign them to a Ruby false value.
+# In both XHTML and HTML
+#
+#   %input{:selected => false}
+#
+# will just render as
+#
+#   <input>
+#
 # ==== []
-#
+#
 # Square brackets follow a tag definition and contain a Ruby object
 # that is used to set the class and id of that tag.
 # The class is set to the object's class
@@ -192,41 +221,40 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # and the id is set to the object's class, followed by its id.
 # Because the id of an object is normally an obscure implementation detail,
 # this is most useful for elements that represent instances of Models.
+# Additionally, the second argument (if present) will be used as a prefix for
+# both the id and class attributes.
 # For example:
-#
+#
 #   # file: app/controllers/users_controller.rb
-#
+#
 #   def show
 #     @user = CrazyUser.find(15)
 #   end
-#
+#
 #   -# file: app/views/users/show.haml
-#
-#   %div[@user]
+#
+#   %div[@user, :greeting]
 #     %bar[290]/
 #     Hello!
-#
+#
 # is compiled to:
-#
-#   <div class="crazy_user" id="crazy_user_15">
+#
+#   <div class="greeting_crazy_user" id="greeting_crazy_user_15">
 #     <bar class="fixnum" id="fixnum_581" />
 #     Hello!
 #   </div>
-#
-# This is based off of DHH's SimplyHelpful syntax,
-# as presented at RailsConf Europe 2006.
-#
+#
 # ==== /
-#
+#
 # The forward slash character, when placed at the end of a tag definition,
 # causes the tag to be self-closed.
 # For example:
-#
+#
 #   %br/
 #   %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
-#
+#
 # is compiled to:
-#
+#
 #   <br />
 #   <meta http-equiv='Content-Type' content='text/html' />
 #
@@ -242,9 +270,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 #   <br />
 #   <meta http-equiv='Content-Type' content='text/html' />
-#
+#
 # ==== . and #
-#
+#
 # The period and pound sign are borrowed from CSS.
 # They are used as shortcuts to specify the <tt>class</tt>
 # and <tt>id</tt> attributes of an element, respectively.
@@ -252,22 +280,22 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # by chaining the class names together with periods.
 # They are placed immediately after the tag and before an attributes hash.
 # For example:
-#
+#
 #   %div#things
 #     %span#rice Chicken Fried
 #     %p.beans{ :food => 'true' } The magical fruit
 #     %h1.class.otherclass#id La La La
-#
+#
 # is compiled to:
-#
+#
 #   <div id='things'>
 #     <span id='rice'>Chicken Fried</span>
 #     <p class='beans' food='true'>The magical fruit</p>
 #     <h1 class='class otherclass' id='id'>La La La</h1>
 #   </div>
-#
+#
 # And,
-#
+#
 #   #content
 #     .articles
 #       .article.title
@@ -276,9 +304,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #         2006-11-05
 #       .article.entry
 #         Neil Patrick Harris would like to dispel any rumors that he is straight
-#
+#
 # is compiled to:
-#
+#
 #   <div id="content">
 #     <div class="articles">
 #       <div class="article title">Doogie Howser Comes Out</div>
@@ -288,34 +316,89 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #       </div>
 #     </div>
 #   </div>
-#
+#
 # ==== Implicit Div Elements
-#
+#
 # Because the div element is used so often, it is the default element.
 # If you only define a class and/or id using the <tt>.</tt> or <tt>#</tt> syntax,
 # a div element is automatically used.
 # For example:
-#
+#
 #   #collection
 #     .item
 #       .description What a cool item!
-#
+#
 # is the same as:
-#
+#
 #   %div{:id => collection}
 #     %div{:class => 'item'}
 #       %div{:class => 'description'} What a cool item!
-#
+#
 # and is compiled to:
-#
+#
 #   <div id='collection'>
 #     <div class='item'>
 #       <div class='description'>What a cool item!</div>
 #     </div>
 #   </div>
-#
+#
+# ==== > and <
+#
+# <tt>></tt> and <tt><</tt> give you more control over the whitespace near a tag.
+# <tt>></tt> will remove all whitespace surrounding a tag,
+# while <tt><</tt> will remove all whitespace immediately within a tag.
+# You can think of them as alligators eating the whitespace:
+# <tt>></tt> faces out of the tag and eats the whitespace on the outside,
+# and <tt><</tt> faces into the tag and eats the whitespace on the inside.
+# They're placed at the end of a tag definition,
+# after class, id, and attribute declarations
+# but before <tt>/</tt> or <tt>=</tt>.
+# For example:
+#
+#   %blockquote<
+#     %div
+#       Foo!
+#
+# is compiled to:
+#
+#   <blockquote><div>
+#     Foo!
+#   </div></blockquote>
+#
+# And:
+#
+#   %img
+#   %img>
+#   %img
+#
+# is compiled to:
+#
+#   <img /><img /><img />
+#
+# And:
+#
+#  %p<= "Foo\nBar"
+#
+# is compiled to:
+#
+#  <p>Foo
+#  Bar</p>
+#
+# And finally:
+#
+#   %img
+#   %pre><
+#     foo
+#     bar
+#   %img
+#
+# is compiled to:
+#
+#   <img /><pre>foo
+#   bar</pre><img />
+#
 # ==== =
-#
+#
 # <tt>=</tt> is placed at the end of a tag definition,
 # after class, id, and attribute declarations.
 # It's just a shortcut for inserting Ruby code into an element.
@@ -324,45 +407,63 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # However, if the result is short enough,
 # it is displayed entirely on one line.
 # For example:
-#
+#
 #   %p= "hello"
-#
+#
 # is not quite the same as:
-#
+#
 #   %p
 #     = "hello"
-#
+#
 # It's compiled to:
-#
+#
 #   <p>hello</p>
-#
+#
+# ==== ~
+#
+# ~ works just like =, except that it runs Haml::Helpers#find_and_preserve on its input.
+# For example,
+#
+#   ~ "Foo\n<pre>Bar\nBaz</pre>"
+#
+# is the same as:
+#
+#   = find_and_preserve("Foo\n<pre>Bar\nBaz</pre>")
+#
+# and is compiled to:
+#
+#   Foo
+#   <pre>Bar&#x000A;Baz</pre>
+#
+# See also Whitespace Preservation, below.
+#
 # === XHTML Helpers
-#
+#
 # ==== No Special Character
-#
+#
 # If no special character appears at the beginning of a line,
 # the line is rendered as plain text.
 # For example:
-#
+#
 #   %gee
 #     %whiz
 #       Wow this is cool!
-#
+#
 # is compiled to:
-#
+#
 #   <gee>
 #     <whiz>
 #       Wow this is cool!
 #     </whiz>
 #   </gee>
-#
+#
 # ==== !!!
-#
+#
 # When describing XHTML documents with Haml,
 # you can have a document type or XML prolog generated automatically
 # by including the characters <tt>!!!</tt>.
 # For example:
-#
+#
 #   !!! XML
 #   !!!
 #   %html
@@ -371,9 +472,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #     %body
 #       %h1 I am the international space station
 #       %p Sign my guestbook
-#
+#
 # is compiled to:
-#
+#
 #   <?xml version="1.0" encoding="utf-8" ?>
 #   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 #   <html>
@@ -385,112 +486,112 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #       <p>Sign my guestbook</p>
 #     </body>
 #   </html>
-#
+#
 # You can also specify the version and type of XHTML after the <tt>!!!</tt>.
 # XHTML 1.0 Strict, Transitional, and Frameset and XHTML 1.1 are supported.
 # The default version is 1.0 and the default type is Transitional.
 # For example:
-#
+#
 #   !!! 1.1
-#
+#
 # is compiled to:
-#
+#
 #   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-#
+#
 # and
-#
+#
 #   !!! Strict
-#
+#
 # is compiled to:
-#
+#
 #   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-#
+#
 # If you're not using the UTF-8 character set for your document,
 # you can specify which encoding should appear
 # in the XML prolog in a similar way.
 # For example:
-#
+#
 #   !!! XML iso-8859-1
-#
+#
 # is compiled to:
-#
+#
 #   <?xml version="1.0" encoding="iso-8859-1" ?>
-#
+#
 # ==== /
-#
+#
 # The forward slash character, when placed at the beginning of a line,
 # wraps all text after it in an HTML comment.
 # For example:
-#
+#
 #   %peanutbutterjelly
 #     / This is the peanutbutterjelly element
 #     I like sandwiches!
-#
+#
 # is compiled to:
-#
+#
 #   <peanutbutterjelly>
 #     <!-- This is the peanutbutterjelly element -->
 #     I like sandwiches!
 #   </peanutbutterjelly>
-#
+#
 # The forward slash can also wrap indented sections of code. For example:
-#
+#
 #   /
 #     %p This doesn't render...
 #     %div
 #       %h1 Because it's commented out!
-#
+#
 # is compiled to:
-#
+#
 #   <!--
 #     <p>This doesn't render...</p>
 #     <div>
 #       <h1>Because it's commented out!</h1>
 #     </div>
 #   -->
-#
+#
 # You can also use Internet Explorer conditional comments
 # (about)[http://www.quirksmode.org/css/condcom.html]
 # by enclosing the condition in square brackets after the <tt>/</tt>.
 # For example:
-#
+#
 #   /[if IE]
 #     %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
 #       %h1 Get Firefox
-#
+#
 # is compiled to:
-#
+#
 #   <!--[if IE]>
 #     <a href='http://www.mozilla.com/en-US/firefox/'>
 #       <h1>Get Firefox</h1>
 #     </a>
 #   <![endif]-->
-#
+#
 # ==== \
-#
+#
 # The backslash character escapes the first character of a line,
 # allowing use of otherwise interpreted characters as plain text.
 # For example:
-#
+#
 #   %title
 #     = @title
 #     \- MySite
-#
+#
 # is compiled to:
-#
+#
 #   <title>
 #     MyPage
 #     - MySite
 #   </title>
-#
+#
 # ==== |
-#
+#
 # The pipe character designates a multiline string.
 # It's placed at the end of a line
 # and means that all following lines that end with <tt>|</tt>
 # will be evaluated as though they were on the same line.
 # For example:
-#
+#
 #   %whoo
 #     %hoo I think this might get |
 #       pretty long so I should |
@@ -498,9 +599,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #       multiline so it doesn't |
 #       look awful. |
 #     %p This is short.
-#
+#
 # is compiled to:
-#
+#
 #   <whoo>
 #     <hoo>
 #       I think this might get pretty long so I should probably make it multiline so it doesn't look awful.
@@ -530,101 +631,180 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #     <p>Hello, <em>World</em></p>
 #   </p>
 #
+# Filters can have Ruby code interpolated, like with ==.
+# For example,
+#
+#   - flavor = "raspberry"
+#   #content
+#     :textile
+#       I *really* prefer _#{h flavor}_ jam.
+#
+# is compiled to
+#
+#   <div id='content'>
+#     <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
+#   </div>
+#
 # Haml has the following filters defined:
 #
-# [plain]     Does not parse the filtered text.
-#             This is useful for large blocks of text without HTML tags,
-#             when you don't want lines starting with <tt>.</tt> or <tt>-</tt>
-#             to be parsed.
+# [plain]      Does not parse the filtered text.
+#              This is useful for large blocks of text without HTML tags,
+#              when you don't want lines starting with <tt>.</tt> or <tt>-</tt>
+#              to be parsed.
+#
+# [javascript] Surrounds the filtered text with <script> and CDATA tags.
+#              Useful for including inline Javascript.
 #
-# [ruby]      Parses the filtered text with the normal Ruby interpreter.
-#             All output sent to <tt>$stdout</tt>, like with +puts+,
-#             is output into the Haml document.
-#             Not available if the <tt>suppress_eval</tt> option is set to true.
+# [escaped]    Works the same as plain, but HTML-escapes the text
+#              before placing it in the document.
 #
-# [preserve]  Inserts the filtered text into the template with whitespace preserved.
-#             <tt>preserve</tt>d blocks of text aren't indented,
-#             and newlines are replaced with the HTML escape code for newlines,
-#             to preserve nice-looking output.
+# [ruby]       Parses the filtered text with the normal Ruby interpreter.
+#              All output sent to <tt>$stdout</tt>, like with +puts+,
+#              is output into the Haml document.
+#              Not available if the <tt>suppress_eval</tt> option is set to true.
+#              The Ruby code is evaluated in the same context as the Haml template.
 #
-# [erb]       Parses the filtered text with ERB, like an RHTML template.
-#             Not available if the <tt>suppress_eval</tt> option is set to true.
-#             At the moment, this doesn't support access to variables
-#             defined by Ruby on Rails or Haml code.
+# [preserve]   Inserts the filtered text into the template with whitespace preserved.
+#              <tt>preserve</tt>d blocks of text aren't indented,
+#              and newlines are replaced with the HTML escape code for newlines,
+#              to preserve nice-looking output.
+#              See also Whitespace Preservation, below.
 #
-# [sass]      Parses the filtered text with Sass to produce CSS output.
+# [erb]        Parses the filtered text with ERB, like an RHTML template.
+#              Not available if the <tt>suppress_eval</tt> option is set to true.
+#              Embedded Ruby code is evaluated in the same context as the Haml template.
 #
-# [redcloth]  Parses the filtered text with RedCloth (http://whytheluckystiff.net/ruby/redcloth),
-#             which uses both Textile and Markdown syntax.
-#             Only works if RedCloth is installed.
+# [sass]       Parses the filtered text with Sass to produce CSS output.
 #
-# [textile]   Parses the filtered text with Textile (http://www.textism.com/tools/textile).
-#             Only works if RedCloth is installed.
+# [redcloth]   Parses the filtered text with RedCloth (http://whytheluckystiff.net/ruby/redcloth),
+#              which uses both Textile and Markdown syntax.
+#              Only works if RedCloth is installed.
 #
-# [markdown]  Parses the filtered text with Markdown (http://daringfireball.net/projects/markdown).
-#             Only works if RedCloth or BlueCloth (http://www.deveiate.org/projects/BlueCloth)
-#             is installed
-#             (BlueCloth takes precedence if both are installed).
+# [textile]    Parses the filtered text with Textile (http://www.textism.com/tools/textile).
+#              Only works if RedCloth is installed.
+#
+# [markdown]   Parses the filtered text with Markdown (http://daringfireball.net/projects/markdown).
+#              Only works if RedCloth or BlueCloth (http://www.deveiate.org/projects/BlueCloth)
+#              is installed
+#              (BlueCloth takes precedence if both are installed).
+#
+# You can also define your own filters (see Haml::Filters).
 #
-# You can also define your own filters (see Setting Options, below).
-#
 # === Ruby evaluators
-#
+#
 # ==== =
-#
+#
 # The equals character is followed by Ruby code,
 # which is evaluated and the output inserted into the document as plain text.
 # For example:
-#
+#
 #   %p
 #     = ['hi', 'there', 'reader!'].join " "
 #     = "yo"
-#
+#
 # is compiled to:
-#
+#
 #   <p>
 #     hi there reader!
 #     yo
 #   </p>
 #
-# You can also use two equal signs, <tt>==</tt>,
-# along with conventional Ruby string-embedding syntax
-# to easily embed Ruby code in otherwise static text.
-# For example:
+# If the <tt>:escape_html</tt> option is set, <tt>=</tt> will sanitize any
+# HTML-sensitive characters generated by the script. For example:
 #
-#   %p
-#     == 1 + 1 = #{1 + 1}
+#   = '<script>alert("I\'m evil!");</script>'
 #
-# is compiled to:
+# would be compiled to
+#
+#   &lt;script&gt;alert(&quot;I'm evil!&quot;);&lt;/script&gt;
 #
-#   <p>
-#     1 + 1 = 2
-#   </p>
-#
 # ==== -
-#
+#
 # The hyphen character makes the text following it into "silent script":
 # Ruby script that is evaluated, but not output.
-#
+#
 # <b>It is not recommended that you use this widely;
 # almost all processing code and logic should be restricted
 # to the Controller, the Helper, or partials.</b>
-#
+#
 # For example:
-#
+#
 #   - foo = "hello"
 #   - foo << " there"
 #   - foo << " you!"
 #   %p= foo
-#
+#
 # is compiled to:
-#
+#
 #   <p>
 #     hello there you!
 #   </p>
-#
+#
+# ==== ==
+#
+# Two equals characters interpolates Ruby code into plain text,
+# similarly to Ruby string interpolation.
+# For example,
+#
+#   %p== This is #{h quality} cake!
+#
+# is the same as
+#
+#   %p= "This is #{h quality} cake!"
+#
+# and might compile to
+#
+#   <p>This is scrumptious cake!</p>
+#
+# Backslashes can be used to escape "#{" strings,
+# but they don't act as escapes anywhere else in the string.
+# For example:
+#
+#   %p
+#     == \\ Look at \\#{h word} lack of backslash: \#{foo}
+#
+# might compile to
+#
+#  <p>
+#    \\ Look at \yon lack of backslash: #{foo}
+#  </p>
+#
+# ==== &=
+#
+# An ampersand followed by one or two equals characters
+# evaluates Ruby code just like the equals without the ampersand,
+# but sanitizes any HTML-sensitive characters in the result of the code.
+# For example:
+#
+#   &= "I like cheese & crackers"
+#
+# compiles to
+#
+#   I like cheese &amp; crackers
+#
+# If the <tt>:escape_html</tt> option is set,
+# &= behaves identically to =.
+#
+# ==== !=
+#
+# An exclamation mark followed by one or two equals characters
+# evaluates Ruby code just like the equals would,
+# but never sanitizes the HTML.
+#
+# By default, the single equals doesn't sanitize HTML either.
+# However, if the <tt>:escape_html</tt> option is set, = will sanitize the HTML, but != still won't.
+# For example, if <tt>:escape_html</tt> is set:
+#
+#   = "I feel <strong>!"
+#   != "I feel <strong>!"
+#
+# compiles to
+#
+#   I feel &lt;strong&gt;!
+#   I feel <strong>!
+#
 # ===== Blocks
-#
+#
 # Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
 # Rather, they're automatically closed, based on indentation.
 # A block begins whenever the indentation is increased
@@ -632,13 +812,13 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # It ends when the indentation decreases
 # (as long as it's not an +else+ clause or something similar).
 # For example:
-#
+#
 #   - (42...47).each do |i|
 #     %p= i
 #   %p See, I can count!
-#
+#
 # is compiled to:
-#
+#
 #   <p>
 #     42
 #   </p>
@@ -654,9 +834,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #   <p>
 #     46
 #   </p>
-#
+#
 # Another example:
-#
+#
 #   %p
 #     - case 2
 #     - when 1
@@ -665,9 +845,9 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #       = "2?"
 #     - when 3
 #       = "3."
-#
+#
 # is compiled to:
-#
+#
 #   <p>
 #     2?
 #   </p>
@@ -678,35 +858,52 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # signifies a silent comment.
 # Any text following this isn't rendered in the resulting document
 # at all.
-#
+#
 # For example:
 #
-# %p foo
-# -# This is a comment
-# %p bar
+#   %p foo
+#   -# This is a comment
+#   %p bar
 #
 # is compiled to:
 #
-# <p>foo</p>
-# <p>bar</p>
+#   <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
+#   %p foo
+#   -#
+#     This won't be displayed
+#       Nor will this
+#   %p bar
 #
 # is compiled to:
 #
-# <p>foo</p>
-# <p>bar</p>
-#
+#   <p>foo</p>
+#   <p>bar</p>
+#
 # == Other Useful Things
 #
+# === Whitespace Preservation
+#
+# Sometimes you don't want Haml to indent all your text.
+# For example, tags like +pre+ and +textarea+ are whitespace-sensitive;
+# indenting the text makes them render wrong.
+#
+# Haml deals with this by "preserving" newlines before they're put into the document --
+# converting them to the XHTML whitespace escape code, <tt>&#x000A;</tt>.
+# Then Haml won't try to re-format the indentation.
+#
+# Literal +textarea+ and +pre+ tags automatically preserve their content.
+# Dynamically can't be caught automatically,
+# and so should be passed through Haml::Helpers#find_and_preserve or the <tt>~</tt> command,
+# which has the same effect (see above).
+#
+# Blocks of literal text can be preserved using the :preserve filter (see above).
+#
 # === Helpers
 #
 # Haml offers a bunch of helpers that are useful
@@ -714,19 +911,30 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # creating nicely indented output for user-defined helpers,
 # and other useful things.
 # The helpers are all documented in the Haml::Helpers and Haml::Helpers::ActionViewExtensions modules.
-#
+#
 # === Haml Options
-#
+#
 # Options can be set by setting the hash <tt>Haml::Template.options</tt>
 # from <tt>environment.rb</tt> in Rails,
 # or by passing an options hash to Haml::Engine.
 # Available options are:
-#
+#
+# [<tt>:output</tt>]        Determines the output format. The default is :xhtml.
+#                           Other options are :html4 and :html5, which are
+#                           identical to :xhtml except there are no self-closing tags,
+#                           XML prolog is ignored and correct DOCTYPEs are generated.
+#
+# [<tt>:escape_html</tt>]   Sets whether or not to escape HTML-sensitive characters in script.
+#                           If this is true, = behaves like &=;
+#                           otherwise, it behaves like !=.
+#                           <b>Note that this escapes tag attributes.</b>
+#                           Defaults to false.
+#
 # [<tt>:suppress_eval</tt>] Whether or not attribute hashes and Ruby scripts
 #                           designated by <tt>=</tt> or <tt>~</tt> should be
 #                           evaluated. If this is true, said scripts are
 #                           rendered as empty strings. Defaults to false.
-#
+#
 # [<tt>:attr_wrapper</tt>]  The character that should wrap element attributes.
 #                           This defaults to <tt>'</tt> (an apostrophe). Characters
 #                           of this type within the attributes will be escaped
@@ -739,20 +947,75 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #                           so it's really only useful for the user to assign
 #                           when dealing with Haml programatically.
 #
-# [<tt>:filters</tt>]       A hash of filters that can be applied to Haml code.
-#                           The keys are the string names of the filters;
-#                           the values are references to the classes of the filters.
-#                           User-defined filters should always have lowercase keys,
-#                           and should have:
-#                           * An +initialize+ method that accepts one parameter,
-#                             the text to be filtered.
-#                           * A +render+ method that returns the result of the filtering.
+# [<tt>:line</tt>]          The line offset of the Haml template being parsed.
+#                           This is useful for inline templates,
+#                           similar to the last argument to Kernel#eval.
 #
 # [<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', 'br', 'hr', 'input', 'area']</tt>.
+#                           Defaults to <tt>['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']</tt>.
+#
+# [<tt>:preserve</tt>]      A list of tag names that should automatically have their newlines preserved
+#                           using the Haml::Helpers#preserve helper.
+#                           This means that any content given on the same line as the tag will be preserved.
+#                           For example:
+#
+#                             %textarea= "Foo\nBar"
+#
+#                           compiles to:
+#
+#                             <textarea>Foo&&#x000A;Bar</textarea>
+#
+#                           Defaults to <tt>['textarea', 'pre']</tt>.
+#
+#                           See also Whitespace Preservation, above.
 #
 module Haml
+  # Returns a hash representing the version of Haml.
+  # The :major, :minor, and :teeny keys have their respective numbers.
+  # The :string key contains a human-readable string representation of the version.
+  # If Haml is checked out from Git,
+  # the :rev key will have the revision hash.
+  def self.version
+    return @@version if defined?(@@version)
+    numbers = File.read(scope('VERSION')).strip.split('.').map { |n| n.to_i }
+    @@version = {
+      :major => numbers[0],
+      :minor => numbers[1],
+      :teeny => numbers[2]
+    }
+    @@version[:string] = [:major, :minor, :teeny].map { |comp| @@version[comp] }.compact.join('.')
+    if File.exists?(scope('REVISION'))
+      rev = File.read(scope('REVISION')).strip
+      rev = nil if rev !~ /[a-f0-9]+/
+    end
+    if rev.nil? && File.exists?(scope('.git/HEAD'))
+      rev = File.read(scope('.git/HEAD')).strip
+      if rev =~ /^ref: (.*)$/
+        rev = File.read(scope(".git/#{$1}")).strip
+      end
+    end
+    if rev
+      @@version[:rev] = rev
+      @@version[:string] << "." << rev[0...7]
+    end
+    @@version
+  end
+  # Returns the path of file relative to the Haml root.
+  def self.scope(file) # :nodoc:
+    File.join(File.dirname(__FILE__), '..', file)
+  end
+  # A string representing the version of Haml.
+  # A more fine-grained representation is generated by Haml.version.
+  VERSION = version[:string] unless defined?(Haml::VERSION)
   # 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