[Haml] Convert the Haml reference to YARD.
This commit is contained in:
parent
ac3c887203
commit
7a8ad96e42
324
lib/haml.rb
324
lib/haml.rb
|
@ -3,7 +3,7 @@ $LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
|
|||
|
||||
require 'haml/version'
|
||||
|
||||
# = Haml (XHTML Abstraction Markup Language)
|
||||
# # Haml (XHTML Abstraction Markup Language)
|
||||
#
|
||||
# Haml is a markup language
|
||||
# that's used to cleanly and simply describe the XHTML of any web document,
|
||||
|
@ -14,7 +14,7 @@ require 'haml/version'
|
|||
# because it is actually an abstract description of the XHTML,
|
||||
# with some code to generate dynamic content.
|
||||
#
|
||||
# == Features
|
||||
# ## Features
|
||||
#
|
||||
# * Whitespace active
|
||||
# * Well-formatted markup
|
||||
|
@ -23,7 +23,7 @@ require 'haml/version'
|
|||
# * Integrates Ruby code
|
||||
# * Implements Rails templates with the .haml extension
|
||||
#
|
||||
# == Using Haml
|
||||
# ## Using Haml
|
||||
#
|
||||
# Haml can be used in three ways:
|
||||
# as a plugin for Ruby on Rails,
|
||||
|
@ -38,17 +38,17 @@ require 'haml/version'
|
|||
#
|
||||
# haml --rails path/to/rails/app
|
||||
#
|
||||
# Once it's installed, all view files with the ".html.haml" extension
|
||||
# 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.
|
||||
# Use `haml --help` for full documentation.
|
||||
#
|
||||
# You can access instance variables in Haml templates
|
||||
# the same way you do in ERb 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):
|
||||
#
|
||||
|
@ -76,7 +76,7 @@ require 'haml/version'
|
|||
# </div>
|
||||
# </div>
|
||||
#
|
||||
# === Ruby Module
|
||||
# ### Ruby Module
|
||||
#
|
||||
# Haml can also be used completely separately from Rails and ActionView.
|
||||
# To do this, install the gem with RubyGems:
|
||||
|
@ -84,27 +84,27 @@ require 'haml/version'
|
|||
# gem install haml
|
||||
#
|
||||
# You can then use it by including the "haml" gem in Ruby code,
|
||||
# and using Haml::Engine like so:
|
||||
# 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
|
||||
# ## 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 <tt><element></element></tt>.
|
||||
# It creates an element in the form of `<element></element>`.
|
||||
# For example:
|
||||
#
|
||||
# %one
|
||||
|
@ -122,7 +122,7 @@ require 'haml/version'
|
|||
# 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.
|
||||
|
@ -151,11 +151,11 @@ require 'haml/version'
|
|||
#
|
||||
# <script src='javascripts/script_9' type='text/javascript'></script>
|
||||
#
|
||||
# ===== Attribute Methods
|
||||
# ##### 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:
|
||||
# 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}
|
||||
|
@ -195,9 +195,9 @@ require 'haml/version'
|
|||
# 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
|
||||
# ##### Boolean Attributes
|
||||
#
|
||||
# Some attributes, such as "checked" for <tt>input</tt> tags or "selected" for <tt>option</tt> tags,
|
||||
# Some attributes, such as "checked" for `input` tags or "selected" for `option` 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
|
||||
|
@ -222,11 +222,11 @@ require 'haml/version'
|
|||
#
|
||||
# <input>
|
||||
#
|
||||
# ==== . and #
|
||||
# #### . 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.
|
||||
# They are used as shortcuts to specify the `class`
|
||||
# and `id` 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.
|
||||
|
@ -249,10 +249,8 @@ require 'haml/version'
|
|||
#
|
||||
# #content
|
||||
# .articles
|
||||
# .article.title
|
||||
# Doogie Howser Comes Out
|
||||
# .article.date
|
||||
# 2006-11-05
|
||||
# .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
|
||||
#
|
||||
|
@ -268,10 +266,10 @@ require 'haml/version'
|
|||
# </div>
|
||||
# </div>
|
||||
#
|
||||
# ==== 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 <tt>.</tt> or <tt>#</tt> syntax,
|
||||
# If you only define a class and/or id using the `.` or `#` syntax,
|
||||
# a div element is automatically used.
|
||||
# For example:
|
||||
#
|
||||
|
@ -293,7 +291,7 @@ require 'haml/version'
|
|||
# </div>
|
||||
# </div>
|
||||
#
|
||||
# ==== /
|
||||
# #### /
|
||||
#
|
||||
# The forward slash character, when placed at the end of a tag definition,
|
||||
# causes the tag to be self-closed.
|
||||
|
@ -308,8 +306,8 @@ require 'haml/version'
|
|||
# <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).
|
||||
# `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
|
||||
|
@ -320,7 +318,7 @@ require 'haml/version'
|
|||
# <br />
|
||||
# <meta http-equiv='Content-Type' content='text/html' />
|
||||
#
|
||||
# ==== []
|
||||
# #### \[]
|
||||
#
|
||||
# Square brackets follow a tag definition and contain a Ruby object
|
||||
# that is used to set the class and id of that tag.
|
||||
|
@ -352,17 +350,17 @@ require 'haml/version'
|
|||
# Hello!
|
||||
# </div>
|
||||
#
|
||||
# ==== > and <
|
||||
# #### > 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.
|
||||
# `>` 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:
|
||||
# <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.
|
||||
# `>` 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 <tt>/</tt> or <tt>=</tt>.
|
||||
# but before `/` or `=`.
|
||||
# For example:
|
||||
#
|
||||
# %blockquote<
|
||||
|
@ -407,12 +405,12 @@ require 'haml/version'
|
|||
# <img /><pre>foo
|
||||
# bar</pre><img />
|
||||
#
|
||||
# ==== =
|
||||
# #### =
|
||||
#
|
||||
# <tt>=</tt> 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 <tt>=</tt> 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.
|
||||
|
@ -429,9 +427,9 @@ require 'haml/version'
|
|||
#
|
||||
# <p>hello</p>
|
||||
#
|
||||
# ==== #{}
|
||||
# #### `#{}`
|
||||
#
|
||||
# Ruby code can also be interpolated within plain text using <tt>#{}</tt>,
|
||||
# Ruby code can also be interpolated within plain text using `#{}`,
|
||||
# similarly to Ruby string interpolation.
|
||||
# For example,
|
||||
#
|
||||
|
@ -445,22 +443,25 @@ require 'haml/version'
|
|||
#
|
||||
# <p>This is scrumptious cake!</p>
|
||||
#
|
||||
# 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}
|
||||
# Look at \\#{h word} lack of backslash: \#{foo}
|
||||
# And yon presence thereof: \{foo}
|
||||
#
|
||||
# might compile to
|
||||
#
|
||||
# <p>
|
||||
# \\ Look at \yon lack of backslash: #{foo}
|
||||
# Look at \yon lack of backslash: #{foo}
|
||||
# And yon presence thereof: \{foo}
|
||||
# </p>
|
||||
#
|
||||
# ==== ~
|
||||
# {#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\n<pre>Bar\nBaz</pre>"
|
||||
|
@ -474,11 +475,11 @@ require 'haml/version'
|
|||
# Foo
|
||||
# <pre>Bar
Baz</pre>
|
||||
#
|
||||
# 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.
|
||||
|
@ -496,11 +497,11 @@ require 'haml/version'
|
|||
# </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>.
|
||||
# by including the characters `!!!`.
|
||||
# For example:
|
||||
#
|
||||
# !!! XML
|
||||
|
@ -526,7 +527,7 @@ require 'haml/version'
|
|||
# </body>
|
||||
# </html>
|
||||
#
|
||||
# You can also specify the version and type of XHTML after the <tt>!!!</tt>.
|
||||
# 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:
|
||||
|
@ -572,7 +573,7 @@ require 'haml/version'
|
|||
#
|
||||
# <?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.
|
||||
|
@ -605,9 +606,8 @@ require 'haml/version'
|
|||
# </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>.
|
||||
# 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]
|
||||
|
@ -622,7 +622,7 @@ require 'haml/version'
|
|||
# </a>
|
||||
# <![endif]-->
|
||||
#
|
||||
# ==== \
|
||||
# #### \
|
||||
#
|
||||
# The backslash character escapes the first character of a line,
|
||||
# allowing use of otherwise interpreted characters as plain text.
|
||||
|
@ -639,11 +639,11 @@ require 'haml/version'
|
|||
# - 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>
|
||||
# and means that all following lines that end with `|`
|
||||
# will be evaluated as though they were on the same line.
|
||||
# For example:
|
||||
#
|
||||
|
@ -664,7 +664,7 @@ require 'haml/version'
|
|||
# <p>This is short</p>
|
||||
# </whoo>
|
||||
#
|
||||
# ==== :
|
||||
# #### :
|
||||
#
|
||||
# The colon character designates a filter.
|
||||
# This allows you to pass an indented block of text as input
|
||||
|
@ -687,7 +687,7 @@ require 'haml/version'
|
|||
# <p>Hello, <em>World</em></p>
|
||||
# </p>
|
||||
#
|
||||
# Filters can have Ruby code interpolated, like with ==.
|
||||
# Filters can have Ruby code interpolated with `#{}`.
|
||||
# For example,
|
||||
#
|
||||
# - flavor = "raspberry"
|
||||
|
@ -703,50 +703,64 @@ require 'haml/version'
|
|||
#
|
||||
# Haml has the following filters defined:
|
||||
#
|
||||
# [plain] Does not parse the filtered text.
|
||||
# {#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 <tt>.</tt> or <tt>-</tt>
|
||||
# to be parsed.
|
||||
# when you don't want lines starting with `.` or `-` to be parsed.
|
||||
#
|
||||
# [javascript] Surrounds the filtered text with <script> and CDATA tags.
|
||||
# {#javascript-filter} javascript
|
||||
# : Surrounds the filtered text with `<script>` and CDATA tags.
|
||||
# Useful for including inline Javascript.
|
||||
#
|
||||
# [cdata] Surrounds the filtered text with CDATA tags.
|
||||
# {#cdata-filter} cdata
|
||||
# : Surrounds the filtered text with CDATA tags.
|
||||
#
|
||||
# [escaped] Works the same as plain, but HTML-escapes the text
|
||||
# {#escaped-filter} 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+,
|
||||
# {#ruby-filter} ruby
|
||||
# : Parses the filtered text with the normal Ruby interpreter.
|
||||
# All output sent to `$stdout`, like with `puts`,
|
||||
# is output into the Haml document.
|
||||
# Not available if the <tt>suppress_eval</tt> option is set to true.
|
||||
# Not available if the [`:suppress_eval`](#suppress_eval-option) 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,
|
||||
# {#preserve-filter} preserve
|
||||
# : Inserts the filtered text into the template with whitespace preserved.
|
||||
# `preserve`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.
|
||||
# See also [Whitespace Preservation](#whitespace_preservation).
|
||||
#
|
||||
# [erb] Parses the filtered text with ERB, like an RHTML template.
|
||||
# Not available if the <tt>suppress_eval</tt> option is set to true.
|
||||
# {#erb-filter} erb
|
||||
# : Parses the filtered text with ERB, like an RHTML template.
|
||||
# Not available if the [`:suppress_eval`](#suppress_eval-option) 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.
|
||||
# {#sass-filter} 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.
|
||||
# {#textile-filter} textile
|
||||
# : Parses the filtered text with [Textile](http://www.textism.com/tools/textile).
|
||||
# Only works if [RedCloth](http://redcloth.org) 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.
|
||||
# {#markdown-filter} markdown
|
||||
# : Parses the filtered text with [Markdown](http://daringfireball.net/projects/markdown).
|
||||
# Only works if [RDiscount](http://github.com/rtomayko/rdiscount),
|
||||
# [RPeg-Markdown](http://github.com/rtomayko/rpeg-markdown),
|
||||
# [Maruku](http://maruku.rubyforge.org),
|
||||
# or [BlueCloth](www.deveiate.org/projects/BlueCloth) are installed.
|
||||
#
|
||||
# [maruku] Parses the filtered text with Maruku, which has some non-standard extensions to Markdown.
|
||||
# {#maruku-filter} maruku
|
||||
# : Parses the filtered text with [Maruku](http://maruku.rubyforge.org),
|
||||
# which has some non-standard extensions to Markdown.
|
||||
#
|
||||
# You can also define your own filters (see Haml::Filters).
|
||||
# You can also define your own filters (see {Haml::Filters}).
|
||||
#
|
||||
# === Ruby evaluators
|
||||
# ### Ruby evaluators
|
||||
#
|
||||
# ==== =
|
||||
# #### =
|
||||
#
|
||||
# The equals character is followed by Ruby code,
|
||||
# which is evaluated and the output inserted into the document as plain text.
|
||||
|
@ -763,7 +777,7 @@ require 'haml/version'
|
|||
# yo
|
||||
# </p>
|
||||
#
|
||||
# If the <tt>:escape_html</tt> option is set, <tt>=</tt> will sanitize any
|
||||
# If the [`:escape_html`](#escape_html-option) option is set, `=` will sanitize any
|
||||
# HTML-sensitive characters generated by the script. For example:
|
||||
#
|
||||
# = '<script>alert("I\'m evil!");</script>'
|
||||
|
@ -772,14 +786,14 @@ require 'haml/version'
|
|||
#
|
||||
# <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.
|
||||
#
|
||||
# <b>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.</b>
|
||||
# to the Controller, the Helper, or partials.**
|
||||
#
|
||||
# For example:
|
||||
#
|
||||
|
@ -794,7 +808,7 @@ require 'haml/version'
|
|||
# hello there you!
|
||||
# </p>
|
||||
#
|
||||
# ==== &=
|
||||
# #### &=
|
||||
#
|
||||
# An ampersand followed by one or two equals characters
|
||||
# evaluates Ruby code just like the equals without the ampersand,
|
||||
|
@ -807,10 +821,10 @@ require 'haml/version'
|
|||
#
|
||||
# I like cheese & crackers
|
||||
#
|
||||
# If the <tt>:escape_html</tt> 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 <tt>#{}</tt> interpolation is escaped.
|
||||
# `&` can also be used on its own so that `#{}` interpolation is escaped.
|
||||
# For example,
|
||||
#
|
||||
# & I like #{"cheese & crackers"}
|
||||
|
@ -819,15 +833,16 @@ require 'haml/version'
|
|||
#
|
||||
# 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 <tt>:escape_html</tt> option is set, = will sanitize the HTML, but != still won't.
|
||||
# For example, if <tt>:escape_html</tt> 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 <strong>!"
|
||||
# != "I feel <strong>!"
|
||||
|
@ -837,7 +852,7 @@ require 'haml/version'
|
|||
# I feel <strong>!
|
||||
# I feel <strong>!
|
||||
#
|
||||
# ! can also be used on its own so that <tt>#{}</tt> interpolation is unescaped.
|
||||
# `!` can also be used on its own so that `#{}` interpolation is unescaped.
|
||||
# For example,
|
||||
#
|
||||
# ! I feel #{"<strong>"}!
|
||||
|
@ -846,14 +861,14 @@ require 'haml/version'
|
|||
#
|
||||
# I feel <strong>!
|
||||
#
|
||||
# ===== 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|
|
||||
|
@ -895,7 +910,7 @@ require 'haml/version'
|
|||
# 2?
|
||||
# </p>
|
||||
#
|
||||
# ==== -#
|
||||
# #### -#
|
||||
#
|
||||
# The hyphen followed immediately by the pound sign
|
||||
# signifies a silent comment.
|
||||
|
@ -928,101 +943,98 @@ require 'haml/version'
|
|||
# <p>foo</p>
|
||||
# <p>bar</p>
|
||||
#
|
||||
# == 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, <tt>
</tt>.
|
||||
# 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 <tt>~</tt> 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 <tt>Haml::Template.options</tt> hash
|
||||
# in <tt>environment.rb</tt> in Rails...
|
||||
# Options can be set by setting the {Haml::Template.options} hash
|
||||
# in `environment.rb` 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...
|
||||
# ...or by setting the `Merb::Plugin.config[:haml]` hash in `init.rb` in Merb...
|
||||
#
|
||||
# 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:
|
||||
#
|
||||
# [<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.
|
||||
# {#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.
|
||||
#
|
||||
# [<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
|
||||
# {#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.
|
||||
#
|
||||
#--
|
||||
#TODO: Make this an anchor when this becomes markdown
|
||||
#++
|
||||
# [<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.
|
||||
# {#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`.
|
||||
#
|
||||
# [<tt>:attr_wrapper</tt>] The character that should wrap element attributes.
|
||||
# This defaults to <tt>'</tt> (an apostrophe). Characters
|
||||
# {#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 <tt>'</tt>) if
|
||||
# (e.g. by replacing them with `'`) if
|
||||
# the character is an apostrophe or a quotation mark.
|
||||
#
|
||||
# [<tt>:filename</tt>] The name of the Haml file being parsed.
|
||||
# {#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.
|
||||
#
|
||||
# [<tt>:line</tt>] The line offset of the Haml template being parsed.
|
||||
# {#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.
|
||||
# similar to the last argument to `Kernel#eval`.
|
||||
#
|
||||
# [<tt>:autoclose</tt>] A list of tag names that should be automatically self-closed
|
||||
# {#autoclose-option} `:autoclose`
|
||||
# : 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>.
|
||||
# Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`.
|
||||
#
|
||||
# [<tt>:preserve</tt>] A list of tag names that should automatically have their newlines preserved
|
||||
# using the Haml::Helpers#preserve helper.
|
||||
# {#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:
|
||||
#
|
||||
# <textarea>Foo&
Bar</textarea>
|
||||
#
|
||||
# Defaults to <tt>['textarea', 'pre']</tt>.
|
||||
#
|
||||
# See also Whitespace Preservation, above.
|
||||
# For example, `%textarea= "Foo\nBar"` compiles to `<textarea>Foo
Bar</textarea>`.
|
||||
# Defaults to `['textarea', 'pre']`.
|
||||
# See also [Whitespace Preservation](#whitespace_preservation).
|
||||
#
|
||||
module Haml
|
||||
|
||||
|
@ -1032,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}
|
||||
|
|
|
@ -183,7 +183,7 @@ module Haml
|
|||
def render(text); text; end
|
||||
end
|
||||
|
||||
# Surrounds the filtered text with <script> and CDATA tags.
|
||||
# Surrounds the filtered text with `<script>` and CDATA tags.
|
||||
# Useful for including inline Javascript.
|
||||
module Javascript
|
||||
include Base
|
||||
|
|
Loading…
Reference in New Issue