From 88c1a23bc21ad72c83973e67a755dace397baa34 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Tue, 10 Sep 2019 17:28:10 -0700 Subject: [PATCH] Document new built-in functions Closes #365 --- helpers/sass_helpers.rb | 2 +- source/documentation/modules/meta.html.md.erb | 194 ++++++++++++++++++ .../_module-system-function-status.erb | 3 + 3 files changed, 198 insertions(+), 1 deletion(-) create mode 100644 source/documentation/snippets/_module-system-function-status.erb diff --git a/helpers/sass_helpers.rb b/helpers/sass_helpers.rb index e432eaaec..0f6536c6a 100644 --- a/helpers/sass_helpers.rb +++ b/helpers/sass_helpers.rb @@ -423,7 +423,7 @@ def _impl_status_row(name, status) ] end - # Renders API docs for a Sass function. + # Renders API docs for a Sass function (or mixin). # # The function's name is parsed from the signature. The API description is # passed as a Markdown block. If `returns` is passed, it's included as the diff --git a/source/documentation/modules/meta.html.md.erb b/source/documentation/modules/meta.html.md.erb index 0ec7a9863..1c20f59f3 100644 --- a/source/documentation/modules/meta.html.md.erb +++ b/source/documentation/modules/meta.html.md.erb @@ -4,6 +4,99 @@ title: sass:meta <%= partial '../snippets/built-in-module-status' %> +## Mixins + +<% function 'meta.load-css($url, $with: null)' do %> + <% impl_status dart: '(unreleased)', libsass: false, ruby: false do %> + Only Dart Sass currently supports this mixin. + <% end %> + + Loads the [module][] at `$url` and includes its CSS as though it were written + as the contents of this mixin. The `$with` parameter provides + [configuration][] for the modules; if it's passed, it must be a map from + variable names (without `$`) to the values of those variables to use in the + loaded module. + + [module]: ../at-rules/use + [configuration]: ../at-rules/use#configuring-modules + + If `$url` is relative, it's interpreted as relative to the file in which + `meta.load-css()` is included. + + **Like the [`@use` rule][]**: + + [`@use` rule]: ../at-rules/use + + * This will only evaluate the given module once, even if it's loaded multiple + times in different ways. + + * This cannot provide configuration to a module that's already been loaded, + whether or not it was already loaded with configuration. + + **Unlike the [`@use` rule][]**: + + * This doesn't make any members from the loaded module available in the + current module. + + * This can be used anywhere in a stylesheet. It can even be nested within + style rules to create nested styles! + + * The module URL being loaded can come from a variable and include + [interpolation][]. + + [interpolation]: ../interpolation + + <% heads_up do %> + The `$url` parameter should be a string containing a URL like you'd pass to + the `@use` rule. It shouldn't be a CSS `url()`! + <% end %> + + <% example(autogen_css: false) do %> + // dark-theme/_code.scss + $border-contrast: false !default; + + code { + background-color: #6b717f; + color: #d2e1dd; + @if $border-contrast { + border-color: #dadbdf; + } + } + --- + // style.scss + @use "sass:meta"; + + body.dark { + @include meta.load-css("dark-theme/code", + $with: ("border-contrast": true)); + } + === + // dark-theme/_code.scss + $border-contrast: false !default + + code + background-color: #6b717f + color: #d2e1dd + @if $border-contrast + border-color: #dadbdf + --- + // style.scss + @use "sass:meta" + + body.dark + $configuration: ("border-contrast": true) + @include meta.load-css("dark-theme/code", $with: $configuration) + === + body.dark code { + background-color: #6b717f; + color: #d2e1dd; + border-color: #dadbdf; + } + <% end %> +<% end %> + +## Functions + <% function 'meta.call($function, $args...)', 'call($function, $args...)' do %> <%= partial 'documentation/snippets/call-impl-status' %> @@ -239,6 +332,107 @@ title: sass:meta <% end %> +<% function 'meta.module-functions($module)', + returns: 'map' do %> + <%= partial '../snippets/module-system-function-status' %> + + Returns all the functions defined in a module, as a map from function names to + [function values][]. + + [function values]: ../values/functions + + The `$module` parameter must be a string matching the namespace of a [`@use` + rule][] in the current file. + + [`@use` rule]: ../at-rules/use + + <% example(autogen_css: false) do %> + // _functions.scss + @function pow($base, $exponent) { + $result: 1; + @for $_ from 1 through $exponent { + $result: $result * $base; + } + @return $result; + } + --- + @use "sass:map"; + @use "sass:meta"; + + @use "functions"; + + @debug meta.module-functions("functions"); // ("pow": get-function("pow")) + + @debug meta.call(map.get(meta.module-variables("functions"), "pow"), 3, 4); // 16 + === + // _functions.sass + @function pow($base, $exponent) + $result: 1 + @for $_ from 1 through $exponent + $result: $result * $base + + @return $result + --- + @use "sass:map" + @use "sass:meta" + + @use "functions" + + @debug meta.module-functions("functions") // ("pow": get-function("pow")) + + @debug meta.call(map.get(meta.module-variables("functions"), "pow"), 3, 4) // 16 + <% end %> +<% end %> + + +<% function 'meta.module-variables($module)', + returns: 'map' do %> + <%= partial '../snippets/module-system-function-status' %> + + Returns all the variables defined in a module, as a map from variable names + (without `$`) to the values of those variables. + + The `$module` parameter must be a string matching the namespace of a [`@use` + rule][] in the current file. + + [`@use` rule]: ../at-rules/use + + <% example(autogen_css: false) do %> + // _variables.scss + $hopbush: #c69; + $midnight-blue: #036; + $wafer: #e1d7d2; + --- + @use "sass:meta"; + + @use "variables"; + + @debug meta.module-variables("variables"); + // ( + // "hopbush": #c69, + // "midnight-blue": #036, + // "wafer": #e1d7d2 + // ) + === + // _variables.sass + $hopbush: #c69 + $midnight-blue: #036 + $wafer: #e1d7d2 + --- + @use "sass:meta" + + @use "variables" + + @debug meta.module-variables("variables") + // ( + // "hopbush": #c69, + // "midnight-blue": #036, + // "wafer": #e1d7d2 + // ) + <% end %> +<% end %> + + <% function 'meta.type-of($value)', 'type-of($value)', returns: 'unquoted string' do %> diff --git a/source/documentation/snippets/_module-system-function-status.erb b/source/documentation/snippets/_module-system-function-status.erb new file mode 100644 index 000000000..8a462db2c --- /dev/null +++ b/source/documentation/snippets/_module-system-function-status.erb @@ -0,0 +1,3 @@ +<% impl_status dart: '(unreleased)', libsass: false, ruby: false do %> + Only Dart Sass currently supports this function. +<% end %>