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 |
the body of a motif |
the motif’s body |
the parameters of the motif, |
a function |
the body |
the parameters |
|
each value after |
|
|
each source after the source of a name, and the items of the |
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 |
the move |
|
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:
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.
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.