jwhitmire-haml 2.1.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (168) hide show
  1. data/README.rdoc +332 -0
  2. data/bin/css2sass +7 -0
  3. data/bin/haml +9 -0
  4. data/bin/html2haml +7 -0
  5. data/bin/sass +8 -0
  6. data/lib/haml/buffer.rb +255 -0
  7. data/lib/haml/engine.rb +268 -0
  8. data/lib/haml/error.rb +22 -0
  9. data/lib/haml/exec.rb +395 -0
  10. data/lib/haml/filters.rb +276 -0
  11. data/lib/haml/helpers/action_view_extensions.rb +45 -0
  12. data/lib/haml/helpers/action_view_mods.rb +181 -0
  13. data/lib/haml/helpers.rb +468 -0
  14. data/lib/haml/html.rb +218 -0
  15. data/lib/haml/precompiler.rb +889 -0
  16. data/lib/haml/shared.rb +45 -0
  17. data/lib/haml/template/patch.rb +58 -0
  18. data/lib/haml/template/plugin.rb +72 -0
  19. data/lib/haml/template.rb +51 -0
  20. data/lib/haml/util.rb +77 -0
  21. data/lib/haml/version.rb +47 -0
  22. data/lib/haml.rb +1042 -0
  23. data/lib/sass/css.rb +388 -0
  24. data/lib/sass/engine.rb +499 -0
  25. data/lib/sass/environment.rb +33 -0
  26. data/lib/sass/error.rb +35 -0
  27. data/lib/sass/plugin/merb.rb +56 -0
  28. data/lib/sass/plugin/rails.rb +24 -0
  29. data/lib/sass/plugin.rb +203 -0
  30. data/lib/sass/repl.rb +51 -0
  31. data/lib/sass/script/bool.rb +13 -0
  32. data/lib/sass/script/color.rb +97 -0
  33. data/lib/sass/script/funcall.rb +28 -0
  34. data/lib/sass/script/functions.rb +122 -0
  35. data/lib/sass/script/lexer.rb +152 -0
  36. data/lib/sass/script/literal.rb +60 -0
  37. data/lib/sass/script/number.rb +231 -0
  38. data/lib/sass/script/operation.rb +30 -0
  39. data/lib/sass/script/parser.rb +142 -0
  40. data/lib/sass/script/string.rb +42 -0
  41. data/lib/sass/script/unary_operation.rb +21 -0
  42. data/lib/sass/script/variable.rb +20 -0
  43. data/lib/sass/script.rb +38 -0
  44. data/lib/sass/tree/attr_node.rb +64 -0
  45. data/lib/sass/tree/comment_node.rb +34 -0
  46. data/lib/sass/tree/debug_node.rb +22 -0
  47. data/lib/sass/tree/directive_node.rb +50 -0
  48. data/lib/sass/tree/file_node.rb +27 -0
  49. data/lib/sass/tree/for_node.rb +29 -0
  50. data/lib/sass/tree/if_node.rb +27 -0
  51. data/lib/sass/tree/mixin_def_node.rb +18 -0
  52. data/lib/sass/tree/mixin_node.rb +34 -0
  53. data/lib/sass/tree/node.rb +99 -0
  54. data/lib/sass/tree/rule_node.rb +120 -0
  55. data/lib/sass/tree/variable_node.rb +24 -0
  56. data/lib/sass/tree/while_node.rb +20 -0
  57. data/lib/sass.rb +1062 -0
  58. data/test/benchmark.rb +99 -0
  59. data/test/haml/engine_test.rb +734 -0
  60. data/test/haml/helper_test.rb +224 -0
  61. data/test/haml/html2haml_test.rb +92 -0
  62. data/test/haml/markaby/standard.mab +52 -0
  63. data/test/haml/mocks/article.rb +6 -0
  64. data/test/haml/results/content_for_layout.xhtml +15 -0
  65. data/test/haml/results/eval_suppressed.xhtml +9 -0
  66. data/test/haml/results/filters.xhtml +62 -0
  67. data/test/haml/results/helpers.xhtml +93 -0
  68. data/test/haml/results/helpful.xhtml +10 -0
  69. data/test/haml/results/just_stuff.xhtml +68 -0
  70. data/test/haml/results/list.xhtml +12 -0
  71. data/test/haml/results/nuke_inner_whitespace.xhtml +40 -0
  72. data/test/haml/results/nuke_outer_whitespace.xhtml +148 -0
  73. data/test/haml/results/original_engine.xhtml +20 -0
  74. data/test/haml/results/partial_layout.xhtml +5 -0
  75. data/test/haml/results/partials.xhtml +21 -0
  76. data/test/haml/results/render_layout.xhtml +3 -0
  77. data/test/haml/results/silent_script.xhtml +74 -0
  78. data/test/haml/results/standard.xhtml +42 -0
  79. data/test/haml/results/tag_parsing.xhtml +23 -0
  80. data/test/haml/results/very_basic.xhtml +5 -0
  81. data/test/haml/results/whitespace_handling.xhtml +89 -0
  82. data/test/haml/rhtml/_av_partial_1.rhtml +12 -0
  83. data/test/haml/rhtml/_av_partial_2.rhtml +8 -0
  84. data/test/haml/rhtml/action_view.rhtml +62 -0
  85. data/test/haml/rhtml/standard.rhtml +54 -0
  86. data/test/haml/template_test.rb +204 -0
  87. data/test/haml/templates/_av_partial_1.haml +9 -0
  88. data/test/haml/templates/_av_partial_1_ugly.haml +9 -0
  89. data/test/haml/templates/_av_partial_2.haml +5 -0
  90. data/test/haml/templates/_av_partial_2_ugly.haml +5 -0
  91. data/test/haml/templates/_layout.erb +3 -0
  92. data/test/haml/templates/_layout_for_partial.haml +3 -0
  93. data/test/haml/templates/_partial.haml +8 -0
  94. data/test/haml/templates/_text_area.haml +3 -0
  95. data/test/haml/templates/action_view.haml +47 -0
  96. data/test/haml/templates/action_view_ugly.haml +47 -0
  97. data/test/haml/templates/breakage.haml +8 -0
  98. data/test/haml/templates/content_for_layout.haml +10 -0
  99. data/test/haml/templates/eval_suppressed.haml +11 -0
  100. data/test/haml/templates/filters.haml +66 -0
  101. data/test/haml/templates/helpers.haml +95 -0
  102. data/test/haml/templates/helpful.haml +11 -0
  103. data/test/haml/templates/just_stuff.haml +83 -0
  104. data/test/haml/templates/list.haml +12 -0
  105. data/test/haml/templates/nuke_inner_whitespace.haml +32 -0
  106. data/test/haml/templates/nuke_outer_whitespace.haml +144 -0
  107. data/test/haml/templates/original_engine.haml +17 -0
  108. data/test/haml/templates/partial_layout.haml +3 -0
  109. data/test/haml/templates/partialize.haml +1 -0
  110. data/test/haml/templates/partials.haml +12 -0
  111. data/test/haml/templates/render_layout.haml +2 -0
  112. data/test/haml/templates/silent_script.haml +40 -0
  113. data/test/haml/templates/standard.haml +42 -0
  114. data/test/haml/templates/standard_ugly.haml +1 -0
  115. data/test/haml/templates/tag_parsing.haml +21 -0
  116. data/test/haml/templates/very_basic.haml +4 -0
  117. data/test/haml/templates/whitespace_handling.haml +87 -0
  118. data/test/linked_rails.rb +12 -0
  119. data/test/sass/css2sass_test.rb +193 -0
  120. data/test/sass/engine_test.rb +786 -0
  121. data/test/sass/functions_test.rb +96 -0
  122. data/test/sass/more_results/more1.css +9 -0
  123. data/test/sass/more_results/more1_with_line_comments.css +26 -0
  124. data/test/sass/more_results/more_import.css +29 -0
  125. data/test/sass/more_templates/_more_partial.sass +2 -0
  126. data/test/sass/more_templates/more1.sass +23 -0
  127. data/test/sass/more_templates/more_import.sass +11 -0
  128. data/test/sass/plugin_test.rb +208 -0
  129. data/test/sass/results/alt.css +4 -0
  130. data/test/sass/results/basic.css +9 -0
  131. data/test/sass/results/compact.css +5 -0
  132. data/test/sass/results/complex.css +87 -0
  133. data/test/sass/results/compressed.css +1 -0
  134. data/test/sass/results/expanded.css +19 -0
  135. data/test/sass/results/import.css +29 -0
  136. data/test/sass/results/line_numbers.css +49 -0
  137. data/test/sass/results/mixins.css +95 -0
  138. data/test/sass/results/multiline.css +24 -0
  139. data/test/sass/results/nested.css +22 -0
  140. data/test/sass/results/parent_ref.css +13 -0
  141. data/test/sass/results/script.css +16 -0
  142. data/test/sass/results/subdir/nested_subdir/nested_subdir.css +1 -0
  143. data/test/sass/results/subdir/subdir.css +3 -0
  144. data/test/sass/results/units.css +11 -0
  145. data/test/sass/script_test.rb +153 -0
  146. data/test/sass/templates/_partial.sass +2 -0
  147. data/test/sass/templates/alt.sass +16 -0
  148. data/test/sass/templates/basic.sass +23 -0
  149. data/test/sass/templates/bork.sass +2 -0
  150. data/test/sass/templates/bork2.sass +2 -0
  151. data/test/sass/templates/compact.sass +17 -0
  152. data/test/sass/templates/complex.sass +309 -0
  153. data/test/sass/templates/compressed.sass +15 -0
  154. data/test/sass/templates/expanded.sass +17 -0
  155. data/test/sass/templates/import.sass +11 -0
  156. data/test/sass/templates/importee.sass +19 -0
  157. data/test/sass/templates/line_numbers.sass +13 -0
  158. data/test/sass/templates/mixins.sass +76 -0
  159. data/test/sass/templates/multiline.sass +20 -0
  160. data/test/sass/templates/nested.sass +25 -0
  161. data/test/sass/templates/parent_ref.sass +25 -0
  162. data/test/sass/templates/script.sass +101 -0
  163. data/test/sass/templates/subdir/nested_subdir/_nested_partial.sass +2 -0
  164. data/test/sass/templates/subdir/nested_subdir/nested_subdir.sass +3 -0
  165. data/test/sass/templates/subdir/subdir.sass +6 -0
  166. data/test/sass/templates/units.sass +11 -0
  167. data/test/test_helper.rb +21 -0
  168. metadata +245 -0
data/lib/haml.rb ADDED
@@ -0,0 +1,1042 @@
1
+ dir = File.dirname(__FILE__)
2
+ $LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
3
+
4
+ require 'haml/version'
5
+
6
+ # = Haml (XHTML Abstraction Markup Language)
7
+ #
8
+ # Haml is a markup language
9
+ # that's used to cleanly and simply describe the XHTML of any web document,
10
+ # without the use of inline code.
11
+ # Haml functions as a replacement
12
+ # for inline page templating systems such as PHP, ERB, and ASP.
13
+ # However, Haml avoids the need for explicitly coding XHTML into the template,
14
+ # because it is actually an abstract description of the XHTML,
15
+ # with some code to generate dynamic content.
16
+ #
17
+ # == Features
18
+ #
19
+ # * Whitespace active
20
+ # * Well-formatted markup
21
+ # * DRY
22
+ # * Follows CSS conventions
23
+ # * Integrates Ruby code
24
+ # * Implements Rails templates with the .haml extension
25
+ #
26
+ # == Using Haml
27
+ #
28
+ # Haml can be used in three ways:
29
+ # as a plugin for Ruby on Rails,
30
+ # as a standalone Ruby module,
31
+ # and as a command-line tool.
32
+ # The first step for all of these is to install the Haml gem:
33
+ #
34
+ # gem install haml
35
+ #
36
+ # To enable it as a Rails plugin,
37
+ # then run
38
+ #
39
+ # haml --rails path/to/rails/app
40
+ #
41
+ # Once it's installed, all view files with the ".html.haml" extension
42
+ # will be compiled using Haml.
43
+ #
44
+ # To run Haml from the command line, just use
45
+ #
46
+ # haml input.haml output.html
47
+ #
48
+ # Use <tt>haml --help</tt> for full documentation.
49
+ #
50
+ # You can access instance variables in Haml templates
51
+ # the same way you do in ERb templates.
52
+ # Helper methods are also available in Haml templates.
53
+ # For example (this example uses Rails, but the principle for Merb is the same):
54
+ #
55
+ # # file: app/controllers/movies_controller.rb
56
+ #
57
+ # class MoviesController < ApplicationController
58
+ # def index
59
+ # @title = "Teen Wolf"
60
+ # end
61
+ # end
62
+ #
63
+ # -# file: app/views/movies/index.haml
64
+ #
65
+ # #content
66
+ # .title
67
+ # %h1= @title
68
+ # = link_to 'Home', home_url
69
+ #
70
+ # may be compiled to:
71
+ #
72
+ # <div id='content'>
73
+ # <div class='title'>
74
+ # <h1>Teen Wolf</h1>
75
+ # <a href='/'>Home</a>
76
+ # </div>
77
+ # </div>
78
+ #
79
+ # === Ruby Module
80
+ #
81
+ # Haml can also be used completely separately from Rails and ActionView.
82
+ # To do this, install the gem with RubyGems:
83
+ #
84
+ # gem install haml
85
+ #
86
+ # You can then use it by including the "haml" gem in Ruby code,
87
+ # and using Haml::Engine like so:
88
+ #
89
+ # engine = Haml::Engine.new("%p Haml code!")
90
+ # engine.render #=> "<p>Haml code!</p>\n"
91
+ #
92
+ # == Characters with meaning to Haml
93
+ #
94
+ # Various characters, when placed at a certain point in a line,
95
+ # instruct Haml to render different types of things.
96
+ #
97
+ # === XHTML Tags
98
+ #
99
+ # These characters render XHTML tags.
100
+ #
101
+ # ==== %
102
+ #
103
+ # The percent character is placed at the beginning of a line.
104
+ # It's followed immediately by the name of an element,
105
+ # then optionally by modifiers (see below), a space,
106
+ # and text to be rendered inside the element.
107
+ # It creates an element in the form of <tt><element></element></tt>.
108
+ # For example:
109
+ #
110
+ # %one
111
+ # %two
112
+ # %three Hey there
113
+ #
114
+ # is compiled to:
115
+ #
116
+ # <one>
117
+ # <two>
118
+ # <three>Hey there</three>
119
+ # </two>
120
+ # </one>
121
+ #
122
+ # Any string is a valid element name;
123
+ # Haml will automatically generate opening and closing tags for any element.
124
+ #
125
+ # ==== {}
126
+ #
127
+ # Brackets represent a Ruby hash
128
+ # that is used for specifying the attributes of an element.
129
+ # It is literally evaluated as a Ruby hash,
130
+ # so logic will work in it and local variables may be used.
131
+ # Quote characters within the attribute
132
+ # will be replaced by appropriate escape sequences.
133
+ # The hash is placed after the tag is defined.
134
+ # For example:
135
+ #
136
+ # %html{:xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en"}
137
+ #
138
+ # is compiled to:
139
+ #
140
+ # <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'></html>
141
+ #
142
+ # Attribute hashes can also be stretched out over multiple lines
143
+ # to accomidate many attributes.
144
+ # However, newlines may only be placed immediately after commas.
145
+ # For example:
146
+ #
147
+ # %script{:type => "text/javascript",
148
+ # :src => "javascripts/script_#{2 + 7}"}
149
+ #
150
+ # is compiled to:
151
+ #
152
+ # <script src='javascripts/script_9' type='text/javascript'></script>
153
+ #
154
+ # ===== Attribute Methods
155
+ #
156
+ # A Ruby method call that returns a hash
157
+ # can be substituted for the hash contents.
158
+ # For example, Haml::Helpers defines the following method:
159
+ #
160
+ # def html_attrs(lang = 'en-US')
161
+ # {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
162
+ # end
163
+ #
164
+ # This can then be used in Haml, like so:
165
+ #
166
+ # %html{html_attrs('fr-fr')}
167
+ #
168
+ # This is compiled to:
169
+ #
170
+ # <html lang='fr-fr' xml:lang='fr-fr' xmlns='http://www.w3.org/1999/xhtml'>
171
+ # </html>
172
+ #
173
+ # You can use as many such attribute methods as you want
174
+ # by separating them with commas,
175
+ # like a Ruby argument list.
176
+ # All the hashes will me merged together, from left to right.
177
+ # For example, if you defined
178
+ #
179
+ # def hash1
180
+ # {:bread => 'white', :filling => 'peanut butter and jelly'}
181
+ # end
182
+ #
183
+ # def hash2
184
+ # {:bread => 'whole wheat'}
185
+ # end
186
+ #
187
+ # then
188
+ #
189
+ # %sandwich{hash1, hash2, :delicious => true}/
190
+ #
191
+ # would compile to:
192
+ #
193
+ # <sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
194
+ #
195
+ # Note that the Haml attributes list has the same syntax as a Ruby method call.
196
+ # This means that any attribute methods must come before the hash literal.
197
+ #
198
+ # ===== Boolean Attributes
199
+ #
200
+ # Some attributes, such as "checked" for <tt>input</tt> tags or "selected" for <tt>option</tt> tags,
201
+ # are "boolean" in the sense that their values don't matter -
202
+ # it only matters whether or not they're present.
203
+ # In HTML (but not XHTML), these attributes can be written as
204
+ #
205
+ # <input selected>
206
+ #
207
+ # To do this in Haml, just assign a Ruby true value to the attribute:
208
+ #
209
+ # %input{:selected => true}
210
+ #
211
+ # In XHTML, the only valid value for these attributes is the name of the attribute.
212
+ # Thus this will render in XHTML as
213
+ #
214
+ # <input selected='selected'>
215
+ #
216
+ # To set these attributes to false, simply assign them to a Ruby false value.
217
+ # In both XHTML and HTML
218
+ #
219
+ # %input{:selected => false}
220
+ #
221
+ # will just render as
222
+ #
223
+ # <input>
224
+ #
225
+ # ==== . and #
226
+ #
227
+ # The period and pound sign are borrowed from CSS.
228
+ # They are used as shortcuts to specify the <tt>class</tt>
229
+ # and <tt>id</tt> attributes of an element, respectively.
230
+ # Multiple class names can be specified in a similar way to CSS,
231
+ # by chaining the class names together with periods.
232
+ # They are placed immediately after the tag and before an attributes hash.
233
+ # For example:
234
+ #
235
+ # %div#things
236
+ # %span#rice Chicken Fried
237
+ # %p.beans{ :food => 'true' } The magical fruit
238
+ # %h1.class.otherclass#id La La La
239
+ #
240
+ # is compiled to:
241
+ #
242
+ # <div id='things'>
243
+ # <span id='rice'>Chicken Fried</span>
244
+ # <p class='beans' food='true'>The magical fruit</p>
245
+ # <h1 class='class otherclass' id='id'>La La La</h1>
246
+ # </div>
247
+ #
248
+ # And,
249
+ #
250
+ # #content
251
+ # .articles
252
+ # .article.title
253
+ # Doogie Howser Comes Out
254
+ # .article.date
255
+ # 2006-11-05
256
+ # .article.entry
257
+ # Neil Patrick Harris would like to dispel any rumors that he is straight
258
+ #
259
+ # is compiled to:
260
+ #
261
+ # <div id='content'>
262
+ # <div class='articles'>
263
+ # <div class='article title'>Doogie Howser Comes Out</div>
264
+ # <div class='article date'>2006-11-05</div>
265
+ # <div class='article entry'>
266
+ # Neil Patrick Harris would like to dispel any rumors that he is straight
267
+ # </div>
268
+ # </div>
269
+ # </div>
270
+ #
271
+ # ==== Implicit Div Elements
272
+ #
273
+ # Because the div element is used so often, it is the default element.
274
+ # If you only define a class and/or id using the <tt>.</tt> or <tt>#</tt> syntax,
275
+ # a div element is automatically used.
276
+ # For example:
277
+ #
278
+ # #collection
279
+ # .item
280
+ # .description What a cool item!
281
+ #
282
+ # is the same as:
283
+ #
284
+ # %div{:id => collection}
285
+ # %div{:class => 'item'}
286
+ # %div{:class => 'description'} What a cool item!
287
+ #
288
+ # and is compiled to:
289
+ #
290
+ # <div id='collection'>
291
+ # <div class='item'>
292
+ # <div class='description'>What a cool item!</div>
293
+ # </div>
294
+ # </div>
295
+ #
296
+ # ==== /
297
+ #
298
+ # The forward slash character, when placed at the end of a tag definition,
299
+ # causes the tag to be self-closed.
300
+ # For example:
301
+ #
302
+ # %br/
303
+ # %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
304
+ #
305
+ # is compiled to:
306
+ #
307
+ # <br />
308
+ # <meta http-equiv='Content-Type' content='text/html' />
309
+ #
310
+ # Some tags are automatically closed, as long as they have no content.
311
+ # +meta+, +img+, +link+, +script+, +br+, and +hr+ tags are closed by default.
312
+ # This list can be customized by setting the <tt>:autoclose</tt> option (see below).
313
+ # For example:
314
+ #
315
+ # %br
316
+ # %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}
317
+ #
318
+ # is also compiled to:
319
+ #
320
+ # <br />
321
+ # <meta http-equiv='Content-Type' content='text/html' />
322
+ #
323
+ # ==== []
324
+ #
325
+ # Square brackets follow a tag definition and contain a Ruby object
326
+ # that is used to set the class and id of that tag.
327
+ # The class is set to the object's class
328
+ # (transformed to use underlines rather than camel case)
329
+ # and the id is set to the object's class, followed by its id.
330
+ # Because the id of an object is normally an obscure implementation detail,
331
+ # this is most useful for elements that represent instances of Models.
332
+ # Additionally, the second argument (if present) will be used as a prefix for
333
+ # both the id and class attributes.
334
+ # For example:
335
+ #
336
+ # # file: app/controllers/users_controller.rb
337
+ #
338
+ # def show
339
+ # @user = CrazyUser.find(15)
340
+ # end
341
+ #
342
+ # -# file: app/views/users/show.haml
343
+ #
344
+ # %div[@user, :greeting]
345
+ # %bar[290]/
346
+ # Hello!
347
+ #
348
+ # is compiled to:
349
+ #
350
+ # <div class='greeting_crazy_user' id='greeting_crazy_user_15'>
351
+ # <bar class='fixnum' id='fixnum_581' />
352
+ # Hello!
353
+ # </div>
354
+ #
355
+ # ==== > and <
356
+ #
357
+ # <tt>></tt> and <tt><</tt> give you more control over the whitespace near a tag.
358
+ # <tt>></tt> will remove all whitespace surrounding a tag,
359
+ # while <tt><</tt> will remove all whitespace immediately within a tag.
360
+ # You can think of them as alligators eating the whitespace:
361
+ # <tt>></tt> faces out of the tag and eats the whitespace on the outside,
362
+ # and <tt><</tt> faces into the tag and eats the whitespace on the inside.
363
+ # They're placed at the end of a tag definition,
364
+ # after class, id, and attribute declarations
365
+ # but before <tt>/</tt> or <tt>=</tt>.
366
+ # For example:
367
+ #
368
+ # %blockquote<
369
+ # %div
370
+ # Foo!
371
+ #
372
+ # is compiled to:
373
+ #
374
+ # <blockquote><div>
375
+ # Foo!
376
+ # </div></blockquote>
377
+ #
378
+ # And:
379
+ #
380
+ # %img
381
+ # %img>
382
+ # %img
383
+ #
384
+ # is compiled to:
385
+ #
386
+ # <img /><img /><img />
387
+ #
388
+ # And:
389
+ #
390
+ # %p<= "Foo\nBar"
391
+ #
392
+ # is compiled to:
393
+ #
394
+ # <p>Foo
395
+ # Bar</p>
396
+ #
397
+ # And finally:
398
+ #
399
+ # %img
400
+ # %pre><
401
+ # foo
402
+ # bar
403
+ # %img
404
+ #
405
+ # is compiled to:
406
+ #
407
+ # <img /><pre>foo
408
+ # bar</pre><img />
409
+ #
410
+ # ==== =
411
+ #
412
+ # <tt>=</tt> is placed at the end of a tag definition,
413
+ # after class, id, and attribute declarations.
414
+ # It's just a shortcut for inserting Ruby code into an element.
415
+ # It works the same as <tt>=</tt> without a tag:
416
+ # it inserts the result of the Ruby code into the template.
417
+ # However, if the result is short enough,
418
+ # it is displayed entirely on one line.
419
+ # For example:
420
+ #
421
+ # %p= "hello"
422
+ #
423
+ # is not quite the same as:
424
+ #
425
+ # %p
426
+ # = "hello"
427
+ #
428
+ # It's compiled to:
429
+ #
430
+ # <p>hello</p>
431
+ #
432
+ # ==== #{}
433
+ #
434
+ # Ruby code can also be interpolated within plain text using <tt>#{}</tt>,
435
+ # similarly to Ruby string interpolation.
436
+ # For example,
437
+ #
438
+ # %p This is #{h quality} cake!
439
+ #
440
+ # is the same as
441
+ #
442
+ # %p= "This is the #{h quality} cake!"
443
+ #
444
+ # and might compile to
445
+ #
446
+ # <p>This is scrumptious cake!</p>
447
+ #
448
+ # Backslashes can be used to escape "#{" strings,
449
+ # but they don't act as escapes anywhere else in the string.
450
+ # For example:
451
+ #
452
+ # %p
453
+ # \\ Look at \\#{h word} lack of backslash: \#{foo}
454
+ #
455
+ # might compile to
456
+ #
457
+ # <p>
458
+ # \\ Look at \yon lack of backslash: #{foo}
459
+ # </p>
460
+ #
461
+ # ==== ~
462
+ #
463
+ # ~ works just like =, except that it runs Haml::Helpers#find_and_preserve on its input.
464
+ # For example,
465
+ #
466
+ # ~ "Foo\n<pre>Bar\nBaz</pre>"
467
+ #
468
+ # is the same as:
469
+ #
470
+ # = find_and_preserve("Foo\n<pre>Bar\nBaz</pre>")
471
+ #
472
+ # and is compiled to:
473
+ #
474
+ # Foo
475
+ # <pre>Bar&#x000A;Baz</pre>
476
+ #
477
+ # See also Whitespace Preservation, below.
478
+ #
479
+ # === XHTML Helpers
480
+ #
481
+ # ==== No Special Character
482
+ #
483
+ # If no special character appears at the beginning of a line,
484
+ # the line is rendered as plain text.
485
+ # For example:
486
+ #
487
+ # %gee
488
+ # %whiz
489
+ # Wow this is cool!
490
+ #
491
+ # is compiled to:
492
+ #
493
+ # <gee>
494
+ # <whiz>
495
+ # Wow this is cool!
496
+ # </whiz>
497
+ # </gee>
498
+ #
499
+ # ==== !!!
500
+ #
501
+ # When describing XHTML documents with Haml,
502
+ # you can have a document type or XML prolog generated automatically
503
+ # by including the characters <tt>!!!</tt>.
504
+ # For example:
505
+ #
506
+ # !!! XML
507
+ # !!!
508
+ # %html
509
+ # %head
510
+ # %title Myspace
511
+ # %body
512
+ # %h1 I am the international space station
513
+ # %p Sign my guestbook
514
+ #
515
+ # is compiled to:
516
+ #
517
+ # <?xml version='1.0' encoding='utf-8' ?>
518
+ # <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
519
+ # <html>
520
+ # <head>
521
+ # <title>Myspace</title>
522
+ # </head>
523
+ # <body>
524
+ # <h1>I am the international space station</h1>
525
+ # <p>Sign my guestbook</p>
526
+ # </body>
527
+ # </html>
528
+ #
529
+ # You can also specify the version and type of XHTML after the <tt>!!!</tt>.
530
+ # XHTML 1.0 Strict, Transitional, and Frameset and XHTML 1.1 are supported.
531
+ # The default version is 1.0 and the default type is Transitional.
532
+ # For example:
533
+ #
534
+ # !!! 1.1
535
+ #
536
+ # is compiled to:
537
+ #
538
+ # <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
539
+ #
540
+ # and
541
+ #
542
+ # !!! Strict
543
+ #
544
+ # is compiled to:
545
+ #
546
+ # <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
547
+ #
548
+ # while
549
+ #
550
+ # !!! Basic
551
+ #
552
+ # is compiled to:
553
+ #
554
+ # <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
555
+ #
556
+ # and
557
+ #
558
+ # !!! Mobile
559
+ #
560
+ # is compiled to:
561
+ #
562
+ # <!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">
563
+ #
564
+ # If you're not using the UTF-8 character set for your document,
565
+ # you can specify which encoding should appear
566
+ # in the XML prolog in a similar way.
567
+ # For example:
568
+ #
569
+ # !!! XML iso-8859-1
570
+ #
571
+ # is compiled to:
572
+ #
573
+ # <?xml version='1.0' encoding='iso-8859-1' ?>
574
+ #
575
+ # ==== /
576
+ #
577
+ # The forward slash character, when placed at the beginning of a line,
578
+ # wraps all text after it in an HTML comment.
579
+ # For example:
580
+ #
581
+ # %peanutbutterjelly
582
+ # / This is the peanutbutterjelly element
583
+ # I like sandwiches!
584
+ #
585
+ # is compiled to:
586
+ #
587
+ # <peanutbutterjelly>
588
+ # <!-- This is the peanutbutterjelly element -->
589
+ # I like sandwiches!
590
+ # </peanutbutterjelly>
591
+ #
592
+ # The forward slash can also wrap indented sections of code. For example:
593
+ #
594
+ # /
595
+ # %p This doesn't render...
596
+ # %div
597
+ # %h1 Because it's commented out!
598
+ #
599
+ # is compiled to:
600
+ #
601
+ # <!--
602
+ # <p>This doesn't render...</p>
603
+ # <div>
604
+ # <h1>Because it's commented out!</h1>
605
+ # </div>
606
+ # -->
607
+ #
608
+ # You can also use Internet Explorer conditional comments
609
+ # (about)[http://www.quirksmode.org/css/condcom.html]
610
+ # by enclosing the condition in square brackets after the <tt>/</tt>.
611
+ # For example:
612
+ #
613
+ # /[if IE]
614
+ # %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
615
+ # %h1 Get Firefox
616
+ #
617
+ # is compiled to:
618
+ #
619
+ # <!--[if IE]>
620
+ # <a href='http://www.mozilla.com/en-US/firefox/'>
621
+ # <h1>Get Firefox</h1>
622
+ # </a>
623
+ # <![endif]-->
624
+ #
625
+ # ==== \
626
+ #
627
+ # The backslash character escapes the first character of a line,
628
+ # allowing use of otherwise interpreted characters as plain text.
629
+ # For example:
630
+ #
631
+ # %title
632
+ # = @title
633
+ # \- MySite
634
+ #
635
+ # is compiled to:
636
+ #
637
+ # <title>
638
+ # MyPage
639
+ # - MySite
640
+ # </title>
641
+ #
642
+ # ==== |
643
+ #
644
+ # The pipe character designates a multiline string.
645
+ # It's placed at the end of a line
646
+ # and means that all following lines that end with <tt>|</tt>
647
+ # will be evaluated as though they were on the same line.
648
+ # For example:
649
+ #
650
+ # %whoo
651
+ # %hoo I think this might get |
652
+ # pretty long so I should |
653
+ # probably make it |
654
+ # multiline so it doesn't |
655
+ # look awful. |
656
+ # %p This is short.
657
+ #
658
+ # is compiled to:
659
+ #
660
+ # <whoo>
661
+ # <hoo>
662
+ # I think this might get pretty long so I should probably make it multiline so it doesn't look awful.
663
+ # </hoo>
664
+ # <p>This is short</p>
665
+ # </whoo>
666
+ #
667
+ # ==== :
668
+ #
669
+ # The colon character designates a filter.
670
+ # This allows you to pass an indented block of text as input
671
+ # to another filtering program and add the result to the output of Haml.
672
+ # The syntax is simply a colon followed by the name of the filter.
673
+ # For example,
674
+ #
675
+ # %p
676
+ # :markdown
677
+ # Textile
678
+ # =======
679
+ #
680
+ # Hello, *World*
681
+ #
682
+ # is compiled to
683
+ #
684
+ # <p>
685
+ # <h1>Textile</h1>
686
+ #
687
+ # <p>Hello, <em>World</em></p>
688
+ # </p>
689
+ #
690
+ # Filters can have Ruby code interpolated, like with ==.
691
+ # For example,
692
+ #
693
+ # - flavor = "raspberry"
694
+ # #content
695
+ # :textile
696
+ # I *really* prefer _#{h flavor}_ jam.
697
+ #
698
+ # is compiled to
699
+ #
700
+ # <div id='content'>
701
+ # <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
702
+ # </div>
703
+ #
704
+ # Haml has the following filters defined:
705
+ #
706
+ # [plain] Does not parse the filtered text.
707
+ # This is useful for large blocks of text without HTML tags,
708
+ # when you don't want lines starting with <tt>.</tt> or <tt>-</tt>
709
+ # to be parsed.
710
+ #
711
+ # [javascript] Surrounds the filtered text with <script> and CDATA tags.
712
+ # Useful for including inline Javascript.
713
+ #
714
+ # [escaped] Works the same as plain, but HTML-escapes the text
715
+ # before placing it in the document.
716
+ #
717
+ # [ruby] Parses the filtered text with the normal Ruby interpreter.
718
+ # All output sent to <tt>$stdout</tt>, like with +puts+,
719
+ # is output into the Haml document.
720
+ # Not available if the <tt>suppress_eval</tt> option is set to true.
721
+ # The Ruby code is evaluated in the same context as the Haml template.
722
+ #
723
+ # [preserve] Inserts the filtered text into the template with whitespace preserved.
724
+ # <tt>preserve</tt>d blocks of text aren't indented,
725
+ # and newlines are replaced with the HTML escape code for newlines,
726
+ # to preserve nice-looking output.
727
+ # See also Whitespace Preservation, below.
728
+ #
729
+ # [erb] Parses the filtered text with ERB, like an RHTML template.
730
+ # Not available if the <tt>suppress_eval</tt> option is set to true.
731
+ # Embedded Ruby code is evaluated in the same context as the Haml template.
732
+ #
733
+ # [sass] Parses the filtered text with Sass to produce CSS output.
734
+ #
735
+ # [textile] Parses the filtered text with Textile (http://www.textism.com/tools/textile).
736
+ # Only works if RedCloth is installed.
737
+ #
738
+ # [markdown] Parses the filtered text with Markdown (http://daringfireball.net/projects/markdown).
739
+ # Only works if RDiscount, RPeg-Markdown, Maruku, or BlueCloth are installed.
740
+ #
741
+ # [maruku] Parses the filtered text with Maruku, which has some non-standard extensions to Markdown.
742
+ #
743
+ # You can also define your own filters (see Haml::Filters).
744
+ #
745
+ # === Ruby evaluators
746
+ #
747
+ # ==== =
748
+ #
749
+ # The equals character is followed by Ruby code,
750
+ # which is evaluated and the output inserted into the document as plain text.
751
+ # For example:
752
+ #
753
+ # %p
754
+ # = ['hi', 'there', 'reader!'].join " "
755
+ # = "yo"
756
+ #
757
+ # is compiled to:
758
+ #
759
+ # <p>
760
+ # hi there reader!
761
+ # yo
762
+ # </p>
763
+ #
764
+ # If the <tt>:escape_html</tt> option is set, <tt>=</tt> will sanitize any
765
+ # HTML-sensitive characters generated by the script. For example:
766
+ #
767
+ # = '<script>alert("I\'m evil!");</script>'
768
+ #
769
+ # would be compiled to
770
+ #
771
+ # &lt;script&gt;alert(&quot;I'm evil!&quot;);&lt;/script&gt;
772
+ #
773
+ # ==== -
774
+ #
775
+ # The hyphen character makes the text following it into "silent script":
776
+ # Ruby script that is evaluated, but not output.
777
+ #
778
+ # <b>It is not recommended that you use this widely;
779
+ # almost all processing code and logic should be restricted
780
+ # to the Controller, the Helper, or partials.</b>
781
+ #
782
+ # For example:
783
+ #
784
+ # - foo = "hello"
785
+ # - foo << " there"
786
+ # - foo << " you!"
787
+ # %p= foo
788
+ #
789
+ # is compiled to:
790
+ #
791
+ # <p>
792
+ # hello there you!
793
+ # </p>
794
+ #
795
+ # ==== &=
796
+ #
797
+ # An ampersand followed by one or two equals characters
798
+ # evaluates Ruby code just like the equals without the ampersand,
799
+ # but sanitizes any HTML-sensitive characters in the result of the code.
800
+ # For example:
801
+ #
802
+ # &= "I like cheese & crackers"
803
+ #
804
+ # compiles to
805
+ #
806
+ # I like cheese &amp; crackers
807
+ #
808
+ # If the <tt>:escape_html</tt> option is set,
809
+ # &= behaves identically to =.
810
+ #
811
+ # & can also be used on its own so that <tt>#{}</tt> interpolation is escaped.
812
+ # For example,
813
+ #
814
+ # & I like #{"cheese & crackers"}
815
+ #
816
+ # compiles to
817
+ #
818
+ # I like cheese &amp; crackers
819
+ #
820
+ # ==== !=
821
+ #
822
+ # An exclamation mark followed by one or two equals characters
823
+ # evaluates Ruby code just like the equals would,
824
+ # but never sanitizes the HTML.
825
+ #
826
+ # By default, the single equals doesn't sanitize HTML either.
827
+ # However, if the <tt>:escape_html</tt> option is set, = will sanitize the HTML, but != still won't.
828
+ # For example, if <tt>:escape_html</tt> is set:
829
+ #
830
+ # = "I feel <strong>!"
831
+ # != "I feel <strong>!"
832
+ #
833
+ # compiles to
834
+ #
835
+ # I feel &lt;strong&gt;!
836
+ # I feel <strong>!
837
+ #
838
+ # ! can also be used on its own so that <tt>#{}</tt> interpolation is unescaped.
839
+ # For example,
840
+ #
841
+ # ! I feel #{"<strong>"}!
842
+ #
843
+ # compiles to
844
+ #
845
+ # I feel <strong>!
846
+ #
847
+ # ===== Blocks
848
+ #
849
+ # Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
850
+ # Rather, they're automatically closed, based on indentation.
851
+ # A block begins whenever the indentation is increased
852
+ # after a silent script command.
853
+ # It ends when the indentation decreases
854
+ # (as long as it's not an +else+ clause or something similar).
855
+ # For example:
856
+ #
857
+ # - (42...47).each do |i|
858
+ # %p= i
859
+ # %p See, I can count!
860
+ #
861
+ # is compiled to:
862
+ #
863
+ # <p>
864
+ # 42
865
+ # </p>
866
+ # <p>
867
+ # 43
868
+ # </p>
869
+ # <p>
870
+ # 44
871
+ # </p>
872
+ # <p>
873
+ # 45
874
+ # </p>
875
+ # <p>
876
+ # 46
877
+ # </p>
878
+ #
879
+ # Another example:
880
+ #
881
+ # %p
882
+ # - case 2
883
+ # - when 1
884
+ # = "1!"
885
+ # - when 2
886
+ # = "2?"
887
+ # - when 3
888
+ # = "3."
889
+ #
890
+ # is compiled to:
891
+ #
892
+ # <p>
893
+ # 2?
894
+ # </p>
895
+ #
896
+ # ==== -#
897
+ #
898
+ # The hyphen followed immediately by the pound sign
899
+ # signifies a silent comment.
900
+ # Any text following this isn't rendered in the resulting document
901
+ # at all.
902
+ #
903
+ # For example:
904
+ #
905
+ # %p foo
906
+ # -# This is a comment
907
+ # %p bar
908
+ #
909
+ # is compiled to:
910
+ #
911
+ # <p>foo</p>
912
+ # <p>bar</p>
913
+ #
914
+ # You can also nest text beneath a silent comment.
915
+ # None of this text will be rendered.
916
+ # For example:
917
+ #
918
+ # %p foo
919
+ # -#
920
+ # This won't be displayed
921
+ # Nor will this
922
+ # %p bar
923
+ #
924
+ # is compiled to:
925
+ #
926
+ # <p>foo</p>
927
+ # <p>bar</p>
928
+ #
929
+ # == Other Useful Things
930
+ #
931
+ # === Whitespace Preservation
932
+ #
933
+ # Sometimes you don't want Haml to indent all your text.
934
+ # For example, tags like +pre+ and +textarea+ are whitespace-sensitive;
935
+ # indenting the text makes them render wrong.
936
+ #
937
+ # Haml deals with this by "preserving" newlines before they're put into the document --
938
+ # converting them to the XHTML whitespace escape code, <tt>&#x000A;</tt>.
939
+ # Then Haml won't try to re-format the indentation.
940
+ #
941
+ # Literal +textarea+ and +pre+ tags automatically preserve their content.
942
+ # Dynamically can't be caught automatically,
943
+ # and so should be passed through Haml::Helpers#find_and_preserve or the <tt>~</tt> command,
944
+ # which has the same effect (see above).
945
+ #
946
+ # Blocks of literal text can be preserved using the :preserve filter (see above).
947
+ #
948
+ # === Helpers
949
+ #
950
+ # Haml offers a bunch of helpers that are useful
951
+ # for doing stuff like preserving whitespace,
952
+ # creating nicely indented output for user-defined helpers,
953
+ # and other useful things.
954
+ # The helpers are all documented in the Haml::Helpers and Haml::Helpers::ActionViewExtensions modules.
955
+ #
956
+ # === Haml Options
957
+ #
958
+ # Options can be set by setting the <tt>Haml::Template.options</tt> hash
959
+ # in <tt>environment.rb</tt> in Rails...
960
+ #
961
+ # Haml::Template.options[:format] = :html5
962
+ #
963
+ # ...or by setting the <tt>Merb::Plugin.config[:haml]</tt> hash in <tt>init.rb</tt> in Merb...
964
+ #
965
+ # Merb::Plugin.config[:haml][:format] = :html5
966
+ #
967
+ # ...or by passing an options hash to Haml::Engine.new.
968
+ # Available options are:
969
+ #
970
+ # [<tt>:format</tt>] Determines the output format. The default is :xhtml.
971
+ # Other options are :html4 and :html5, which are
972
+ # identical to :xhtml except there are no self-closing tags,
973
+ # XML prolog is ignored and correct DOCTYPEs are generated.
974
+ #
975
+ # [<tt>:escape_html</tt>] Sets whether or not to escape HTML-sensitive characters in script.
976
+ # If this is true, = behaves like &=;
977
+ # otherwise, it behaves like !=.
978
+ # Note that if this is set, != should be used for yielding to subtemplates
979
+ # and rendering partials.
980
+ # Defaults to false.
981
+ #
982
+ # [<tt>:suppress_eval</tt>] Whether or not attribute hashes and Ruby scripts
983
+ # designated by <tt>=</tt> or <tt>~</tt> should be
984
+ # evaluated. If this is true, said scripts are
985
+ # rendered as empty strings. Defaults to false.
986
+ #
987
+ # [<tt>:attr_wrapper</tt>] The character that should wrap element attributes.
988
+ # This defaults to <tt>'</tt> (an apostrophe). Characters
989
+ # of this type within the attributes will be escaped
990
+ # (e.g. by replacing them with <tt>&apos;</tt>) if
991
+ # the character is an apostrophe or a quotation mark.
992
+ #
993
+ # [<tt>:filename</tt>] The name of the Haml file being parsed.
994
+ # This is only used as information when exceptions are raised.
995
+ # This is automatically assigned when working through ActionView,
996
+ # so it's really only useful for the user to assign
997
+ # when dealing with Haml programatically.
998
+ #
999
+ # [<tt>:line</tt>] The line offset of the Haml template being parsed.
1000
+ # This is useful for inline templates,
1001
+ # similar to the last argument to Kernel#eval.
1002
+ #
1003
+ # [<tt>:autoclose</tt>] A list of tag names that should be automatically self-closed
1004
+ # if they have no content.
1005
+ # Defaults to <tt>['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']</tt>.
1006
+ #
1007
+ # [<tt>:preserve</tt>] A list of tag names that should automatically have their newlines preserved
1008
+ # using the Haml::Helpers#preserve helper.
1009
+ # This means that any content given on the same line as the tag will be preserved.
1010
+ # For example:
1011
+ #
1012
+ # %textarea= "Foo\nBar"
1013
+ #
1014
+ # compiles to:
1015
+ #
1016
+ # <textarea>Foo&&#x000A;Bar</textarea>
1017
+ #
1018
+ # Defaults to <tt>['textarea', 'pre']</tt>.
1019
+ #
1020
+ # See also Whitespace Preservation, above.
1021
+ #
1022
+ module Haml
1023
+
1024
+ extend Haml::Version
1025
+
1026
+ # A string representing the version of Haml.
1027
+ # A more fine-grained representation is available from Haml.version.
1028
+ VERSION = version[:string] unless defined?(Haml::VERSION)
1029
+
1030
+ # This method is called by init.rb,
1031
+ # which is run by Rails on startup.
1032
+ # We use it rather than putting stuff straight into init.rb
1033
+ # so we can change the initialization behavior
1034
+ # without modifying the file itself.
1035
+ def self.init_rails(binding)
1036
+ # No &method here for Rails 2.1 compatibility
1037
+ %w[haml/template sass sass/plugin].each {|f| require f}
1038
+ end
1039
+ end
1040
+
1041
+ require 'haml/util'
1042
+ require 'haml/engine'