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-steps The compiler turns a source into a .mtpc in six steps, in this order:.

  • Rule 2.2 prove-bodies-once The 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-passes The parse, rewrite and prove steps each either reject the source or pass their output to the next step.

  • Rule 2.4 prover-finds-ranges To prove a range or a constraint, the prover works out ranges (ranges, range-rules).

  • Rule 2.5 compiler-input-output The compiler is given one source file.

  • Rule 2.6 compiler-decides-early Everything that can be decided when compiling is decided when compiling, even when that makes compiling slower.

  • Rule 2.7 compiler-same-bytes The 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-files The compiler reads only the source file and the files that it imports, directly or through other imports.

  • Rule 2.9 compiler-never-acts-while-drawing The compiler never does what happens only while drawing (binding-time).

  • Rule 2.10 runtime-loads-mtpc The 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-loading Once 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-model When 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-components The 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-objects What 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-drawing While 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-runtime Every conforming compiler works with every conforming runtime.

  • Rule 2.17 mtpc-only-boundary The .mtpc is the only thing that passes from the compiler to the runtime.

  • Rule 2.18 corrupt-mtpc A .mtpc that matches the schema of its version and breaks a rule of this spec is corrupt.

  • Rule 2.19 schema-strength The 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-version The versions of this spec are numbered 1, 2, 3 and so on.

  • Rule 2.21 what-is-normative These 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 conformance An 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-context At 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-text A source is a sequence of Unicode characters.

  • Rule 3.3 expression-positions Each 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-comments Whitespace is the three characters space (U+0020), tab (U+0009) and newline (line feed, U+000A).

  • Rule 3.5 word-ends A word is a name, a number, an operator, a bool literal or none.

  • Rule 3.6 no-name-part-after-form The ) that closes a form is never followed directly by.

  • Rule 3.7 name-characters Each name part starts with a letter, one of the ASCII letters a to z and A to Z.

  • Rule 3.8 name-underscore An 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-words The word true or false is a bool literal.

  • Rule 3.10 keywords A keyword is one of the words of keywords-table, and no other word.

  • Rule 3.11 reserved-characters Outside a string literal, {, } and " are errors, and so is a $ or a # that is not followed by '.

  • Rule 3.12 number-literals A digit is one of the ASCII digits 0 to 9.

  • Rule 3.13 string-literals A string literal is written in single quotes.

  • Rule 3.14 tex-strings A TeX string is written tex'…'.

  • Rule 3.15 prefix-forms A 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-strings An interpolated string is written $'…', and a name string is written #'…'.

  • Rule 4.1 forms A form is a (, then any number of expressions, its items, then a ).

  • Rule 4.2 top-level-forms A source is any number of forms, with or without whitespace and comments between them.

  • Rule 4.3 adjacent-items Among 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 lists A list literal is written in square brackets, with its items separated as in adjacent-items: [], [0 1], [(f x) 'a'].

  • Rule 4.5 name-brackets A [ 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-types A broadened type is two words or more joined by | with no whitespace between them, such as real|none.

  • Rule 4.7 parser-expressions The parser produces the forms of a source as expressions, one for each form, in the order of the source.

  • Rule 4.8 shorthand-forms The parser produces each spelling on the left as the form on the right:.

  • Rule 4.9 unnamed-head When 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-template Every form is written (head name? positional… option… body…):.

  • Rule 4.11 declared-names The 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-name These 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-first An 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-once Each optional argument appears at most once in a form: a second one is an error, such as "'fill' is given twice".

  • Rule 4.15 docstrings Every declaration and every listener may have a docstring, doc@'text', and at most one.

  • Rule 4.16 contexts Each 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-terms The string of a formula declares the terms that it marks with \term{name}{…}.

  • Rule 4.19 listeners-in-views A listener acts only on what happens in the view in whose body it is written.

  • Rule 5.1 kinds-of-form Every head belongs to exactly one of three kinds: sugar (sugar-form), library (library-form) or core.

  • Rule 5.2 sugar-form A 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-form The 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-rewrites 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.

  • Rule 5.5 drag-group-translate 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.

  • 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-length 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 (prover-finds-ranges).

  • Rule 5.8 dot-name-part In (.

  • Rule 5.9 animation-step An (animation ITEM…) written as an item of an animation's body is one step of that body.

  • Rule 5.10 names-from-values 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.

  • Rule 6.1 declarations-and-bindings A 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 scopes A scope is a part of a file in which some names may be used.

  • Rule 6.3 declare-before-use A 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-lookup A 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-scope In 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-nothing A 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-names No declaration and no binding takes as its name a keyword (keywords) or a built-in type.

  • Rule 7.1 import-form An 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-file Two imports read the same file when the two paths name one file on disk, links followed.

  • Rule 7.4 import-file-holds A 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-file The compiler proves every declaration of an imported file, whether the source uses it or not.

  • Rule 7.6 import-files An 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-names An (import …) gives its names at its place in the file.

  • Rule 8.1 values-and-objects A 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-types These are the types of mtp:.

  • Rule 8.3 type-notation Where a type is expected, the compiler reads these expressions as types, and every other expression there is a compile error:.

  • Rule 8.4 fits A 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-implication A list of constraints implies a constraint C exactly in these cases:.

  • Rule 8.6 constraints A constraint is one of these forms.

  • Rule 8.7 wrap-brings-in A 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-constraints A 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-values A 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-types A literal has the type that is expected where it is written.

  • Rule 8.11 conversions Only these change the type of a value where no form asks for it:.

  • Rule 8.12 known-lengths The length of a list is known when its type holds (length n).

  • Rule 8.13 none-only-where-allowed A type includes none when it is none or a broadened type.

  • Rule 8.14 choice-types A choice type is a refined type (string (one-of s…)).

  • Rule 8.15 interfaces An interface is a type that no object has as its own type.

  • Rule 8.16 common-type Where 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-types The 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 parameters A 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-type The result type of (func[R] N PARAMS BODY) is R.

  • Rule 8.21 form-types Each form has this type:.

  • Rule 10.1 no-dependency-cycles The value of every bound variable and attribute is computed from the values that its expression reads (reaction).

  • Rule 10.2 self-reference-today These rules hold for a use of a name inside the form that declares or binds it:.

  • Rule 10.3 writable-targets The 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-values Each 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-conditions Each 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-once Two 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-proves The prover proves exactly these, and nothing else:.

  • Rule 10.8 ranges A 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-rules The range of each expression is the following.

  • Rule 10.10 may-give-none The 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-proof A value given where the expected type holds a constraint C meets C when one of these holds:.

  • Rule 10.12 if-narrowing A branch of an if is proved only for the values for which it runs.

  • Rule 12.1 evaluation-is-pure Evaluation of an expression gives a value and changes nothing: no variable, no attribute, no seed and no page element.

  • Rule 12.2 arguments-before-call A 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-parts These forms evaluate only some of their parts:.

  • Rule 12.4 known-condition-takes-one-branch When 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-none Besides 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-inputs An 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-propagates An operation that receives none as an argument gives none, at both times, with these exceptions:.

  • Rule 12.8 none-never-a-condition The condition of an if and the value of the (active …) of a control or a listener never receive none.

  • Rule 12.9 number-types There are four types of number (types).

  • Rule 12.10 number-result-types An arithmetic operation gives the broadest type of its inputs, in the order int, ratio, real, complex, with these exceptions:.

  • Rule 12.11 number-limit Every number lies within the number limit, from -10¹⁵⁰ to 10¹⁵⁰, when folded and while drawing:.

  • Rule 12.12 rounding Wherever 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-channels Each 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-variable Every 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-site Each call of rand, rand-int, pick or shuffle has a site: a whole number.

  • Rule 12.16 random-hash The 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-values With s the value of the seed and p the site:.

  • Rule 12.18 random-never-folded A 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-content Values compare by content, and mutable objects by identity.

  • Rule 12.21 matching Two 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-limit The 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-times An 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-reals Each 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-declarations Of the declarations that a source imports (sugar-rewrites), a .mtpc holds only those that the source uses, directly or through other declarations.