diff options
| -rw-r--r-- | docs/spec/system.html | 42 | ||||
| -rw-r--r-- | spec/system.md | 25 |
2 files changed, 23 insertions, 44 deletions
diff --git a/docs/spec/system.html b/docs/spec/system.html index 64200f27..de33a0d4 100644 --- a/docs/spec/system.html +++ b/docs/spec/system.html @@ -8,7 +8,7 @@ <p>This portion of the spec is still potentially subject to major changes.</p> <p>The <code><span class='Value'>•</span></code> symbol is used to access values other than primitives provided by BQN.</p> <p>All system values described in the BQN specification are optional: an implementation does not have to include any of them. However, if a system value with one of the names given below is included, then it must have the specified behavior. For namespaces this rule applies to individual fields as well: a namespace may be provided with only some of the fields, but a field with one of the given names must behave as specified.</p> -<h2 id="execution-and-scope-manipulation"><a class="header" href="#execution-and-scope-manipulation">Execution and scope manipulation</a></h2> +<h2 id="execution"><a class="header" href="#execution">Execution</a></h2> <table> <thead> <tr> @@ -22,31 +22,17 @@ <td>Evaluate the argument string in an isolated scope</td> </tr> <tr> -<td><code><span class='Function'>•Eval</span></code></td> -<td>Evaluate the argument string in the current scope</td> -</tr> -<tr> -<td><code><span class='Function'>•ScopedEval</span></code></td> -<td>Evaluate the argument string in a child scope</td> -</tr> -<tr> -<td><code><span class='Function'>•MakeREPL</span></code></td> -<td>Create an evaluator that keeps variables across runs</td> -</tr> -<tr> -<td><code><span class='Function'>•Using</span></code></td> -<td>Import all values from the argument namespace</td> +<td><code><span class='Function'>•ReBQN</span></code></td> +<td>Create a BQN-like evaluation function with options <code><span class='Value'>𝕩</span></code></td> </tr> <tr> -<td><code><span class='Function'>•NewBQN</span></code></td> -<td>Create a BQN-like evaluation function with options <code><span class='Value'>𝕩</span></code></td> +<td><code><span class='Value'>•primitives</span></code></td> +<td>List of primitives as glyph-value pairs</td> </tr> </tbody> </table> -<p>The left argument to any evaluator (<code><span class='Function'>•BQN</span></code>, <code><span class='Function'>•Eval</span></code>, <code><span class='Function'>•ScopedEval</span></code>, result of <code><span class='Function'>•MakeREPL</span></code>), if given, is a list of up to three elements, giving a prefix of <code><span class='Value'>•state</span></code> (see next section) during evaluations of that function. Thus <code><span class='Bracket'>⟨</span><span class='String'>""</span><span class='Separator'>,</span><span class='String'>"xyz"</span><span class='Bracket'>⟩</span><span class='Function'>•BQN</span><span class='String'>"•name"</span></code> returns <code><span class='String'>"xyz"</span></code>.</p> -<p>The effect of <code><span class='Function'>•Eval</span></code> should be the same as if its argument were written as source code in the scope where <code><span class='Function'>•Eval</span></code> appears. It can define variables, and modify those in the current scope or a parent.</p> -<p><code><span class='Function'>•ScopedEval</span></code> creates as new scope for evaluation as it is loaded. Other than its syntactic role, it is effectively equivalent to <code><span class='Brace'>{</span><span class='Function'>•Eval</span><span class='Brace'>}</span></code>. Parent scopes are visible from the created scope; to make a scope without this property use <code><span class='Function'>•BQN</span><span class='String'>"•Eval"</span></code> or <code><span class='Function'>•BQN</span><span class='String'>"•ScopedEval"</span></code>.</p> -<p><code><span class='Function'>•NewBQN</span></code> accepts a namespace <code><span class='Value'>𝕩</span></code>. The following options are specified if supported:</p> +<p>The left argument to <code><span class='Function'>•BQN</span></code> or the result of <code><span class='Function'>•ReBQN</span></code>, if given, is a list of up to three elements, giving a prefix of <code><span class='Value'>•state</span></code> (see next section) during evaluations of that function. Thus <code><span class='Bracket'>⟨</span><span class='String'>""</span><span class='Separator'>,</span><span class='String'>"xyz"</span><span class='Bracket'>⟩</span><span class='Function'>•BQN</span><span class='String'>"•name"</span></code> returns <code><span class='String'>"xyz"</span></code>.</p> +<p><code><span class='Function'>•ReBQN</span></code> accepts a namespace <code><span class='Value'>𝕩</span></code>. The following options are specified if supported:</p> <table> <thead> <tr> @@ -60,20 +46,20 @@ <td><code><span class='String'>"none"</span></code>, <code><span class='String'>"strict"</span></code>, <code><span class='String'>"loose"</span></code></td> </tr> <tr> -<td><code><span class='Value'>scope</span></code></td> -<td><code><span class='String'>"none"</span></code>, <code><span class='String'>"read"</span></code>, <code><span class='String'>"modify"</span></code></td> +<td><code><span class='Value'>primitives</span></code></td> +<td>List of glyph-value pairs; default <code><span class='Value'>•primitives</span></code></td> </tr> <tr> -<td><code><span class='Value'>primitives</span></code></td> -<td>List of glyph-value pairs; default <code><span class='Bracket'>⟨⟩</span></code></td> +<td><code><span class='Value'>system</span></code></td> +<td><code><span class='String'>"all"</span></code>, <code><span class='String'>"none"</span></code>, <code><span class='String'>"safe"</span></code> or list of names</td> </tr> <tr> -<td><code><span class='Value'>retain</span></code></td> -<td><code><span class='String'>"all"</span></code>, <code><span class='String'>"unique"</span></code>, <code><span class='String'>"none"</span></code></td> +<td><code><span class='Value'>scope</span></code></td> +<td><code><span class='String'>"none"</span></code>, <code><span class='String'>"read"</span></code>, <code><span class='String'>"modify"</span></code> or list of name-setting pairs</td> </tr> </tbody> </table> -<p>The option <code><span class='Value'>repl</span></code> indicates how variables are retained across calls: with "none" they are not saved; with "strict", they are saved and can't be redefined; and with "loose" they may be redefined. <code><span class='Value'>scope</span></code> indicates allowed interaction with the scope in which <code><span class='Function'>•NewBQN</span></code> is <em>called</em> (not loaded): with "read" variables may be read and with "modify" they may be read or modified. <code><span class='Value'>primitives</span></code> indicates primitives to be added in this copy of BQN. Each primitive uses the glyph and value given. The value must have an operation type and its type determines the primitive's role. <code><span class='Value'>retain</span></code> indicates which primitives from the current running BQN should be kept. With "all", an error is given if <code><span class='Value'>primitives</span></code> redefines an existing primitive, but with "unique" primitives may be redefined.</p> +<p>The option <code><span class='Value'>repl</span></code> indicates how variables are retained across calls: with "none" they are not saved; with "strict", they are saved and can't be redefined; and with "loose" they may be redefined. Each element in <code><span class='Value'>primitives</span></code> gives the glyph and value for a primitive to be made available. The value must have an operation type and its type determines the primitive's role. <code><span class='Value'>system</span></code> in general gives the list of system values to be made available, with shorthand values to indicate all currently-available ones, none of them, or only a subset that cannot be used to interact with anything outside of the execution context. <code><span class='Value'>scope</span></code> indicates allowed interaction with the scope in which <code><span class='Function'>•ReBQN</span></code> is <em>called</em> (not loaded): with "read" variables may be read and with "modify" they may be read or modified.</p> <h2 id="scripts"><a class="header" href="#scripts">Scripts</a></h2> <table> <thead> diff --git a/spec/system.md b/spec/system.md index c003cdb5..81802c83 100644 --- a/spec/system.md +++ b/spec/system.md @@ -8,33 +8,26 @@ The `•` symbol is used to access values other than primitives provided by BQN. All system values described in the BQN specification are optional: an implementation does not have to include any of them. However, if a system value with one of the names given below is included, then it must have the specified behavior. For namespaces this rule applies to individual fields as well: a namespace may be provided with only some of the fields, but a field with one of the given names must behave as specified. -## Execution and scope manipulation +## Execution | Name | Summary |---------------|-------------------------- | `•BQN` | Evaluate the argument string in an isolated scope -| `•Eval` | Evaluate the argument string in the current scope -| `•ScopedEval` | Evaluate the argument string in a child scope -| `•MakeREPL` | Create an evaluator that keeps variables across runs -| `•Using` | Import all values from the argument namespace -| `•NewBQN` | Create a BQN-like evaluation function with options `𝕩` +| `•ReBQN` | Create a BQN-like evaluation function with options `𝕩` +| `•primitives` | List of primitives as glyph-value pairs -The left argument to any evaluator (`•BQN`, `•Eval`, `•ScopedEval`, result of `•MakeREPL`), if given, is a list of up to three elements, giving a prefix of `•state` (see next section) during evaluations of that function. Thus `⟨"","xyz"⟩•BQN"•name"` returns `"xyz"`. +The left argument to `•BQN` or the result of `•ReBQN`, if given, is a list of up to three elements, giving a prefix of `•state` (see next section) during evaluations of that function. Thus `⟨"","xyz"⟩•BQN"•name"` returns `"xyz"`. -The effect of `•Eval` should be the same as if its argument were written as source code in the scope where `•Eval` appears. It can define variables, and modify those in the current scope or a parent. - -`•ScopedEval` creates as new scope for evaluation as it is loaded. Other than its syntactic role, it is effectively equivalent to `{•Eval}`. Parent scopes are visible from the created scope; to make a scope without this property use `•BQN"•Eval"` or `•BQN"•ScopedEval"`. - -`•NewBQN` accepts a namespace `𝕩`. The following options are specified if supported: +`•ReBQN` accepts a namespace `𝕩`. The following options are specified if supported: | Option | Values (default first) |---------------|-------------------------- | `repl` | `"none"`, `"strict"`, `"loose"` -| `scope` | `"none"`, `"read"`, `"modify"` -| `primitives` | List of glyph-value pairs; default `⟨⟩` -| `retain` | `"all"`, `"unique"`, `"none"` +| `primitives` | List of glyph-value pairs; default `•primitives` +| `system` | `"all"`, `"none"`, `"safe"` or list of names +| `scope` | `"none"`, `"read"`, `"modify"` or list of name-setting pairs -The option `repl` indicates how variables are retained across calls: with "none" they are not saved; with "strict", they are saved and can't be redefined; and with "loose" they may be redefined. `scope` indicates allowed interaction with the scope in which `•NewBQN` is *called* (not loaded): with "read" variables may be read and with "modify" they may be read or modified. `primitives` indicates primitives to be added in this copy of BQN. Each primitive uses the glyph and value given. The value must have an operation type and its type determines the primitive's role. `retain` indicates which primitives from the current running BQN should be kept. With "all", an error is given if `primitives` redefines an existing primitive, but with "unique" primitives may be redefined. +The option `repl` indicates how variables are retained across calls: with "none" they are not saved; with "strict", they are saved and can't be redefined; and with "loose" they may be redefined. Each element in `primitives` gives the glyph and value for a primitive to be made available. The value must have an operation type and its type determines the primitive's role. `system` in general gives the list of system values to be made available, with shorthand values to indicate all currently-available ones, none of them, or only a subset that cannot be used to interact with anything outside of the execution context. `scope` indicates allowed interaction with the scope in which `•ReBQN` is *called* (not loaded): with "read" variables may be read and with "modify" they may be read or modified. ## Scripts |