Section on compiler arguments in VM docs

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/implementation/vm.html b/docs/implementation/vm.html
index 56a020a7..c1916ab7 100644
--- a/docs/implementation/vm.html
+++ b/docs/implementation/vm.html
@@ -714,6 +714,17 @@
   <span class='Value'>r</span>
 <span class='Brace'>}</span>
 </pre>
+<h2 id="compiler-arguments"><a class="header" href="#compiler-arguments">Compiler arguments</a></h2>
+<p>The compiler takes the source code as <code><span class='Value'>𝕩</span></code>. The execution environment is passed as <code><span class='Value'>𝕨</span></code>, which can contain up to four values:</p>
+<ul>
+<li><strong>Runtime</strong>: list of primitive values; see <a href="#runtime">previous section</a></li>
+<li><strong>System</strong>: function that takes a list of strings and returns corresponding system values</li>
+<li><strong>Variables</strong>: names of existing variables in the scope</li>
+<li><strong>Depths</strong>: lexical depth of these variables (default <code><span class='Number'>0</span></code>; <code><span class='Number'>¯1</span></code> for depth 0 but allowing shadowing)</li>
+</ul>
+<p>If <code><span class='Value'>𝕨</span></code> has length greater than 4 it's assumed to be the runtime only. If the length is less than 4, empty defaults that don't define any values are used for the missing arguments.</p>
+<p>The system-value function is passed a list of unique normalized names, meaning that each name is lowercase and contains no underscores. It should return a corresponding list of system values. Because system values are requested on each program run, a function that has access to context such as <code><span class='Value'>•path</span></code> can construct appropriate system values on demand.</p>
+<p>The variable list is used to create REPLs, but has other uses as well, such as allowing execution to take place within a surrounding scope. It consists of a list of normalized names. The corresponding depth list indicates the lexical depth of each of these, with 0 and -1 indicating that the variable should exist directly in the top-level scope. A typical interactive REPL uses only the value -1, because it allows variables to be shadowed. It maintains a single top-level environment to be used for all evaluations. When the programmer enters a line, it's compiled, then the environment and list of top-level names is extended according to the result.</p>
 <h2 id="assembly"><a class="header" href="#assembly">Assembly</a></h2>
 <p>The full BQN implementation is made up of the two components above—virtual machine and core runtime—and the compiled runtime, compiler, and formatter. Since the compiler unlikely to work right away, I suggest initially testing the virtual machine on smaller pieces of code compiled by an existing, working, BQN implementation.</p>
 <p>BQN sources are compiled with <a href="https://github.com/mlochbaum/BQN/blob/master/implementation/../src/cjs.bqn">cjs.bqn</a>, which runs under <a href="https://github.com/dzaima/BQN/">dzaima/BQN</a> as a Unix-style script. It has two modes. If given a command-line argument <code><span class='Value'>r</span></code>, <code><span class='Value'>c</span></code>, or <code><span class='Value'>fmt</span></code>, it compiles one of the source files. With any other command-line arguments, it will compile each one, and format it as a single line of output. The output is in a format designed for Javascript, but it can be adjusted to work in other languages either by text replacement on the output or changes to the formatting functions in cjs.bqn.</p>