sass

|unrecognize|未被认识的，未被承认的， 被忽略的|

|recognized|承认，认出，认可|

|invoke|调用，激活，请求，提及|

|contrast|对比，对照，反差|

|relative|相对的，相关的，比较的|

sass:meta

mixins

• meta.load-css($url, $width: null): loads the module at $url and includes its css, if passed $with, it must be a map(key without $), and $url can be relative
• $url should be a string but not be a css url()
• like the @use rule:
  • only evaluate the given module once
  • cannot provide configuration to already loaded module
• unlike the @use rule:
  • in loaded module, any members don’t avaliable in the current module
  • can used to anywhere in stylesheet even can nested
  • url can come from variable and include interpolation

// 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));
}

functions

• meta.call($function, $args…) or call($function, $args…):
  • invoke $function with $args and return result
  • $function should be a function returned by meta.get-function()

@use "sass:list";
@use "sass:meta";
@use "sass:string";
// return a copy of $list with all elements for with $condition returns `true` removed
@function remove-where($list, $condition) {
  $new-list: ();
  $separator: list.separactor($list);
  @each $element in $list {
    @if not meta.call($condition, $element) {
      $new-list: list.append($new-list, $element, $separactor: $separactor);
    }
  }
  @return $new-list;
}
$fonts: Tahoma, Geneva, "Helvetica Neue", Helvetica, Arial, sans-serif;
content {
  @function contains-helvetica($string)  {
    @return string.index ($string, "Helvetica");
  }
  font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

• meta.content-exists() or content-exists()
  • return boolean whether the current mixin was passed a @content block
  • throws an error if called outside of a mixin

@mixin debug-content-exists {
  @debug meta.content-exists();
  @content;
}
@include debug-content-exists;    // false
@include debug-content-exists {    // true
  // content!
}

• meta.feature-exists($feature) or feature-exists($feature):
  • return boolean whether the current sass-implementation support $feature
  • $feature must be a string:
    • global-variable-shadowing: means local variable will shadow a global variable unless it’s !global flag
    • extend-selector-psedoclass: means @extend rule will affect selector nested in pseudo-class like :not()
    • units-level3: means unit arithmetic support units defined in css values and units level 3
    • at-error: means support @error rule
    • custom-property: means custom property declaration values only support interpolation, doesn’t support other expression
    • any unrecognize $feature return false

@debug meta.feature-exists("at-error");    // true
@debug meta.feature-exists("unrecognize");    // false

• meta.function-exists($name) or function-exists($name): reurn boolean whether a function is defined

@debug meta.function-exists("scale-color");    // true
@debug meta.function-exists("add");    // false
@function add($num1, $num2) {
  @return $num1 + $num2;
}
@debug meta.function-exists("add");    // true

• meta.get-function($name, $css: false) or get-function($name, $css: false):
  • return named $name function
  • if named $name function not existing, will throws an error
  • if $css is true, it instead returns a plain css function
  • returned function can be called using meta.call()

@use "sass:list";
@use "sass:meta";
@use "sass:string";
// return a copy of $list with all elements for which $condition returns `true` removed
@function remove-where($list, $condition) {
  $new-list: ();
  $separactor: list.separactor($list);
  @each $element in $list {
    @if not meta.call($condition, $element) {
      $new-list: list.append($new-list, $element, $separator: $srparator);
    }
  }
  @return $new-list;
}
content {
  @function contains-helvetica($string) {
    @return string.index($string, "Helvetica");
  }
  font-family: remove-where($fonts, meta.get-function("contains-helvetica"));
}

• meta.global-variable-exists($name) or global-variable-exists($name): return boolean whether exist a named $name global variable

@debug meta.global-variable-exists("var1");    // false
$var1: value;
@debug meta.global-variable-exists("var1);    // true
h1 {
  // $var2 is local
  $var2: value;
  @debug meta.global-variable-exists("var2");    // false
}

• meta.inspect($value) or inspect($value): return a unquoted string of any sass value not only css value, the function is intended for debugging

@debug meta.inspect(10px 20px 30px);    // unquote("10px 20px 30px")
@debug meta.inspect(("width": 200px));    // unquote('("width": 200px)')
@debug meta.inspect(null);    // unquote("null")
@debug meta.inspect("Helvetica");    // unquote('"Helvetica"')

• meta.keywords($args) or keywords($args): return keyword-map(key without $) passed to mixin or function takes arbitrary arguments, $args must be an arguments list

@use "sass:meta";
@mixin syntax-colors($args...) {
  @debug meta.keywords($args);
  // (string: #080, comment: #800, variable: #60b)
  @each $name, $color in meta.keywords($args) {
    pre span.stx-#{$name} {
      color: $color;
    }
  }
}
@include syntax-colors(
  $string: #080,
  $comment: #800,
  $variable: #60b,
  )

• meta.mixin-exists($name) or mixin-exists($name) return boolean whether named $name mixin exists

@debug meta.mixin-exists("shadow-none");    // false
@mixin shadow-none {
  box-shadow: none;
}
@debug meta.mixin-exists("shadow-none");    // true

• meta.module-functions($module) return have all function-key-value map in module, the $module must refer using @use rule

// _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

• meta.module-variables($module) return all variables-key-value-map(without $) defined in a module, and need using @use rule

// _variables.scss
$hopbush: #c69;
$midnight-blue: #036;
$wafer: #e1d7d2;
@use "sass:meta";
@use "variables";
@debug meta.module-variales("variables");
// (
//     "hopbush": #c69,
//     "midnight-blue": #036,
//     "wafer": #e1d7d2,
//    )

• meta.type-of($value) or type-of($value) return the type of $value like these: number, string, color, list, mpa, bool, null, function, arglist, and () may return list or map, depending whether returned by map function

@debug meta.type-of(10px);    // number
@debug meta.type-of(10px 20px 30px);    // list
@debug meta.type-of(());     // list

• meta.variale-exists($name) or variable-exists($name) return boolean whether named $name variable existing in current scope

@debug meta.variable-exists("var1);    // false
$var1: value;
@debug meta.variable-exists("val1");    // true
h1 {
  // $var2 is local
  $var2: value;
  @debug meta.variable-exists("var2");    // true
}