BQN uses lexical scoping for variables, where scopes correspond roughly to blocks, or pairs of curly braces separated by semicolons. At the top level in a scope, new variables are visible only after they are defined, but in the scopes it contains, all variables defined in that scope are visible. This system is specified more precisely below.
A running BQN program manipulates variables during its execution, but it is important to distinguish these variables from the identifiers that refer to them. As defined in the tokenization rules, an identifier is a particular kind of token found in a program's source code. The lexical scoping rules in this page define which identifiers are considered the same; these identifiers will refer to the same variables when the program is run. While each variable has only one identifier, an identifier can refer to any number of variables because a new variable is created for that identifier each time its containing scope is instantiated (that is, each time the contents of the block are evaluated).
In this section the concept of an identifier's definition, a possibly different instance of that identifier, is specified. The definition determines when identifiers refer to the "same thing". In concrete terms, identifiers with the same definition all manipulate the same variable in a particular instance of the definition's containing scope.
A scope is a PROGRAM, I_CASE, A_CASE, or S_CASE node as defined by the BQN grammar. An identifier instance is an s, F, _m, or _c_ node. This does not include the special names that some block types allow for these terms, and the names used only for namespace field access as described below are explicitly excluded. Its containing scope is the "smallest" scope that contains itβthe scope that contains the identifier but not any other scopes containing the identifier. An identifier instance is defined when it is contained in the left hand side of an β assignment expression, that is, the leftmost component of one of the four grammatical rules with ASGN, provided that the ASGN node is "β" or "β", or in a scope header, that is, IMM_HEAD, ARG_HEAD, or the s term in S_CASE. Each identifier instance in a valid BQN program corresponds to exactly one such defined identifier, called its definition, and two instances are considered to refer to the same identifier if they have the same definition.
Two identifier instances have the same name if their tokens, as strings, match after removing all underscores _ and ignoring case (so that the letters a to z are equal to their uppercase equivalents A to Z for this comparison). However, instances with the same name are not necessarily the same identifier, as they must also have the same definition. A defined identifier is a potential definition of another identifier instance if the two have the same name, and either:
The definition for an identifier is chosen from the potential definitions based on their containing scopes: it is the one whose containing scope does not contain or match the containing scope of any other potential definition. If for any identifier there is no definition, then the program is not valid and results in an error. This can occur if the identifier has no potential definition, and also if two potential definitions appear in the same scope. In fact, under this rule it is never valid to make two definitions with the same name at the top level of a single scope, because both definitions would be potential definitions for the one that comes second in program order. Both definitions have the same containing scope, and any potential definition must contain or match this scope, so no potential definition can be selected.
The definition of program order for identifier tokens follows the order of BQN execution. It corresponds to the order of a particular traversal of the abstract syntax tree for a program. To find the relative ordering of two identifiers in a program, we consider the highest-depth node that they both belong to; in this node they must occur in different components, or that component would be a higher-depth node containing both of them. In most nodes, the program order goes from right to left: components further to the right come earlier in program order. The exceptions are PROGRAM, BODY, array, subject (for stranding), lhsList, lhsArray, lhsStr, and body structure (I_CASE, A_CASE, S_CASE, IMM_BLK, ARG_BLK, and blSub) nodes, in which program order goes in the opposite order, from left to right.
A subject label is the s term in a S_CASE node. As part of a header, it can serve as the definition for an identifier. However, it's defined to be a syntax error if another instance of this identifier appears.
Special names such as π© or π£ refer to variables, but have no definition and do not use scoping. Instead, they always refer to the immediately enclosing scope, and are defined automatically when the block is evaluated.
The six special names are π¨π©πππ€π£, and they may alternatively be spelled as πππ½πΎπ meaning π¨π©πππ€ respectively, and _π£ or _π£_ meaning π£. Special names may be modified with β© assignment but cannot appear as the target of other kinds of assignment. Two special names represent the same identifier if they are the same name and appear in the same body (more precisely, the set of BODY nodes that contains each is the same). The initial value these names have is defined by the evaluation rules; the grammar for blocks ensures that all special names used in a block will be defined (possibly as the special value Β· in the case of π¨). For this reason special names in header rules headW, headX, HeadF, HeadG, and LABEL are defined to have no effect when evaluated.
A name preceded by an atom "." term, and the NAME in LHS_ENTRY's lhs "β" NAME rule, indicates a namespace field access and is excluded from being an identifier instance. Also, the NAME in an LHS_ANY may indicate a field access in addition to its role as an identifier declaration. A field access operates on a namespace, giving the value of a variable with a particular name in that namespace. It doesn't use lexical scoping; in general the name must be stored somehow in order to perform a lookup when the namespace is available.
An identifier is exported if the ASGN node in its definition is "β", or if it appears anywhere in an EXPORT term. An identifier can only be exported in the scope where it is defined, and not in a containing scope. An EXPORT term that includes an identifier from such a scope causes an error.
A variable is an entity that permits two operations: it can be set to a particular value, and its value can be obtained, resulting in the last value it was set to. When either operation is performed it is referred to as accessing the variable.
When a body in a block is evaluated, it creates a namespace, which contains a variable for each definition (that is, defined identifier instance) the body contains. Whenever another blockβthe block itself, not its contentsβis evaluated during the execution of the block, it is linked to the currently-evaluating block, so that it will use the variables defined in this instance. By following these links repeatedly, an instance of a block is always linked to exactly one instance of each block that contains it. These links form a tree that is not necessarily related to the call stack of functions and modifiers. Using the links, the variable an identifier refers to is the one corresponding to that variable's definition in the linked instance of the containing scope for the definition.
The first access to a variable must be made by its definition (this also means it sets the variable). If a different instance of its identifier accesses it first, then an error results. This can happen because every scope contained in a particular scope sees all the definitions it uses, and such a scope could be called before the definition is run. Because of conditional execution, this property must be checked at run time in general; however, in cases where it is possible to statically determine that a program will always violate it, a BQN instance can give an error at compile time rather than run time.
A namespace defines a mapping from names to variables: if the given name is shared by an exported identifier in the body used to create that namespace, then that name maps to the variable corresponding to that identifier. The mapping is undefined for other names.