Add grammar for namespace blocks with export and import statements

1 files changed, 30 insertions, 13 deletions

diff --git a/docs/spec/grammar.html b/docs/spec/grammar.html
index b5443ce7..8eabe899 100644
--- a/docs/spec/grammar.html
+++ b/docs/spec/grammar.html
@@ -7,9 +7,9 @@
 <h1 id="specification-bqn-grammar">Specification: BQN grammar</h1>
 <p>BQN's grammar is given below. Terms are defined in a <a href="https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form">BNF</a> variant. However, handling special names properly is possible but difficult in BNF, so they are explained in text along with the braced block grammar.</p>
 <p>The symbols <code><span class='Value'>s</span></code>, <code><span class='Function'>F</span></code>, <code><span class='Modifier'>_m</span></code>, and <code><span class='Modifier2'>_c_</span></code> are identifier tokens with subject, function, 1-modifier, and 2-modifier classes respectively. Similarly, <code><span class='Value'>sl</span></code>, <code><span class='Function'>Fl</span></code>, <code><span class='Modifier'>_ml</span></code>, and <code><span class='Modifier2'>_cl_</span></code> refer to literals and primitives of those classes. While names in the BNF here follow the identifier naming scheme, this is informative only: syntactic classes are no longer used after parsing and cannot be inspected in a running program.</p>
-<p>A program is a list of statements. Almost all statements are expressions. Only valueless results stemming from <code><span class='Nothing'>·</span></code>, or <code><span class='Value'>𝕨</span></code> in a monadic brace function, can be used as statements but not expressions.</p>
-<pre><span class='Function'>PROGRAM</span>  <span class='Function'>=</span> <span class='Separator'>⋄</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>STMT</span> <span class='Separator'>⋄</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>STMT</span> <span class='Separator'>⋄</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span>
-<span class='Function'>STMT</span>     <span class='Function'>=</span> <span class='Function'>EXPR</span> <span class='Function'>|</span> <span class='Value'>nothing</span>
+<p>A program is a list of statements. Almost all statements are expressions. Valueless results stemming from <code><span class='Nothing'>·</span></code>, or <code><span class='Value'>𝕨</span></code> in a monadic brace function, can be used as statements but not expressions. &quot;Namespace statements&quot;, which import multiple values from a namespace block (immediate block containing <code><span class='Gets'>⇐</span></code>), also cannot be expressions. An extension to BQN to allow first-class namespaces would extend ordinary expressions so that <code><span class='Function'>NS_STMT</span></code> would no longer be needed, as it would be a subset of <code><span class='Function'>EXPR</span></code>.</p>
+<pre><span class='Function'>PROGRAM</span>  <span class='Function'>=</span> <span class='Separator'>⋄</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>STMT</span> <span class='Function'>|</span> <span class='Function'>EXPORT</span> <span class='Separator'>⋄</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Function'>STMT</span> <span class='Separator'>⋄</span><span class='Value'>?</span> <span class='Paren'>)</span><span class='Value'>?</span>
+<span class='Function'>STMT</span>     <span class='Function'>=</span> <span class='Function'>EXPR</span> <span class='Function'>|</span> <span class='Value'>nothing</span> <span class='Function'>|</span> <span class='Function'>NS_STMT</span>
 <span class='Separator'>⋄</span>        <span class='Function'>=</span> <span class='Paren'>(</span> <span class='String'>&quot;⋄&quot;</span> <span class='Function'>|</span> <span class='String'>&quot;,&quot;</span> <span class='Function'>|</span> <span class='Value'>\n</span> <span class='Paren'>)</span><span class='Function'>+</span>
 <span class='Function'>EXPR</span>     <span class='Function'>=</span> <span class='Value'>subExpr</span> <span class='Function'>|</span> <span class='Function'>FuncExpr</span> <span class='Function'>|</span> <span class='Modifier'>_m1Expr</span> <span class='Function'>|</span> <span class='Modifier2'>_m2Expr_</span>
 </pre>
@@ -22,8 +22,8 @@
 <span class='Value'>list</span>     <span class='Function'>=</span> <span class='String'>&quot;⟨&quot;</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'>&quot;⟩&quot;</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'>&quot;‿&quot;</span> <span class='Function'>ANY</span> <span class='Paren'>)</span><span class='Function'>+</span>
 </pre>
-<p>Starting at the highest-order objects, modifiers have fairly simple syntax. In most cases the syntax for <code><span class='Gets'>←</span></code> and <code><span class='Gets'>↩</span></code> is the same, but only <code><span class='Gets'>↩</span></code> can be used for modified assignment.</p>
-<pre><span class='Function'>ASGN</span>     <span class='Function'>=</span> <span class='String'>&quot;←&quot;</span> <span class='Function'>|</span> <span class='String'>&quot;↩&quot;</span>
+<p>Starting at the highest-order objects, modifiers have fairly simple syntax. In most cases the syntax for <code><span class='Gets'>←</span></code> and <code><span class='Gets'>↩</span></code> is the same, but only <code><span class='Gets'>↩</span></code> can be used for modified assignment. The export arrow <code><span class='Gets'>⇐</span></code> can only be used in namespace blocks <code><span class='Value'>brNS</span></code>, and the top-level <code><span class='Function'>PROGRAM</span></code>. There it can be used in the same ways as <code><span class='Gets'>←</span></code>, but it can also be used in a <code><span class='Value'>brNS</span></code> header, or with no expression on the right in an <code><span class='Function'>EXPORT</span></code> statement.</p>
+<pre><span class='Function'>ASGN</span>     <span class='Function'>=</span> <span class='String'>&quot;←&quot;</span> <span class='Function'>|</span> <span class='String'>&quot;⇐&quot;</span> <span class='Function'>|</span> <span class='String'>&quot;↩&quot;</span>
 <span class='Modifier2'>_m2Expr_</span> <span class='Function'>=</span> <span class='Modifier2'>_mod2_</span>
          <span class='Function'>|</span> <span class='Modifier2'>_c_</span> <span class='Function'>ASGN</span> <span class='Modifier2'>_m2Expr_</span>
 <span class='Modifier'>_m1Expr</span>  <span class='Function'>=</span> <span class='Modifier'>_mod1</span>
@@ -50,13 +50,13 @@
          <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'>&quot;·&quot;</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'>nothing</span>
-<span class='Function'>LHS_ANY</span>  <span class='Function'>=</span> <span class='Value'>lhsSub</span> <span class='Function'>|</span> <span class='Function'>F</span> <span class='Function'>|</span> <span class='Modifier'>_m</span> <span class='Function'>|</span> <span class='Modifier2'>_c_</span>
+<span class='Function'>LHS_NAME</span> <span class='Function'>=</span> <span class='Value'>s</span> <span class='Function'>|</span> <span class='Function'>F</span> <span class='Function'>|</span> <span class='Modifier'>_m</span> <span class='Function'>|</span> <span class='Modifier2'>_c_</span>
+<span class='Function'>LHS_ANY</span>  <span class='Function'>=</span> <span class='Function'>LHS_NAME</span>
+         <span class='Function'>|</span> <span class='String'>&quot;⟨&quot;</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'>&quot;⟩&quot;</span>
 <span class='Function'>LHS_ATOM</span> <span class='Function'>=</span> <span class='Function'>LHS_ANY</span> <span class='Function'>|</span> <span class='String'>&quot;(&quot;</span> <span class='Value'>lhsStr</span> <span class='String'>&quot;)&quot;</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='Value'>lhsSub</span>   <span class='Function'>=</span> <span class='Value'>s</span>
-         <span class='Function'>|</span> <span class='String'>&quot;⟨&quot;</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'>&quot;⟩&quot;</span>
 <span class='Value'>lhsStr</span>   <span class='Function'>=</span> <span class='Function'>LHS_ATOM</span> <span class='Paren'>(</span> <span class='String'>&quot;‿&quot;</span> <span class='Function'>LHS_ATOM</span> <span class='Paren'>)</span><span class='Function'>+</span>
-<span class='Value'>lhs</span>      <span class='Function'>=</span> <span class='Value'>lhsSub</span> <span class='Function'>|</span> <span class='Value'>lhsStr</span>
+<span class='Value'>lhs</span>      <span class='Function'>=</span> <span class='Value'>s</span> <span class='Function'>|</span> <span class='Value'>lhsSub</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'>&quot;↩&quot;</span> <span class='Value'>subExpr</span>       <span class='Comment'># Modified assignment
@@ -87,7 +87,16 @@
 <span class='Modifier'>_brMod1</span>  <span class='Function'>=</span> <span class='String'>&quot;{&quot;</span> <span class='Paren'>(</span> <span class='Modifier'>_mCase</span>  <span class='String'>&quot;;&quot;</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Paren'>(</span> <span class='Modifier'>_mCase</span>  <span class='Function'>|</span> <span class='Modifier'>_mMain</span> <span class='Paren'>(</span> <span class='String'>&quot;;&quot;</span> <span class='Modifier'>_mMain</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Paren'>)</span> <span class='String'>&quot;}&quot;</span>
 <span class='Modifier2'>_brMod2_</span> <span class='Function'>=</span> <span class='String'>&quot;{&quot;</span> <span class='Paren'>(</span> <span class='Modifier2'>_cCase_</span> <span class='String'>&quot;;&quot;</span> <span class='Paren'>)</span><span class='Value'>*</span> <span class='Paren'>(</span> <span class='Modifier2'>_cCase_</span> <span class='Function'>|</span> <span class='Modifier2'>_cMan_</span> <span class='Paren'>(</span> <span class='String'>&quot;;&quot;</span> <span class='Modifier2'>_cMan_</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Paren'>)</span> <span class='String'>&quot;}&quot;</span>
 </pre>
-<p>Two additional rules apply to blocks, based on the special name associations in the table below. First, each block allows the special names in its column to be used as the given token types within <code><span class='Function'>BODY</span></code> terms (not headers). Except for the spaces labelled &quot;None&quot;, each column is cumulative and a given entry also includes all the entries above it. Second, for <code><span class='Function'>BrFunc</span></code>, <code><span class='Modifier'>_brMod1</span></code>, and <code><span class='Modifier2'>_brMod2_</span></code> terms, if no header is given, then at least one <code><span class='Function'>BODY</span></code> term in it <em>must</em> contain one of the names on, and not above, the corresponding row. Otherwise the syntax would be ambiguous, since for example a simple <code><span class='String'>&quot;{&quot;</span> <span class='Function'>BODY</span> <span class='String'>&quot;}&quot;</span></code> sequence could have any type.</p>
+<p>A namespace block is very similar in grammar to an ordinary immediate block, but allows export declarations with <code><span class='Gets'>⇐</span></code>, either in place of the ordinary definition <code><span class='Gets'>←</span></code> or in the special <code><span class='Function'>EXPORT</span></code> statement. The arrow <code><span class='Gets'>⇐</span></code> can also be placed in the header to mark a namespace block.</p>
+<pre><span class='Function'>NS_STMT</span>  <span class='Function'>=</span> <span class='Value'>nsLHS</span> <span class='Function'>ASGN</span> <span class='Value'>brNS</span>
+<span class='Function'>NS_VAR</span>   <span class='Function'>=</span> <span class='Function'>LHS_NAME</span> <span class='Paren'>(</span> <span class='String'>&quot;:&quot;</span> <span class='Value'>lhs</span> <span class='Paren'>)</span><span class='Value'>?</span>
+<span class='Value'>nsLHS</span>    <span class='Function'>=</span> <span class='Function'>LHS_NAME</span> <span class='Paren'>(</span> <span class='String'>&quot;‿&quot;</span> <span class='Function'>LHS_NAME</span> <span class='Paren'>)</span><span class='Function'>+</span>
+         <span class='Function'>|</span> <span class='String'>&quot;⟨&quot;</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'>&quot;⟩&quot;</span>
+<span class='Function'>EXPORT</span>   <span class='Function'>=</span> <span class='Paren'>(</span> <span class='Function'>LHS_NAME</span> <span class='Function'>|</span> <span class='Value'>lhsSub</span> <span class='Function'>|</span> <span class='Value'>lhsStr</span> <span class='Paren'>)</span> <span class='String'>&quot;⇐&quot;</span>
+<span class='Function'>NS_BODY</span>  <span class='Function'>=</span> <span class='Separator'>⋄</span><span class='Value'>?</span> <span class='Paren'>(</span> <span class='Paren'>(</span> <span class='Function'>STMT</span> <span class='Function'>|</span> <span class='Function'>EXPORT</span> <span class='Paren'>)</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='Value'>brNS</span>     <span class='Function'>=</span> <span class='String'>&quot;{&quot;</span> <span class='Paren'>(</span> <span class='Separator'>⋄</span><span class='Value'>?</span> <span class='String'>&quot;⇐&quot;</span><span class='Value'>?</span> <span class='Value'>s</span> <span class='String'>&quot;:&quot;</span> <span class='Paren'>)</span><span class='Value'>?</span> <span class='Function'>NS_BODY</span> <span class='String'>&quot;}&quot;</span>
+</pre>
+<p>Two additional rules apply to blocks, based on the special name associations in the table below. First, each block allows the special names in its column to be used as the given token types within <code><span class='Function'>BODY</span></code> terms (not headers). Except for the spaces labelled &quot;None&quot;, each column is cumulative and a given entry also includes all the entries above it up to the next &quot;None&quot;. Second, for <code><span class='Function'>BrFunc</span></code>, <code><span class='Modifier'>_brMod1</span></code>, <code><span class='Modifier2'>_brMod2_</span></code>, and <code><span class='Value'>brNS</span></code> terms, if no header is given (or, for <code><span class='Value'>brNS</span></code>, if the header does not contain <code><span class='String'>&quot;⇐&quot;</span></code>), then at least one <code><span class='Function'>BODY</span></code> term in it <em>must</em> contain one of the tokens on, and not above, the corresponding row. Otherwise the syntax would be ambiguous, since for example a simple <code><span class='String'>&quot;{&quot;</span> <span class='Function'>BODY</span> <span class='String'>&quot;}&quot;</span></code> sequence could have any type.</p>
 <table>
 <thead>
 <tr>
@@ -101,12 +110,20 @@
 </thead>
 <tbody>
 <tr>
-<td><code><span class='Value'>brSub</span></code>, <code><span class='Function'>PROGRAM</span></code></td>
+<td><code><span class='Value'>brNS</span></code>, <code><span class='Function'>PROGRAM</span></code></td>
+<td>None</td>
+<td>None</td>
+<td>None</td>
+<td>None</td>
+<td><code><span class='Gets'>⇐</span></code></td>
+</tr>
+<tr>
+<td><code><span class='Value'>brSub</span></code></td>
+<td>None</td>
 <td>None</td>
 <td>None</td>
 <td>None</td>
 <td>None</td>
-<td></td>
 </tr>
 <tr>
 <td><code><span class='Function'>BrFunc</span></code></td>
@@ -114,7 +131,7 @@
 <td><code><span class='Function'>𝕎𝕏𝕊</span></code></td>
 <td></td>
 <td></td>
-<td><code><span class='String'>&quot;;&quot;</span></code></td>
+<td><code><span class='Value'>;</span></code></td>
 </tr>
 <tr>
 <td><code><span class='Modifier'>_brMod1</span></code></td>