haml 3.0.21 → 3.0.22

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 (195) hide show
  1. data/Rakefile +1 -41
  2. data/VERSION +1 -1
  3. data/lib/haml/precompiler.rb +8 -6
  4. data/lib/haml/template/plugin.rb +16 -6
  5. data/lib/sass/less.rb +31 -12
  6. data/lib/sass/script/funcall.rb +2 -1
  7. data/lib/sass/script/operation.rb +10 -5
  8. data/lib/sass/script/parser.rb +9 -0
  9. data/test/haml/engine_test.rb +25 -0
  10. data/test/sass/less_conversion_test.rb +24 -3
  11. data/test/sass/script_conversion_test.rb +60 -0
  12. metadata +243 -426
  13. data/vendor/sass/CONTRIBUTING +0 -3
  14. data/vendor/sass/MIT-LICENSE +0 -20
  15. data/vendor/sass/README.md +0 -201
  16. data/vendor/sass/Rakefile +0 -363
  17. data/vendor/sass/TODO +0 -39
  18. data/vendor/sass/VERSION +0 -1
  19. data/vendor/sass/VERSION_NAME +0 -1
  20. data/vendor/sass/bin/css2sass +0 -13
  21. data/vendor/sass/bin/sass +0 -8
  22. data/vendor/sass/bin/sass-convert +0 -7
  23. data/vendor/sass/doc-src/FAQ.md +0 -35
  24. data/vendor/sass/doc-src/INDENTED_SYNTAX.md +0 -210
  25. data/vendor/sass/doc-src/SASS_CHANGELOG.md +0 -1870
  26. data/vendor/sass/doc-src/SASS_REFERENCE.md +0 -1713
  27. data/vendor/sass/doc-src/SCSS_FOR_SASS_USERS.md +0 -155
  28. data/vendor/sass/ext/extconf.rb +0 -10
  29. data/vendor/sass/extra/update_watch.rb +0 -13
  30. data/vendor/sass/init.rb +0 -18
  31. data/vendor/sass/lib/sass.rb +0 -71
  32. data/vendor/sass/lib/sass/cache_store.rb +0 -208
  33. data/vendor/sass/lib/sass/callbacks.rb +0 -66
  34. data/vendor/sass/lib/sass/css.rb +0 -294
  35. data/vendor/sass/lib/sass/engine.rb +0 -792
  36. data/vendor/sass/lib/sass/environment.rb +0 -143
  37. data/vendor/sass/lib/sass/error.rb +0 -201
  38. data/vendor/sass/lib/sass/exec.rb +0 -619
  39. data/vendor/sass/lib/sass/importers.rb +0 -22
  40. data/vendor/sass/lib/sass/importers/base.rb +0 -138
  41. data/vendor/sass/lib/sass/importers/filesystem.rb +0 -121
  42. data/vendor/sass/lib/sass/less.rb +0 -363
  43. data/vendor/sass/lib/sass/plugin.rb +0 -126
  44. data/vendor/sass/lib/sass/plugin/compiler.rb +0 -346
  45. data/vendor/sass/lib/sass/plugin/configuration.rb +0 -123
  46. data/vendor/sass/lib/sass/plugin/generic.rb +0 -15
  47. data/vendor/sass/lib/sass/plugin/merb.rb +0 -48
  48. data/vendor/sass/lib/sass/plugin/rack.rb +0 -47
  49. data/vendor/sass/lib/sass/plugin/rails.rb +0 -41
  50. data/vendor/sass/lib/sass/plugin/staleness_checker.rb +0 -145
  51. data/vendor/sass/lib/sass/railtie.rb +0 -8
  52. data/vendor/sass/lib/sass/repl.rb +0 -58
  53. data/vendor/sass/lib/sass/root.rb +0 -7
  54. data/vendor/sass/lib/sass/script.rb +0 -63
  55. data/vendor/sass/lib/sass/script/bool.rb +0 -18
  56. data/vendor/sass/lib/sass/script/color.rb +0 -491
  57. data/vendor/sass/lib/sass/script/css_lexer.rb +0 -29
  58. data/vendor/sass/lib/sass/script/css_parser.rb +0 -31
  59. data/vendor/sass/lib/sass/script/funcall.rb +0 -79
  60. data/vendor/sass/lib/sass/script/functions.rb +0 -852
  61. data/vendor/sass/lib/sass/script/interpolation.rb +0 -70
  62. data/vendor/sass/lib/sass/script/lexer.rb +0 -337
  63. data/vendor/sass/lib/sass/script/literal.rb +0 -236
  64. data/vendor/sass/lib/sass/script/node.rb +0 -101
  65. data/vendor/sass/lib/sass/script/number.rb +0 -423
  66. data/vendor/sass/lib/sass/script/operation.rb +0 -92
  67. data/vendor/sass/lib/sass/script/parser.rb +0 -392
  68. data/vendor/sass/lib/sass/script/string.rb +0 -67
  69. data/vendor/sass/lib/sass/script/string_interpolation.rb +0 -93
  70. data/vendor/sass/lib/sass/script/unary_operation.rb +0 -57
  71. data/vendor/sass/lib/sass/script/variable.rb +0 -48
  72. data/vendor/sass/lib/sass/scss.rb +0 -17
  73. data/vendor/sass/lib/sass/scss/css_parser.rb +0 -51
  74. data/vendor/sass/lib/sass/scss/parser.rb +0 -838
  75. data/vendor/sass/lib/sass/scss/rx.rb +0 -126
  76. data/vendor/sass/lib/sass/scss/sass_parser.rb +0 -11
  77. data/vendor/sass/lib/sass/scss/script_lexer.rb +0 -15
  78. data/vendor/sass/lib/sass/scss/script_parser.rb +0 -25
  79. data/vendor/sass/lib/sass/scss/static_parser.rb +0 -40
  80. data/vendor/sass/lib/sass/selector.rb +0 -361
  81. data/vendor/sass/lib/sass/selector/abstract_sequence.rb +0 -62
  82. data/vendor/sass/lib/sass/selector/comma_sequence.rb +0 -82
  83. data/vendor/sass/lib/sass/selector/sequence.rb +0 -236
  84. data/vendor/sass/lib/sass/selector/simple.rb +0 -113
  85. data/vendor/sass/lib/sass/selector/simple_sequence.rb +0 -135
  86. data/vendor/sass/lib/sass/shared.rb +0 -78
  87. data/vendor/sass/lib/sass/tree/comment_node.rb +0 -128
  88. data/vendor/sass/lib/sass/tree/debug_node.rb +0 -36
  89. data/vendor/sass/lib/sass/tree/directive_node.rb +0 -75
  90. data/vendor/sass/lib/sass/tree/extend_node.rb +0 -65
  91. data/vendor/sass/lib/sass/tree/for_node.rb +0 -67
  92. data/vendor/sass/lib/sass/tree/if_node.rb +0 -81
  93. data/vendor/sass/lib/sass/tree/import_node.rb +0 -124
  94. data/vendor/sass/lib/sass/tree/mixin_def_node.rb +0 -60
  95. data/vendor/sass/lib/sass/tree/mixin_node.rb +0 -123
  96. data/vendor/sass/lib/sass/tree/node.rb +0 -490
  97. data/vendor/sass/lib/sass/tree/prop_node.rb +0 -220
  98. data/vendor/sass/lib/sass/tree/root_node.rb +0 -125
  99. data/vendor/sass/lib/sass/tree/rule_node.rb +0 -273
  100. data/vendor/sass/lib/sass/tree/variable_node.rb +0 -39
  101. data/vendor/sass/lib/sass/tree/warn_node.rb +0 -42
  102. data/vendor/sass/lib/sass/tree/while_node.rb +0 -48
  103. data/vendor/sass/lib/sass/util.rb +0 -700
  104. data/vendor/sass/lib/sass/util/subset_map.rb +0 -101
  105. data/vendor/sass/lib/sass/version.rb +0 -109
  106. data/vendor/sass/rails/init.rb +0 -1
  107. data/vendor/sass/sass.gemspec +0 -32
  108. data/vendor/sass/test/sass/cache_test.rb +0 -74
  109. data/vendor/sass/test/sass/callbacks_test.rb +0 -61
  110. data/vendor/sass/test/sass/conversion_test.rb +0 -1210
  111. data/vendor/sass/test/sass/css2sass_test.rb +0 -364
  112. data/vendor/sass/test/sass/data/hsl-rgb.txt +0 -319
  113. data/vendor/sass/test/sass/engine_test.rb +0 -2283
  114. data/vendor/sass/test/sass/extend_test.rb +0 -1348
  115. data/vendor/sass/test/sass/functions_test.rb +0 -565
  116. data/vendor/sass/test/sass/importer_test.rb +0 -104
  117. data/vendor/sass/test/sass/less_conversion_test.rb +0 -632
  118. data/vendor/sass/test/sass/mock_importer.rb +0 -49
  119. data/vendor/sass/test/sass/more_results/more1.css +0 -9
  120. data/vendor/sass/test/sass/more_results/more1_with_line_comments.css +0 -26
  121. data/vendor/sass/test/sass/more_results/more_import.css +0 -29
  122. data/vendor/sass/test/sass/more_templates/_more_partial.sass +0 -2
  123. data/vendor/sass/test/sass/more_templates/more1.sass +0 -23
  124. data/vendor/sass/test/sass/more_templates/more_import.sass +0 -11
  125. data/vendor/sass/test/sass/plugin_test.rb +0 -430
  126. data/vendor/sass/test/sass/results/alt.css +0 -4
  127. data/vendor/sass/test/sass/results/basic.css +0 -9
  128. data/vendor/sass/test/sass/results/compact.css +0 -5
  129. data/vendor/sass/test/sass/results/complex.css +0 -86
  130. data/vendor/sass/test/sass/results/compressed.css +0 -1
  131. data/vendor/sass/test/sass/results/expanded.css +0 -19
  132. data/vendor/sass/test/sass/results/import.css +0 -31
  133. data/vendor/sass/test/sass/results/line_numbers.css +0 -49
  134. data/vendor/sass/test/sass/results/mixins.css +0 -95
  135. data/vendor/sass/test/sass/results/multiline.css +0 -24
  136. data/vendor/sass/test/sass/results/nested.css +0 -22
  137. data/vendor/sass/test/sass/results/options.css +0 -1
  138. data/vendor/sass/test/sass/results/parent_ref.css +0 -13
  139. data/vendor/sass/test/sass/results/script.css +0 -16
  140. data/vendor/sass/test/sass/results/scss_import.css +0 -31
  141. data/vendor/sass/test/sass/results/scss_importee.css +0 -2
  142. data/vendor/sass/test/sass/results/subdir/nested_subdir/nested_subdir.css +0 -1
  143. data/vendor/sass/test/sass/results/subdir/subdir.css +0 -3
  144. data/vendor/sass/test/sass/results/units.css +0 -11
  145. data/vendor/sass/test/sass/results/warn.css +0 -0
  146. data/vendor/sass/test/sass/results/warn_imported.css +0 -0
  147. data/vendor/sass/test/sass/script_conversion_test.rb +0 -254
  148. data/vendor/sass/test/sass/script_test.rb +0 -470
  149. data/vendor/sass/test/sass/scss/css_test.rb +0 -897
  150. data/vendor/sass/test/sass/scss/rx_test.rb +0 -156
  151. data/vendor/sass/test/sass/scss/scss_test.rb +0 -1088
  152. data/vendor/sass/test/sass/scss/test_helper.rb +0 -37
  153. data/vendor/sass/test/sass/templates/_partial.sass +0 -2
  154. data/vendor/sass/test/sass/templates/alt.sass +0 -16
  155. data/vendor/sass/test/sass/templates/basic.sass +0 -23
  156. data/vendor/sass/test/sass/templates/bork1.sass +0 -2
  157. data/vendor/sass/test/sass/templates/bork2.sass +0 -2
  158. data/vendor/sass/test/sass/templates/bork3.sass +0 -2
  159. data/vendor/sass/test/sass/templates/bork4.sass +0 -2
  160. data/vendor/sass/test/sass/templates/compact.sass +0 -17
  161. data/vendor/sass/test/sass/templates/complex.sass +0 -305
  162. data/vendor/sass/test/sass/templates/compressed.sass +0 -15
  163. data/vendor/sass/test/sass/templates/expanded.sass +0 -17
  164. data/vendor/sass/test/sass/templates/import.sass +0 -12
  165. data/vendor/sass/test/sass/templates/importee.less +0 -2
  166. data/vendor/sass/test/sass/templates/importee.sass +0 -19
  167. data/vendor/sass/test/sass/templates/line_numbers.sass +0 -13
  168. data/vendor/sass/test/sass/templates/mixin_bork.sass +0 -5
  169. data/vendor/sass/test/sass/templates/mixins.sass +0 -76
  170. data/vendor/sass/test/sass/templates/multiline.sass +0 -20
  171. data/vendor/sass/test/sass/templates/nested.sass +0 -25
  172. data/vendor/sass/test/sass/templates/nested_bork1.sass +0 -2
  173. data/vendor/sass/test/sass/templates/nested_bork2.sass +0 -2
  174. data/vendor/sass/test/sass/templates/nested_bork3.sass +0 -2
  175. data/vendor/sass/test/sass/templates/nested_bork4.sass +0 -2
  176. data/vendor/sass/test/sass/templates/nested_mixin_bork.sass +0 -6
  177. data/vendor/sass/test/sass/templates/options.sass +0 -2
  178. data/vendor/sass/test/sass/templates/parent_ref.sass +0 -25
  179. data/vendor/sass/test/sass/templates/script.sass +0 -101
  180. data/vendor/sass/test/sass/templates/scss_import.scss +0 -11
  181. data/vendor/sass/test/sass/templates/scss_importee.scss +0 -1
  182. data/vendor/sass/test/sass/templates/subdir/nested_subdir/_nested_partial.sass +0 -2
  183. data/vendor/sass/test/sass/templates/subdir/nested_subdir/nested_subdir.sass +0 -3
  184. data/vendor/sass/test/sass/templates/subdir/subdir.sass +0 -6
  185. data/vendor/sass/test/sass/templates/units.sass +0 -11
  186. data/vendor/sass/test/sass/templates/warn.sass +0 -3
  187. data/vendor/sass/test/sass/templates/warn_imported.sass +0 -4
  188. data/vendor/sass/test/sass/test_helper.rb +0 -8
  189. data/vendor/sass/test/sass/util/subset_map_test.rb +0 -91
  190. data/vendor/sass/test/sass/util_test.rb +0 -275
  191. data/vendor/sass/test/test_helper.rb +0 -64
  192. data/vendor/sass/yard/callbacks.rb +0 -29
  193. data/vendor/sass/yard/default/fulldoc/html/css/common.sass +0 -26
  194. data/vendor/sass/yard/default/layout/html/footer.erb +0 -12
  195. data/vendor/sass/yard/inherited_hash.rb +0 -41
@@ -1,1713 +0,0 @@
1
- # Sass (Syntactically Awesome StyleSheets)
2
-
3
- * Table of contents
4
- {:toc}
5
-
6
- Sass is an extension of CSS
7
- that adds power and elegance to the basic language.
8
- It allows you to use [variables](#variables_), [nested rules](#nested_rules),
9
- [mixins](#mixins), [inline imports](#import), and more,
10
- all with a fully CSS-compatible syntax.
11
- Sass helps keep large stylesheets well-organized,
12
- and get small stylesheets up and running quickly,
13
- particularly with the help of
14
- [the Compass style library](http://compass-style.org).
15
-
16
- ## Features
17
-
18
- * Fully CSS3-compatible
19
- * Language extensions such as variables, nesting, and mixins
20
- * Many {Sass::Script::Functions useful functions} for manipulating colors and other values
21
- * Advanced features like [control directives](#control_directives) for libraries
22
- * Well-formatted, customizable output
23
- * [Firebug integration](https://addons.mozilla.org/en-US/firefox/addon/103988)
24
-
25
- ## Syntax
26
-
27
- There are two syntaxes available for Sass.
28
- The first, known as SCSS (Sassy CSS) and used throughout this reference,
29
- is an extension of the syntax of CSS3.
30
- This means that every valid CSS3 stylesheet
31
- is a valid SCSS file with the same meaning.
32
- In addition, SCSS understands most CSS hacks
33
- and vendor-specific syntax, such as [IE's old `filter` syntax](http://msdn.microsoft.com/en-us/library/ms533754%28VS.85%29.aspx).
34
- This syntax is enhanced with the Sass features described below.
35
- Files using this syntax have the `.scss` extension.
36
-
37
- The second and older syntax, known as the indented syntax (or sometimes just "Sass"),
38
- provides a more concise way of writing CSS.
39
- It uses indentation rather than brackets to indicate nesting of selectors,
40
- and newlines rather than semicolons to separate properties.
41
- Some people find this to be easier to read and quicker to write than SCSS.
42
- The indented syntax has all the same features,
43
- although some of them have slightly different syntax;
44
- this is described in {file:INDENTED_SYNTAX.md the indented syntax reference}.
45
- Files using this syntax have the `.sass` extension.
46
-
47
- Either syntax can [import](#import) files written in the other.
48
- Files can be automatically converted from one syntax to the other
49
- using the `sass-convert` command line tool:
50
-
51
- # Convert Sass to SCSS
52
- $ sass-convert style.sass style.scss
53
-
54
- # Convert SCSS to Sass
55
- $ sass-convert style.scss style.sass
56
-
57
- ## Using Sass
58
-
59
- Sass can be used in three ways:
60
- as a command-line tool,
61
- as a standalone Ruby module,
62
- and as a plugin for any Rack-enabled framework,
63
- including Ruby on Rails and Merb.
64
- The first step for all of these is to install the Sass gem:
65
-
66
- gem install sass
67
-
68
- If you're using Windows,
69
- you may need to [install Ruby](http://rubyinstaller.org/download.html) first.
70
-
71
- To run Sass from the command line, just use
72
-
73
- sass input.scss output.css
74
-
75
- You can also tell Sass to watch the file and update the CSS
76
- every time the Sass file changes:
77
-
78
- sass --watch input.scss:output.css
79
-
80
- If you have a directory with many Sass files,
81
- you can also tell Sass to watch the entire directory:
82
-
83
- sass --watch app/sass:public/stylesheets
84
-
85
- Use `sass --help` for full documentation.
86
-
87
- Using Sass in Ruby code is very simple.
88
- After installing the Sass gem,
89
- you can use it by running `require "sass"`
90
- and using {Sass::Engine} like so:
91
-
92
- engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss)
93
- engine.render #=> "#main { background-color: #0000ff; }\n"
94
-
95
- ### Rack/Rails/Merb Plugin
96
-
97
- To enable Sass in Rails versions before Rails 3,
98
- add the following line to `environment.rb`:
99
-
100
- config.gem "sass"
101
-
102
- For Rails 3, instead add the following line to the Gemfile:
103
-
104
- gem "sass"
105
-
106
- To enable Sass in Merb,
107
- add the following line to `config/dependencies.rb`:
108
-
109
- dependency "merb-haml"
110
-
111
- To enable Sass in a Rack application,
112
- add
113
-
114
- require 'sass/plugin/rack'
115
- use Sass::Plugin::Rack
116
-
117
- to `config.ru`.
118
-
119
- Sass stylesheets don't work the same as views.
120
- They don't contain dynamic content,
121
- so the CSS only needs to be generated when the Sass file has been updated.
122
- By default, `.sass` and `.scss` files are placed in public/stylesheets/sass
123
- (this can be customized with the [`:template_location`](#template_location-option) option).
124
- Then, whenever necessary, they're compiled into corresponding CSS files in public/stylesheets.
125
- For instance, public/stylesheets/sass/main.scss would be compiled to public/stylesheets/main.css.
126
-
127
- ### Caching
128
-
129
- By default, Sass caches compiled templates and [partials](#partials).
130
- This dramatically speeds up re-compilation of large collections of Sass files,
131
- and works best if the Sass templates are split up into separate files
132
- that are all [`@import`](#import)ed into one large file.
133
-
134
- Without a framework, Sass puts the cached templates in the `.sass-cache` directory.
135
- In Rails and Merb, they go in `tmp/sass-cache`.
136
- The directory can be customized with the [`:cache_location`](#cache_location-option) option.
137
- If you don't want Sass to use caching at all,
138
- set the [`:cache`](#cache-option) option to `false`.
139
-
140
- ### Options
141
-
142
- Options can be set by setting the {Sass::Plugin::Configuration#options Sass::Plugin#options} hash
143
- in `environment.rb` in Rails or `config.ru` in Rack...
144
-
145
- Sass::Plugin.options[:style] = :compact
146
-
147
- ...or by setting the `Merb::Plugin.config[:sass]` hash in `init.rb` in Merb...
148
-
149
- Merb::Plugin.config[:sass][:style] = :compact
150
-
151
- ...or by passing an options hash to {Sass::Engine#initialize}.
152
- All relevant options are also available via flags
153
- to the `sass` command-line executable.
154
- Available options are:
155
-
156
- {#style-option} `:style`
157
- : Sets the style of the CSS output.
158
- See [Output Style](#output_style).
159
-
160
- {#syntax-option} `:syntax`
161
- : The syntax of the input file, `:sass` for the indented syntax
162
- and `:scss` for the CSS-extension syntax.
163
- This is only useful when you're constructing {Sass::Engine} instances yourself;
164
- it's automatically set properly when using {Sass::Plugin}.
165
- Defaults to `:sass`.
166
-
167
- {#property_syntax-option} `:property_syntax`
168
- : Forces indented-syntax documents to use one syntax for properties.
169
- If the correct syntax isn't used, an error is thrown.
170
- `:new` forces the use of a colon or equals sign
171
- after the property name.
172
- For example: `color: #0f3`
173
- or `width: $main_width`.
174
- `:old` forces the use of a colon
175
- before the property name.
176
- For example: `:color #0f3`
177
- or `:width $main_width`.
178
- By default, either syntax is valid.
179
- This has no effect on SCSS documents.
180
-
181
- {#cache-option} `:cache`
182
- : Whether parsed Sass files should be cached,
183
- allowing greater speed. Defaults to true.
184
-
185
- {#read_cache-option} `:read_cache`
186
- : If this is set and `:cache` is not,
187
- only read the Sass cache if it exists,
188
- don't write to it if it doesn't.
189
-
190
- {#cache_store-option} `:cache_store`
191
- : If this is set to an instance of a subclass of {Sass::CacheStore},
192
- that cache store will be used to store and retrieve
193
- cached compilation results.
194
- Defaults to a {Sass::FileCacheStore} that is
195
- initialized using the [`:cache_location` option](#cache_location-option).
196
-
197
- {#never_update-option} `:never_update`
198
- : Whether the CSS files should never be updated,
199
- even if the template file changes.
200
- Setting this to true may give small performance gains.
201
- It always defaults to false.
202
- Only has meaning within Rack, Ruby on Rails, or Merb.
203
-
204
- {#always_update-option} `:always_update`
205
- : Whether the CSS files should be updated every
206
- time a controller is accessed,
207
- as opposed to only when the template has been modified.
208
- Defaults to false.
209
- Only has meaning within Rack, Ruby on Rails, or Merb.
210
-
211
- {#always_check-option} `:always_check`
212
- : Whether a Sass template should be checked for updates every
213
- time a controller is accessed,
214
- as opposed to only when the server starts.
215
- If a Sass template has been updated,
216
- it will be recompiled and will overwrite the corresponding CSS file.
217
- Defaults to false in production mode, true otherwise.
218
- Only has meaning within Rack, Ruby on Rails, or Merb.
219
-
220
- {#full_exception-option} `:full_exception`
221
- : Whether an error in the Sass code
222
- should cause Sass to provide a detailed description
223
- within the generated CSS file.
224
- If set to true, the error will be displayed
225
- along with a line number and source snippet
226
- both as a comment in the CSS file
227
- and at the top of the page (in supported browsers).
228
- Otherwise, an exception will be raised in the Ruby code.
229
- Defaults to false in production mode, true otherwise.
230
- Only has meaning within Rack, Ruby on Rails, or Merb.
231
-
232
- {#template_location-option} `:template_location`
233
- : A path to the root sass template directory for your application.
234
- If a hash, `:css_location` is ignored and this option designates
235
- a mapping between input and output directories.
236
- May also be given a list of 2-element lists, instead of a hash.
237
- Defaults to `css_location + "/sass"`.
238
- Only has meaning within Rack, Ruby on Rails, or Merb.
239
- Note that if multiple template locations are specified, all
240
- of them are placed in the import path, allowing you to import
241
- between them.
242
- **Note that due to the many possible formats it can take,
243
- this option should only be set directly, not accessed or modified.
244
- Use the {Sass::Plugin::Configuration#template_location_array Sass::Plugin#template_location_array},
245
- {Sass::Plugin::Configuration#add_template_location Sass::Plugin#add_template_location},
246
- and {Sass::Plugin::Configuration#remove_template_location Sass::Plugin#remove_template_location} methods instead**.
247
-
248
- {#css_location-option} `:css_location`
249
- : The path where CSS output should be written to.
250
- This option is ignored when `:template_location` is a Hash.
251
- Defaults to `"./public/stylesheets"`.
252
- Only has meaning within Rack, Ruby on Rails, or Merb.
253
-
254
- {#cache_location-option} `:cache_location`
255
- : The path where the cached `sassc` files should be written to.
256
- Defaults to `"./tmp/sass-cache"` in Rails and Merb,
257
- or `"./.sass-cache"` otherwise.
258
- If the [`:cache_store` option](#cache_location-option) is set,
259
- this is ignored.
260
-
261
- {#unix_newlines-option} `:unix_newlines`
262
- : If true, use Unix-style newlines when writing files.
263
- Only has meaning on Windows, and only when Sass is writing the files
264
- (in Rack, Rails, or Merb, when using {Sass::Plugin} directly,
265
- or when using the command-line executable).
266
-
267
- {#filename-option} `:filename`
268
- : The filename of the file being rendered.
269
- This is used solely for reporting errors,
270
- and is automatically set when using Rack, Rails, or Merb.
271
-
272
- {#line-option} `:line`
273
- : The number of the first line of the Sass template.
274
- Used for reporting line numbers for errors.
275
- This is useful to set if the Sass template is embedded in a Ruby file.
276
-
277
- {#load_paths-option} `:load_paths`
278
- : An array of filesystem paths which should be searched
279
- for Sass templates imported with the [`@import`](#import) directive.
280
- This defaults to the working directory and, in Rack, Rails, or Merb,
281
- whatever `:template_location` is.
282
-
283
- {#filesystem_importer-option} `:filesystem_importer`
284
- : A {Sass::Importers::Base} subclass used to handle plain string load paths.
285
- This should import files from the filesystem.
286
- It should be a Class object inheriting from {Sass::Importers::Base}
287
- with a constructor that takes a single string argument (the load path).
288
- Defaults to {Sass::Importers::Filesystem}.
289
-
290
- {#line_numbers-option} `:line_numbers`
291
- : When set to true, causes the line number and file
292
- where a selector is defined to be emitted into the compiled CSS
293
- as a comment. Useful for debugging, especially when using imports
294
- and mixins.
295
- This option may also be called `:line_comments`.
296
- Automatically disabled when using the `:compressed` output style
297
- or the `:debug_info` option.
298
-
299
- {#debug_info-option} `:debug_info`
300
- : When set to true, causes the line number and file
301
- where a selector is defined to be emitted into the compiled CSS
302
- in a format that can be understood by the browser.
303
- Useful in conjunction with [the FireSass Firebug extension](https://addons.mozilla.org/en-US/firefox/addon/103988)
304
- for displaying the Sass filename and line number.
305
- Automatically disabled when using the `:compressed` output style.
306
-
307
- {#custom-option} `:custom`
308
- : An option that's available for individual applications to set
309
- to make data available to {Sass::Script::Functions custom Sass functions}.
310
-
311
- {#sass2-option} `:sass2`
312
- : Parses the document using semantics closer to that of Sass v2.
313
- Currently, this just means that strings in mixin arguments
314
- are treated as though they were in [an `=` context](#sass-script-strings).
315
-
316
- {#quiet-option} `:quiet`
317
- : When set to true, causes warnings to be disabled.
318
-
319
- ### Encodings
320
-
321
- When running on Ruby 1.9 and later, Sass is aware of the character encoding of documents
322
- and will handle them the same way that CSS would.
323
- By default, Sass assumes that all stylesheets are encoded
324
- using whatever coding system your operating system defaults to.
325
- For many users this will be `UTF-8`, the de facto standard for the web.
326
- For some users, though, it may be a more local encoding.
327
-
328
- If you want to use a different encoding for your stylesheet
329
- than your operating system default,
330
- you can use the `@charset` declaration just like in CSS.
331
- Add `@charset "encoding-name";` at the beginning of the stylesheet
332
- (before any whitespace or comments)
333
- and Sass will interpret it as the given encoding.
334
- Note that whatever encoding you use, it must be convertible to Unicode.
335
-
336
- Sass will also respect any Unicode BOMs and non-ASCII-compatible Unicode encodings
337
- [as specified by the CSS spec](http://www.w3.org/TR/CSS2/syndata.html#charset),
338
- although this is *not* the recommended way
339
- to specify the character set for a document.
340
- Note that Sass does not support the obscure `UTF-32-2143`,
341
- `UTF-32-3412`, `EBCDIC`, `IBM1026`, and `GSM 03.38` encodings,
342
- since Ruby does not have support for them
343
- and they're highly unlikely to ever be used in practice.
344
-
345
- ## CSS Extensions
346
-
347
- ### Nested Rules
348
-
349
- Sass allows CSS rules to be nested within one another.
350
- The inner rule then only applies within the outer rule's selector.
351
- For example:
352
-
353
- #main p {
354
- color: #00ff00;
355
- width: 97%;
356
-
357
- .redbox {
358
- background-color: #ff0000;
359
- color: #000000;
360
- }
361
- }
362
-
363
- is compiled to:
364
-
365
- #main p {
366
- color: #00ff00;
367
- width: 97%; }
368
- #main p .redbox {
369
- background-color: #ff0000;
370
- color: #000000; }
371
-
372
- This helps avoid repetition of parent selectors,
373
- and makes complex CSS layouts with lots of nested selectors much simpler.
374
- For example:
375
-
376
- #main {
377
- width: 97%;
378
-
379
- p, div {
380
- font-size: 2em;
381
- a { font-weight: bold; }
382
- }
383
-
384
- pre { font-size: 3em; }
385
- }
386
-
387
- is compiled to:
388
-
389
- #main {
390
- width: 97%; }
391
- #main p, #main div {
392
- font-size: 2em; }
393
- #main p a, #main div a {
394
- font-weight: bold; }
395
- #main pre {
396
- font-size: 3em; }
397
-
398
- ### Referencing Parent Selectors: `&`
399
-
400
- Sometimes it's useful to use a nested rule's parent selector
401
- in other ways than the default.
402
- For instance, you might want to have special styles
403
- for when that selector is hovered over
404
- or for when the body element has a certain class.
405
- In these cases, you can explicitly specify where the parent selector
406
- should be inserted using the `&` character.
407
- For example:
408
-
409
- a {
410
- font-weight: bold;
411
- text-decoration: none;
412
- &:hover { text-decoration: underline; }
413
- body.firefox & { font-weight: normal; }
414
- }
415
-
416
- is compiled to:
417
-
418
- a {
419
- font-weight: bold;
420
- text-decoration: none; }
421
- a:hover {
422
- text-decoration: underline; }
423
- body.firefox a {
424
- font-weight: normal; }
425
-
426
- `&` will be replaced with the parent selector as it appears in the CSS.
427
- This means that if you have a deeply nested rule,
428
- the parent selector will be fully resolved
429
- before the `&` is replaced.
430
- For example:
431
-
432
- #main {
433
- color: black;
434
- a {
435
- font-weight: bold;
436
- &:hover { color: red; }
437
- }
438
- }
439
-
440
- is compiled to:
441
-
442
- #main {
443
- color: black; }
444
- #main a {
445
- font-weight: bold; }
446
- #main a:hover {
447
- color: red; }
448
-
449
- ### Nested Properties
450
-
451
- CSS has quite a few properties that are in "namespaces;"
452
- for instance, `font-family`, `font-size`, and `font-weight`
453
- are all in the `font` namespace.
454
- In CSS, if you want to set a bunch of properties in the same namespace,
455
- you have to type it out each time.
456
- Sass provides a shortcut for this:
457
- just write the namespace one,
458
- then nest each of the sub-properties within it.
459
- For example:
460
-
461
- .funky {
462
- font: {
463
- family: fantasy;
464
- size: 30em;
465
- weight: bold;
466
- }
467
- }
468
-
469
- is compiled to:
470
-
471
- .funky {
472
- font-family: fantasy;
473
- font-size: 30em;
474
- font-weight: bold; }
475
-
476
- The property namespace itself can also have a value.
477
- For example:
478
-
479
- .funky {
480
- font: 2px/3px {
481
- family: fantasy;
482
- size: 30em;
483
- weight: bold;
484
- }
485
- }
486
-
487
- is compiled to:
488
-
489
- .funky {
490
- font: 2px/3px;
491
- font-family: fantasy;
492
- font-size: 30em;
493
- font-weight: bold; }
494
-
495
- ## Comments: `/* */` and `//` {#comments}
496
-
497
- Sass supports standard multiline CSS comments with `/* */`,
498
- as well as single-line comments with `//`.
499
- The multiline comments are preserved in the CSS output where possible,
500
- while the single-line comments are removed.
501
- For example:
502
-
503
- /* This comment is
504
- * several lines long.
505
- * since it uses the CSS comment syntax,
506
- * it will appear in the CSS output. */
507
- body { color: black; }
508
-
509
- // These comments are only one line long each.
510
- // They won't appear in the CSS output,
511
- // since they use the single-line comment syntax.
512
- a { color: green; }
513
-
514
- is compiled to:
515
-
516
- /* This comment is
517
- * several lines long.
518
- * since it uses the CSS comment syntax,
519
- * it will appear in the CSS output. */
520
- body {
521
- color: black; }
522
-
523
- a {
524
- color: green; }
525
-
526
- ## SassScript {#sassscript}
527
-
528
- In addition to the plain CSS property syntax,
529
- Sass supports a small set of extensions called SassScript.
530
- SassScript allows properties to use
531
- variables, arithmetic, and extra functions.
532
- SassScript can be used in any property value.
533
-
534
- SassScript can also be used to generate selectors and property names,
535
- which is useful when writing [mixins](#mixins).
536
- This is done via [interpolation](#interpolation_).
537
-
538
- ### Interactive Shell
539
-
540
- You can easily experiment with SassScript using the interactive shell.
541
- To launch the shell run the sass command-line with the `-i` option. At the
542
- prompt, enter any legal SassScript expression to have it evaluated
543
- and the result printed out for you:
544
-
545
- $ sass -i
546
- >> "Hello, Sassy World!"
547
- "Hello, Sassy World!"
548
- >> 1px + 1px + 1px
549
- 3px
550
- >> #777 + #777
551
- #eeeeee
552
- >> #777 + #888
553
- white
554
-
555
- ### Variables: `$` {#variables_}
556
-
557
- The most straightforward way to use SassScript
558
- is to use variables.
559
- Variables begin with dollar signs,
560
- and are set like CSS properties:
561
-
562
- $width: 5em;
563
-
564
- You can then refer to them in properties:
565
-
566
- #main {
567
- width: $width;
568
- }
569
-
570
- Variables are only available within the level of nested selectors
571
- where they're defined.
572
- If they're defined outside of any nested selectors,
573
- they're available everywhere.
574
-
575
- Variables used to use the prefix character `!`;
576
- this still works, but it's deprecated and prints a warning.
577
- `$` is the recommended syntax.
578
-
579
- Variables also used to be defined with `=` rather than `:`;
580
- this still works, but it's deprecated and prints a warning.
581
- `:` is the recommended syntax.
582
-
583
- ### Data Types
584
-
585
- SassScript supports four main data types:
586
-
587
- * numbers (e.g. `1.2`, `13`, `10px`)
588
- * strings of text, with and without quotes (e.g. `"foo"`, `'bar'`, `baz`)
589
- * colors (e.g. `blue`, `#04a3f9`, `rgba(255, 0, 0, 0.5)`)
590
- * booleans (e.g. `true`, `false`)
591
-
592
- SassScript also supports all other types of CSS property value,
593
- such as Unicode ranges and `!important` declarations.
594
- However, it has no special handling for these types.
595
- They're treated just like unquoted strings.
596
-
597
- #### Strings {#sass-script-strings}
598
-
599
- CSS specifies two kinds of strings: those with quotes,
600
- such as `"Lucida Grande"` or `'http://sass-lang.com'`,
601
- and those without quotes, such as `sans-serif` or `bold`.
602
- SassScript recognizes both kinds,
603
- and in general if one kind of string is used in the Sass document,
604
- that kind of string will be used in the resulting CSS.
605
-
606
- There is one exception to this, though:
607
- when using [`#{}` interpolation](#interpolation_),
608
- quoted strings are unquoted.
609
- This makes it easier to use e.g. selector names in [mixins](#mixins).
610
- For example:
611
-
612
- @mixin firefox-message($selector) {
613
- body.firefox #{$selector}:before {
614
- content: "Hi, Firefox users!"; } }
615
-
616
- @include firefox-message(".header");
617
-
618
- is compiled to:
619
-
620
- body.firefox .header:before {
621
- content: "Hi, Firefox users!"; }
622
-
623
- It's also worth noting that when using the [deprecated `=` property syntax](#sassscript),
624
- all strings are interpreted as unquoted,
625
- regardless of whether or not they're written with quotes.
626
-
627
- ### Operations
628
-
629
- All types support equality operations (`==` and `!=`).
630
- In addition, each type has its own operations
631
- that it has special support for.
632
-
633
- #### Number Operations
634
-
635
- SassScript supports the standard arithmetic operations on numbers
636
- (`+`, `-`, `*`, `/`, `%`),
637
- and will automatically convert between units if it can:
638
-
639
- p {
640
- width: 1in + 8pt;
641
- }
642
-
643
- is compiled to:
644
-
645
- p {
646
- width: 1.111in; }
647
-
648
- Relational operators
649
- (`<`, `>`, `<=`, `>=`)
650
- are also supported for numbers,
651
- and equality operators
652
- (`==`, `!=`)
653
- are supported for all types.
654
-
655
- ##### Division and `/`
656
- {#division-and-slash}
657
-
658
- CSS allows `/` to appear in property values
659
- as a way of separating numbers.
660
- Since SassScript is an extension of the CSS property syntax,
661
- it must support this, while also allowing `/` to be used for division.
662
- This means that by default, if two numbers are separated by `/` in SassScript,
663
- then they will appear that way in the resulting CSS.
664
-
665
- However, there are three situations where the `/` will be interpreted as division.
666
- These cover the vast majority of cases where division is actually used.
667
- They are:
668
-
669
- 1. If the value, or any part of it, is stored in a variable.
670
- 2. If the value is surrounded by parentheses.
671
- 3. If the value is used as part of another arithmetic expression.
672
-
673
- For example:
674
-
675
- p {
676
- font: 10px/8px; // Plain CSS, no division
677
- $width: 1000px;
678
- width: $width/2; // Uses a variable, does division
679
- height: (500px/2); // Uses parentheses, does division
680
- margin-left: 5px + 8px/2px; // Uses +, does division
681
- }
682
-
683
- is compiled to:
684
-
685
- p {
686
- font: 10px/8px;
687
- width: 500px;
688
- height: 250px;
689
- margin-left: 9px; }
690
-
691
- If you want to use variables along with a plain CSS `/`,
692
- you can use `#{}` to insert them.
693
- For example:
694
-
695
- p {
696
- $font-size: 12px;
697
- $line-height: 30px;
698
- font: #{$font-size}/#{$line-height};
699
- }
700
-
701
- is compiled to:
702
-
703
- p {
704
- font: 12px/30px;
705
- }
706
-
707
- #### Color Operations
708
-
709
- All arithmetic operations are supported for color values,
710
- where they work piecewise.
711
- This means that the operation is performed
712
- on the red, green, and blue components in turn.
713
- For example:
714
-
715
- p {
716
- color: #010203 + #040506;
717
- }
718
-
719
- computes `01 + 04 = 05`, `02 + 05 = 07`, and `03 + 06 = 09`,
720
- and is compiled to:
721
-
722
- p {
723
- color: #050709; }
724
-
725
- Often it's more useful to use {Sass::Script::Functions color functions}
726
- than to try to use color arithmetic to achieve the same effect.
727
-
728
- Arithmetic operations also work between numbers and colors,
729
- also piecewise.
730
- For example:
731
-
732
- p {
733
- color: #010203 * 2;
734
- }
735
-
736
- computes `01 * 2 = 02`, `02 * 2 = 04`, and `03 * 2 = 06`,
737
- and is compiled to:
738
-
739
- p {
740
- color: #020406; }
741
-
742
- Note that colors with an alpha channel
743
- (those created with the {Sass::Script::Functions#rgba rgba}
744
- or {Sass::Script::Functions#hsla hsla} functions)
745
- must have the same alpha value in order for color arithmetic
746
- to be done with them.
747
- The arithmetic doesn't affect the alpha value.
748
- For example:
749
-
750
- p {
751
- color: rgba(255, 0, 0, 0.75) + rgba(0, 255, 0, 0.75);
752
- }
753
-
754
- is compiled to:
755
-
756
- p {
757
- color: rgba(255, 255, 0, 0.75); }
758
-
759
- The alpha channel of a color can be adjusted using the
760
- {Sass::Script::Functions#opacify opacify} and
761
- {Sass::Script::Functions#transparentize transparentize} functions.
762
- For example:
763
-
764
- $translucent-red: rgba(255, 0, 0, 0.5);
765
- p {
766
- color: opacify($translucent-red, 0.8);
767
- background-color: transparentize($translucent-red, 50%);
768
- }
769
-
770
- is compiled to:
771
-
772
- p {
773
- color: rgba(255, 0, 0, 0.9);
774
- background-color: rgba(255, 0, 0, 0.25); }
775
-
776
- #### String Operations
777
-
778
- The `+` operation can be used to concatenate strings:
779
-
780
- p {
781
- cursor: e + -resize;
782
- }
783
-
784
- is compiled to:
785
-
786
- p {
787
- cursor: e-resize; }
788
-
789
- Note that if a quoted string is added to an unquoted string
790
- (that is, the quoted string is to the left of the `+`),
791
- the result is a quoted string.
792
- Likewise, if an unquoted string is added to a quoted string
793
- (the unquoted string is to the left of the `+`),
794
- the result is an unquoted string.
795
- For example:
796
-
797
- p:before {
798
- content: "Foo " + Bar;
799
- font-family: sans- + "serif"; }
800
-
801
- is compiled to:
802
-
803
- p:before {
804
- content: "Foo Bar";
805
- font-family: sans-serif; }
806
-
807
- By default, if two values are placed next to one another,
808
- they are concatenated with a space:
809
-
810
- p {
811
- margin: 3px + 4px auto;
812
- }
813
-
814
- is compiled to:
815
-
816
- p {
817
- margin: 7px auto; }
818
-
819
- Within a string of text, #{} style interpolation can be used to
820
- place dynamic values within the string:
821
-
822
- p:before {
823
- content: "I ate #{5 + 10} pies!"; }
824
-
825
- is compiled to:
826
-
827
- p:before {
828
- content: "I ate 15 pies!"; }
829
-
830
- #### Boolean Operations
831
-
832
- SassScript supports `and`, `or`, and `not` operators
833
- for boolean values.
834
-
835
- ### Parentheses
836
-
837
- Parentheses can be used to affect the order of operations:
838
-
839
- p {
840
- width: 1em + (2em * 3);
841
- }
842
-
843
- is compiled to:
844
-
845
- p {
846
- width: 7em; }
847
-
848
- ### Functions
849
-
850
- SassScript defines some useful functions
851
- that are called using the normal CSS function syntax:
852
-
853
- p {
854
- color: hsl(0, 100%, 0.5);
855
- }
856
-
857
- is compiled to:
858
-
859
- p {
860
- color: #ff0000; }
861
-
862
- See {Sass::Script::Functions} for a full listing of Sass functions,
863
- as well as instructions on defining your own in Ruby.
864
-
865
- ### Interpolation: `#{}` {#interpolation_}
866
-
867
- You can also use SassScript variables in selectors
868
- and property names using #{} interpolation syntax:
869
-
870
- $name: foo;
871
- $attr: border;
872
- p.#{$name} { #{$attr}-color: blue }
873
-
874
- is compiled to:
875
-
876
- p.foo {
877
- border-color: blue; }
878
-
879
- It's also possible to use `#{}` to put SassScript into property values.
880
- In most cases this isn't any better than using a variable,
881
- but using `#{}` does mean that any operations near it
882
- will be treated as plain CSS.
883
- For example:
884
-
885
- p {
886
- $font-size: 12px;
887
- $line-height: 30px;
888
- font: #{$font-size}/#{$line-height};
889
- }
890
-
891
- is compiled to:
892
-
893
- p {
894
- font: 12px/30px;
895
- }
896
-
897
- ### Variable Defaults: `!default`
898
-
899
- You can assign to variables if they aren't already assigned
900
- by adding the `!default` flag to the end of the value.
901
- This means that if the variable has already been assigned to,
902
- it won't be re-assigned,
903
- but if it doesn't have a value yet, it will be given one.
904
-
905
- For example:
906
-
907
- $content: "First content";
908
- $content: "Second content?" !default;
909
- $new_content: "First time reference" !default;
910
-
911
- #main {
912
- content: $content;
913
- new-content: $new_content;
914
- }
915
-
916
- is compiled to:
917
-
918
- #main {
919
- content: "First content";
920
- new-content: "First time reference"; }
921
-
922
- ## `@`-Rules and Directives {#directives}
923
-
924
- Sass supports all CSS3 `@`-rules,
925
- as well as some additional Sass-specific ones
926
- known as "directives."
927
- These have various effects in Sass, detailed below.
928
- See also [control directives](#control-directives)
929
- and [mixin directives](#mixins).
930
-
931
- ### `@import` {#import}
932
-
933
- Sass extends the CSS `@import` rule
934
- to allow it to import SCSS and Sass files.
935
- All imported SCSS and Sass files will be merged together
936
- into a single CSS output file.
937
- In addition, any variables or [mixins](#mixins)
938
- defined in imported files can be used in the main file.
939
-
940
- Sass looks for other Sass files in the current directory,
941
- and the Sass file directory under Rack, Rails, or Merb.
942
- Additional search directories may be specified
943
- using the [`:load_paths`](#load_paths-option) option,
944
- or the `--load-path` option on the command line.
945
-
946
- `@import` takes a filename to import.
947
- By default, it looks for a Sass file to import directly,
948
- but there are a few circumstances under which it will compile to a CSS `@import` rule:
949
-
950
- * If the file's extension is `.css`.
951
- * If the filename begins with `http://`.
952
- * If the filename is a `url()`.
953
- * If the `@import` has any media queries.
954
-
955
- If none of the above conditions are met
956
- and the extension is `.scss` or `.sass`,
957
- then the named Sass or SCSS file will be imported.
958
- If there is no extension,
959
- Sass will try to find a file with that name and the `.scss` or `.sass` extension
960
- and import it.
961
-
962
- For example,
963
-
964
- @import "foo.scss";
965
-
966
- or
967
-
968
- @import "foo";
969
-
970
- would both import the file `foo.scss`,
971
- whereas
972
-
973
- @import "foo.css";
974
- @import "foo" screen;
975
- @import "http://foo.com/bar";
976
- @import url(foo);
977
-
978
- would all compile to
979
-
980
- @import "foo.css";
981
- @import "foo" screen;
982
- @import "http://foo.com/bar";
983
- @import url(foo);
984
-
985
- It's also possible to import multiple files in one `@import`. For example:
986
-
987
- @import "rounded-corners", "text-shadow";
988
-
989
- would import both the `rounded-corners` and the `text-shadow` files.
990
-
991
- #### Partials {#partials}
992
-
993
- If you have a SCSS or Sass file that you want to import
994
- but don't want to compile to a CSS file,
995
- you can add an underscore to the beginning of the filename.
996
- This will tell Sass not to compile it to a normal CSS file.
997
- You can then import these files without using the underscore.
998
-
999
- For example, you might have `_colors.scss`.
1000
- Then no `_colors.css` file would be created,
1001
- and you can do
1002
-
1003
- @import "colors";
1004
-
1005
- and `_colors.scss` would be imported.
1006
-
1007
- ### `@extend` {#extend}
1008
-
1009
- There are often cases when designing a page
1010
- when one class should have all the styles of another class,
1011
- as well as its own specific styles.
1012
- The most common way of handling this is to use both the more general class
1013
- and the more specific class in the HTML.
1014
- For example, suppose we have a design for a normal error
1015
- and also for a serious error. We might write our markup like so:
1016
-
1017
- <div class="error seriousError">
1018
- Oh no! You've been hacked!
1019
- </div>
1020
-
1021
- And our styles like so:
1022
-
1023
- .error {
1024
- border: 1px #f00;
1025
- background-color: #fdd;
1026
- }
1027
- .seriousError {
1028
- border-width: 3px;
1029
- }
1030
-
1031
- Unfortunately, this means that we have to always remember
1032
- to use `.error` with `.seriousError`.
1033
- This is a maintenance burden, leads to tricky bugs,
1034
- and can bring non-semantic style concerns into the markup.
1035
-
1036
- The `@extend` directive avoids these problems
1037
- by telling Sass that one selector should inherit the styles of another selector.
1038
- For example:
1039
-
1040
- .error {
1041
- border: 1px #f00;
1042
- background-color: #fdd;
1043
- }
1044
- .seriousError {
1045
- @extend .error;
1046
- border-width: 3px;
1047
- }
1048
-
1049
- This means that all styles defined for `.error`
1050
- are also applied to `.seriousError`,
1051
- in addition to the styles specific to `.seriousError`.
1052
- In effect, everything with class `.seriousError` also has class `.error`.
1053
-
1054
- Other rules that use `.error` will work for `.seriousError` as well.
1055
- For example, if we have special styles for errors caused by hackers:
1056
-
1057
- .error.intrusion {
1058
- background-image: url("/image/hacked.png");
1059
- }
1060
-
1061
- Then `<div class="seriousError intrusion">`
1062
- will have the `hacked.png` background image as well.
1063
-
1064
- #### How it Works
1065
-
1066
- `@extend` works by inserting the extending selector (e.g. `.seriousError`)
1067
- anywhere in the stylesheet that the extended selector (.e.g `.error`) appears.
1068
- Thus the example above:
1069
-
1070
- .error {
1071
- border: 1px #f00;
1072
- background-color: #fdd;
1073
- }
1074
- .error.intrusion {
1075
- background-image: url("/image/hacked.png");
1076
- }
1077
- .seriousError {
1078
- @extend .error;
1079
- border-width: 3px;
1080
- }
1081
-
1082
- is compiled to:
1083
-
1084
- .error, .seriousError {
1085
- border: 1px #f00;
1086
- background-color: #fdd; }
1087
-
1088
- .error.intrusion, .seriousError.intrusion {
1089
- background-image: url("/image/hacked.png"); }
1090
-
1091
- .seriousError {
1092
- border-width: 3px; }
1093
-
1094
- When merging selectors, `@extend` is smart enough
1095
- to avoid unnecessary duplication,
1096
- so something like `.seriousError.seriousError` gets translated to `.seriousError`.
1097
- In addition, it won't produce selectors that can't match anything, like `#main#footer`.
1098
-
1099
- #### Extending Complex Selectors
1100
-
1101
- Class selectors aren't the only things that can be extended.
1102
- It's possible to extend any selector involving only a single element,
1103
- such as `.special.cool`, `a:hover`, or `a.user[href^="http://"]`.
1104
- For example:
1105
-
1106
- .hoverlink {@extend a:hover}
1107
-
1108
- Just like with classes, this means that all styles defined for `a:hover`
1109
- are also applied to `.hoverlink`.
1110
- For example:
1111
-
1112
- .hoverlink {@extend a:hover}
1113
- a:hover {text-decoration: underline}
1114
-
1115
- is compiled to:
1116
-
1117
- a:hover, .hoverlink {text-decoration: underline}
1118
-
1119
- Just like with `.error.intrusion` above,
1120
- any rule that uses `a:hover` will also work for `.hoverlink`,
1121
- even if they have other selectors as well.
1122
- For example:
1123
-
1124
- .hoverlink {@extend a:hover}
1125
- .comment a.user:hover {font-weight: bold}
1126
-
1127
- is compiled to:
1128
-
1129
- .comment a.user:hover, .comment .hoverlink.user {font-weight: bold}
1130
-
1131
- #### Multiple Extends
1132
-
1133
- A single selector can extend more than one selector.
1134
- This means that it inherits the styles of all the extended selectors.
1135
- For example:
1136
-
1137
- .error {
1138
- border: 1px #f00;
1139
- background-color: #fdd;
1140
- }
1141
- .attention {
1142
- font-size: 3em;
1143
- background-color: #ff0;
1144
- }
1145
- .seriousError {
1146
- @extend .error;
1147
- @extend .attention;
1148
- border-width: 3px;
1149
- }
1150
-
1151
- is compiled to:
1152
-
1153
- .error, .seriousError {
1154
- border: 1px #f00;
1155
- background-color: #fdd; }
1156
-
1157
- .attention, .seriousError {
1158
- font-size: 3em;
1159
- background-color: #ff0; }
1160
-
1161
- .seriousError {
1162
- border-width: 3px; }
1163
-
1164
- In effect, everything with class `.seriousError`
1165
- also has class `.error` *and* class `.attention`.
1166
- Thus, the styles defined later in the document take precedence:
1167
- `.seriousError` has background color `#ff0` rather than `#fdd`,
1168
- since `.attention` is defined later than `.error`.
1169
-
1170
- #### Chaining Extends
1171
-
1172
- It's possible for one selector to extend another selector
1173
- that in turn extends a third.
1174
- For example:
1175
-
1176
- .error {
1177
- border: 1px #f00;
1178
- background-color: #fdd;
1179
- }
1180
- .seriousError {
1181
- @extend .error;
1182
- border-width: 3px;
1183
- }
1184
- .criticalError {
1185
- @extend .seriousError;
1186
- position: fixed;
1187
- top: 10%;
1188
- bottom: 10%;
1189
- left: 10%;
1190
- right: 10%;
1191
- }
1192
-
1193
- Now everything with class `.seriousError` also has class `.error`,
1194
- and everything with class `.criticalError` has class `.seriousError`
1195
- *and* class `.error`.
1196
- It's compiled to:
1197
-
1198
- .error, .seriousError, .criticalError {
1199
- border: 1px #f00;
1200
- background-color: #fdd; }
1201
-
1202
- .seriousError, .criticalError {
1203
- border-width: 3px; }
1204
-
1205
- .criticalError {
1206
- position: fixed;
1207
- top: 10%;
1208
- bottom: 10%;
1209
- left: 10%;
1210
- right: 10%; }
1211
-
1212
- #### Selector Sequences
1213
-
1214
- Selector sequences, such as `.foo .bar` or `.foo + .bar`, currently can't be extended.
1215
- However, it is possible for nested selectors themselves to use `@extend`.
1216
- For example:
1217
-
1218
- #fake-links .link {@extend a}
1219
-
1220
- a {
1221
- color: blue;
1222
- &:hover {text-decoration: underline}
1223
- }
1224
-
1225
- is compiled to
1226
-
1227
- a, #fake-links .link {
1228
- color: blue; }
1229
- a:hover, #fake-links .link:hover {
1230
- text-decoration: underline; }
1231
-
1232
- ##### Merging Selector Sequences
1233
-
1234
- Sometimes a selector sequence extends another selector that appears in another sequence.
1235
- In this case, the two sequences need to be merged.
1236
- For example:
1237
-
1238
- #admin .tabbar a {font-weight: bold}
1239
- #demo .overview .fakelink {@extend a}
1240
-
1241
- While it would technically be possible
1242
- to generate all selectors that could possibly match either sequence,
1243
- this would make the stylesheet far too large.
1244
- The simple example above, for instance, would require ten selectors.
1245
- Instead, Sass generates only selectors that are likely to be useful.
1246
-
1247
- When the two sequences being merged have no selectors in common,
1248
- then two new selectors are generated:
1249
- one with the first sequence before the second,
1250
- and one with the second sequence before the first.
1251
- For example:
1252
-
1253
- #admin .tabbar a {font-weight: bold}
1254
- #demo .overview .fakelink {@extend a}
1255
-
1256
- is compiled to:
1257
-
1258
- #admin .tabbar a,
1259
- #admin .tabbar #demo .overview .fakelink,
1260
- #demo .overview #admin .tabbar .fakelink {
1261
- font-weight: bold; }
1262
-
1263
- If the two sequences do share some selectors,
1264
- then those selectors will be merged together
1265
- and only the differences (if any still exist) will alternate.
1266
- In this example, both sequences contain the id `#admin`,
1267
- so the resulting selectors will merge those two ids:
1268
-
1269
- #admin .tabbar a {font-weight: bold}
1270
- #admin .overview .fakelink {@extend a}
1271
-
1272
- This is compiled to:
1273
-
1274
- #admin .tabbar a,
1275
- #admin .tabbar .overview .fakelink,
1276
- #admin .overview .tabbar .fakelink {
1277
- font-weight: bold; }
1278
-
1279
- ### `@debug`
1280
-
1281
- The `@debug` directive prints the value of a SassScript expression
1282
- to the standard error output stream.
1283
- It's useful for debugging Sass files
1284
- that have complicated SassScript going on.
1285
- For example:
1286
-
1287
- @debug 10em + 12em;
1288
-
1289
- outputs:
1290
-
1291
- Line 1 DEBUG: 22em
1292
-
1293
- ### `@warn`
1294
-
1295
- The `@warn` directive prints the value of a SassScript expression
1296
- to the standard error output stream.
1297
- It's useful for libraries that need to warn users of deprecations
1298
- or recovering from minor mixin usage mistakes.
1299
- There are two major distinctions between `@warn` and `@debug`:
1300
-
1301
- 1. You can turn warnings off with the `--quiet` command-line option
1302
- or the `:quiet` Sass option.
1303
- 2. A stylesheet trace will be printed out along with the message
1304
- so that the user being warned can see where their styles caused the warning.
1305
-
1306
- Usage Example:
1307
-
1308
- @mixin adjust-location($x, $y) {
1309
- @if unitless($x) {
1310
- @warn "Assuming #{$x} to be in pixels";
1311
- $x: 1px * $x;
1312
- }
1313
- @if unitless($y) {
1314
- @warn "Assuming #{$y} to be in pixels";
1315
- $y: 1px * $y;
1316
- }
1317
- position: relative; left: $x; top: $y;
1318
- }
1319
-
1320
- ## Control Directives
1321
-
1322
- SassScript supports basic control directives
1323
- for including styles only under some conditions
1324
- or including the same style several times with variations.
1325
-
1326
- **Note that control directives are an advanced feature,
1327
- and are not recommended in the course of day-to-day styling**.
1328
- They exist mainly for use in [mixins](#mixins),
1329
- particularly those that are part of libraries like [Compass](http://compass-style.org),
1330
- and so require substantial flexibility.
1331
-
1332
- ### `@if`
1333
-
1334
- The `@if` directive takes a SassScript expression
1335
- and uses the styles nested beneath it if the expression returns
1336
- anything other than `false`:
1337
-
1338
- p {
1339
- @if 1 + 1 == 2 { border: 1px solid; }
1340
- @if 5 < 3 { border: 2px dotted; }
1341
- }
1342
-
1343
- is compiled to:
1344
-
1345
- p {
1346
- border: 1px solid; }
1347
-
1348
- The `@if` statement can be followed by several `@else if` statements
1349
- and one `@else` statement.
1350
- If the `@if` statement fails,
1351
- the `@else if` statements are tried in order
1352
- until one succeeds or the `@else` is reached.
1353
- For example:
1354
-
1355
- $type: monster;
1356
- p {
1357
- @if $type == ocean {
1358
- color: blue;
1359
- } @else if $type == matador {
1360
- color: red;
1361
- } @else if $type == monster {
1362
- color: green;
1363
- } @else {
1364
- color: black;
1365
- }
1366
- }
1367
-
1368
- is compiled to:
1369
-
1370
- p {
1371
- color: green; }
1372
-
1373
- ### `@for`
1374
-
1375
- The `@for` directive has two forms:
1376
- `@for $var from <start> to <end>` or
1377
- `@for $var from <start> through <end>`.
1378
- `$var` can be any variable name, like `$i`,
1379
- and `<start>` and `<end>` are SassScript expressions
1380
- that should return integers.
1381
-
1382
- The `@for` statement sets `$var` to each number
1383
- from `<start>` to `<end>`,
1384
- including `<end>` if `through` is used.
1385
- Then it outputs the nested styles
1386
- using that value of `$var`.
1387
- For example:
1388
-
1389
- @for $i from 1 through 3 {
1390
- .item-#{$i} { width: 2em * $i; }
1391
- }
1392
-
1393
- is compiled to:
1394
-
1395
- .item-1 {
1396
- width: 2em; }
1397
- .item-2 {
1398
- width: 4em; }
1399
- .item-3 {
1400
- width: 6em; }
1401
-
1402
- ### `@while`
1403
-
1404
- The `@while` directive takes a SassScript expression
1405
- and repeatedly outputs the nested styles
1406
- until the statement evaluates to `false`.
1407
- This can be used to achieve more complex looping
1408
- than the `@for` statement is capable of,
1409
- although this is rarely necessary.
1410
- For example:
1411
-
1412
- $i: 6;
1413
- @while $i > 0 {
1414
- .item-#{$i} { width: 2em * $i; }
1415
- $i: $i - 2;
1416
- }
1417
-
1418
- is compiled to:
1419
-
1420
- .item-6 {
1421
- width: 12em; }
1422
-
1423
- .item-4 {
1424
- width: 8em; }
1425
-
1426
- .item-2 {
1427
- width: 4em; }
1428
-
1429
- ## Mixin Directives {#mixins}
1430
-
1431
- Mixins allow you to define styles
1432
- that can be re-used throughout the stylesheet
1433
- without needing to resort to non-semantic classes like `.float-left`.
1434
- Mixins can also contain full CSS rules,
1435
- and anything else allowed elsewhere in a Sass document.
1436
- They can even take [arguments](#mixin-arguments)
1437
- which allows you to produce a wide variety of styles
1438
- with very few mixins.
1439
-
1440
- ### Defining a Mixin: `@mixin` {#defining_a_mixin}
1441
-
1442
- Mixins are defined with the `@mixin` directive.
1443
- It's followed by the name of the mixin
1444
- and optionally the [arguments](#mixin-arguments),
1445
- and a block containing the contents of the mixin.
1446
- For example, the `large-text` mixin is defined as follows:
1447
-
1448
- @mixin large-text {
1449
- font: {
1450
- family: Arial;
1451
- size: 20px;
1452
- weight: bold;
1453
- }
1454
- color: #ff0000;
1455
- }
1456
-
1457
- Mixins may also contain selectors,
1458
- possibly mixed with properties.
1459
- The selectors can even contain [parent references](#referencing_parent_selectors_).
1460
- For example:
1461
-
1462
- @mixin clearfix {
1463
- display: inline-block;
1464
- &:after {
1465
- content: ".";
1466
- display: block;
1467
- height: 0;
1468
- clear: both;
1469
- visibility: hidden;
1470
- }
1471
- * html & { height: 1px }
1472
- }
1473
-
1474
- ### Including a Mixin: `@include` {#including_a_mixin}
1475
-
1476
- Mixins are included in the document
1477
- with the `@include` directive.
1478
- This takes the name of a mixin
1479
- and optionally [arguments to pass to it](#mixin-arguments),
1480
- and includes the styles defined by that mixin
1481
- into the current rule.
1482
- For example:
1483
-
1484
- .page-title {
1485
- @include large-text;
1486
- padding: 4px;
1487
- margin-top: 10px;
1488
- }
1489
-
1490
- is compiled to:
1491
-
1492
- .page-title {
1493
- font-family: Arial;
1494
- font-size: 20px;
1495
- font-weight: bold;
1496
- color: #ff0000;
1497
- padding: 4px;
1498
- margin-top: 10px; }
1499
-
1500
- Mixins may also be included outside of any rule
1501
- (that is, at the root of the document)
1502
- as long as they don't directly define any properties
1503
- or use any parent references.
1504
- For example:
1505
-
1506
- @mixin silly-links {
1507
- a {
1508
- color: blue;
1509
- background-color: red;
1510
- }
1511
- }
1512
-
1513
- @include silly-links;
1514
-
1515
- is compiled to:
1516
-
1517
- a {
1518
- color: blue;
1519
- background-color: red; }
1520
-
1521
- Mixin definitions can also include other mixins.
1522
- For example:
1523
-
1524
- @mixin compound {
1525
- @include highlighted-background;
1526
- @include header-text;
1527
- }
1528
-
1529
- @mixin highlighted-background { background-color: #fc0; }
1530
- @mixin header-text { font-size: 20px; }
1531
-
1532
- Mixins that only define descendent selectors, can be safely mixed
1533
- into the top most level of a document.
1534
-
1535
- ### Arguments {#mixin-arguments}
1536
-
1537
- Mixins can take arguments SassScript values as arguments,
1538
- which are given when the mixin is included
1539
- and made available within the mixin as variables.
1540
-
1541
- When defining a mixin,
1542
- the arguments are written as variable names separated by commas,
1543
- all in parentheses after the name.
1544
- Then when including the mixin,
1545
- values can be passed in in the same manner.
1546
- For example:
1547
-
1548
- @mixin sexy-border($color, $width) {
1549
- border: {
1550
- color: $color;
1551
- width: $width;
1552
- style: dashed;
1553
- }
1554
- }
1555
-
1556
- p { @include sexy-border(blue, 1in); }
1557
-
1558
- is compiled to:
1559
-
1560
- p {
1561
- border-color: blue;
1562
- border-width: 1in;
1563
- border-style: dashed; }
1564
-
1565
- Mixins can also specify default values for their arguments
1566
- using the normal variable-setting syntax.
1567
- Then when the mixin is included,
1568
- if it doesn't pass in that argument,
1569
- the default value will be used instead.
1570
- For example:
1571
-
1572
- @mixin sexy-border($color, $width: 1in) {
1573
- border: {
1574
- color: $color;
1575
- width: $width;
1576
- style: dashed;
1577
- }
1578
- }
1579
- p { @include sexy-border(blue); }
1580
- h1 { @include sexy-border(blue, 2in); }
1581
-
1582
- is compiled to:
1583
-
1584
- p {
1585
- border-color: blue;
1586
- border-width: 1in;
1587
- border-style: dashed; }
1588
-
1589
- h1 {
1590
- border-color: blue;
1591
- border-width: 2in;
1592
- border-style: dashed; }
1593
-
1594
- ## Output Style
1595
-
1596
- Although the default CSS style that Sass outputs is very nice
1597
- and reflects the structure of the document,
1598
- tastes and needs vary and so Sass supports several other styles.
1599
-
1600
- Sass allows you to choose between four different output styles
1601
- by setting the [`:style` option](#style-option)
1602
- or using the `--style` command-line flag.
1603
-
1604
- ### `:nested`
1605
-
1606
- Nested style is the default Sass style,
1607
- because it reflects the structure of the CSS styles
1608
- and the HTML document they're styling.
1609
- Each property has its own line,
1610
- but the indentation isn't constant.
1611
- Each rule is indented based on how deeply it's nested.
1612
- For example:
1613
-
1614
- #main {
1615
- color: #fff;
1616
- background-color: #000; }
1617
- #main p {
1618
- width: 10em; }
1619
-
1620
- .huge {
1621
- font-size: 10em;
1622
- font-weight: bold;
1623
- text-decoration: underline; }
1624
-
1625
- Nested style is very useful when looking at large CSS files:
1626
- it allows you to easily grasp the structure of the file
1627
- without actually reading anything.
1628
-
1629
- ### `:expanded`
1630
-
1631
- Expanded is a more typical human-made CSS style,
1632
- with each property and rule taking up one line.
1633
- Properties are indented within the rules,
1634
- but the rules aren't indented in any special way.
1635
- For example:
1636
-
1637
- #main {
1638
- color: #fff;
1639
- background-color: #000;
1640
- }
1641
- #main p {
1642
- width: 10em;
1643
- }
1644
-
1645
- .huge {
1646
- font-size: 10em;
1647
- font-weight: bold;
1648
- text-decoration: underline;
1649
- }
1650
-
1651
- ### `:compact`
1652
-
1653
- Compact style takes up less space than Nested or Expanded.
1654
- It also draws the focus more to the selectors than to their properties.
1655
- Each CSS rule takes up only one line,
1656
- with every property defined on that line.
1657
- Nested rules are placed next to each other with no newline,
1658
- while separate groups of rules have newlines between them.
1659
- For example:
1660
-
1661
- #main { color: #fff; background-color: #000; }
1662
- #main p { width: 10em; }
1663
-
1664
- .huge { font-size: 10em; font-weight: bold; text-decoration: underline; }
1665
-
1666
- ### `:compressed`
1667
-
1668
- Compressed style takes up the minimum amount of space possible,
1669
- having no whitespace except that necessary to separate selectors
1670
- and a newline at the end of the file.
1671
- It also includes some other minor compressions,
1672
- such as choosing the smallest representation for colors.
1673
- It's not meant to be human-readable.
1674
- For example:
1675
-
1676
- #main{color:#fff;background-color:#000}#main p{width:10em}.huge{font-size:10em;font-weight:bold;text-decoration:underline}
1677
-
1678
- ## Extending Sass
1679
-
1680
- Sass provides a number of advanced customizations for users with unique requirements.
1681
- Using these features requires a strong understanding of Ruby.
1682
-
1683
- ### Defining Custom Sass Functions
1684
-
1685
- The same way that Sass defines new functions for use in Sass stylesheets is available
1686
- to users who which to do so. For more information see the [source
1687
- documentation](/docs/yardoc/Sass/Script/Functions.html#adding_custom_functions).
1688
-
1689
- ### Cache Stores
1690
-
1691
- Sass caches parsed documents so that they can be reused without parsing them again
1692
- unless they have changed. By default, Sass will write these cache files to a location
1693
- on the filesystem indicated by [`:cache_location`](#cache_location-option). If you
1694
- cannot write to the filesystem or need to share cache across ruby processes or machines,
1695
- then you can define your own cache store and set the[`:cache_store`
1696
- option](#cache_store-option). For details on creating your own cache store, please
1697
- see the {Sass::CacheStore source documentation}.
1698
-
1699
- ### Custom Importers
1700
-
1701
- Sass importers are in charge of taking paths passed to `@import` and finding the
1702
- appropriate Sass code for those paths. By default, this code is loaded from
1703
- the {Sass::Importers::Filesystem filesystem}, but importers could be added to load
1704
- from a database, over HTTP, or use a different file naming scheme than what Sass expects.
1705
-
1706
- Each importer is in charge of a single load path (or whatever the corresponding notion
1707
- is for the backend). Importers can be placed in the {file:SASS_REFERENCE.md#load_paths-option
1708
- `:load_paths` array} alongside normal filesystem paths.
1709
-
1710
- When resolving an `@import`, Sass will go through the load paths looking for an importer
1711
- that successfully imports the path. Once one is found, the imported file is used.
1712
-
1713
- User-created importers must inherit from {Sass::Importers::Base}.