mirror of
https://github.com/sass/sass.git
synced 2024-09-21 02:27:30 +00:00
Require shortcut links
This commit is contained in:
Natalie Weizenbaum
parent
f91c4cda2d
commit
b79c8ee2ba
@ -28,3 +28,4 @@ config:
|
||||
shortcut_syntax: true
|
||||
|
||||
first-line-heading: false
|
||||
link-image-style: {collapsed: false}
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
When we add a new feature to Sass, we want to make sure the feature is
|
||||
well-designed, clearly specified, feasible to implement, and that it meets the
|
||||
use-cases it's designed for. Although most features should follow the [full
|
||||
process][], very small features can follow the [fast-track process][] instead.
|
||||
process], very small features can follow the [fast-track process] instead.
|
||||
|
||||
[full process]: #process
|
||||
[fast-track process]: #fast-track
|
||||
@ -22,10 +22,10 @@ process][], very small features can follow the [fast-track process][] instead.
|
||||
|
||||
The process for adding a new feature works as follows:
|
||||
|
||||
1. The feature is informally discussed on [the issue tracker][]. Most new
|
||||
features come directly from use-cases brought up by Sass users, or new CSS
|
||||
syntax that Sass needs to support. Once the Sass team has agreed that a
|
||||
feature is desirable, it's marked as [Planned][] and can move to step 2.
|
||||
1. The feature is informally discussed on [the issue tracker]. Most new features
|
||||
come directly from use-cases brought up by Sass users, or new CSS syntax that
|
||||
Sass needs to support. Once the Sass team has agreed that a feature is
|
||||
desirable, it's marked as [Planned] and can move to step 2.
|
||||
|
||||
[the issue tracker]: https://github.com/sass/sass/issues
|
||||
[Planned]: https://github.com/sass/sass/labels/Planned
|
||||
@ -38,21 +38,21 @@ The process for adding a new feature works as follows:
|
||||
|
||||
Step 2 is also where issues are opened for each individual implementation to
|
||||
add the feature. These issues should link to the feature's main issue in the
|
||||
[sass/sass][] issue tracker, and that issue should link back to the
|
||||
[sass/sass] issue tracker, and that issue should link back to the
|
||||
implementation issues.
|
||||
|
||||
[sass/sass]: https://github.com/sass/sass
|
||||
|
||||
3. Public comments are solicited for the feature, usually via a tweet from
|
||||
[@SassCSS][]. If the feature is big enough, a blog post soliciting feedback
|
||||
may also be written. Then we await comments and iterate on feedback for an
|
||||
amount of time that varies based on the size of the feature and the amount of
|
||||
[@SassCSS]. If the feature is big enough, a blog post soliciting feedback may
|
||||
also be written. Then we await comments and iterate on feedback for an amount
|
||||
of time that varies based on the size of the feature and the amount of
|
||||
feedback received.
|
||||
|
||||
[@SassCSS]: https://twitter.com/SassCSS
|
||||
|
||||
As the proposal is updated based on feedback, its draft number should be
|
||||
increased according to the [versioning policy][] and changes should be logged
|
||||
increased according to the [versioning policy] and changes should be logged
|
||||
in a changelog file named `<proposal>.changes.md`. Once enough time has
|
||||
elapsed and the Sass team is satisfied that all feedback is addressed, the
|
||||
feature moves to step 4.
|
||||
@ -123,11 +123,11 @@ their sections.
|
||||
|
||||
Everything in sections that aren't explicitly marked as non-normative should be
|
||||
construed as part of the specification of the feature. Non-normative notes can
|
||||
be included inline in normative sections using [blockquotes][].
|
||||
be included inline in normative sections using [blockquotes].
|
||||
|
||||
[blockquotes]: https://daringfireball.net/projects/markdown/syntax#blockquote
|
||||
|
||||
See [the `accepted/` directory][] for examples of proposals that have been
|
||||
See [the `accepted/` directory] for examples of proposals that have been
|
||||
accepted.
|
||||
|
||||
* **Background**
|
||||
@ -149,7 +149,7 @@ accepted.
|
||||
corner of the feature, it just needs to give users an idea of how it works and
|
||||
what use-cases it addresses. Code examples are encouraged.
|
||||
|
||||
See [Escapes in Identifiers][] for a good example of a Summary section.
|
||||
See [Escapes in Identifiers] for a good example of a Summary section.
|
||||
|
||||
[Escapes in Identifiers]: accepted/identifier-escapes.md#summary
|
||||
|
||||
@ -167,7 +167,7 @@ accepted.
|
||||
* **Syntax**
|
||||
|
||||
This section describes the syntax of the feature being added, if it adds new
|
||||
syntax to the language. The syntax should be written in [Backus-Naur form][],
|
||||
syntax to the language. The syntax should be written in [Backus-Naur form],
|
||||
with regular expression-style operators and the convention that nonterminals
|
||||
are written in capitalized camel-case form. For example:
|
||||
|
||||
@ -187,7 +187,7 @@ accepted.
|
||||
Syntax definitions can also refer to productions from CSS specs. The proposal
|
||||
should link to the specs in question.
|
||||
|
||||
See [Range-Context Media Features][] for an good example of a Syntax section.
|
||||
See [Range-Context Media Features] for an good example of a Syntax section.
|
||||
|
||||
[Range-Context Media Features]: accepted/media-ranges.md
|
||||
|
||||
@ -205,7 +205,7 @@ accepted.
|
||||
* **Deprecation Process**
|
||||
|
||||
All backwards-incompatible features should go through a deprecation process if
|
||||
at all possible (see [Dart Sass's compatibility policy][]). This section
|
||||
at all possible (see [Dart Sass's compatibility policy]). This section
|
||||
describes the details of that process, including what code will produce
|
||||
deprecation warnings and how those warnings will indicate what the user should
|
||||
do to make their stylesheet forwards-compatible.
|
||||
@ -293,13 +293,13 @@ process, it must be moved so that it can have a full discussion.
|
||||
|
||||
The fast-track process works as follows:
|
||||
|
||||
1. The feature is informally discussed on [the issue tracker][]. Once the Sass
|
||||
team has agreed that a feature is desirable, it's marked as [Planned][] and
|
||||
can move to step 2.
|
||||
1. The feature is informally discussed on [the issue tracker]. Once the Sass
|
||||
team has agreed that a feature is desirable, it's marked as [Planned] and can
|
||||
move to step 2.
|
||||
|
||||
2. Issues are opened for each individual implementation to add the feature.
|
||||
These issues should link to the feature's main issue in the [sass/sass][]
|
||||
issue tracker, and that issue should link back to the implementation issues.
|
||||
These issues should link to the feature's main issue in the [sass/sass] issue
|
||||
tracker, and that issue should link back to the implementation issues.
|
||||
|
||||
Three pull requests are sent out concurrently.
|
||||
|
||||
@ -308,7 +308,7 @@ The fast-track process works as follows:
|
||||
author. *Unlike the full proposal process*, this pull request directly
|
||||
modifies the appropriate spec in `specs/`.
|
||||
|
||||
2. A pull request is sent to [sass-spec][] that adds or updates specs for the
|
||||
2. A pull request is sent to [sass-spec] that adds or updates specs for the
|
||||
new feature. The new specs should have an `options.yml` file that marks
|
||||
them as ignored for LibSass. For example:
|
||||
|
||||
@ -322,7 +322,7 @@ The fast-track process works as follows:
|
||||
cause it not to run Dart Sass tests, which would otherwise fail because
|
||||
the implementation of the new feature hasn't landed yet.
|
||||
|
||||
3. A pull request is sent to [Dart Sass][] that implements the new feature.
|
||||
3. A pull request is sent to [Dart Sass] that implements the new feature.
|
||||
This pull request's message should link to the sass-spec pull request (for
|
||||
example, `See sass/sass-spec#1293`). This will cause it to run against the
|
||||
specs in that pull request and so test your new feature.
|
||||
|
||||
17
README.md
17
README.md
@ -47,14 +47,13 @@ nav {
|
||||
## Install Sass
|
||||
|
||||
You can install Sass on Windows, Mac, or Linux by downloading the package for
|
||||
your operating system [from GitHub][] and [adding it to your `PATH`][PATH].
|
||||
That's all—there are no external dependencies and nothing else you need to
|
||||
install.
|
||||
your operating system [from GitHub] and [adding it to your `PATH`][PATH]. That's
|
||||
all—there are no external dependencies and nothing else you need to install.
|
||||
|
||||
[from GitHub]: https://github.com/sass/dart-sass/releases
|
||||
[PATH]: https://katiek2.github.io/path-doc/
|
||||
|
||||
If you use Node.js, you can also install Sass using [npm][] by running
|
||||
If you use Node.js, you can also install Sass using [npm] by running
|
||||
|
||||
[npm]: https://www.npmjs.com/
|
||||
|
||||
@ -85,16 +84,16 @@ learn Sass!
|
||||
## This Repository
|
||||
|
||||
This repository isn't an implementation of Sass. Those live in
|
||||
[`sass/dart-sass`][] and [`sass/libsass`][]. Instead, it contains:
|
||||
[`sass/dart-sass`] and [`sass/libsass`]. Instead, it contains:
|
||||
|
||||
[`sass/dart-sass`]: https://github.com/sass/dart-sass
|
||||
[`sass/libsass`]: https://github.com/sass/libsass
|
||||
|
||||
* [`spec/`][], which contains specifications for language features.
|
||||
* [`proposal/`][], which contains in-progress proposals for changes to the
|
||||
* [`spec/`], which contains specifications for language features.
|
||||
* [`proposal/`], which contains in-progress proposals for changes to the
|
||||
language.
|
||||
* [`accepted/`][], which contains proposals that have been accepted and are
|
||||
either implemented or in the process of being implemented.
|
||||
* [`accepted/`], which contains proposals that have been accepted and are either
|
||||
implemented or in the process of being implemented.
|
||||
|
||||
[`spec/`]: https://github.com/sass/sass/tree/main/spec
|
||||
[`proposal/`]: https://github.com/sass/sass/tree/main/proposal
|
||||
|
||||
@ -125,12 +125,12 @@ All new functions are part of the `sass:color` built-in module.
|
||||
* Set `blackness` to `blackness / (whiteness + blackness)`.
|
||||
|
||||
* Let `red`, `green`, and `blue` be the result of converting `hue`,
|
||||
`whiteness`, and `blackness` [to RGB][].
|
||||
`whiteness`, and `blackness` [to RGB].
|
||||
|
||||
* Set `red`, `green`, and `blue` to their existing values multiplied by 255
|
||||
and rounded to the nearest integers.
|
||||
|
||||
* Let `alpha` be the result of [percent-converting][] `$alpha` with a `max` of 1.
|
||||
* Let `alpha` be the result of [percent-converting] `$alpha` with a `max` of 1.
|
||||
|
||||
* Return a color with the given `red`, `green`, `blue`, and `alpha` channels.
|
||||
|
||||
@ -268,7 +268,7 @@ This function's new definition is as follows:
|
||||
* If `$lightness` isn't null, set `lightness` to `lightness + $lightness`
|
||||
clamped between 0 and 100.
|
||||
|
||||
* Return the result of calling [`hsl()`][] with `hue`, `saturation`,
|
||||
* Return the result of calling [`hsl()`] with `hue`, `saturation`,
|
||||
`lightness`, and `alpha`.
|
||||
|
||||
* Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null:
|
||||
@ -356,7 +356,7 @@ This function's new definition is as follows:
|
||||
* Let `lightness` be the result of calling `lightness($color)` if
|
||||
`$lightness` is null, or `$lightness` otherwise.
|
||||
|
||||
* Return the result of calling [`hsl()`][] with `hue`, `saturation`,
|
||||
* Return the result of calling [`hsl()`] with `hue`, `saturation`,
|
||||
`lightness`, and `alpha`.
|
||||
|
||||
* Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null:
|
||||
@ -398,7 +398,7 @@ This function's new definition is as follows:
|
||||
|
||||
* Let `alpha` be `$color`'s alpha channel.
|
||||
|
||||
* If `$alpha` isn't null, set `alpha` to the result of [scaling][] `alpha` by
|
||||
* If `$alpha` isn't null, set `alpha` to the result of [scaling] `alpha` by
|
||||
`$alpha` with `max` 1.
|
||||
|
||||
[scaling]: #scaling-a-number
|
||||
@ -410,13 +410,13 @@ This function's new definition is as follows:
|
||||
|
||||
* Let `red`, `green`, and `blue` be `$color`'s red, green, and blue channels.
|
||||
|
||||
* If `$red` isn't null, set `red` to the result of [scaling][] `red` by `$red`
|
||||
* If `$red` isn't null, set `red` to the result of [scaling] `red` by `$red`
|
||||
with `max` 255.
|
||||
|
||||
* If `$green` isn't null, set `green` to the result of [scaling][] `green` by
|
||||
* If `$green` isn't null, set `green` to the result of [scaling] `green` by
|
||||
`$green` with `max` 255.
|
||||
|
||||
* If `$blue` isn't null, set `blue` to the result of [scaling][] `blue` by `$blue`
|
||||
* If `$blue` isn't null, set `blue` to the result of [scaling] `blue` by `$blue`
|
||||
with `max` 255.
|
||||
|
||||
* Return a color with `red`, `green`, `blue`, and `alpha` as the red, green,
|
||||
@ -429,13 +429,13 @@ This function's new definition is as follows:
|
||||
* Let `hue`, `saturation`, and `lightness` be the result of calling
|
||||
`hue($color)`, `saturation($color)`, and `lightness($color)` respectively.
|
||||
|
||||
* If `$saturation` isn't null, set `saturation` to the result of [scaling][]
|
||||
* If `$saturation` isn't null, set `saturation` to the result of [scaling]
|
||||
`saturation` by `$saturation` with `max` `100%`.
|
||||
|
||||
* If `$lightness` isn't null, set `lightness` to the result of [scaling][]
|
||||
* If `$lightness` isn't null, set `lightness` to the result of [scaling]
|
||||
`lightness` by `$lightness` with `max` `100%`.
|
||||
|
||||
* Return the result of calling [`hsl()`][] with `hue`, `saturation`,
|
||||
* Return the result of calling [`hsl()`] with `hue`, `saturation`,
|
||||
`lightness`, and `alpha`.
|
||||
|
||||
* Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null:
|
||||
@ -443,10 +443,10 @@ This function's new definition is as follows:
|
||||
* Let `hue`, `whiteness`, and `blackness` be the result of calling
|
||||
`hue($color)`, `whiteness($color)`, and `blackness($color)` respectively.
|
||||
|
||||
* If `$whiteness` isn't null, set `whiteness` to the result of [scaling][]
|
||||
* If `$whiteness` isn't null, set `whiteness` to the result of [scaling]
|
||||
`whiteness` by `$whiteness` with `max` `100%`.
|
||||
|
||||
* If `$blackness` isn't null, set `blackness` to the result of [scaling][]
|
||||
* If `$blackness` isn't null, set `blackness` to the result of [scaling]
|
||||
`blackness` by `$blackness` with `max` `100%`.
|
||||
|
||||
* Return the result of calling `hwb()` with `hue`, `whiteness`, `blackness`,
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
*([Issue](https://github.com/sass/sass/issues/2564), [Changelog](color-4-rgb-hsl.changes.md))*
|
||||
|
||||
This proposal expands Sass's built-in `rgb()`, `rgba()`, `hsl()`, and `hsla()`
|
||||
functions to support the new terse syntax defined in [CSS Color Level 4][].
|
||||
functions to support the new terse syntax defined in [CSS Color Level 4].
|
||||
|
||||
[CSS Color Level 4]: https://drafts.csswg.org/css-color/
|
||||
|
||||
@ -22,7 +22,7 @@ functions to support the new terse syntax defined in [CSS Color Level 4][].
|
||||
Sass's `rgb()` and `hsl()` functions will add support for the Color Level 4
|
||||
syntax, so `rgb(179 115 153)`, `rgb(70% 45% 60%)`, and `hsl(324deg 29% 57%)`
|
||||
will all return the same color. They'll also support the slash-separated alpha
|
||||
syntax using [the normal rules][] for distinguishing between division and `/`,
|
||||
syntax using [the normal rules] for distinguishing between division and `/`,
|
||||
so `rgb(179 115 153 / 50%)` will return a 50%-opacity color but
|
||||
`rgb(179 115 $blue / 50%)` will not.
|
||||
|
||||
@ -58,7 +58,7 @@ case-insensitive.
|
||||
|
||||
### Special Variable String
|
||||
|
||||
A *special variable string* is [special number string][] that begins with
|
||||
A *special variable string* is [special number string] that begins with
|
||||
`var(`. This matching is case-insensitive.
|
||||
|
||||
[special number string]: #special-number-string
|
||||
@ -78,7 +78,7 @@ functions:
|
||||
rgb($channels)
|
||||
```
|
||||
|
||||
* If `$channels` is a [special variable string][], return a plain CSS function
|
||||
* If `$channels` is a [special variable string], return a plain CSS function
|
||||
string with the name `"rgb"` and the argument `$channels`.
|
||||
|
||||
* If `$channels` is not an unbracketed space-separated list, throw an error.
|
||||
@ -87,7 +87,7 @@ functions:
|
||||
|
||||
* If `$channels` has fewer than three elements:
|
||||
|
||||
* If any element of `$channels` is a [special variable string][], return a
|
||||
* If any element of `$channels` is a [special variable string], return a
|
||||
plain CSS function string with the name `"rgb"` and the argument
|
||||
`$channels`.
|
||||
|
||||
@ -131,7 +131,7 @@ functions:
|
||||
rgb($color, $alpha)
|
||||
```
|
||||
|
||||
* If either argument is a [special variable string][], return a plain CSS
|
||||
* If either argument is a [special variable string], return a plain CSS
|
||||
function string with the name `"rgb"` and the same arguments.
|
||||
|
||||
* Call `rgba()` with the same arguments and return the result.
|
||||
@ -140,7 +140,7 @@ functions:
|
||||
hsl($channels)
|
||||
```
|
||||
|
||||
* If `$channels` is a [special variable string][], return a plain CSS function
|
||||
* If `$channels` is a [special variable string], return a plain CSS function
|
||||
string with the name `"hsl"` and the argument `$channels`.
|
||||
|
||||
* If `$channels` is not an unbracketed space-separated list, throw an error.
|
||||
@ -149,7 +149,7 @@ functions:
|
||||
|
||||
* If `$channels` has fewer than three elements:
|
||||
|
||||
* If any element of `$channels` is a [special variable string][], return a
|
||||
* If any element of `$channels` is a [special variable string], return a
|
||||
plain CSS function string with the name `"hsl"` and the argument
|
||||
`$channels`.
|
||||
|
||||
|
||||
@ -67,7 +67,7 @@ We decided to use `using` as opposed to another word because it's relatively
|
||||
terse while still being clear. We considered `as` instead, but decided the
|
||||
meaning of the word didn't match the semantics; and we considered `with`, but
|
||||
decided that it was both semantically ambiguous and confusing because the
|
||||
[module system proposal][] uses to declare an argument *invocation* rather than
|
||||
[module system proposal] uses to declare an argument *invocation* rather than
|
||||
an argument *declaration*.
|
||||
|
||||
[module system proposal]: module-system.md
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
This proposal covers a long-awaited Sass feature: the ability to import plain
|
||||
CSS files from Sass. Although the original plan was to wait on this support
|
||||
until the [module system][] was in place and support CSS imports only with
|
||||
until the [module system] was in place and support CSS imports only with
|
||||
`@use`, it has become desirable to support them sooner in order to have
|
||||
compatibility with the existing LibSass implementation. See
|
||||
[Background](#background) for more details.
|
||||
@ -33,7 +33,7 @@ compatibility with the existing LibSass implementation. See
|
||||
Historically, the reference implementations of Sass—first Ruby Sass, then Dart
|
||||
Sass—only supported importing other Sass files. However, LibSass supported
|
||||
importing CSS files as well, interpreting them as though they were SCSS.
|
||||
Although this technically violated the [implementation guide][]'s prohibition on
|
||||
Although this technically violated the [implementation guide]'s prohibition on
|
||||
unilaterally extending the language, these CSS imports were useful and were
|
||||
widely adopted in the Node.js community.
|
||||
|
||||
@ -162,7 +162,7 @@ To evaluate an `@import` rule:
|
||||
|
||||
If this returns null, throw an error.
|
||||
|
||||
* If an AST with the same [canonical URL][] as `stylesheet` is currently being
|
||||
* If an AST with the same [canonical URL] as `stylesheet` is currently being
|
||||
evaluated, throw an error.
|
||||
|
||||
* Evaluate `stylesheet` in the global scope.
|
||||
@ -173,7 +173,7 @@ To evaluate an `@import` rule:
|
||||
|
||||
This algorithm takes a string, `argument`, and returns a Sass stylesheet.
|
||||
|
||||
* Let `root` be the current stylesheet's [canonical URL][] if its scheme is
|
||||
* Let `root` be the current stylesheet's [canonical URL] if its scheme is
|
||||
`file`, otherwise null.
|
||||
|
||||
* Let `bases` be a list beginning with `root` if it's non-null, followed by the
|
||||
@ -181,7 +181,7 @@ This algorithm takes a string, `argument`, and returns a Sass stylesheet.
|
||||
|
||||
* For each `base` in `bases`:
|
||||
|
||||
* Let `url` be the result of [parsing `argument` as a URL][] with `base` as
|
||||
* Let `url` be the result of [parsing `argument` as a URL] with `base` as
|
||||
the base URL.
|
||||
|
||||
If this returns a failure, throw that failure.
|
||||
@ -213,7 +213,7 @@ This algorithm takes a string, `argument`, and returns a Sass stylesheet.
|
||||
> The algorithm for [resolving a `file:` URL](#resolving-a-file-url)
|
||||
> guarantees that `resolved` will have one of these extensions.
|
||||
|
||||
* Return `ast` with the [canonical URL][] `resolved`.
|
||||
* Return `ast` with the [canonical URL] `resolved`.
|
||||
|
||||
[parsing `argument` as a URL]: https://url.spec.whatwg.org/#concept-url-parser
|
||||
|
||||
@ -400,7 +400,7 @@ It returns a Sass stylesheet.
|
||||
> The algorithm for [resolving a `file:` URL](#resolving-a-file-url)
|
||||
> guarantees that `resolved` will have one of these extensions.
|
||||
|
||||
* Return `ast` with the [canonical URL][] `url`.
|
||||
* Return `ast` with the [canonical URL] `url`.
|
||||
|
||||
## Deprecation process
|
||||
|
||||
|
||||
@ -111,12 +111,12 @@ One optimization that we've been doing for a long time is
|
||||
`extend(a.foo, .foo, a) = a`, as discussed above. This violates the first law,
|
||||
since `a != a.foo`.
|
||||
|
||||
Another optimization added in [8f4869e][] is `extend(a, a, a.foo) = a`. This
|
||||
Another optimization added in [8f4869e] is `extend(a, a, a.foo) = a`. This
|
||||
violates the second law, since `spec(a) < spec(a.foo)`.
|
||||
|
||||
[8f4869e]: https://github.com/sass/ruby-sass/commit/8f4869e608e70d7f468bb463ebfe7a939d834e27
|
||||
|
||||
However, many of the optimizations added in [8f4869e][] do still work. For
|
||||
However, many of the optimizations added in [8f4869e] do still work. For
|
||||
example, `extend(.bar a, a, a.foo) = .bar a` works because
|
||||
`spec(.bar a) = spec(a.foo)`.
|
||||
|
||||
|
||||
@ -163,10 +163,10 @@ meta.get-mixin($name, $module: null)
|
||||
|
||||
* If `$module` is not a string, throw an error.
|
||||
|
||||
* Let `use` be the `@use` rule in [the current source file][] whose
|
||||
* Let `use` be the `@use` rule in [the current source file] whose
|
||||
namespace is equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
* Return [`use`'s module][]'s mixin named `$name`, or throw an error if no
|
||||
* Return [`use`'s module]'s mixin named `$name`, or throw an error if no
|
||||
such mixin exists.
|
||||
|
||||
[the current source file]: ../spec/spec.md#current-source-file
|
||||
@ -182,11 +182,11 @@ meta.module-mixins($module)
|
||||
|
||||
* If `$module` is not a string, throw an error.
|
||||
|
||||
* Let `use` be the `@use` rule in [the current source file][] whose namespace is
|
||||
* Let `use` be the `@use` rule in [the current source file] whose namespace is
|
||||
equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
* Return a map whose keys are the quoted string names of mixins in
|
||||
[`use`'s module][] and whose values are the corresponding mixins.
|
||||
[`use`'s module] and whose values are the corresponding mixins.
|
||||
|
||||
### `meta.accepts-content()`
|
||||
|
||||
|
||||
@ -41,7 +41,7 @@ of the root module, without removing that option for end-users.
|
||||
|
||||
Sass will add a `with` clause to `@forward`. The `@forward ... with` syntax is
|
||||
based on the `@use ... with` syntax, but allows the addition of `!default` flags
|
||||
similar to a [variable declaration][]. Unlike `@use ... with`, unconfigured
|
||||
similar to a [variable declaration]. Unlike `@use ... with`, unconfigured
|
||||
origin variables, and variables configured with a `!default` flag, will remain
|
||||
configurable by any file importing the combined module. For example:
|
||||
|
||||
@ -133,7 +133,7 @@ The new `WithClause` extends `@forward` to the follow grammar:
|
||||
## Semantics
|
||||
|
||||
The `@forward ... with` semantics builds on the existing proposal for
|
||||
[Executing Files][], and should be understood as modifying and expanding upon
|
||||
[Executing Files], and should be understood as modifying and expanding upon
|
||||
the existing execution process rather than being a comprehensive replacement.
|
||||
|
||||
[Executing Files]: ../accepted/module-system.md#executing-files
|
||||
@ -143,7 +143,7 @@ Given a source file `file`, a configuration `config`, and an import context
|
||||
|
||||
* Let `module` be an empty module with the same URL as `file`.
|
||||
|
||||
* Let `uses` be an empty map from `@use` rules to [modules][].
|
||||
* Let `uses` be an empty map from `@use` rules to [modules].
|
||||
|
||||
* When a `@use` rule `rule` is encountered:
|
||||
|
||||
@ -161,7 +161,7 @@ Given a source file `file`, a configuration `config`, and an import context
|
||||
* Add a variable to `rule-config` with the same name as `argument`'s
|
||||
identifier and with `value` as its value.
|
||||
|
||||
* Let `module` be the result of [loading][] the module with `rule`'s URL
|
||||
* Let `module` be the result of [loading] the module with `rule`'s URL
|
||||
and `rule-config`.
|
||||
|
||||
* If `rule` has a `WithClause` that contains any variables that aren't part of
|
||||
@ -200,7 +200,7 @@ Given a source file `file`, a configuration `config`, and an import context
|
||||
* Add a variable to `rule-config` with the same name as `argument`'s
|
||||
identifier, and with `value` as its value.
|
||||
|
||||
* Let `forwarded` be the result of [loading][] the module with `rule`'s URL
|
||||
* Let `forwarded` be the result of [loading] the module with `rule`'s URL
|
||||
and `rule-config`.
|
||||
|
||||
* If `rule` has a `WithClause` that contains any variables that aren't part of
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
*([Issue](https://github.com/sass/sass/issues/1778))*
|
||||
|
||||
Spurred by [#1774][], I started thinking about how messy interpolation is in
|
||||
Spurred by [#1774], I started thinking about how messy interpolation is in
|
||||
SassScript at the moment and how to clean it up. This issue is the result of
|
||||
that thought process.
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ CSS handles escapes.
|
||||
At time of writing, while Sass recognizes escaped code points in identifiers and
|
||||
other names, it doesn't resolve them into the code points they represent. This
|
||||
means that, for example, Sass considers the selector `.\!foo` and the selector
|
||||
`.\21 foo` to be distinct. This is contrary to the [CSS Syntax Level 3][], which
|
||||
`.\21 foo` to be distinct. This is contrary to the [CSS Syntax Level 3], which
|
||||
[says that][css: consume name] the value of an escaped code point should be
|
||||
included in the name rather than the syntax of the escape.
|
||||
|
||||
@ -94,12 +94,12 @@ intended to replace the existing algorithms.
|
||||
|
||||
### Consuming an Identifier
|
||||
|
||||
This algorithm consumes input from a stream of [code points][] and returns a
|
||||
This algorithm consumes input from a stream of [code points] and returns a
|
||||
string.
|
||||
|
||||
[code points]: https://infra.spec.whatwg.org/#code-point
|
||||
|
||||
This production has the same grammar as [`<ident-token>`][].
|
||||
This production has the same grammar as [`<ident-token>`].
|
||||
|
||||
[`<ident-token>`]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
|
||||
@ -111,10 +111,10 @@ This production has the same grammar as [`<ident-token>`][].
|
||||
|
||||
* If the stream starts with `-`, consume it and append it to `string`.
|
||||
|
||||
* If the stream starts with `\`, [consume an escaped code point][] with the
|
||||
* If the stream starts with `\`, [consume an escaped code point] with the
|
||||
`start` flag set and append it to `string`.
|
||||
|
||||
* Otherwise, if the stream starts with a [name-start code point][], consume it
|
||||
* Otherwise, if the stream starts with a [name-start code point], consume it
|
||||
and append it to `string`.
|
||||
|
||||
* Otherwise, throw an error.
|
||||
@ -128,7 +128,7 @@ This production has the same grammar as [`<ident-token>`][].
|
||||
|
||||
### Consuming an Interpolated Identifier
|
||||
|
||||
This algorithm consumes input from a stream of [code points][] and returns a
|
||||
This algorithm consumes input from a stream of [code points] and returns a
|
||||
sequence of strings and/or expressions.
|
||||
|
||||
The grammar for this production is:
|
||||
@ -152,7 +152,7 @@ No whitespace is allowed between components of an `InterpolatedIdentifier`.
|
||||
* Otherwise, [consume an identifier](#consuming-an-identifier) and add its string
|
||||
to `components`.
|
||||
|
||||
* While the input starts with `#{`, a [name code point][], or `\`:
|
||||
* While the input starts with `#{`, a [name code point], or `\`:
|
||||
|
||||
[name code point]: https://drafts.csswg.org/css-syntax-3/#name-code-point
|
||||
|
||||
@ -166,52 +166,52 @@ No whitespace is allowed between components of an `InterpolatedIdentifier`.
|
||||
|
||||
### Consuming a Name
|
||||
|
||||
This algorithm consumes input from a stream of [code points][] and returns a
|
||||
This algorithm consumes input from a stream of [code points] and returns a
|
||||
string.
|
||||
|
||||
The grammar for this production is:
|
||||
|
||||
<x><pre>
|
||||
**Name** ::= ([name code point][] | [escape][])+
|
||||
**Name** ::= ([name code point] | [escape])+
|
||||
</pre></x>
|
||||
|
||||
* Let `string` be an empty string.
|
||||
|
||||
* While the input starts with a [name code point][] or `\`:
|
||||
* While the input starts with a [name code point] or `\`:
|
||||
|
||||
* If the input starts with a [name code point][], consume it and append it to
|
||||
* If the input starts with a [name code point], consume it and append it to
|
||||
`string`.
|
||||
|
||||
* Otherwise, [consume an escaped code point][] and append it to `string`.
|
||||
* Otherwise, [consume an escaped code point] and append it to `string`.
|
||||
|
||||
* Return `string`.
|
||||
|
||||
### Consuming an Escaped Code Point
|
||||
|
||||
This algorithm consumes input from a stream of [code points][]. It takes an
|
||||
This algorithm consumes input from a stream of [code points]. It takes an
|
||||
optional boolean flag, `start`, which indicates whether it's at the beginning of
|
||||
an identifier and defaults to false. It returns a string.
|
||||
|
||||
This production has the same grammar as [`escape`][escape] in CSS Syntax Level 3.
|
||||
|
||||
* If the stream doesn't [start with a valid escape][], throw an error.
|
||||
* If the stream doesn't [start with a valid escape], throw an error.
|
||||
|
||||
[start with a valid escape]: https://drafts.csswg.org/css-syntax-3/#starts-with-a-valid-escape
|
||||
|
||||
* Let `codepoint` be the result of [consuming an escaped code point][].
|
||||
* Let `codepoint` be the result of [consuming an escaped code point].
|
||||
|
||||
[consuming an escaped code point]: https://drafts.csswg.org/css-syntax-3/#consume-escaped-code-point
|
||||
|
||||
* Let `character` be the string containing only `codepoint`.
|
||||
|
||||
* If `codepoint` is a [name-start code point][], return `character`.
|
||||
* If `codepoint` is a [name-start code point], return `character`.
|
||||
|
||||
* Otherwise, if `codepoint` is a [name code point][] and the `start` flag is
|
||||
* Otherwise, if `codepoint` is a [name code point] and the `start` flag is
|
||||
not set, return `character`.
|
||||
|
||||
* Otherwise, if `codepoint` is a [non-printable code point][], U+000A LINE FEED,
|
||||
* Otherwise, if `codepoint` is a [non-printable code point], U+000A LINE FEED,
|
||||
U+000D CARRIAGE RETURN, or U+000C FORM FEED; *or* if `codepoint` is a
|
||||
[digit][] and the `start` flag is set:
|
||||
[digit] and the `start` flag is set:
|
||||
|
||||
[non-printable code point]: https://drafts.csswg.org/css-syntax-3/#non-printable-code-point
|
||||
[digit]: https://drafts.csswg.org/css-syntax-3/#digit
|
||||
|
||||
@ -28,12 +28,12 @@ members that are behind a `@forward` rule.
|
||||
This makes it difficult for libraries with configurable variables to migrate to
|
||||
the module system without breaking downstream users that haven't migrated yet.
|
||||
This is especially true if the library removed a manual prefix from its members
|
||||
during migration. When the [migrator][] does this, it creates an import-only file
|
||||
during migration. When the [migrator] does this, it creates an import-only file
|
||||
that forwards the regular stylesheet with the prefix added back, but that
|
||||
`@forward` rule means configuration doesn't work.
|
||||
|
||||
Because it is nearly impossible to migrate these cases incrementally, this
|
||||
violates the module system's [backwards compatibility goal][]. Libraries with
|
||||
violates the module system's [backwards compatibility goal]. Libraries with
|
||||
prefixes and configuration variables are common, and without an incremental
|
||||
migration solution, these libraries may be slow to start using the module
|
||||
system, limiting its adoption by the ecosystem as a whole.
|
||||
@ -49,8 +49,8 @@ This proposal modifies the semantics for configuring a module when `@import` is
|
||||
involved to ensure that most downstream users of a library are not broken when
|
||||
the library migrates to the module system.
|
||||
|
||||
When a file is loaded by an `@import` rule, a [configuration][] is created that
|
||||
includes all variables declared in the current [import context][]. This
|
||||
When a file is loaded by an `@import` rule, a [configuration] is created that
|
||||
includes all variables declared in the current [import context]. This
|
||||
implicitly created configuration is a special type that can be distinguished
|
||||
from other, explicitly created configurations.
|
||||
|
||||
@ -78,7 +78,7 @@ We considered a few alternatives in designing this proposal.
|
||||
|
||||
One alternative did not involve any language changes at all, instead
|
||||
recommending that library authors add `@use` rules explicitly configuring their
|
||||
variables to their [import-only files][] when migrating. For example:
|
||||
variables to their [import-only files] when migrating. For example:
|
||||
|
||||
```scss
|
||||
// app.scss
|
||||
@ -118,7 +118,7 @@ configuration between the two imports, the change will be ignored. However,
|
||||
this is an edge case that is (a) probably not intended by the user, (b)
|
||||
relatively easy to fix by moving all declared configuration variables before
|
||||
all library imports, and (c) very difficult to support for a library using the
|
||||
module system without compromising the module system's [import once goal][], as
|
||||
module system without compromising the module system's [import once goal], as
|
||||
handling this case would require modules in the library to be executed twice.
|
||||
|
||||
[import-only files]: ../accepted/module-system.md#import-compatibility
|
||||
@ -126,8 +126,8 @@ handling this case would require modules in the library to be executed twice.
|
||||
|
||||
## Definitions
|
||||
|
||||
This proposal modifies the definition of a [configuration][] within the
|
||||
[module system spec][] to add the following:
|
||||
This proposal modifies the definition of a [configuration] within the
|
||||
[module system spec] to add the following:
|
||||
|
||||
A configuration is either *explicit* or *implicit*. When a configuration is
|
||||
created, if the type is not specified, it is considered *explicit*.
|
||||
@ -136,10 +136,10 @@ created, if the type is not specified, it is considered *explicit*.
|
||||
|
||||
## Procedures
|
||||
|
||||
This proposal modifies the fourth bullet of the [Loading Modules][] procedure
|
||||
within the [module system spec][] to read as follows:
|
||||
This proposal modifies the fourth bullet of the [Loading Modules] procedure
|
||||
within the [module system spec] to read as follows:
|
||||
|
||||
* If `file` has already been [executed][]:
|
||||
* If `file` has already been [executed]:
|
||||
|
||||
* If `config` is **explicit and** not empty, throw an error.
|
||||
|
||||
@ -152,8 +152,8 @@ within the [module system spec][] to read as follows:
|
||||
|
||||
### Executing Files
|
||||
|
||||
This proposal modifies the first bullet of the semantics of [Executing Files][]
|
||||
within the [module system spec][] to read as follows:
|
||||
This proposal modifies the first bullet of the semantics of [Executing Files]
|
||||
within the [module system spec] to read as follows:
|
||||
|
||||
* If this file isn't being executed for a `@forward` **or `@import`** rule:
|
||||
|
||||
@ -183,10 +183,10 @@ This proposal also modifies the fifth bullet to read as follows:
|
||||
|
||||
* Otherwise, let `rule-config` be `config`.
|
||||
|
||||
* Let `forwarded` be the result of [loading][] the module with `rule`'s URL
|
||||
* Let `forwarded` be the result of [loading] the module with `rule`'s URL
|
||||
and `rule-config`.
|
||||
|
||||
* [Forward `forwarded`][] with `file` through `module`.
|
||||
* [Forward `forwarded`] with `file` through `module`.
|
||||
|
||||
[Executing Files]: ../accepted/module-system.md#executing-files
|
||||
[loading]: ../accepted/module-system.md#loading-modules
|
||||
@ -194,11 +194,11 @@ This proposal also modifies the fifth bullet to read as follows:
|
||||
|
||||
### Importing Files
|
||||
|
||||
This proposal modifies the semantics for [Importing Files][] within the
|
||||
[module system spec][] to read as follows:
|
||||
This proposal modifies the semantics for [Importing Files] within the
|
||||
[module system spec] to read as follows:
|
||||
|
||||
This algorithm takes a [source file][] `file`, an [import context][] `import`,
|
||||
and a mutable [module][] `module`.
|
||||
This algorithm takes a [source file] `file`, an [import context] `import`,
|
||||
and a mutable [module] `module`.
|
||||
|
||||
* If `file` is currently being executed, throw an error.
|
||||
|
||||
@ -209,19 +209,19 @@ and a mutable [module][] `module`.
|
||||
> used, so implementations may wish to skip this step and use the empty
|
||||
> configuration instead in that case for performance reasons.
|
||||
|
||||
* Let `imported` be the result of [executing][] `file` with ~~the empty
|
||||
* Let `imported` be the result of [executing] `file` with ~~the empty
|
||||
configuration~~ **`config` as its configuration** and `import` as
|
||||
its import context, except that if the `@import` rule is nested within
|
||||
at-rules and/or style rules, that context is preserved when executing `file`.
|
||||
|
||||
* Let `css` be the result of [resolving extensions][] for
|
||||
* Let `css` be the result of [resolving extensions] for
|
||||
`imported`, except that if the `@import` rule is nested within at-rules and/or
|
||||
style rules, that context is added to CSS that comes from modules loaded by
|
||||
`imported`.
|
||||
|
||||
* Add `css` to `module`'s CSS.
|
||||
|
||||
* Add `imported`'s [extensions][] to `module`.
|
||||
* Add `imported`'s [extensions] to `module`.
|
||||
|
||||
* Add each member in `imported` to `import` and `module`.
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
*([Issue](https://github.com/sass/sass/issues/1864), [Changelog](media-ranges.changes.md))*
|
||||
|
||||
This proposal defines how Sass handles media queries with features written in a
|
||||
[range context][].
|
||||
[range context].
|
||||
|
||||
[range context]: https://www.w3.org/TR/mediaqueries-4/#mq-range-context
|
||||
|
||||
@ -34,7 +34,7 @@ complexity to media merging, for very limited benefits in terms of output size
|
||||
and readability.
|
||||
|
||||
The values of media features with the "range" type are heterogeneous, including
|
||||
a [`<ratio>`][] type value type that Sass has no existing knowledge of. If Sass
|
||||
a [`<ratio>`] type value type that Sass has no existing knowledge of. If Sass
|
||||
were to support intelligent merging of these features, it would need to keep
|
||||
abreast of any new value types supported by "range"-type media features. This
|
||||
would violate Sass's general design principle of knowing as little about CSS as
|
||||
@ -54,7 +54,7 @@ plain CSS.
|
||||
This proposal defines a new syntax for media queries in Sass stylesheets. It is
|
||||
intended to replace the existing syntax.
|
||||
|
||||
> Other than support for the [range context][] syntax, this syntax is designed
|
||||
> Other than support for the [range context] syntax, this syntax is designed
|
||||
> to represent the current behavior of all Sass implementations.
|
||||
|
||||
<x><pre>
|
||||
@ -76,13 +76,13 @@ operators `=`, `>`, `>=`, `<`, or `<=`, except within parentheses (including
|
||||
function calls and map literals) and square brackets.
|
||||
|
||||
The `<mf-comparison>`, `<mf-lt>`, and `<mf-gt>` productions are defined in
|
||||
[Media Queries Level 4][].
|
||||
[Media Queries Level 4].
|
||||
|
||||
[Media Queries Level 4]: https://drafts.csswg.org/mediaqueries-4/#mq-syntax
|
||||
|
||||
> Note that Sass currently doesn't support parsing full media conditions
|
||||
> according to the level 4 specification, since no browsers support it yet. See
|
||||
> [sass/sass#2538][] for details.
|
||||
> [sass/sass#2538] for details.
|
||||
|
||||
[sass/sass#2538]: https://github.com/sass/sass/issues/2538
|
||||
|
||||
@ -105,7 +105,7 @@ Plain CSS media queries are parsed using the following syntax:
|
||||
The `<ident-token>` production matches the [railroad diagram][ident-token]
|
||||
listed in CSS Syntax Level 3. The `<declaration-value>` production uses
|
||||
[the definition][declaration-value] from CSS Syntax Level 3,
|
||||
[consuming tokens][] only as needed until the production terminates.
|
||||
[consuming tokens] only as needed until the production terminates.
|
||||
|
||||
[ident-token]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
[declaration-value]: https://drafts.csswg.org/css-syntax-3/#typedef-declaration-value
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
*([Issue](https://github.com/sass/sass/issues/2378), [Changelog](min-max.changes.md))*
|
||||
|
||||
This proposal defines how Sass handles CSS's `min()` and `max()`
|
||||
[math functions][].
|
||||
[math functions].
|
||||
|
||||
[math functions]: https://drafts.csswg.org/css-values/#math-function
|
||||
|
||||
@ -20,7 +20,7 @@ This proposal defines how Sass handles CSS's `min()` and `max()`
|
||||
|
||||
Since Ruby Sass 3.2, Sass has provided `min()` and `max()` functions that return
|
||||
the minimum or maximum values among a set of SassScript numbers. Later, CSS
|
||||
Values and Units Level 4 added support for additional [math functions][] with
|
||||
Values and Units Level 4 added support for additional [math functions] with
|
||||
special syntax like that in `calc()`, among which were `min()` and `max()`.
|
||||
|
||||
This presents a problem for Sass: to retain backwards-compatibility with
|
||||
@ -29,7 +29,7 @@ functions. However, to provide compatibility with CSS, it must also support them
|
||||
as math functions with special syntax.
|
||||
|
||||
Support for CSS's `min()` and `max()` has landed in real browsers and
|
||||
[Sass users want to use it][], so this should be solved with some urgency.
|
||||
[Sass users want to use it], so this should be solved with some urgency.
|
||||
|
||||
[Sass users want to use it]: https://github.com/sass/sass/issues/2378#issuecomment-367490840
|
||||
|
||||
|
||||
@ -203,7 +203,7 @@
|
||||
the current stylesheet.
|
||||
|
||||
* Removed the low-level "using CSS files" goal, since this is now covered by
|
||||
[the CSS Imports proposal][].
|
||||
[the CSS Imports proposal].
|
||||
|
||||
[the CSS Imports proposal]: ../accepted/css-imports.md
|
||||
|
||||
@ -224,7 +224,7 @@
|
||||
|
||||
* Refer to "namespaces" rather than "prefixes".
|
||||
|
||||
* Refer to "URLs" rather than "URIs", per [the URL spec][].
|
||||
* Refer to "URLs" rather than "URIs", per [the URL spec].
|
||||
|
||||
[the URL spec]: https://url.spec.whatwg.org/#goals
|
||||
|
||||
|
||||
@ -525,7 +525,7 @@ file](#source-file) identified by the module's canonical URL with a
|
||||
### Module Graph
|
||||
|
||||
Modules also track their `@use` and `@forward` at-rules, which point to other
|
||||
modules. In this sense, modules can be construed as a [directed acyclic graph][]
|
||||
modules. In this sense, modules can be construed as a [directed acyclic graph]
|
||||
where the vertices are modules and the edges are `@use` rules and/or `@forward`
|
||||
rules. We call this the *module graph*.
|
||||
|
||||
@ -592,7 +592,7 @@ The new at-rule will be called `@use`. The grammar for this rule is as follows:
|
||||
|
||||
`@use` rules must be at the top level of the document, and must come before any
|
||||
rules other than `@charset` or `@forward`. The `QuotedString`'s contents, known
|
||||
as the rule's *URL*, must be a [valid URL string][] (for non-[special][special
|
||||
as the rule's *URL*, must be a [valid URL string] (for non-[special][special
|
||||
URL scheme] base URL). No whitespace is allowed after `$` in `KeywordArgument`.
|
||||
|
||||
[valid URL string]: https://url.spec.whatwg.org/#valid-url-string
|
||||
@ -637,7 +637,7 @@ grammar for this rule is as follows:
|
||||
|
||||
`@forward` rules must be at the top level of the document, and must come before
|
||||
any rules other than `@charset` or `@use`. If they have a `QuotedString`, its
|
||||
contents, known as the rule's *URL*, must be a [valid URL string][] (for
|
||||
contents, known as the rule's *URL*, must be a [valid URL string] (for
|
||||
non-[special][special URL scheme] base URL). No whitespace is allowed after `$`
|
||||
in `MemberName`, or before `*` in `AsClause`.
|
||||
|
||||
@ -648,7 +648,7 @@ mixins, this update affects only calls, not definitions. Variables, on the other
|
||||
hand, may use this syntax for either assignment or reference.
|
||||
|
||||
<x><pre>
|
||||
**PublicIdentifier** ::= [\<ident-token>][] that doesn't begin with '-' or '_'
|
||||
**PublicIdentifier** ::= [\<ident-token>] that doesn't begin with '-' or '_'
|
||||
**Variable** ::= '$' Identifier | Identifier '.$' PublicIdentifier
|
||||
**NamespacedIdentifier** ::= Identifier | Identifier '.' PublicIdentifier
|
||||
**FunctionCall** ::= NamespacedIdentifier ArgumentInvocation
|
||||
@ -800,7 +800,7 @@ CSS for *all* modules transitively used or forwarded by `starting-module`.
|
||||
* Let `extended` be the subgraph of the [module graph](#module-graph) containing
|
||||
modules that are transitively reachable from `starting-module`.
|
||||
|
||||
* For each module `domestic` in `extended`, in reverse [topological][] order:
|
||||
* For each module `domestic` in `extended`, in reverse [topological] order:
|
||||
|
||||
* Let `downstream` be the set of modules that use or forward `domestic`.
|
||||
|
||||
@ -832,7 +832,7 @@ CSS for *all* modules transitively used or forwarded by `starting-module`.
|
||||
|
||||
* Set `new-selectors[rule]` to a selector that matches the union of all
|
||||
elements matched by selectors in `selector-lists`. This selector must obey
|
||||
[the specificity laws of extend][] relative to the selectors from which it
|
||||
[the specificity laws of extend] relative to the selectors from which it
|
||||
was generated. For the purposes of the first law of extend, "the original
|
||||
extendee" is considered only to refer to selectors that appear in
|
||||
`domestic`'s CSS, *not* selectors that were added by other modules'
|
||||
@ -891,7 +891,7 @@ CSS for *all* modules transitively used or forwarded by `starting-module`.
|
||||
|
||||
### Resolving a `file:` URL
|
||||
|
||||
This algorithm is intended to replace [the existing algorithm][] for resolving a
|
||||
This algorithm is intended to replace [the existing algorithm] for resolving a
|
||||
`file:` URL to add support for `@import`-only files, and to allow imports that
|
||||
include a literal `.css` extension. This algorithm takes a URL, `url`, whose
|
||||
scheme must be `file` and returns either another URL that's guaranteed to point
|
||||
@ -1092,7 +1092,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
|
||||
|
||||
* Let `css` be the result of executing the rule as normal.
|
||||
|
||||
* Remove any [complex selectors][] containing a placeholder selector that
|
||||
* Remove any [complex selectors] containing a placeholder selector that
|
||||
begins with `-` or `_` from `css`.
|
||||
|
||||
* Remove any style rules that now have no selector from `css`.
|
||||
@ -1180,7 +1180,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
|
||||
>
|
||||
> without needing to use `!global`.
|
||||
|
||||
* Otherwise, if no block containing `declaration` has a [scope][] with a
|
||||
* Otherwise, if no block containing `declaration` has a [scope] with a
|
||||
variable named `name`, set the innermost block's scope's variable `name` to
|
||||
`value`.
|
||||
|
||||
@ -1204,7 +1204,7 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
|
||||
|
||||
* When a member use `member` is encountered:
|
||||
|
||||
* Let `scope` be the [scope][] of the innermost block containing `member` such
|
||||
* Let `scope` be the [scope] of the innermost block containing `member` such
|
||||
that `scope` has a member of `member`'s name and type, or `null` if no such
|
||||
scope exists.
|
||||
|
||||
@ -1223,14 +1223,14 @@ Given a source file `file`, a [configuration](#configuration) `config`, and an
|
||||
yet in `module`, set `variable` to `null` in `module`.
|
||||
|
||||
> This isn't necessary for implementations that follow the most recent
|
||||
> [variables spec][] and don't allow `!global` assignments to variables
|
||||
> [variables spec] and don't allow `!global` assignments to variables
|
||||
> that don't yet exist. However, at time of writing, all existing
|
||||
> implementations are in the process of deprecating the old `!global`
|
||||
> behavior, which allowed `!global` declarations to create new
|
||||
> variables.
|
||||
>
|
||||
> Setting all `!global` variables to `null` if they weren't otherwise set
|
||||
> guarantees [static analysis][] by ensuring that the set of variables a
|
||||
> guarantees [static analysis] by ensuring that the set of variables a
|
||||
> module exposes doesn't depend on how it was executed.
|
||||
|
||||
* Return `module`. Its functions, mixins, and CSS are now immutable.
|
||||
@ -1476,7 +1476,7 @@ context](#import-context) `import`, and a mutable [module](#module) `module`.
|
||||
* Add `imported`'s [extensions](#extension) to `module`.
|
||||
|
||||
* If the `@import` rule is nested within at-rules and/or style rules, add each
|
||||
member in `imported` to the local [scope][].
|
||||
member in `imported` to the local [scope].
|
||||
|
||||
* Otherwise, add each member in `imported` to `import` and `module`.
|
||||
|
||||
|
||||
@ -44,7 +44,7 @@ available on the global namespace.
|
||||
> This section is non-normative.
|
||||
|
||||
This proposal defines Sassified versions of all the mathematical functions in
|
||||
the [CSS Values and Units 4 Draft][], as well as logarithms and the constants
|
||||
the [CSS Values and Units 4 Draft], as well as logarithms and the constants
|
||||
`e` and `pi`. Each function is basically equivalent to its mathematical form,
|
||||
with stricter unit handling. Proper unit handling prevents these functions from
|
||||
creating meaningless units. For instance, consider `(1px)^(1/3)`—what does
|
||||
@ -56,7 +56,7 @@ To avoid issues like this, the exponential functions—`log()`, `pow()`, `sqrt()
|
||||
accept only a unitless number as input, and output a unitless number.
|
||||
|
||||
The trig functions—`cos()`, `sin()`, `tan()`—accept a SassScript number with a
|
||||
unit, as long as that unit is an [angle][] type. If the input is a unitless
|
||||
unit, as long as that unit is an [angle] type. If the input is a unitless
|
||||
number, it is treated as though it were in `rad`. These functions output a
|
||||
unitless number.
|
||||
|
||||
@ -66,7 +66,7 @@ The inverse trig functions—`acos()`, `asin()`, `atan()`—accept a unitless nu
|
||||
and output a SassScript number in `deg`. `atan2()` is similar, but it accepts
|
||||
two unitless numbers.
|
||||
|
||||
`clamp()` accepts three SassScript numbers with [compatible][] units: the
|
||||
`clamp()` accepts three SassScript numbers with [compatible] units: the
|
||||
minimum value, preferred value, and maximum value. This function "clamps" the
|
||||
preferred value in between the minimum and maximum values, while preserving
|
||||
their units appropriately. For example, `clamp(1in, 15cm, 12in)` outputs `15cm`,
|
||||
@ -84,8 +84,8 @@ of the first input.
|
||||
### Built-in Module Variables
|
||||
|
||||
Variables defined in built-in modules are not modifiable. As such, this proposal
|
||||
modifies the semantics of [Executing a Variable Declaration][] within the
|
||||
[Variables spec][] to read as follows:
|
||||
modifies the semantics of [Executing a Variable Declaration] within the
|
||||
[Variables spec] to read as follows:
|
||||
|
||||
[Executing a Variable Declaration]: ../spec/variables.md#executing-a-variable-declaration
|
||||
[Variables spec]: ../spec/variables.md
|
||||
@ -96,7 +96,7 @@ To execute a `VariableDeclaration` `declaration`:
|
||||
|
||||
* Let `name` be `declaration`'s `Variable`.
|
||||
|
||||
* **Let `resolved` be the result of [resolving a variable][] named `name`.**
|
||||
* **Let `resolved` be the result of [resolving a variable] named `name`.**
|
||||
|
||||
[resolving a variable]: ../spec/modules.md#resolving-a-member
|
||||
|
||||
@ -109,7 +109,7 @@ To execute a `VariableDeclaration` `declaration`:
|
||||
* Otherwise, if `declaration` is outside of any block of statements, *or*
|
||||
`declaration` has a `!global` flag, *or* `name` is a `NamespacedVariable`:
|
||||
|
||||
* ~~Let `resolved` be the result of [resolving a variable][] named `name` using
|
||||
* ~~Let `resolved` be the result of [resolving a variable] named `name` using
|
||||
`file`, `uses`, and `import`.~~
|
||||
|
||||
(...)
|
||||
@ -117,11 +117,11 @@ To execute a `VariableDeclaration` `declaration`:
|
||||
* Otherwise, if `declaration` is within one or more blocks associated with
|
||||
`@if`, `@each`, `@for`, and/or `@while` rules *and no other blocks*:
|
||||
|
||||
* ~~Let `resolved` be the result of [resolving a variable][] named `name`.~~
|
||||
* ~~Let `resolved` be the result of [resolving a variable] named `name`.~~
|
||||
|
||||
(...)
|
||||
|
||||
* ~~Otherwise, if no block containing `declaration` has a [scope][] with a
|
||||
* ~~Otherwise, if no block containing `declaration` has a [scope] with a
|
||||
variable named `name`, set the innermost block's scope's variable `name` to
|
||||
`value`.~~
|
||||
|
||||
@ -189,7 +189,7 @@ log($number, $base: null)
|
||||
* If `$number < 0`, return `NaN` as a unitless number.
|
||||
* If `$number == 0`, return `-Infinity` as a unitless number.
|
||||
* If `$number == Infinity`, return `Infinity` as a unitless number.
|
||||
* Return the [natural log][] of `$number`, as a unitless number.
|
||||
* Return the [natural log] of `$number`, as a unitless number.
|
||||
* Otherwise, return the natural log of `$number` divided by the natural log of
|
||||
`$base`, as a unitless number.
|
||||
|
||||
@ -259,7 +259,7 @@ cos($number)
|
||||
* If `$number` is unitless, treat it as though its unit were `rad`.
|
||||
* If `$number == Infinity` or `$number == -Infinity`, return `NaN` as a unitless
|
||||
number.
|
||||
* Return the [cosine][] of `$number`, as a unitless number.
|
||||
* Return the [cosine] of `$number`, as a unitless number.
|
||||
|
||||
[cosine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
|
||||
|
||||
@ -275,7 +275,7 @@ sin($number)
|
||||
number.
|
||||
* If `$number == -0`, return `-0` as a unitless number.
|
||||
* If `$number == 0`, return `0` as a unitless number.
|
||||
* Return the [sine][] of `$number`, as a unitless number.
|
||||
* Return the [sine] of `$number`, as a unitless number.
|
||||
|
||||
[sine]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
|
||||
|
||||
@ -295,7 +295,7 @@ tan($number)
|
||||
integer, return `Infinity` as a unitless number.
|
||||
* If `$number` is equivalent to `-90deg +/- 360deg * n`, where `n` is any
|
||||
integer, return `-Infinity` as a unitless number.
|
||||
* Return the [tangent][] of `$number`, as a unitless number.
|
||||
* Return the [tangent] of `$number`, as a unitless number.
|
||||
|
||||
[tangent]: https://en.wikipedia.org/wiki/Trigonometric_functions#Right-angled_triangle_definitions
|
||||
|
||||
@ -308,7 +308,7 @@ acos($number)
|
||||
* If `$number` has units, throw an error.
|
||||
* If `$number < -1` or `$number > 1`, return `NaN` as a number in `deg`.
|
||||
* If `$number == 1`, return `0deg`.
|
||||
* Return the [arccosine][] of `$number`, as a number in `deg`.
|
||||
* Return the [arccosine] of `$number`, as a number in `deg`.
|
||||
|
||||
[arccosine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
|
||||
|
||||
@ -322,7 +322,7 @@ asin($number)
|
||||
* If `$number < -1` or `$number > 1`, return `NaN` as a number in `deg`.
|
||||
* If `$number == -0`, return `-0deg`.
|
||||
* If `$number == 0`, return `0deg`.
|
||||
* Return the [arcsine][] of `$number`, as a number in `deg`.
|
||||
* Return the [arcsine] of `$number`, as a number in `deg`.
|
||||
|
||||
[arcsine]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
|
||||
|
||||
@ -337,7 +337,7 @@ atan($number)
|
||||
* If `$number == 0`, return `0deg`.
|
||||
* If `$number == -Infinity`, return `-90deg`.
|
||||
* If `$number == Infinity`, return `90deg`.
|
||||
* Return the [arctangent][] of `$number`, as a number in `deg`.
|
||||
* Return the [arctangent] of `$number`, as a number in `deg`.
|
||||
|
||||
[arctangent]: https://en.wikipedia.org/wiki/Inverse_trigonometric_functions#Basic_properties
|
||||
|
||||
@ -355,7 +355,7 @@ atan2($y, $x)
|
||||
* If `$y` and `$x` are not compatible, throw an error.
|
||||
* If `$y` has units and `$x` does not, or vice-versa, throw an error.
|
||||
* If the inputs match one of the following edge cases, return the provided
|
||||
number. Otherwise, return the [2-argument arctangent][] of `$y` and `$x`, as a
|
||||
number. Otherwise, return the [2-argument arctangent] of `$y` and `$x`, as a
|
||||
number in `deg`.
|
||||
|
||||
[2-argument arctangent]: https://en.wikipedia.org/wiki/Atan2
|
||||
|
||||
@ -14,7 +14,7 @@
|
||||
|
||||
> This section is non-normative.
|
||||
|
||||
In the new Sass [module system][] as written, the implicit namespace of a `@use`
|
||||
In the new Sass [module system] as written, the implicit namespace of a `@use`
|
||||
rule that loads a partial with an explicit leading underscore contains that
|
||||
underscore. This was unintended and confusing, making the namespace look like a
|
||||
private identifier and making it different than the same file's namespace
|
||||
@ -34,7 +34,7 @@ have the implicit namespace `styles` rather than `_styles`.
|
||||
### Determining a `@use` Rule's Namespace
|
||||
|
||||
This modifies the existing algorithm for [Determining a `@use` Rule's
|
||||
Namespace][] to read as follows (new text in bold):
|
||||
Namespace] to read as follows (new text in bold):
|
||||
|
||||
[Determining a `@use` Rule's Namespace]: ../spec/at-rules/use.md#determining-a-use-rules-namespace
|
||||
|
||||
|
||||
@ -126,7 +126,7 @@ To execute a style rule `rule`:
|
||||
|
||||
[bogus]: ../spec/selectors.md#bogus-selector
|
||||
|
||||
* Remove any [complex selectors][] containing a placeholder selector that
|
||||
* Remove any [complex selectors] containing a placeholder selector that
|
||||
begins with `-` or `_` from `css`'s selector.
|
||||
|
||||
[complex selectors]: https://drafts.csswg.org/selectors-4/#complex
|
||||
|
||||
@ -44,13 +44,13 @@ Early on in Sass's history, the decision was made to use `/` as a division
|
||||
operator, since that was (and is) by far the most common representation across
|
||||
programming languages. The `/` character was used in very few plain CSS
|
||||
properties, and for those it was an optional shorthand. So Sass defined [a set
|
||||
of heuristics][] that defined when `/` would be rendered as a literal slash
|
||||
of heuristics] that defined when `/` would be rendered as a literal slash
|
||||
versus treated as an operator.
|
||||
|
||||
[a set of heuristics]: https://sass-lang.com/documentation/operators/numeric#slash-separated-values
|
||||
|
||||
For a long time, these heuristics worked pretty well. In recent years, however,
|
||||
new additions to CSS such as [CSS Grid][] and [CSS Color Level 4][] have been
|
||||
new additions to CSS such as [CSS Grid] and [CSS Color Level 4] have been
|
||||
using `/` as a separator increasingly often. Using the same character for both
|
||||
division and slash-separation is becoming more and more annoying to users, and
|
||||
will likely eventually become untenable.
|
||||
@ -124,7 +124,7 @@ efficient to write than a function call for many Sass users.
|
||||
We eventually want to add native Sass support for parsing `calc()` expressions,
|
||||
resolving them at compile-time if possible, and producing a new Sass value that
|
||||
can have arithmetic performed on it if necessary. This is known as [first-class
|
||||
`calc()`][], and it would mean that division could be written unambiguously
|
||||
`calc()`], and it would mean that division could be written unambiguously
|
||||
using `/` in the context of a `calc()` expression. For example, `$width / 2`
|
||||
would be instead written `calc($width / 2)`.
|
||||
|
||||
@ -132,7 +132,7 @@ would be instead written `calc($width / 2)`.
|
||||
|
||||
However, first-class `calc()` is likely to be a very complex feature to design
|
||||
and implement. Most of the resources available for large-scale language features
|
||||
are currently focused on [the new module system][], so it's likely that a full
|
||||
are currently focused on [the new module system], so it's likely that a full
|
||||
implementation of first-class `calc()` won't land until mid-to-late 2020. And
|
||||
the full implementation is a prerequisite for even *beginning* the deprecation
|
||||
cycle for `/`-as-division, which means we probably wouldn't fully support
|
||||
@ -236,7 +236,7 @@ support for slash-separated lists. The new grammar for this production is:
|
||||
> This defines `/` to bind tighter than `,` but looser than space-separated
|
||||
> lists. This was chosen because most common uses of `/` in CSS conceptually
|
||||
> bind looser than space-separated values. The only exception is the [`font`
|
||||
> shorthand syntax][], which is used much more rarely will still work (albeit
|
||||
> shorthand syntax], which is used much more rarely will still work (albeit
|
||||
> with an unintuitive SassScript representation) with a loose-binding `/`.
|
||||
>
|
||||
> [`font` shorthand syntax]: https://developer.mozilla.org/en-US/docs/Web/CSS/font
|
||||
@ -374,7 +374,7 @@ overload to be the following:
|
||||
|
||||
[old rgb]: ../spec/functions.md#rgb-and-rgba
|
||||
|
||||
* If `$channels` is a [special variable string][], return a plain CSS function
|
||||
* If `$channels` is a [special variable string], return a plain CSS function
|
||||
string with the name `"rgb"` and the argument `$channels`.
|
||||
|
||||
[special variable string]: ../spec/functions.md#special-variable-string
|
||||
@ -393,7 +393,7 @@ overload to be the following:
|
||||
|
||||
* If `rgb` has fewer than three elements:
|
||||
|
||||
* If any element of `rgb` is a [special variable string][], return a
|
||||
* If any element of `rgb` is a [special variable string], return a
|
||||
plain CSS function string with the name `"rgb"` and the argument
|
||||
`$channels`.
|
||||
|
||||
@ -418,7 +418,7 @@ overload to be the following:
|
||||
|
||||
[old hsl]: ../spec/functions.md#hsl-and-hsla
|
||||
|
||||
* If `$channels` is a [special variable string][], return a plain CSS function
|
||||
* If `$channels` is a [special variable string], return a plain CSS function
|
||||
string with the name `"hsl"` and the argument `$channels`.
|
||||
|
||||
* If `$channels` is an unbracketed slash-separated list:
|
||||
@ -435,7 +435,7 @@ overload to be the following:
|
||||
|
||||
* If `hsl` has fewer than three elements:
|
||||
|
||||
* If any element of `hsl` is a [special variable string][], return a
|
||||
* If any element of `hsl` is a [special variable string], return a
|
||||
plain CSS function string with the name `"hsl"` and the argument
|
||||
`$channels`.
|
||||
|
||||
@ -451,7 +451,7 @@ overload to be the following:
|
||||
### Selector Functions
|
||||
|
||||
This proposal modifies [the "Parse a Selector From a SassScript Object"
|
||||
procedure][] to throw an error whenever it encounters a slash-separated list.
|
||||
procedure] to throw an error whenever it encounters a slash-separated list.
|
||||
|
||||
[the "Parse a Selector From a SassScript Object" procedure]: ../spec/built-in-modules/selector.md#parse-a-selector-from-a-sassscript-object
|
||||
|
||||
@ -531,7 +531,7 @@ described above (so `math.div()` will only accept numbers). In phase 2, the
|
||||
`list.slash()` function will emit a deprecation warning whenever it's called.
|
||||
|
||||
> It's recommended that implementations increment their major version numbers
|
||||
> with the release of phase 2, in accordance with [semantic versioning][].
|
||||
> with the release of phase 2, in accordance with [semantic versioning].
|
||||
>
|
||||
> [semantic versioning]: https://semver.org/
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
*([Issue](https://github.com/sass/sass/issues/2780), [Changelog](supports-general.changes.md))*
|
||||
|
||||
This proposal defines how Sass parses supports queries that use the
|
||||
[`<general-enclosed>`][] production.
|
||||
[`<general-enclosed>`] production.
|
||||
|
||||
[`<general-enclosed>`]: https://drafts.csswg.org/mediaqueries-4/#typedef-general-enclosed
|
||||
|
||||
@ -24,13 +24,13 @@ This proposal defines how Sass parses supports queries that use the
|
||||
> This section is non-normative.
|
||||
|
||||
Historically, Sass has supported the `@supports` condition syntax as defined in
|
||||
[the April 2013 CSS Conditional Rules Level 3 Candidate Recommendation][], with
|
||||
[the April 2013 CSS Conditional Rules Level 3 Candidate Recommendation], with
|
||||
the addition of supporting raw SassScript expressions in the declaration syntax.
|
||||
The [Editor's Draft][] (as published October 2019) expands this syntax with a
|
||||
The [Editor's Draft] (as published October 2019) expands this syntax with a
|
||||
`<general-enclosed>` production to ensure parser forwards-compatibility with
|
||||
future CSS, which Sass does not yet support. The [Level 4 Editor's Draft][] (as
|
||||
future CSS, which Sass does not yet support. The [Level 4 Editor's Draft] (as
|
||||
of March 2019) further adds a `selector()` function syntax (which is covered by
|
||||
`<general-enclosed>`), which is [supported by Firefox][] as of version 69.
|
||||
`<general-enclosed>`), which is [supported by Firefox] as of version 69.
|
||||
|
||||
[the April 2013 CSS Conditional Rules Level 3 Candidate Recommendation]: https://www.w3.org/TR/2013/CR-css3-conditional-20130404/#at-supports
|
||||
[Editor's Draft]: https://drafts.csswg.org/css-conditional-3/#at-supports
|
||||
@ -93,10 +93,10 @@ expression. If not, Sass must continually update its syntax to support new CSS
|
||||
constructs.
|
||||
|
||||
We've been burned by this in the past. Both this proposal and the [media ranges
|
||||
proposal][] would have been unnecessary (or at least much simpler) if the rules
|
||||
proposal] would have been unnecessary (or at least much simpler) if the rules
|
||||
in questions had only allowed SassScript via interpolation in the first place.
|
||||
And it's likely that this syntax *will* evolve in ways that aren't
|
||||
SassScript-compatible, as with the `selector()` function [mentioned above][].
|
||||
SassScript-compatible, as with the `selector()` function [mentioned above].
|
||||
|
||||
[media ranges proposal]: ../accepted/media-ranges.md
|
||||
[mentioned above]: #background
|
||||
@ -139,8 +139,8 @@ ambiguous with a declaration and thus with raw SassScript.
|
||||
**SupportsInParens** ::= '(' (SupportsCondition | SupportsDeclaration | SupportsAnything) ')'
|
||||
  | SupportsFunction | Interpolation
|
||||
**SupportsDeclaration** ::= Expression¹ ':' Expression
|
||||
**SupportsAnything** ::= [InterpolatedIdentifier][]² [InterpolatedAnyValue][]³?
|
||||
**SupportsFunction** ::= [InterpolatedIdentifier][]⁴ '(' [InterpolatedAnyValue][]? ')'
|
||||
**SupportsAnything** ::= [InterpolatedIdentifier]² [InterpolatedAnyValue]³?
|
||||
**SupportsFunction** ::= [InterpolatedIdentifier]⁴ '(' [InterpolatedAnyValue]? ')'
|
||||
</pre></x>
|
||||
|
||||
[InterpolatedIdentifier]: ../spec/syntax.md#interpolatedidentifier
|
||||
@ -168,7 +168,7 @@ the purposes of this production.
|
||||
|
||||
### `InterpolatedAnyValue`
|
||||
|
||||
The `InterpolatedAnyValue` production is identical to CSS's [`<any-value>`][]
|
||||
The `InterpolatedAnyValue` production is identical to CSS's [`<any-value>`]
|
||||
except that after it parses `"#{"`, it parses an `Expression` which must be
|
||||
followed by `"}"`.
|
||||
|
||||
|
||||
@ -1 +0,0 @@
|
||||
spec.md
|
||||
230
spec/README.md
Normal file
230
spec/README.md
Normal file
@ -0,0 +1,230 @@
|
||||
# Sass Specification
|
||||
|
||||
This directory contains the formal specification for the Sass language.
|
||||
|
||||
Sass is a *living specification*, which means that it's actively updated over
|
||||
time without having distinctions between numbered versions. Different
|
||||
implementations may support different subsets of the specification, although all
|
||||
implementations are expected to work towards full support. The *reference
|
||||
implementation* (currently [Dart Sass]) will generally support as close to the
|
||||
full spec as possible.
|
||||
|
||||
[Dart Sass]: https://sass-lang.com/dart-sass
|
||||
|
||||
This specification is incomplete, and is added to *lazily*. This means that
|
||||
portions of the spec are only written when they're necessary as background for
|
||||
new language proposals. The Sass team eventually hopes to specify every part of
|
||||
the language this way.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [Definitions](#definitions)
|
||||
* [Scope](#scope)
|
||||
* [Global Scope](#global-scope)
|
||||
* [Current Source File](#current-source-file)
|
||||
* [Current Configuration](#current-configuration)
|
||||
* [Current Import Context](#current-import-context)
|
||||
* [Current Module](#current-module)
|
||||
* [Procedures](#procedures)
|
||||
* [Running in a New Scope](#running-in-a-new-scope)
|
||||
* [Semantics](#semantics)
|
||||
* [Compiling a Path](#compiling-a-path)
|
||||
* [Compiling a String](#compiling-a-string)
|
||||
* [Executing a File](#executing-a-file)
|
||||
|
||||
## Definitions
|
||||
|
||||
### Scope
|
||||
|
||||
A *scope* is a mutable structure that contains:
|
||||
|
||||
* The scope's *variables*: a mapping from identifiers to SassScript values.
|
||||
* The scope's *mixins*: a mapping from identifiers to mixins.
|
||||
* The scope's *functions*: a mapping from identifiers to functions.
|
||||
* The scope's *parent*: a reference to another scope, which may be unset.
|
||||
|
||||
One scope at a time is designated the *current scope*. By default, this is the
|
||||
[global scope](#global-scope).
|
||||
|
||||
### Global Scope
|
||||
|
||||
The *global scope* is the scope shared among the top level of all Sass files. It
|
||||
has no parent.
|
||||
|
||||
### Current Source File
|
||||
|
||||
The *current source file* is the [source file] that was passed to the innermost
|
||||
active invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[source file]: syntax.md#source-file
|
||||
|
||||
*All current source files* refer to all the source files passed to any active
|
||||
invocation of Executing a File.
|
||||
|
||||
### Current Configuration
|
||||
|
||||
The *current configuration* is the [configuration] that was passed to the
|
||||
innermost active invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[configuration]: modules.md#configuration
|
||||
|
||||
### Current Import Context
|
||||
|
||||
The *current import context* is the [import context] that was passed to the
|
||||
innermost active invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[import context]: modules.md#import-context
|
||||
|
||||
### Current Module
|
||||
|
||||
The *current module* is the [module] that was created by the innermost active
|
||||
invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[module]: modules.md#module
|
||||
|
||||
> Because a module is only made immutable (other than its variables) when
|
||||
> execution has finished, the current module is always mutable.
|
||||
|
||||
## Procedures
|
||||
|
||||
### Running in a New Scope
|
||||
|
||||
To run a set of steps *in a new scope*:
|
||||
|
||||
* Let `parent` be the [current scope].
|
||||
|
||||
[current scope]: #scope
|
||||
|
||||
* Return the result of running the given steps with the current scope set to an
|
||||
empty scope with `parent` as its parent.
|
||||
|
||||
## Semantics
|
||||
|
||||
### Compiling a Path
|
||||
|
||||
> This an entrypoint to the specification; it's up to each implementation how it
|
||||
> exposes this to the user.
|
||||
|
||||
This algorithm takes a local filesystem path `path`, an optional list of
|
||||
[importers] `importers`, and an optional list of paths `load-paths`. It returns
|
||||
a string.
|
||||
|
||||
* Let `text` be the result of decoding the binary contents of the file at
|
||||
`path`.
|
||||
|
||||
* Let `syntax` be:
|
||||
|
||||
* "indented" if `path` ends in `.sass`.
|
||||
* "css" if `path` ends in `.css`.
|
||||
* "scss" otherwise.
|
||||
|
||||
* Let `url` be the absolute `file:` URL corresponding to `path`.
|
||||
|
||||
* Let `importer` be a [filesystem importer] with an arbitrary `base`.
|
||||
|
||||
> This importer will only ever be passed absolute URLs, so its base won't
|
||||
> matter.
|
||||
|
||||
* Return the result of [compiling](#compiling-a-string) `text` with `syntax`,
|
||||
`url`, `importer`, `importers`, and `load-paths`.
|
||||
|
||||
[importers]: modules.md#importer
|
||||
|
||||
### Compiling a String
|
||||
|
||||
> This an entrypoint to the specification; it's up to each implementation how it
|
||||
> exposes this to the user.
|
||||
|
||||
This algorithm takes:
|
||||
|
||||
* a string `string`,
|
||||
* a syntax `syntax` ("indented", "scss", or "css"),
|
||||
* an optional URL `url`,
|
||||
* an optional [importer] `importer`,
|
||||
* an optional list of importers `importers`,
|
||||
* and an optional list of paths `load-paths`.
|
||||
|
||||
[importer]: modules.md#importer
|
||||
|
||||
It runs as follows:
|
||||
|
||||
* Set the [global importer list] to `importers`.
|
||||
|
||||
* For each `path` in `load-paths`:
|
||||
|
||||
* Let `base` be the absolute `file:` URL that refers to `path`.
|
||||
|
||||
* Add a [filesystem importer] with base `base` to the global importer list.
|
||||
|
||||
* Let `ast` be the result of [parsing] `text` as `syntax`.
|
||||
|
||||
* If `url` is null:
|
||||
|
||||
* If `importer` is not null, throw an error.
|
||||
|
||||
* Set `url` to a unique value.
|
||||
|
||||
> This ensures that all source files have a valid URL. When displaying this
|
||||
> value, implementations should help users understand the source of the string
|
||||
> if possible.
|
||||
|
||||
* If `importer` is null:
|
||||
|
||||
* If `url` is a `file:` URL, set `importer` to be a [filesystem importer] with an
|
||||
arbitrary `base`.
|
||||
|
||||
> This importer will only ever be passed absolute URLs, so its base won't
|
||||
> matter.
|
||||
|
||||
* If `url` is not a `file:` URL, set `importer` to be a function that always
|
||||
returns null.
|
||||
|
||||
* Let `file` be the [source file] with `ast`, canonical URL `url`, and
|
||||
importer `importer`.
|
||||
|
||||
* Let `module` be the result of [executing](#executing-a-file) `file`.
|
||||
|
||||
* Let `css` be the result of [resolving `module`'s extensions].
|
||||
|
||||
[resolving `module`'s extensions]: at-rules/extend.md#resolving-a-modules-extensions
|
||||
|
||||
* Return the result of converting `css` to a CSS string.
|
||||
|
||||
[filesystem importer]: modules.md#filesystem-importer
|
||||
[parsing]: syntax.md#parsing-text
|
||||
[global importer list]: modules.md#global-importer-list
|
||||
|
||||
### Executing a File
|
||||
|
||||
This algorithm takes a [source file] `file`, a [configuration] `config`, an
|
||||
[import context] `import`, and returns a [module].
|
||||
|
||||
* Let `module` be an empty module with source file `file`.
|
||||
|
||||
* Let `uses` be an empty map from `@use` rules to modules.
|
||||
|
||||
* Execute each top-level statement as described in that statement's
|
||||
specification.
|
||||
|
||||
> The semantics for executing each statement is defined in that statement's
|
||||
> individual specification.
|
||||
|
||||
* For each variable declaration `variable` with a `!global` flag in `file`,
|
||||
whether or not it was evaluated:
|
||||
|
||||
* If `variable`'s name *doesn't* begin with `-` or `_` and `variable` is not
|
||||
yet in `module`, set `variable` to `null` in `module`.
|
||||
|
||||
> This isn't necessary for implementations that follow the most recent
|
||||
> [variables spec] and don't allow `!global` assignments to variables that
|
||||
> don't yet exist. However, at time of writing, all existing implementations
|
||||
> are in the process of deprecating the old `!global` behavior, which
|
||||
> allowed `!global` declarations to create new variables.
|
||||
>
|
||||
> Setting all `!global` variables to `null` if they weren't otherwise set
|
||||
> guarantees the stability of static analysis by ensuring that the set of
|
||||
> variables a module exposes doesn't depend on how it was executed.
|
||||
|
||||
[variables spec]: variables.md
|
||||
|
||||
* Return `module`. Its functions, mixins, and CSS are now immutable.
|
||||
@ -41,14 +41,14 @@ use of `@extend`:
|
||||
|
||||
### Extender
|
||||
|
||||
An `@extend` rule's *extender* is the [selector list][] for the style rule in
|
||||
An `@extend` rule's *extender* is the [selector list] for the style rule in
|
||||
which the `@extend` rule appears.
|
||||
|
||||
[selector list]: https://drafts.csswg.org/selectors-4/#selector-list
|
||||
|
||||
### Target
|
||||
|
||||
An `@extend` rule's *target* is the [simple selector][] that's used as an
|
||||
An `@extend` rule's *target* is the [simple selector] that's used as an
|
||||
argument to `@extend`.
|
||||
|
||||
[simple selector]: https://drafts.csswg.org/selectors-4/#simple
|
||||
@ -61,8 +61,8 @@ An *extension* is a collection of various properties.
|
||||
> an `@extend` rule. As such, all `@extend` rules define extensions, but not all
|
||||
> extensions directly correspond to `@extend` rules.
|
||||
|
||||
* The *extender*, a [selector list][].
|
||||
* The *target*, a [simple selector][].
|
||||
* The *extender*, a [selector list].
|
||||
* The *target*, a [simple selector].
|
||||
|
||||
### Extendee
|
||||
|
||||
@ -103,7 +103,7 @@ that module's transitive dependencies.
|
||||
|
||||
To execute an `@extend` rule `rule`:
|
||||
|
||||
* If there is no [current style rule][], throw an error.
|
||||
* If there is no [current style rule], throw an error.
|
||||
|
||||
[current style rule]: ../style-rules.md#current-style-rule
|
||||
|
||||
@ -119,7 +119,7 @@ To execute an `@extend` rule `rule`:
|
||||
* Let `extension` be an [extension](#extension) whose extender is the current
|
||||
style rule's selector and whose target is `target`.
|
||||
|
||||
* Add `extension` to [the current module][]'s extensions.
|
||||
* Add `extension` to [the current module]'s extensions.
|
||||
|
||||
[the current module]: ../spec.md#current-module
|
||||
|
||||
@ -129,7 +129,7 @@ To execute an `@extend` rule `rule`:
|
||||
|
||||
### Resolving a Module's Extensions
|
||||
|
||||
This algorithm takes a [module][] `starting-module` and returns a [CSS tree][]
|
||||
This algorithm takes a [module] `starting-module` and returns a [CSS tree]
|
||||
that includes CSS for *all* modules transitively used or forwarded by
|
||||
`starting-module`.
|
||||
|
||||
@ -144,12 +144,12 @@ that includes CSS for *all* modules transitively used or forwarded by
|
||||
* Let `new-extensions` be an empty map from modules to sets of
|
||||
[extensions](#extension).
|
||||
|
||||
* Let `extended` be the subgraph of the [module graph][] containing
|
||||
* Let `extended` be the subgraph of the [module graph] containing
|
||||
modules that are transitively reachable from `starting-module`.
|
||||
|
||||
[module graph]: ../modules.md#module-graph
|
||||
|
||||
* For each module `domestic` in `extended`, in reverse [topological][] order:
|
||||
* For each module `domestic` in `extended`, in reverse [topological] order:
|
||||
|
||||
[topological]: https://en.wikipedia.org/wiki/Topological_sorting
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
## Syntax
|
||||
|
||||
<x><pre>
|
||||
**ForRule** ::= '@for' [PlainVariable][] FromDeclaration
|
||||
**ForRule** ::= '@for' [PlainVariable] FromDeclaration
|
||||
  (ToDeclaration | ThroughDeclaration) ForBlock
|
||||
**FromDeclaration** ::= 'from' Expression
|
||||
**ToDeclaration** ::= 'to' Expression
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# `@forward`
|
||||
|
||||
The `@forward` rule loads a [module][] from a URL and adds its members to the
|
||||
The `@forward` rule loads a [module] from a URL and adds its members to the
|
||||
public API of the current module without making them available to use within the
|
||||
current stylesheet.
|
||||
|
||||
@ -17,21 +17,21 @@ The grammar for the `@forward` rule is as follows:
|
||||
|
||||
<x><pre>
|
||||
**ForwardRule** ::= '@forward' QuotedString AsClause? (ShowClause | HideClause)? WithClause?
|
||||
**AsClause** ::= 'as' [\<ident-token>][] '\*'
|
||||
**AsClause** ::= 'as' [\<ident-token>] '\*'
|
||||
**ShowClause** ::= 'show' MemberName (',' MemberName)\*
|
||||
**HideClause** ::= 'hide' MemberName (',' MemberName)\*
|
||||
**WithClause** ::= 'with' '('
|
||||
  ForwardWithArgument (',' ForwardWithArgument)\* ','?
|
||||
  ')'
|
||||
**ForwardWithArgument** ::= '$' Identifier ':' Expression '!default'?
|
||||
**MemberName** ::= '$'? [\<ident-token>][]
|
||||
**MemberName** ::= '$'? [\<ident-token>]
|
||||
</pre></x>
|
||||
|
||||
[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
|
||||
`@forward` rules must be at the top level of the document, and must come before
|
||||
any rules other than `@charset` or `@use`. The `QuotedString`'s contents, known
|
||||
as the rule's *URL*, must be a [valid URL string][] (for non-[special][] base
|
||||
as the rule's *URL*, must be a [valid URL string] (for non-[special] base
|
||||
URL). No whitespace is allowed after `$` in `MemberName`, or before `*` in
|
||||
`AsClause`.
|
||||
|
||||
@ -80,7 +80,7 @@ To execute a `@forward` rule `rule`:
|
||||
* Add a variable to `rule-config` with the same name as `argument`'s
|
||||
identifier, and with `value` as its value.
|
||||
|
||||
* Let `forwarded` be the result of [loading the module][] with `rule`'s URL
|
||||
* Let `forwarded` be the result of [loading the module] with `rule`'s URL
|
||||
string and `rule-config`.
|
||||
|
||||
[loading the module]: ../modules.md#loading-a-module
|
||||
@ -101,7 +101,7 @@ To execute a `@forward` rule `rule`:
|
||||
* If `rule` has an `AsClause` `as`, prepend `as`'s identifier to `name` (after
|
||||
the `$` if `member` is a variable).
|
||||
|
||||
* If there's a member defined at the top level of [the current source file][]
|
||||
* If there's a member defined at the top level of [the current source file]
|
||||
named `name` with the same type as `member`, do nothing.
|
||||
|
||||
* Otherwise, if `rule` has a `show` clause that doesn't include `name`
|
||||
@ -116,11 +116,11 @@ To execute a `@forward` rule `rule`:
|
||||
* If another `@forward` rule's module has a member named `name` with the same
|
||||
type as `member`:
|
||||
|
||||
* If the other member is [identical to][] `member`, do nothing.
|
||||
* If the other member is [identical to] `member`, do nothing.
|
||||
|
||||
* Otherwise, throw an error.
|
||||
|
||||
* Otherwise, add `member` to [the current module][] with the name `name`.
|
||||
* Otherwise, add `member` to [the current module] with the name `name`.
|
||||
|
||||
> It's possible for the same member to be added to a given module multiple
|
||||
> times if it's forwarded with different prefixes. All of these names refer
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
## Syntax
|
||||
|
||||
<x><pre>
|
||||
**FunctionRule** ::= '@function' [\<ident-token>][] ArgumentDeclaration '{' Statements '}'
|
||||
**FunctionRule** ::= '@function' [\<ident-token>] ArgumentDeclaration '{' Statements '}'
|
||||
</pre></x>
|
||||
|
||||
[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
@ -52,7 +52,7 @@ To execute a `@function` rule `rule`:
|
||||
|
||||
* If `rule` is outside of any block of statements:
|
||||
|
||||
* If `name` *doesn't* begin with `-` or `_`, set [the current module][]'s
|
||||
* If `name` *doesn't* begin with `-` or `_`, set [the current module]'s
|
||||
function `name` to `function`.
|
||||
|
||||
> This overrides the previous definition, if one exists.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# Import
|
||||
|
||||
The `@import` rule is the legacy way of splitting styles across multiple files
|
||||
in Sass. The [`@use` rule][] should generally be used instead, but `@import` is
|
||||
in Sass. The [`@use` rule] should generally be used instead, but `@import` is
|
||||
still supported for backwards-compatibility.
|
||||
|
||||
[`@use` rule]: use.md
|
||||
@ -23,7 +23,7 @@ still supported for backwards-compatibility.
|
||||
  | InterpolatedIdentifier (',' [MediaQueryList])\*
|
||||
**ImportSupports** ::= 'supports(' SupportsDeclaration ')'
|
||||
**ImportFunction** ::= [InterpolatedIdentifier]¹ '(' InterpolatedDeclarationValue? ')'
|
||||
**ImportUrl** ::= QuotedString | [InterpolatedUrl][]
|
||||
**ImportUrl** ::= QuotedString | [InterpolatedUrl]
|
||||
</pre></x>
|
||||
|
||||
[InterpolatedIdentifier]: ../syntax.md#interpolatedidentifier
|
||||
@ -112,20 +112,20 @@ To execute an `@import` rule `rule`:
|
||||
* Add an `@import` with the evaluated modifiers to [the current module]'s CSS
|
||||
AST after the longest initial subsequence of comments and `@import` rules.
|
||||
|
||||
* Otherwise, let `file` be the result of [loading the file][] with
|
||||
* Otherwise, let `file` be the result of [loading the file] with
|
||||
`argument`'s URL string. If this returns null, throw an error.
|
||||
|
||||
* If `file`'s canonical URL is the same as that of any other [current source
|
||||
file][], throw an error.
|
||||
file], throw an error.
|
||||
|
||||
* Let `imported` be the result of [executing][] `file` with the empty
|
||||
configuration and the [current import context][], except that if
|
||||
* Let `imported` be the result of [executing] `file` with the empty
|
||||
configuration and the [current import context], except that if
|
||||
`rule` is nested within at-rules and/or style rules, that context is
|
||||
preserved when executing `file`.
|
||||
|
||||
> Note that this execution can mutate `import`.
|
||||
|
||||
* Let `css` be the result of [resolving `imported`'s extensions][], except
|
||||
* Let `css` be the result of [resolving `imported`'s extensions], except
|
||||
that if `rule` is nested within at-rules and/or style rules, that context is
|
||||
added to CSS that comes from modules loaded by `imported`.
|
||||
|
||||
@ -135,7 +135,7 @@ To execute an `@import` rule `rule`:
|
||||
|
||||
* Add `css` to the current module's CSS.
|
||||
|
||||
* Add `imported`'s [extensions][] to the current module.
|
||||
* Add `imported`'s [extensions] to the current module.
|
||||
|
||||
* If the `@import` rule is nested within at-rules and/or style rules, add each
|
||||
member in `imported` to the [current scope].
|
||||
|
||||
@ -17,7 +17,7 @@
|
||||
### Syntax
|
||||
|
||||
<x><pre>
|
||||
**MixinRule** ::= '@mixin' [\<ident-token>][] ArgumentDeclaration? '{' Statements '}'
|
||||
**MixinRule** ::= '@mixin' [\<ident-token>] ArgumentDeclaration? '{' Statements '}'
|
||||
</pre></x>
|
||||
|
||||
[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
@ -73,7 +73,7 @@ To execute a `@mixin` rule `rule`:
|
||||
### Syntax
|
||||
|
||||
<x><pre>
|
||||
**IncludeRule** ::= '@include' [NamespacedIdentifier][] ArgumentInvocation?
|
||||
**IncludeRule** ::= '@include' [NamespacedIdentifier] ArgumentInvocation?
|
||||
  ContentBlock?
|
||||
**ContentBlock** ::= UsingDeclaration? '{' Statements '}'
|
||||
**UsingDeclaration** ::= 'using' ArgumentDeclaration
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# `@use`
|
||||
|
||||
The `@use` rule loads a [module][] from a URL, makes its members available to
|
||||
The `@use` rule loads a [module] from a URL, makes its members available to
|
||||
the current stylesheet, and includes its CSS in the compilation output.
|
||||
|
||||
[module]: ../modules.md#module
|
||||
@ -18,7 +18,7 @@ the current stylesheet, and includes its CSS in the compilation output.
|
||||
|
||||
### A `@use` Rule's Module
|
||||
|
||||
A `@use` rule's *module* is a [module][] associated with a `@use` rule. This
|
||||
A `@use` rule's *module* is a [module] associated with a `@use` rule. This
|
||||
module is only associated once the rule has been [executed](#semantics).
|
||||
|
||||
## Syntax
|
||||
@ -27,24 +27,24 @@ The grammar for the `@use` rule is as follows:
|
||||
|
||||
<x><pre>
|
||||
**UseRule** ::= '@use' QuotedString AsClause? WithClause?
|
||||
**AsClause** ::= 'as' ('\*' | [\<ident-token>][])
|
||||
**AsClause** ::= 'as' ('\*' | [\<ident-token>])
|
||||
**WithClause** ::= 'with' '('
|
||||
  KeywordArgument (',' KeywordArgument)\* ','?
|
||||
  ')'
|
||||
**KeywordArgument** ::= '$' [\<ident-token>][] ':' Expression
|
||||
**KeywordArgument** ::= '$' [\<ident-token>] ':' Expression
|
||||
</pre></x>
|
||||
|
||||
[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
|
||||
`@use` rules must be at the top level of the document, and must come before any
|
||||
rules other than `@charset` or `@forward`. The `QuotedString`'s contents, known
|
||||
as the rule's *URL*, must be a [valid URL string][] (for non-[special][] base
|
||||
as the rule's *URL*, must be a [valid URL string] (for non-[special] base
|
||||
URL). No whitespace is allowed after `$` in `KeywordArgument`.
|
||||
|
||||
[valid URL string]: https://url.spec.whatwg.org/#valid-url-string
|
||||
[special]: https://url.spec.whatwg.org/#special-scheme
|
||||
|
||||
> Because each `@use` rule affects the namespace of the entire [source file][]
|
||||
> Because each `@use` rule affects the namespace of the entire [source file]
|
||||
> that contains it, whereas most other Sass constructs are purely imperative,
|
||||
> keeping it at the top of the file helps reduce confusion.
|
||||
>
|
||||
@ -68,7 +68,7 @@ A `@use` rule's *namespace* is determined using [this
|
||||
algorithm](#determining-a-use-rules-namespace). If the algorithm for determining
|
||||
a namespace fails for a `@use` rule, that rule is invalid. If it returns `null`,
|
||||
that rule is called *global*. A namespace is used to identify the used
|
||||
[module][]'s members within the current [source file][].
|
||||
[module]'s members within the current [source file].
|
||||
|
||||
## Procedures
|
||||
|
||||
@ -108,7 +108,7 @@ This algorithm takes a `@use` rule `rule`, and returns either an identifier or
|
||||
To execute a `@use` rule `rule`:
|
||||
|
||||
* If `rule` has a namespace that's the same as another `@use` rule's namespace
|
||||
in [the current source file][], throw an error.
|
||||
in [the current source file], throw an error.
|
||||
|
||||
[the current source file]: ../spec.md#current-source-file
|
||||
|
||||
@ -123,7 +123,7 @@ To execute a `@use` rule `rule`:
|
||||
* Add a variable to `rule-config` with the same name as `argument`'s identifier
|
||||
and with `value` as its value.
|
||||
|
||||
* Let `module` be the result of [loading the module][] with `rule`'s URL string
|
||||
* Let `module` be the result of [loading the module] with `rule`'s URL string
|
||||
and `rule-config`.
|
||||
|
||||
[loading the module]: ../modules.md#loading-a-module
|
||||
|
||||
@ -142,7 +142,7 @@ This function is also available as a global function named `adjust-color()`.
|
||||
* If `$lightness` isn't null, set `lightness` to `lightness + $lightness`
|
||||
clamped between 0% and 100%.
|
||||
|
||||
* Return the result of calling [`hsl()`][] with `hue`, `saturation`,
|
||||
* Return the result of calling [`hsl()`] with `hue`, `saturation`,
|
||||
`lightness`, and `alpha`.
|
||||
|
||||
* Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null:
|
||||
@ -189,7 +189,7 @@ alpha($color)
|
||||
This function is also available as a global function named `opacity()`.
|
||||
|
||||
> There is also a global function named `alpha()`, but it supports an additional
|
||||
> overload with different behavior that's defined with the [global functions][].
|
||||
> overload with different behavior that's defined with the [global functions].
|
||||
>
|
||||
> [global functions]: ../functions.md#alpha
|
||||
|
||||
@ -297,7 +297,7 @@ This function is also available as a global function named `change-color()`.
|
||||
* Let `lightness` be the result of calling `lightness($color)` if
|
||||
`$lightness` is null, or `$lightness` otherwise.
|
||||
|
||||
* Return the result of calling [`hsl()`][] with `hue`, `saturation`,
|
||||
* Return the result of calling [`hsl()`] with `hue`, `saturation`,
|
||||
`lightness`, and `alpha`.
|
||||
|
||||
* Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null:
|
||||
@ -430,12 +430,12 @@ This function is also available as a global function named `hue()`.
|
||||
* Set `blackness` to `blackness / (whiteness + blackness)`.
|
||||
|
||||
* Let `red`, `green`, and `blue` be the result of converting `hue`,
|
||||
`whiteness`, and `blackness` [to RGB][].
|
||||
`whiteness`, and `blackness` [to RGB].
|
||||
|
||||
* Set `red`, `green`, and `blue` to their existing values multiplied by 255
|
||||
and rounded to the nearest integers.
|
||||
|
||||
* Let `alpha` be the result of [percent-converting][] `$alpha` with a `max` of 1.
|
||||
* Let `alpha` be the result of [percent-converting] `$alpha` with a `max` of 1.
|
||||
|
||||
* Return a color with the given `red`, `green`, `blue`, and `alpha` channels.
|
||||
|
||||
@ -670,7 +670,7 @@ This function is also available as a global function named `scale-color()`.
|
||||
|
||||
* Let `alpha` be `$color`'s alpha channel.
|
||||
|
||||
* If `$alpha` isn't null, set `alpha` to the result of [scaling][] `alpha` by
|
||||
* If `$alpha` isn't null, set `alpha` to the result of [scaling] `alpha` by
|
||||
`$alpha` with `max` 1.
|
||||
|
||||
[scaling]: #scaling-a-number
|
||||
@ -682,13 +682,13 @@ This function is also available as a global function named `scale-color()`.
|
||||
|
||||
* Let `red`, `green`, and `blue` be `$color`'s red, green, and blue channels.
|
||||
|
||||
* If `$red` isn't null, set `red` to the result of [scaling][] `red` by `$red`
|
||||
* If `$red` isn't null, set `red` to the result of [scaling] `red` by `$red`
|
||||
with `max` 255.
|
||||
|
||||
* If `$green` isn't null, set `green` to the result of [scaling][] `green` by
|
||||
* If `$green` isn't null, set `green` to the result of [scaling] `green` by
|
||||
`$green` with `max` 255.
|
||||
|
||||
* If `$blue` isn't null, set `blue` to the result of [scaling][] `blue` by `$blue`
|
||||
* If `$blue` isn't null, set `blue` to the result of [scaling] `blue` by `$blue`
|
||||
with `max` 255.
|
||||
|
||||
* Return a color with `red`, `green`, `blue`, and `alpha` as the red, green,
|
||||
@ -701,13 +701,13 @@ This function is also available as a global function named `scale-color()`.
|
||||
* Let `hue`, `saturation`, and `lightness` be the result of calling
|
||||
`hue($color)`, `saturation($color)`, and `lightness($color)` respectively.
|
||||
|
||||
* If `$saturation` isn't null, set `saturation` to the result of [scaling][]
|
||||
* If `$saturation` isn't null, set `saturation` to the result of [scaling]
|
||||
`saturation` by `$saturation` with `max` `100%`.
|
||||
|
||||
* If `$lightness` isn't null, set `lightness` to the result of [scaling][]
|
||||
* If `$lightness` isn't null, set `lightness` to the result of [scaling]
|
||||
`lightness` by `$lightness` with `max` `100%`.
|
||||
|
||||
* Return the result of calling [`hsl()`][] with `hue`, `saturation`,
|
||||
* Return the result of calling [`hsl()`] with `hue`, `saturation`,
|
||||
`lightness`, and `alpha`.
|
||||
|
||||
* Otherwise, if either `$hue`, `$whiteness`, or `$blackness` aren't null:
|
||||
@ -715,10 +715,10 @@ This function is also available as a global function named `scale-color()`.
|
||||
* Let `hue`, `whiteness`, and `blackness` be the result of calling
|
||||
`hue($color)`, `whiteness($color)`, and `blackness($color)` respectively.
|
||||
|
||||
* If `$whiteness` isn't null, set `whiteness` to the result of [scaling][]
|
||||
* If `$whiteness` isn't null, set `whiteness` to the result of [scaling]
|
||||
`whiteness` by `$whiteness` with `max` `100%`.
|
||||
|
||||
* If `$blackness` isn't null, set `blackness` to the result of [scaling][]
|
||||
* If `$blackness` isn't null, set `blackness` to the result of [scaling]
|
||||
`blackness` by `$blackness` with `max` `100%`.
|
||||
|
||||
* Return the result of calling `hwb()` with `hue`, `whiteness`, `blackness`,
|
||||
|
||||
@ -114,18 +114,18 @@ This function is also available as a global function named `function-exists()`.
|
||||
|
||||
* If `$module` is null:
|
||||
|
||||
* Return whether [resolving a function][] named `$name` returns null.
|
||||
* Return whether [resolving a function] named `$name` returns null.
|
||||
|
||||
[resolving a function]: ../modules.md#resolving-a-member
|
||||
|
||||
* Otherwise, if `$module` isn't a string, throw an error.
|
||||
|
||||
* Otherwise, let `use` be the `@use` rule in [the current source file][] whose
|
||||
* Otherwise, let `use` be the `@use` rule in [the current source file] whose
|
||||
namespace is equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
[the current source file]: ../spec.md#current-source-file
|
||||
|
||||
* Return whether [`use`'s module][] contains a function named `$name`.
|
||||
* Return whether [`use`'s module] contains a function named `$name`.
|
||||
|
||||
[`use`'s module]: ../at-rules/use.md#a-use-rules-module
|
||||
|
||||
@ -145,7 +145,7 @@ This function is also available as a global function named `get-function()`.
|
||||
|
||||
* If `$css` is falsey:
|
||||
|
||||
* Return the result of [resolving a function][] named `$name`. If this
|
||||
* Return the result of [resolving a function] named `$name`. If this
|
||||
returns null, throw an error.
|
||||
|
||||
* Otherwise, return a function object that takes arguments `($args...)`. When
|
||||
@ -162,10 +162,10 @@ This function is also available as a global function named `get-function()`.
|
||||
|
||||
* If `$css` is truthy, throw an error.
|
||||
|
||||
* Let `use` be the `@use` rule in [the current source file][] whose
|
||||
* Let `use` be the `@use` rule in [the current source file] whose
|
||||
namespace is equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
* Return [`use`'s module][]'s function named `$name`, or throw an error if no
|
||||
* Return [`use`'s module]'s function named `$name`, or throw an error if no
|
||||
such function exists.
|
||||
|
||||
### `get-mixin()`
|
||||
@ -211,19 +211,19 @@ This function is also available as a global function named `global-variable-exis
|
||||
|
||||
* If `$module` is null:
|
||||
|
||||
* Return whether [resolving a variable][] named `$name`, ignoring local
|
||||
* Return whether [resolving a variable] named `$name`, ignoring local
|
||||
scopes, returns null.
|
||||
|
||||
[resolving a variable]: ../modules.md#resolving-a-member
|
||||
|
||||
* Otherwise, if `$module` isn't a string, throw an error.
|
||||
|
||||
* Otherwise, let `use` be the `@use` rule in the [current source file][] whose
|
||||
* Otherwise, let `use` be the `@use` rule in the [current source file] whose
|
||||
namespace is equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
[current source file]: ../spec.md#current-source-file
|
||||
|
||||
* Return whether [`use`'s module][] contains a function named `$name`.
|
||||
* Return whether [`use`'s module] contains a function named `$name`.
|
||||
|
||||
### `inspect()`
|
||||
|
||||
@ -274,10 +274,10 @@ This function is also available as a global function named `module-functions()`.
|
||||
|
||||
* If `$module` is not a string, throw an error.
|
||||
|
||||
* Let `use` be the `@use` rule in [the current source file][] whose namespace is
|
||||
* Let `use` be the `@use` rule in [the current source file] whose namespace is
|
||||
equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
* Return a map whose keys are the names of functions in [`use`'s module][] and
|
||||
* Return a map whose keys are the names of functions in [`use`'s module] and
|
||||
whose values are the corresponding functions.
|
||||
|
||||
### `module-mixins()`
|
||||
@ -306,11 +306,11 @@ This function is also available as a global function named `module-variables()`.
|
||||
|
||||
* If `$module` is not a string, throw an error.
|
||||
|
||||
* Let `use` be the `@use` rule in [the current source file][] whose namespace is
|
||||
* Let `use` be the `@use` rule in [the current source file] whose namespace is
|
||||
equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
* Return a map whose keys are the names (without `$`) of variables in [`use`'s
|
||||
module][] and whose values are the corresponding values.
|
||||
module] and whose values are the corresponding values.
|
||||
|
||||
### `type-of()`
|
||||
|
||||
@ -351,14 +351,14 @@ This function is also available as a global function named `variable-exists()`.
|
||||
|
||||
* If `$module` is null:
|
||||
|
||||
* Return whether [resolving a variable][] named `$name` returns null.
|
||||
* Return whether [resolving a variable] named `$name` returns null.
|
||||
|
||||
* Otherwise, if `$module` isn't a string, throw an error.
|
||||
|
||||
* Otherwise, let `use` be the `@use` rule in [the current source file][] whose
|
||||
* Otherwise, let `use` be the `@use` rule in [the current source file] whose
|
||||
namespace is equal to `$module`. If no such rule exists, throw an error.
|
||||
|
||||
* Return whether [`use`'s module][] contains a mixin named `$name`.
|
||||
* Return whether [`use`'s module] contains a mixin named `$name`.
|
||||
|
||||
## Mixins
|
||||
|
||||
@ -391,11 +391,11 @@ load-css($url, $with: null)
|
||||
* Let `config` be a configuration whose variable names and values are given by
|
||||
`$with` if `$with` isn't null, or the empty configuration otherwise.
|
||||
|
||||
* Let `module` be the result of [loading][] `$url` with `config`.
|
||||
* Let `module` be the result of [loading] `$url` with `config`.
|
||||
|
||||
[loading]: ../modules.md#loading-a-module
|
||||
|
||||
* Let `css` be the result of [resolving `module`'s extensions][].
|
||||
* Let `css` be the result of [resolving `module`'s extensions].
|
||||
|
||||
[resolving `module`'s extensions]: ../at-rules/extend.md#resolving-a-modules-extensions
|
||||
|
||||
|
||||
@ -43,8 +43,8 @@ to CSS. The other, the *host*, is responsible for telling the compiler what to
|
||||
compile and for providing implementations of custom importers and functions.
|
||||
|
||||
Messages are sent between the host and the compiler in the form of [protocol
|
||||
buffers][], using a custom RPC system [defined below][]. The messages and
|
||||
services that comprise this protocol are defined in [the `.proto` file][]
|
||||
buffers], using a custom RPC system [defined below]. The messages and
|
||||
services that comprise this protocol are defined in [the `.proto` file]
|
||||
included in this repository. Most messages are *requests* which require the
|
||||
other endpoint to produce a *response*, but some are *events* which require no
|
||||
response.
|
||||
@ -92,7 +92,7 @@ For a length-delimited stream, each packet has the following structure:
|
||||
### Type Definitions
|
||||
|
||||
All RPCs are wrapped in an outer message that indicates the RPC's type using [a
|
||||
oneof field][]. There are two wrapper messages:
|
||||
oneof field]. There are two wrapper messages:
|
||||
|
||||
[a oneof field]: https://developers.google.com/protocol-buffers/docs/proto3#oneof
|
||||
|
||||
@ -193,7 +193,7 @@ functions can be written in the host language. In order to ensure that custom
|
||||
functions will behave consistently with built-in Sass functions, the host
|
||||
language should provide APIs that meet the following guidelines.
|
||||
|
||||
The [Dart `Value` API][] is a good example of an object-oriented API that
|
||||
The [Dart `Value` API] is a good example of an object-oriented API that
|
||||
follows these guidelines.
|
||||
|
||||
[Dart `Value` API]: https://pub.dartlang.org/documentation/sass/latest/sass/Value-class.html
|
||||
@ -213,7 +213,7 @@ or a number's units) should match that of the original object.
|
||||
|
||||
SassScript values use index 1 to refer to the first element and -1 to refer to
|
||||
the final element. The index 0 is invalid. Furthermore, indexes in Sass strings
|
||||
refer to [Unicode code points][], not bytes or UTF-16 code units. The API should
|
||||
refer to [Unicode code points], not bytes or UTF-16 code units. The API should
|
||||
provide a means to convert between Sass's indexing scheme and the host
|
||||
language's indexing scheme, and should encourage authors to treat any indexes
|
||||
they're passed as Sass-style indexes rather than host-language-style indexes.
|
||||
@ -240,7 +240,7 @@ is quoted or not.
|
||||
The API should provide additional assertions for numbers:
|
||||
|
||||
* that the number doesn't have any units;
|
||||
* that the number's units are [compatible][] with given expected units;
|
||||
* that the number's units are [compatible] with given expected units;
|
||||
* that the number is an integer, which for the purposes of Sass numbers means
|
||||
that its numeric value is within 1e-11 of an integer;
|
||||
* that the number is in a given range, where being within 1e-11 of the top or
|
||||
@ -252,7 +252,7 @@ The API should also provide means of converting a number to the equivalent
|
||||
number with different-but-compatible units, and for returning it as the host
|
||||
language's integer type if it is an integer.
|
||||
|
||||
Two numbers are equal if they have [compatible][] units, and if their numerical
|
||||
Two numbers are equal if they have [compatible] units, and if their numerical
|
||||
value (with normalized units) are within 1e-11 of one another. A hash code with
|
||||
the same equality semantics can be generated for a number `x` by rounding
|
||||
`x * 1e11` to the nearest integer and taking the hash code of the result.
|
||||
|
||||
@ -69,7 +69,7 @@ matching is case-insensitive.
|
||||
[`SpecialFunctionName`]: syntax.md#specialfunctionexpression
|
||||
|
||||
<x><pre>
|
||||
**FunctionCall** ::= [NamespacedIdentifier][] ArgumentInvocation
|
||||
**FunctionCall** ::= [NamespacedIdentifier] ArgumentInvocation
|
||||
</pre></x>
|
||||
|
||||
No whitespace is allowed between the `NamespacedIdentifier` and the
|
||||
@ -99,7 +99,7 @@ To evaluate a `FunctionCall` `call`:
|
||||
|
||||
* Let `name` be `call`'s `NamespacedIdentifier`.
|
||||
|
||||
* Let `function` be the result of [resolving a function][] named `name`.
|
||||
* Let `function` be the result of [resolving a function] named `name`.
|
||||
|
||||
* If `function` is null and `name` is not a plain `Identifier`, throw an error.
|
||||
|
||||
@ -145,7 +145,7 @@ To evaluate a `FunctionCall` `call`:
|
||||
|
||||
## Global Functions
|
||||
|
||||
> While most built-in Sass functions are defined in [built-in modules][], a few
|
||||
> While most built-in Sass functions are defined in [built-in modules], a few
|
||||
> are globally available with no `@use` necessary. These are mostly functions
|
||||
> that expand upon the behavior of plain CSS functions.
|
||||
>
|
||||
@ -192,7 +192,7 @@ adjust-hue($color, $degrees)
|
||||
```
|
||||
|
||||
> This overload exists to support Microsoft's proprietary [`alpha()`
|
||||
> function][].
|
||||
> function].
|
||||
|
||||
[`alpha()` function]: https://blogs.msdn.microsoft.com/ie/2010/08/17/ie9-opacity-and-alpha/
|
||||
|
||||
@ -223,7 +223,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
|
||||
* If any of `$red`, `$green`, `$blue`, or `$alpha` aren't numbers, throw an
|
||||
error.
|
||||
|
||||
* Let `red`, `green`, and `blue` be the result of [percent-converting][]
|
||||
* Let `red`, `green`, and `blue` be the result of [percent-converting]
|
||||
`$red`, `$green`, and `$blue`, respectively, with a `max` of 255.
|
||||
|
||||
* Let `alpha` be the result of percent-converting `$alpha` with a `max` of 1.
|
||||
@ -246,7 +246,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
|
||||
rgb($color, $alpha)
|
||||
```
|
||||
|
||||
* If either argument is a [special variable string][], return a plain CSS
|
||||
* If either argument is a [special variable string], return a plain CSS
|
||||
function string with the name `"rgb"` and the same arguments.
|
||||
|
||||
* If `$color` isn't a color, throw an error.
|
||||
@ -259,7 +259,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
|
||||
rgb($channels)
|
||||
```
|
||||
|
||||
* If `$channels` is a [special variable string][], return a plain CSS function
|
||||
* If `$channels` is a [special variable string], return a plain CSS function
|
||||
string with the name `"rgb"` and the argument `$channels`.
|
||||
|
||||
* If `$channels` is an unbracketed slash-separated list:
|
||||
@ -280,7 +280,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
|
||||
|
||||
* If `rgb` has fewer than three elements:
|
||||
|
||||
* If any element of `rgb` is a [special variable string][], return a
|
||||
* If any element of `rgb` is a [special variable string], return a
|
||||
plain CSS function string with the name `"rgb"` and the argument
|
||||
`$channels`.
|
||||
|
||||
@ -302,7 +302,7 @@ plain CSS function named `"rgb"` that function is named `"rgba"` instead.
|
||||
|
||||
* If `$channels` has fewer than three elements:
|
||||
|
||||
* If any element of `$channels` is a [special variable string][], return a
|
||||
* If any element of `$channels` is a [special variable string], return a
|
||||
plain CSS function string with the name `"rgb"` and the argument
|
||||
`$channels`.
|
||||
|
||||
@ -358,12 +358,12 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
|
||||
`$lightness`, respectively, between `0%` and `100%` and dividing by `100%`.
|
||||
|
||||
* Let `red`, `green`, and `blue` be the result of converting `hue`,
|
||||
`saturation`, and `lightness` [to RGB][].
|
||||
`saturation`, and `lightness` [to RGB].
|
||||
|
||||
* Set `red`, `green`, and `blue` to their existing values multiplied by 255
|
||||
and rounded to the nearest integers.
|
||||
|
||||
* Let `alpha` be the result of [percent-converting][] `$alpha` with a `max` of 1.
|
||||
* Let `alpha` be the result of [percent-converting] `$alpha` with a `max` of 1.
|
||||
|
||||
* Return a color with the given `red`, `green`, `blue`, and `alpha` channels.
|
||||
|
||||
@ -385,7 +385,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
|
||||
hsl($hue, $saturation)
|
||||
```
|
||||
|
||||
* If either argument is a [special variable string][], return a plain CSS
|
||||
* If either argument is a [special variable string], return a plain CSS
|
||||
function string with the name `"hsl"` and the same arguments.
|
||||
|
||||
* Otherwise, throw an error.
|
||||
@ -394,7 +394,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
|
||||
hsl($channels)
|
||||
```
|
||||
|
||||
* If `$channels` is a [special variable string][], return a plain CSS function
|
||||
* If `$channels` is a [special variable string], return a plain CSS function
|
||||
string with the name `"hsl"` and the argument `$channels`.
|
||||
|
||||
* If `$channels` is an unbracketed slash-separated list:
|
||||
@ -415,7 +415,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
|
||||
|
||||
* If `hsl` has fewer than three elements:
|
||||
|
||||
* If any element of `hsl` is a [special variable string][], return a
|
||||
* If any element of `hsl` is a [special variable string], return a
|
||||
plain CSS function string with the name `"hsl"` and the argument
|
||||
`$channels`.
|
||||
|
||||
@ -437,7 +437,7 @@ plain CSS function named `"hsl"` that function is named `"hsla"` instead.
|
||||
|
||||
* If `$channels` has fewer than three elements:
|
||||
|
||||
* If any element of `$channels` is a [special variable string][], return a
|
||||
* If any element of `$channels` is a [special variable string], return a
|
||||
plain CSS function string with the name `"hsl"` and the argument
|
||||
`$channels`.
|
||||
|
||||
|
||||
@ -86,7 +86,7 @@ A *module* is a collection of various properties:
|
||||
> member names and signatures regardless of the context in which those modules
|
||||
> are loaded.
|
||||
|
||||
* A set of [extensions][].
|
||||
* A set of [extensions].
|
||||
|
||||
[extensions]: at-rules/extend.md#extension
|
||||
|
||||
@ -97,7 +97,7 @@ A *module* is a collection of various properties:
|
||||
> any plain CSS rules.
|
||||
|
||||
* A list of references to other modules, known as the module's *dependencies*,
|
||||
in the same order as their [`@use` rules][] and/or [`@forward` rules][] appear
|
||||
in the same order as their [`@use` rules] and/or [`@forward` rules] appear
|
||||
in the module's source file. If a dependency is referred to from multiple
|
||||
rules, its order is determined by the first such rule.
|
||||
|
||||
@ -107,7 +107,7 @@ A *module* is a collection of various properties:
|
||||
[`@use` rules]: at-rules/use.md
|
||||
[`@forward` rules]: at-rules/forward.md
|
||||
|
||||
* An optional [source file][].
|
||||
* An optional [source file].
|
||||
|
||||
> Note that [built-in modules](#built-in-module) *do not* have source files
|
||||
> associated with them.
|
||||
@ -117,7 +117,7 @@ A *module* is a collection of various properties:
|
||||
* An absolute URL, known as the module's *canonical URL*. If the module has a
|
||||
source file, this must be the same as the source file's canonical URL.
|
||||
|
||||
Once a user-defined module has been returned by [Executing a File][], it is
|
||||
Once a user-defined module has been returned by [Executing a File], it is
|
||||
immutable except for its variable values. [Built-in modules](#built-in-module)
|
||||
are always immutable.
|
||||
|
||||
@ -126,8 +126,8 @@ are always immutable.
|
||||
### Module Graph
|
||||
|
||||
The set of [modules](#module) loaded in the course of processing a stylesheet
|
||||
can be construed as a [directed acyclic graph][] where the vertices are modules
|
||||
and the edges are [`@use` rules][] and/or [`@forward` rules][]. We call this the
|
||||
can be construed as a [directed acyclic graph] where the vertices are modules
|
||||
and the edges are [`@use` rules] and/or [`@forward` rules]. We call this the
|
||||
*module graph*.
|
||||
|
||||
[directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
|
||||
@ -135,7 +135,7 @@ and the edges are [`@use` rules][] and/or [`@forward` rules][]. We call this the
|
||||
The module graph is not allowed to contain cycles because they make it
|
||||
impossible to guarantee that all dependencies of a module are available before
|
||||
that module is loaded. Although the names and APIs of a dependency's members can
|
||||
be determined without [executing][] it, Sass allows code to be executed during
|
||||
be determined without [executing] it, Sass allows code to be executed during
|
||||
load, so those members may not behave correctly when invoked before the
|
||||
dependency is executed.
|
||||
|
||||
@ -146,10 +146,10 @@ dependency is executed.
|
||||
An *import context* is a set of [members](#member) that contains at most one
|
||||
member of any given type and name. It's always mutable.
|
||||
|
||||
> Import contexts serve as glue between the old [`@import` rule][] and the
|
||||
> Import contexts serve as glue between the old [`@import` rule] and the
|
||||
> module system. It serves as a shared global namespace for stylesheets loaded
|
||||
> using `@import` rules, while also preventing global names from leaking into or
|
||||
> out of stylesheets loaded using [`@use` rules][] and/or [`@forward` rules][].
|
||||
> out of stylesheets loaded using [`@use` rules] and/or [`@forward` rules].
|
||||
|
||||
[`@import` rule]: at-rules/import.md
|
||||
|
||||
@ -158,7 +158,7 @@ member of any given type and name. It's always mutable.
|
||||
A *built-in module* is a module defined either by the Sass specification or by
|
||||
the host environment of the Sass compilation in some implementation-specific
|
||||
way. Modules defined by the Sass specification all have the scheme `sass:` and
|
||||
are all described in [the `built-in-modules` directory][]. Modules defined
|
||||
are all described in [the `built-in-modules` directory]. Modules defined
|
||||
outside the Sass compilation may not use the scheme `sass:`.
|
||||
|
||||
[the `built-in-modules` directory]: built-in-modules
|
||||
@ -329,8 +329,8 @@ The module system defines the following syntax for referring to names from other
|
||||
modules:
|
||||
|
||||
<x><pre>
|
||||
**PublicIdentifier** ::= [\<ident-token>][] that doesn't begin with '-' or '_'
|
||||
**NamespacedIdentifier** ::= [\<ident-token>][] | [\<ident-token>][] '.' PublicIdentifier
|
||||
**PublicIdentifier** ::= [\<ident-token>] that doesn't begin with '-' or '_'
|
||||
**NamespacedIdentifier** ::= [\<ident-token>] | [\<ident-token>] '.' PublicIdentifier
|
||||
</pre></x>
|
||||
|
||||
[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
@ -379,7 +379,7 @@ This algorithm takes a string `argument` and [configuration](#configuration)
|
||||
> This disallows circular `@use`s, which ensures that modules can't be used
|
||||
> until they're fully initialized.
|
||||
|
||||
* Otherwise, return the result of [executing][] `file` with `config` and a new
|
||||
* Otherwise, return the result of [executing] `file` with `config` and a new
|
||||
[import context](#import-context).
|
||||
|
||||
> For simplicity, the spec creates an import context for every module.
|
||||
@ -538,11 +538,11 @@ and returns a member of type `type` or null.
|
||||
[current scope]: spec.md#scope
|
||||
|
||||
* If `name` is a [`NamespacedIdentifier`](#syntax) of the form
|
||||
`namespace.raw-name` or a [`Variable`][] of the form `namespace.$raw-name`:
|
||||
`namespace.raw-name` or a [`Variable`] of the form `namespace.$raw-name`:
|
||||
|
||||
[`Variable`]: variables.md#syntax
|
||||
|
||||
* Let `use` be the [`@use` rule][] in the [current source file][] whose
|
||||
* Let `use` be the [`@use` rule] in the [current source file] whose
|
||||
namespace is `namespace`. If there isn't exactly one such rule, throw an
|
||||
error.
|
||||
|
||||
@ -551,7 +551,7 @@ and returns a member of type `type` or null.
|
||||
|
||||
* If `use` hasn't been executed yet, throw an error.
|
||||
|
||||
* Otherwise, let `module` be [`use`'s module][].
|
||||
* Otherwise, let `module` be [`use`'s module].
|
||||
|
||||
* Return the member of `module` with type `type` and name `raw-name`. If there
|
||||
is no such member, throw an error.
|
||||
@ -568,7 +568,7 @@ and returns a member of type `type` or null.
|
||||
> variable definition will set the module's variable value rather than
|
||||
> defining a new variable local to this module.
|
||||
|
||||
* If the [current import context][] contains a member `member` of type `type`
|
||||
* If the [current import context] contains a member `member` of type `type`
|
||||
named `name`, return it.
|
||||
|
||||
> This includes member definitions within the current module.
|
||||
@ -581,8 +581,8 @@ and returns a member of type `type` or null.
|
||||
|
||||
[current import context]: spec.md#current-import-context
|
||||
|
||||
* Let `members` be the set of [unique][] members of type `type` named `name` in
|
||||
[modules of][] the global `@use` rules.
|
||||
* Let `members` be the set of [unique] members of type `type` named `name` in
|
||||
[modules of] the global `@use` rules.
|
||||
|
||||
[unique]: #member
|
||||
[modules of]: at-rules/use.md#a-use-rules-module
|
||||
|
||||
20
spec/spec.md
20
spec/spec.md
@ -6,7 +6,7 @@ Sass is a *living specification*, which means that it's actively updated over
|
||||
time without having distinctions between numbered versions. Different
|
||||
implementations may support different subsets of the specification, although all
|
||||
implementations are expected to work towards full support. The *reference
|
||||
implementation* (currently [Dart Sass][]) will generally support as close to the
|
||||
implementation* (currently [Dart Sass]) will generally support as close to the
|
||||
full spec as possible.
|
||||
|
||||
[Dart Sass]: https://sass-lang.com/dart-sass
|
||||
@ -53,7 +53,7 @@ has no parent.
|
||||
|
||||
### Current Source File
|
||||
|
||||
The *current source file* is the [source file][] that was passed to the
|
||||
The *current source file* is the [source file] that was passed to the
|
||||
innermost active invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[source file]: syntax.md#source-file
|
||||
@ -63,21 +63,21 @@ invocation of Executing a File.
|
||||
|
||||
### Current Configuration
|
||||
|
||||
The *current configuration* is the [configuration][] that was passed to the
|
||||
The *current configuration* is the [configuration] that was passed to the
|
||||
innermost active invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[configuration]: modules.md#configuration
|
||||
|
||||
### Current Import Context
|
||||
|
||||
The *current import context* is the [import context][] that was passed to the
|
||||
The *current import context* is the [import context] that was passed to the
|
||||
innermost active invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[import context]: modules.md#import-context
|
||||
|
||||
### Current Module
|
||||
|
||||
The *current module* is the [module][] that was created by the innermost active
|
||||
The *current module* is the [module] that was created by the innermost active
|
||||
invocation of [Executing a File](#executing-a-file).
|
||||
|
||||
[module]: modules.md#module
|
||||
@ -179,12 +179,12 @@ It runs as follows:
|
||||
* If `url` is not a `file:` URL, set `importer` to be a function that always
|
||||
returns null.
|
||||
|
||||
* Let `file` be the [source file][] with `ast`, canonical URL `url`, and
|
||||
* Let `file` be the [source file] with `ast`, canonical URL `url`, and
|
||||
importer `importer`.
|
||||
|
||||
* Let `module` be the result of [executing](#executing-a-file) `file`.
|
||||
|
||||
* Let `css` be the result of [resolving `module`'s extensions][].
|
||||
* Let `css` be the result of [resolving `module`'s extensions].
|
||||
|
||||
[resolving `module`'s extensions]: at-rules/extend.md#resolving-a-modules-extensions
|
||||
|
||||
@ -196,8 +196,8 @@ It runs as follows:
|
||||
|
||||
### Executing a File
|
||||
|
||||
This algorithm takes a [source file][] `file`, a [configuration][] `config`, an
|
||||
[import context][] `import`, and returns a [module][].
|
||||
This algorithm takes a [source file] `file`, a [configuration] `config`, an
|
||||
[import context] `import`, and returns a [module].
|
||||
|
||||
* Let `module` be an empty module with source file `file`.
|
||||
|
||||
@ -216,7 +216,7 @@ This algorithm takes a [source file][] `file`, a [configuration][] `config`, an
|
||||
yet in `module`, set `variable` to `null` in `module`.
|
||||
|
||||
> This isn't necessary for implementations that follow the most recent
|
||||
> [variables spec][] and don't allow `!global` assignments to variables
|
||||
> [variables spec] and don't allow `!global` assignments to variables
|
||||
> that don't yet exist. However, at time of writing, all existing
|
||||
> implementations are in the process of deprecating the old `!global`
|
||||
> behavior, which allowed `!global` declarations to create new
|
||||
|
||||
@ -60,7 +60,7 @@ representation of the intermediate production.
|
||||
### `InterpolatedIdentifier`
|
||||
|
||||
<x><pre>
|
||||
**InterpolatedIdentifier** ::= ([\<ident-token>][] | '-'? Interpolation) ([Name][] | Interpolation)*
|
||||
**InterpolatedIdentifier** ::= ([\<ident-token>] | '-'? Interpolation) ([Name] | Interpolation)*
|
||||
</pre></x>
|
||||
|
||||
[\<ident-token>]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
@ -72,7 +72,7 @@ No whitespace is allowed between components of an `InterpolatedIdentifier`.
|
||||
|
||||
<x><pre>
|
||||
**InterpolatedUrl** ::= 'url(' (QuotedString | InterpolatedUnquotedUrlContents) ')'
|
||||
**InterpolatedUnquotedUrlContents** ::= ([unescaped url contents][] | [escape][] | Interpolation)*
|
||||
**InterpolatedUnquotedUrlContents** ::= ([unescaped url contents] | [escape] | Interpolation)*
|
||||
</pre></x>
|
||||
|
||||
[unescaped url contents]: https://www.w3.org/TR/css-syntax-3/#url-token-diagram
|
||||
@ -82,7 +82,7 @@ No whitespace is allowed between components of an `InterpolatedUnquotedUrlConten
|
||||
### `Name`
|
||||
|
||||
<x><pre>
|
||||
**Name** ::= ([identifier code point][] | [escape][])+
|
||||
**Name** ::= ([identifier code point] | [escape])+
|
||||
</pre></x>
|
||||
|
||||
[identifier code point]: https://drafts.csswg.org/css-syntax-3/#identifier-code-point
|
||||
@ -112,7 +112,7 @@ No whitespace is allowed between components of an `InterpolatedUnquotedUrlConten
|
||||
**PseudoSelector** ::= NormalPseudoSelector
|
||||
  | SelectorPseudo
|
||||
  | NthSelectorPseudo
|
||||
**NormalPseudoSelector** ::= ':' ':'? VendorPrefix? [\<ident-token>][]
|
||||
**NormalPseudoSelector** ::= ':' ':'? VendorPrefix? [\<ident-token>]
|
||||
  ('(' [\<declaration-value>] ')')?
|
||||
**SelectorPseudo** ::= SelectorPseudoName '(' Selector ')'
|
||||
**NthSelectorPseudo** ::= NthSelectorPseudoName '(' [\<an+b>] 'of'¹ Selector ')'
|
||||
@ -284,12 +284,12 @@ SCSS:
|
||||
|
||||
### Consuming an Identifier
|
||||
|
||||
This algorithm consumes input from a stream of [code points][] and returns a
|
||||
This algorithm consumes input from a stream of [code points] and returns a
|
||||
string.
|
||||
|
||||
[code points]: https://infra.spec.whatwg.org/#code-point
|
||||
|
||||
This production has the same grammar as [`<ident-token>`][].
|
||||
This production has the same grammar as [`<ident-token>`].
|
||||
|
||||
[`<ident-token>`]: https://drafts.csswg.org/css-syntax-3/#ident-token-diagram
|
||||
|
||||
@ -301,10 +301,10 @@ This production has the same grammar as [`<ident-token>`][].
|
||||
|
||||
* If the stream starts with `-`, consume it and append it to `string`.
|
||||
|
||||
* If the stream starts with `\`, [consume an escaped code point][] with the
|
||||
* If the stream starts with `\`, [consume an escaped code point] with the
|
||||
`start` flag set and append it to `string`.
|
||||
|
||||
* Otherwise, if the stream starts with an [identifier-start code point][],
|
||||
* Otherwise, if the stream starts with an [identifier-start code point],
|
||||
consume it and append it to `string`.
|
||||
|
||||
* Otherwise, throw an error.
|
||||
@ -318,9 +318,9 @@ This production has the same grammar as [`<ident-token>`][].
|
||||
|
||||
### Consuming an Interpolated Identifier
|
||||
|
||||
This algorithm consumes input from a stream of [code points][] and returns a
|
||||
This algorithm consumes input from a stream of [code points] and returns a
|
||||
sequence of strings and/or expressions. It follows the grammar for an
|
||||
[`InterpolatedIdentifier`][].
|
||||
[`InterpolatedIdentifier`].
|
||||
|
||||
[`InterpolatedIdentifier`]: #interpolatedidentifier
|
||||
|
||||
@ -335,7 +335,7 @@ sequence of strings and/or expressions. It follows the grammar for an
|
||||
* Otherwise, [consume an identifier](#consuming-an-identifier) and add its string
|
||||
to `components`.
|
||||
|
||||
* While the input starts with `#{`, a [identifier code point][], or `\`:
|
||||
* While the input starts with `#{`, a [identifier code point], or `\`:
|
||||
|
||||
* If the input starts with `#{`, consume an interpolation and add
|
||||
its expression to `components`.
|
||||
@ -347,50 +347,50 @@ sequence of strings and/or expressions. It follows the grammar for an
|
||||
|
||||
### Consuming a Name
|
||||
|
||||
This algorithm consumes input from a stream of [code points][] and returns a
|
||||
This algorithm consumes input from a stream of [code points] and returns a
|
||||
string. The grammar for this production is:
|
||||
|
||||
<x><pre>
|
||||
**Name** ::= ([identifier code point][] | [escape][])+
|
||||
**Name** ::= ([identifier code point] | [escape])+
|
||||
</pre></x>
|
||||
|
||||
* Let `string` be an empty string.
|
||||
|
||||
* While the input starts with a [identifier code point][] or `\`:
|
||||
* While the input starts with a [identifier code point] or `\`:
|
||||
|
||||
* If the input starts with a [identifier code point][], consume it and append
|
||||
* If the input starts with a [identifier code point], consume it and append
|
||||
it to `string`.
|
||||
|
||||
* Otherwise, [consume an escaped code point][] and append it to `string`.
|
||||
* Otherwise, [consume an escaped code point] and append it to `string`.
|
||||
|
||||
* Return `string`.
|
||||
|
||||
### Consuming an Escaped Code Point
|
||||
|
||||
This algorithm consumes input from a stream of [code points][]. It takes an
|
||||
This algorithm consumes input from a stream of [code points]. It takes an
|
||||
optional boolean flag, `start`, which indicates whether it's at the beginning of
|
||||
an identifier and defaults to false. It returns a string.
|
||||
|
||||
This production has the same grammar as [`escape`][escape] in CSS Syntax Level 3.
|
||||
|
||||
* If the stream doesn't [start with a valid escape][], throw an error.
|
||||
* If the stream doesn't [start with a valid escape], throw an error.
|
||||
|
||||
[start with a valid escape]: https://drafts.csswg.org/css-syntax-3/#starts-with-a-valid-escape
|
||||
|
||||
* Let `codepoint` be the result of [consuming an escaped code point][].
|
||||
* Let `codepoint` be the result of [consuming an escaped code point].
|
||||
|
||||
[consuming an escaped code point]: https://drafts.csswg.org/css-syntax-3/#consume-escaped-code-point
|
||||
|
||||
* Let `character` be the string containing only `codepoint`.
|
||||
|
||||
* If `codepoint` is a [identifier-start code point][], return `character`.
|
||||
* If `codepoint` is a [identifier-start code point], return `character`.
|
||||
|
||||
* Otherwise, if `codepoint` is an [identifier code point][] and the `start` flag
|
||||
* Otherwise, if `codepoint` is an [identifier code point] and the `start` flag
|
||||
is not set, return `character`.
|
||||
|
||||
* Otherwise, if `codepoint` is a [non-printable code point][], U+0009 CHARACTER
|
||||
* Otherwise, if `codepoint` is a [non-printable code point], U+0009 CHARACTER
|
||||
TABULATION, U+000A LINE FEED, U+000D CARRIAGE RETURN, or U+000C FORM FEED;
|
||||
*or* if `codepoint` is a [digit][] and the `start` flag is set:
|
||||
*or* if `codepoint` is a [digit] and the `start` flag is set:
|
||||
|
||||
[non-printable code point]: https://drafts.csswg.org/css-syntax-3/#non-printable-code-point
|
||||
|
||||
|
||||
@ -13,8 +13,8 @@
|
||||
|
||||
<x><pre>
|
||||
**Variable** ::= PlainVariable | NamespacedVariable
|
||||
**PlainVariable** ::= '\$' [\<ident-token>][]
|
||||
**NamespacedVariable** ::= [\<ident-token>][] '.$' [PublicIdentifier][]
|
||||
**PlainVariable** ::= '\$' [\<ident-token>]
|
||||
**NamespacedVariable** ::= [\<ident-token>] '.$' [PublicIdentifier]
|
||||
**VariableDeclaration** ::= Variable ':' Expression ('!global' | '!default')*
|
||||
</pre></x>
|
||||
|
||||
@ -36,7 +36,7 @@ To execute a `VariableDeclaration` `declaration`:
|
||||
|
||||
* Let `name` be `declaration`'s `Variable`.
|
||||
|
||||
* Let `resolved` be the result of [resolving a variable][] named `name`.
|
||||
* Let `resolved` be the result of [resolving a variable] named `name`.
|
||||
|
||||
[resolving a variable]: modules.md#resolving-a-member
|
||||
|
||||
@ -105,7 +105,7 @@ To execute a `VariableDeclaration` `declaration`:
|
||||
|
||||
To evaluate a `Variable` `variable`:
|
||||
|
||||
* Let `definition` be the result of [resolving a variable][] named `variable`.
|
||||
* Let `definition` be the result of [resolving a variable] named `variable`.
|
||||
If this returns null, throw an error.
|
||||
|
||||
* Return `definition`'s value.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user