An interface for functions and mixins that can be invoked from Sass by passing in arguments.
This extends AsyncCallable because all synchronous callables are also
usable in asynchronous contexts. Callables are usable with both the
synchronous and asynchronous
compile() functions, and as such should be
used in preference to AsyncCallables if possible.
When writing custom functions, it's important to make them as user-friendly and as close to the standards set by Sass's core functions as possible. Some good guidelines to follow include:
Value.assert*methods, like Value.assertString, to cast untyped
Valueobjects to more specific types. For values from the argument list, pass in the argument name as well. This ensures that the user gets good error messages when they pass in the wrong type to your function.
Individual classes may have more specific
assert*methods, like SassNumber.assertInt, which should be used when possible.
In Sass, every value counts as a list. Functions should avoid casting values to the
SassListtype, and should use the Value.asList method instead.
When manipulating values like lists, strings, and numbers that have metadata (comma versus sepace separated, bracketed versus unbracketed, quoted versus unquoted, units), the output metadata should match the input metadata. For lists, the
Value.changeListmethod can be used to do this automatically.
When in doubt, lists should default to comma-separated, strings should default to quoted, and number should default to unitless.
In Sass, lists and strings use one-based indexing and use negative indices to index from the end of value. Functions should follow these conventions. The Value.sassIndexToListIndex and SassString.sassIndexToStringIndex methods can be used to do this automatically.
String indexes in Sass refer to Unicode code points while Dart string indices refer to UTF-16 code units. For example, the character U+1F60A, Smiling Face With Smiling Eyes, is a single Unicode code point but is represented in UTF-16 as two code units (
0xDE0A). So in Dart,
0xD83D, whereas in Sass
str-slice("a😊b", 1, 1)returns
"😊". Functions should follow this convention. The SassString.sassIndexToStringIndex and SassString.sassIndexToRuneIndex methods can be used to do this automatically, and the SassString.sassLength getter can be used to access a string's length in code points.