From 5b661e364c0925706e00f93134f44c3a3fb765be Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Fri, 26 Mar 2021 21:56:02 -0400 Subject: Editing and clarifications --- docs/spec/system.html | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/spec/system.html b/docs/spec/system.html index 3da59147..978a5610 100644 --- a/docs/spec/system.html +++ b/docs/spec/system.html @@ -5,7 +5,7 @@
BQN / main / spec

Specification: BQN system-provided values

-

This portion of the spec is definitely still a draft.

+

This portion of the spec is still potentially subject to major changes.

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.

Scripts

@@ -35,11 +35,11 @@ -

•Import loads another BQN script. The script is evaluated in its own scope, and its result is either the result of the last line, or a module if it exports with ⇐ at the top level. If it is a module, then it must be destructured immediately unless first-class namespaces are possible.

+

•Import loads another BQN script. The script is evaluated in its own isolated scope, and its result is either the result of the last line, or a module if it exports with ⇐ at the top level. If it is a module, then it must be destructured immediately unless first-class namespaces are possible.

The right argument is a filename, which may be relative or absolute. Relative paths are taken relative to the source file where this instance of •Import was written. The left argument, if given, is the list of arguments that should be passed through to the file as •args. If no left argument is given then ⟨⟩ is used for •args. However, the behavior is different in this case. The same file will only be loaded once in a given BQN program by •Import calls with no left argument: the first such call saves the returned value, even if it is mutable, and subsequent calls return this saved value. To avoid this and reload the file, pass a left argument of ⟨⟩.

•args is the arguments passed as the file was invoked, either from the command line or •Import. For command line calls it is a list of strings.

•path simply gives the path of the file in which it appears. It includes a trailing slash but not the name of the file itself.

-

•name gives the name, including the extension, of the file in which it appears.

+

•name gives the name, including the extension, of the file in which it appears. It doesn't include the path.

File access

@@ -89,7 +89,7 @@ - + @@ -98,7 +98,7 @@
•ScopedEvalEvaluate the argument string in a scopeEvaluate the argument string in a child scope
•Using

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}.

+

•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".

Input and output

@@ -179,10 +179,14 @@ + + + +
5 2-modifier
6Namespace

•Glyph gives the glyph corresponding to a primitive as a single character, for example returning '+' given an argument matching +. It causes an error if the argument is not a primitive.

-

•Source gives a string containing a block's source, including the enclosing braces {}. It causes an error if the argument is not a primitive.

+

•Source gives a string containing a block's source, including the enclosing braces {}. It causes an error if the argument is not a block. In contrast to •Glyph, this function does not give full information about 𝕩 because the result cannot convey environment or mutable identity.

•Decompose breaks down one level of a compound function or modifier, returning a list with a code giving what kind of structure it has (as listed in the table below) followed by each of its components. Non-operations do not cause an error, but return code -1, then the argument as a single component. The result is thus a list of length 2 to 4, and •Decompose cannot cause an error.

@@ -273,5 +277,5 @@

All times are measured in seconds.

The Unix epoch is 1970-01-01 00:00:00 UTC. •UnixTime is intended for absolute time measurement and should be implemented with the method that gives the most accurate result at any given time. •MonoTime is intended for relative measurement and should use the method that gives the most precise time differences over the course of the program. Its return value must never decrease between calls.

-

•_timed returns the total time taken divided by the number of function calls, including the overhead required for the outer loop that counts iterations (which will typically be negligible in comparison to the BQN code).

+

•_timed returns the total time taken divided by the number of function calls (𝕨 if provided and 1 otherwise), including the overhead required for the outer loop that counts iterations (which will typically be negligible in comparison to the BQN code).

More accurately the modifier •_maxTime_ may fail if execution of 𝔽 takes over 𝕨𝔾𝕩 seconds, and should fail as quickly as it is practically able to. The most likely way to implement this modifier is to interrupt execution at the given time. If 𝔽 completes before the interrupt there is no need to measure the amount of time it actually took.

-- cgit v1.2.3