radiant 0.8.2 → 0.9.0.rc2

data/vendor/plugins/haml/extra/sass-mode.el

@@ -1,16 +1,25 @@
-;;; sass-mode.el -- Major mode for editing Sass files
-;;; Written by Nathan Weizenbaum
+;;; sass-mode.el --- Major mode for editing Sass files
 
-;;; Because Sass's indentation schema is similar
-;;; to that of YAML and Python, many indentation-related
-;;; functions are similar to those in yaml-mode and python-mode.
+;; Copyright (c) 2007, 2008 Nathan Weizenbaum
 
-;;; To install, save this somewhere and add the following to your .emacs file:
-;;;
-;;; (add-to-list 'load-path "/path/to/sass-mode.el")
-;;; (require 'sass-mode nil 't)
-;;; (add-to-list 'auto-mode-alist '("\\.sass$" . sass-mode))
-;;;
+;; Author: Nathan Weizenbaum
+;; URL: http://github.com/nex3/haml/tree/master
+;; Version: 2.2.18
+;; Created: 2007-03-15
+;; By: Nathan Weizenbaum
+;; Keywords: markup, language, css
+;; Package-Requires: ((haml-mode "2.2.18"))
+
+;;; Commentary:
+
+;; Because Sass's indentation schema is similar
+;; to that of YAML and Python, many indentation-related
+;; functions are similar to those in yaml-mode and python-mode.
+
+;; To install, save this on your load path and add the following to
+;; your .emacs file:
+;;
+;; (require 'sass-mode)
 
 ;;; Code:
 
@@ -36,34 +45,134 @@
 (defvar sass-non-block-openers
   '("^ *:[^ \t]+[ \t]+[^ \t]"
     "^ *[^ \t:]+[ \t]*[=:][ \t]*[^ \t]")
-  "A list of regexps that match lines of Sass that couldn't have
-text nested beneath them.")
+  "A list of regexps that match lines of Sass that don't open blocks.
+That is, a Sass line that can't have text nested beneath it
+should be matched by a regexp in this list.")
 
 ;; Font lock
 
+(defconst sass-selector-font-lock-keywords
+  '(;; Attribute selectors (e.g. p[foo=bar])
+    ("\\[\\([^]=]+\\)" (1 font-lock-variable-name-face)
+     ("[~|$^*]?=\\([^]=]+\\)" nil nil (1 font-lock-string-face)))
+    ("&"       0 font-lock-constant-face)
+    ("\\.\\w+" 0 font-lock-type-face)
+    ("#\\w+"   0 font-lock-keyword-face)
+    ;; Pseudo-selectors, optionally with arguments (e.g. :first, :nth-child(12))
+    ("\\(::?\\w+\\)" (1 font-lock-function-name-face)
+     ("(\\([^)]+\\))" nil nil (1 font-lock-string-face)))))
+
+(defconst sass-script-font-lock-keywords
+  `(("\"\\([^\"\\\\]\\|\\\\.\\)*\"" 0 font-lock-string-face)
+    ("!\\(\\w\\|_\\)+" 0 font-lock-variable-name-face)
+    ("#[0-9a-fA-F]\\{0,6\\}" 0 font-lock-preprocessor-face)
+    (,(regexp-opt
+       '("true" "false" "black" "silver" "gray" "white" "maroon" "red"
+         "purple" "fuchsia" "green" "lime" "olive" "yellow" "navy"
+         "blue" "teal" "aqua"))
+     0 font-lock-constant-face)
+    (,(regexp-opt '("and" "or" "not")) 0 font-lock-keyword-face)))
+
+(defconst sass-syntax-table
+  (let ((st (make-syntax-table)))
+    (modify-syntax-entry ?- "w" st)
+    (modify-syntax-entry ?_ "w" st)
+    st))
+
+(defconst sass-script-syntax-table
+  (let ((st (make-syntax-table sass-syntax-table)))
+    (modify-syntax-entry ?- "." st)
+    st))
+
 (defconst sass-font-lock-keywords
-  '(("^ *\\(\t\\)"                            1 'haml-tab-face)
-    ("^@.*"                                   0 font-lock-constant-face)
-    ("\\(\'[^']*'\\)"                         1 font-lock-string-face append)
-    ("\\(\"[^\"]*\"\\)"                       1 font-lock-string-face append)
-    ("\\(#[0-9a-fA-F]\\{3\\}\\{1,2\\}\\>\\)"  1 font-lock-string-face append)
-    ("\\(:[A-Za-z-]+\\|[A-Za-z-]+:\\)"        0 font-lock-constant-face append)
-    ("![a-z0-9_-]+"                           0 font-lock-variable-name-face append)
-    ("^ *\\(/[/*].*\\)$"                      1 font-lock-comment-face append)
-    ("\\(?:^\\|,\\) *\\(#[a-z0-9_-]+\/?\\)"   1 font-lock-keyword-face)
-    ("\\(?:^\\|,\\) *\\(\\.[a-z0-9_-]+\/?\\)" 1 font-lock-type-face)
-    ("\\(?:^\\|,\\) *\\(&\\|[a-z0-9_]+\/?\\)" 1 font-lock-function-name-face)
-    ("\\([=]\\)"                              0 font-lock-preprocessor-face prepend)
-    ("\\(?:^\\|,\\) *\\(#[a-z0-9_]+\/?\\)"    (1 font-lock-keyword-face)
-     ("\\.[a-z0-9_-]+" nil nil                (0 font-lock-type-face)))
-    ("\\(?:^\\|,\\) *\\(\\.[a-z0-9_]+\/?\\)"  (1 font-lock-type-face)
-     ("\\.[a-z0-9_-]+" nil nil                (0 font-lock-type-face)))
-    ("\\(?:^\\|,\\) *\\(\\.[a-z0-9_]+\/?\\)"  (1 font-lock-type-face)
-     ("\\#[a-z0-9_-]+" nil nil                (0 font-lock-keyword-face)))
-    ("\\(?:^\\|,\\) *\\(&\\|[a-z0-9_]+\/?\\)" (1 font-lock-function-name-face)
-     ("\\.[a-z0-9_-]+" nil nil                (0 font-lock-type-face)))
-    ("\\(?:^\\|,\\) *\\(&\\|[a-z0-9_]+\/?\\)" (1 font-lock-function-name-face)
-     ("\\#[a-z0-9_-]+" nil nil                (0 font-lock-keyword-face)))))
+  '((sass-highlight-line 1 nil nil t)))
+
+(defconst sass-line-keywords
+  '(("@\\(\\w+\\)"    0 font-lock-keyword-face sass-highlight-directive)
+    ("/[/*].*"  0 font-lock-comment-face)
+    ("[=+]\\w+" 0 font-lock-function-name-face sass-highlight-script-after-match)
+    ("!\\w+"    0 font-lock-variable-name-face sass-highlight-script-after-match)
+    (":\\w+"    0 font-lock-variable-name-face)
+    ("\\w+\s*:" 0 font-lock-variable-name-face)
+    ("\\(\\w+\\)\s*="  1 font-lock-variable-name-face sass-highlight-script-after-match)
+    ("\\(:\\w+\\)\s*=" 1 font-lock-variable-name-face sass-highlight-script-after-match)
+    (".*"      sass-highlight-selector))
+  "A list of full-line Sass syntax to highlight, used by `sass-highlight-line'.
+
+Each item is either of the form (REGEXP SUBEXP FACE), (REGEXP FN),
+or (REGEXP SUBEXP FACE FN).  Each REGEXP is run successively on the
+beginning of non-whitespace on the current line until one matches.
+If it has SUBEXP and FACE, then SUBEXP is highlighted using FACE.
+If it has FN, FN is run.")
+
+(defun sass-highlight-line (limit)
+  "Highlight a single line using some Sass single-line syntax.
+This syntax is taken from `sass-line-keywords'.
+LIMIT is the limit of the search."
+  (save-match-data
+    (when (re-search-forward "^ *\\(.+\\)$" limit t)
+      (goto-char (match-beginning 1))
+      (dolist (keyword sass-line-keywords)
+        (destructuring-bind (keyword subexp-or-fn &optional face fn) keyword
+          (when (looking-at keyword)
+            (if (integerp subexp-or-fn)
+                (put-text-property (match-beginning subexp-or-fn)
+                                   (match-end subexp-or-fn)
+                                   'face face)
+              (setq fn subexp-or-fn))
+            (when fn (funcall fn))
+            (end-of-line)
+            (return t)))))))
+
+(defun sass-highlight-selector ()
+  "Highlight a CSS selector starting at `point' and ending at `end-of-line'."
+  (let ((font-lock-keywords sass-selector-font-lock-keywords)
+        font-lock-multiline)
+    (font-lock-fontify-region
+     (point) (progn (end-of-line) (point))))
+  t)
+
+(defun sass-highlight-script (beg end)
+  "Highlight a section of SassScript between BEG and END."
+  (save-match-data
+    (with-syntax-table sass-script-syntax-table
+      (let ((font-lock-keywords sass-script-font-lock-keywords)
+            font-lock-syntax-table
+            font-lock-extend-region-functions)
+        (font-lock-fontify-region beg end)))))
+
+(defun sass-highlight-script-after-match ()
+  "Highlight a section of SassScript after the last match."
+  (end-of-line)
+  (sass-highlight-script (match-end 0) (point)))
+
+(defun sass-highlight-directive ()
+  "Highlight a Sass directive."
+  (goto-char (match-end 0))
+  (block nil
+    (case (intern (match-string 1))
+      (for
+       (unless (looking-at " +!\\w+") (return))
+       (put-text-property (match-beginning 0) (match-end 0)
+                          'face font-lock-variable-name-face)
+       (goto-char (match-end 0))
+       (unless (looking-at " +from") (return))
+       (put-text-property (match-beginning 0) (match-end 0)
+                          'face font-lock-keyword-face)
+       (goto-char (match-end 0))
+       (when (looking-at " +\\(.+?\\) +\\(to\\|through\\)")
+         (sass-highlight-script (match-beginning 1) (match-end 1))
+         (put-text-property (match-beginning 2) (match-end 2)
+                            'face font-lock-keyword-face))
+       (sass-highlight-script-after-match))
+
+      (else
+       (unless (looking-at " +if") (return))
+       (put-text-property (match-beginning 0) (match-end 0)
+                          'face font-lock-keyword-face)
+       (sass-highlight-script-after-match))
+
+      ((if while debug) (sass-highlight-script-after-match)))))
 
 ;; Constants
 
@@ -72,18 +181,26 @@ text nested beneath them.")
 ;;;###autoload
 (define-derived-mode sass-mode haml-mode "Sass"
   "Major mode for editing Sass files."
+  (set-syntax-table sass-syntax-table)
+  (setq font-lock-extend-region-functions
+        '(font-lock-extend-region-wholelines font-lock-extend-region-multiline))
+  (setq font-lock-multiline nil)
+  (setq comment-start "/*")
   (set (make-local-variable 'haml-indent-function) 'sass-indent-p)
   (set (make-local-variable 'haml-indent-offset) sass-indent-offset)
-  (setq font-lock-defaults '(sass-font-lock-keywords nil t)))
+  (setq font-lock-defaults '(sass-font-lock-keywords t t)))
 
 ;; Indentation
 
 (defun sass-indent-p ()
-  "Returns true if the current line can have lines nested beneath it."
+  "Return non-nil if the current line can have lines nested beneath it."
   (loop for opener in sass-non-block-openers
         unless (looking-at opener) return t
         return nil))
 
-;; Setup/Activation
+;;;###autoload
+(add-to-list 'auto-mode-alist '("\\.sass$" . sass-mode))
 
+;; Setup/Activation
 (provide 'sass-mode)
+;;; sass-mode.el ends here

data/vendor/plugins/haml/extra/update_watch.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'sinatra'
+require 'json'
+set :port, 3123
+set :environment, :production
+enable :lock
+Dir.chdir(File.dirname(__FILE__) + "/..")
+
+post "/" do
+  puts "Recieved payload!"
+  puts "Rev: #{`git name-rev HEAD`.strip}"
+  system %{rake handle_update --trace REF=#{JSON.parse(params["payload"])["ref"].inspect}}
+end

data/vendor/plugins/haml/haml.gemspec

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+# Note that Haml's gem-compilation process requires access to the filesystem.
+# This means that it cannot be automatically run by e.g. GitHub's gem system.
+# However, a build server automatically packages the master branch
+# every time it's pushed to; this is made available as the haml-edge gem.
+HAML_GEMSPEC = Gem::Specification.new do |spec|
+  spec.rubyforge_project = 'haml'
+  spec.name = File.exist?('EDGE_GEM_VERSION') ? 'haml-edge' : 'haml'
+  spec.summary = "An elegant, structured XHTML/XML templating engine.\nComes with Sass, a similar CSS templating engine."
+  spec.version = File.read('VERSION').strip
+  spec.authors = ['Nathan Weizenbaum', 'Hampton Catlin']
+  spec.email = 'haml@googlegroups.com'
+  spec.description = <<-END
+      Haml (HTML Abstraction Markup Language) is a layer on top of XHTML or XML
+      that's designed to express the structure of XHTML or XML documents
+      in a non-repetitive, elegant, easy way,
+      using indentation rather than closing tags
+      and allowing Ruby to be embedded with ease.
+      It was originally envisioned as a plugin for Ruby on Rails,
+      but it can function as a stand-alone templating engine.
+    END
+
+  spec.add_development_dependency 'yard', '>= 0.5.3'
+  spec.add_development_dependency 'maruku', '>= 0.5.9'
+
+  # We need the revision file to exist,
+  # so we just create it if it doesn't.
+  # It'll usually just get overwritten, though.
+  File.open('REVISION', 'w') { |f| f.puts "(unknown)" } unless File.exist?('REVISION')
+  readmes = FileList.new('*') do |list|
+    list.exclude(/(^|[^.a-z])[a-z]+/)
+    list.exclude('TODO')
+    list.include('REVISION')
+  end.to_a
+  spec.executables = ['haml', 'html2haml', 'sass', 'css2sass']
+  spec.files = FileList['rails/init.rb', 'lib/**/*', 'bin/*', 'test/**/*',
+    'extra/**/*', 'Rakefile', 'init.rb', '.yardopts'].to_a + readmes
+  spec.homepage = 'http://haml-lang.com/'
+  spec.has_rdoc = true
+  spec.extra_rdoc_files = readmes
+  spec.rdoc_options += [
+    '--title', 'Haml',
+    '--main', 'README.rdoc',
+    '--exclude', 'lib/haml/buffer.rb',
+    '--line-numbers',
+    '--inline-source'
+   ]
+  spec.test_files = FileList['test/**/*_test.rb'].to_a
+end

data/vendor/plugins/haml/init.rb

@@ -1,8 +1,16 @@
 begin
   require File.join(File.dirname(__FILE__), 'lib', 'haml') # From here
 rescue LoadError
-  require 'haml' # From gem
+  begin
+    require 'haml' # From gem
+  rescue LoadError => e
+    # gems:install may be run to install Haml with the skeleton plugin
+    # but not the gem itself installed.
+    # Don't die if this is the case.
+    raise e unless defined?(Rake) && Rake.application.top_level_tasks.include?('gems:install')
+  end
 end
 
-# Load Haml and Sass
-Haml.init_rails(binding)
+# Load Haml and Sass.
+# Haml may be undefined if we're running gems:install.
+Haml.init_rails(binding) if defined?(Haml)

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

@@ -3,1011 +3,33 @@ $LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
 
 require 'haml/version'
 
-# = Haml (XHTML Abstraction Markup Language)
+# The module that contains everything Haml-related:
 #
-# 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,
-# because it is actually an abstract description of the XHTML,
-# with some code to generate dynamic content.
-#
-# == Features
-#
-# * Whitespace active
-# * Well-formatted markup
-# * DRY
-# * Follows CSS conventions
-# * Integrates Ruby code
-# * Implements Rails templates with the .haml extension
-#
-# == Using Haml
-#
-# Haml can be used in three ways:
-# as a plugin for Ruby on Rails,
-# as a standalone Ruby module,
-# and as a command-line tool.
-# The first step for all of these is to install the Haml gem:
-#
-#   gem install haml
-#
-# To enable it as a Rails plugin,
-# then run
-#
-#   haml --rails path/to/rails/app
-#
-# Once it's installed, all view files with the ".html.haml" extension
-# will be compiled using Haml.
-#
-# To run Haml from the command line, just use
-#
-#   haml input.haml output.html
-#
-# Use <tt>haml --help</tt> for full documentation.
-#
-# You can access instance variables in Haml templates
-# 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>
-#       <a href='/'>Home</a>
-#     </div>
-#   </div>
-#
-# === Ruby Module
-#
-# Haml can also be used completely separately from Rails and ActionView.
-# To do this, install the gem with RubyGems:
-#
-#   gem install haml
-#
-# You can then use it by including the "haml" gem in Ruby code,
-# and using Haml::Engine like so:
-#
-#   engine = Haml::Engine.new("%p Haml code!")
-#   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,
-# so logic will work in it and local variables may be used.
-# Quote characters within the attribute
-# 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:
-#
-#   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' />
-#
-# Note that the Haml attributes list has the same syntax as a Ruby method call.
-# This means that any attribute methods must come before the hash literal.
-#
-# ===== 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
-# (transformed to use underlines rather than camel case)
-# 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, :greeting]
-#     %bar[290]/
-#     Hello!
-#
-# is compiled to:
-#
-#   <div class='greeting_crazy_user' id='greeting_crazy_user_15'>
-#     <bar class='fixnum' id='fixnum_581' />
-#     Hello!
-#   </div>
-#
-# ==== /
-#
-# 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' />
-#
-# Some tags are automatically closed, as long as they have no content.
-# +meta+, +img+, +link+, +script+, +br+, and +hr+ tags are closed by default.
-# This list can be customized by setting the <tt>:autoclose</tt> option (see below).
-# For example:
-#
-#   %br
-#   %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}
-#
-# is also compiled to:
-#
-#   <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.
-# Multiple class names can be specified in a similar way to CSS,
-# 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
-#         Doogie Howser Comes Out
-#       .article.date
-#         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>
-#       <div class='article date'>2006-11-05</div>
-#       <div class='article entry'>
-#         Neil Patrick Harris would like to dispel any rumors that he is straight
-#       </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.
-# It works the same as <tt>=</tt> without a tag:
-# it inserts the result of the Ruby code into the template.
-# 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
-#     %head
-#       %title Myspace
-#     %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>
-#     <head>
-#       <title>Myspace</title>
-#     </head>
-#     <body>
-#       <h1>I am the international space station</h1>
-#       <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">
-#
-# while 
-#
-#   !!! Basic
-#
-# is compiled to:
-#
-#   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> 
-#
-# and
-#   
-#   !!! Mobile
-#
-# is compiled to: 
-#
-#   <!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.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 |
-#       probably make it |
-#       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.
-#     </hoo>
-#     <p>This is short</p>
-#   </whoo>
-#
-# ==== :
-#
-# The colon character designates a filter.
-# This allows you to pass an indented block of text as input
-# to another filtering program and add the result to the output of Haml.
-# The syntax is simply a colon followed by the name of the filter.
-# For example,
-#
-#   %p
-#     :markdown
-#       Textile
-#       =======
-#
-#       Hello, *World*
-#
-# is compiled to
-#
-#   <p>
-#     <h1>Textile</h1>
-#
-#     <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.
-#
-# [javascript] Surrounds the filtered text with <script> and CDATA tags.
-#              Useful for including inline Javascript.
-#
-# [escaped]    Works the same as plain, but HTML-escapes the text
-#              before placing it in the document.
-#
-# [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.
-#
-# [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.
-#
-# [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.
-#
-# [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.
-#
-# [markdown]   Parses the filtered text with Markdown (http://daringfireball.net/projects/markdown).
-#              Only works if RDiscount, RPeg-Markdown, Maruku, or BlueCloth are installed.
-#
-# [maruku]     Parses the filtered text with Maruku, which has some non-standard extensions to Markdown.
-#
-# You can also define your own filters (see Haml::Filters).
-#
-# === 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>
-#
-# If the <tt>:escape_html</tt> option is set, <tt>=</tt> will sanitize any
-# HTML-sensitive characters generated by the script. For example:
-#
-#   = '<script>alert("I\'m evil!");</script>'
-#
-# would be compiled to
-#
-#   &lt;script&gt;alert(&quot;I'm evil!&quot;);&lt;/script&gt;
-#
-# ==== -
-#
-# 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
-# after a silent script command.
-# 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>
-#   <p>
-#     43
-#   </p>
-#   <p>
-#     44
-#   </p>
-#   <p>
-#     45
-#   </p>
-#   <p>
-#     46
-#   </p>
-#
-# Another example:
-#
-#   %p
-#     - case 2
-#     - when 1
-#       = "1!"
-#     - when 2
-#       = "2?"
-#     - when 3
-#       = "3."
-#
-# is compiled to:
-#
-#   <p>
-#     2?
-#   </p>
-#
-# ==== -#
-#
-# The hyphen followed immediately by the pound sign
-# 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
-#
-# is compiled to:
-#
-#   <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
-#
-# === 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
-# for doing stuff like preserving whitespace,
-# 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 <tt>Haml::Template.options</tt> hash
-# in <tt>environment.rb</tt> in Rails...
-#
-#   Haml::Template.options[:format] = :html5
-#
-# ...or by setting the <tt>Merb::Plugin.config[:haml]</tt> hash in <tt>init.rb</tt> in Merb...
-#
-#   Merb::Plugin.config[:haml][:format] = :html5
-# 
-# ...or by passing an options hash to Haml::Engine.new.
-# Available options are:
-#
-# [<tt>:format</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 !=.
-#                           Note that if this is set, != should be used for yielding to subtemplates
-#                           and rendering partials.
-#                           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
-#                           (e.g. by replacing them with <tt>&apos;</tt>) if
-#                           the character is an apostrophe or a quotation mark.
-#
-# [<tt>:filename</tt>]      The name of the Haml file being parsed.
-#                           This is only used as information when exceptions are raised.
-#                           This is automatically assigned when working through ActionView,
-#                           so it's really only useful for the user to assign
-#                           when dealing with Haml programatically.
-#
-# [<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', '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.
+# * {Haml::Engine} is the class used to render Haml within Ruby code.
+# * {Haml::Helpers} contains Ruby helpers available within Haml templates.
+# * {Haml::Template} interfaces with web frameworks (Rails in particular).
+# * {Haml::Error} is raised when Haml encounters an error.
+# * {Haml::HTML} handles conversion of HTML to Haml.
 #
+# Also see the {file:HAML_REFERENCE.md full Haml reference}.
 module Haml
-
   extend Haml::Version
 
   # A string representing the version of Haml.
   # A more fine-grained representation is available from Haml.version.
   VERSION = version[:string] unless defined?(Haml::VERSION)
 
-  # This method is called by init.rb,
+  # Initializes Haml for Rails.
+  #
+  # 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
+  # We use it rather than putting stuff straight into `init.rb`
   # so we can change the initialization behavior
   # without modifying the file itself.
+  #
+  # @param binding [Binding] The context of the `init.rb` file.
+  #   This isn't actually used;
+  #   it's just passed in in case it needs to be used in the future
   def self.init_rails(binding)
     # No &method here for Rails 2.1 compatibility
     %w[haml/template sass sass/plugin].each {|f| require f}