6. Names and scope#

This page defines declarations and bindings, the part of a source in which each name may be used, and the declaration or binding to which each use of a name refers. Which characters a name holds is defined in Rule 3.7. Which expressions may read the scene, a formula or the page is defined in Binding time and access.

The rewrite step finds what each name refers to (Rule 2.1), so a source that breaks a rule of this page is rejected in the rewrite step. A name that is built from a value, (name S) with S reading a foreach name or a motif parameter, is resolved in the prove step instead (Rule 5.10). This page specifies the language.

6.1. Declarations and bindings#

Rule 6.1

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. The thing exists whether or not the source gives it a name, so (circle_ (r 1)) creates a circle that has no name. A binding gives a name to a value for a part of a source, and creates nothing: the names of a let and of a foreach, and the parameters of a function, a motif, a variant or a choreo, are bindings. The language makes two bindings of its own: the move of a drag binds pointer to the position of the pointer, and the body of a motif binds self to the instance being built. An import creates nothing either: it gives names to the things that the declarations of another file create (Imports).

So (real a 1), (circle c (r a)), (canvas v s), (func twice ((real x)) (* 2 x)) and (type unit real (>= 0) (<= 1)) are declarations, and so is a listener written in a canvas, such as (on-click c (move a (to 0) (duration 1))), which creates a listener with no name. In (let ((k 2)) (circle c (r k))), the circle c is a declaration and k is a binding.

6.2. Scopes#

Rule 6.2

A scope is a part of a file in which some names may be used. These are the scopes of mtp, and the names of each one:

Scope

Covers

Names

the file scope of a source or of a file to import

the whole file

every declaration at the top level, every name that an import gives (Rule 7.7), and every declaration in the scene and in its groups, rows and columns, at any depth

the body of a motif

the motif’s body

the parameters of the motif, self, and every shape and variable declared in the body, at any depth

a function (func N PARAMS BODY), a function (fn PARAMS BODY), a variant and a choreo

the body

the parameters

(let ((N1 V1) … (Nk Vk)) …), in an expression or in a body

each value after Vi, and the body or the items of the let

N1 to Nk, each Ni from V(i+1) on

foreach

each source after the source of a name, and the items of the foreach

the names that it binds, each from the next source on

a namespace or a palette

the items after each member

its members

a formula

the items of the formula

its variables, from the item after each, and its terms (Rule 4.18)

the move of an on-drag

the move

pointer

The scope of a body is inside the scope of the form around it, and every scope is inside the file scope. A group, a row, a column and the scene make no scope of their own. The names that are declared in the items of a let or of a foreach written in a body belong to the scope of that body: only the names that the let or the foreach binds belong to its own scope.

So the shapes of the scene, at any depth in its groups, are names of the file scope: a canvas, a listener and a readout name them. A copy that a foreach in the scene makes, such as #'dot-{k}', is a name of the file scope too, while k is used only inside the foreach. A parameter is used only in its body, and so a default of a parameter never reads another parameter. A member of a namespace, a palette or a formula is used by its bare name only inside that declaration, and elsewhere through it, as theme.ink, by Rule 5.8. In the same way, a member of a motif’s body is used from outside the body only through an instance, as d1.face.

Rule 6.3

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. The order is the order of the source after the rewrite step, with each foreach read as its copies, in the order of the copy index. A declaration, a binding or an import comes before a use when its form starts before the use. A use of a name inside the form that declares or binds it is allowed only as Rule 10.2 allows.

So two functions never call each other, since one of them would name the other before its declaration, and a function calls itself only by Rule 10.2. A canvas comes after the scene that it draws, a control comes after the views that its (in …) names, and an exists-when comes after the shape that it names. Copy k of a foreach may name copy k - 1, which comes before it, and never copy k + 1. By Rule 7.7, a name that an import gives is used only after the import.

Code differs

The compiler reads every import of a file before any other form (compiler.py:745, imports), so a name that an import gives may be used above the import. Bead mtp-ydd4.7.12.

6.3. What a name refers to#

Rule 6.4

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:

  1. Among the scopes around the use, from the innermost outwards to the file scope, the first that has the name among its names before the use (Rule 6.3). The use refers to the declaration or the binding of the name in that scope, or, for a name that an import gives, to the declaration in the imported file.

  2. A built-in function or a built-in constant of that name (Standard library).

When neither step finds the name, the source is a compile error.

So an inner name hides an outer name of the same text inside its scope: a parameter, a let name and a foreach name hide a name of the file scope, and a member of a namespace hides a top-level name inside the namespace. A declaration in the file scope, and a name that an import gives, hide a built-in function or constant from that declaration or import on (Rule 6.7). The name parts of a name after its first are not looked up in any scope: p.r is (. p r) (Rule 5.4), and what r is in it is defined in Rule 5.8. pointer is found only in the move of an on-drag, and is a compile error everywhere else, since no declaration and no binding takes it as its name.

In this example, the parameter x hides the variable x inside tenfold, so (tenfold 2) is 20 whatever the slider gives the variable:

; the parameter x hides the variable x inside tenfold
(real x 1 (>= 0) (<= 4))
(func tenfold ((real x)) (* 10 x))
(readout r $'x = {x:.1f}, (tenfold 2) = {(tenfold 2)}, (tenfold x) = {(tenfold x):.0f}')
(slider change (move x (from 0) (to 4)) (label 'x'))

Rule 6.5

In one scope, a name is declared or bound at most once, whatever the kinds of the declarations and the bindings. A variable, a shape, a function, a type, an interface, a motif, a variant, a choreo, a component and every other declaration share the names of their scope, and so do the bindings and the names that imports give. In the same way, the parameters of one form, the names of one let and the names of one foreach are all different. A second declaration, binding or import of a name in the same scope is a compile error.

So (type unit real (>= 0) (<= 1)) followed by (real unit 1) is a compile error, and so is a shape of the scene that has the name of a top-level function. Since the scene makes no scope, two shapes in two groups of the scene never have the same name. Two copies of a foreach declare different names, as #'dot-{k}' does.

Code differs

The compiler does not check that the names of one let are all different (compiler.py:6670, let, and compiler.py:959, body_let), so (let ((a 1) (a 2)) a) compiles, and is 2. Bead mtp-ydd4.7.41.

Rule 6.6

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. Such a declaration is a compile error.

So inside a motif’s body, a name declared at the top level always means the top-level declaration, unless a parameter, a let name or a foreach name hides it. A shape of the scene is not declared at the top level, so two motifs and the scene may each have a member c. A file imported whole gives only its own name (Rule 5.4), so a member ink does not hide house.ink. A motif in an imported file follows the rule against that file’s own top-level names.

6.4. Imports#

The file scope of an imported file, and the names that an import gives, are defined in Imports.

6.5. Names that no declaration or binding takes#

Rule 6.7

No declaration and no binding takes as its name a keyword (Rule 3.10) or a built-in type. This holds for every kind of declaration and binding: a variable, a shape, a function, a parameter, a name of a let or a foreach, a member of a namespace, a palette or a formula, a motif, a font, and every other. The built-in types are int, ratio, real, complex, bool, string, color, font, point, transform, transition, animation, scene, func, rand-seed, list, maybe, the shape types, and the interfaces shape, positioned, sequence and palette. A declaration or a binding may take the name of a built-in function, an operator included, or of a built-in constant (pi, tau and euler): from that declaration or binding on, the name refers to what it declares or binds (Rule 6.4).

So (real if 1) and (circle line …) are compile errors, and (func max ((real a) (real b)) a) and (real pi 3) are allowed. scene, transition, animation and func are both built-in types and keywords. true, false and none are values, never names (Rule 3.7). The built-in functions and constants are found only by the second step of Rule 6.4. The names of the standard library are not built-in: they are ordinary declarations of its files (Standard library), which a source brings in with import, and are found as any other imported name.

A variable may be named pointer or self. Inside the move of a drag, the binding pointer hides a declaration named pointer, and inside the body of a motif, the binding self hides a declaration named self (Rule 6.4). A member of a motif’s body named self is a compile error by Rule 6.5, since the body binds self.

Code differs

compiler.py:99 (RESERVED) forbids only the names scene, animation, transition, move, in-order, at-once, when, else, true, false, none, const, self, doc and free, so the name self is refused everywhere. The special forms of compiler.py:122 (SPECIAL) and the types are forbidden only as the name of a function (compiler.py:181, NOT_FUNCTION_NAMES), so a variable may be named if, and a function may not take the name of a constant. A name bound by let is checked against neither (_Compiler.let, compiler.py:6663). Bead mtp-ydd4.7.35 makes the compiler follow the rule.

Open question Q-scope-1 (parked)

Every rule about a declaration that reads itself or its container is to be redesigned around self, so that a declaration, a shape for example, refers to itself through self. Today self is bound only in the body of a motif (Rule 6.1). The redesign is parked, and the rules of today about a declaration that reads itself are in Rule 10.2.