Index of rules#
Every rule of the spec, in order, with its label and its first sentence. Each fact is stated in exactly one rule, so two lines here that say the same thing are a duplicate to remove.
Rule 2.1
compile-stepsThe compiler turns a source into a .mtpc in six steps, in this order:.Rule 2.2
prove-bodies-onceThe prove step proves each body once: the body of a function with each parameter ranging over every value of its declared type, the body of a foreach with its variable ranging over every value of its range, and the body of a motif or a choreo with each parameter ranging over every value of its declared type and constraints.Rule 2.3
step-rejects-or-passesThe parse, rewrite and prove steps each either reject the source or pass their output to the next step.Rule 2.4
prover-finds-rangesTo prove a range or a constraint, the prover works out ranges (ranges, range-rules).Rule 2.5
compiler-input-outputThe compiler is given one source file.Rule 2.6
compiler-decides-earlyEverything that can be decided when compiling is decided when compiling, even when that makes compiling slower.Rule 2.7
compiler-same-bytesThe compiler is deterministic: the same source and the same imported files always give the same bytes (compiled-format, "Same source, same bytes").Rule 2.8
compiler-reads-filesThe compiler reads only the source file and the files that it imports, directly or through other imports.Rule 2.9
compiler-never-acts-while-drawingThe compiler never does what happens only while drawing (binding-time).Rule 2.10
runtime-loads-mtpcThe runtime loads each .mtpc given by the src attribute of an <mtp-model> element, once, from a file that it fetches or from a block in the page (page-interface).Rule 2.11
no-errors-after-loadingOnce a .mtpc has loaded, nothing that a reader does and nothing that the runtime computes makes a component or the page fail or show an error.Rule 2.12
runtime-builds-live-modelWhen a .mtpc loads, the runtime builds its live model, once, before any component draws: it turns every expression into a function, once, and gives every free variable and attribute its starting value, reading each free start once (compiled-format, "Free and bound values").Rule 2.13
runtime-serves-componentsThe runtime defines one page element for each kind of view and control, and serves each element that the page places: in each element, it draws the view or control of the element's model that the element's name attribute gives.Rule 2.14
runtime-adds-no-objectsWhat a world model holds is decided by the illustrator alone: the objects of a live model are those that the source declares, and the runtime never adds an object to a live model or removes one.Rule 2.15
runtime-no-type-work-while-drawingWhile drawing, the runtime never checks whether a value has its type, and never converts a value from one type to another.Rule 2.16
any-compiler-any-runtimeEvery conforming compiler works with every conforming runtime.Rule 2.17
mtpc-only-boundaryThe .mtpc is the only thing that passes from the compiler to the runtime.Rule 2.18
corrupt-mtpcA .mtpc that matches the schema of its version and breaks a rule of this spec is corrupt.Rule 2.19
schema-strengthThe schema of each version of this spec holds every rule of compiled-format that a JSON schema can express, so that as few corrupt files as possible match it.Rule 2.20
spec-versionThe versions of this spec are numbered 1, 2, 3 and so on.Rule 2.21
what-is-normativeThese are normative, and every conforming implementation gives the same: which sources are accepted and which are rejected, the meaning of the .mtpc, and what the runtime does.Rule 2.22
conformanceAn implementation of the compiler conforms to this spec when, for every source and the files that it imports, it rejects the source if and only if this spec rejects it, and otherwise writes a .mtpc that has the meaning that compiled-format defines for the world model of the source.Rule 3.1
grammar-in-contextAt each place in a source, the parser reads only the text that the grammar allows at that place. Where several definitions in capitals could match there, the parser reads the one of the highest priority, and among those of the same priority, the one that matches the longest text.Rule 3.2
source-textA source is a sequence of Unicode characters.Rule 3.3
expression-positionsEach expression that the parser produces has a position: the line and the column of its first character, counting from 1.Rule 3.4
whitespace-and-commentsWhitespace is the three characters space (U+0020), tab (U+0009) and newline (line feed, U+000A).Rule 3.5
word-endsA word is a name, a number, an operator, a bool literal or none.Rule 3.6
no-name-part-after-formThe ) that closes a form is never followed directly by.Rule 3.7
name-charactersEach name part starts with a letter, one of the ASCII letters a to z and A to Z.Rule 3.8
name-underscoreAn underscore may be written only at the very end of the head of a form, right after its last name part: (circle_ (r 1)), (marks.grid_ …), (line|none_ …) and (none_ a).Rule 3.9
literal-wordsThe word true or false is a bool literal.Rule 3.10
keywordsA keyword is one of the words of keywords-table, and no other word.Rule 3.11
reserved-charactersOutside a string literal, {, } and " are errors, and so is a $ or a # that is not followed by '.Rule 3.12
number-literalsA digit is one of the ASCII digits 0 to 9.Rule 3.13
string-literalsA string literal is written in single quotes.Rule 3.14
tex-stringsA TeX string is written tex'…'.Rule 3.15
prefix-formsA name, @ and an item, written with nothing between them, are short for the form of that name and that item: H@X is (H X).Rule 3.16
interpolated-stringsAn interpolated string is written $'…', and a name string is written #'…'.Rule 4.1
formsA form is a (, then any number of expressions, its items, then a ).Rule 4.2
top-level-formsA source is any number of forms, with or without whitespace and comments between them.Rule 4.3
adjacent-itemsAmong the items of a form, a list literal or brackets, whitespace or a comment separates every two expressions, except where one of the two is a form.Rule 4.4
listsA list literal is written in square brackets, with its items separated as in adjacent-items: [], [0 1], [(f x) 'a'].Rule 4.5
name-bracketsA [ right after a name, with no whitespace between them, starts brackets after the name, which hold one expression or more: xs[0], xs[(+ k 1)], g['m1'], func[real real].Rule 4.6
broadened-typesA broadened type is two words or more joined by | with no whitespace between them, such as real|none.Rule 4.7
parser-expressionsThe parser produces the forms of a source as expressions, one for each form, in the order of the source.Rule 4.8
shorthand-formsThe parser produces each spelling on the left as the form on the right:.Rule 4.9
unnamed-headWhen the head of a form is a mtp:head, the parser removes the _ and puts none in as the second item: (circle_ (r 1)) is (circle none (r 1)), and (marks.grid_ …) is (marks.grid none …).Rule 4.10
form-templateEvery form is written (head name? positional… option… body…):.Rule 4.11
declared-namesThe name of a declaration is a bare name with one name part, none, a name string such as #'dot-{k}', or (name s).Rule 4.12
forms-with-no-nameThese forms have no name, so their second item is their first positional argument or their first optional argument: a listener, (move …), an (animation …) inside a control or a listener, (foreach …), (let …), (exists-when …), (import …), (term …), (like …), every optional argument, every call and every special form.Rule 4.13
optional-arguments-firstAn optional argument is a form, after the name and the positional arguments, whose head names one of the optional arguments that the form allows, such as (r 1) in (circle c (r 1)).Rule 4.14
optional-arguments-onceEach optional argument appears at most once in a form: a second one is an error, such as "'fill' is given twice".Rule 4.15
docstringsEvery declaration and every listener may have a docstring, doc@'text', and at most one.Rule 4.16
contextsEach body holds only the kinds of item that contexts-table gives for it, in the numbers that it gives, and the let and foreach forms that body-let-foreach allows.Rule 4.17
body-let-foreach(let ((name value) …) item…), (foreach i n item…), (foreach x list item…) and (foreach ((i n) (x list) …) item…), written in a body, are replaced by their items, with their names bound: once for let, and once for each value for foreach.Rule 4.18
formula-termsThe string of a formula declares the terms that it marks with \term{name}{…}.Rule 4.19
listeners-in-viewsA listener acts only on what happens in the view in whose body it is written.Rule 5.1
kinds-of-formEvery head belongs to exactly one of three kinds: sugar (sugar-form), library (library-form) or core.Rule 5.2
sugar-formA form is sugar if and only if it can be rewritten into core forms without computing any value and without using any type.Rule 5.3
library-formThe library is the built-in functions, which are implemented natively, and the files of the standard library, which are written in mtp.Rule 5.4
sugar-rewritesEach 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.Rule 5.5
drag-group-translateIn 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.Rule 5.6
foreach-count(foreach N X ITEMS…), where X is an int, means exactly (foreach N (range X) ITEMS…).Rule 5.7
foreach-bounded-lengthA 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 (prover-finds-ranges).Rule 5.8
dot-name-partIn (.Rule 5.9
animation-stepAn (animation ITEM…) written as an item of an animation's body is one step of that body.Rule 5.10
names-from-valuesA (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.Rule 6.1
declarations-and-bindingsA declaration is a form that creates a new thing that can be addressed: an object of the world model, a function, a type or a choreo.Rule 6.2
scopesA scope is a part of a file in which some names may be used.Rule 6.3
declare-before-useA use of a name refers only to a declaration or a binding that comes before the use, in every scope, with no exceptions, and a name that an import gives is used only after the import.Rule 6.4
name-lookupA use of a bare name, and the first name part of a name with several name parts, refers to what these steps find, in order:.Rule 6.5
one-declaration-per-scopeIn one scope, a name is declared or bound at most once, whatever the kinds of the declarations and the bindings.Rule 6.6
motif-names-hide-nothingA shape or a variable declared in the body of a motif never takes a name that the file declares at its top level, or that an (import F N…) gives, before the motif.Rule 6.7
declaration-namesNo declaration and no binding takes as its name a keyword (keywords) or a built-in type.Rule 7.1
import-formAn import is (import F) or (import F N1 N2…), with F and each Ni a name of one name part (name-characters).Rule 7.2
import-file-name(import F …) reads the file whose name is F followed by .mtp, looked for in the folders that compiler-reads-files gives, in that order.Rule 7.3
import-same-fileTwo imports read the same file when the two paths name one file on disk, links followed.Rule 7.4
import-file-holdsA file to import holds at its top level only the forms that contexts-table gives for the top level of a file to import.Rule 7.5
import-proves-whole-fileThe compiler proves every declaration of an imported file, whether the source uses it or not.Rule 7.6
import-filesAn imported file has a file scope of its own: its forms use only the names that it declares, binds and imports, and never a name of a file that imports it.Rule 7.7
import-declares-namesAn (import …) gives its names at its place in the file.Rule 8.1
values-and-objectsA value is what an expression gives: a number, a bool, a string, a color, a font, a point, a transform, a list, a function or none.Rule 8.2
the-typesThese are the types of mtp:.Rule 8.3
type-notationWhere a type is expected, the compiler reads these expressions as types, and every other expression there is a compile error:.Rule 8.4
fitsA type A fits a type B, and a value of type A is accepted where a value of type B is expected, exactly when one of these holds:.Rule 8.5
constraint-implicationA list of constraints implies a constraint C exactly in these cases:.Rule 8.6
constraintsA constraint is one of these forms.Rule 8.7
wrap-brings-inA number that enters a type that holds (wrap lo hi) is brought into its interval, and is never refused: it is replaced by lo + ((v - lo) mod (hi - lo)), with mod as stdlib defines it, exact for ints and ratios.Rule 8.8
writes-into-constraintsA write of a number into a variable or an attribute brings it into the constraints of the type of what it is written into: below a (>= c) it becomes c, above a (<= c) it becomes c, it is brought into a (wrap …) by wrap-brings-in, and when it breaks a (> c) or a (< c) it is not written.Rule 8.9
type-valuesA variable declared with no value, and a parameter that a call or an instance leaves out and that has no default, hold the value of their type:.Rule 8.10
literal-typesA literal has the type that is expected where it is written.Rule 8.11
conversionsOnly these change the type of a value where no form asks for it:.Rule 8.12
known-lengthsThe length of a list is known when its type holds (length n).Rule 8.13
none-only-where-allowedA type includes none when it is none or a broadened type.Rule 8.14
choice-typesA choice type is a refined type (string (one-of s…)).Rule 8.15
interfacesAn interface is a type that no object has as its own type.Rule 8.16
common-typeWhere the types of several values meet in one type, the type is the narrowest type that each of them fits, found this way for two types A and B:.Rule 8.17
motif-and-variant-types(motif M PARAMS …) declares the shape type M, whose objects are the instances of M. (variant V PARAMS S) declares the shape type V, whose base type is the type of the shape S (contexts-table): a built-in shape type, a motif type or a variant type.Rule 8.18
function-typesThe values of a function type are the functions declared with func, the functions written with fn, the colormaps, the built-in functions, and the functions that a library function gives, such as the ease that (step N) gives.Rule 8.19
parametersA parameter (T N DEFAULT?) of a function, a motif, a variant or a choreo has the type T, which is always written, with its constraints.Rule 8.20
function-result-typeThe result type of (func[R] N PARAMS BODY) is R.Rule 8.21
form-typesEach form has this type:.Rule 10.1
no-dependency-cyclesThe value of every bound variable and attribute is computed from the values that its expression reads (reaction).Rule 10.2
self-reference-todayThese rules hold for a use of a name inside the form that declares or binds it:.Rule 10.3
writable-targetsThe target of a writer and of a move is a name: a variable, an attribute of a shape, of an instance or of a term, or a member of a namespace or a formula, with a name string allowed in place of a name (shorthand-forms).Rule 10.4
written-valuesEach value that a write gives must fit the type of its target (fits), with the comparisons, the wraps and the choices of the constraints of that type left out, since the write brings the value into those (writes-into-constraints).Rule 10.5
writer-conditionsEach condition of a control or a listener (contexts-table) is a comparison (OP A B), OP one of <, <=, > and >=, in which one side is a read of a variable or an attribute that the writer writes, and the other side, the limit, does not depend on that variable or attribute, directly or through bound values.Rule 10.6
moves-at-onceTwo parts of one at-once that write the same value at times that overlap are a compile error. The values that a move writes are those of concurrency, section "Values".Rule 10.7
prover-provesThe prover proves exactly these, and nothing else:.Rule 10.8
rangesA range is a closed interval of reals, from a lower end to an upper end, each of them an int, a ratio or a binary64 number, the lower at most the upper.Rule 10.9
range-rulesThe range of each expression is the following.Rule 10.10
may-give-noneThe type of an operation that is not folded includes none when the ranges of its arguments, each taken on its own, hold an input at which it gives none by operations-that-give-none. For a part of a list or a group:.Rule 10.11
constraint-proofA value given where the expected type holds a constraint C meets C when one of these holds:.Rule 10.12
if-narrowingA branch of an if is proved only for the values for which it runs.Rule 12.1
evaluation-is-pureEvaluation of an expression gives a value and changes nothing: no variable, no attribute, no seed and no page element.Rule 12.2
arguments-before-callA call of a function, a built-in function or an operator evaluates every argument, then computes its result from their values.Rule 12.3
forms-evaluate-some-partsThese forms evaluate only some of their parts:.Rule 12.4
known-condition-takes-one-branchWhen the condition of an if is known in the prove step (prove-bodies-once), the prove step proves only the branch that is taken.Rule 12.5
operations-that-give-noneBesides an argument that is none (none-propagates), an operation gives none at these inputs, when folded and while drawing.Rule 12.6
none-at-known-inputsAn operation whose inputs are known in the prove step (prove-bodies-once), and are among the inputs at which it gives none (operations-that-give-none), is a compile error.Rule 12.7
none-propagatesAn operation that receives none as an argument gives none, at both times, with these exceptions:.Rule 12.8
none-never-a-conditionThe condition of an if and the value of the (active …) of a control or a listener never receive none.Rule 12.9
number-typesThere are four types of number (types).Rule 12.10
number-result-typesAn arithmetic operation gives the broadest type of its inputs, in the order int, ratio, real, complex, with these exceptions:.Rule 12.11
number-limitEvery number lies within the number limit, from -10¹⁵⁰ to 10¹⁵⁰, when folded and while drawing:.Rule 12.12
roundingWherever a number is rounded, other than a channel of a mixed color (mixed-color-channels), halves round away from zero, on the number's shortest exact decimal form, not on its binary value: 2.5 gives 3, -2.5 gives -3, 0.125 to two decimal places gives 0.13, and 2.675 to two decimal places gives 2.68.Rule 12.13
mixed-color-channelsEach channel of a mixed color is rounded to a whole number, and a channel that lies exactly halfway between two whole numbers is rounded up, when folded and while drawing, as CSS color-mix() does in browsers.Rule 12.14
seed-variableEvery random value is computed from a seed: a free variable of the built-in type rand-seed, which is any int.Rule 12.15
random-siteEach call of rand, rand-int, pick or shuffle has a site: a whole number.Rule 12.16
random-hashThe hash h of whole numbers x₁, …, xₙ is a whole number below 2³², computed with every product taken modulo 2³², every xor and shift on 32-bit numbers, and >> the shift that fills with zeros:.Rule 12.17
random-valuesWith s the value of the seed and p the site:.Rule 12.18
random-never-foldedA random value is known only while drawing (binding-time).Rule 12.19
equality-operands(= a b) and (!= a b) are a compile error unless the type of one side fits the type of the other, or one side is none.Rule 12.20
equality-by-contentValues compare by content, and mutable objects by identity.Rule 12.21
matchingTwo values match when they are equal, with one difference: two reals match when they differ by at most 10⁻¹² or by at most a millionth of the larger of their sizes.Rule 12.22
call-depth-limitThe depth of a call of a function, declared with func or written with fn, is 1 plus the number of such calls that are still being computed when it starts.Rule 12.23
same-value-at-both-timesAn expression gives the same value when it is folded as when it is computed while drawing, for the same values of what it reads.Rule 12.24
correctly-rounded-realsEach built-in function and operator rounds each binary64 number of its result (a real, a part of a complex number, a number of a point or of a list) from the exact value at its binary64 inputs to the nearest binary64 number, and of the two nearest, to the one whose last bit is 0 when the exact value lies exactly halfway between them.Rule 19.1
mtpc-imported-declarationsOf the declarations that a source imports (sugar-rewrites), a .mtpc holds only those that the source uses, directly or through other declarations.