--name(), $name()
Define a function of your own, then call it anywhere in the doodle. A call is replaced by the function's body, with the arguments in place of the parameters.
Syntax
- --<name>(<param>, ...): <body>;
- --<name>(<param> = <default>, ...): <body>;
- --<name>(): { <body> }
- --<name>(<param>, ...): { result: <value>; }
- $<name>(<argument>, ...)
A definition goes at the top level of the doodle, before or after its calls, or inside an @svg(), and emits nothing.
In the body, $p is the argument passed for the parameter p.
Values
The simplest body is one value. = value gives a parameter a default, used when a call leaves it out:
@grid: 6 / 60vmin _2px;
--dot(r, c = #000): radial-gradient($c $r, #0000 0);
background: $dot(30%), $dot(60%, #e6437d); Inside $() the parameter can be written without $:
@grid: 9 / 60vmin;
--wave(v): $(sin(v / 1.5) / 2 + .5);
background: #000;
border-radius: 50%;
scale: $wave(@x);
opacity: $wave(@y);
Inside $() a call is one value: with --inc(x): x + 1, $(2 * $inc(3)) is 8.
There the $ can be left out, as in $(2 * inc(3)) or @match(inc(x) > 3) { … }.
A body can give a point: with --at(a): $(cos(a)) $(sin(a)),
points: @m(6, $at($(n * π / 3))) in @svg is a hexagon.
Declarations and elements
A body in braces can hold several declarations, pasted where the function is called:
@grid: 7 / 60vmin _2px;
--fill(c, r): {
background: $c;
border-radius: $r;
}
@even { $fill(#000, 50%) }
@odd { $fill(#e6437d, 10%) }
The same works for elements inside @svg.
A definition can also go inside the @svg(), where only that @svg() sees it:
@grid: 1 / 60vmin;
background: @svg(
viewBox: -10 -10 20 20;
--dot(r, c = #000): circle { r: $r; fill: $c }
$dot(8) $dot(5, #e6437d) $dot(2)
); In @pattern and @scene
Calls work inside @pattern and @scene bodies too,
where a parameter reads bare. A body that assigns result gives a value,
and each call keeps its own names, so the two rings here have their own d:
@grid: 1 / 60vmin;
--ring(p, r, w = .01): {
d: abs(length(p) - r);
result: 1 - smoothstep(0, w, d);
}
@content: @pattern(
a: $ring(pos, .3);
b: $ring(pos - vec2(.15, 0), .15, .03);
fill: mix(#fff, #000, max(a, b));
); result: a, b gives several values, and r, a: before a call takes one each.
Here one call gives the distance and the angle of each pixel:
@grid: 1 / 60vmin;
--polar(p): {
result: length(p), atan(p.y, p.x) / 2π;
}
@content: @pattern(
r, a: $polar(pos);
fill: mix(#fff, #000, step(.5, fract(a * 6 + r * 4)));
); Reference
Definitions and calls
| Part | Rule |
|---|---|
| name | letters, digits, _, and - between words, starting with a letter or _ |
| parameter | a name such as x or size, with an optional = default |
| body | one statement up to its ;, or any text inside braces. A call is replaced by it, so it works wherever its text would. |
$p | the argument passed for p. Inside $() and the test of a @match(…) { } block a bare p works too, and reads the argument in parentheses. |
bare name(…) | in the same places, calls the function as $name(…) does, unless a built-in such as sin has the name |
| arguments | a random or picking argument such as @r(5) is worked out once at the call, so every use of the parameter gets the same number. Other arguments are pasted as written. In the arguments of a call a bare p is the argument, as $p is, unless a : follows it or a dash joins it to a word, as in var(--p): with --seg(k): $(k * 10)px, --row(k): $seg(k + 1) makes $row(3) 40px. |
result | a body made only of result declarations gives the last one's value, as a CSS @function does: with --double(x): { result: $(x * 2); }, $double(2) is 4. A body with any other statement is pasted as written. |
| scope | calls work anywhere but inside quotes, nested @doodle code included. A definition inside an @svg() is seen only there. Code inserted with @use can call the doodle's functions. |
| no such function | $name without parentheses is still the custom property --name, and $name(…) warns, then appends name as a unit |
| errors | a function that calls itself is reported, and the call expands to nothing. A call with too many arguments, or a missing one without a default, is reported too. |
In @pattern and @scene
| Part | Rule |
|---|---|
| parameter | reads bare, as $p does, and p.xy takes its swizzle. It hides a built-in of the same name. |
| argument | one value, so with --f(a): a * 2, $f(x + 1) reads (x + 1) * 2 |
| expression body | one value too, so with --g(a): a + 1, $g(x) * 2 reads (x + 1) * 2 |
result | the call reads as the last result assigned. To assign it inside a match block, give it a value before the block. |
result: a, b | several values: r, a: $polar(pos) sets one name to each. Anywhere else the call reads as the first. |
| names | a name reads the caller's until the body assigns it. p: p * 2 changes the function's own copy; the caller's names stay as they were. |
without result | the body is pasted where it is called and writes the caller's names, as its text would |