Callable class abstract interface

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:

  • Use Value.assert* methods, like Value.assertString, to cast untyped Value objects 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 SassList type, and should use the Value.asList method instead.

  • When manipulating values like lists, strings, and numbers that have metadata (comma versus space separated, bracketed versus unbracketed, quoted versus unquoted, units), the output metadata should match the input metadata. For lists, the Value.withListContents method 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 (0xD83D and 0xDE0A). So in Dart, "a😊b".codeUnitAt(1) returns 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.

Implemented types
Annotations
  • @sealed

Constructors

Callable(String name, String arguments, Value callback(List<Value> arguments))
factory
Callable.fromSignature(String signature, Value callback(List<Value> arguments), {bool requireParens = true})
Creates a callable with a single signature and a single callback.
factory
Callable.function(String name, String arguments, Value callback(List<Value> arguments))
Creates a function with the given name and arguments that runs callback when called.
factory

Properties

hashCode → int
The hash code for this object.
no setterinherited
name → String
The callable's name.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited