JavaScript functions

A function written in JavaScript: for calculations and geometry that are easier to write in a general-purpose language, with the drawing's variables and points to hand. It is called, saved and made again when the drawing changes, as any other function is.

Syntax

FUNCTION NAME(a,b,…) JAVASCRIPT <<<
  JavaScript …
>>>
FUNCTION NAME(a,b,…) JAVASCRIPT <<< JavaScript … >>>

Part	Meaning
NAME	The function's name, as for any FUNCTION.
a, b	Its parameters: JavaScript names, used as written (`x`, `width`, `c`).
`<<<` … `>>>`	The code: from the line after `<<<` to a line that is only `>>>`, or on one line between them. It is kept exactly as written.

The code is the body of a JavaScript function of the parameters (strict mode). What it returns is the function's value; it can return nothing if it only makes geometry.

What the code is given

The drawing API, shared with extensions: the drawing's variables and the points of the page worked on, and functions to make points and elements. In brief:

Values	Numbers, strings and `true`/`false` as they are; a position as `{x, y}`; a list as an array; a dictionary as a `Map`. Values returned come back the same way: an object with numbers `x` and `y` is a position, any other object a dictionary of its properties.
`vars.NAME`, `variable("NAME")`	A variable of the drawing: `vars.L` and `variable("L")` are `L`.
`getPoint(n)`	A point: `getPoint(4)` or `getPoint("P4")`, as `{x, y, id}`.
`evaluate("…")`	An expression of the drawing language: `evaluate("DISTANCE(P0,P2)")`.
`setVariable("NAME", value)`	Sets a variable, to a number or an expression.
`newPoint(…)`, `offset(p, dx, dy)`, `polar(p, angle, distance)`, `between(p, q, t)`	New points: at a position or defined by an expression; from another point. Sizes can be expressions (`"W/2"`).
`line`, `arc`, `circle`, `bezier`, `polyline`, `point`, `text`	Elements, from points or positions.
`layer(n)`	The layer the elements after it are made on.
`command("…")`	Any statement of the drawing language: `command("FILLET(@1,@2,5)")`.
`print(…)`, `console.log(…)`	Shows values, as PRINT does.

Positions can be given as {x: 10, y: 20} or [10, 20]; a point given as itself (getPoint(4), "P4") keeps what is made on it following it.

Examples

FUNCTION HYPOT(a, b) JAVASCRIPT <<< return Math.sqrt(a * a + b * b) >>>
DIAGONAL = HYPOT(L, W)

JavaScript functions example

FUNCTION STAR(c, n, r) JAVASCRIPT <<<
  for (let k = 0; k < 2 * n; k++) {
    const a = Math.PI / 2 + k * Math.PI / n, b = a + Math.PI / n;
    const r1 = k % 2 ? r / 2 : r, r2 = k % 2 ? r : r / 2;
    line({ x: c.x + r1 * Math.cos(a), y: c.y + r1 * Math.sin(a) },
         { x: c.x + r2 * Math.cos(b), y: c.y + r2 * Math.sin(b) });
  }
>>>
CALL STAR(P2, 5, W / 4)

A five-pointed star at the box's corner P2: change W or move P2 and it is made again.

FUNCTION HOLES(widths) JAVASCRIPT <<<
  let x = 20;
  for (const w of widths) {
    circle([x + w / 2, 50], w / 2);
    x += w + 10;
  }
  return x;
>>>
WIDTHS = {10, 20, 40}
CALL HOLES(WIDTHS)

A list given to JavaScript as an array: a hole for each width.

Notes

A JavaScript function sees the drawing's variables and points, as they are when it is called. The points and elements it makes are its own (as a block's are): drawn and exported with the drawing, but not its elements to pick or snap to one by one.
It is called like any function: in an expression for its value (HYPOT(3,4)), or with CALL for its geometry, from the drawing, a block or another function. Functions of the drawing language can call it, and it can call them through evaluate.
Sandboxed: the code can't reach files, the network or the computer, only what is listed above. A call stops if it runs more than a million statements or ten seconds, calls itself more than 200 deep, or uses too much memory.
Repeatable: a drawing must come out the same each time it is worked out, so Math.random() gives the same numbers every time and there is no Date.
Code that can't be read is refused when the function is defined, with the reason. Something that goes wrong when it runs is shown with the line of the FUNCTION it happened on.

More commands