Merge pull request sass#370 from sass/new-functions

Document new built-in functions
asaf400 · Sep 24, 2019 · 445c07b · 445c07b
2 parents 67a5e2b + b2c30bc
commit 445c07b
Show file tree

Hide file tree

Showing 9 changed files with 235 additions and 31 deletions.
diff --git 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/assets/js/components/redirect.js b/source/assets/js/components/redirect.js
@@ -196,6 +196,13 @@ if (window.location.hash) {
       "#hsla": "/documentation/modules#hsla"
     };
 
+    var redirect = redirects[window.location.hash];
+    if (redirect) window.location.href = redirect;
+  } else if (window.location.pathname == "/documentation/modules/map") {
+    var redirects = {
+      "#keywords": "/documentation/modules/meta#keywords"
+    };
+
     var redirect = redirects[window.location.hash];
     if (redirect) window.location.href = redirect;
   }

diff --git a/source/code-snippets/_example-mixin-arbitrary-keyword-arguments.html.erb b/source/code-snippets/_example-mixin-arbitrary-keyword-arguments.html.erb
@@ -1,11 +1,11 @@
 <% example do %>
-  @use "sass:map";
+  @use "sass:meta";
 
   @mixin syntax-colors($args...) {
-    @debug map.keywords($args);
+    @debug meta.keywords($args);
     // (string: #080, comment: #800, $variable: $60b)
 
-    @each $name, $color in map.keywords($args) {
+    @each $name, $color in meta.keywords($args) {
       pre span.stx-#{$name} {
         color: $color;
       }
@@ -18,13 +18,13 @@
     $variable: #60b,
   )
   ===
-  @use "sass:map"
+  @use "sass:meta"
 
   @mixin syntax-colors($args...)
-    @debug map.keywords($args)
+    @debug meta.keywords($args)
     // (string: #080, comment: #800, $variable: $60b)
 
-    @each $name, $color in map.keywords($args)
+    @each $name, $color in meta.keywords($args)
       pre span.stx-#{$name}
         color: $color
 

diff --git a/source/documentation/at-rules/function.html.md.erb b/source/documentation/at-rules/function.html.md.erb
@@ -190,20 +190,20 @@ argument is known as an [argument list][].
 #### Taking Arbitrary Keyword Arguments
 
 Argument lists can also be used to take arbitrary keyword arguments. The
-[`map.keywords()` function][] takes an argument list and returns any extra
+[`meta.keywords()` function][] takes an argument list and returns any extra
 keywords that were passed to the function as a [map][] from argument names (not
 including `$`) to those arguments' values.
 
-[`map.keywords()` function]: ../modules/map#keywords
+[`meta.keywords()` function]: ../modules/meta#keywords
 [map]: ../values/maps
 
 <% fun_fact do %>
-  If you don't ever pass an argument list to the [`map.keywords()` function][],
+  If you don't ever pass an argument list to the [`meta.keywords()` function][],
   that argument list won't allow extra keyword arguments. This helps callers of
   your function make sure they haven't accidentally misspelled any argument
   names.
 
-  [`map.keywords()` function]: ../modules/map#keywords
+  [`meta.keywords()` function]: ../modules/meta#keywords
 <% end %>
 
 #### Passing Arbitrary Arguments

diff --git a/source/documentation/at-rules/mixin.html.md.erb b/source/documentation/at-rules/mixin.html.md.erb
@@ -256,24 +256,24 @@ is known as an [argument list][].
 #### Taking Arbitrary Keyword Arguments
 
 Argument lists can also be used to take arbitrary keyword arguments. The
-[`map.keywords()` function][] takes an argument list and returns any extra
+[`meta.keywords()` function][] takes an argument list and returns any extra
 keywords that were passed to the mixin as a [map][] from argument names (not
 including `$`) to those arguments' values.
 
-[`map.keywords()` function]: ../modules/map#keywords
+[`meta.keywords()` function]: ../modules/meta#keywords
 [map]: ../values/maps
 
 <%# TODO(nweiz): auto-generate this CSS once we're compiling with Dart Sass %>
 
 <%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
 
 <% fun_fact do %>
-  If you don't ever pass an argument list to the [`map.keywords()` function][],
+  If you don't ever pass an argument list to the [`meta.keywords()` function][],
   that argument list won't allow extra keyword arguments. This helps callers of
   your mixin make sure they haven't accidentally misspelled any argument
   names.
 
-  [`map.keywords()` function]: ../modules/map#keywords
+  [`meta.keywords()` function]: ../modules/meta#keywords
 <% end %>
 
 #### Passing Arbitrary Arguments

diff --git a/source/documentation/modules/map.html.md.erb b/source/documentation/modules/map.html.md.erb
@@ -49,20 +49,6 @@ title: sass:map
 <% end %>
 
 
-<% function 'map.keywords($args)', 'keywords($args)', returns: 'map' do %>
-  Returns the keywords passed to a mixin or function that takes [arbitrary
-  arguments][]. The `$args` argument must be an [argument list][].
-
-  [arbitrary arguments]: ../at-rules/mixin#taking-arbitrary-arguments
-  [argument list]: ../values/lists#argument-lists
-
-  The keywords are returned as a map from argument names as unquoted strings (not
-  including `$`) to the values of those arguments.
-
-  <%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
-<% end %>
-
-
 <% function 'map.merge($map1, $map2)',
             'map-merge($map1, $map2)',
             returns: 'map' do %>

diff --git 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.sass
+    $border-contrast: false !default
+
+    code
+      background-color: #6b717f
+      color: #d2e1dd
+      @if $border-contrast
+        border-color: #dadbdf
+    ---
+    // style.sass
+    @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' %>
 
@@ -198,6 +291,20 @@ title: sass:meta
 <% end %>
 
 
+<% function 'meta.keywords($args)', 'keywords($args)', returns: 'map' do %>
+  Returns the keywords passed to a mixin or function that takes [arbitrary
+  arguments][]. The `$args` argument must be an [argument list][].
+
+  [arbitrary arguments]: ../at-rules/mixin#taking-arbitrary-arguments
+  [argument list]: ../values/lists#argument-lists
+
+  The keywords are returned as a map from argument names as unquoted strings (not
+  including `$`) to the values of those arguments.
+
+  <%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
+<% end %>
+
+
 <% function 'meta.mixin-exists($name)',
             'mixin-exists($name)',
             returns: 'boolean' do %>
@@ -225,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
@@ -0,0 +1,3 @@
+<% impl_status dart: '(unreleased)', libsass: false, ruby: false do %>
+  Only Dart Sass currently supports this function.
+<% end %>
diff --git a/source/documentation/values/lists.html.md.erb b/source/documentation/values/lists.html.md.erb
@@ -180,9 +180,9 @@ When you declare a mixin or function that takes [arbitrary arguments][], the
 value you get is a special list known as an *argument list*. It acts just like a
 list that contains all the arguments passed to the mixin or function, with one
 extra feature: if the user passed keyword arguments, they can be accessed as a
-map by passing the argument list to the [`map.keywords()` function][].
+map by passing the argument list to the [`meta.keywords()` function][].
 
 <%= partial 'code-snippets/example-mixin-arbitrary-keyword-arguments' %>
 
 [arbitrary arguments]: ../at-rules/mixin#taking-arbitrary-arguments
-[`map.keywords()` function]: ../modules/map#keywords
+[`meta.keywords()` function]: ../modules/meta#keywords