diff options
Diffstat (limited to 'docs/spec/index.html')
| -rw-r--r-- | docs/spec/index.html | 17 |
1 files changed, 14 insertions, 3 deletions
diff --git a/docs/spec/index.html b/docs/spec/index.html index 71d7c6f6..5c2017e1 100644 --- a/docs/spec/index.html +++ b/docs/spec/index.html @@ -5,9 +5,9 @@ </head> <div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a></div> <h1 id="bqn-specification">BQN specification</h1> -<p>This directory gives a specification for BQN. The specification differs from the <a href="../doc/index.html">documentation</a> in that its purpose is only to describe the exact details of BQN's operation in the most quickly accessible way, rather than to explain the core ideas of BQN functionality and how it might be used.</p> -<p>The core of BQN, which excludes system-provided values, is now completely specified, although the spec will continue to be edited further to improve clarity and cover edge cases that were missed initially.</p> -<p>The BQN specification consists of the following documents:</p> +<p>This document, and the others in this directory (linked in the list below) make up the pre-versioning BQN specification. The specification differs from the <a href="../doc/index.html">documentation</a> in that its purpose is only to describe the exact details of BQN's operation in the most quickly accessible way, rather than to explain the central ideas of BQN functionality and how it might be used. The core of BQN, which excludes system-provided values, is now almost completely specified. Three planned features—syntax for system-provided values, inferred property function headers, and an extension to allow low-rank elements in the argument to Join—have not yet been added, and the spec will continue to be edited further to improve clarity and cover any edge cases that have been missed.</p> +<p>Under this specification, a language implementation is a <strong>BQN pre-version implementation</strong> if it behaves as specified for all input programs. It is a <strong>BQN pre-version implementation with extensions</strong> if it behaves as specified in all cases where the specification does not require an error, but behaves differently in at least one case where it requires an error. It is a <strong>partial</strong> version of either of these if it doesn't conform to the description but differs from a conforming implementation only by rejecting with an error some programs that the conforming implementation accepts. As the specification is not yet versioned, other instances of the specification define these terms in different ways. An implementation can use one of these term if it conforms to any instance of the pre-versioning BQN specifications that defines them. When versioning is begun, there will be only one specification for each version.</p> +<p>The following documents are included in the BQN specification. A BQN program is a sequence of <a href="https://en.wikipedia.org/wiki/Unicode">Unicode</a> code points: to evaluate it, it is converted into a sequence of tokens using the token formation rules, then these tokens are arranged in a syntax tree according to the grammar, and then this tree is evaluated according to the evaluation semantics. The program may be evaluated in the presence of additional context such as a filesystem or command-line arguments; this context is presented to the program and manipulated through the system-provided values.</p> <ul> <li><a href="types.html">Types</a></li> <li><a href="token.html">Token formation</a></li> @@ -19,3 +19,14 @@ <li><a href="inferred.html">Inferred properties</a> (identities, fills, Undo, and Under)</li> <li><a href="system.html">System-provided values</a> (<code><span class='Value'>•</span></code>)</li> </ul> +<p>In several cases, an implementation can choose between more than one possible behavior.</p> +<ul> +<li>An implementation chooses its number system, which must be an approximation of the real or complex numbers but has no specific requirements. Results of basic numeric operations must be deterministic but are not specified.</li> +<li>Minimum (<code><span class='Function'>⌊</span></code>) and Maximum (<code><span class='Function'>⌈</span></code>) may give an error if either argument is a character.</li> +<li>Other than the required cases, attempting to use an inferred property can either fail or give a result consistent with the constraints on that property.</li> +<li>In some cases there are multiple valid results for Undo. Any of these results, or an error, can be given; if there is no obvious choice of result an error is recommended. The choice must depend only on the inputs to Undo.</li> +<li>If the specification does not identify the fill element for an array, then any or no fill can be deterministically chosen.</li> +<li>If an expression in a program cannot be evaluated without error (that is, there is no context that would cause the program, or a caller with access to its result, to evaluate the expression but not eventually fail with an error), then the implementation may reject this program, giving an error before evaluating any code and regardless of context—in this case, it must not accept the program in any context. This "compiler clause" modifies the behavior described above.</li> +<li>The way the program's output (either a result or an error) is displayed to the user is not specified.</li> +<li>Any system values can be implemented, and they may act in an arbitrary way including modifying the behavior of the rest of the program. If system values with names given in this specification are implemented, however, then they must conform with the specified behavior.</li> +</ul> |