haml 6.0.0.beta.1-java

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. checksums.yaml +7 -0
  2. data/.github/FUNDING.yml +1 -0
  3. data/.github/workflows/test.yml +40 -0
  4. data/.gitignore +19 -0
  5. data/CHANGELOG.md +1515 -0
  6. data/FAQ.md +147 -0
  7. data/Gemfile +23 -0
  8. data/MIT-LICENSE +20 -0
  9. data/README.md +210 -0
  10. data/REFERENCE.md +1380 -0
  11. data/Rakefile +116 -0
  12. data/bin/bench +66 -0
  13. data/bin/console +11 -0
  14. data/bin/ruby +3 -0
  15. data/bin/setup +7 -0
  16. data/bin/stackprof +27 -0
  17. data/bin/test +24 -0
  18. data/exe/haml +6 -0
  19. data/ext/haml/extconf.rb +10 -0
  20. data/ext/haml/haml.c +537 -0
  21. data/ext/haml/hescape.c +108 -0
  22. data/ext/haml/hescape.h +20 -0
  23. data/haml.gemspec +47 -0
  24. data/lib/haml/ambles.rb +20 -0
  25. data/lib/haml/attribute_builder.rb +175 -0
  26. data/lib/haml/attribute_compiler.rb +128 -0
  27. data/lib/haml/attribute_parser.rb +110 -0
  28. data/lib/haml/cli.rb +154 -0
  29. data/lib/haml/compiler/children_compiler.rb +126 -0
  30. data/lib/haml/compiler/comment_compiler.rb +39 -0
  31. data/lib/haml/compiler/doctype_compiler.rb +46 -0
  32. data/lib/haml/compiler/script_compiler.rb +116 -0
  33. data/lib/haml/compiler/silent_script_compiler.rb +24 -0
  34. data/lib/haml/compiler/tag_compiler.rb +76 -0
  35. data/lib/haml/compiler.rb +97 -0
  36. data/lib/haml/dynamic_merger.rb +67 -0
  37. data/lib/haml/engine.rb +53 -0
  38. data/lib/haml/error.rb +16 -0
  39. data/lib/haml/escapable.rb +13 -0
  40. data/lib/haml/filters/base.rb +12 -0
  41. data/lib/haml/filters/cdata.rb +20 -0
  42. data/lib/haml/filters/coffee.rb +17 -0
  43. data/lib/haml/filters/css.rb +33 -0
  44. data/lib/haml/filters/erb.rb +10 -0
  45. data/lib/haml/filters/escaped.rb +22 -0
  46. data/lib/haml/filters/javascript.rb +33 -0
  47. data/lib/haml/filters/less.rb +20 -0
  48. data/lib/haml/filters/markdown.rb +11 -0
  49. data/lib/haml/filters/plain.rb +29 -0
  50. data/lib/haml/filters/preserve.rb +22 -0
  51. data/lib/haml/filters/ruby.rb +10 -0
  52. data/lib/haml/filters/sass.rb +15 -0
  53. data/lib/haml/filters/scss.rb +15 -0
  54. data/lib/haml/filters/text_base.rb +25 -0
  55. data/lib/haml/filters/tilt_base.rb +49 -0
  56. data/lib/haml/filters.rb +75 -0
  57. data/lib/haml/force_escapable.rb +29 -0
  58. data/lib/haml/haml_error.rb +66 -0
  59. data/lib/haml/helpers.rb +15 -0
  60. data/lib/haml/html.rb +22 -0
  61. data/lib/haml/identity.rb +13 -0
  62. data/lib/haml/object_ref.rb +30 -0
  63. data/lib/haml/parser.rb +986 -0
  64. data/lib/haml/rails_helpers.rb +51 -0
  65. data/lib/haml/rails_template.rb +55 -0
  66. data/lib/haml/railtie.rb +15 -0
  67. data/lib/haml/ruby_expression.rb +32 -0
  68. data/lib/haml/string_splitter.rb +20 -0
  69. data/lib/haml/template.rb +20 -0
  70. data/lib/haml/temple_line_counter.rb +31 -0
  71. data/lib/haml/util.rb +260 -0
  72. data/lib/haml/version.rb +4 -0
  73. data/lib/haml.rb +13 -0
  74. metadata +359 -0
data/REFERENCE.md ADDED
@@ -0,0 +1,1380 @@
1
+ # Haml (HTML Abstraction Markup Language)
2
+
3
+ Haml is a markup language that's used to cleanly and simply describe the HTML of
4
+ any web document, without the use of inline code. Haml functions as a
5
+ replacement for inline page templating systems such as PHP, ERB, and ASP.
6
+ However, Haml avoids the need for explicitly coding HTML into the template,
7
+ because it is actually an abstract description of the HTML, with some code to
8
+ generate dynamic content.
9
+
10
+ ## Features
11
+
12
+ * Whitespace active
13
+ * Well-formatted markup
14
+ * DRY
15
+ * Follows CSS conventions
16
+ * Integrates Ruby code
17
+ * Implements Rails templates with the .haml extension
18
+
19
+ ## Using Haml
20
+
21
+ Haml can be used in three ways:
22
+
23
+ * as a command-line tool,
24
+ * as a plugin for Ruby on Rails,
25
+ * and as a standalone Ruby module.
26
+
27
+ The first step for all of these is to install the Haml gem:
28
+
29
+ gem install haml
30
+
31
+ To run Haml from the command line, just use
32
+
33
+ haml input.haml output.html
34
+
35
+ Use `haml --help` for full documentation.
36
+
37
+ To use Haml with Rails, add the following line to the Gemfile:
38
+
39
+ gem "haml"
40
+
41
+ Once it's installed, all view files with the `".html.haml"` extension will be
42
+ compiled using Haml.
43
+
44
+ You can access instance variables in Haml templates the same way you do in ERB
45
+ templates. Helper methods are also available in Haml templates. For example:
46
+
47
+ # file: app/controllers/movies_controller.rb
48
+
49
+ class MoviesController < ApplicationController
50
+ def index
51
+ @title = "Teen Wolf"
52
+ end
53
+ end
54
+
55
+ -# file: app/views/movies/index.html.haml
56
+
57
+ #content
58
+ .title
59
+ %h1= @title
60
+ = link_to 'Home', home_url
61
+
62
+ may be compiled to:
63
+
64
+ <div id='content'>
65
+ <div class='title'>
66
+ <h1>Teen Wolf</h1>
67
+ <a href='/'>Home</a>
68
+ </div>
69
+ </div>
70
+
71
+ ### Rails XSS Protection
72
+
73
+ Haml supports Rails' XSS protection scheme, which was introduced in Rails 2.3.5+
74
+ and is enabled by default in 3.0.0+. If it's enabled, Haml's
75
+ {Haml::Options#escape_html `:escape_html`} option is set to `true` by default -
76
+ like in ERB, all strings printed to a Haml template are escaped by default. Also
77
+ like ERB, strings marked as HTML safe are not escaped. Haml also has [its own
78
+ syntax for printing a raw string to the template](#unescaping_html).
79
+
80
+ If the `:escape_html` option is set to false when XSS protection is enabled,
81
+ Haml doesn't escape Ruby strings by default. However, if a string marked
82
+ HTML-safe is passed to [Haml's escaping syntax](#escaping_html), it won't be
83
+ escaped.
84
+
85
+ Finally, all the {Haml::Helpers Haml helpers} that return strings that are known
86
+ to be HTML safe are marked as such. In addition, string input is escaped unless
87
+ it's HTML safe.
88
+
89
+ ### Ruby Module
90
+
91
+ Haml can also be used completely separately from Rails and ActionView. To do
92
+ this, install the gem with RubyGems:
93
+
94
+ gem install haml
95
+
96
+ You can then use it by including the "haml" gem in Ruby code, and using
97
+ {Haml::Engine} like so:
98
+
99
+ engine = Haml::Engine.new("%p Haml code!")
100
+ engine.render #=> "<p>Haml code!</p>\n"
101
+
102
+ ### Options
103
+
104
+ Haml understands various configuration options that affect its performance and
105
+ output.
106
+
107
+ In Rails, options can be set by setting the {Haml::Template#options Haml::Template.options}
108
+ hash in an initializer:
109
+
110
+ ```ruby
111
+ # config/initializers/haml.rb
112
+ Haml::Template.options[:format] = :html5
113
+
114
+ # Avoid escaping attributes which are already escaped
115
+ Haml::Template.options[:escape_attrs] = :once
116
+ ```
117
+
118
+ Outside Rails, you can set them by configuring them globally in
119
+ Haml::Options.defaults:
120
+
121
+ ```ruby
122
+ Haml::Options.defaults[:format] = :html5
123
+ ```
124
+
125
+ In sinatra specifically, you can set them in global config with:
126
+ ```ruby
127
+ set :haml, { escape_html: true }
128
+ ```
129
+
130
+ Finally, you can also set them by passing an options hash to
131
+ {Haml::Engine#initialize}. For the complete list of available options, please
132
+ see {Haml::Options}.
133
+
134
+ ### Encodings
135
+
136
+ Haml supports the same sorts of
137
+ encoding-declaration comments that Ruby does. Although both Ruby and Haml
138
+ support several different styles, the easiest it just to add `-# coding:
139
+ encoding-name` at the beginning of the Haml template (it must come before all
140
+ other lines). This will tell Haml that the template is encoded using the named
141
+ encoding.
142
+
143
+ By default, the HTML generated by Haml has the same encoding as the Haml
144
+ template. However, if `Encoding.default_internal` is set, Haml will attempt to
145
+ use that instead. In addition, the {Haml::Options#encoding `:encoding` option}
146
+ can be used to specify an output encoding manually.
147
+
148
+ Note that, like Ruby, Haml does not support templates encoded in UTF-16 or
149
+ UTF-32, since these encodings are not compatible with ASCII. It is possible to
150
+ use these as the output encoding, though.
151
+
152
+ ## Plain Text
153
+
154
+ A substantial portion of any HTML document is its content, which is plain old
155
+ text. Any Haml line that's not interpreted as something else is taken to be
156
+ plain text, and passed through unmodified. For example:
157
+
158
+ %gee
159
+ %whiz
160
+ Wow this is cool!
161
+
162
+ is compiled to:
163
+
164
+ <gee>
165
+ <whiz>
166
+ Wow this is cool!
167
+ </whiz>
168
+ </gee>
169
+
170
+ Note that HTML tags are passed through unmodified as well. If you have some HTML
171
+ you don't want to convert to Haml, or you're converting a file line-by-line, you
172
+ can just include it as-is. For example:
173
+
174
+ %p
175
+ <div id="blah">Blah!</div>
176
+
177
+ is compiled to:
178
+
179
+ <p>
180
+ <div id="blah">Blah!</div>
181
+ </p>
182
+
183
+ ### Escaping: `\`
184
+
185
+ The backslash character escapes the first character of a line, allowing use of
186
+ otherwise interpreted characters as plain text. For example:
187
+
188
+ %title
189
+ = @title
190
+ \= @title
191
+
192
+ is compiled to:
193
+
194
+ <title>
195
+ MyPage
196
+ = @title
197
+ </title>
198
+
199
+ ## HTML Elements
200
+
201
+ ### Element Name: `%`
202
+
203
+ The percent character is placed at the beginning of a line. It's followed
204
+ immediately by the name of an element, then optionally by modifiers (see below),
205
+ a space, and text to be rendered inside the element. It creates an element in
206
+ the form of `<element></element>`. For example:
207
+
208
+ %one
209
+ %two
210
+ %three Hey there
211
+
212
+ is compiled to:
213
+
214
+ <one>
215
+ <two>
216
+ <three>Hey there</three>
217
+ </two>
218
+ </one>
219
+
220
+ Any string is a valid element name; Haml will automatically generate opening and
221
+ closing tags for any element.
222
+
223
+ ### Attributes: `{}` or `()` {#attributes}
224
+
225
+ Brackets represent a Ruby hash that is used for specifying the attributes of an
226
+ element. It is literally evaluated as a Ruby hash, so logic will work in it and
227
+ local variables may be used. Quote characters within the attribute will be
228
+ replaced by appropriate escape sequences. The hash is placed after the tag is
229
+ defined. For example:
230
+
231
+ %html{:xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en"}
232
+
233
+ is compiled to:
234
+
235
+ <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'></html>
236
+
237
+ Attribute hashes can also be stretched out over multiple lines to accommodate
238
+ many attributes.
239
+
240
+ %script{
241
+ "type": text/javascript",
242
+ "src": javascripts/script_#{2 + 7}",
243
+ "data": {
244
+ "controller": "reporter",
245
+ },
246
+ }
247
+
248
+ is compiled to:
249
+
250
+ <script src='javascripts/script_9' type='text/javascript' data-controller='reporter'></script>
251
+
252
+ #### `:class` and `:id` Attributes {#class-and-id-attributes}
253
+
254
+ The `:class` and `:id` attributes can also be specified as a Ruby array whose
255
+ elements will be joined together. A `:class` array is joined with `" "` and an
256
+ `:id` array is joined with `"_"`. For example:
257
+
258
+ %div{:id => [@item.type, @item.number], :class => [@item.type, @item.urgency]}
259
+
260
+ is equivalent to:
261
+
262
+ %div{:id => "#{@item.type}_#{@item.number}", :class => "#{@item.type} #{@item.urgency}"}
263
+
264
+ The array will first be flattened and any elements that do not test as true will
265
+ be removed. The remaining elements will be converted to strings. For example:
266
+
267
+ %div{:class => [@item.type, @item == @sortcol && [:sort, @sortdir]] } Contents
268
+
269
+ could render as any of:
270
+
271
+ <div class="numeric sort ascending">Contents</div>
272
+ <div class="numeric">Contents</div>
273
+ <div class="sort descending">Contents</div>
274
+ <div>Contents</div>
275
+
276
+ depending on whether `@item.type` is `"numeric"` or `nil`, whether `@item == @sortcol`,
277
+ and whether `@sortdir` is `"ascending"` or `"descending"`.
278
+
279
+ If a single value is specified and it evaluates to false it is ignored;
280
+ otherwise it gets converted to a string. For example:
281
+
282
+ .item{:class => @item.is_empty? && "empty"}
283
+
284
+ could render as either of:
285
+
286
+ class="item"
287
+ class="item empty"
288
+
289
+ #### HTML-style Attributes: `()`
290
+
291
+ Haml also supports a terser, less Ruby-specific attribute syntax based on HTML's
292
+ attributes. These are used with parentheses instead of brackets, like so:
293
+
294
+ %html(xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en")
295
+
296
+ Ruby variables can be used by omitting the quotes. Local variables or instance
297
+ variables can be used. For example:
298
+
299
+ %a(title=@title href=href) Stuff
300
+
301
+ This is the same as:
302
+
303
+ %a{:title => @title, :href => href} Stuff
304
+
305
+ Because there are no commas separating attributes, though, more complicated
306
+ expressions aren't allowed. For those you'll have to use the `{}` syntax. You
307
+ can, however, use both syntaxes together:
308
+
309
+ %a(title=@title){:href => @link.href} Stuff
310
+
311
+ You can also use `#{}` interpolation to insert complicated expressions in a
312
+ HTML-style attribute:
313
+
314
+ %span(class="widget_#{@widget.number}")
315
+
316
+ HTML-style attributes can be stretched across multiple lines just like
317
+ hash-style attributes:
318
+
319
+ %script(type="text/javascript"
320
+ src="javascripts/script_#{2 + 7}")
321
+
322
+ #### Ruby 1.9-style Hashes
323
+
324
+ Haml also supports Ruby's new hash syntax:
325
+
326
+ %a{title: @title, href: href} Stuff
327
+
328
+ #### Attribute Methods
329
+
330
+ A Ruby method call that returns a hash can be substituted for the hash contents.
331
+ For example, {Haml::Helpers} defines the following method:
332
+
333
+ def html_attrs(lang = 'en-US')
334
+ {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
335
+ end
336
+
337
+ This can then be used in Haml, like so:
338
+
339
+ %html{html_attrs('fr-fr')}
340
+
341
+ This is compiled to:
342
+
343
+ <html lang='fr-fr' xml:lang='fr-fr' xmlns='http://www.w3.org/1999/xhtml'>
344
+ </html>
345
+
346
+ You can use as many such attribute methods as you want by separating them with
347
+ commas, like a Ruby argument list. All the hashes will be merged together, from
348
+ left to right. For example, if you defined
349
+
350
+ def hash1
351
+ {:bread => 'white', :filling => 'peanut butter and jelly'}
352
+ end
353
+
354
+ def hash2
355
+ {:bread => 'whole wheat'}
356
+ end
357
+
358
+ then
359
+
360
+ %sandwich{hash1, hash2, :delicious => 'true'}/
361
+
362
+ would compile to:
363
+
364
+ <sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
365
+
366
+ Note that the Haml attributes list has the same syntax as a Ruby method call.
367
+ This means that any attribute methods must come before the hash literal.
368
+
369
+ Attribute methods aren't supported for HTML-style attributes.
370
+
371
+ #### Boolean Attributes
372
+
373
+ Some attributes, such as "checked" for `input` tags or "selected" for `option`
374
+ tags, are "boolean" in the sense that their values don't matter - it only
375
+ matters whether or not they're present. In HTML (but not XHTML), these
376
+ attributes can be written as
377
+
378
+ <input selected>
379
+
380
+ To do this in Haml using hash-style attributes, just assign a Ruby `true` value
381
+ to the attribute:
382
+
383
+ %input{:selected => true}
384
+
385
+ In XHTML, the only valid value for these attributes is the name of the
386
+ attribute. Thus this will render in XHTML as
387
+
388
+ <input selected='selected'>
389
+
390
+ To set these attributes to false, simply assign them to a Ruby false value. In
391
+ both XHTML and HTML,
392
+
393
+ %input{:selected => false}
394
+
395
+ will just render as:
396
+
397
+ <input>
398
+
399
+ HTML-style boolean attributes can be written just like HTML:
400
+
401
+ %input(selected)
402
+
403
+ or using `true` and `false`:
404
+
405
+ %input(selected=true)
406
+
407
+ <!-- The title to the next section (Prefixed Attributes) has changed. This
408
+ <a> tag is so old links to here still work. -->
409
+ <a id="html5_custom_data_attributes" style="border:0;"></a>
410
+
411
+ #### Prefixed Attributes
412
+
413
+ HTML5 allows for adding
414
+ [custom non-visible data attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data-with-the-data-*-attributes)
415
+ to elements using attribute names beginning with `data-`. The
416
+ [Accessible Rich Internet Applications](http://www.w3.org/WAI/intro/aria)
417
+ specification makes use of attributes beginning with `aria-`. There are also
418
+ frameworks that use non-standard attributes with a common prefix.
419
+
420
+ Haml can help generate collections of attributes that share a prefix like
421
+ these. Any entry in an attribute hash that has a Hash as its value is expanded
422
+ into a series of attributes, one for each key/value pair in the hash, with the
423
+ attribute name formed by joining the “parent” key name to the key name with a
424
+ hyphen.
425
+
426
+ For example:
427
+
428
+ %a{:href=>"/posts", :data => {:author_id => 123, :category => 7}} Posts By Author
429
+
430
+ will render as:
431
+
432
+ <a data-author-id='123' data-category='7' href='/posts'>Posts By Author</a>
433
+
434
+ Notice that the underscore in `author_id` was replaced by a hyphen. If you wish
435
+ to suppress this behavior, you can set Haml's
436
+ {Haml::Options#hyphenate_data_attrs `:hyphenate_data_attrs` option} to `false`,
437
+ and the output will be rendered as:
438
+
439
+ <a data-author_id='123' data-category='7' href='/posts'>Posts By Author</a>
440
+
441
+ This expansion of hashes is recursive – any value of the child hash that is
442
+ itself a hash will create an attribute for each entry, with the attribute name
443
+ prefixed with all ancestor keys. For example:
444
+
445
+ .book-info{:data => {:book => {:id => 123, :genre => 'programming'}, :category => 7}}
446
+
447
+ will render as:
448
+
449
+ <div class='book-info' data-book-genre='programming' data-book-id='123' data-category='7'></div>
450
+
451
+ ### Class and ID: `.` and `#`
452
+
453
+ The period and pound sign are borrowed from CSS. They are used as shortcuts to
454
+ specify the `class` and `id` attributes of an element, respectively. Multiple
455
+ class names can be specified in a similar way to CSS, by chaining the class
456
+ names together with periods. They are placed immediately after the tag and
457
+ before an attributes hash. For example:
458
+
459
+ %div#things
460
+ %span#rice Chicken Fried
461
+ %p.beans{ :food => 'true' } The magical fruit
462
+ %h1.class.otherclass#id La La La
463
+
464
+ is compiled to:
465
+
466
+ <div id='things'>
467
+ <span id='rice'>Chicken Fried</span>
468
+ <p class='beans' food='true'>The magical fruit</p>
469
+ <h1 class='class otherclass' id='id'>La La La</h1>
470
+ </div>
471
+
472
+ And,
473
+
474
+ %div#content
475
+ %div.articles
476
+ %div.article.title Doogie Howser Comes Out
477
+ %div.article.date 2006-11-05
478
+ %div.article.entry
479
+ Neil Patrick Harris would like to dispel any rumors that he is straight
480
+
481
+ is compiled to:
482
+
483
+ <div id='content'>
484
+ <div class='articles'>
485
+ <div class='article title'>Doogie Howser Comes Out</div>
486
+ <div class='article date'>2006-11-05</div>
487
+ <div class='article entry'>
488
+ Neil Patrick Harris would like to dispel any rumors that he is straight
489
+ </div>
490
+ </div>
491
+ </div>
492
+
493
+ These shortcuts can be combined with long-hand attributes; the two values will
494
+ be merged together as though they were all placed in an array (see [the
495
+ documentation on `:class` and `:id` attributes](#class-and-id-attributes)). For
496
+ example:
497
+
498
+ %div#Article.article.entry{:id => @article.number, :class => @article.visibility}
499
+
500
+ is equivalent to
501
+
502
+ %div{:id => ['Article', @article.number], :class => ['article', 'entry', @article.visibility]} Gabba Hey
503
+
504
+ and could compile to:
505
+
506
+ <div class="article entry visible" id="Article_27">Gabba Hey</div>
507
+
508
+ #### Implicit Div Elements
509
+
510
+ Because divs are used so often, they're the default elements. If you only define
511
+ a class and/or id using `.` or `#`, a div is automatically used. For example:
512
+
513
+ #collection
514
+ .item
515
+ .description What a cool item!
516
+
517
+ is the same as:
518
+
519
+ %div#collection
520
+ %div.item
521
+ %div.description What a cool item!
522
+
523
+ and is compiled to:
524
+
525
+ <div id='collection'>
526
+ <div class='item'>
527
+ <div class='description'>What a cool item!</div>
528
+ </div>
529
+ </div>
530
+
531
+ #### Class Name Merging and Ordering
532
+
533
+ Class names are ordered in the following way:
534
+
535
+ 1) Tag identifiers in order (aka, ".alert.me" => "alert me")
536
+ 2) Classes appearing in HTML-style attributes
537
+ 3) Classes appearing in Hash-style attributes
538
+
539
+ For instance, this is a complicated and unintuitive test case illustrating the ordering
540
+
541
+ .foo.moo{:class => ['bar', 'alpha']}(class='baz')
542
+
543
+ The resulting HTML would be as follows:
544
+
545
+ <div class='foo moo baz bar alpha'></div>
546
+
547
+ *Versions of Haml prior to 5.0 would alphabetically sort class names.*
548
+
549
+ ### Empty (void) Tags: `/`
550
+
551
+ The forward slash character, when placed at the end of a tag definition, causes
552
+ Haml to treat it as being an empty (or void) element. Depending on the format,
553
+ the tag will be rendered either without a closing tag (`:html4` or `:html5`), or
554
+ as a self-closing tag (`:xhtml`).
555
+
556
+ Taking the following as an example:
557
+
558
+ %br/
559
+ %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
560
+
561
+ When the format is `:html4` or `:html5` this is compiled to:
562
+
563
+ <br>
564
+ <meta content='text/html' http-equiv='Content-Type'>
565
+
566
+ and when the format is `:xhtml` it is compiled to:
567
+
568
+ <br />
569
+ <meta content='text/html' http-equiv='Content-Type' />
570
+
571
+ Some tags are automatically treated as being empty, as long as they have no
572
+ content in the Haml source. `meta`, `img`, `link`, `br`, `hr`, `input`,
573
+ `area`, `param`, `col` and `base` tags are treated as empty by default. This
574
+ list can be customized by setting the {Haml::Options#autoclose `:autoclose`}
575
+ option.
576
+
577
+ ### Whitespace Removal: `>` and `<`
578
+
579
+ `>` and `<` give you more control over the whitespace near a tag. `>` will
580
+ remove all whitespace surrounding a tag, while `<` will remove all whitespace
581
+ immediately within a tag. You can think of them as alligators eating the
582
+ whitespace: `>` faces out of the tag and eats the whitespace on the outside, and
583
+ `<` faces into the tag and eats the whitespace on the inside. They're placed at
584
+ the end of a tag definition, after class, id, and attribute declarations but
585
+ before `/` or `=`. For example:
586
+
587
+ %blockquote<
588
+ %div
589
+ Foo!
590
+
591
+ is compiled to:
592
+
593
+ <blockquote><div>
594
+ Foo!
595
+ </div></blockquote>
596
+
597
+ And:
598
+
599
+ %img
600
+ %img>
601
+ %img
602
+
603
+ is compiled to:
604
+
605
+ <img /><img /><img />
606
+
607
+ And:
608
+
609
+ %p<= "Foo\nBar"
610
+
611
+ is compiled to:
612
+
613
+ <p>Foo
614
+ Bar</p>
615
+
616
+ And finally:
617
+
618
+ %img
619
+ %pre><
620
+ foo
621
+ bar
622
+ %img
623
+
624
+ is compiled to:
625
+
626
+ <img /><pre>foo
627
+ bar</pre><img />
628
+
629
+ ### Object Reference: `[]`
630
+
631
+ Square brackets follow a tag definition and contain a Ruby object that is used
632
+ to set the class and id of that tag. The class is set to the object's class
633
+ (transformed to use underlines rather than camel case) and the id is set to the
634
+ object's class, followed by the value of its `#to_key` or `#id` method (in that
635
+ order). This is most useful for elements that represent instances of Active
636
+ Model models. Additionally, the second argument (if present) will be used as a
637
+ prefix for both the id and class attributes. For example:
638
+
639
+ # file: app/controllers/users_controller.rb
640
+
641
+ def show
642
+ @user = CrazyUser.find(15)
643
+ end
644
+
645
+ -# file: app/views/users/show.haml
646
+
647
+ %div[@user, :greeting]
648
+ %bar[290]/
649
+ Hello!
650
+
651
+ is compiled to:
652
+
653
+ <div class='greeting_crazy_user' id='greeting_crazy_user_15'>
654
+ <bar class='fixnum' id='fixnum_581' />
655
+ Hello!
656
+ </div>
657
+
658
+ If you require that the class be something other than the underscored object's
659
+ class, you can implement the `haml_object_ref` method on the object.
660
+
661
+ # file: app/models/crazy_user.rb
662
+
663
+ class CrazyUser < ActiveRecord::Base
664
+ def haml_object_ref
665
+ "a_crazy_user"
666
+ end
667
+ end
668
+
669
+ -# file: app/views/users/show.haml
670
+
671
+ %div[@user]
672
+ Hello!
673
+
674
+ is compiled to:
675
+
676
+ <div class='a_crazy_user' id='a_crazy_user_15'>
677
+ Hello!
678
+ </div>
679
+
680
+ The `:class` attribute may be used in conjunction with an object
681
+ reference. The compiled element will have the union of all classes.
682
+
683
+ - user = User.find(1)
684
+ %p[user]{:class => 'alpha bravo'}
685
+ <p id="user_1" class="alpha bravo user"></p>
686
+
687
+ ## Doctype: `!!!`
688
+
689
+ When describing HTML documents with Haml, you can have a document type or XML
690
+ prolog generated automatically by including the characters `!!!`. For example:
691
+
692
+ !!! XML
693
+ !!!
694
+ %html
695
+ %head
696
+ %title Myspace
697
+ %body
698
+ %h1 I am the international space station
699
+ %p Sign my guestbook
700
+
701
+ is compiled to:
702
+
703
+ <?xml version='1.0' encoding='utf-8' ?>
704
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
705
+ <html>
706
+ <head>
707
+ <title>Myspace</title>
708
+ </head>
709
+ <body>
710
+ <h1>I am the international space station</h1>
711
+ <p>Sign my guestbook</p>
712
+ </body>
713
+ </html>
714
+
715
+ You can also specify the specific doctype after the `!!!` When the
716
+ {Haml::Options#format `:format`} is set to `:xhtml`. The following doctypes are
717
+ supported:
718
+
719
+ `!!!`
720
+ : XHTML 1.0 Transitional<br/>
721
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">`
722
+
723
+ `!!! Strict`
724
+ : XHTML 1.0 Strict<br/>
725
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">`
726
+
727
+ `!!! Frameset`
728
+ : XHTML 1.0 Frameset<br/>
729
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">`
730
+
731
+ `!!! 5`
732
+ : XHTML 5<br/>
733
+ `<!DOCTYPE html>`<br/>
734
+
735
+ `!!! 1.1`
736
+ : XHTML 1.1<br/>
737
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">`
738
+
739
+ `!!! Basic`
740
+ : XHTML Basic 1.1<br/>
741
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> `
742
+
743
+ `!!! Mobile`
744
+ : XHTML Mobile 1.2<br/>
745
+ `<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">`
746
+
747
+ `!!! RDFa`
748
+ : XHTML+RDFa 1.0<br/>
749
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">`
750
+
751
+ When the {Haml::Options#format `:format`} option is set to `:html4`, the following
752
+ doctypes are supported:
753
+
754
+ `!!!`
755
+ : HTML 4.01 Transitional<br/>
756
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">`
757
+
758
+ `!!! Strict`
759
+ : HTML 4.01 Strict<br/>
760
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">`
761
+
762
+ `!!! Frameset`
763
+ : HTML 4.01 Frameset<br/>
764
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">`
765
+
766
+ When the {Haml::Options#format `:format`} option is set to `:html5`,
767
+ `!!!` is always `<!DOCTYPE html>`.
768
+
769
+ If you're not using the UTF-8 character set for your document, you can specify
770
+ which encoding should appear in the XML prolog in a similar way. For example:
771
+
772
+ !!! XML iso-8859-1
773
+
774
+ is compiled to:
775
+
776
+ <?xml version='1.0' encoding='iso-8859-1' ?>
777
+
778
+ If the mime_type of the template being rendered is `text/xml` then a format of
779
+ `:xhtml` will be used even if the global output format is set to `:html4` or
780
+ `:html5`.
781
+
782
+ ## Comments
783
+
784
+ Haml supports two sorts of comments: those that show up in the HTML output and
785
+ those that don't.
786
+
787
+ ### HTML Comments: `/`
788
+
789
+ The forward slash character, when placed at the beginning of a line, wraps all
790
+ text after it in an HTML comment. For example:
791
+
792
+ %peanutbutterjelly
793
+ / This is the peanutbutterjelly element
794
+ I like sandwiches!
795
+
796
+ is compiled to:
797
+
798
+ <peanutbutterjelly>
799
+ <!-- This is the peanutbutterjelly element -->
800
+ I like sandwiches!
801
+ </peanutbutterjelly>
802
+
803
+ The forward slash can also wrap indented sections of code. For example:
804
+
805
+ /
806
+ %p This doesn't render...
807
+ %div
808
+ %h1 Because it's commented out!
809
+
810
+ is compiled to:
811
+
812
+ <!--
813
+ <p>This doesn't render...</p>
814
+ <div>
815
+ <h1>Because it's commented out!</h1>
816
+ </div>
817
+ -->
818
+
819
+ #### Conditional Comments: `/[]`
820
+
821
+ You can also use [Internet Explorer conditional
822
+ comments](http://www.quirksmode.org/css/condcom.html) by enclosing the condition
823
+ in square brackets after the `/`. For example:
824
+
825
+ /[if IE]
826
+ %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
827
+ %h1 Get Firefox
828
+
829
+ is compiled to:
830
+
831
+ <!--[if IE]>
832
+ <a href='http://www.mozilla.com/en-US/firefox/'>
833
+ <h1>Get Firefox</h1>
834
+ </a>
835
+ <![endif]-->
836
+
837
+ To generate “downlevel-revealed” conditional comments, where the content is
838
+ hidden from IE but not other browsers, add a `!` before the brackets: `/![]`.
839
+ Haml will produce valid HTML when generating this kind of conditional comment.
840
+
841
+ For example:
842
+
843
+ /![if !IE]
844
+ You are not using Internet Explorer, or are using version 10+.
845
+
846
+ is compiled to:
847
+
848
+ <!--[if !IE]><!-->
849
+ You are not using Internet Explorer, or are using version 10+.
850
+ <!--<![endif]-->
851
+
852
+ ### Haml Comments: `-#`
853
+
854
+ The hyphen followed immediately by the pound sign signifies a silent comment.
855
+ Any text following this isn't rendered in the resulting document at all.
856
+
857
+ For example:
858
+
859
+ %p foo
860
+ -# This is a comment
861
+ %p bar
862
+
863
+ is compiled to:
864
+
865
+ <p>foo</p>
866
+ <p>bar</p>
867
+
868
+ You can also nest text beneath a silent comment. None of this text will be
869
+ rendered. For example:
870
+
871
+ %p foo
872
+ -#
873
+ This won't be displayed
874
+ Nor will this
875
+ Nor will this.
876
+ %p bar
877
+
878
+ is compiled to:
879
+
880
+ <p>foo</p>
881
+ <p>bar</p>
882
+
883
+ ## Ruby Evaluation
884
+
885
+ ### Inserting Ruby: `=` {#inserting_ruby}
886
+
887
+ The equals character is followed by Ruby code. This code is evaluated and the
888
+ output is inserted into the document. For example:
889
+
890
+ %p
891
+ = ['hi', 'there', 'reader!'].join " "
892
+ = "yo"
893
+
894
+ is compiled to:
895
+
896
+ <p>
897
+ hi there reader!
898
+ yo
899
+ </p>
900
+
901
+ If the {Haml::Options#escape_html `:escape_html`} option is set, `=` will sanitize
902
+ any HTML-sensitive characters generated by the script. For example:
903
+
904
+ = '<script>alert("I\'m evil!");</script>'
905
+
906
+ would be compiled to
907
+
908
+ &lt;script&gt;alert(&quot;I'm evil!&quot;);&lt;/script&gt;
909
+
910
+ `=` can also be used at the end of a tag to insert Ruby code within that tag.
911
+ For example:
912
+
913
+ %p= "hello"
914
+
915
+ would be compiled to:
916
+
917
+ <p>hello</p>
918
+
919
+ A line of Ruby code can be stretched over multiple lines as long as each line
920
+ but the last ends with a comma. For example:
921
+
922
+ = link_to_remote "Add to cart",
923
+ :url => { :action => "add", :id => product.id },
924
+ :update => { :success => "cart", :failure => "error" }
925
+
926
+ Note that it's illegal to nest code within a tag that ends with `=`.
927
+
928
+ ### Running Ruby: `-`
929
+
930
+ The hyphen character is also followed by Ruby code. This code is evaluated but
931
+ *not* inserted into the document.
932
+
933
+ **It is not recommended that you use this widely; almost all processing code and
934
+ logic should be restricted to Controllers, Helpers, or partials.**
935
+
936
+ For example:
937
+
938
+ - foo = "hello"
939
+ - foo << " there"
940
+ - foo << " you!"
941
+ %p= foo
942
+
943
+ is compiled to:
944
+
945
+ <p>
946
+ hello there you!
947
+ </p>
948
+
949
+ A line of Ruby code can be stretched over multiple lines as long as each line
950
+ but the last ends with a comma. For example:
951
+
952
+ - links = {:home => "/",
953
+ :docs => "/docs",
954
+ :about => "/about"}
955
+
956
+ #### Ruby Blocks
957
+
958
+ Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
959
+ Rather, they're automatically closed, based on indentation. A block begins
960
+ whenever the indentation is increased after a Ruby evaluation command. It ends
961
+ when the indentation decreases (as long as it's not an `else` clause or
962
+ something similar). For example:
963
+
964
+ - (42...47).each do |i|
965
+ %p= i
966
+ %p See, I can count!
967
+
968
+ is compiled to:
969
+
970
+ <p>42</p>
971
+ <p>43</p>
972
+ <p>44</p>
973
+ <p>45</p>
974
+ <p>46</p>
975
+ <p>See, I can count!</p>
976
+
977
+ Another example:
978
+
979
+ %p
980
+ - case 2
981
+ - when 1
982
+ = "1!"
983
+ - when 2
984
+ = "2?"
985
+ - when 3
986
+ = "3."
987
+
988
+ is compiled to:
989
+
990
+ <p>
991
+ 2?
992
+ </p>
993
+
994
+ ### Whitespace Preservation: `~` {#tilde}
995
+
996
+ `~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve}
997
+ on its input. For example,
998
+
999
+ ~ "Foo\n<pre>Bar\nBaz</pre>"
1000
+
1001
+ is the same as:
1002
+
1003
+ = find_and_preserve("Foo\n<pre>Bar\nBaz</pre>")
1004
+
1005
+ and is compiled to:
1006
+
1007
+ Foo
1008
+ <pre>Bar&#x000A;Baz</pre>
1009
+
1010
+ See also [Whitespace Preservation](#whitespace_preservation).
1011
+
1012
+ ### Ruby Interpolation: `#{}`
1013
+
1014
+ Ruby code can also be interpolated within plain text using `#{}`, similarly to
1015
+ Ruby string interpolation. For example,
1016
+
1017
+ %p This is #{h quality} cake!
1018
+
1019
+ is the same as
1020
+
1021
+ %p= "This is #{h quality} cake!"
1022
+
1023
+ and might compile to:
1024
+
1025
+ <p>This is scrumptious cake!</p>
1026
+
1027
+ Backslashes can be used to escape `#{}` strings, but they don't act as escapes
1028
+ anywhere else in the string. For example:
1029
+
1030
+ %p
1031
+ Look at \\#{h word} lack of backslash: \#{foo}
1032
+ And yon presence thereof: \{foo}
1033
+
1034
+ might compile to:
1035
+
1036
+ <p>
1037
+ Look at \yon lack of backslash: #{foo}
1038
+ And yon presence thereof: \{foo}
1039
+ </p>
1040
+
1041
+ Interpolation can also be used within [filters](#filters). For example:
1042
+
1043
+ :javascript
1044
+ $(document).ready(function() {
1045
+ alert(#{@message.to_json});
1046
+ });
1047
+
1048
+ might compile to:
1049
+
1050
+ <script type='text/javascript'>
1051
+ //<![CDATA[
1052
+ $(document).ready(function() {
1053
+ alert("Hi there!");
1054
+ });
1055
+ //]]>
1056
+ </script>
1057
+
1058
+ #### Gotchas
1059
+
1060
+ Haml uses an overly simplistic regular expression to identify string
1061
+ interpolation rather than a full-blown Ruby parser. This is fast and works for
1062
+ most code but you may have errors with code like the following:
1063
+
1064
+ %span #{'{'}
1065
+
1066
+ This code will generate a syntax error, complaining about unbalanced brackets.
1067
+ In cases like this, the recommended workaround is output the code as a Ruby
1068
+ string to force Haml to parse the code with Ruby.
1069
+
1070
+ %span= "#{'{'}"
1071
+
1072
+
1073
+ ### Escaping HTML: `&=` {#escaping_html}
1074
+
1075
+ An ampersand followed by one or two equals characters evaluates Ruby code just
1076
+ like the equals without the ampersand, but sanitizes any HTML-sensitive
1077
+ characters in the result of the code. For example:
1078
+
1079
+ &= "I like cheese & crackers"
1080
+
1081
+ compiles to
1082
+
1083
+ I like cheese &amp; crackers
1084
+
1085
+ If the {Haml::Options#escape_html `:escape_html`} option is set, `&=` behaves
1086
+ identically to `=`.
1087
+
1088
+ `&` can also be used on its own so that `#{}` interpolation is escaped. For
1089
+ example,
1090
+
1091
+ & I like #{"cheese & crackers"}
1092
+
1093
+ compiles to:
1094
+
1095
+ I like cheese &amp; crackers
1096
+
1097
+ ### Unescaping HTML: `!=` {#unescaping_html}
1098
+
1099
+ An exclamation mark followed by one or two equals characters evaluates Ruby code
1100
+ just like the equals would, but never sanitizes the HTML.
1101
+
1102
+ By default, the single equals doesn't sanitize HTML either. However, if the
1103
+ {Haml::Options#escape_html `:escape_html`} option is set, `=` will sanitize the
1104
+ HTML, but `!=` still won't. For example, if `:escape_html` is set:
1105
+
1106
+ = "I feel <strong>!"
1107
+ != "I feel <strong>!"
1108
+
1109
+ compiles to
1110
+
1111
+ I feel &lt;strong&gt;!
1112
+ I feel <strong>!
1113
+
1114
+ `!` can also be used on its own so that `#{}` interpolation is unescaped.
1115
+ For example,
1116
+
1117
+ ! I feel #{"<strong>"}!
1118
+
1119
+ compiles to
1120
+
1121
+ I feel <strong>!
1122
+
1123
+ ## Filters {#filters}
1124
+
1125
+ The colon character designates a filter. This allows you to pass an indented
1126
+ block of text as input to another filtering program and add the result to the
1127
+ output of Haml. The syntax is simply a colon followed by the name of the filter.
1128
+ For example:
1129
+
1130
+ %p
1131
+ :markdown
1132
+ # Greetings
1133
+
1134
+ Hello, *World*
1135
+
1136
+ is compiled to:
1137
+
1138
+ <p>
1139
+ <h1>Greetings</h1>
1140
+
1141
+ <p>Hello, <em>World</em></p>
1142
+ </p>
1143
+
1144
+ Filters can have Ruby code interpolated with `#{}`. For example:
1145
+
1146
+ - flavor = "raspberry"
1147
+ #content
1148
+ :textile
1149
+ I *really* prefer _#{flavor}_ jam.
1150
+
1151
+ is compiled to
1152
+
1153
+ <div id='content'>
1154
+ <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
1155
+ </div>
1156
+
1157
+ Note that `#{}` interpolation within filters is HTML-escaped if you specify true to
1158
+ {Haml::Options#escape_filter_interpolations `:escape_filter_interpolations`} option.
1159
+
1160
+ The functionality of some filters such as Markdown can be provided by many
1161
+ different libraries. Usually you don't have to worry about this - you can just
1162
+ load the gem of your choice and Haml will automatically use it.
1163
+
1164
+ However in some cases you may want to make Haml explicitly use a specific gem to
1165
+ be used by a filter. In these cases you can do this via Tilt, the library Haml
1166
+ uses to implement many of its filters:
1167
+
1168
+ Tilt.prefer Tilt::RedCarpetTemplate
1169
+
1170
+ See the [Tilt documentation](https://github.com/rtomayko/tilt#fallback-mode) for
1171
+ more info.
1172
+
1173
+ Haml comes with the following filters defined:
1174
+
1175
+ ### `:cdata` {#cdata-filter}
1176
+
1177
+ Surrounds the filtered text with CDATA tags.
1178
+
1179
+ ### `:coffee` {#coffee-filter}
1180
+
1181
+ Compiles the filtered text to JavaScript in `<script>` tag using CoffeeScript.
1182
+ You can also reference this filter as `:coffeescript`. This filter is
1183
+ implemented using Tilt.
1184
+
1185
+ ### `:css` {#css-filter}
1186
+
1187
+ Surrounds the filtered text with `<style>` and (optionally) CDATA tags. Useful
1188
+ for including inline CSS. Use the {Haml::Options#cdata `:cdata` option} to
1189
+ control when CDATA tags are added.
1190
+
1191
+ ### `:erb` {#erb-filter}
1192
+
1193
+ Parses the filtered text with ERB, like an RHTML template. Not available if the
1194
+ {Haml::Options#suppress_eval `:suppress_eval`} option is set to true. Embedded
1195
+ Ruby code is evaluated in the same context as the Haml template. This filter is
1196
+ implemented using Tilt.
1197
+
1198
+ ### `:escaped` {#escaped-filter}
1199
+
1200
+ Works the same as plain, but HTML-escapes the text
1201
+ before placing it in the document.
1202
+
1203
+ ### `:javascript` {#javascript-filter}
1204
+
1205
+ Surrounds the filtered text with `<script>` and (optionally) CDATA tags.
1206
+ Useful for including inline Javascript. Use the {Haml::Options#cdata `:cdata`
1207
+ option} to control when CDATA tags are added.
1208
+
1209
+ ### `:less` {#less-filter}
1210
+
1211
+ Parses the filtered text with [Less](http://lesscss.org/) to produce CSS output in `<style>` tag.
1212
+ This filter is implemented using Tilt.
1213
+
1214
+ ### `:markdown` {#markdown-filter}
1215
+
1216
+ Parses the filtered text with
1217
+ [Markdown](http://daringfireball.net/projects/markdown). This filter is
1218
+ implemented using Tilt.
1219
+
1220
+ ### `:maruku` {#maruku-filter}
1221
+
1222
+ Parses the filtered text with [Maruku](https://github.com/nex3/maruku), which
1223
+ has some non-standard extensions to Markdown.
1224
+
1225
+ As of Haml 4.0, this filter is defined in [Haml
1226
+ contrib](https://github.com/haml/haml-contrib) but is loaded automatically for
1227
+ historical reasons. In future versions of Haml it will likely not be loaded by
1228
+ default. This filter is implemented using Tilt.
1229
+
1230
+ ### `:plain` {#plain-filter}
1231
+
1232
+ Does not parse the filtered text. This is useful for large blocks of text
1233
+ without HTML tags, when you don't want lines starting with `.` or `-` to be
1234
+ parsed.
1235
+
1236
+ ### `:preserve` {#preserve-filter}
1237
+
1238
+ Inserts the filtered text into the template with whitespace preserved.
1239
+ `preserve`d blocks of text aren't indented, and newlines are replaced with the
1240
+ HTML escape code for newlines, to preserve nice-looking output. See also
1241
+ [Whitespace Preservation](#whitespace_preservation).
1242
+
1243
+ ### `:ruby` {#ruby-filter}
1244
+
1245
+ Parses the filtered text with the normal Ruby interpreter. Creates an `IO`
1246
+ object named `haml_io`, anything written to it is output into the Haml document.
1247
+ Not available if the {Haml::Options#suppress_eval `:suppress_eval`} option is
1248
+ set to true. The Ruby code is evaluated in the same context as the Haml
1249
+ template.
1250
+
1251
+ ### `:sass` {#sass-filter}
1252
+
1253
+ Parses the filtered text with [Sass](http://sass-lang.com/) to produce CSS
1254
+ output in `<style>` tag. This filter is implemented using Tilt.
1255
+
1256
+ ### `:scss` {#scss-filter}
1257
+
1258
+ Parses the filtered text with Sass like the `:sass` filter, but uses the newer
1259
+ SCSS syntax to produce CSS output in `<style>` tag. This filter is implemented
1260
+ using Tilt.
1261
+
1262
+ ### `:textile` {#textile-filter}
1263
+
1264
+ Parses the filtered text with [Textile](http://www.textism.com/tools/textile).
1265
+ Only works if [RedCloth](http://redcloth.org) is installed.
1266
+
1267
+ As of Haml 4.0, this filter is defined in [Haml
1268
+ contrib](https://github.com/haml/haml-contrib) but is loaded automatically for
1269
+ historical reasons. In future versions of Haml it will likely not be loaded by
1270
+ default. This filter is implemented using Tilt.
1271
+
1272
+ ### Custom Filters
1273
+
1274
+ You can also define your own filters. See {Haml::Filters} for details.
1275
+
1276
+ ## Helper Methods {#helper-methods}
1277
+
1278
+ Sometimes you need to manipulate whitespace in a more precise fashion than what
1279
+ the whitespace removal methods allow. There are a few helper methods that are
1280
+ useful when dealing with inline content. All these methods take a Haml block to
1281
+ modify.
1282
+
1283
+ ### surround {#surround}
1284
+
1285
+ Surrounds a Haml block with text. Expects 1 or 2 string arguments used to
1286
+ surround the Haml block. If a second argument is not provided, the first
1287
+ argument is used as the second.
1288
+
1289
+ = surround "(", ")" do
1290
+ = link_to "learn more", "#"
1291
+
1292
+ ### precede {#precede}
1293
+
1294
+ Prepends a Haml block with text. Expects 1 argument.
1295
+
1296
+ = precede "*" do
1297
+ %span Required
1298
+
1299
+ ### succeed {#succeed}
1300
+
1301
+ Appends a Haml block with text. Expects 1 argument.
1302
+
1303
+ Begin by
1304
+ = succeed "," do
1305
+ = link_to "filling out your profile", "#"
1306
+ = succeed "," do
1307
+ = link_to "adding a bio", "#"
1308
+ and
1309
+ = succeed "." do
1310
+ = link_to "inviting friends", "#"
1311
+
1312
+ ## Multiline: `|` {#multiline}
1313
+
1314
+ The pipe character designates a multiline string.
1315
+ It's placed at the end of a line (after some whitespace)
1316
+ and means that all following lines that end with `|`
1317
+ will be evaluated as though they were on the same line.
1318
+ **Note that even the last line in the multiline block
1319
+ should end with `|`.**
1320
+ For example:
1321
+
1322
+ %whoo
1323
+ %hoo= h( |
1324
+ "I think this might get " + |
1325
+ "pretty long so I should " + |
1326
+ "probably make it " + |
1327
+ "multiline so it doesn't " + |
1328
+ "look awful.") |
1329
+ %p This is short.
1330
+
1331
+ is compiled to:
1332
+
1333
+ <whoo>
1334
+ <hoo>I think this might get pretty long so I should probably make it multiline so it doesn't look awful.</hoo>
1335
+ <p>This is short</p>
1336
+ </whoo>
1337
+
1338
+ Using multiline declarations in Haml is intentionally awkward.
1339
+ This is designed to discourage people from putting lots and lots of Ruby code
1340
+ in their Haml templates.
1341
+ If you find yourself using multiline declarations, stop and think:
1342
+ could I do this better with a helper?
1343
+
1344
+ Note that there are a few cases where it's useful to allow
1345
+ something to flow over onto multiple lines in a non-awkward manner.
1346
+ One of these is HTML attributes.
1347
+ Some elements just have lots of attributes,
1348
+ so you can wrap attributes without using `|` (see [Attributes](#attributes)).
1349
+
1350
+ In addition, sometimes you need to call Ruby methods or declare data structures
1351
+ that just need a lot of template information.
1352
+ So data structures and functions that require lots of arguments
1353
+ can be wrapped over multiple lines,
1354
+ as long as each line but the last ends in a comma
1355
+ (see [Inserting Ruby](#inserting_ruby)).
1356
+
1357
+ ## Whitespace Preservation
1358
+
1359
+ Sometimes you don't want Haml to indent all your text.
1360
+ For example, tags like `pre` and `textarea` are whitespace-sensitive;
1361
+ indenting the text makes them render wrong.
1362
+
1363
+ Haml deals with this by "preserving" newlines before they're put into the
1364
+ document -- converting them to the HTML whitespace escape code, `&#x000A;`. Then
1365
+ Haml won't try to re-format the indentation.
1366
+
1367
+ Literal `textarea` and `pre` tags automatically preserve content given through
1368
+ `=`. Dynamically-generated `textarea`s and `pre`s can't be preserved
1369
+ automatically, and so should be passed through
1370
+ {Haml::Helpers#find\_and\_preserve} or the [`~` command](#tilde), which has the
1371
+ same effect.
1372
+
1373
+ Blocks of literal text can be preserved using the [`:preserve` filter](#preserve-filter).
1374
+
1375
+ ## Helpers
1376
+
1377
+ Haml offers a bunch of helpers that are useful for doing stuff like preserving
1378
+ whitespace, creating nicely indented output for user-defined helpers, and other
1379
+ useful things. The helpers are all documented in the {Haml::Helpers} and
1380
+ {Haml::Helpers::ActionViewExtensions} modules.