haml 2.0.10 → 2.2.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of haml might be problematic. Click here for more details.

Files changed (107) hide show
  1. data/.yardopts +5 -0
  2. data/MIT-LICENSE +1 -1
  3. data/README.md +347 -0
  4. data/Rakefile +124 -19
  5. data/VERSION +1 -1
  6. data/VERSION_NAME +1 -0
  7. data/extra/haml-mode.el +397 -78
  8. data/extra/sass-mode.el +148 -36
  9. data/extra/update_watch.rb +13 -0
  10. data/lib/haml.rb +15 -993
  11. data/lib/haml/buffer.rb +131 -84
  12. data/lib/haml/engine.rb +129 -97
  13. data/lib/haml/error.rb +7 -7
  14. data/lib/haml/exec.rb +127 -42
  15. data/lib/haml/filters.rb +107 -42
  16. data/lib/haml/helpers.rb +210 -156
  17. data/lib/haml/helpers/action_view_extensions.rb +34 -39
  18. data/lib/haml/helpers/action_view_mods.rb +132 -139
  19. data/lib/haml/html.rb +77 -65
  20. data/lib/haml/precompiler.rb +404 -213
  21. data/lib/haml/shared.rb +78 -0
  22. data/lib/haml/template.rb +14 -14
  23. data/lib/haml/template/patch.rb +2 -2
  24. data/lib/haml/template/plugin.rb +2 -3
  25. data/lib/haml/util.rb +211 -6
  26. data/lib/haml/version.rb +30 -13
  27. data/lib/sass.rb +7 -856
  28. data/lib/sass/css.rb +169 -161
  29. data/lib/sass/engine.rb +344 -328
  30. data/lib/sass/environment.rb +79 -0
  31. data/lib/sass/error.rb +33 -11
  32. data/lib/sass/files.rb +139 -0
  33. data/lib/sass/plugin.rb +160 -117
  34. data/lib/sass/plugin/merb.rb +7 -6
  35. data/lib/sass/plugin/rails.rb +5 -6
  36. data/lib/sass/repl.rb +58 -0
  37. data/lib/sass/script.rb +59 -0
  38. data/lib/sass/script/bool.rb +17 -0
  39. data/lib/sass/script/color.rb +183 -0
  40. data/lib/sass/script/funcall.rb +50 -0
  41. data/lib/sass/script/functions.rb +198 -0
  42. data/lib/sass/script/lexer.rb +178 -0
  43. data/lib/sass/script/literal.rb +177 -0
  44. data/lib/sass/script/node.rb +14 -0
  45. data/lib/sass/script/number.rb +381 -0
  46. data/lib/sass/script/operation.rb +45 -0
  47. data/lib/sass/script/parser.rb +172 -0
  48. data/lib/sass/script/string.rb +12 -0
  49. data/lib/sass/script/unary_operation.rb +34 -0
  50. data/lib/sass/script/variable.rb +31 -0
  51. data/lib/sass/tree/comment_node.rb +73 -10
  52. data/lib/sass/tree/debug_node.rb +30 -0
  53. data/lib/sass/tree/directive_node.rb +42 -17
  54. data/lib/sass/tree/file_node.rb +41 -0
  55. data/lib/sass/tree/for_node.rb +48 -0
  56. data/lib/sass/tree/if_node.rb +54 -0
  57. data/lib/sass/tree/mixin_def_node.rb +29 -0
  58. data/lib/sass/tree/mixin_node.rb +48 -0
  59. data/lib/sass/tree/node.rb +214 -11
  60. data/lib/sass/tree/prop_node.rb +109 -0
  61. data/lib/sass/tree/rule_node.rb +178 -51
  62. data/lib/sass/tree/variable_node.rb +34 -0
  63. data/lib/sass/tree/while_node.rb +31 -0
  64. data/test/haml/engine_test.rb +331 -36
  65. data/test/haml/helper_test.rb +12 -1
  66. data/test/haml/results/content_for_layout.xhtml +0 -3
  67. data/test/haml/results/filters.xhtml +2 -0
  68. data/test/haml/results/list.xhtml +1 -1
  69. data/test/haml/template_test.rb +7 -2
  70. data/test/haml/templates/content_for_layout.haml +0 -2
  71. data/test/haml/templates/list.haml +1 -1
  72. data/test/haml/util_test.rb +92 -0
  73. data/test/sass/css2sass_test.rb +69 -24
  74. data/test/sass/engine_test.rb +586 -64
  75. data/test/sass/functions_test.rb +125 -0
  76. data/test/sass/more_results/more1.css +9 -0
  77. data/test/sass/more_results/more1_with_line_comments.css +26 -0
  78. data/test/sass/more_results/more_import.css +29 -0
  79. data/test/sass/more_templates/_more_partial.sass +2 -0
  80. data/test/sass/more_templates/more1.sass +23 -0
  81. data/test/sass/more_templates/more_import.sass +11 -0
  82. data/test/sass/plugin_test.rb +81 -28
  83. data/test/sass/results/line_numbers.css +49 -0
  84. data/test/sass/results/{constants.css → script.css} +4 -4
  85. data/test/sass/results/subdir/subdir.css +2 -0
  86. data/test/sass/results/units.css +11 -0
  87. data/test/sass/script_test.rb +258 -0
  88. data/test/sass/templates/import.sass +1 -1
  89. data/test/sass/templates/importee.sass +7 -2
  90. data/test/sass/templates/line_numbers.sass +13 -0
  91. data/test/sass/templates/{constants.sass → script.sass} +11 -10
  92. data/test/sass/templates/subdir/nested_subdir/_nested_partial.sass +2 -0
  93. data/test/sass/templates/subdir/subdir.sass +2 -2
  94. data/test/sass/templates/units.sass +11 -0
  95. data/test/test_helper.rb +14 -0
  96. metadata +77 -19
  97. data/FAQ +0 -138
  98. data/README.rdoc +0 -319
  99. data/lib/sass/constant.rb +0 -216
  100. data/lib/sass/constant/color.rb +0 -101
  101. data/lib/sass/constant/literal.rb +0 -54
  102. data/lib/sass/constant/nil.rb +0 -9
  103. data/lib/sass/constant/number.rb +0 -87
  104. data/lib/sass/constant/operation.rb +0 -30
  105. data/lib/sass/constant/string.rb +0 -22
  106. data/lib/sass/tree/attr_node.rb +0 -57
  107. data/lib/sass/tree/value_node.rb +0 -20
@@ -3,869 +3,20 @@ $LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
3
3
 
4
4
  require 'haml/version'
5
5
 
6
- # = Sass (Syntactically Awesome StyleSheets)
6
+ # The module that contains everything Sass-related:
7
7
  #
8
- # Sass is a meta-language on top of CSS
9
- # that's used to describe the style of a document
10
- # cleanly and structurally,
11
- # with more power than flat CSS allows.
12
- # Sass both provides a simpler, more elegant syntax for CSS
13
- # and implements various features that are useful
14
- # for creating manageable stylesheets.
15
- #
16
- # == Features
17
- #
18
- # * Whitespace active
19
- # * Well-formatted output
20
- # * Elegant input
21
- # * Feature-rich
22
- #
23
- # == Using Sass
24
- #
25
- # Sass can be used in three ways:
26
- # as a plugin for Ruby on Rails,
27
- # as a standalone Ruby module,
28
- # and as a command-line tool.
29
- # Sass is bundled with Haml,
30
- # so if the Haml plugin or RubyGem is installed,
31
- # Sass will already be installed as a plugin or gem, respectively.
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
- # To enable Sass in Merb,
42
- # add
43
- #
44
- # dependency "merb-haml"
45
- #
46
- # to config/dependencies.rb.
47
- #
48
- # Sass templates in Rails don't quite function in the same way as views,
49
- # because they don't contain dynamic content,
50
- # and so only need to be compiled when the template file has been updated.
51
- # By default (see options, below),
52
- # ".sass" files are placed in public/stylesheets/sass.
53
- # Then, whenever necessary, they're compiled into corresponding CSS files in public/stylesheets.
54
- # For instance, public/stylesheets/sass/main.sass would be compiled to public/stylesheets/main.css.
55
- #
56
- # To run Sass from the command line, just use
57
- #
58
- # sass input.sass output.css
59
- #
60
- # Use <tt>sass --help</tt> for full documentation.
61
- #
62
- # Using Sass in Ruby code is very simple.
63
- # After installing the Haml gem,
64
- # you can use it by running <tt>require "sass"</tt>
65
- # and using Sass::Engine like so:
66
- #
67
- # engine = Sass::Engine.new("#main\n :background-color #0000ff")
68
- # engine.render #=> "#main { background-color: #0000ff; }\n"
69
- #
70
- # == CSS Rules
71
- #
72
- # Rules in flat CSS have two elements:
73
- # the selector
74
- # (e.g. "#main", "div p", "li a:hover")
75
- # and the attributes
76
- # (e.g. "color: #00ff00;", "width: 5em;").
77
- #
78
- # Sass has both of these,
79
- # as well as one additional element: nested rules.
80
- #
81
- # === Rules and Selectors
82
- #
83
- # However, some of the syntax is a little different.
84
- # The syntax for selectors is the same,
85
- # but instead of using brackets to delineate the attributes that belong to a particular rule,
86
- # Sass uses two spaces of indentation.
87
- # For example:
88
- #
89
- # #main p
90
- # <attribute>
91
- # <attribute>
92
- # ...
93
- #
94
- # Like CSS, you can stretch rules over multiple lines.
95
- # However, unlike CSS, you can only do this if each line but the last
96
- # ends with a comma.
97
- # For example:
98
- #
99
- # .users #userTab,
100
- # .posts #postsTab
101
- # <attributes>
102
- #
103
- # === Attributes
104
- #
105
- # There are two different ways to write CSS attrbibutes.
106
- # The first is very similar to the how you're used to writing them:
107
- # with a colon between the name and the value.
108
- # However, Sass attributes don't have semicolons at the end;
109
- # each attribute is on its own line, so they aren't necessary.
110
- # For example:
111
- #
112
- # #main p
113
- # color: #00ff00
114
- # width: 97%
115
- #
116
- # is compiled to:
117
- #
118
- # #main p {
119
- # color: #00ff00;
120
- # width: 97% }
121
- #
122
- # The second syntax for attributes is slightly different.
123
- # The colon is at the beginning of the attribute,
124
- # rather than between the name and the value,
125
- # so it's easier to tell what elements are attributes just by glancing at them.
126
- # For example:
127
- #
128
- # #main p
129
- # :color #00ff00
130
- # :width 97%
131
- #
132
- # is compiled to:
133
- #
134
- # #main p {
135
- # color: #00ff00;
136
- # width: 97% }
137
- #
138
- # By default, either attribute syntax may be used.
139
- # If you want to force one or the other,
140
- # see the <tt>:attribute_syntax</tt> option below.
141
- #
142
- # === Nested Rules
143
- #
144
- # Rules can also be nested within each other.
145
- # This signifies that the inner rule's selector is a child of the outer selector.
146
- # For example:
147
- #
148
- # #main p
149
- # :color #00ff00
150
- # :width 97%
151
- #
152
- # .redbox
153
- # :background-color #ff0000
154
- # :color #000000
155
- #
156
- # is compiled to:
157
- #
158
- # #main p {
159
- # color: #00ff00;
160
- # width: 97%; }
161
- # #main p .redbox {
162
- # background-color: #ff0000;
163
- # color: #000000; }
164
- #
165
- # This makes insanely complicated CSS layouts with lots of nested selectors very simple:
166
- #
167
- # #main
168
- # :width 97%
169
- #
170
- # p, div
171
- # :font-size 2em
172
- # a
173
- # :font-weight bold
174
- #
175
- # pre
176
- # :font-size 3em
177
- #
178
- # is compiled to:
179
- #
180
- # #main {
181
- # width: 97%; }
182
- # #main p, #main div {
183
- # font-size: 2em; }
184
- # #main p a, #main div a {
185
- # font-weight: bold; }
186
- # #main pre {
187
- # font-size: 3em; }
188
- #
189
- # === Referencing Parent Rules
190
- #
191
- # In addition to the default behavior of inserting the parent selector
192
- # as a CSS parent of the current selector
193
- # (e.g. above, "#main" is the parent of "p"),
194
- # you can have more fine-grained control over what's done with the parent selector
195
- # by using the ampersand character "&" in your selectors.
196
- #
197
- # The ampersand is automatically replaced by the parent selector,
198
- # instead of having it prepended.
199
- # This allows you to cleanly create pseudo-attributes:
200
- #
201
- # a
202
- # :font-weight bold
203
- # :text-decoration none
204
- # &:hover
205
- # :text-decoration underline
206
- # &:visited
207
- # :font-weight normal
208
- #
209
- # Which would become:
210
- #
211
- # a {
212
- # font-weight: bold;
213
- # text-decoration: none; }
214
- # a:hover {
215
- # text-decoration: underline; }
216
- # a:visited {
217
- # font-weight: normal; }
218
- #
219
- # It also allows you to add selectors at the base of the hierarchy,
220
- # which can be useuful for targeting certain styles to certain browsers:
221
- #
222
- # #main
223
- # :width 90%
224
- # #sidebar
225
- # :float left
226
- # :margin-left 20%
227
- # .ie6 &
228
- # :margin-left 40%
229
- #
230
- # Which would become:
231
- #
232
- # #main {
233
- # width: 90%; }
234
- # #main #sidebar {
235
- # float: left;
236
- # margin-left: 20%; }
237
- # .ie6 #main #sidebar {
238
- # margin-left: 40%; }
239
- #
240
- # === Attribute Namespaces
241
- #
242
- # CSS has quite a few attributes that are in "namespaces;"
243
- # for instance, "font-family," "font-size," and "font-weight"
244
- # are all in the "font" namespace.
245
- # In CSS, if you want to set a bunch of attributes in the same namespace,
246
- # you have to type it out each time.
247
- # Sass offers a shortcut for this:
248
- # just write the namespace one,
249
- # then indent each of the sub-attributes within it.
250
- # For example:
251
- #
252
- # .funky
253
- # :font
254
- # :family fantasy
255
- # :size 30em
256
- # :weight bold
257
- #
258
- # is compiled to:
259
- #
260
- # .funky {
261
- # font-family: fantasy;
262
- # font-size: 30em;
263
- # font-weight: bold; }
264
- #
265
- # === Rule Escaping
266
- #
267
- # In case, for whatever reason, you need to write a rule
268
- # that begins with a Sass-meaningful character,
269
- # you can escape it with a backslash (<tt>\</tt>).
270
- # For example:
271
- #
272
- # #main
273
- # \+div
274
- # clear: both
275
- #
276
- # is compiled to:
277
- #
278
- # #main +div {
279
- # clear: both; }
280
- #
281
- # == Constants
282
- #
283
- # Sass has support for setting document-wide constants.
284
- # They're set using an exclamation mark followed by the name,
285
- # an equals sign, and the value.
286
- # An attribute can then be set to the value of a constant
287
- # by following it with another equals sign.
288
- # For example:
289
- #
290
- # !main_color = #00ff00
291
- #
292
- # #main
293
- # :color = !main_color
294
- # :p
295
- # :background-color = !main_color
296
- # :color #000000
297
- #
298
- # is compiled to:
299
- #
300
- # #main {
301
- # color: #00ff00; }
302
- # #main p {
303
- # background-color: #00ff00;
304
- # color: #000000; }
305
- #
306
- # === Arithmetic
307
- #
308
- # You can even do basic arithmetic with constants.
309
- # Sass recognizes numbers, colors,
310
- # lengths (numbers with units),
311
- # and strings (everything that's not one of the above),
312
- # and various operators that work on various values.
313
- # All the normal arithmetic operators
314
- # (+, -, *, /, %, and parentheses for grouping)
315
- # are defined as usual
316
- # for numbers, colors, and lengths.
317
- # The "+" operator is also defined for Strings
318
- # as the concatenation operator.
319
- # For example:
320
- #
321
- # !main_width = 10
322
- # !unit1 = em
323
- # !unit2 = px
324
- # !bg_color = #a5f39e
325
- #
326
- # #main
327
- # :background-color = !bg_color
328
- # p
329
- # :background-color = !bg_color + #202020
330
- # :width = !main_width + !unit1
331
- # img.thumb
332
- # :width = (!main_width + 15) + !unit2
333
- #
334
- # is compiled to:
335
- #
336
- # #main {
337
- # background-color: #a5f39e; }
338
- # #main p {
339
- # background-color: #c5ffbe;
340
- # width: 10em; }
341
- # #main img.thumb {
342
- # width: 25em; }
343
- #
344
- # === Colors
345
- #
346
- # Colors may be written as three- or six-digit hex numbers prefixed
347
- # by a pound sign (#), or as HTML4 color names. For example,
348
- # "#ff0", "#ffff00" and "yellow" all refer to the same color.
349
- #
350
- # Not only can arithmetic be done between colors and other colors,
351
- # but it can be done between colors and normal numbers.
352
- # In this case, the operation is done piecewise one each of the
353
- # Red, Green, and Blue components of the color.
354
- # For example:
355
- #
356
- # !main_color = #a5f39e
357
- #
358
- # #main
359
- # :background-color = !main_color
360
- # p
361
- # :background-color = !main_color + 32
362
- #
363
- # is compiled to:
364
- #
365
- # #main {
366
- # background-color: #a5f39e; }
367
- # #main p {
368
- # background-color: #c5ffbe; }
369
- #
370
- # === Strings
371
- #
372
- # Strings are the type that's used by default
373
- # when an element in a bit of constant arithmetic isn't recognized
374
- # as another type of constant.
375
- # However, they can also be created explicitly be wrapping a section of code with quotation marks.
376
- # Inside the quotation marks,
377
- # a backslash can be used to
378
- # escape quotation marks that you want to appear in the CSS.
379
- # For example:
380
- #
381
- # !content = "Hello, \"Hubert\" Bean."
382
- #
383
- # #main
384
- # :content = "string(" + !content + ")"
385
- #
386
- # is compiled to:
387
- #
388
- # #main {
389
- # content: string(Hello, "Hubert" Bean.) }
390
- #
391
- # === Optional Assignment
392
- #
393
- # You can assign Sass constants if they aren't already assigned
394
- # using the ||= assignment operator.
395
- # This means that if the constant has already been assigned to,
396
- # it won't be re-assigned,
397
- # but if it doesn't have a value yet,
398
- # it will be given one.
399
- # For example:
400
- #
401
- # !content = "First content"
402
- # !content ||= "Second content?"
403
- #
404
- # #main
405
- # content = content
406
- #
407
- # is compiled to:
408
- #
409
- # #main {
410
- # content: First content; }
411
- #
412
- # However,
413
- #
414
- # !content ||= "Second content?"
415
- #
416
- # #main
417
- # content = content
418
- #
419
- # is compiled to:
420
- #
421
- # #main {
422
- # content: Second content?; }
423
- #
424
- # === Default Concatenation
425
- #
426
- # All those plusses and quotes for concatenating strings
427
- # can get pretty messy, though.
428
- # Most of the time, if you want to concatenate stuff,
429
- # you just want individual values with spaces in between them.
430
- # Thus, in Sass, when two values are next to each other without an operator,
431
- # they're simply joined with a space.
432
- # For example:
433
- #
434
- # !font_family = "sans-serif"
435
- # !main_font_size = 1em
436
- #
437
- # #main
438
- # :font
439
- # :family = !font_family
440
- # :size = !main_font_size
441
- # h6
442
- # :font = italic "small-caps" bold (!main_font_size + 0.1em) !font_family
443
- #
444
- # is compiled to:
445
- #
446
- # #main {
447
- # font-family: sans-serif;
448
- # font-size: 1em; }
449
- # #main h6 {
450
- # font: italic small-caps bold 1.1em sans-serif; }
451
- #
452
- # == Directives
453
- #
454
- # Directives allow the author to directly issue instructions to the Sass compiler.
455
- # They're prefixed with an at sign, "<tt>@</tt>",
456
- # followed by the name of the directive,
457
- # a space, and any arguments to it -
458
- # just like CSS directives.
459
- # For example:
460
- #
461
- # @import red.sass
462
- #
463
- # === Import
464
- #
465
- # Currently, the only directive is the "import" directive.
466
- # It works in a very similar way to the CSS import directive,
467
- # and sometimes compiles to a literal CSS "@import".
468
- #
469
- # Sass can import either other Sass files or plain CSS files.
470
- # If it imports a Sass file,
471
- # not only are the rules from that file included,
472
- # but all constants in that file are made available in the current file.
473
- #
474
- # Sass looks for other Sass files in the working directory,
475
- # and the Sass file directory under Rails or Merb.
476
- # Additional search directories may be specified
477
- # using the :load_paths option (see below).
478
- #
479
- # Sass can also import plain CSS files.
480
- # In this case, it doesn't literally include the content of the files;
481
- # rather, it uses the built-in CSS "@import" directive to tell the client program
482
- # to import the files.
483
- #
484
- # The import directive can take either a full filename
485
- # or a filename without an extension.
486
- # If an extension isn't provided,
487
- # Sass will try to find a Sass file with the given basename in the load paths,
488
- # and, failing that, will assume a relevant CSS file will be available.
489
- #
490
- # For example,
491
- #
492
- # @import foo.sass
493
- #
494
- # would compile to
495
- #
496
- # .foo
497
- # :color #f00
498
- #
499
- # whereas
500
- #
501
- # @import foo.css
502
- #
503
- # would compile to
504
- #
505
- # @import foo.css
506
- #
507
- # Finally,
508
- #
509
- # @import foo
510
- #
511
- # might compile to either,
512
- # depending on whether a file called "foo.sass" existed.
513
- #
514
- # === @font-face, @media, etc.
515
- #
516
- # Sass behaves as you'd expect for normal CSS @-directives.
517
- # For example:
518
- #
519
- # @font-face
520
- # font-family: "Bitstream Vera Sans"
521
- # src: url(http://foo.bar/bvs")
522
- #
523
- # compiles to:
524
- #
525
- # @font-face {
526
- # font-family: "Bitstream Vera Sans";
527
- # src: url(http://foo.bar/bvs"); }
528
- #
529
- # and
530
- #
531
- # @media print
532
- # #sidebar
533
- # display: none
534
- #
535
- # #main
536
- # background-color: white
537
- #
538
- # compiles to:
539
- #
540
- # @media print {
541
- # #sidebar {
542
- # display: none; }
543
- #
544
- # #main {
545
- # background-color: white; }
546
- # }
547
- #
548
- # == Comments
549
- #
550
- # === Silent Comments
551
- #
552
- # It's simple to add "silent" comments,
553
- # which don't output anything to the CSS document,
554
- # to a Sass document.
555
- # Simply use the familiar C-style notation for a one-line comment, "//",
556
- # at the normal indentation level and all text following it won't be output.
557
- # For example:
558
- #
559
- # // A very awesome rule.
560
- # #awesome.rule
561
- # // An equally awesome attribute.
562
- # :awesomeness very
563
- #
564
- # becomes
565
- #
566
- # #awesome.rule {
567
- # awesomeness: very; }
568
- #
569
- # You can also nest text beneath a comment to comment out a whole block.
570
- # For example:
571
- #
572
- # // A very awesome rule
573
- # #awesome.rule
574
- # // Don't use these attributes
575
- # color: green
576
- # font-size: 10em
577
- # color: red
578
- #
579
- # becomes
580
- #
581
- # #awesome.rule {
582
- # color: red; }
583
- #
584
- # === Loud Comments
585
- #
586
- # "Loud" comments are just as easy as silent ones.
587
- # These comments output to the document as CSS comments,
588
- # and thus use the same opening sequence: "/*".
589
- # For example:
590
- #
591
- # /* A very awesome rule.
592
- # #awesome.rule
593
- # /* An equally awesome attribute.
594
- # :awesomeness very
595
- #
596
- # becomes
597
- #
598
- # /* A very awesome rule. */
599
- # #awesome.rule {
600
- # /* An equally awesome attribute. */
601
- # awesomeness: very; }
602
- #
603
- # You can also nest content beneath loud comments. For example:
604
- #
605
- # #pbj
606
- # /* This rule describes
607
- # the styling of the element
608
- # that represents
609
- # a peanut butter and jelly sandwich.
610
- # :background-image url(/images/pbj.png)
611
- # :color red
612
- #
613
- # becomes
614
- #
615
- # #pbj {
616
- # /* This rule describes
617
- # * the styling of the element
618
- # * that represents
619
- # * a peanut butter and jelly sandwich. */
620
- # background-image: url(/images/pbj.png);
621
- # color: red; }
622
- #
623
- # == Mixins
624
- #
625
- # Mixins enable you to define groups of CSS attributes and
626
- # then include them inline in any number of selectors
627
- # throughout the document.
628
- #
629
- # === Defining a Mixin
630
- #
631
- # To define a mixin you use a slightly modified form of selector syntax.
632
- # For example the 'large-text' mixin is defined as follows:
633
- #
634
- # =large-text
635
- # :font
636
- # :family Arial
637
- # :size 20px
638
- # :weight bold
639
- # :color #ff0000
640
- #
641
- # The initial '=' marks this as a mixin rather than a standard selector.
642
- # The CSS rules that follow won't be included until the mixin is referenced later on.
643
- # Anything you can put into a standard selector,
644
- # you can put into a mixin definition. e.g.
645
- #
646
- # =clearfix
647
- # display: inline-block
648
- # &:after
649
- # content: "."
650
- # display: block
651
- # height: 0
652
- # clear: both
653
- # visibility: hidden
654
- # * html &
655
- # height: 1px
656
- #
657
- #
658
- # === Mixing it in
659
- #
660
- # Inlining a defined mixin is simple,
661
- # just prepend a '+' symbol to the name of a mixin defined earlier in the document.
662
- # So to inline the 'large-text' defined earlier,
663
- # we include the statment '+large-text' in our selector definition thus:
664
- #
665
- # .page-title
666
- # +large-text
667
- # :padding 4px
668
- # :margin
669
- # :top 10px
670
- #
671
- #
672
- # This will produce the following CSS output:
673
- #
674
- # .page-title {
675
- # font-family: Arial;
676
- # font-size: 20px;
677
- # font-weight: bold;
678
- # color: #ff0000;
679
- # padding: 4px;
680
- # margin-top: 10px;
681
- # }
682
- #
683
- # Any number of mixins may be defined and there is no limit on
684
- # the number that can be included in a particular selector.
685
- #
686
- # Mixin definitions can also include references to other mixins defined earlier in the file.
687
- # E.g.
688
- #
689
- # =highlighted-background
690
- # background:
691
- # color: #fc0
692
- # =header-text
693
- # font:
694
- # size: 20px
695
- #
696
- # =compound
697
- # +highlighted-background
698
- # +header-text
699
- #
700
- #
701
- # == Output Style
702
- #
703
- # Although the default CSS style that Sass outputs is very nice,
704
- # and reflects the structure of the document in a similar way that Sass does,
705
- # sometimes it's good to have other formats available.
706
- #
707
- # Sass allows you to choose between three different output styles
708
- # by setting the <tt>:style</tt> option.
709
- # In Rails, this is done by setting <tt>Sass::Plugin.options[:style]</tt>;
710
- # outside Rails, it's done by passing an options hash with </tt>:style</tt> set.
711
- #
712
- # === <tt>:nested</tt>
713
- #
714
- # Nested style is the default Sass style,
715
- # because it reflects the structure of the document
716
- # in much the same way Sass does.
717
- # Each attribute has its own line,
718
- # but the indentation isn't constant.
719
- # Each rule is indented based on how deeply it's nested.
720
- # For example:
721
- #
722
- # #main {
723
- # color: #fff;
724
- # background-color: #000; }
725
- # #main p {
726
- # width: 10em; }
727
- #
728
- # .huge {
729
- # font-size: 10em;
730
- # font-weight: bold;
731
- # text-decoration: underline; }
732
- #
733
- # Nested style is very useful when looking at large CSS files
734
- # for the same reason Sass is useful for making them:
735
- # it allows you to very easily grasp the structure of the file
736
- # without actually reading anything.
737
- #
738
- # === <tt>:expanded</tt>
739
- #
740
- # Expanded is the typical human-made CSS style,
741
- # with each attribute and rule taking up one line.
742
- # Attributes are indented within the rules,
743
- # but the rules aren't indented in any special way.
744
- # For example:
745
- #
746
- # #main {
747
- # color: #fff;
748
- # background-color: #000;
749
- # }
750
- # #main p {
751
- # width: 10em;
752
- # }
753
- #
754
- # .huge {
755
- # font-size: 10em;
756
- # font-weight: bold;
757
- # text-decoration: underline;
758
- # }
759
- #
760
- # === <tt>:compact</tt>
761
- #
762
- # Compact style, as the name would imply,
763
- # takes up less space than Nested or Expanded.
764
- # However, it's also harder to read.
765
- # Each CSS rule takes up only one line,
766
- # with every attribute defined on that line.
767
- # Nested rules are placed next to each other with no newline,
768
- # while groups of rules have newlines between them.
769
- # For example:
770
- #
771
- # #main { color: #fff; background-color: #000; }
772
- # #main p { width: 10em; }
773
- #
774
- # .huge { font-size: 10em; font-weight: bold; text-decoration: underline; }
775
- #
776
- # === <tt>:compressed</tt>
777
- #
778
- # Compressed style takes up the minimum amount of space possible,
779
- # having no whitespace except that necessary to separate selectors
780
- # and a newline at the end of the file.
781
- # It's not meant to be human-readable.
782
- # For example:
783
- #
784
- # #main{color:#fff;background-color:#000}#main p{width:10em}.huge{font-size:10em;font-weight:bold;text-decoration:underline}
785
- #
786
- # == Sass Options
787
- #
788
- # Options can be set by setting the <tt>Sass::Plugin.options</tt> hash
789
- # in <tt>environment.rb</tt> in Rails...
790
- #
791
- # Sass::Plugin.options[:style] = :compact
792
- #
793
- # ...or by setting the <tt>Merb::Plugin.config[:sass]</tt> hash in <tt>init.rb</tt> in Merb...
794
- #
795
- # Merb::Plugin.config[:sass][:style] = :compact
796
- #
797
- # ...or by passing an options hash to Sass::Engine.new.
798
- # Available options are:
799
- #
800
- # [<tt>:style</tt>] Sets the style of the CSS output.
801
- # See the section on Output Style, above.
802
- #
803
- # [<tt>:attribute_syntax</tt>] Forces the document to use one syntax for attributes.
804
- # If the correct syntax isn't used, an error is thrown.
805
- # <tt>:normal</tt> forces the use of a colon
806
- # before the attribute name.
807
- # For example: <tt>:color #0f3</tt>
808
- # or <tt>:width = !main_width</tt>.
809
- # <tt>:alternate</tt> forces the use of a colon or equals sign
810
- # after the attribute name.
811
- # For example: <tt>color: #0f3</tt>
812
- # or <tt>width = !main_width</tt>.
813
- # By default, either syntax is valid.
814
- #
815
- # [<tt>:never_update</tt>] Whether the CSS files should never be updated,
816
- # even if the template file changes.
817
- # Setting this to true may give small performance gains.
818
- # It always defaults to false.
819
- # Only has meaning within Ruby on Rails or Merb.
820
- #
821
- # [<tt>:always_update</tt>] Whether the CSS files should be updated every
822
- # time a controller is accessed,
823
- # as opposed to only when the template has been modified.
824
- # Defaults to false.
825
- # Only has meaning within Ruby on Rails or Merb.
826
- #
827
- # [<tt>:always_check</tt>] Whether a Sass template should be checked for updates every
828
- # time a controller is accessed,
829
- # as opposed to only when the Rails server starts.
830
- # If a Sass template has been updated,
831
- # it will be recompiled and will overwrite the corresponding CSS file.
832
- # Defaults to false in production mode, true otherwise.
833
- # Only has meaning within Ruby on Rails or Merb.
834
- #
835
- # [<tt>:full_exception</tt>] Whether an error in the Sass code
836
- # should cause Sass to provide a detailed description.
837
- # If set to true, the specific error will be displayed
838
- # along with a line number and source snippet.
839
- # Otherwise, a simple uninformative error message will be displayed.
840
- # Defaults to false in production mode, true otherwise.
841
- # Only has meaning within Ruby on Rails or Merb.
842
- #
843
- # [<tt>:template_location</tt>] The directory where Sass templates should be read from.
844
- # Defaults to <tt>RAILS_ROOT + "/public/stylesheets/sass"</tt>
845
- # or <tt>MERB_ROOT + "/public/stylesheets/sass"</tt>.
846
- # Only has meaning within Ruby on Rails or Merb.
847
- #
848
- # [<tt>:css_location</tt>] The directory where CSS output should be written to.
849
- # Defaults to <tt>RAILS_ROOT + "/public/stylesheets"</tt>
850
- # or <tt>MERB_ROOT + "/public/stylesheets"</tt>.
851
- # Only has meaning within Ruby on Rails or Merb.
852
- #
853
- # [<tt>:filename</tt>] The filename of the file being rendered.
854
- # This is used solely for reporting errors,
855
- # and is automatically set when using Rails or Merb.
856
- #
857
- # [<tt>:load_paths</tt>] An array of filesystem paths which should be searched
858
- # for Sass templates imported with the "@import" directive.
859
- # This defaults to the working directory and, in Rails or Merb,
860
- # whatever <tt>:template_location</tt> is.
8
+ # * {Sass::Engine} is the class used to render Sass within Ruby code.
9
+ # * {Sass::Plugin} is interfaces with web frameworks (Rails and Merb in particular).
10
+ # * {Sass::SyntaxError} is raised when Sass encounters an error.
11
+ # * {Sass::CSS} handles conversion of CSS to Sass.
861
12
  #
13
+ # Also see the {file:SASS_REFERENCE.md full Sass reference}.
862
14
  module Sass
863
15
  extend Haml::Version
864
16
 
865
17
  # A string representing the version of Sass.
866
- # A more fine-grained representation is available from Sass.version.
18
+ # A more fine-grained representation is available from {Sass.version}.
867
19
  VERSION = version[:string] unless defined?(Sass::VERSION)
868
-
869
20
  end
870
21
 
871
22
  require 'haml/util'