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 |
|---|---|---|
|
|
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 |
|
|
Exactly two arguments |
|
|
|
|
|
|
|
|
|
|
|
|
the type |
the type |
|
a type |
the type |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
the top-level declarations of |
|
|
the same, and each |
Each |
|
|
Each item is |
|
|
|
|
the same container, with |
Its |
|
the same container without it, with each |
Each |
|
the same formula without it, with each |
The terms are those marked in the formula’s string |
|
|
|
|
|
|
|
|
|
|
|
As for |
|
|
The names are all different |
|
|
|
|
|
|
|
|
|
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.ris 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 localr,xs.ris an error while(. xs r)is an item ofxs(mtp-ydd4.7.5).(like M)on an instance copies neither itspointer-events(compiler.py:4749, 4759-4762) nor itsclip(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 typenamespace(mtp-ydd4.7.22).(cond (else V))is folded to the value ofVand, since it is not a literal, marked const (compiler.py:5653-5657), so(real v (cond (else 3)))makesva 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.kis accepted, and(. lib k)is a compile error, “unknown name ‘lib’” (compiler.py:6056) (mtp-ydd4.7.47).condgives a list literal among its values the type of all its other values (compiler.py:6629-6641), while anifgives it the type of its other branch only (compiler.py:6494-6504) (mtp-08wd.2).(pos P)compilesPonce and splits it (compiler.py:5594-5611), so a random call inPis 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). WhetherYis an attribute depends onX(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.
rowandcolumn. Each member is placed after the box of the member before. A rewrite into a group with atranslateon 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 theexists-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, anat-onceor anin-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-orderor anat-onceof 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 intn. It means(map (range n) f), and is told apart from(map xs f)by the type ofn. This is part of the typing of the library functionmap(Standard library).The operators,
not,abs,or?,none?,some?,somesand 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 |
|---|---|---|---|
|
sugar |
|
|
|
sugar |
|
|
|
core |
|
|
|
core |
|
|
|
sugar |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
copies of its declarations, made in the expand step |
|
|
core |
a variable, among them |
|
core |
views and controls (see “Components and their items”) |
||
|
core |
a docstring, kept in the .mtpc |
5.4.2. Variables and constraints#
Head |
Kind |
What it is |
Defined in |
|---|---|---|---|
|
core |
a variable of type |
|
|
core |
a list whose item type is the type of its value |
|
|
core |
|
|
|
core |
the parts of a font |
|
|
sugar |
copies the parts of another font |
|
|
core |
|
|
|
core |
a bound |
|
|
core |
the length of a list |
|
|
core |
the choices of a string |
|
|
core |
a value that no writer may write |
|
|
core |
an interval that a number wraps into |
5.4.3. Type notation#
Notation |
Kind |
What it is |
Defined in |
|---|---|---|---|
|
core |
the built-in types |
|
|
core |
the shape types |
|
|
core |
the built-in interfaces |
|
|
core |
lists |
|
|
core |
function types |
|
|
core |
a type that allows |
|
|
core |
a refined type |
|
|
sugar |
|
|
|
sugar |
|
|
a name declared by |
sugar |
the type that it names |
|
a name declared by |
core |
that type |
|
|
core |
the type of seeds, any int |
5.4.4. The scene, shapes and containers#
Head |
Kind |
What it is |
Defined in |
|---|---|---|---|
|
core |
the scene’s background |
|
|
core |
how the scene’s coordinates are drawn |
|
|
core |
the shapes |
|
|
core |
a container |
|
|
core |
a group that places its members one after another |
|
|
core |
an instance, an object of kind |
|
|
core |
an instance of a variant |
|
|
core |
a shape that may not exist |
|
|
core |
|
|
|
core |
values worked out once, where the |
|
|
core |
copies of declarations |
|
a variable in the scene |
core |
as at the top level |
5.4.5. Arguments of shapes and containers#
Head |
Kind |
What it is |
Defined in |
|---|---|---|---|
|
core |
an attribute of the shape |
|
|
sugar |
|
|
|
core |
the dash lengths and |
|
|
sugar |
an offset of 0 |
|
|
sugar |
copies another shape’s arguments |
|
|
sugar |
what a container gives its members |
|
|
core |
a shape that the members are drawn inside |
|
|
core |
a group whose members are measured in screen pixels |
|
|
sugar |
a default for the members |
|
|
core |
the spacing and alignment of a row or a column |
5.4.6. Motifs and variants#
Head |
Kind |
What it is |
Defined in |
|---|---|---|---|
a parameter |
core |
a parameter of a motif, variant, function or choreo |
|
a shape, a bound variable, |
core |
the members and values of each instance |
|
|
core |
the instance being built, inside a motif’s body |
|
a parameter given to an instance, |
core |
the parameter’s value |
|
|
core |
the instance’s frame |
|
|
sugar |
as on a shape |
|
|
core |
as on a group |
|
|
core |
what the instance gives the members that its motif makes |
|
|
sugar |
a default for the members |
|
|
sugar |
copies another instance’s items |
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 |
|
|
core, sugar |
a namespace inside a namespace |
|
|
sugar |
|
|
|
core |
an attribute that an object must have |
5.4.8. Formulas and terms#
Head |
Kind |
What it is |
Defined in |
|---|---|---|---|
core |
the formula’s LaTeX, which marks its terms |
||
|
core |
|
|
|
core |
a term’s attributes |
|
|
sugar |
copies another term’s form |
|
|
sugar |
attributes for every term |
|
|
core |
when a term exists |
|
a variable in a formula |
core |
a member, kept as |
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, |
|
a name |
core |
what the name refers to |
|
a name with several name parts, |
sugar |
||
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
sugar |
|
|
|
sugar |
||
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
|
|
|
core |
see “Variables and constraints”. In an expression it is a compile error |
|
|
core |
a call |
|
|
core |
a call of a function held by a parameter or a |
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 |
|---|---|
|
the operators |
|
logic, absolute value and |
|
numbers |
|
angles |
|
points |
|
transforms |
|
colors |
|
with a varying number or type of arguments |
|
the third argument of |
|
random values and seeds |
|
eases: |
|
the last argument of a random function, |
|
collections |
|
points on a shape’s box |
|
constants |
the files |
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 |
|---|---|---|---|
|
core |
|
|
|
core |
the parts of a transition |
|
|
core |
a function from 0 to 1, such as the value of |
|
|
sugar |
||
|
core |
|
|
an animation’s body of several items |
sugar |
one |
|
|
core |
a duration and an ease for the moves inside |
|
|
core |
|
|
|
core |
items together, or one after another |
|
|
core |
puts its moves where it is written |
|
the name of an animation or a transition in a body |
core |
plays what it names |
|
|
sugar |
||
|
sugar |
||
a use of a choreo |
core |
the choreo’s moves, with the values of its arguments, as one step |
5.4.12. Components and their items#
Head |
Kind |
What it is |
Defined in |
|---|---|---|---|
|
core |
the views |
|
|
core |
the controls |
Page interface of views and controls, State and reaction, Concurrency model |
|
core |
listeners on a shape or a term, or for |
|
|
core |
listeners that play while a canvas starts or stops drawing a shape |
|
|
core |
listeners on their own view |
|
|
core |
the view box and how the reader may move it |
|
|
core |
how a canvas fades its items in and out |
|
a name, a list literal or an expression in a canvas |
core |
what the canvas draws |
|
|
core |
the readout’s font |
|
|
core |
|
|
|
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 |
|
the move of a slider |
core |
a |
|
the target of |
core |
a name |
|
the target of |
core |
|
|
the target of |
sugar |
the move of the shape’s position |
|
|
core |
a control’s label |
|
|
core |
a label given as LaTeX |
|
|
core |
the number of positions of its knob |
|
|
core |
its bars, its rest between steps, its step names |
|
|
core |
whether it is the current choice |
|
|
core |
whether the writer acts |
|
|
core |
the writer’s priority |
|
|
core |
whether an event goes up the scene tree |
|
|
core |
the views that a control belongs to |
|
a condition |
core |
a bool form that limits what a writer writes |
|
|
core |
its docstring |
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 |
|---|---|---|
|
in an animation’s body |
use |
|
on a control |
use a canvas’s |
|
on a writer |
use |
|
on a control or a listener |
use |
|
on a toggle |
give the bool its start where it is declared |
|
on a stepper |
a stepper stops after each step |
|
as an item |
write |
|
in a canvas |
a canvas takes no move |
|
at the top level |
a term is given inside its formula |
5.5. Summary#
Head |
Kind |
Rewrite or defining page |
|---|---|---|
|
sugar, made by the parser |
|
|
sugar, made by the parser |
|
|
sugar |
|
|
sugar |
|
|
sugar |
|
|
sugar |
|
|
sugar |
|
|
sugar, or core with a |
|
|
sugar |
|
|
sugar |
|
|
sugar |
|
|
sugar |
|
a name as the target of |
sugar |
|
|
sugar |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
the constraints |
core |
|
the type notation of “Type notation”, but |
core |
|
the twelve shapes |
core |
|
|
core |
|
the attribute arguments of the shapes, |
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
|
core |
|
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 |
core |
|
a condition |
core |
|
the operators, |
library |
|
the built-in functions and the collections, |
library |
|
the constants and the standard library files |
library |