5. Core and derived forms#

On this page, every head that the compiler accepts is sorted into three kinds: core form, sugar and library. Each sugar form is given as a rewrite into core forms. Each core form is given with the page of the spec where its meaning is defined.

This page specifies the language.

5.1. Kinds of form#

The head of a form is its first item (Rule 4.10): if in (if c a b), circle in (circle p (r 1)). An item of a form is also called by its head, so (r 1) is an r item.

Rule 5.1

Every head belongs to exactly one of three kinds: sugar (Rule 5.2), library (Rule 5.3) or core. A head that is neither sugar nor library is core.

Rule 5.2

A form is sugar if and only if it can be rewritten into core forms without computing any value and without using any type. Looking up a name is neither, since lexical scope is fixed by the text, so a rewrite may resolve a name and read the text of the declaration or the binding that the name refers to. A form that needs a value or a type to be rewritten is core.

Rule 5.3

The library is the built-in functions, which are implemented natively, and the files of the standard library, which are written in mtp. A call of a library function is a call, which is a core form. The library holds functions, constants and declarations, and no form of the language.

By Rule 6.7, a declared function may take the name of a library function: after (func + ((real a) (real b)) 7), (+ 1 2) is 7.

The compiler rewrites every sugar form in the rewrite step, which comes before the prove step (Rule 2.1), so the prover is given only core forms. The prove step proves the body of each foreach, motif and choreo once, before the expand step makes the copies, the instances and the uses (Rule 2.2). So a form whose rewrite would need the value of a foreach name or of a parameter of a motif or a choreo is core: the prover proves it once for every value that the name may take, and the expand step replaces it (Rule 5.10).

5.1.1. How a rewrite is written#

A rewrite is a pair of mtp fragments: the form as written, then the core forms that it means. In a fragment, a name in capitals stands for any text of the kind that the rule names: X for an expression, N for a name, T for a type, ARGS… for any number of items. Everything else is written as it is.

5.2. Rewrite rules#

The parser makes the rewrites of the lexical shorthands while it reads the source: a prefixed form H@X, a name string #'…', a part after a list literal, […][X] (Rule 4.8), and a head that ends with _ (Rule 4.9). Every other sugar form is in the table of the rule below.

Rule 5.4

Each form in the first column of this table is sugar, and means exactly the core forms in the second column, when the conditions in the third column hold. A sugar form whose conditions do not hold is a compile error. A rewrite may move text or copy it, and each name in the moved or copied text refers to what it referred to where it was written. A rewrite may give sugar forms, which are rewritten in turn, until no sugar form is left. A (like …) is rewritten before any other rewrite of the declaration that it copies.

Written

Means exactly

Conditions

N.A, N[X]

(. N A), (. N X). A chain is rewritten from left to right: p.pos.x is (. (. p pos) x), and g[0].r is (. (. g 0) r)

The name is written as an expression or as the target of a writer. A head and the name of a declaration are not rewritten

(when C X)

(if C X none)

Exactly two arguments

(cond (C1 V1) MORE… (else V)), (cond (else V))

(if C1 V1 (cond MORE… (else V))), V

(and A B MORE…), (and A)

(if A (and B MORE…) false), A

(or A B MORE…), (or A)

(if A true (or B MORE…)), A

(maybe T), in a type

T|none

the type colormap

the type func[real color]

a type N, declared (type N BASE C…)

the type (BASE C…)

(range X)

(range 0 X (gap 1))

X is not a (gap …) or (num …) item

(rand ARGS…), and the same with rand-int, pick or shuffle, with no (seed …)

(rand ARGS… (seed S))

S is the only seed that the file declares or imports (Rule 12.14)

(roll-dice S), in an animation’s body

(move S (to (next-seed S)) (duration 0))

S is a seed

(roll-dice), in an animation’s body

(roll-dice S)

S as for a random function

(import F)

the top-level declarations of F.mtp, after its own rewrites, each under the name F.N. Each F.N and each (. F N) in the source is a use of that name

F.mtp holds only what a file to import holds (Table 4.1). A file imported several times, directly or through other files, is put in once

(import F N1 N2…)

the same, and each Ni in the source is a use of F.Ni

Each Ni is a name that F.mtp gives (Rule 7.6)

(palette N (M C)…)

(namespace N (color M C)…)

Each item is (M C)

(K N (like M) ARGS…)

(K N ARGS… COPIED…). COPIED… is each item of the declaration of M, as written, after its own (like …) is rewritten, whose head ARGS… does not give. A positional string of a text is copied too. A (pos P) of M gives both x and y: when ARGS… gives exactly one of them, COPIED… holds the other, (x (. P 0)) or (y (. P 1))

M is a plain name. K is a shape head other than group, row and column, and M a shape of kind K. Or M is an instance of the motif or the variant K. Or K is font and M a font. Or K is term and M a term of the same formula, whose (term …) form comes before. Or the form is a move or a transition, and M is a transition declared at the top level

(pointer-events B), on a group, a row, a column or an instance

the same container, with (pointer-events B) moved into its (defaults …), which is added when it has none

Its (defaults …) gives no pointer-events

(defaults (A V)…), on a group, a row or a column

the same container without it, with each (A V) added to each member, at any depth, that takes A from a container (World model) and does not give A, the nearest container first. For a member that is an instance, (A V) is added to the instance’s own (defaults …)

Each A is one that a container gives its members (World model)

(defaults (A V)…), in a formula

the same formula without it, with each (A V) added to the (term T …) form of each term T of the formula that does not give A, and a form (term T (A V)…) added for each term that has none

The terms are those marked in the formula’s string

(dash L)

(dash L 0)

(pos [X Y])

(x X) (y Y)

(pos P)

(x (. P 0)) (y (. P 1))

P is not a list literal, and holds no call of rand, rand-int, pick or shuffle

(pos free@[X Y]), (pos free@P)

(x free@X) (y free@Y), (x free@(. P 0)) (y free@(. P 1))

As for (pos P)

(foreach ((N1 S1) (N2 S2) MORE…) ITEMS…), (foreach ((N S)) ITEMS…)

(foreach N1 S1 (foreach ((N2 S2) MORE…) ITEMS…)), (foreach N S ITEMS…)

The names are all different

(wait T), (wait), in an animation’s body

(move none (duration T)), (move none)

(animation OPT… A B MORE…), and the body of a choreo

(animation OPT… (in-order A B MORE…))

OPT… are the optional arguments of the animation, the (defaults …) and the (loop …)

(on-drag S M.pos ITEMS…), (on-drag S M.x ITEMS…), (on-drag S M.y ITEMS…)

(on-drag S (move M.pos (to pointer)) ITEMS…), (on-drag S (move M.x (to (. pointer 0))) ITEMS…), (on-drag S (move M.y (to (. pointer 1))) ITEMS…)

M names the shape or the term S

Of the declarations that an (import …) puts in, the .mtpc holds only those that the source uses (Rule 19.1).

A use of a choreo, (C A1 … Ak), is core, as a motif instance is. It is written where a move, an animation or a step of an animation’s body may be written, and k is at least the position of the last parameter with no default. In the expand step it becomes an (animation …) whose body is the body of the choreo, with each parameter replaced by the value of its argument, or by its default when the use gives no argument for it. So a use written as a step of an animation’s body is one step (Rule 5.9). The prover proves that each argument fits the type of its parameter. An argument may be any expression that may be written in the body in the places where its parameter is written, so (pulse (* 2 k)) is an error when the parameter is a duration, by Binding time and access, and is accepted when it is a to. A parameter stands for a value or a shape, never for a variable: a move in the body may move an attribute of a shape given as a parameter, such as who.opacity, and never the parameter itself.

Code differs

The compiler writes each use of a choreo out where it is written (compiler.py:1669-1729), proves the body again for each use, compiles a choreo whose parameters all have defaults once more without a use, and binds a parameter given a name to that name, so that a move of the parameter moves what it names (mtp-ydd4.7.56).

Since (like M) copies what M was written with in the source, a copy does not get the defaults of M’s container: (circle b (like a)) outside the group of a has only what a was written with. The copy follows what M’s items read: if the radius of M is (* 2 k), so is the radius of the copy. The defaults of an instance, and its pointer-events and its clip, are items of it, so (like M) copies them.

Since a copied random call is a site of its own (Rule 12.15), (pos (pick corners)) would draw x and y at two sites, so it is an error. A body let holds the point once: (let ((q (pick corners))) (circle c (pos q))) is (x (. q 0)) (y (. q 1)), which reads one value.

Code differs

The compiler makes these rewrites while it compiles each form, in the same functions that check it, and not in a step of their own (for example compiler.py:6471-6479 for when, 3074-3087 for wait, 3745-3764 for an animation item, 1669-1729 for a choreo use, 745-826 for imports, 5543-5576 for the defaults of a group). Beads mtp-08wd.5, mtp-08wd.6, mtp-08wd.7, mtp-08wd.8 and mtp-08wd.2 will make them in the rewrite step. Where the result differs today:

  • p.r is read as one name with name parts (parse.py:337-395), and each name part after the first as an attribute (compiler.py:5953-5960), so with a local r, xs.r is an error while (. xs r) is an item of xs (mtp-ydd4.7.5).

  • (like M) on an instance copies neither its pointer-events (compiler.py:4749, 4759-4762) nor its clip (mtp-ydd4.7.20).

  • (wait T) makes no transition object, while (move none (duration T)) does (compiler.py:3074-3087, 3184-3197). The two .mtpc files differ by that object (mtp-ydd4.7.21).

  • A palette has the type palette (compiler.py:1454, types.py:148-162), and the namespace that it means has the type namespace (mtp-ydd4.7.22).

  • (cond (else V)) is folded to the value of V and, since it is not a literal, marked const (compiler.py:5653-5657), so (real v (cond (else 3))) makes v a constant, while (real v 3) is a free variable that a writer may write (mtp-ydd4.7.46).

  • _through (compiler.py:7280-7290) rewrites only a name with several name parts, so after (import lib), lib.k is accepted, and (. lib k) is a compile error, “unknown name ‘lib’” (compiler.py:6056) (mtp-ydd4.7.47).

  • cond gives a list literal among its values the type of all its other values (compiler.py:6629-6641), while an if gives it the type of its other branch only (compiler.py:6494-6504) (mtp-08wd.2).

  • (pos P) compiles P once and splits it (compiler.py:5594-5611), so a random call in P is accepted, as one site (mtp-ydd4.7.25).

  • A choreo’s argument must be known when compiling, a name or a function (compiler.py:1702-1708), and is compiled once, then bound to the parameter (mtp-08wd.5).

So a bare name as the target of an on-drag is the position of the dragged shape, its x or its y, and any other bare name there is a compile error: (on-drag p k) must be written with a move, such as (on-drag p (move k (to (. pointer 0)))).

5.2.1. Dragging a group#

Rule 5.5

In an on-drag on a group, a row or a column, whether its fixed-size is true or not, a move whose target is the pos, the x or the y of that same container writes the container’s translate in place of the target: all of it for pos, its first number for x, and its second number for y. In that move, pointer is the translate of the container at the press plus the motion of the pointer since the press, in the frame of the container’s container.

By Rule 5.4, (on-drag g g.pos) is (on-drag g (move g.pos (to pointer))), so both spellings move the group by its translate, and the members keep their own positions.

Code differs

For a bare target, the runtime moves each member of a group that is not fixed-size by the motion of the pointer (web/src/drag.ts:113-117, drag.ts:155-162), and moves a fixed-size group by its translate (drag.ts:108-111, drag.ts:149-153). For a move, it writes the group’s x and y (drag.ts:138-147), and the compiler marks the translate as what the drag writes only for a fixed-size group (compiler.py:4009-4021). Bead mtp-ydd4.7.36 makes the code follow the rule.

5.2.2. foreach over a count or a list whose length is known only while drawing#

Rule 5.6

(foreach N X ITEMS…), where X is an int, means exactly (foreach N (range X) ITEMS…).

So the two spellings mean the same, at all times, and every rule about the second applies to the first. The first is core, and not sugar, only because an int and a list are told apart by the type of X (Rule 5.2).

Rule 5.7

A foreach over a list whose length is known only while drawing makes as many copies as the upper bound of that length that the prover proves (Rule 2.4). Copy k, counted from 0, exists only while k is below the length. When the prover proves no upper bound of the length below the number limit, the foreach is a compile error.

So with (int n 3 (>= 0) (<= 5)), which a slider writes, (foreach k n …) and (foreach k (range n) …) both make 5 copies, and copies 3 and 4 do not exist while n is 3.

Code differs

The compiler makes the bounded copies for a count (compiler.py:880-915), but rejects a list whose length is known only while drawing, (range n) included, with “the length of the list a foreach goes through must be known when compiling” (compiler.py:930-934). Bead mtp-ydd4.7.37 makes the compiler follow the rule.

5.2.3. The form .#

Rule 5.8

In (. X Y), where Y is a bare name with one name part, Y is the attribute or the member of X of that name, when X has one. Otherwise Y is an expression, and its value is a position or a key of X.

So p.r is the attribute r of a circle p, and with (let ((r 1)) xs.r), xs.r is item 1 of the list xs, as (. xs r) is. A member of a namespace, a palette, a formula or an instance is read by its name, even when another declaration or a binding has the same name. So with (color yellow '#ffd700') and (palette marks (yellow '#e6c200') (blue '#0072b2')) at the top level, marks.yellow is the member yellow of the palette, and not the color yellow.

Code differs

compiler.py:6540-6549 reads Y as an attribute only when has_attr (compiler.py:6175-6188) finds one, and has_attr finds no member of a namespace or a formula. So (. marks yellow) reads the color yellow as a key (mtp-ydd4.7.19).

5.2.4. An animation written as a step#

Rule 5.9

An (animation ITEM…) written as an item of an animation’s body is one step of that body. It plays its own body, a (loop …) included, as the name of an animation with the same body does (Time and animation). The (defaults …) around it do not apply inside it.

Code differs

An animation’s body does not accept the head animation (compiler.py:3097-3103). A use of a choreo is compiled to its steps in place (compiler.py:1714-1729) (mtp-ydd4.7.26).

5.2.5. Names built from values#

Rule 5.10

A (name S), and a (like (name S)), whose string S reads a name bound by a foreach or a parameter of a motif, are core. The prover proves, for every value that those names may take, that S gives the name of a declaration that comes before the form, and that every such declaration fits the form: for (name S), a type that fits all of them, and for (like …), the conditions of the row for (like M) in Rule 5.4. The expand step replaces each by the name that S gives in each copy, and then makes the (like …) copy of that row.

For example, take this foreach:

(foreach k 5
  (circle #'d-{k}' (pos [k 0]) (r (if (= k 0) 1 (/ #'d-{(- k 1)}'.r 2)))))

The prover proves its body once, for k from 0 to 4. In the branch of the if that is taken for k from 1 to 4, #'d-{(- k 1)}' names one of the copies d-0 to d-3, each a circle that comes before, since the prover narrows the range of k in that branch to 1 to 4 (Rule 10.12).

Code differs

The compiler makes each copy first, and then compiles (name S) and (like …) with the values of that copy (compiler.py:1161-1167, compiler.py:5329-5341) (mtp-08wd.1).

5.3. Forms that are core because a rewrite would need a value or a type#

By Rule 5.2, each form below is core. Its meaning is defined in the page named in the inventory.

  • (. X Y). Whether Y is an attribute depends on X (Rule 5.8).

  • foreach. The number of copies is a value, and (foreach i n …) is told apart from (foreach x xs …) by the type of the second item (Rule 5.6).

  • A motif instance. Its members are the motif’s body with the values of its parameters, made in the expand step.

  • A use of a choreo. Its moves are the choreo’s body with the values of its parameters, made in the expand step, as for a motif instance.

  • A variant instance. It is its base shape with the variant’s parameters as attributes, some attributes fixed, and the variant as its type. No core form of a shape carries these.

  • row and column. Each member is placed after the box of the member before. A rewrite into a group with a translate on each member would make each member read its own box, which depends on that translate.

  • colormap. Its positions must be known when compiling and must not decrease, and the steps of a discrete map are worked out from them, so its rewrite needs their values. Each call is compiled where it is written, so that the colors that it mixes stay the tokens that they read.

  • exists-when. Its condition may read what is declared between the shape and the exists-when, so it cannot be moved into the declaration of the shape (Rule 6.3).

  • let. A rewrite that put each value in place of each use would compute it once for each use, with a site of its own for each random call. A rewrite into a variable needs the value’s type.

  • (defaults …) on an instance. The members of an instance are made only in the expand step, so the prover proves that each value fits its attribute.

  • (defaults …) in an animation, an at-once or an in-order. A default ease does not apply to a move of a bool, a string or a choice, so writing the ease into each move needs the type of its target. A default duration also applies to the name of a transition in the body, which cannot be given a duration without making a new transition.

  • An in-order or an at-once of one item. It is one step, while its item may be several: a play of (animation (in-order (in-order a b))) has one step, and a play of (animation (in-order a b)) has two.

  • (map n f) with an int n. It means (map (range n) f), and is told apart from (map xs f) by the type of n. This is part of the typing of the library function map (Standard library).

  • The operators, not, abs, or?, none?, some?, somes and the box points. They are library functions, which the compiler reads itself (Rule 5.3), so a declared function may take their names (Rule 6.7).

5.4. Inventory of heads#

Each table lists the heads of one context. The column “Defined in” gives the page where a core form’s meaning is defined, the rule for a sugar form, or Standard library for the library.

5.4.1. Top-level forms#

Head

Kind

What it is

Defined in

import

sugar

(import F) or (import F N…): the declarations of another file

Rule 5.4

type

sugar

(type N BASE C…): a name for a refined type

Rule 5.4

interface

core

(interface N (T A C…)…): typed attributes that an object must have

Types

namespace

core

(namespace N MEMBER…): a mutable object that is not drawn

World model

palette

sugar

(palette N (M C)…): a namespace of colors

Rule 5.4

colormap

core

(colormap N [C…] ITEM…): a function from a real to a color

Evaluation

scene

core

(scene N ITEM…): the scene, of which a source holds at most one

World model

formula

core

(formula N ITEM…): typeset math with terms

World model

motif

core

(motif N PARAMS ITEM…): a template of shapes

World model

variant

core

(variant N PARAMS SHAPE): a new type of shape

Types

func, func[T]

core

(func N PARAMS BODY): a named function

Types, Evaluation

transition

core

(transition N TARGET ITEM…): a named trajectory

Time and animation

animation

core

(animation N ITEM…): a named animation

Time and animation

choreo

core

(choreo N PARAMS ITEM…): a template of moves, as a motif is a template of shapes

Time and animation

foreach

core

copies of its declarations, made in the expand step

Binding time and access

(T N …) for a type T

core

a variable, among them color and font tokens and rand-seed seeds

World model, State and reaction

components

core

views and controls (see “Components and their items”)

Page interface of views and controls

doc

core

a docstring, kept in the .mtpc

The .mtpc format

5.4.2. Variables and constraints#

Head

Kind

What it is

Defined in

(T N VALUE C…)

core

a variable of type T, free or bound

World model, State and reaction

list with no item type

core

a list whose item type is the type of its value

Types

font

core

(font N PART…): a font token, given by its parts

World model

family, style, weight, size

core

the parts of a font

World model

like in a font

sugar

copies the parts of another font

Rule 5.4

free

core

(free X): a free value that starts at the value of X, written only as the value of a variable or of an attribute

State and reaction, Binding time and access

>=, >, <=, < with one number

core

a bound

Types

length

core

the length of a list

Types

one-of

core

the choices of a string

Types

const

core

a value that no writer may write

Types

wrap

core

an interval that a number wraps into

Types

5.4.3. Type notation#

Notation

Kind

What it is

Defined in

int, ratio, real, complex, bool, string, color, font, point, transform, transition, animation, none, scene

core

the built-in types

Types

circle and the other shape names

core

the shape types

Types

shape, positioned, sequence, sequence[T]

core

the built-in interfaces

Types

list[T]

core

lists

Types

func[P… R]

core

function types

Types

T|none

core

a type that allows none

Types

(T C…)

core

a refined type

Types

(maybe T)

sugar

T|none

Rule 5.4

colormap

sugar

func[real color]

Rule 5.4

a name declared by type

sugar

the type that it names

Rule 5.4

a name declared by interface, motif or variant

core

that type

Types

rand-seed

core

the type of seeds, any int

Types, Evaluation

5.4.4. The scene, shapes and containers#

Head

Kind

What it is

Defined in

background

core

the scene’s background

World model

transform in the scene

core

how the scene’s coordinates are drawn

World model

circle, rect, ellipse, line, triangle, polyline, polygon, curve, arc, ring, text

core

the shapes

World model

group

core

a container

World model

row, column

core

a group that places its members one after another

World model

(M N …) for a motif M

core

an instance, an object of kind instance

World model

(V N …) for a variant V

core

an instance of a variant

World model

(H|none N …) for a shape head H

core

a shape that may not exist

World model

exists-when

core

(exists-when N C): when a shape exists

World model

let in a body

core

values worked out once, where the let is written

Binding time and access

foreach in a body

core

copies of declarations

Binding time and access

a variable in the scene

core

as at the top level

World model

5.4.5. Arguments of shapes and containers#

Head

Kind

What it is

Defined in

x, y, translate, transform, fill, stroke, stroke-width, opacity, fill-opacity, stroke-opacity, line-cap, line-join, drawn, pointer-events on a shape, r, width, height, rx, ry, from, to, a, b, c, points, controls, head-start, head-end, head-size, value, halign, valign, font

core

an attribute of the shape

World model

pos

sugar

x and y given as one point

Rule 5.4

dash with two arguments

core

the dash lengths and dash-offset

World model

dash with one argument

sugar

an offset of 0

Rule 5.4

like

sugar

copies another shape’s arguments

Rule 5.4

defaults on a group, a row or a column

sugar

what a container gives its members

Rule 5.4

clip

core

a shape that the members are drawn inside

World model

fixed-size

core

a group whose members are measured in screen pixels

World model

pointer-events on a group, a row or a column

sugar

a default for the members

Rule 5.4

gap, align

core

the spacing and alignment of a row or a column

World model

5.4.6. Motifs and variants#

Head

Kind

What it is

Defined in

a parameter (T N DEFAULT?)

core

a parameter of a motif, variant, function or choreo

Types

a shape, a bound variable, foreach, let or exists-when in a motif’s body

core

the members and values of each instance

World model

self

core

the instance being built, inside a motif’s body

Names and scope

a parameter given to an instance, (P X)

core

the parameter’s value

World model

x, y, translate, transform on an instance

core

the instance’s frame

World model

pos on an instance

sugar

as on a shape

Rule 5.4

clip on an instance

core

as on a group

World model

defaults on an instance

core

what the instance gives the members that its motif makes

World model

pointer-events on an instance

sugar

a default for the members

Rule 5.4

like on an instance or a variant instance

sugar

copies another instance’s items

Rule 5.4

The rules about a declaration that reads itself or its container, such as a default that reads its own group, are to be redesigned around self. Until then, the rules of today hold (Rule 10.2).

5.4.7. Namespaces, palettes and interfaces#

Head

Kind

What it is

Defined in

a variable in a namespace

core

a member, kept as N.M

World model

namespace, palette in a namespace

core, sugar

a namespace inside a namespace

World model, Rule 5.4

(M C) in a palette

sugar

(color M C)

Rule 5.4

(T A C…) in an interface

core

an attribute that an object must have

Types

5.4.8. Formulas and terms#

Head

Kind

What it is

Defined in

a TeX string

core

the formula’s LaTeX, which marks its terms

World model

term

core

(term T ITEM…): a term’s attributes

World model

fill, opacity, background, outline, outline-width, padding, rounding, tex in a term

core

a term’s attributes

World model

like in a term

sugar

copies another term’s form

Rule 5.4

defaults in a formula

sugar

attributes for every term

Rule 5.4

exists-when in a formula

core

when a term exists

World model

a variable in a formula

core

a member, kept as F.M

World model

5.4.9. Special forms and other expressions#

The heads of this table that are written as words, from . to type-of, are keywords (Rule 3.10).

Head

Kind

What it is

Defined in

a literal

core

a number, string, TeX string, interpolated string, bool, none or list literal

Lexical syntax, Types

a name

core

what the name refers to

Names and scope

a name with several name parts, N.A, N[X]

sugar

Rule 5.4

.

core

(. X Y): an attribute, member, item or key of X

Rule 5.8

name

core

(name S): the name whose text is S, known when compiling

Names and scope, Rule 5.10

if

core

(if C A B)

Evaluation

when

sugar

(when C X)

Rule 5.4

cond, else, and, or

sugar

Rule 5.4

let

core

(let ((N V)…) BODY)

Names and scope, Evaluation

fn

core

(fn PARAMS BODY): a function written in place

Types, Evaluation

as

core

(as T LITERAL): a literal given a type

Types

type-of

core

(type-of X): the type of X, as a string

Types

free

core

see “Variables and constraints”. In an expression it is a compile error

State and reaction

(F A…) for a declared function F

core

a call

Evaluation

(L A…) for a local function value L

core

a call of a function held by a parameter or a let name

Evaluation

5.4.10. Library functions#

These heads name functions of the library. Each call is a core call (Rule 5.3).

Heads

What they are

+, -, *, /, ^, mod, =, !=, <, <=, >, >=

the operators

not, abs, or?, none?, some?, somes

logic, absolute value and none

sqrt, sign, floor, ceil, exp

numbers

sin, cos, tan, sec, csc, cot, sind, cosd, tand, secd, cscd, cotd, asin, acos, atan, acot, asec, acsc, asind, acosd, atand, acotd, asecd, acscd, rad, turn, deg, to-rad, to-turn

angles

polar, to-polar, dist

points

rotate, translate, scale, transform

transforms

mix, lighten, darken, light-dark

colors

round, log, min, max, lerp, range

with a varying number or type of arguments

gap, num

the third argument of range

rand, rand-int, pick, shuffle, next-seed

random values and seeds

step, step-ease

eases: (step N) gives the ease of N equal jumps, and (step-ease P) the ease that is 0 before P and 1 from P on

seed

the last argument of a random function, (seed S)

map, where, sort, reverse, reduce, sum, count, any, all

collections

top, bottom, left, right, top-left, top-right, bottom-left, bottom-right

points on a shape’s box

pi, tau, euler

constants

the files colors, ease, fonts, marks, math, rand, types

the standard library, written in mtp

A call of step or step-ease gives an ease, which is a function, so the two are library functions and not keywords. By Rule 6.7, a declaration or a binding named step or step-ease takes the place of the library function from that declaration or binding on.

Code differs

The compiler reads (step N) and (step-ease P) only as the whole value of an ease (compiler.py:2918-2933), and not as calls. So after (real step 3), (ease (step 2)) still compiles as the ease of two jumps, and (step 2) in any other place is the error “unknown function”. Bead mtp-ydd4.7.40 makes the compiler follow the rule.

5.4.11. Transitions and animations#

Head

Kind

What it is

Defined in

move

core

(move TARGET ITEM…): a transition written in place

Time and animation

from, to, duration, path

core

the parts of a transition

Time and animation

ease

core

a function from 0 to 1, such as the value of (step N) or (step-ease P)

Time and animation

like in a transition or a move

sugar

Rule 5.4

animation written inline

core

(animation ITEM…), or (animation N) naming one, also as a step

Time and animation, Rule 5.9

an animation’s body of several items

sugar

one in-order

Rule 5.4

defaults in an animation, at-once or in-order

core

a duration and an ease for the moves inside

Time and animation

loop

core

(loop) or (loop N)

Time and animation

at-once, in-order

core

items together, or one after another

Time and animation

foreach in an animation’s body

core

puts its moves where it is written

Time and animation, Binding time and access

the name of an animation or a transition in a body

core

plays what it names

Time and animation

wait

sugar

Rule 5.4

roll-dice

sugar

Rule 5.4

a use of a choreo

core

the choreo’s moves, with the values of its arguments, as one step

Time and animation, Rule 5.9

5.4.12. Components and their items#

Head

Kind

What it is

Defined in

canvas, readout, display

core

the views

Page interface of views and controls, Lifecycle of a canvas

slider, button, play, stepper, toggle

core

the controls

Page interface of views and controls, State and reaction, Concurrency model

on-drag, on-click, on-release, on-dragstart, on-dragend, on-enter, on-leave, on-pointermove

core

listeners on a shape or a term, or for on-pointermove, on its canvas

State and reaction, Concurrency model

on-show, on-hide

core

listeners that play while a canvas starts or stops drawing a shape

State and reaction, Lifecycle of a canvas

on-view, on-ready, on-live, on-quiet

core

listeners on their own view

Lifecycle of a canvas

x, y, width, height, transform, pan, zoom on a canvas

core

the view box and how the reader may move it

Page interface of views and controls

toggle-duration, toggle-ease

core

how a canvas fades its items in and out

Time and animation, Page interface of views and controls

a name, a list literal or an expression in a canvas

core

what the canvas draws

Page interface of views and controls

font on a readout

core

the readout’s font

Page interface of views and controls

kind on a display

core

'block' or 'inline'

Page interface of views and controls

move, animation or a use of a choreo on a control or a listener

core

what the writer plays: one move, a collection of moves, or the moves of a choreo. A writer has at most one of them

State and reaction, Time and animation

the move of a slider

core

a move or the name of a transition, its first item

Page interface of views and controls, State and reaction

the target of toggle, on-pointermove

core

a name

State and reaction

the target of on-drag written as a move

core

(move TARGET (to X))

State and reaction, Rule 5.5

the target of on-drag written as a name

sugar

the move of the shape’s position

Rule 5.4

label

core

a control’s label

Page interface of views and controls, Accessibility

tex in a label

core

a label given as LaTeX

Page interface of views and controls

step on a slider

core

the number of positions of its knob

Page interface of views and controls

buttons, rest, labels on a play

core

its bars, its rest between steps, its step names

Page interface of views and controls, Time and animation

selected on a button

core

whether it is the current choice

Page interface of views and controls, Accessibility

active

core

whether the writer acts

State and reaction

priority

core

the writer’s priority

Concurrency model

stop-propagation

core

whether an event goes up the scene tree

State and reaction

in

core

the views that a control belongs to

Page interface of views and controls, Lifecycle of a canvas

a condition

core

a bool form that limits what a writer writes

State and reaction

doc on a component

core

its docstring

The .mtpc format

5.4.13. Heads that are errors#

These heads were once part of the language, or belong in another context. No body holds them, so each is a compile error (Rule 4.16). The compiler gives a message about what to write in their place. They are not forms of the language.

Head

Where

The message, in short

step

in an animation’s body

use (labels …) and (in-order …)

autoplay

on a control

use a canvas’s (on-ready …)

exclusive

on a writer

use (priority n)

when

on a control or a listener

use (active bool)

value

on a toggle

give the bool its start where it is declared

buttons

on a stepper

a stepper stops after each step

dash-offset

as an item

write (dash [4 2] 1)

move

in a canvas

a canvas takes no move

term

at the top level

a term is given inside its formula

5.5. Summary#

Head

Kind

Rewrite or defining page

H@X, #'…', […][X]

sugar, made by the parser

Rule 4.8

(H_ …)

sugar, made by the parser

Rule 4.9

N.A, N[X]

sugar

Rule 5.4

when, cond, and, or

sugar

Rule 5.4

(maybe T), colormap as a type, a name declared by type

sugar

Rule 5.4

(range X), a random function with no (seed …)

sugar

Rule 5.4

import, type, palette

sugar

Rule 5.4

like

sugar, or core with a (name …)

Rule 5.4, Rule 5.10

pointer-events on a container

sugar

Rule 5.4

defaults on a group, a row or a column, and in a formula

sugar

Rule 5.4

dash with one argument, pos

sugar

Rule 5.4

foreach with a list of names

sugar

Rule 5.4

a name as the target of on-drag

sugar

Rule 5.4

wait, roll-dice, an animation’s body of several items

sugar

Rule 5.4

interface, namespace

core

Types, World model

colormap

core

Evaluation

scene, background, transform in the scene

core

World model

formula, term and the attributes of a term

core

World model

motif, a motif instance, self, defaults on an instance

core

World model, Names and scope

variant, a variant instance

core

Types, World model

func, func[T], fn, calls

core

Types, Evaluation

transition, move and their parts

core

Time and animation

choreo and its uses

core

Time and animation, Rule 2.2

animation, at-once, in-order, loop, defaults in an animation

core

Time and animation, Rule 5.9

foreach

core

Rule 5.6, Rule 5.7, Binding time and access

let

core

Names and scope, Binding time and access

(T N …), a variable, font and its parts

core

World model, State and reaction

free

core

State and reaction, Binding time and access

the constraints >=, >, <=, <, length, one-of, const, wrap

core

Types

the type notation of “Type notation”, but maybe, colormap and the names declared by type

core

Types

the twelve shapes

core

World model

row, column, gap, align

core

World model

the attribute arguments of the shapes, dash with two arguments, clip, fixed-size

core

World model

exists-when

core

World model

.

core

Rule 5.8

name

core

Names and scope, Rule 5.10

if, as, type-of

core

Evaluation, Types

doc

core

The .mtpc format

the views, the controls and their items

core

Page interface of views and controls, State and reaction, Concurrency model

the fourteen listeners

core

State and reaction, Concurrency model, Lifecycle of a canvas

a move as the target of on-drag

core

State and reaction, Rule 5.5

a condition

core

State and reaction

the operators, not, abs, the none functions and the box points

library

Rule 5.3

the built-in functions and the collections, map over an int included, step and step-ease

library

Standard library

the constants and the standard library files

library

Standard library