From d01198f380e89979e9583117b7fef44cb222364c Mon Sep 17 00:00:00 2001
From: Marshall Lochbaum <mwlochbaum@gmail.com>
Date: Wed, 18 Aug 2021 17:32:23 -0400
Subject: Update docs based on full header support

---
 README.md                   |  2 +-
 docs/implementation/vm.html | 14 ++++++++++----
 docs/index.html             |  2 +-
 docs/running.html           |  5 ++---
 docs/try.html               |  1 -
 implementation/vm.md        |  7 ++++---
 running.md                  |  6 ++----
 7 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index aa745184..6447fc59 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 </center>
 
-*Try it online below, on [this page](https://mlochbaum.github.io/BQN/try.html), or [in our chat](#where-can-i-find-bqn-users). Offline options [here](running.md).*
+*Try it online below, on [this page](https://mlochbaum.github.io/BQN/try.html), or [in our chat](#where-can-i-find-bqn-users). Use [CBQN](https://github.com/dzaima/CBQN) offline; details [here](running.md).*
 <!--GEN
 E ← ⊐⟜":"⊸(↑At"class="∾1⊸+⊸↓)⊸Enc
 repl ← "div:cont" E ⟨
diff --git a/docs/implementation/vm.html b/docs/implementation/vm.html
index 234101be..c7ba1507 100644
--- a/docs/implementation/vm.html
+++ b/docs/implementation/vm.html
@@ -242,10 +242,10 @@
 <tr>
 <td align="right">23</td>
 <td>VFYM</td>
-<td align="center"></td>
+<td align="center">X</td>
 <td align="right"></td>
 <td align="left"></td>
-<td>Convert to matcher (for header tests)</td>
+<td>Convert constant to matcher (for headers)</td>
 </tr>
 <tr>
 <td align="right">24</td>
@@ -421,6 +421,12 @@
 <td>Local variable reference</td>
 </tr>
 <tr>
+<td align="right">23</td>
+<td>VFYM</td>
+<td><code><span class='Value'>c</span> <span class='Gets'>→</span> <span class='Value'>r</span></code></td>
+<td>Constant to match reference</td>
+</tr>
+<tr>
 <td align="right">25</td>
 <td>RETN</td>
 <td><code><span class='Value'>x</span> <span class='Gets'>→</span> <span class='Value'>x</span></code></td>
@@ -453,12 +459,12 @@
 <p>When a block is pushed with <strong>DFND</strong>, an instance of the block is created, with its <em>parent frame</em> set to be the frame of the currently-executing block. Setting the parent frame when the block is first seen, instead of when it's evaluated, is what distinguishes lexical from dynamic scoping. If it's an immediate block, it's evaluated immediately, and otherwise it's pushed onto the stack. When the block is evaluated, its frame is initialized using any arguments passed to it, the next instruction's index is pushed onto the return stack, and execution moves to the first instruction in the block. When the RETN instruction is encountered, an index is popped from the return stack and execution returns to this location. As an alternative to maintaining an explicit return stack, a block can be implemented as a native function that creates a new execution stack and returns the value in it when the <strong>RETN</strong> instruction is reached. This approach uses the implementation language's call stack for the return stack.</p>
 <p>Local variables are manipulated with the <strong>LOCO</strong> (or <strong>LOCU</strong>) and <strong>LOCM</strong> instructions, which load the value of a variable and a reference to it (see the next section) respectively. These instructions reference variables by <em>frame depth</em> and <em>slot index</em>. The frame depth indicates in which frame the variable is found: the current frame has depth 0, its block's parent frame has depth 1, and so on. The slot index is an index within that frame.</p>
 <p>Slots should be initialized with some indication they are not yet defined. The variable can be defined with SETN only if it hasn't been defined yet, and can be accessed with LOCO or LOCU or modified with SETU or SETM only if it <em>has</em> been defined.</p>
-<h3 id="variable-references-arrm-locm-setn-setu-setm-seth"><a class="header" href="#variable-references-arrm-locm-setn-setu-setm-seth">Variable references: ARRM LOCM SETN SETU SETM SETH</a></h3>
+<h3 id="variable-references-arrm-locm-setn-setu-setm-seth-vfym"><a class="header" href="#variable-references-arrm-locm-setn-setu-setm-seth-vfym">Variable references: ARRM LOCM SETN SETU SETM SETH VFYM</a></h3>
 <p>A <em>variable reference</em> indicates a particular frame slot in a way that's independent of the execution context. For example, it could be a pointer to the slot, or a reference to the frame along with the index of the slot. <strong>LOCM</strong> pushes a variable reference to the stack.</p>
 <p>A <em>reference list</em> is a list of variable references or reference lists. It's created with the <strong>ARRM</strong> instruction. In the Javascript VM there's no difference between a reference list and an ordinary BQN list other than the contents.</p>
 <p>The <strong>SETN</strong>, <strong>SETU</strong>, and <strong>SETM</strong> instructions set a value for a reference. If the reference is to a variable, they simply set its value. For a reference list, the value needs to be destructured. It must be a list of the same length, and each reference in the reference list is set to the corresponding element of the value list.</p>
 <p><strong>SETM</strong> additionally needs to get the current value of a reference. For a variable reference this is its current value (with an error if it's not defined yet); for a reference list it's a list of the values of each reference in the list.</p>
-<p><strong>SETH</strong> is a modification of SETN for use in header destructuring. It differs in that it doesn't place its result on the stack (making it more like SETN followed by POPS), and that if the assignment fails because the reference and value don't conform then it moves on to the next eligible body in the block rather than giving an error. It also accepts constant matchers produced by VFYM as references, which fail if they don't match the corresponding value.</p>
+<p><strong>SETH</strong> is a modification of SETN for use in header destructuring. It differs in that it doesn't place its result on the stack (making it more like SETN followed by POPS), and that if the assignment fails because the reference and value don't conform then it moves on to the next eligible body in the block rather than giving an error. <strong>VFYM</strong> converts a BQN value <code><span class='Value'>c</span></code> to a special reference: assigning a value <code><span class='Value'>v</span></code> to it should check if <code><span class='Value'>v</span><span class='Function'>≡</span><span class='Value'>c</span></code> but do no assignment. Only SETH needs to accept these references, and it should treat non-matching values as failing assignment.</p>
 <h3 id="namespaces-fldo-fldm-nspm-retd"><a class="header" href="#namespaces-fldo-fldm-nspm-retd">Namespaces: FLDO FLDM NSPM RETD</a></h3>
 <p>A <em>namespace</em> is the collection of variables in a particular scope, along with an association mapping some exported <em>symbols</em> (case- and underscore-normalized strings) to a subset of these. It can be represented using a frame for the variables, plus the variable name list and mask of exported variables from that block's properties in the bytecode. <strong>RETD</strong> finishes executing the block and returns the namespace for that execution.</p>
 <p>The variable name list is split into a program-level list of names and a list of indices into these names: within-program field accesses can be done with the indices only while cross-program ones must use names. One way to check whether an access is cross-program is to compare the accessor's program-level name list with the one for the accessed namespace as references or pointers. Then a lookup should be performed as appropriate. A persistent lookup table is needed to make this efficient.</p>
diff --git a/docs/index.html b/docs/index.html
index a801a62e..ed83da99 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -10,7 +10,7 @@
 <p><a href="doc/index.html">documentation</a> • <a href="spec/index.html">specification</a> • <a href="tutorial/index.html">tutorials</a> • <a href="implementation/index.html">implementation</a></p>
 </center>
 
-<p><em>Try it online below, on <a href="https://mlochbaum.github.io/BQN/try.html">this page</a>, or <a href="#where-can-i-find-bqn-users">in our chat</a>. Offline options <a href="running.html">here</a>.</em></p>
+<p><em>Try it online below, on <a href="https://mlochbaum.github.io/BQN/try.html">this page</a>, or <a href="#where-can-i-find-bqn-users">in our chat</a>. Use <a href="https://github.com/dzaima/CBQN">CBQN</a> offline; details <a href="running.html">here</a>.</em></p>
 <div class='cont'>
   <div class='kb'></div>
   <div class='rel'>
diff --git a/docs/running.html b/docs/running.html
index 4d1aac71..8ed679f2 100644
--- a/docs/running.html
+++ b/docs/running.html
@@ -5,11 +5,10 @@
 </head>
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="index.html">BQN</a></div>
 <h1 id="how-to-run-bqn"><a class="header" href="#how-to-run-bqn">How to run BQN</a></h1>
-<p>We are currently working quickly to make <a href="https://github.com/dzaima/CBQN">CBQN</a> into the definitive offline implementation. Compilation speed (self-hosted) is good, the only significant core language feature missing is block headers and multiple bodies, and the essential system functions are there. Unless you need to start heavy number crunching right away, I recommend that you use CBQN and make system function or performance requests on Github or the BQN forums.</p>
-<p>A lot of development to date has been done in dzaima/BQN and uses features (mainly headers) that aren't in CBQN yet. Scripts in this repository use <code><span class='Value'>bqn</span></code> in the <code><span class='Comment'>#!</span></code> line if self-hosted or dzaima/BQN can run them, and <code><span class='Value'>dbqn</span></code> if only dzaima/BQN works.</p>
+<p><a href="https://github.com/dzaima/CBQN">CBQN</a> is now the primary offline implementation. However, many scripts have been written for dzaima/BQN and they're not all transferred over yet. Scripts in this repository use <code><span class='Value'>bqn</span></code> in the <code><span class='Comment'>#!</span></code> line if self-hosted or dzaima/BQN can run them, and <code><span class='Value'>dbqn</span></code> if only dzaima/BQN works.</p>
 <h3 id="self-hosted-bqn"><a class="header" href="#self-hosted-bqn">Self-hosted BQN</a></h3>
 <p>See the subsections below for instructions on specific implementations.</p>
-<p>This version of BQN is <a href="implementation/index.html">implemented</a> mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows <a href="doc/embed.html">embedding</a>, where programs in the host language can include BQN code. It fully supports all primitives except a few cases of structural Under (<code><span class='Modifier2'>⌾</span></code>), but is still missing some advanced features: block headers and multiple body syntax, derived 1-modifiers, and block returns.</p>
+<p>This version of BQN is <a href="implementation/index.html">implemented</a> mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows <a href="doc/embed.html">embedding</a>, where programs in the host language can include BQN code. It fully supports all primitives except a few cases of structural Under (<code><span class='Modifier2'>⌾</span></code>), and is missing some minor syntax features such as derived 1-modifiers and block returns.</p>
 <p>Support in the following languages has been implemented:</p>
 <ul>
 <li>Javascript, in this repository. Slow (compiles at ~5kB/s) but usable.</li>
diff --git a/docs/try.html b/docs/try.html
index da053e98..e638496e 100644
--- a/docs/try.html
+++ b/docs/try.html
@@ -32,7 +32,6 @@
     <ul>
       <li>You can type special characters with a back<em>slash</em> prefix (customize at the right), as shown by hovering over the character bar above. Documentation links for primitives are <a href="doc/primitive.html#functions">here</a>.</li>
       <li>Any modifier with enter will execute, not just shift. The code window is vertically resizeable.</li>
-      <li>Support for function headers and multiple bodies is missing.</li>
     </ul>
   </p>
 
diff --git a/implementation/vm.md b/implementation/vm.md
index 470df0ad..df828e69 100644
--- a/implementation/vm.md
+++ b/implementation/vm.md
@@ -78,7 +78,7 @@ The following instructions are defined by dzaima/BQN. The ones emitted by the se
 | 20 | OP2H |      |      |          | Bind right operand to 2-modifier
 | 21 | LOCO |  X   |      | `D`, `I` | Push local variable `I` from `D` frames up
 | 22 | LOCM |  X   |      | `D`, `I` | Push local variable reference `I` from `D` frames up
-| 23 | VFYM |      |      |          | Convert to matcher (for header tests)
+| 23 | VFYM |  X   |      |          | Convert constant to matcher (for headers)
 | 24 | SETH |  X   |  11  |          | Test and set header
 | 25 | RETN |  X   |      |          | Returns top of stack
 | 26 | FLDO |  NS  |      | `I`      | Read field `I` from namespace
@@ -108,6 +108,7 @@ Stack effects for most instructions are given below. Instructions 16, 17, and 19
 | 20 | OP2H | `𝕘 𝕣 → (_𝕣_ 𝕘)`       |
 | 21 | LOCO | `→ x`                 | Local variable value
 | 22 | LOCM | `→ r`                 | Local variable reference
+| 23 | VFYM | `c → r`               | Constant to match reference
 | 25 | RETN | `x → x`               | Returns from current block
 | 26 | FLDO | `n → n.i`             |
 | 28 | NSPM | `r → s`               | Reference `s` gets field `i` and puts in `r`
@@ -127,7 +128,7 @@ Local variables are manipulated with the **LOCO** (or **LOCU**) and **LOCM** ins
 
 Slots should be initialized with some indication they are not yet defined. The variable can be defined with SETN only if it hasn't been defined yet, and can be accessed with LOCO or LOCU or modified with SETU or SETM only if it *has* been defined.
 
-### Variable references: ARRM LOCM SETN SETU SETM SETH
+### Variable references: ARRM LOCM SETN SETU SETM SETH VFYM
 
 A *variable reference* indicates a particular frame slot in a way that's independent of the execution context. For example, it could be a pointer to the slot, or a reference to the frame along with the index of the slot. **LOCM** pushes a variable reference to the stack.
 
@@ -137,7 +138,7 @@ The **SETN**, **SETU**, and **SETM** instructions set a value for a reference. I
 
 **SETM** additionally needs to get the current value of a reference. For a variable reference this is its current value (with an error if it's not defined yet); for a reference list it's a list of the values of each reference in the list.
 
-**SETH** is a modification of SETN for use in header destructuring. It differs in that it doesn't place its result on the stack (making it more like SETN followed by POPS), and that if the assignment fails because the reference and value don't conform then it moves on to the next eligible body in the block rather than giving an error. It also accepts constant matchers produced by VFYM as references, which fail if they don't match the corresponding value.
+**SETH** is a modification of SETN for use in header destructuring. It differs in that it doesn't place its result on the stack (making it more like SETN followed by POPS), and that if the assignment fails because the reference and value don't conform then it moves on to the next eligible body in the block rather than giving an error. **VFYM** converts a BQN value `c` to a special reference: assigning a value `v` to it should check if `v≡c` but do no assignment. Only SETH needs to accept these references, and it should treat non-matching values as failing assignment.
 
 ### Namespaces: FLDO FLDM NSPM RETD
 
diff --git a/running.md b/running.md
index 638bc800..4d28355e 100644
--- a/running.md
+++ b/running.md
@@ -2,15 +2,13 @@
 
 # How to run BQN
 
-We are currently working quickly to make [CBQN](https://github.com/dzaima/CBQN) into the definitive offline implementation. Compilation speed (self-hosted) is good, the only significant core language feature missing is block headers and multiple bodies, and the essential system functions are there. Unless you need to start heavy number crunching right away, I recommend that you use CBQN and make system function or performance requests on Github or the BQN forums.
-
-A lot of development to date has been done in dzaima/BQN and uses features (mainly headers) that aren't in CBQN yet. Scripts in this repository use `bqn` in the `#!` line if self-hosted or dzaima/BQN can run them, and `dbqn` if only dzaima/BQN works.
+[CBQN](https://github.com/dzaima/CBQN) is now the primary offline implementation. However, many scripts have been written for dzaima/BQN and they're not all transferred over yet. Scripts in this repository use `bqn` in the `#!` line if self-hosted or dzaima/BQN can run them, and `dbqn` if only dzaima/BQN works.
 
 ### Self-hosted BQN
 
 See the subsections below for instructions on specific implementations.
 
-This version of BQN is [implemented](implementation/README.md) mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows [embedding](doc/embed.md), where programs in the host language can include BQN code. It fully supports all primitives except a few cases of structural Under (`⌾`), but is still missing some advanced features: block headers and multiple body syntax, derived 1-modifiers, and block returns.
+This version of BQN is [implemented](implementation/README.md) mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows [embedding](doc/embed.md), where programs in the host language can include BQN code. It fully supports all primitives except a few cases of structural Under (`⌾`), and is missing some minor syntax features such as derived 1-modifiers and block returns.
 
 Support in the following languages has been implemented:
 - Javascript, in this repository. Slow (compiles at ~5kB/s) but usable.
-- 
cgit v1.2.3