diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-03-15 16:59:32 -0400 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-03-15 16:59:32 -0400 |
| commit | 4f618598f2f31bc466343e4d304f35b53a366da6 (patch) | |
| tree | f645f16425939a45ac82fcd0b3b477f9030bc7d9 | |
| parent | e858f41dffaee272ffcf4b2cb63a49ad25ebf7d7 (diff) | |
Finish namespace specification
| -rw-r--r-- | docs/spec/evaluate.html | 8 | ||||
| -rw-r--r-- | docs/spec/grammar.html | 18 | ||||
| -rw-r--r-- | docs/spec/scope.html | 7 | ||||
| -rw-r--r-- | docs/spec/token.html | 6 | ||||
| -rw-r--r-- | docs/spec/types.html | 6 | ||||
| -rw-r--r-- | spec/evaluate.md | 10 | ||||
| -rw-r--r-- | spec/grammar.md | 18 | ||||
| -rw-r--r-- | spec/scope.md | 8 | ||||
| -rw-r--r-- | spec/token.md | 6 | ||||
| -rw-r--r-- | spec/types.md | 7 |
10 files changed, 49 insertions, 45 deletions
diff --git a/docs/spec/evaluate.html b/docs/spec/evaluate.html index be087db0..d1ab7b80 100644 --- a/docs/spec/evaluate.html +++ b/docs/spec/evaluate.html @@ -9,17 +9,17 @@ <p>Here we assume that the referent of each identifier, or equivalently the connections between identifiers, have been identified according to the <a href="scope.html">scoping rules</a>.</p> <h3 id="programs-and-blocks">Programs and blocks</h3> <p>The result of parsing a valid BQN program is a <code><span class='Function'>PROGRAM</span></code>, and the program is run by evaluating this term.</p> -<p>A <code><span class='Function'>PROGRAM</span></code> or <code><span class='Function'>BODY</span></code> is a list of <code><span class='Function'>STMT</span></code>s (for <code><span class='Function'>BODY</span></code>, the last must be an <code><span class='Function'>EXPR</span></code>, a particular kind of <code><span class='Function'>STMT</span></code>), which are evaluated in program order. The statement <code><span class='Function'>EXPR</span></code> evaluates some APL code and possibly assigns the results, while <code><span class='Value'>nothing</span></code> evaluates any <code><span class='Value'>subject</span></code> or <code><span class='Function'>Derv</span></code> terms it contains but discards the results.</p> +<p>A <code><span class='Function'>PROGRAM</span></code> or <code><span class='Function'>BODY</span></code> is a list of <code><span class='Function'>STMT</span></code>s, which are evaluated in program order. A result is always required for <code><span class='Function'>BODY</span></code> nodes, and sometimes for <code><span class='Function'>PROGRAM</span></code> nodes (for example, when loaded with <code><span class='Function'>β’Import</span></code>). If any identifiers in the node's scope are exported, or any of its statements is an <code><span class='Function'>EXPORT</span></code>, then the result is the namespace created in order to evaluate the node. If a result is required but the namespace case doesn't apply, then the last <code><span class='Function'>STMT</span></code> node must be an <code><span class='Function'>EXPR</span></code> and its result is used. The statement <code><span class='Function'>EXPR</span></code> evaluates some APL code and possibly assigns the results, while <code><span class='Value'>nothing</span></code> evaluates any <code><span class='Value'>subject</span></code> or <code><span class='Function'>Derv</span></code> terms it contains but discards the results. An <code><span class='Function'>EXPORT</span></code> statement performs no action.</p> <p>A block consists of several <code><span class='Function'>BODY</span></code> terms, some of which may have an accompanying header describing accepted inputs and how they are processed. An immediate block <code><span class='Value'>brImm</span></code> can only have one <code><span class='Function'>BODY</span></code>, and is evaluated by evaluating the code in it. Other types of blocks do not evaluate any <code><span class='Function'>BODY</span></code> immediately, but instead return a function or modifier that obtains its result by evaluating a particular <code><span class='Function'>BODY</span></code>. The <code><span class='Function'>BODY</span></code> is identified and evaluated once the block has received enough inputs (operands or arguments), which for modifiers can take one or two calls: if two calls are required, then on the first call the operands are simply stored and no code is evaluated yet. Two calls are required if there is more than one <code><span class='Function'>BODY</span></code> term, if the <code><span class='Function'>BODY</span></code> contains the special names <code><span class='Value'>π¨π©π€</span><span class='Function'>πππ</span></code>, or if its header specifies arguments (the header-body combination is a <code><span class='Modifier'>_mCase</span></code> or <code><span class='Modifier2'>_cCase_</span></code>). Otherwise only one is required.</p> <p>To evaluate a block when enough inputs have been received, first the correct case must be identified. To do this, first each special case (<code><span class='Function'>FCase</span></code>, <code><span class='Modifier'>_mCase</span></code>, or <code><span class='Modifier2'>_cCase_</span></code>) is checked in order to see if its arguments are strucurally compatible with the given arguments. That is, is <code><span class='Value'>headW</span></code> is a <code><span class='Value'>subject</span></code>, there must be a left argument matching that structure, and if <code><span class='Value'>headX</span></code> is a <code><span class='Value'>subject</span></code>, the right argument must match that structure. This means that <code><span class='Value'>π¨</span></code> not only matches any left argument but also no argument. The test for compatibility is the same as for multiple assignment described below, except that the header may contain constants, which must match the corresponding part of the given argument.If no special case matches, then an appropriate general case (<code><span class='Function'>FMain</span></code>, <code><span class='Modifier'>_mMain</span></code>, or <code><span class='Modifier2'>_cMain_</span></code>) is used: if there are two, the first is used with no left argument and the second with a left argument; if there are one, it is always used, and if there are none, an error results.</p> <p>The only remaining step before evaluating the <code><span class='Function'>BODY</span></code> is to bind the inputs and other names. Special names are always bound when applicable: <code><span class='Value'>π¨π©π€</span></code> if arguments are used, <code><span class='Value'>π¨</span></code> if there is a left argument, <code><span class='Value'>ππ</span></code> if operands are used, and <code><span class='Modifier'>_π£</span></code> and <code><span class='Modifier2'>_π£_</span></code> for modifiers and combinators, respectively. Any names in the header are also bound, allowing multiple assignment for arguments.</p> <p>If there is no left argument, but the <code><span class='Function'>BODY</span></code> contains <code><span class='Value'>π¨</span></code> at the top level, then it is conceptually re-parsed with <code><span class='Value'>π¨</span></code> replaced by <code><span class='Nothing'>Β·</span></code> to give a monadic version before application; this modifies the syntax tree by replacing some instances of <code><span class='Value'>arg</span></code> with <code><span class='Value'>nothing</span></code>. However, it also causes an error if, in a function that is called with no left argument, <code><span class='Value'>π¨</span></code> is used as an operand or list element, where <code><span class='Value'>nothing</span></code> is not allowed by the grammar. The same effect can also be achieved dynamically by treating <code><span class='Nothing'>Β·</span></code> as a value and checking for it during execution. If it is used as a left argument, then the function should instead be called with no left argument (and similarly in trains); it it is used as a right argument, then the function and its left argument are evaluated but rather than calling the function <code><span class='Nothing'>Β·</span></code> is "returned" immediately; and if it is used in another context then it causes an error.</p> <h3 id="assignment">Assignment</h3> -<p>An <em>assignment</em> is one of the four rules containing <code><span class='Function'>ASGN</span></code>, other than <code><span class='Function'>IMPORT</span></code>. It is evaluated by first evaluating the right-hand-side <code><span class='Value'>subExpr</span></code>, <code><span class='Function'>FuncExpr</span></code>, <code><span class='Modifier'>_m1Expr</span></code>, or <code><span class='Modifier2'>_m2Exp_</span></code> expression, and then storing the result in the left-hand-side identifier or identifiers. The result of the assignment expression is the result of its right-hand side. Except for subjects, only a lone identifier is allowed on the left-hand side and storage sets it equal to the result. For subjects, <em>multiple assignment</em> with a list left-hand side is also allowed. Multiple assignment is performed recursively by assigning right-hand-side values to the left-hand-side targets, with single-identifier (<code><span class='Value'>s</span></code>) assignment as the base case. When matching the right-hand side to a list left-hand side, the left hand side is treated as a list of <code><span class='Value'>lhs</span></code> targets. The evaluated right-hand side must be a list (rank-1 array) of the same length, and is matched to these targets element-wise.</p> +<p>An <em>assignment</em> is one of the four rules containing <code><span class='Function'>ASGN</span></code>. It is evaluated by first evaluating the right-hand-side <code><span class='Value'>subExpr</span></code>, <code><span class='Function'>FuncExpr</span></code>, <code><span class='Modifier'>_m1Expr</span></code>, or <code><span class='Modifier2'>_m2Exp_</span></code> expression, and then storing the result in the left-hand-side identifier or identifiers. The result of the assignment expression is the result of its right-hand side. Except for subjects, only a lone identifier is allowed on the left-hand side and storage sets it equal to the result. For subjects, <em>destructuring assignment</em> is performed when an <code><span class='Value'>lhs</span></code> is <code><span class='Value'>lhsList</span></code> or <code><span class='Value'>lhsStr</span></code>. Destructuring assignment is performed recursively by assigning right-hand-side values to the left-hand-side targets, with single-identifier assignment as the base case.</p> +<p>The right-hand-side value, here called <code><span class='Value'>v</span></code>, in destructuring assignment must be a list (rank 1 array) or namespace. If it's a list, then each <code><span class='Function'>LHS_ENTRY</span></code> node must be an <code><span class='Function'>LHS_ELT</span></code>. The left-hand side is treated as a list of <code><span class='Value'>lhs</span></code> targets, and matched to <code><span class='Value'>v</span></code> element-wise, with an error if the two lists differ in length. If <code><span class='Value'>v</span></code> is a namespace, then the left-hand side must be an <code><span class='Value'>lhsStr</span></code> where every <code><span class='Function'>LHS_ATOM</span></code> is an <code><span class='Function'>LHS_NAME</span></code>, or an <code><span class='Value'>lhsList</span></code> where every <code><span class='Function'>LHS_ENTRY</span></code> is an <code><span class='Function'>LHS_NAME</span></code> or <code><span class='Value'>lhs</span> <span class='String'>"β"</span> <span class='Function'>LHS_NAME</span></code>, so that it can be considered a list of <code><span class='Function'>LHS_NAME</span></code> nodes some of which are also associated with <code><span class='Value'>lhs</span></code> nodes. To perform the assignment, the value of each name is obtained from the namespace <code><span class='Value'>v</span></code>, giving an error if <code><span class='Value'>v</span></code> does not define that name. The value is assigned to the <code><span class='Value'>lhs</span></code> node if present (which may be a destructuring assignment or simple subject assignment), and otherwise assigned to the same <code><span class='Function'>LHS_NAME</span></code> node used to get it from <code><span class='Value'>v</span></code>.</p> <p><em>Modified assignment</em> is the subject assignment rule <code><span class='Value'>lhs</span> <span class='Function'>Derv</span> <span class='String'>"β©"</span> <span class='Value'>subExpr</span></code>. In this case, <code><span class='Value'>lhs</span></code> should be evaluated as if it were a <code><span class='Value'>subExpr</span></code> (the syntax is a subset of <code><span class='Value'>subExpr</span></code>), and the result of the function application <code><span class='Value'>lhs</span> <span class='Function'>Derv</span> <span class='Value'>subExpr</span></code> should be assigned to <code><span class='Value'>lhs</span></code>, and is also the result of the modified assignment expression.</p> -<p>The <code><span class='Function'>IMPORT</span></code> rule resembles a multiple assignment. However, in this case the values passed do not form a list but rather a module or namespace, which in this specification is not a value accessible to the programmer. To evaluate the <code><span class='Function'>IMPORT</span></code> the <code><span class='Value'>brNS</span></code> side is evaluated, then each inner variable mentioned in the <code><span class='Value'>nsLHS</span></code> term is extracted and assigned to the corresponding outer identifier. Typically the two will both share the <code><span class='Function'>LHS_NAME</span></code>, but if <code><span class='Gets'>β</span></code> is used in an <code><span class='Function'>NS_VAR</span></code> then the <code><span class='Value'>lhs</span></code> term refers to the outer identifier and <code><span class='Function'>LHS_NAME</span></code> to the inner one. Since <code><span class='Function'>IMPORT</span></code> is a statement and not an expression, it doesn't have a result value.</p> <h3 id="expressions">Expressions</h3> -<p>We now give rules for evaluating an <code><span class='Value'>atom</span></code>, <code><span class='Function'>Func</span></code>, <code><span class='Modifier'>_mod1</span></code> or <code><span class='Modifier2'>_mod2_</span></code> expression (the possible options for <code><span class='Function'>ANY</span></code>). A literal or primitive <code><span class='Value'>sl</span></code>, <code><span class='Function'>Fl</span></code>, <code><span class='Modifier'>_ml</span></code>, or <code><span class='Modifier2'>_cl_</span></code> has a fixed value defined by the specification (<a href="literal.html">literals</a> and <a href="primitive.html">built-ins</a>). An identifier <code><span class='Value'>s</span></code>, <code><span class='Function'>F</span></code>, <code><span class='Modifier'>_m</span></code>, or <code><span class='Modifier2'>_c_</span></code> is evaluated by returning its value; because of the scoping rules it must have one when evaluated. A parenthesized expression such as <code><span class='String'>"("</span> <span class='Modifier'>_modExpr</span> <span class='String'>")"</span></code> simply returns the result of the interior expression. A braced construct such as <code><span class='Function'>BraceFunc</span></code> is defined by the evaluation of the statements it contains after all parameters are accepted. Finally, a list <code><span class='String'>"β¨"</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>EXPR</span> <span class='Separator'>β</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>EXPR</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='String'>"β©"</span></code> or <code><span class='Function'>ANY</span> <span class='Paren'>(</span> <span class='String'>"βΏ"</span> <span class='Function'>ANY</span> <span class='Paren'>)</span><span class='Function'>+</span></code> consists grammatically of a list of expressions. To evaluate it, each expression is evaluated in source order and their results are placed as elements of a rank-1 array. The two forms have identical semantics but different punctuation.</p> +<p>We now give rules for evaluating an <code><span class='Value'>atom</span></code>, <code><span class='Function'>Func</span></code>, <code><span class='Modifier'>_mod1</span></code> or <code><span class='Modifier2'>_mod2_</span></code> expression (the possible options for <code><span class='Function'>ANY</span></code>). A literal or primitive <code><span class='Value'>sl</span></code>, <code><span class='Function'>Fl</span></code>, <code><span class='Modifier'>_ml</span></code>, or <code><span class='Modifier2'>_cl_</span></code> has a fixed value defined by the specification (<a href="literal.html">literals</a> and <a href="primitive.html">built-ins</a>). An identifier <code><span class='Value'>s</span></code>, <code><span class='Function'>F</span></code>, <code><span class='Modifier'>_m</span></code>, or <code><span class='Modifier2'>_c_</span></code>, if not preceded by <code><span class='Value'>atom</span> <span class='String'>"."</span></code>, must have an associated variable due to the scoping rules, and returns this variable's value, or causes an error if it has not yet been set. If it is preceded by <code><span class='Value'>atom</span> <span class='String'>"."</span></code>, then the <code><span class='Value'>atom</span></code> node is evaluated first; its value must be a namespace, and the result is the value of the identifier's name in the namespace, or an error if the name is undefined. A parenthesized expression such as <code><span class='String'>"("</span> <span class='Modifier'>_modExpr</span> <span class='String'>")"</span></code> simply returns the result of the interior expression. A braced construct such as <code><span class='Function'>BraceFunc</span></code> is defined by the evaluation of the statements it contains after all parameters are accepted. Finally, a list <code><span class='String'>"β¨"</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>EXPR</span> <span class='Separator'>β</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>EXPR</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='String'>"β©"</span></code> or <code><span class='Function'>ANY</span> <span class='Paren'>(</span> <span class='String'>"βΏ"</span> <span class='Function'>ANY</span> <span class='Paren'>)</span><span class='Function'>+</span></code> consists grammatically of a list of expressions. To evaluate it, each expression is evaluated in source order and their results are placed as elements of a rank-1 array. The two forms have identical semantics but different punctuation.</p> <p>Rules in the table below are function and modifier evaluation.</p> <table> <thead> diff --git a/docs/spec/grammar.html b/docs/spec/grammar.html index 876bcfa7..dca88643 100644 --- a/docs/spec/grammar.html +++ b/docs/spec/grammar.html @@ -16,10 +16,10 @@ </pre> <p>Here we define the "atomic" forms of functions and modifiers, which are either single tokens or enclosed in paired symbols. Stranded vectors with <code><span class='Ligature'>βΏ</span></code>, which binds more tightly than any form of execution, are also included.</p> <pre><span class='Function'>ANY</span> <span class='Function'>=</span> <span class='Value'>atom</span> <span class='Function'>|</span> <span class='Function'>Func</span> <span class='Function'>|</span> <span class='Modifier'>_mod1</span> <span class='Function'>|</span> <span class='Modifier2'>_mod2_</span> -<span class='Modifier2'>_mod2_</span> <span class='Function'>=</span> <span class='Modifier2'>_c_</span> <span class='Function'>|</span> <span class='Modifier2'>_cl_</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Modifier2'>_m1Expr_</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Modifier2'>_brMod2_</span> -<span class='Modifier'>_mod1</span> <span class='Function'>=</span> <span class='Modifier'>_m</span> <span class='Function'>|</span> <span class='Modifier'>_ml</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Modifier'>_m2Expr</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Modifier'>_brMod1</span> -<span class='Function'>Func</span> <span class='Function'>=</span> <span class='Function'>F</span> <span class='Function'>|</span> <span class='Function'>Fl</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Function'>FuncExpr</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Function'>BrFunc</span> -<span class='Value'>atom</span> <span class='Function'>=</span> <span class='Value'>s</span> <span class='Function'>|</span> <span class='Value'>sl</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Value'>subExpr</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Value'>brSub</span> <span class='Function'>|</span> <span class='Value'>list</span> +<span class='Modifier2'>_mod2_</span> <span class='Function'>=</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Modifier2'>_c_</span> <span class='Function'>|</span> <span class='Modifier2'>_cl_</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Modifier2'>_m1Expr_</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Modifier2'>_brMod2_</span> +<span class='Modifier'>_mod1</span> <span class='Function'>=</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Modifier'>_m</span> <span class='Function'>|</span> <span class='Modifier'>_ml</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Modifier'>_m2Expr</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Modifier'>_brMod1</span> +<span class='Function'>Func</span> <span class='Function'>=</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Function'>F</span> <span class='Function'>|</span> <span class='Function'>Fl</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Function'>FuncExpr</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Function'>BrFunc</span> +<span class='Value'>atom</span> <span class='Function'>=</span> <span class='Paren'>(</span> <span class='Value'>atom</span> <span class='String'>"."</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Value'>s</span> <span class='Function'>|</span> <span class='Value'>sl</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Value'>subExpr</span> <span class='String'>")"</span> <span class='Function'>|</span> <span class='Value'>brSub</span> <span class='Function'>|</span> <span class='Value'>list</span> <span class='Value'>list</span> <span class='Function'>=</span> <span class='String'>"β¨"</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>EXPR</span> <span class='Separator'>β</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>EXPR</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='String'>"β©"</span> <span class='Value'>subject</span> <span class='Function'>=</span> <span class='Value'>atom</span> <span class='Function'>|</span> <span class='Function'>ANY</span> <span class='Paren'>(</span> <span class='String'>"βΏ"</span> <span class='Function'>ANY</span> <span class='Paren'>)</span><span class='Function'>+</span> </pre> @@ -46,7 +46,7 @@ </span><span class='Function'>FuncExpr</span> <span class='Function'>=</span> <span class='Function'>Train</span> <span class='Function'>|</span> <span class='Function'>F</span> <span class='Function'>ASGN</span> <span class='Function'>FuncExpr</span> </pre> -<p>Subject expressions are complicated by the possibility of list assignment. We also define nothing-statements, which have very similar syntax to subject expressions but do not permit assignment.</p> +<p>Subject expressions are complicated by the possibility of list and namespace assignment, which share the nodes <code><span class='Value'>lhsList</span></code> and <code><span class='Value'>lhsStr</span></code> and cannot be completely distinguished until execution. We also define nothing-statements, which have very similar syntax to subject expressions but do not permit assignment.</p> <pre><span class='Value'>arg</span> <span class='Function'>=</span> <span class='Value'>subExpr</span> <span class='Function'>|</span> <span class='Paren'>(</span> <span class='Value'>subject</span> <span class='Function'>|</span> <span class='Value'>nothing</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Function'>Derv</span> <span class='Value'>arg</span> <span class='Value'>nothing</span> <span class='Function'>=</span> <span class='String'>"Β·"</span> @@ -55,12 +55,10 @@ <span class='Function'>LHS_ANY</span> <span class='Function'>=</span> <span class='Function'>LHS_NAME</span> <span class='Function'>|</span> <span class='Value'>lhsList</span> <span class='Function'>LHS_ATOM</span> <span class='Function'>=</span> <span class='Function'>LHS_ANY</span> <span class='Function'>|</span> <span class='String'>"("</span> <span class='Value'>lhsStr</span> <span class='String'>")"</span> <span class='Function'>LHS_ELT</span> <span class='Function'>=</span> <span class='Function'>LHS_ANY</span> <span class='Function'>|</span> <span class='Value'>lhsStr</span> +<span class='Function'>LHS_ENTRY=</span> <span class='Function'>LHS_ELT</span> <span class='Function'>|</span> <span class='Value'>lhs</span> <span class='String'>"β"</span> <span class='Function'>LHS_NAME</span> <span class='Value'>lhsStr</span> <span class='Function'>=</span> <span class='Function'>LHS_ATOM</span> <span class='Paren'>(</span> <span class='String'>"βΏ"</span> <span class='Function'>LHS_ATOM</span> <span class='Paren'>)</span><span class='Function'>+</span> -<span class='Value'>lhsList</span> <span class='Function'>=</span> <span class='String'>"β¨"</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>LHS_ELT</span> <span class='Separator'>β</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>LHS_ELT</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='String'>"β©"</span> -<span class='Function'>NS_VAR</span> <span class='Function'>=</span> <span class='Paren'>(</span> <span class='Value'>lhs</span> <span class='String'>"β"</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Function'>LHS_NAME</span> -<span class='Value'>lhsNs</span> <span class='Function'>=</span> <span class='Function'>LHS_NAME</span> <span class='Paren'>(</span> <span class='String'>"βΏ"</span> <span class='Function'>LHS_NAME</span> <span class='Paren'>)</span><span class='Function'>+</span> - <span class='Function'>|</span> <span class='String'>"β¨"</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>NS_VAR</span> <span class='Separator'>β</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>NS_VAR</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='String'>"β©"</span> -<span class='Value'>lhs</span> <span class='Function'>=</span> <span class='Value'>s</span> <span class='Function'>|</span> <span class='Value'>lhsList</span> <span class='Function'>|</span> <span class='Value'>lhsStr</span> <span class='Function'>|</span> <span class='Value'>lhsNs</span> +<span class='Value'>lhsList</span> <span class='Function'>=</span> <span class='String'>"β¨"</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>LHS_ENTRY</span> <span class='Separator'>β</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>LHS_ENTRY</span> <span class='Separator'>β</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='String'>"β©"</span> +<span class='Value'>lhs</span> <span class='Function'>=</span> <span class='Value'>s</span> <span class='Function'>|</span> <span class='Value'>lhsList</span> <span class='Function'>|</span> <span class='Value'>lhsStr</span> <span class='Value'>subExpr</span> <span class='Function'>=</span> <span class='Value'>arg</span> <span class='Function'>|</span> <span class='Value'>lhs</span> <span class='Function'>ASGN</span> <span class='Value'>subExpr</span> <span class='Function'>|</span> <span class='Value'>lhs</span> <span class='Function'>Derv</span> <span class='String'>"β©"</span> <span class='Value'>subExpr</span> <span class='Comment'># Modified assignment diff --git a/docs/spec/scope.html b/docs/spec/scope.html index d5280e31..8ed5bab2 100644 --- a/docs/spec/scope.html +++ b/docs/spec/scope.html @@ -22,9 +22,10 @@ <p>Special names such as <code><span class='Value'>π©</span></code> or <code><span class='Value'>π£</span></code> 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.</p> <p>The six special names are <code><span class='Value'>π¨π©πππ€π£</span></code>, and the tokens <code><span class='Function'>πππ½πΎπ</span></code>, <code><span class='Modifier'>_π£</span></code>, and <code><span class='Modifier2'>_π£_</span></code> are alternate spellings of these names as described in the <a href="token.html">tokenization rules</a>. Special names may be modified with <code><span class='Gets'>β©</span></code> 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. The initial value these names have is defined by the <a href="evaluate.html">evaluation rules</a>; the grammar for blocks ensures that all special names used in a block will be defined (possibly as the special value <code><span class='Nothing'>Β·</span></code> in the case of <code><span class='Value'>π¨</span></code>).</p> <h3 id="imports-and-exports">Imports and exports</h3> -<p>The names to be used in an <code><span class='Function'>IMPORT</span></code>, that is, <code><span class='Function'>LHS_NAME</span></code> terms in an <code><span class='Function'>NS_VAR</span></code> or <code><span class='Value'>nsLHS</span></code>, are variable references inside that <code><span class='Function'>IMPORT</span></code>'s <code><span class='Value'>brNS</span></code> term. If they appear without an accompanying <code><span class='Value'>lhs</span> <span class='String'>"β"</span></code> term (in <code><span class='Function'>NS_VAR</span></code>), then this is in addition to their role as identifiers within the actual enclosing scope, which works like any other assignment. These references behave as though they are at the end of the <code><span class='Value'>brNS</span></code> term, that is, they "see" all definitions in the block. However, they must refer to identifiers that are <em>exported</em> by that block; references to any other variable cause an error much like references that have no definition.</p> -<p>An identifier is exported if the <code><span class='Function'>ASGN</span></code> node in its definition is <code><span class='String'>"β"</span></code>, or if it appears anywhere in an <code><span class='Function'>EXPORT</span></code> term. An identifier can only be exported in the scope where it is defined, and not in a containing scope. An <code><span class='Function'>EXPORT</span></code> term that includes an identifier from such a scope causes an error.</p> +<p>Names that are preceded by an <code><span class='Value'>atom</span> <span class='String'>"."</span></code> term, or that appear as <code><span class='Function'>LHS_NAME</span></code> terms in an <code><span class='Function'>NS_VAR</span></code> or <code><span class='Value'>lhsNs</span></code>, are variable references in a namespace: in the first case, the result of the <code><span class='Value'>atom</span></code> node, and in the second, of the overall assignments <code><span class='Value'>subExpr</span></code> right hand side. These names do not follow lexical scoping; in general they must be stored in order to perform a name lookup when the namespace is available. Such a name in <code><span class='Value'>lhsNs</span></code>, or in <code><span class='Function'>NS_VAR</span></code> with no accompanying <code><span class='Value'>lhs</span> <span class='String'>"β"</span></code> term, additionally serves as an identifier within the actual enclosing scope, which works like any other assignment.</p> +<p>An identifier is <em>exported</em> if the <code><span class='Function'>ASGN</span></code> node in its definition is <code><span class='String'>"β"</span></code>, or if it appears anywhere in an <code><span class='Function'>EXPORT</span></code> term. An identifier can only be exported in the scope where it is defined, and not in a containing scope. An <code><span class='Function'>EXPORT</span></code> term that includes an identifier from such a scope causes an error.</p> <h2 id="variables">Variables</h2> <p>A <em>variable</em> is an entity that permits two operations: it can be <em>set</em> to a particular value, and its <em>value</em> can be obtained, resulting in the last value it was set to. When either operation is performed it is referred to as <em>accessing</em> the variable.</p> -<p>When a body in a block is evaluated, a variable is created 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.</p> +<p>When a body in a block is evaluated, it creates a <em>namespace</em>, 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.</p> <p>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.</p> +<p>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.</p> diff --git a/docs/spec/token.html b/docs/spec/token.html index 0374e0b8..7209f982 100644 --- a/docs/spec/token.html +++ b/docs/spec/token.html @@ -9,7 +9,7 @@ <p>BQN source code should be considered as a series of unicode code points, which we refer to as "characters". The separator between lines in a file is considered to be a single character, newline, even though some operating systems such as Windows typically represent it with a two-character CRLF sequence. Implementers should note that not all languages treat unicode code points as atomic, as exposing the UTF-8 or UTF-16 representation instead is common. For a language such as JavaScript that uses UTF-16, the double-struck characters <code><span class='Value'>π¨</span><span class='Function'>π</span><span class='Value'>π©</span><span class='Function'>π</span><span class='Value'>π</span><span class='Function'>π½</span><span class='Value'>π</span><span class='Function'>πΎ</span></code> are represented as two 16-bit surrogate characters, but BQN treats them as a single unit.</p> <p>A BQN <em>character literal</em> consists of a single character between single quotes, such as <code><span class='String'>'a'</span></code>, and a <em>string literal</em> consists of any number of characters between double quotes, such as <code><span class='String'>""</span></code> or <code><span class='String'>"abc"</span></code>. Character and string literals take precedence with comments over other tokenization rules, so that <code><span class='Comment'>#</span></code> between quotes does not start a comment and whitespace between quotes is not removed, but a quote within a comment does not start a character literal. Almost any character can be included directly in a character or string literal without escaping. The only exception is the double quote character <code><span class='String'>"</span></code>, which must be written twice to include it in a string, as otherwise it would end the string instead. Character literals require no escaping at all, as the length is fixed. In particular, literals for the double and single quote characters are written <code><span class='String'>'''</span></code> and <code><span class='String'>'"'</span></code>, while length-1 strings containing these characters are <code><span class='String'>"'"</span></code> and <code><span class='String'>""""</span></code>.</p> <p>A comment consists of the hash character <code><span class='Comment'>#</span></code> and any following text until (not including) the next newline character. The initial <code><span class='Comment'>#</span></code> must not be part of a string literal started earlier. Comments are ignored entirely and do not form tokens.</p> -<p>Identifiers and numeric literals share the same token formation rule. These tokens are formed from the <em>numeric characters</em> <code><span class='Number'>Β―βΟ.0123456789</span></code> and <em>alphabetic characters</em> <code><span class='Modifier'>_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ</span></code> and the oddball <code><span class='Value'>π£</span></code>. Any sequence of these characters adjacent to each other forms a single token, which is a <em>numeric literal</em> if it begins with a numeric character and an <em>identifier</em> if it begins with an alphabetic character. If a token begins with an underscore then its first non-underscore character must be alphabetic: for example, <code><span class='Modifier'>_99</span></code> is not a valid token. Numeric literals are also subject to <a href="literal.html">numeric literal rules</a>, which specify which numeric literals are valid and which numbers they represent. If the token contains <code><span class='Value'>π£</span></code> it must be either <code><span class='Value'>π£</span></code>, <code><span class='Modifier'>_π£</span></code>, or <code><span class='Modifier2'>_π£_</span></code> and is considered a special name (see below). As the value taken by this identifier can only be a modifier, the uppercase character <code><span class='Value'>β</span></code> is not allowed.</p> +<p>Identifiers and numeric literals share the same token formation rule. These tokens are formed from the <em>numeric characters</em> <code><span class='Number'>Β―βΟ0123456789</span></code> and <em>alphabetic characters</em> <code><span class='Modifier'>_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ</span></code> and the oddball <code><span class='Value'>π£</span></code>. Additionally, <code><span class='Value'>.</span></code> is considered a numeric character if it is followed immediately by a digit (<code><span class='Number'>0123456789</span></code>); otherwise it forms its own token. Any sequence of these characters adjacent to each other forms a single token, which is a <em>numeric literal</em> if it begins with a numeric character and an <em>identifier</em> if it begins with an alphabetic character. If a token begins with an underscore then its first non-underscore character must be alphabetic: for example, <code><span class='Modifier'>_99</span></code> is not a valid token. Numeric literals are also subject to <a href="literal.html">numeric literal rules</a>, which specify which numeric literals are valid and which numbers they represent. If the token contains <code><span class='Value'>π£</span></code> it must be either <code><span class='Value'>π£</span></code>, <code><span class='Modifier'>_π£</span></code>, or <code><span class='Modifier2'>_π£_</span></code> and is considered a special name (see below). As the value taken by this identifier can only be a modifier, the uppercase character <code><span class='Value'>β</span></code> is not allowed.</p> <p>Following this step, the whitespace characters space and tab are ignored, and do not form tokens. Only these whitespace characters, and the newline character, which does form a token, are allowed.</p> <p>Otherwise, a single character forms a token. Only the specified set of characters can be used; others result in an error. The classes of characters are given below.</p> <table> @@ -26,7 +26,7 @@ </tr> <tr> <td>Primitive Function</td> -<td><code><span class='Function'>+-ΓΓ·ββββ|Β¬β§β¨<>β =β€β₯β‘β’β£β’β₯βΎββββ«»β½β/ββββββββ·β</span></code></td> +<td><code><span class='Function'>+-ΓΓ·ββββ|Β¬β§β¨<>β =β€β₯β‘β’β£β’β₯βΎββββ«»β½β/ββββββββ·β!</span></code></td> </tr> <tr> <td>Primitive 1-Modifier</td> @@ -42,7 +42,7 @@ </tr> <tr> <td>Punctuation</td> -<td><code><span class='Gets'>βββ©β</span><span class='Paren'>()</span><span class='Brace'>{}</span><span class='Bracket'>β¨β©</span><span class='Ligature'>βΏ</span><span class='Separator'>β,</span></code> and newline</td> +<td><code><span class='Gets'>βββ©β</span><span class='Paren'>()</span><span class='Brace'>{}</span><span class='Bracket'>β¨β©</span><span class='Ligature'>βΏ</span><span class='Separator'>β,</span><span class='Value'>.</span></code> and newline</td> </tr> </tbody> </table> diff --git a/docs/spec/types.html b/docs/spec/types.html index 3e6f3696..74110a74 100644 --- a/docs/spec/types.html +++ b/docs/spec/types.html @@ -5,7 +5,7 @@ </head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">spec</a></div> <h1 id="specification-bqn-types">Specification: BQN types</h1> -<p>BQN programs manipulate data of six types:</p> +<p>BQN programs manipulate data of seven types:</p> <ul> <li>Character</li> <li>Number</li> @@ -13,13 +13,15 @@ <li>Function</li> <li>1-Modifier</li> <li>2-Modifier</li> +<li>Namespace</li> </ul> -<p>Of these, the first three are considered <em>data types</em> and the remaining three <em>operation types</em>. We first describe the operation types; the remainder of this page will be dedicated to the data types. A member of any operation type accepts some number of <em>inputs</em> and either returns a <em>result</em> or causes an error; inputs and the result are values of any type. When a function is given inputs (<em>called</em>), it may produce side effects before returning, such as manipulating variables and calling other functions within its scope, or performing I/O.</p> +<p>Of these, the first three are considered <em>data types</em> and the next three <em>operation types</em>. We first describe the operation types and the namespace; the remainder of this page will be dedicated to the data types. A member of any operation type accepts some number of <em>inputs</em> and either returns a <em>result</em> or causes an error; inputs and the result are values of any type. When a function is given inputs (<em>called</em>), it may produce side effects before returning, such as manipulating variables and calling other functions within its scope, or performing I/O.</p> <ul> <li>A <em>function</em> takes one (monadic call) or two (dyadic call) <em>arguments</em>.</li> <li>A <em>1-modifier</em> takes one <em>operand</em>.</li> <li>A <em>2-modifier</em> takes two <em>operands</em>.</li> </ul> +<p>A namespace holds the variables used to evaluate a block or program, as defined in the <a href="scope.html">scoping rules</a>. The observable aspects of a namespace are that it can be compared for equality with other namespaces and that it exposes variables associated with certain names, whose values can be queried or set.</p> <p>To begin the data types, a <em>character</em> is a <a href="https://en.wikipedia.org/wiki/Unicode">Unicode</a> code point, that is, its value is a non-negative integer within the ranges defined by Unicode (however, it is distinct from this number as a BQN value). Characters are ordered by this numeric value. BQN deals with code points as abstract entities and does not expose encodings such as UTF-8 or UTF-16.</p> <p>The precise type of a <em>number</em> may vary across BQN implementations or instances. A <em>real number</em> is a member of some supported subset of the <a href="https://en.wikipedia.org/wiki/Extended_real_number_line">extended real numbers</a>, that is, the real numbers and positive or negative infinity. Some system must be defined for rounding an arbitrary real number to a member of this subset, and the basic arithmetic operations add, subtract, multiply, divide, and natural exponent (base <em>e</em>) are defined by performing these operations on exact real values and rounding the result. The Power function (dyadic <code><span class='Function'>β</span></code>) is also used but need not be exactly rounded. A <em>complex number</em> is a value with two real number <em>components</em>, a <em>real part</em> and an <em>imaginary part</em>. A BQN implementation can either support real numbers only, or complex numbers.</p> <p>An <em>array</em> is a rectangular collection of data. It is defined by a <em>shape</em>, which is a list of non-negative integer lengths, and a <em>ravel</em>, which is a list of <em>elements</em> whose length (the array's <em>bound</em>) is the product of all lengths in the shape. Arrays are defined inductively: any value (of a value or function type) can be used as an element of an array, but it is not possible for an array to contain itself as an element, or an array that contains itself, and so on. Types other than array are called <em>atomic types</em>, and their members are called <em>atoms</em>.</p> diff --git a/spec/evaluate.md b/spec/evaluate.md index c5d99751..625192f4 100644 --- a/spec/evaluate.md +++ b/spec/evaluate.md @@ -10,7 +10,7 @@ Here we assume that the referent of each identifier, or equivalently the connect The result of parsing a valid BQN program is a `PROGRAM`, and the program is run by evaluating this term. -A `PROGRAM` or `BODY` is a list of `STMT`s (for `BODY`, the last must be an `EXPR`, a particular kind of `STMT`), which are evaluated in program order. The statement `EXPR` evaluates some APL code and possibly assigns the results, while `nothing` evaluates any `subject` or `Derv` terms it contains but discards the results. +A `PROGRAM` or `BODY` is a list of `STMT`s, which are evaluated in program order. A result is always required for `BODY` nodes, and sometimes for `PROGRAM` nodes (for example, when loaded with `β’Import`). If any identifiers in the node's scope are exported, or any of its statements is an `EXPORT`, then the result is the namespace created in order to evaluate the node. If a result is required but the namespace case doesn't apply, then the last `STMT` node must be an `EXPR` and its result is used. The statement `EXPR` evaluates some APL code and possibly assigns the results, while `nothing` evaluates any `subject` or `Derv` terms it contains but discards the results. An `EXPORT` statement performs no action. A block consists of several `BODY` terms, some of which may have an accompanying header describing accepted inputs and how they are processed. An immediate block `brImm` can only have one `BODY`, and is evaluated by evaluating the code in it. Other types of blocks do not evaluate any `BODY` immediately, but instead return a function or modifier that obtains its result by evaluating a particular `BODY`. The `BODY` is identified and evaluated once the block has received enough inputs (operands or arguments), which for modifiers can take one or two calls: if two calls are required, then on the first call the operands are simply stored and no code is evaluated yet. Two calls are required if there is more than one `BODY` term, if the `BODY` contains the special names `π¨π©π€πππ`, or if its header specifies arguments (the header-body combination is a `_mCase` or `_cCase_`). Otherwise only one is required. @@ -22,15 +22,15 @@ If there is no left argument, but the `BODY` contains `π¨` at the top level, t ### Assignment -An *assignment* is one of the four rules containing `ASGN`, other than `IMPORT`. It is evaluated by first evaluating the right-hand-side `subExpr`, `FuncExpr`, `_m1Expr`, or `_m2Exp_` expression, and then storing the result in the left-hand-side identifier or identifiers. The result of the assignment expression is the result of its right-hand side. Except for subjects, only a lone identifier is allowed on the left-hand side and storage sets it equal to the result. For subjects, *multiple assignment* with a list left-hand side is also allowed. Multiple assignment is performed recursively by assigning right-hand-side values to the left-hand-side targets, with single-identifier (`s`) assignment as the base case. When matching the right-hand side to a list left-hand side, the left hand side is treated as a list of `lhs` targets. The evaluated right-hand side must be a list (rank-1 array) of the same length, and is matched to these targets element-wise. +An *assignment* is one of the four rules containing `ASGN`. It is evaluated by first evaluating the right-hand-side `subExpr`, `FuncExpr`, `_m1Expr`, or `_m2Exp_` expression, and then storing the result in the left-hand-side identifier or identifiers. The result of the assignment expression is the result of its right-hand side. Except for subjects, only a lone identifier is allowed on the left-hand side and storage sets it equal to the result. For subjects, *destructuring assignment* is performed when an `lhs` is `lhsList` or `lhsStr`. Destructuring assignment is performed recursively by assigning right-hand-side values to the left-hand-side targets, with single-identifier assignment as the base case. -*Modified assignment* is the subject assignment rule `lhs Derv "β©" subExpr`. In this case, `lhs` should be evaluated as if it were a `subExpr` (the syntax is a subset of `subExpr`), and the result of the function application `lhs Derv subExpr` should be assigned to `lhs`, and is also the result of the modified assignment expression. +The right-hand-side value, here called `v`, in destructuring assignment must be a list (rank 1 array) or namespace. If it's a list, then each `LHS_ENTRY` node must be an `LHS_ELT`. The left-hand side is treated as a list of `lhs` targets, and matched to `v` element-wise, with an error if the two lists differ in length. If `v` is a namespace, then the left-hand side must be an `lhsStr` where every `LHS_ATOM` is an `LHS_NAME`, or an `lhsList` where every `LHS_ENTRY` is an `LHS_NAME` or `lhs "β" LHS_NAME`, so that it can be considered a list of `LHS_NAME` nodes some of which are also associated with `lhs` nodes. To perform the assignment, the value of each name is obtained from the namespace `v`, giving an error if `v` does not define that name. The value is assigned to the `lhs` node if present (which may be a destructuring assignment or simple subject assignment), and otherwise assigned to the same `LHS_NAME` node used to get it from `v`. -The `IMPORT` rule resembles a multiple assignment. However, in this case the values passed do not form a list but rather a module or namespace, which in this specification is not a value accessible to the programmer. To evaluate the `IMPORT` the `brNS` side is evaluated, then each inner variable mentioned in the `nsLHS` term is extracted and assigned to the corresponding outer identifier. Typically the two will both share the `LHS_NAME`, but if `β` is used in an `NS_VAR` then the `lhs` term refers to the outer identifier and `LHS_NAME` to the inner one. Since `IMPORT` is a statement and not an expression, it doesn't have a result value. +*Modified assignment* is the subject assignment rule `lhs Derv "β©" subExpr`. In this case, `lhs` should be evaluated as if it were a `subExpr` (the syntax is a subset of `subExpr`), and the result of the function application `lhs Derv subExpr` should be assigned to `lhs`, and is also the result of the modified assignment expression. ### Expressions -We now give rules for evaluating an `atom`, `Func`, `_mod1` or `_mod2_` expression (the possible options for `ANY`). A literal or primitive `sl`, `Fl`, `_ml`, or `_cl_` has a fixed value defined by the specification ([literals](literal.md) and [built-ins](primitive.md)). An identifier `s`, `F`, `_m`, or `_c_` is evaluated by returning its value; because of the scoping rules it must have one when evaluated. A parenthesized expression such as `"(" _modExpr ")"` simply returns the result of the interior expression. A braced construct such as `BraceFunc` is defined by the evaluation of the statements it contains after all parameters are accepted. Finally, a list `"β¨" β? ( ( EXPR β )* EXPR β? )? "β©"` or `ANY ( "βΏ" ANY )+` consists grammatically of a list of expressions. To evaluate it, each expression is evaluated in source order and their results are placed as elements of a rank-1 array. The two forms have identical semantics but different punctuation. +We now give rules for evaluating an `atom`, `Func`, `_mod1` or `_mod2_` expression (the possible options for `ANY`). A literal or primitive `sl`, `Fl`, `_ml`, or `_cl_` has a fixed value defined by the specification ([literals](literal.md) and [built-ins](primitive.md)). An identifier `s`, `F`, `_m`, or `_c_`, if not preceded by `atom "."`, must have an associated variable due to the scoping rules, and returns this variable's value, or causes an error if it has not yet been set. If it is preceded by `atom "."`, then the `atom` node is evaluated first; its value must be a namespace, and the result is the value of the identifier's name in the namespace, or an error if the name is undefined. A parenthesized expression such as `"(" _modExpr ")"` simply returns the result of the interior expression. A braced construct such as `BraceFunc` is defined by the evaluation of the statements it contains after all parameters are accepted. Finally, a list `"β¨" β? ( ( EXPR β )* EXPR β? )? "β©"` or `ANY ( "βΏ" ANY )+` consists grammatically of a list of expressions. To evaluate it, each expression is evaluated in source order and their results are placed as elements of a rank-1 array. The two forms have identical semantics but different punctuation. Rules in the table below are function and modifier evaluation. | L | Left | Called | Right | R | Types diff --git a/spec/grammar.md b/spec/grammar.md index e9af5f68..af1bb52d 100644 --- a/spec/grammar.md +++ b/spec/grammar.md @@ -17,10 +17,10 @@ A program is a list of statements. Almost all statements are expressions. Namesp Here we define the "atomic" forms of functions and modifiers, which are either single tokens or enclosed in paired symbols. Stranded vectors with `βΏ`, which binds more tightly than any form of execution, are also included. ANY = atom | Func | _mod1 | _mod2_ - _mod2_ = _c_ | _cl_ | "(" _m1Expr_ ")" | ( atom "." )? _brMod2_ - _mod1 = _m | _ml | "(" _m2Expr ")" | ( atom "." )? _brMod1 - Func = F | Fl | "(" FuncExpr ")" | ( atom "." )? BrFunc - atom = s | sl | "(" subExpr ")" | ( atom "." )? brSub | list + _mod2_ = ( atom "." )? _c_ | _cl_ | "(" _m1Expr_ ")" | _brMod2_ + _mod1 = ( atom "." )? _m | _ml | "(" _m2Expr ")" | _brMod1 + Func = ( atom "." )? F | Fl | "(" FuncExpr ")" | BrFunc + atom = ( atom "." )? s | sl | "(" subExpr ")" | brSub | list list = "β¨" β? ( ( EXPR β )* EXPR β? )? "β©" subject = atom | ANY ( "βΏ" ANY )+ @@ -49,7 +49,7 @@ Functions can be formed by fully applying modifiers or as trains. modifiers are FuncExpr = Train | F ASGN FuncExpr -Subject expressions are complicated by the possibility of list assignment. We also define nothing-statements, which have very similar syntax to subject expressions but do not permit assignment. +Subject expressions are complicated by the possibility of list and namespace assignment, which share the nodes `lhsList` and `lhsStr` and cannot be completely distinguished until execution. We also define nothing-statements, which have very similar syntax to subject expressions but do not permit assignment. arg = subExpr | ( subject | nothing )? Derv arg @@ -59,12 +59,10 @@ Subject expressions are complicated by the possibility of list assignment. We al LHS_ANY = LHS_NAME | lhsList LHS_ATOM = LHS_ANY | "(" lhsStr ")" LHS_ELT = LHS_ANY | lhsStr + LHS_ENTRY= LHS_ELT | lhs "β" LHS_NAME lhsStr = LHS_ATOM ( "βΏ" LHS_ATOM )+ - lhsList = "β¨" β? ( ( LHS_ELT β )* LHS_ELT β? )? "β©" - NS_VAR = ( lhs "β" )? LHS_NAME - lhsNs = LHS_NAME ( "βΏ" LHS_NAME )+ - | "β¨" β? ( ( NS_VAR β )* NS_VAR β? )? "β©" - lhs = s | lhsList | lhsStr | lhsNs + lhsList = "β¨" β? ( ( LHS_ENTRY β )* LHS_ENTRY β? )? "β©" + lhs = s | lhsList | lhsStr subExpr = arg | lhs ASGN subExpr | lhs Derv "β©" subExpr # Modified assignment diff --git a/spec/scope.md b/spec/scope.md index e1288cdb..b25c0ce0 100644 --- a/spec/scope.md +++ b/spec/scope.md @@ -28,14 +28,16 @@ The six special names are `π¨π©πππ€π£`, and the tokens `πππ ### Imports and exports -The names to be used in an `IMPORT`, that is, `LHS_NAME` terms in an `NS_VAR` or `nsLHS`, are variable references inside that `IMPORT`'s `brNS` term. If they appear without an accompanying `lhs "β"` term (in `NS_VAR`), then this is in addition to their role as identifiers within the actual enclosing scope, which works like any other assignment. These references behave as though they are at the end of the `brNS` term, that is, they "see" all definitions in the block. However, they must refer to identifiers that are *exported* by that block; references to any other variable cause an error much like references that have no definition. +Names that are preceded by an `atom "."` term, or that appear as `LHS_NAME` terms in an `NS_VAR` or `lhsNs`, are variable references in a namespace: in the first case, the result of the `atom` node, and in the second, of the overall assignments `subExpr` right hand side. These names do not follow lexical scoping; in general they must be stored in order to perform a name lookup when the namespace is available. Such a name in `lhsNs`, or in `NS_VAR` with no accompanying `lhs "β"` term, additionally serves as an identifier within the actual enclosing scope, which works like any other assignment. -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. +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. ## Variables 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, a variable is created 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. +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. diff --git a/spec/token.md b/spec/token.md index 91608c47..d97a6a73 100644 --- a/spec/token.md +++ b/spec/token.md @@ -10,7 +10,7 @@ A BQN *character literal* consists of a single character between single quotes, A comment consists of the hash character `#` and any following text until (not including) the next newline character. The initial `#` must not be part of a string literal started earlier. Comments are ignored entirely and do not form tokens. -Identifiers and numeric literals share the same token formation rule. These tokens are formed from the *numeric characters* `Β―βΟ.0123456789` and *alphabetic characters* `_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ` and the oddball `π£`. Any sequence of these characters adjacent to each other forms a single token, which is a *numeric literal* if it begins with a numeric character and an *identifier* if it begins with an alphabetic character. If a token begins with an underscore then its first non-underscore character must be alphabetic: for example, `_99` is not a valid token. Numeric literals are also subject to [numeric literal rules](literal.md), which specify which numeric literals are valid and which numbers they represent. If the token contains `π£` it must be either `π£`, `_π£`, or `_π£_` and is considered a special name (see below). As the value taken by this identifier can only be a modifier, the uppercase character `β` is not allowed. +Identifiers and numeric literals share the same token formation rule. These tokens are formed from the *numeric characters* `Β―βΟ0123456789` and *alphabetic characters* `_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ` and the oddball `π£`. Additionally, `.` is considered a numeric character if it is followed immediately by a digit (`0123456789`); otherwise it forms its own token. Any sequence of these characters adjacent to each other forms a single token, which is a *numeric literal* if it begins with a numeric character and an *identifier* if it begins with an alphabetic character. If a token begins with an underscore then its first non-underscore character must be alphabetic: for example, `_99` is not a valid token. Numeric literals are also subject to [numeric literal rules](literal.md), which specify which numeric literals are valid and which numbers they represent. If the token contains `π£` it must be either `π£`, `_π£`, or `_π£_` and is considered a special name (see below). As the value taken by this identifier can only be a modifier, the uppercase character `β` is not allowed. Following this step, the whitespace characters space and tab are ignored, and do not form tokens. Only these whitespace characters, and the newline character, which does form a token, are allowed. @@ -19,10 +19,10 @@ Otherwise, a single character forms a token. Only the specified set of character | Class | Characters |-----------------------|------------ | Null literal | `@` -| Primitive Function | `+-ΓΓ·ββββ\|Β¬β§β¨<>β =β€β₯β‘β’β£β’β₯βΎββββ«»β½β/ββββββββ·β` +| Primitive Function | `+-ΓΓ·ββββ\|Β¬β§β¨<>β =β€β₯β‘β’β£β’β₯βΎββββ«»β½β/ββββββββ·β!` | Primitive 1-Modifier | `` ΛΛΛΒ¨ββΌΒ΄Λ` `` | Primitive 2-Modifier | `βββΈββΎββΆβββ` | Special name | `π¨π©πππ€πππ½πΎπ` -| Punctuation | `βββ©β(){}β¨β©βΏβ,` and newline +| Punctuation | `βββ©β(){}β¨β©βΏβ,.` and newline In the BQN [grammar specification](grammar.md), the three primitive classes are grouped into terminals `Fl`, `_ml`, and `_cl`, while the punctuation characters are identified separately as keywords such as `"β"`. The special names are handled specially. The uppercase versions `πππ½πΎπ` and lowercase versions `π¨π©πππ€` are two spellings of the five underlying inputs and function. diff --git a/spec/types.md b/spec/types.md index eb9b8a1f..4549fd04 100644 --- a/spec/types.md +++ b/spec/types.md @@ -2,19 +2,22 @@ # Specification: BQN types -BQN programs manipulate data of six types: +BQN programs manipulate data of seven types: - Character - Number - Array - Function - 1-Modifier - 2-Modifier +- Namespace -Of these, the first three are considered *data types* and the remaining three *operation types*. We first describe the operation types; the remainder of this page will be dedicated to the data types. A member of any operation type accepts some number of *inputs* and either returns a *result* or causes an error; inputs and the result are values of any type. When a function is given inputs (*called*), it may produce side effects before returning, such as manipulating variables and calling other functions within its scope, or performing I/O. +Of these, the first three are considered *data types* and the next three *operation types*. We first describe the operation types and the namespace; the remainder of this page will be dedicated to the data types. A member of any operation type accepts some number of *inputs* and either returns a *result* or causes an error; inputs and the result are values of any type. When a function is given inputs (*called*), it may produce side effects before returning, such as manipulating variables and calling other functions within its scope, or performing I/O. - A *function* takes one (monadic call) or two (dyadic call) *arguments*. - A *1-modifier* takes one *operand*. - A *2-modifier* takes two *operands*. +A namespace holds the variables used to evaluate a block or program, as defined in the [scoping rules](scope.md). The observable aspects of a namespace are that it can be compared for equality with other namespaces and that it exposes variables associated with certain names, whose values can be queried or set. + To begin the data types, a *character* is a [Unicode](https://en.wikipedia.org/wiki/Unicode) code point, that is, its value is a non-negative integer within the ranges defined by Unicode (however, it is distinct from this number as a BQN value). Characters are ordered by this numeric value. BQN deals with code points as abstract entities and does not expose encodings such as UTF-8 or UTF-16. The precise type of a *number* may vary across BQN implementations or instances. A *real number* is a member of some supported subset of the [extended real numbers](https://en.wikipedia.org/wiki/Extended_real_number_line), that is, the real numbers and positive or negative infinity. Some system must be defined for rounding an arbitrary real number to a member of this subset, and the basic arithmetic operations add, subtract, multiply, divide, and natural exponent (base *e*) are defined by performing these operations on exact real values and rounding the result. The Power function (dyadic `β`) is also used but need not be exactly rounded. A *complex number* is a value with two real number *components*, a *real part* and an *imaginary part*. A BQN implementation can either support real numbers only, or complex numbers. |