Function

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

PartRule
nameletters, digits, _, and - between words, starting with a letter or _
parametera name such as x or size, with an optional = default
bodyone statement up to its ;, or any text inside braces. A call is replaced by it, so it works wherever its text would.
$pthe 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
argumentsa 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.
resulta 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.
scopecalls 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
errorsa 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

PartRule
parameterreads bare, as $p does, and p.xy takes its swizzle. It hides a built-in of the same name.
argumentone value, so with --f(a): a * 2, $f(x + 1) reads (x + 1) * 2
expression bodyone value too, so with --g(a): a + 1, $g(x) * 2 reads (x + 1) * 2
resultthe call reads as the last result assigned. To assign it inside a match block, give it a value before the block.
result: a, bseveral values: r, a: $polar(pos) sets one name to each. Anywhere else the call reads as the first.
namesa 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 resultthe body is pasted where it is called and writes the caller's names, as its text would

See also