Haml code!
\n" +# engine = Haml::Engine.new("%p Haml code!") +# engine.render #=> "Haml code!
\n" # -# == Characters with meaning to Haml +# ## 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 +# ### 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
-# Chicken Fried
-#
+# The magical fruit
-#La La La
-#
+# Chicken Fried
+#
#
# 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
+# #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:
#
-# The magical fruit
+#La La La
+#
-#
-#
Doogie Howser Comes Out
-# 2006-11-05
-#
-# Neil Patrick Harris would like to dispel any rumors that he is straight
+#
#
-# ==== Implicit Div Elements
+# #### 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 . or # syntax,
+# If you only define a class and/or id using the `.` or `#` syntax,
# a div element is automatically used.
# For example:
#
-# #collection
-# .item
-# .description What a cool item!
+# #collection
+# .item
+# .description What a cool item!
#
# is the same as:
#
-# %div{:id => collection}
-# %div{:class => 'item'}
-# %div{:class => 'description'} What a cool item!
+# %div{:id => collection}
+# %div{:class => 'item'}
+# %div{:class => 'description'} What a cool item!
#
# and is compiled to:
#
-#
+#
-#
+#
# Doogie Howser Comes Out
+# 2006-11-05
+#
+# Neil Patrick Harris would like to dispel any rumors that he is straight
+#
#
-#
-# +#
+# # # 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 :autoclose option (see below). +# `meta`, `img`, `link`, `script`, `br`, and `hr` tags are closed by default. +# This list can be customized by setting the [`:autoclose`](#autoclose-option) option (see below). # For example: # -# %br -# %meta{'http-equiv' => 'Content-Type', :content => 'text/html'} +# %br +# %meta{'http-equiv' => 'Content-Type', :content => 'text/html'} # # is also compiled to: # -#
-# +#
+# # -# ==== [] +# #### \[] # # Square brackets follow a tag definition and contain a Ruby object # that is used to set the class and id of that tag. @@ -333,338 +331,340 @@ require 'haml/version' # both the id and class attributes. # For example: # -# # file: app/controllers/users_controller.rb +# # file: app/controllers/users_controller.rb # -# def show -# @user = CrazyUser.find(15) -# end +# def show +# @user = CrazyUser.find(15) +# end # -# -# file: app/views/users/show.haml +# -# file: app/views/users/show.haml # -# %div[@user, :greeting] -# %bar[290]/ -# Hello! +# %div[@user, :greeting] +# %bar[290]/ +# Hello! # # is compiled to: # -#![]()
![]()
![]()
+# ![]()
![]()
![]()
#
# And:
#
-# %p<= "Foo\nBar"
+# %p<= "Foo\nBar"
#
# is compiled to:
#
-# ![]()
![]()
+# ![]()
![]()
#
-# ==== =
+# #### =
#
-# = is placed at the end of a tag definition,
+# `=` 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 = without a tag:
+# It works the same as `=` 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"
+# %p= "hello"
#
# is not quite the same as:
#
-# %p
-# = "hello"
+# %p
+# = "hello"
#
# It's compiled to:
#
-#
-#
-# Wow this is cool!
-#
-#
+#
+#
+# Wow this is cool!
+#
+#
#
-# ==== !!!
+# #### !!!
#
# When describing XHTML documents with Haml,
# you can have a document type or XML prolog generated automatically
-# by including the characters !!!.
+# by including the characters `!!!`.
# For example:
#
-# !!! XML
-# !!!
-# %html
-# %head
-# %title Myspace
-# %body
-# %h1 I am the international space station
-# %p Sign my guestbook
+# !!! XML
+# !!!
+# %html
+# %head
+# %title Myspace
+# %body
+# %h1 I am the international space station
+# %p Sign my guestbook
#
# is compiled to:
#
-#
-#
-#
-#
-# Myspace
-#
-#
-# Myspace
+#
+#
+#
-#
-# I like sandwiches!
-#
+#
+#
+# I like sandwiches!
+#
#
# The forward slash can also wrap indented sections of code. For example:
#
-# /
-# %p This doesn't render...
-# %div
-# %h1 Because it's commented out!
+# /
+# %p This doesn't render...
+# %div
+# %h1 Because it's commented out!
#
# is compiled to:
#
-#
+#
#
-# 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 /.
+# You can also use [Internet Explorer conditional comments](http://www.quirksmode.org/css/condcom.html)
+# by enclosing the condition in square brackets after the `/`.
# For example:
#
-# /[if IE]
-# %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
-# %h1 Get Firefox
+# /[if IE]
+# %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
+# %h1 Get Firefox
#
# is compiled to:
#
-#
+#
#
-# ==== \
+# #### \
#
# The backslash character escapes the first character of a line,
# allowing use of otherwise interpreted characters as plain text.
# For example:
#
-# %title
-# = @title
-# \- MySite
+# %title
+# = @title
+# \- MySite
#
# is compiled to:
#
-#
-# MyPage
-# - MySite
-#
+#
+# MyPage
+# - MySite
+#
#
-# ==== |
+# #### |
#
# 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 |
+# and means that all following lines that end with `|`
# 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.
+# %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:
#
-#
-#
-# I think this might get pretty long so I should probably make it multiline so it doesn't look awful.
-#
-#
+#
+#
+# I think this might get pretty long so I should probably make it multiline so it doesn't look awful.
+#
+#
#
-# ==== :
+# #### :
#
# The colon character designates a filter.
# This allows you to pass an indented block of text as input
@@ -672,230 +672,245 @@ require 'haml/version'
# The syntax is simply a colon followed by the name of the filter.
# For example,
#
-# %p
-# :markdown
-# Textile
-# =======
+# %p
+# :markdown
+# Textile
+# =======
#
-# Hello, *World*
+# Hello, *World*
#
# is compiled to
#
-# ] a hash of filter names to classes
def self.defined
@defined ||= {}
end
# The base module for Haml filters.
# User-defined filters should be modules including this module.
+ # The name of the filter is taken by downcasing the module name.
+ # For instance, if the module is named `FooBar`, the filter will be `:foobar`.
#
- # A user-defined filter should override either Base#render or Base #compile.
- # Base#render is the most common.
+ # A user-defined filter should override either \{#render} or {\#compile}.
+ # \{#render} is the most common.
# It takes a string, the filter source,
- # and returns another string,
- # the result of the filter.
- # For example:
+ # and returns another string, the result of the filter.
+ # For example, the following will define a filter named `:sass`:
#
- # module Haml::Filters::Sass
- # include Haml::Filters::Base
+ # module Haml::Filters::Sass
+ # include Haml::Filters::Base
#
- # def render(text)
- # ::Sass::Engine.new(text).render
+ # def render(text)
+ # ::Sass::Engine.new(text).render
+ # end
# end
- # end
#
- # For details on overriding #compile, see its documentation.
+ # For details on overriding \{#compile}, see its documentation.
#
+ # Note that filters overriding \{#render} automatically support `#{}`
+ # for interpolating Ruby code.
+ # Those overriding \{#compile} will need to add such support manually
+ # if it's desired.
module Base
- def self.included(base) # :nodoc:
+ # This method is automatically called when {Base} is included in a module.
+ # It automatically defines a filter
+ # with the downcased name of that module.
+ # For example, if the module is named `FooBar`, the filter will be `:foobar`.
+ #
+ # @param base [Module, Class] The module that this is included in
+ def self.included(base)
Filters.defined[base.name.split("::").last.downcase] = base
base.extend(base)
end
- # Takes a string, the source text that should be passed to the filter,
- # and returns the string resulting from running the filter on text.
+ # Takes the source text that should be passed to the filter
+ # and returns the result of running the filter on that string.
#
# This should be overridden in most individual filter modules
# to render text with the given filter.
- # If compile is overridden, however, render doesn't need to be.
+ # If \{#compile} is overridden, however, \{#render} doesn't need to be.
+ #
+ # @param text [String] The source text for the filter to process
+ # @return [String] The filtered result
+ # @raise [Haml::Error] if it's not overridden
def render(text)
raise Error.new("#{self.inspect}#render not defined!")
end
- # Same as render, but takes the Haml options hash as well.
- # It's only safe to rely on options made available in Haml::Engine#options_for_buffer.
+ # Same as \{#render}, but takes a {Haml::Engine} options hash as well.
+ # It's only safe to rely on options made available in {Haml::Engine#options\_for\_buffer}.
+ #
+ # @see #render
+ # @param text [String] The source text for the filter to process
+ # @return [String] The filtered result
+ # @raise [Haml::Error] if it or \{#render} isn't overridden
def render_with_options(text, options)
render(text)
end
- def internal_compile(*args) # :nodoc:
+ # Same as \{#compile}, but requires the necessary files first.
+ # *This is used by {Haml::Engine} and is not intended to be overridden or used elsewhere.*
+ #
+ # @see #compile
+ def internal_compile(*args)
resolve_lazy_requires
compile(*args)
end
- # compile should be overridden when a filter needs to have access
- # to the Haml evaluation context.
+ # This should be overridden when a filter needs to have access to the Haml evaluation context.
# Rather than applying a filter to a string at compile-time,
- # compile uses the Haml::Precompiler instance to compile the string to Ruby code
+ # \{#compile} uses the {Haml::Precompiler} instance to compile the string to Ruby code
# that will be executed in the context of the active Haml template.
#
- # Warning: the Haml::Precompiler interface is neither well-documented
+ # Warning: the {Haml::Precompiler} interface is neither well-documented
# nor guaranteed to be stable.
- # If you want to make use of it,
- # you'll probably need to look at the source code
+ # If you want to make use of it, you'll probably need to look at the source code
# and should test your filter when upgrading to new Haml versions.
+ #
+ # @param precompiler [Haml::Precompiler] The precompiler instance
+ # @param text [String] The text of the filter
+ # @raise [Haml::Error] if none of \{#compile}, \{#render}, and \{#render_with_options} are overridden
def compile(precompiler, text)
resolve_lazy_requires
filter = self
@@ -89,22 +116,22 @@ RUBY
end
end
- # This becomes a class method of modules that include Base.
+ # This becomes a class method of modules that include {Base}.
# It allows the module to specify one or more Ruby files
# that Haml should try to require when compiling the filter.
#
- # The first file specified is tried first,
- # then the second, etc.
+ # The first file specified is tried first, then the second, etc.
# If none are found, the compilation throws an exception.
#
# For example:
#
- # module Haml::Filters::Markdown
- # lazy_require 'rdiscount', 'peg_markdown', 'maruku', 'bluecloth'
+ # module Haml::Filters::Markdown
+ # lazy_require 'rdiscount', 'peg_markdown', 'maruku', 'bluecloth'
#
- # ...
- # end
+ # ...
+ # end
#
+ # @param reqs [Array] The requires to run
def lazy_require(*reqs)
@lazy_requires = reqs
end
@@ -139,23 +166,29 @@ RUBY
end
end
-# :stopdoc:
-
begin
require 'rubygems'
rescue LoadError; end
module Haml
module Filters
+ # 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 `.` or `-`
+ # to be parsed.
module Plain
include Base
+ # @see Base#render
def render(text); text; end
end
+ # Surrounds the filtered text with `
-#
#
-# ==== /
+# #### /
#
# 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'}/
+# %br/
+# %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
#
# is compiled to:
#
-# What a cool item!
+#
+#
-#
+#
# What a cool item!
+# -# +#
+# # # 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 :autoclose option (see below). +# `meta`, `img`, `link`, `script`, `br`, and `hr` tags are closed by default. +# This list can be customized by setting the [`:autoclose`](#autoclose-option) option (see below). # For example: # -# %br -# %meta{'http-equiv' => 'Content-Type', :content => 'text/html'} +# %br +# %meta{'http-equiv' => 'Content-Type', :content => 'text/html'} # # is also compiled to: # -#
-# +#
+# # -# ==== [] +# #### \[] # # Square brackets follow a tag definition and contain a Ruby object # that is used to set the class and id of that tag. @@ -333,338 +331,340 @@ require 'haml/version' # both the id and class attributes. # For example: # -# # file: app/controllers/users_controller.rb +# # file: app/controllers/users_controller.rb # -# def show -# @user = CrazyUser.find(15) -# end +# def show +# @user = CrazyUser.find(15) +# end # -# -# file: app/views/users/show.haml +# -# file: app/views/users/show.haml # -# %div[@user, :greeting] -# %bar[290]/ -# Hello! +# %div[@user, :greeting] +# %bar[290]/ +# Hello! # # is compiled to: # -#
-#
+#
+#
#
-# ==== > and <
+# #### > and <
#
-# > and < give you more control over the whitespace near a tag.
-# > will remove all whitespace surrounding a tag,
-# while < will remove all whitespace immediately within a tag.
+# `>` and `<` give you more control over the whitespace near a tag.
+# `>` will remove all whitespace surrounding a tag,
+# while `<` will remove all whitespace immediately within a tag.
# You can think of them as alligators eating the whitespace:
-# > faces out of the tag and eats the whitespace on the outside,
-# and < faces into the tag and eats the whitespace on the inside.
+# `>` faces out of the tag and eats the whitespace on the outside,
+# and `<` 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 / or =.
+# but before `/` or `=`.
# For example:
#
-# %blockquote<
-# %div
+# %blockquote<
+# %div
+# Foo!
+#
+# is compiled to:
+#
+# # # And: # -# %img -# %img> -# %img +# %img +# %img> +# %img # # is compiled to: # -## Foo! -# -# is compiled to: -# -#+#-# Foo! -#
Foo -# Bar
+#Foo +# Bar
# # And finally: # -# %img -# %pre>< -# foo -# bar -# %img +# %img +# %pre>< +# foo +# bar +# %img # # is compiled to: # -#foo -# bar
foo +# bar
hello
+#hello
# -# ==== #{} +# #### `#{}` # -# Ruby code can also be interpolated within plain text using #{}, +# Ruby code can also be interpolated within plain text using `#{}`, # similarly to Ruby string interpolation. # For example, # -# %p This is #{h quality} cake! +# %p This is #{h quality} cake! # # is the same as # -# %p= "This is the #{h quality} cake!" +# %p= "This is the #{h quality} cake!" # # and might compile to # -#This is scrumptious cake!
+#This is scrumptious cake!
# -# Backslashes can be used to escape "#{" strings, +# 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} +# %p +# Look at \\#{h word} lack of backslash: \#{foo} +# And yon presence thereof: \{foo} # # might compile to # -#-# \\ Look at \yon lack of backslash: #{foo} -#
+#+# Look at \yon lack of backslash: #{foo} +# And yon presence thereof: \{foo} +#
# -# ==== ~ +# {#tilde} +# #### ~ # -# ~ works just like =, except that it runs Haml::Helpers#find_and_preserve on its input. +# `~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve} on its input. # For example, # -# ~ "Foo\nBar\nBaz" +# ~ "Foo\n
Bar\nBaz" # # is the same as: # -# = find_and_preserve("Foo\n
Bar\nBaz") +# = find_and_preserve("Foo\n
Bar\nBaz") # # and is compiled to: # -# Foo -#
Bar Baz+# Foo +#
Bar Baz# -# See also Whitespace Preservation, below. +# See also [Whitespace Preservation](#whitespace_preservation). # -# === XHTML Helpers +# ### XHTML Helpers # -# ==== No Special Character +# #### 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! +# %gee +# %whiz +# Wow this is cool! # # is compiled to: # -#
I am the international space station
-#Sign my guestbook
-# -# +# +# +# +# +#I am the international space station
+#Sign my guestbook
+# +# # -# You can also specify the version and type of XHTML after the !!!. +# You can also specify the version and type of XHTML after the `!!!`. # 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 +# !!! 1.1 # # is compiled to: # -# +# # # and # -# !!! Strict +# !!! Strict # # is compiled to: # -# +# # # while # -# !!! Basic +# !!! Basic # # is compiled to: # -# +# # # and # -# !!! Mobile +# !!! Mobile # # is compiled to: # -# +# # # 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 +# !!! XML iso-8859-1 # # is compiled to: # -# +# # -# ==== / +# #### / # # 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! +# %peanutbutterjelly +# / This is the peanutbutterjelly element +# I like sandwiches! # # is compiled to: # -#This is short
-#This is short
+#-#
Textile
+#+#
Textile
# -#Hello, World
-# +#Hello, World
+# # -# Filters can have Ruby code interpolated, like with ==. +# Filters can have Ruby code interpolated with `#{}`. # For example, # -# - flavor = "raspberry" -# #content -# :textile -# I *really* prefer _#{h flavor}_ jam. +# - flavor = "raspberry" +# #content +# :textile +# I *really* prefer _#{h flavor}_ jam. # # is compiled to # -#
-#
+# I really prefer raspberry jam.
-#
+#
#
# 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 . or -
-# to be parsed.
+# {#plain-filter} 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 `.` or `-` to be parsed.
#
-# [javascript] Surrounds the filtered text with '
+# = ''
#
# would be compiled to
#
-# <script>alert("I'm evil!");</script>
+# <script>alert("I'm evil!");</script>
#
-# ==== -
+# #### -
#
# The hyphen character makes the text following it into "silent script":
# Ruby script that is evaluated, but not output.
#
-# It is not recommended that you use this widely;
+# **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.
+# to the Controller, the Helper, or partials.**
#
# For example:
#
-# - foo = "hello"
-# - foo << " there"
-# - foo << " you!"
-# %p= foo
+# - foo = "hello"
+# - foo << " there"
+# - foo << " you!"
+# %p= foo
#
# is compiled to:
#
-# I really prefer raspberry jam.
+#-# hello there you! -#
+#+# hello there you! +#
# -# ==== &= +# #### &= # # 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" +# &= "I like cheese & crackers" # # compiles to # -# I like cheese & crackers +# I like cheese & crackers # -# If the :escape_html option is set, -# &= behaves identically to =. +# If the [`:escape_html`](#escape_html-option) option is set, +# `&=` behaves identically to `=`. # -# & can also be used on its own so that #{} interpolation is escaped. +# `&` can also be used on its own so that `#{}` interpolation is escaped. # For example, # -# & I like #{"cheese & crackers"} +# & I like #{"cheese & crackers"} # # compiles to # -# I like cheese & crackers +# I like cheese & crackers # -# ==== != +# #### != # # 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 :escape_html option is set, = will sanitize the HTML, but != still won't. -# For example, if :escape_html is set: +# However, if the [`:escape_html`](#escape_html-option) option is set, +# `=` will sanitize the HTML, but `!=` still won't. +# For example, if `:escape_html` is set: # -# = "I feel !" -# != "I feel !" +# = "I feel !" +# != "I feel !" # # compiles to # -# I feel <strong>! -# I feel ! +# I feel <strong>! +# I feel ! # -# ! can also be used on its own so that #{} interpolation is unescaped. +# `!` can also be used on its own so that `#{}` interpolation is unescaped. # For example, # -# ! I feel #{""}! +# ! I feel #{""}! # # compiles to # -# I feel ! +# I feel ! # -# ===== Blocks +# ##### 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). +# (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! +# - (42...47).each do |i| +# %p= i +# %p See, I can count! # # is compiled to: # -#-# 42 -#
-#-# 43 -#
-#-# 44 -#
-#-# 45 -#
-#-# 46 -#
+#+# 42 +#
+#+# 43 +#
+#+# 44 +#
+#+# 45 +#
+#+# 46 +#
# # Another example: # -# %p -# - case 2 -# - when 1 -# = "1!" -# - when 2 -# = "2?" -# - when 3 -# = "3." +# %p +# - case 2 +# - when 1 +# = "1!" +# - when 2 +# = "2?" +# - when 3 +# = "3." # # is compiled to: # -#-# 2? -#
+#+# 2? +#
# -# ==== -# +# #### -# # # The hyphen followed immediately by the pound sign # signifies a silent comment. @@ -904,122 +919,122 @@ require 'haml/version' # # For example: # -# %p foo -# -# This is a comment -# %p bar +# %p foo +# -# This is a comment +# %p bar # # is compiled to: # -#foo
-#bar
+#foo
+#bar
# # 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: # -#foo
-#bar
+#foo
+#bar
# -# == Other Useful Things +# ## Other Useful Things # -# === Whitespace Preservation +# ### Whitespace Preservation # # Sometimes you don't want Haml to indent all your text. -# For example, tags like +pre+ and +textarea+ are whitespace-sensitive; +# 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, . +# converting them to the XHTML whitespace escape code, ` `. # Then Haml won't try to re-format the indentation. # -# Literal +textarea+ and +pre+ tags automatically preserve their content. +# 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 ~ command, -# which has the same effect (see above). +# and so should be passed through {Haml::Helpers#find\_and\_preserve} or the [`~` command](#tilde), +# which has the same effect. # -# Blocks of literal text can be preserved using the :preserve filter (see above). +# Blocks of literal text can be preserved using the [`:preserve` filter](#preserve-filter). # -# === Helpers +# ### 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. +# The helpers are all documented in the {Haml::Helpers} and {Haml::Helpers::ActionViewExtensions} modules. # -# === Haml Options +# ### Haml Options # -# Options can be set by setting the Haml::Template.options hash -# in environment.rb in Rails... +# Options can be set by setting the {Haml::Template.options} hash +# in `environment.rb` in Rails... # -# Haml::Template.options[:format] = :html5 +# Haml::Template.options[:format] = :html5 # -# ...or by setting the Merb::Plugin.config[:haml] hash in init.rb in Merb... +# ...or by setting the `Merb::Plugin.config[:haml]` hash in `init.rb` in Merb... # -# Merb::Plugin.config[:haml][:format] = :html5 +# Merb::Plugin.config[:haml][:format] = :html5 # -# ...or by passing an options hash to Haml::Engine.new. +# ...or by passing an options hash to {Haml::Engine.new}. # Available options are: # -# [:format] 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. +# {#format-option} `:format` +# : 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, +# the XML prolog is ignored and correct DOCTYPEs are generated. # -# [:escape_html] 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. +# {#escape_html-option} `:escape_html` +# : 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. # -# [:suppress_eval] Whether or not attribute hashes and Ruby scripts -# designated by = or ~ should be -# evaluated. If this is true, said scripts are -# rendered as empty strings. Defaults to false. +# {#suppress_eval-option} `:suppress_eval` +# : Whether or not attribute hashes and Ruby scripts +# designated by `=` or `~` should be +# evaluated. If this is `true`, said scripts are +# rendered as empty strings. Defaults to `false`. # -# [:attr_wrapper] The character that should wrap element attributes. -# This defaults to ' (an apostrophe). Characters -# of this type within the attributes will be escaped -# (e.g. by replacing them with ') if -# the character is an apostrophe or a quotation mark. +# {#attr_wrapper-option} `:attr_wrapper` +# : The character that should wrap element attributes. +# This defaults to `'` (an apostrophe). Characters +# of this type within the attributes will be escaped +# (e.g. by replacing them with `'`) if +# the character is an apostrophe or a quotation mark. # -# [:filename] 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. +# {#filename-option} `:filename` +# : 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. # -# [:line] The line offset of the Haml template being parsed. -# This is useful for inline templates, -# similar to the last argument to Kernel#eval. +# {#line-option} `:line` +# : The line offset of the Haml template being parsed. +# This is useful for inline templates, +# similar to the last argument to `Kernel#eval`. # -# [:autoclose] A list of tag names that should be automatically self-closed -# if they have no content. -# Defaults to ['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']. +# {#autoclose-option} `:autoclose` +# : A list of tag names that should be automatically self-closed +# if they have no content. +# Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`. # -# [:preserve] 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: -# -# -# -# Defaults to ['textarea', 'pre']. -# -# See also Whitespace Preservation, above. +# {#preserve-option} `:preserve` +# : 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 ``. +# Defaults to `['textarea', 'pre']`. +# See also [Whitespace Preservation](#whitespace_preservation). # module Haml @@ -1029,11 +1044,17 @@ module 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} diff --git a/lib/haml/filters.rb b/lib/haml/filters.rb index 3b0c3fdb..fc142101 100644 --- a/lib/haml/filters.rb +++ b/lib/haml/filters.rb @@ -1,71 +1,98 @@ module Haml - # The module containing the default filters, - # as well as the base module, - # Haml::Filters::Base. + # The module containing the default Haml filters, + # as well as the base module, {Haml::Filters::Base}. + # + # @see Haml::Filters::Base module Filters - # Returns a hash of defined filters. + # @return [Hash