Author: Colby Russell (https://colbyrussell.com)
Date: 2021 February 10

An assembler
============

Our aim is to describe an "assembler" for the RSC object file format used in
Project Oberon 2013 <:http://projectoberon.com>.  The Oberon system itself
includes no assembler--Wirth's compiler is single-pass, and it writes object
files directly.  However, the system does include ORTool, a utility for
inspecting the binary object files.  Adapting its output format, while less
than ideal for authoring purposes, would give us something that fits our needs
well enough and spares us the burden of designing our own input language.

As a concrete example, we want to be able to ingest some input like this,
which has been generated from the binary of a simple "hello, world"-style
program module:

  <script> (Fig. 1) - sample output from an ORTool-like utility

    Hello 6C6D65B7   1   192
    imports:
            Texts 0B9E9984
            Fonts F4C9F557
            Files 73F5D686
            Oberon A89CCEE2
            Display 4C08D3EA
            Viewers 25ABF199
    type descriptors
    data    40
    strings
            "Hello"
    code
       0	4EE90004	SP <: SUB SP 4
       1	AFE00000	LK #> STR SP 0
       2	8D000002	SB <: LDR R0 2
       3	40D80000	R0 <: ADD SB 0
       4	8D100002	SB <: LDR R1 2
       5	41D80005	R1 <: ADD SB 5
       6	F7117006	LK <: BJP 1142790
       7	8D000003	SB <: LDR R0 3
       8	40D80000	R0 <: ADD SB 0
       9	8D100002	SB <: LDR R1 2
      10	41D80005	R1 <: ADD SB 5
      11	8D000002	SB <: LDR R0 2
      12	42D80028	R2 <: ADD SB 40
      13	43000006	R3 <: MOV 6
      14	F711D008	LK <: BJP 1167368
      15	8D400004	SB <: LDR R4 4
      16	80D0000D	R0 <: LDR SB 13
      17	8D000002	SB <: LDR R0 2
      18	81D00000	R1 <: LDR SB 0
      19	F710E005	LK <: BJP 1105925
      20	8FE00000	LK <: LDR SP 0
      21	4EE80004	SP <: ADD SP 4
      22	C700000F	PC <: BJP LK
    commands:
    entries
         0
    pointer refs
         0
         4
        36
        24
    fixP =       19
    fixD =       17
    fixT =        0
    entry =        0

  </script>

Our assembler should be able to take input in textual format like the sample
text shown in Figure 1 and generate a bit-for-bit identical copy of the
original binary for which the ORTool-like utility produced the example output.
We say that we rely on an ORTool-*like* utility, because while the ORTool
output is almost rich enough for this purpose, i.e., containing enough
semantic content to allow us to do the job, there are still some abiguities
that would hamper our efforts.  It is on this basis that the ORTool output
"language" has been adapted to incorporate the necessary changes to allow it
to be used as the input format for our assembly tool.

Specifically, to achieve this, we must take some liberties with the contents
of the strings section.  To emphasize: these changes are crucial for the
roundtrippability between binary to text and back.

(NB: And although not strictly a necessary change, the "assembly" instructions
in the preceding sample do not match the exact format that ORTool uses, but it
should be reasonably straightforward to grasp for anyone already familiar with
the ORTool output; this is a change that has been made purely as a matter of
taste and convenience.)

What does the raw content of an RSC binary even look like?  Here's a hex dump
of Hello.rsc corresponding to the binary described in the preceding input
language sample:

  <script> (Fig. 2) - output from the "xxd" utility

    00000000: 4865 6c6c 6f00 b765 6d6c 01c0 0000 0054  Hello..eml.....T
    00000010: 6578 7473 0084 999e 0b46 6f6e 7473 0057  exts.....Fonts.W
    00000020: f5c9 f446 696c 6573 0086 d6f5 734f 6265  ...Files....sObe
    00000030: 726f 6e00 e2ce 9ca8 4469 7370 6c61 7900  ron.....Display.
    00000040: ead3 084c 5669 6577 6572 7300 99f1 ab25  ...LViewers....%
    00000050: 0000 0000 0028 0000 0008 0000 0048 656c  .....(.......Hel
    00000060: 6c6f 0000 0017 0000 0004 00e9 4e00 00e0  lo..........N...
    00000070: af02 0000 8d00 00d8 4002 0010 8d05 00d8  ........@.......
    00000080: 4106 7011 f703 0000 8d00 00d8 4002 0010  A.p.........@...
    00000090: 8d05 00d8 4102 0000 8d28 00d8 4206 0000  ....A....(..B...
    000000a0: 4308 d011 f704 0040 8d0d 00d0 8002 0000  C......@........
    000000b0: 8d00 00d0 8105 e010 f700 00e0 8f04 00e8  ................
    000000c0: 4e0f 0000 c700 0100 0000 0000 0000 0000  N...............
    000000d0: 0000 0400 0000 2400 0000 1800 0000 ffff  ......$.........
    000000e0: ffff 1300 0000 1100 0000 0000 0000 0000  ................
    000000f0: 0000 4f                                  ..O

  </script>

Such a binary was obtained by compiling the following module source using the
Oberon system compiler:

  <script> (Fig. 3) - source code for an Oberon module that prints "Hello"

    MODULE Hello;
    IMPORT Texts, Oberon;
    VAR writer: Texts.Writer;
    BEGIN
            Texts.OpenWriter(writer);
            Texts.WriteString(writer, "Hello");
            Texts.Append(Oberon.Log, writer.buf);
    END Hello.

  </script>

Let's give a detailed breakdown of the format in a way that exhibits a degree
of rigor and completeness that is not possible by merely inspecting a single
binary.


Formal description
==================

A brief aside: to accommodate a broad audience, we should describe the
algorithms here in a neutral and accessible notation.  So what notation is
that, exactly?  The classic answer to this problem would be "use ALGOL", but
if we chose that route for the purity of its thrust, we will have failed in
our goal--ALGOL isn't altogether used much even for academic purposes today
and likely to cause more friction than it's worth.

For that reason the example code will be presented in an ad hoc notation that
is expected to be comprehensible to any moderately experienced programmer--
although those most comfortable working with languages from the C syntactic
family tree will find bias in their favor, since we'll go with a curly brace
notation.  Some will notice that our fictional language's syntax bears
resemblance to JS, and indeed widespread awareness and use of that
language--even if such use is unenthusiastic by disinterested parties under
duress--is a factor that has informed some of the choices made here.

This document attempts to eschew with exotic syntactic constructs that may
prove overly difficult to follow, considering its purpose is clarity;
semantics for the parts of the text appearing in the code blocks should be
self-evident, including for example the "include" declarations and the implied
linking model, and it should be possible to infer modules' file names on
sight--we waste no energy or space labeling them.  The consequences of this
omission are diminished by the fact that blocks of code, even adjacent ones,
are distinguishable from one another because we choose to present them
bracketed by the HTML-like `script` tags (already used for the preceding
Oberon snippet), denoting individual modules; it's expected that this
presentation is simple and straightforward enough to lend itself to immediate
understanding even for readers who've never encountered the convention before.

From this point onwards, this document contains minimal commentary about the
structure of the object file--allowing the pseudocode speak for itself.
Consider the primary module `RSCListingReader` the heart of a hypothetical
assembler utility.  Let's get right into it:

  <script>

    /* External modules referenced by this one */
    include: "RSCAssembler.src"
    include: "RSCObject.src"
    include: "TextGlider.src"
    include: "Tokenizer.src"

    class RSCListingReader {
      static convert(system, path) {
        where:
          system: typeof(SYSTEM)
          path: typeof(string)
        convert => typeof(list$byte)

        let instance = new RSCListingReader;

        // Assume `typeof(SYSTEM)` above just means "sufficiently powerful"
        let inputText = system.read(path);
        let objectCodeIR = instance.parse(inputText);

        system.observe(objectCodeIR);
        return objectCodeIR.getBytes();
      }

      constructor() {
        this._scanner = null;
      }

      parse(text) {
        this._glider = new TextGlider(text);

        let ir = new RSCObject;

        // RSCObject *should* dynamically compute/validate the key and size
        // fields in a "real" assembler implementation, but we'll opt not to.
        ir.name = this._expect(Tokenizer.MODULE_NAME);

        Tokenizer.align(this._glider);
        ir.key = this._expectValue(Tokenizer.HEX_LITERAL);

        Tokenizer.align(this._glider);
        ir.kind = this._expectValue(Tokenizer.DECIMAL_LITERAL);
        if (ir.kind != 0 && ir.kind != 1) {
          this._eject(); // XXX
        }

        Tokenizer.align(this._glider);
        ir.size = this._expectValue(Tokenizer.DECIMAL_LITERAL);

        this._expect(Tokenizer.LINE_TERMINATOR);

        this._expect(Tokenizer.IMPORTS);
        this._expect(Tokenizer.COLON);
        this._expect(Tokenizer.LINE_TERMINATOR);
        this._parseImportRecords(ir);

        this._expect(Tokenizer.TYPE);
        this._expect(Tokenizer.DESCRIPTORS);
        this._expect(Tokenizer.LINE_TERMINATOR);
        this._parseTypeDescriptors(ir);

        this._expect(Tokenizer.DATA)
        Tokenizer.align(this._glider);
        ir.useData(this._expectValue(Tokenizer.DECIMAL_LITERAL));
        this._expect(Tokenizer.LINE_TERMINATOR);

        this._expect(Tokenizer.STRINGS);
        this._expect(Tokenizer.LINE_TERMINATOR);
        this._parseStringRecords(ir);

        this._expect(Tokenizer.CODE);
        this._expect(Tokenizer.LINE_TERMINATOR);
        this._parseCodeSection(ir);

        this._expect(Tokenizer.COMMANDS);
        this._expect(Tokenizer.COLON);
        this._expect(Tokenizer.LINE_TERMINATOR);
        this._parseCommandRecords(ir);

        this._expect(Tokenizer.ENTRIES);
        this._expect(Tokenizer.LINE_TERMINATOR);
        ir.useEntries(this._parseValuesList());

        this._expect(Tokenizer.POINTER);
        this._expect(Tokenizer.REFS);
        this._expect(Tokenizer.LINE_TERMINATOR);
        ir.useRefs(this._parseValuesList());

        ir.useFixorgP(this._parseDefinition(Tokenizer.FIXP));
        ir.useFixorgD(this._parseDefinition(Tokenizer.FIXD));
        ir.useFixorgT(this._parseDefinition(Tokenizer.FIXT));
        ir.useEntry(this._parseDefinition(Tokenizer.ENTRY));

        return ir;
      }

      _parseDefinition(which) {
        this._expect(which);
        Tokenizer.align(this._glider);
        this._expect(Tokenizer.EQUALS);
        Tokenizer.align(this._glider);
        let value = this._expectValue(Tokenizer.DECIMAL_LITERAL);
        this._expect(Tokenizer.LINE_TERMINATOR);
        return value;
      }

      _expectValue(want, optional = false) {
        let words = this._expect(want, optional);
        if (words != null) {
          assert: { words.length == 1 }
          return words[0];
        }
        return null;
      }

      _expect(want, optional = false) {
        where:
          want: typeof(int32)
          option: typeof(boolean)
        _expect => typeof(list$uint32)

        let result = null;

        if (want < Tokenizer.KEYWORD_GROUP_BOUNDARY) {
          let value = null;
          switch (want) {
            case Tokenizer.MODULE_NAME:
            case Tokenizer.PROCEDURE_NAME:
              result = Tokenizer.readIdentifier(this._glider);
            break;
            case Tokenizer.RECORD_MARKER:
              result = Tokenizer.readSpaceSequence(this._glider);
            break;
            case Tokenizer.STRING_ATOM:
              result = Tokenizer.readString(this._glider);
            break;

            case Tokenizer.DECIMAL_LITERAL:
              value = Tokenizer.readDecimal(this._glider);
            break;
            case Tokenizer.HEX_LITERAL:
              value = Tokenizer.readHex(this._glider);
            break;
            case Tokenizer.LINE_TERMINATOR:
              value = Tokenizer.readLineTerminator(this._glider);
            break;

            case Tokenizer.TAB:
            case Tokenizer.COLON:
            case Tokenizer.EQUALS:
              value = Tokenizer.readASCII(this._glider, want);
            break;

            default:
              this._eject(want);
            break;
          }

          if (value != null) {
            result = [ value ];
          }
        } else {
          let content = Tokenizer.getTokenText(want);
          result = Tokenizer.readTokenByText(this._glider, content);
        }

        if (result == null && !optional) {
          this._eject(want);
        }

        return result;
      }

      _eject(want = null) {
        throw new Error; // XXX (use `want` if possible)
      }

      _parseImportRecords(ir) {
        let item = ir.imports;
        let sequence = this._expect(Tokenizer.RECORD_MARKER);
        while (this._hasNextRecord(sequence)) {
          let nameBytes = this._expect(Tokenizer.MODULE_NAME);
          Tokenizer.align(this._glider);
          let key = this._expectValue(Tokenizer.HEX_LITERAL);
          this._expect(Tokenizer.LINE_TERMINATOR);

          item = RSCObject.describeImport(nameBytes, key, item);

          sequence = this._expect(Tokenizer.RECORD_MARKER);
        }

        ir.sealSection(item);
      }

      _hasNextRecord(sequence) {
        return sequence.length > 0;
      }

      _parseTypeDescriptors(ir) {
        let item = ir.types;
        let value = this._expectValue(Tokenizer.HEX_LITERAL, true);
        let count = 0;
        while (value != null) {
          ++count;
          this._expect(Tokenizer.LINE_TERMINATOR);

          item = RSCObject.describeTypeDescriptor(value, item);

          value = this._expectValue(Tokenizer.HEX_LITERAL, true);
        }

        ir.types.load = RSCObject.makeBytesFromWord(count * 4);
      }

      _parseStringRecords(ir) {
        let item = ir.strings;
        let size = 0;
        let sequence = this._expect(Tokenizer.RECORD_MARKER);
        while (this._hasNextRecord(sequence)) {
          let bytes = this._expect(Tokenizer.STRING_ATOM);
          let stop = this._expect(Tokenizer.LINE_TERMINATOR, true);

          item = ir.registerString(bytes, item);

          sequence = this._expect(Tokenizer.RECORD_MARKER);
        }

        ir.sealStrings();
      }

      _parseCodeSection(ir) {
        let instructions = [];
        let assembler = new RSCAssembler;

        Tokenizer.align(this._glider, true);
        let label = this._expectValue(Tokenizer.DECIMAL_LITERAL, true);
        while (label != null) {
          this._expect(Tokenizer.TAB);
          let encoding = this._expectValue(Tokenizer.HEX_LITERAL);
          this._expect(Tokenizer.TAB);

          encoding = assembler.validateInstruction(encoding, this._glider);
          this._expect(Tokenizer.LINE_TERMINATOR);

          instructions.push(encoding);

          Tokenizer.align(this._glider, true);
          label = this._expectValue(Tokenizer.DECIMAL_LITERAL, true);
        }

        ir.useCode(instructions);
      }

      _parseCommandRecords(ir) {
        let item = ir.commands;
        let sequence = this._expect(Tokenizer.RECORD_MARKER);
        while (this._hasNextRecord(sequence)) {
          let nameBytes = this._expect(Tokenizer.PROCEDURE_NAME);
          Tokenizer.align(this._glider);
          let address = this._expectValue(Tokenizer.DECIMAL_LITERAL);
          this._expect(Tokenizer.LINE_TERMINATOR);

          item = RSCObject.describeCommand(nameBytes, address, item);

          sequence = this._expect(Tokenizer.RECORD_MARKER);
        }

        ir.sealSection(item);
      }

      _parseValuesList() {
        let result = [];

        let sequence = this._expect(Tokenizer.RECORD_MARKER);
        while (this._hasNextRecord(sequence)) {
          let value = this._expectValue(Tokenizer.DECIMAL_LITERAL);
          this._expect(Tokenizer.LINE_TERMINATOR);

          result.push(value);

          sequence = this._expect(Tokenizer.RECORD_MARKER);
        }

        return result;
      }
    }

  </script>

  <script>

    class TextGlider {
      constructor(content) {
        this.content = content;
        this.position = 0;

        this.tip = null;
        this.reseat(0);
      }

      advance() {
        this.reseat(this.position + 1);
      }

      reseat(where) {
        this.position = where;
        if (this.position < this.content.length) {
          this.tip = this.content.charCodeAt(this.position);
        } else {
          this.tip = null;
        }
      }
    }

  </script>

  <script>

    class Tokenizer {
      static align(glider, optional = false) {
        let sequence = Tokenizer.readSpaceSequence(glider);
        if (sequence.length < 1 && !optional) {
          throw new Error; // XXX
        }
      }

      static readSpaceSequence(glider) {
        let sequence = [];

        const ASCII_SPACE = 0x20;
        while (glider.tip == ASCII_SPACE) {
          sequence.push(ASCII_SPACE);
          glider.advance();
        }

        return sequence;
      }

      static readIdentifier(glider) {
        let start = glider.position;

        let bytes = [];
        while (Tokenizer.isLetter(glider.tip)) {
          bytes.push(glider.tip);
          glider.advance();
        }
        if (bytes.length) {
          return bytes;
        }

        glider.reseat(start);
        return null;
      }

      static isLetter(code) {
        const UPPER_A = 0x41;
        const UPPER_Z = 0x5A;
        const LOWER_A = 0x61;
        const LOWER_Z = 0x7A;
        if (code != null) {
          return (
            (UPPER_A <= code && code <= UPPER_Z) ||
            (LOWER_A <= code && code <= LOWER_Z)
          );
        }
        return false;
      }

      static isDigit(code) {
        const ASCII_0 = 0x30;
        const ASCII_9 = 0x39;
        return (code != null && ASCII_0 <= code && code <= ASCII_9);
      }

      static isHex(code) {
        const ASCII_A = 0x41;
        const ASCII_F = 0x46;
        return (
          (code != null && ASCII_A <= code && code <= ASCII_F) ||
          Tokenizer.isDigit(code)
        );
      }

      static readHex(glider) {
        let start = glider.position;

        let value = 0;
        while (glider.tip != null && Tokenizer.isHex(glider.tip)) {
          let units = parseInt(glider.content.charAt(glider.position), 16);
          value = ((value << 4) >>> 0) + units;
          glider.advance();

          if (glider.position - start == 8) {
            if (glider.tip == null || !Tokenizer.isHex(glider.tip)) {
              return value;
            }
            break;
          }
        }

        glider.reseat(start);
        return null;
      }

      static readDecimal(glider) {
        let start = glider.position;

        let value = 0;
        while (glider.tip != null && Tokenizer.isDigit(glider.tip)) {
          let units = parseInt(glider.content.charAt(glider.position), 16);
          value = (value * 10) + units;
          glider.advance();
        }
        if (glider.position > start) {
          return value;
        }

        glider.reseat(start);
        return null;
      }

      static getTokenText(want) {
        switch (want) {
          case Tokenizer.IMPORTS: return "imports";
          case Tokenizer.TYPE: return "type";
          case Tokenizer.DESCRIPTORS: return "descriptors";
          case Tokenizer.DATA: return "data";
          case Tokenizer.STRINGS: return "strings";
          case Tokenizer.CODE: return "code";
          case Tokenizer.COMMANDS: return "commands";
          case Tokenizer.ENTRIES: return "entries";
          case Tokenizer.POINTER: return "pointer";
          case Tokenizer.REFS: return "refs";
          case Tokenizer.FIXP: return "fixP";
          case Tokenizer.FIXD: return "fixD";
          case Tokenizer.FIXT: return "fixT";
          case Tokenizer.ENTRY: return "entry";
        }
        return null; // internal error
      }

      static readTokenByText(glider, content) {
        let start = glider.position;

        const ASCII_SPACE = 0x20;
        while (glider.tip == ASCII_SPACE) {
          glider.advance();
        }

        let bytes = [];
        for (let i = 0, n = content.length; i < n; ++i) {
          if (content.charCodeAt(i) == glider.tip) {
            bytes.push(glider.tip);
            glider.advance();
            if (i + 1 == n) {
              return bytes;
            }
          } else {
            break;
          }
        }

        glider.reseat(start);
        return null;
      }

      static readLineTerminator(glider) {
        // TODO support other platform conventions
        const ASCII_LINE_FEED = 0x0A;
        return Tokenizer.readASCII(glider, ASCII_LINE_FEED);
      }

      static readASCII(glider, value) {
        let start = glider.position;

        if (glider.tip == value) {
          glider.advance();
          return value;
        }

        return null;
      }

      static readAssemblyToken(glider) {
        let start = glider.position;

        const ASCII_LINE_FEED = 0x0A;
        const ASCII_SPACE = 0x20;

        // skip whitespace
        while (glider.tip == ASCII_SPACE) {
          glider.advance();
        }

        let content = "";
        while (glider.tip != ASCII_LINE_FEED && glider.tip != ASCII_SPACE) {
          if (glider.tip != null) {
            content += String.fromCharCode(glider.tip);
            glider.advance();
          } else {
            break;
          }
        }

        return Tokenizer.getTokenType(content);
      }

      static readString(glider) {
        let start = glider.position;
        let bytes = [];

        const ASCII_QUOTE = 0x22;
        const ASCII_PESO = 0x24;

        const PRINT_START = 0x20;
        const PRINT_STOP = 0x7F;

        if (glider.tip == ASCII_QUOTE) {
          glider.advance();
          while (glider.tip != null) {
            if (glider.tip < PRINT_START || glider.tip >= PRINT_STOP) {
              break;
            } else if (glider.tip == ASCII_QUOTE) {
              bytes.push(0);
              glider.advance();
              return bytes;
            }

            bytes.push(glider.tip);
            glider.advance();
          }
        } else if (glider.tip == ASCII_PESO) {
          glider.advance();
          while (glider.tip != null && glider.tip != ASCII_PESO) {
            let value = Tokenizer.readHex(glider);
            if (value) {
              bites.push(value);
              if (glider.tip == ASCII_PESO) {
                glider.advance();
                return bytes;
              } else {
                Tokenizer.align(glider);
              }
            } else {
              break;
            }
          }
        }

        glider.reseat(start);
        return null;
      }

      static getTokenType(content) {
        let glider = new TextGlider(content)
        let value = Tokenizer.readDecimal(glider);
        if (value != null && glider.position == content.length) {
          return Tokenizer.DECIMAL_LITERAL;
        }

        switch (content) {
          case "FL": return Tokenizer.FL;
          case "HH": return Tokenizer.HH;
          case "PC": return Tokenizer.PC;

          case "R0": return Tokenizer.R0;
          case "R1": return Tokenizer.R1;
          case "R2": return Tokenizer.R2;
          case "R3": return Tokenizer.R3;
          case "R4": return Tokenizer.R4;
          case "R5": return Tokenizer.R5;
          case "R6": return Tokenizer.R6;
          case "R7": return Tokenizer.R7;
          case "R8": return Tokenizer.R8;
          case "R9": return Tokenizer.R9;
          case "RA": return Tokenizer.RA;
          case "RB": return Tokenizer.RB;
          case "RB": return Tokenizer.RB;
          case "RC": return Tokenizer.RC;
          case "RD": return Tokenizer.RD;
          case "RE": return Tokenizer.RE;
          case "RF": return Tokenizer.RF;
          case "MT": return Tokenizer.RC;
          case "SB": return Tokenizer.RD;
          case "SP": return Tokenizer.RE;
          case "LK": return Tokenizer.RF;

          case "MOV": return Tokenizer.MOV;
          case "LSL": return Tokenizer.LSL;
          case "ASR": return Tokenizer.ASR;
          case "ROR": return Tokenizer.ROR;
          case "AND": return Tokenizer.AND;
          case "ANN": return Tokenizer.ANN;
          case "IOR": return Tokenizer.IOR;
          case "XOR": return Tokenizer.XOR;
          case "ADD": return Tokenizer.ADD;
          case "SUB": return Tokenizer.SUB;
          case "MUL": return Tokenizer.MUL;
          case "DIV": return Tokenizer.DIV;
          case "FAD": return Tokenizer.FAD;
          case "FSB": return Tokenizer.FSB;
          case "FML": return Tokenizer.FML;
          case "FDV": return Tokenizer.FDV;

          case "LDR": return Tokenizer.LDR;
          case "LDB": return Tokenizer.LDB;
          case "STR": return Tokenizer.STR;
          case "STB": return Tokenizer.STB;

          case "BMI": return Tokenizer.BMI;
          case "BEQ": return Tokenizer.BEQ;
          case "BCS": return Tokenizer.BCS;
          case "BVS": return Tokenizer.BVS;
          case "BGS": return Tokenizer.BGS;
          case "BLT": return Tokenizer.BLT;
          case "BLE": return Tokenizer.BLE;
          case "BJP": return Tokenizer.BJP;
          case "BPL": return Tokenizer.BPL;
          case "BNE": return Tokenizer.BNE;
          case "BCC": return Tokenizer.BCC;
          case "BVC": return Tokenizer.BVC;
          case "BLO": return Tokenizer.BLO;
          case "BGE": return Tokenizer.BGE;
          case "BGT": return Tokenizer.BGT;
          case "BNO": return Tokenizer.BNO;

          case "::": return Tokenizer.UNIVERSAL_SEPARATOR;
          case "<:": return Tokenizer.REG_FLOW_SEPARATOR;
          case "#>": return Tokenizer.MEM_FLOW_SEPARATOR;
        }

        return Tokenizer.UNKNOWN_TOKEN;
      }
    }

    Tokenizer.DECIMAL_LITERAL = -1;
    Tokenizer.HEX_LITERAL = -2;
    Tokenizer.LINE_TERMINATOR = -3;
    Tokenizer.MODULE_NAME = -4;
    Tokenizer.PROCEDURE_NAME = -5;
    Tokenizer.RECORD_MARKER = -6;
    Tokenizer.STRING_ATOM = -7;

    Tokenizer.TAB = 9;
    Tokenizer.COLON = 58;
    Tokenizer.EQUALS = 61;

    Tokenizer.IMPORTS = Tokenizer.KEYWORD_GROUP_BOUNDARY = 128;
    Tokenizer.TYPE = 129;
    Tokenizer.DESCRIPTORS = 130;
    Tokenizer.DATA = 131;
    Tokenizer.STRINGS = 132;
    Tokenizer.CODE = 133;
    Tokenizer.COMMANDS = 134;
    Tokenizer.ENTRIES = 135;
    Tokenizer.POINTER = 136;
    Tokenizer.REFS = 137;
    Tokenizer.FIXP = 138;
    Tokenizer.FIXD = 139;
    Tokenizer.FIXT = 140;
    Tokenizer.ENTRY = 141;

    Tokenizer.UNKNOWN_TOKEN = 256;

    Tokenizer.FL = 257;
    Tokenizer.HH = 258;
    Tokenizer.PC = 259;
    Tokenizer.R0 = 260;
    Tokenizer.R1 = 261;
    Tokenizer.R2 = 262;
    Tokenizer.R3 = 263;
    Tokenizer.R4 = 264;
    Tokenizer.R5 = 265;
    Tokenizer.R6 = 266;
    Tokenizer.R7 = 267;
    Tokenizer.R8 = 268;
    Tokenizer.R9 = 269;
    Tokenizer.RA = 270;
    Tokenizer.RB = 271;
    Tokenizer.RC = Tokenizer.MT = 272;
    Tokenizer.RD = Tokenizer.SB = 273;
    Tokenizer.RE = Tokenizer.SP = 274;
    Tokenizer.RF = Tokenizer.LK = 275;
    Tokenizer.UNIVERSAL_SEPARATOR = 276;
    Tokenizer.REG_FLOW_SEPARATOR = 277;
    Tokenizer.MEM_FLOW_SEPARATOR = 278;
    Tokenizer.MOV = 279;
    Tokenizer.LSL = 280;
    Tokenizer.ASR = 281;
    Tokenizer.ROR = 282;
    Tokenizer.AND = 283;
    Tokenizer.ANN = 284;
    Tokenizer.IOR = 285;
    Tokenizer.XOR = 286;
    Tokenizer.ADD = 287;
    Tokenizer.SUB = 288;
    Tokenizer.MUL = 289;
    Tokenizer.DIV = 290;
    Tokenizer.FAD = 291;
    Tokenizer.FSB = 292;
    Tokenizer.FML = 293;
    Tokenizer.FDV = 294;
    Tokenizer.LDR = 295;
    Tokenizer.LDB = 296;
    Tokenizer.STR = 297;
    Tokenizer.STB = 298;
    Tokenizer.BMI = 299;
    Tokenizer.BEQ = 300;
    Tokenizer.BCS = 301;
    Tokenizer.BVS = 302;
    Tokenizer.BGS = 303;
    Tokenizer.BLT = 304;
    Tokenizer.BLE = 305;
    Tokenizer.BJP = 306;
    Tokenizer.BPL = 307;
    Tokenizer.BNE = 308;
    Tokenizer.BCC = 309;
    Tokenizer.BVC = 310;
    Tokenizer.BLO = 311;
    Tokenizer.BGE = 312;
    Tokenizer.BGT = 313;
    Tokenizer.BNO = 314;

  </script>

  <script>

    class RSCObject {
      constructor() {
        // Header fields XXX
        this.name = null;
        this.key = null;
        this.kind = null;
        this.size = null;

        this.entry = new RSCObject.Node;
        this.fixorgT = new RSCObject.Node;
        this.fixorgD = new RSCObject.Node;
        this.fixorgP = new RSCObject.Node;
        this.refs = new RSCObject.Node;
        this.entries = new RSCObject.Node;
        this.commands = new RSCObject.Node;
        this.code = new RSCObject.Node;
        this.strings = new RSCObject.Node;
        this.data = new RSCObject.Node;
        this.types = new RSCObject.Node;
        this.imports = new RSCObject.Node;

        this._stringSize = 0;
      }

      static describeImport(nameBytes, key, previous) {
        let item = new RSCObject.Node(nameBytes, RSCObject.NUL);
        item.next = new RSCObject.Node(RSCObject.makeBytesFromWord(key));

        previous.next = item;

        return item.next;
      }

      static makeBytesFromWord(value, bytes = []) {
        assert: { value >= 0 }
        bytes.push((value >>  0) & 0xFF);
        bytes.push((value >>  8) & 0xFF);
        bytes.push((value >> 16) & 0xFF);
        bytes.push((value >> 24) & 0xFF);
        return bytes;
      }

      static describeTypeDescriptor(value, previous) {
        let item = new RSCObject.Node(RSCObject.makeBytesFromWord(value));
        previous.next = item;
        return item;
      }

      useData(value) {
        this.data.load = RSCObject.makeBytesFromWord(value);
      }

      registerString(bytes, previous) {
        let padding = [];
        for (let k = bytes.length % 4; 0 < k && k < 4; ++k) {
          padding.push(0);
        }

        let item = new RSCObject.Node(bytes.concat(padding));
        previous.next = item;

        this._stringSize += item.load.length;

        return item;
      }


      sealStrings() {
        this.strings.load = RSCObject.makeBytesFromWord(this._stringSize);
      }

      useCode(words) {
        let countBytes = RSCObject.makeBytesFromWord(words.length);
        let countNode = new RSCObject.Node(countBytes);
        this.code.next = countNode;

        let instructionBytes = [];
        for (let i = 0, n = words.length; i < n; ++i) {
          RSCObject.makeBytesFromWord(words[i], instructionBytes);
        }
        countNode.next = new RSCObject.Node(instructionBytes);
      }

      static describeCommand(name, address, previous = null) {
        let item = new RSCObject.Node(name, RSCObject.NUL);
        item.next = new RSCObject.Node(RSCObject.makeBytesFromWord(address));

        previous.next = item;

        return item.next;
      }

      sealSection(last) {
        last.next = new RSCObject.Node([ 0 ]);
      }

      useEntries(values) {
        let countBytes = RSCObject.makeBytesFromWord(values.length);
        let countNode = new RSCObject.Node(countBytes);
        this.entries.next = countNode;

        let valuesBytes = [];
        for (let i = 0, n = values.length; i < n; ++i) {
          RSCObject.makeBytesFromWord(values[i], valuesBytes);
        }
        countNode.next = new RSCObject.Node(valuesBytes);
      }

      useRefs(values) {
        let valuesBytes = [];
        for (let i = 0, n = values.length; i < n; ++i) {
          RSCObject.makeBytesFromWord(values[i], valuesBytes);
        }
        let valuesNode = new RSCObject.Node(valuesBytes);
        this.refs.next = valuesNode;

        let terminatorBytes = RSCObject.makeBytesFromWord(0xFFFFFFFF);
        valuesNode.next = new RSCObject.Node(terminatorBytes);
      }

      useFixorgP(value) {
        this.fixorgP.load = RSCObject.makeBytesFromWord(value);
      }

      useFixorgD(value) {
        this.fixorgD.load = RSCObject.makeBytesFromWord(value);
      }

      useFixorgT(value) {
        this.fixorgT.load = RSCObject.makeBytesFromWord(value);
      }

      useEntry(value) {
        this.entry.load = RSCObject.makeBytesFromWord(value);
      }

      getBytes() {
        let heads = [];

        let item = new RSCObject.Node(this.name, RSCObject.NUL);
        heads.push(item);
        item.next = new RSCObject.Node(RSCObject.makeBytesFromWord(this.key));
        item = item.next;
        item.next = new RSCObject.Node([ this.kind ]);
        item = item.next;
        item.next = new RSCObject.Node(RSCObject.makeBytesFromWord(this.size));

        heads.push(this.imports);
        heads.push(this.types);
        heads.push(this.data);
        heads.push(this.strings);
        heads.push(this.code);
        heads.push(this.commands);
        heads.push(this.entries);
        heads.push(this.refs);
        heads.push(this.fixorgP);
        heads.push(this.fixorgD);
        heads.push(this.fixorgT);
        heads.push(this.entry);
        heads.push(new RSCObject.Node([ 0x4F ]));

        let result = [];
        for (let i = 0, n = heads.length; i < n; ++i) {
          let item = heads[i];
          while (item != null) {
            if (item.load) {
              result = result.concat(item.load);
            }
            item = item.next;
          }
        }

        return result;
      }
    }

    RSCObject.NUL = true;
    RSCObject.RAW = false;

    RSCObject.Node = class Node {
      constructor(bytes = null, cap = RSCObject.RAW) {
        this.load = bytes;
        if (cap) {
          bytes.push(0);
        }

        this.next = null;
      }

      connect(previous) {
        let result = this;
        previous.next = sibling;

        return result;
      }
    }

  </script>

  <script>

    include: "Tokenizer.src"

    class RSCAssembler {
      constructor(source = null) {
        this._source = source;
        this.strategy = RSCAssembler.HINTED_OVERRIDES;
      }

      validateInstruction(hinted, source = this._source) {
        if (source != null) {
          let minted = this._parseInstruction(source);
          if (this.strategy == RSCAssembler.MINTED_OVERRIDES ||
              minted == hinted) {
            return minted;
          }
          return hinted;
        }
        return null; // indicates error
      }

      _parseInstruction(source) {
        let atoken = this._parseRegisterName(source, true);
        this._parseSeparator(source);
        let mnemonic = Tokenizer.readAssemblyToken(source);
        if (this._isRegisterMnemonic(mnemonic)) {
          return this._parseRegisterInstruction(source, atoken, mnemonic);
        } else if (this._isMemoryMnemonic(mnemonic)) {
          return this._parseMemoryInstruction(source, atoken, mnemonic);
        } else if (this._isBranchMnemonic(mnemonic)) {
          return this._parseBranchInstruction(source, atoken, mnemonic);
        }
        return null; // indicates error
      }

      _parseRegisterName(source, includePseudos = false) {
        let which = Tokenizer.readAssemblyToken(source);
        if (this._isRegister(which)) {
          return which;
        }
        return null; // indicates error
      }

      _isRegister(token) {
        return (Tokenizer.FL <= token && token <= Tokenizer.RF);
      }

      _isPseudo(token) {
        return (Tokenizer.FL <= token && token <= Tokenizer.PC);
      }

      _parseSeparator(source) {
        let which = Tokenizer.readAssemblyToken(source);
        if (Tokenizer.UNIVERSAL_SEPARATOR <= which &&
            which <= Tokenizer.MEM_FLOW_SEPARATOR) {
          return which;
        }
        return null; // indicates error
      }

      _isRegisterMnemonic(token) {
        return (Tokenizer.MOV <= token && token <= Tokenizer.FDV);
      }

      _parseRegisterInstruction(source, atoken, mnemonic) {
        let primary = this._getRegisterID(atoken);
        if (primary == null) {
          return null; // indicates error
        }

        let op = this._getMnemonicOp(mnemonic);
        if (op == null) {
          return null; // indicates error
        }

        let secondary = 0;
        if (mnemonic != Tokenizer.MOV) {
          secondary = this._getRegisterID(
            this._parseRegisterName(source)
          );
          if (secondary == null) {
            return null; // indicates error
          }
        }

        Tokenizer.align(source);
        let immediate = Tokenizer.readDecimal(source);
        if (immediate != null) {
          if ((immediate & 0xFFFF0000) == immediate && immediate != 0) {
            op += RSCAssembler.U_BIT;
            return this.getRI(op, primary, secondary, (immediate >>> 16));
          } else if ((0xFFFF000|0) <= immediate && immediate < 0) {
            op += RSCAssembler.V_BIT;
            return this.getRI(op, primary, secondary, (immediate >>> 0));
          } else if (0 <= immediate && immediate <= 0xFFFF) {
            return this.getRI(op, primary, secondary, immediate);
          }
        } else {
          let end = this._parseRegisterName(source);
          if (end != null) {
            if (mnemonic == Tokenizer.MOV) {
              if (end == Tokenizer.FL) {
                op += RSCAssembler.U_BIT;
                op += RSCAssembler.V_BIT;
              } else if (end == Tokenizer.HH) {
                op += RSCAssembler.U_BIT;
              } else if (this._isPseudo(end)) {
                return null; // indicates error
              }
              return this.getRR(op, primary, 0, 0);
            }
            let tertiary = this._getRegisterID(end);
            return this.getRR(op, primary, secondary, tertiary);
          }
        }
        return null; // indicates error
      }

      _getRegisterID(token) {
        if (this._isRegister(token) && !this._isPseudo(token)) {
          return Number(token) - Number(Tokenizer.R0);
        }
        return null; // indicates error
      }

      _getMnemonicOp(token) {
        switch (token) {
          case Tokenizer.MOV: return 0x00;
          case Tokenizer.LSL: return 0x01;
          case Tokenizer.ASR: return 0x02;
          case Tokenizer.ROR: return 0x03;

          case Tokenizer.AND: return 0x04;
          case Tokenizer.ANN: return 0x05;
          case Tokenizer.IOR: return 0x06;
          case Tokenizer.XOR: return 0x07;

          case Tokenizer.ADD: return 0x08;
          case Tokenizer.SUB: return 0x09;
          case Tokenizer.MUL: return 0x0A;
          case Tokenizer.DIV: return 0x0B;

          case Tokenizer.FAD: return 0x0C;
          case Tokenizer.FSB: return 0x0D;
          case Tokenizer.FML: return 0x0E;
          case Tokenizer.FDV: return 0x0F;

          case Tokenizer.LDR: return 0x00 * RSCAssembler.U_BIT;
          case Tokenizer.LDB: return 0x00 * RSCAssembler.U_BIT;
          case Tokenizer.STR: return 0x01 * RSCAssembler.U_BIT;
          case Tokenizer.STB: return 0x01 * RSCAssembler.U_BIT;
        }

        return null; // internal error
      }

      _parseMemoryInstruction(source, atoken, mnemonic) {
        let primary = this._getRegisterID(atoken);
        if (primary == null) {
          return null; // indicates error
        }

        let op = this._getMnemonicOp(mnemonic);
        if (op == null) {
          return null; // indicates error
        }

        let secondary = this._getRegisterID(
          this._parseRegisterName(source)
        );
        if (secondary == null) {
          return null; // indicates error
        }

        Tokenizer.align(source);
        let offset = Tokenizer.readDecimal(source);
        if (mnemonic == Tokenizer.LDB || mnemonic == Tokenizer.STB) {
          if (offset > 0xFF) {
            return null; // indicates error
          }
          op += RSCAssembler.V_BIT;
        } else if (offset > 0xFFFFF) {
          return null; // indicates error
        }
        return this.getLS(op, primary, secondary, offset);
      }

      _parseBranchInstruction(source, atoken, mnemonic) {
        if (atoken != Tokenizer.PC && atoken != Tokenizer.LK) {
          return null; // indicates error
        }

        let condition = this._getCondition(mnemonic);
        if (condition == null) {
          return null; // indicates error
        }

        let op = 0;
        if (this._getRegisterID(atoken) != null) {
          op += RSCAssembler.V_BIT;
        }

        Tokenizer.align(source);
        let destination = Tokenizer.readDecimal(source);
        if (destination != null) {
          op += RSCAssembler.U_BIT;
          if ((0xFF000000|0) < destination && destination <= 0x007FFFFF) {
            return this.getBC(op, condition, destination);
          }
        } else {
          let tertiary = this._getRegisterID(
            this._parseRegisterName(source)
          );
          if (tertiary != null) {
            return this.getBC(op, condition, tertiary);
          }
        }

        return null; // indicates error
      }

      _getCondition(token) {
        switch (token) {
          case Tokenizer.BMI: return 0x0;
          case Tokenizer.BEQ: return 0x1;
          case Tokenizer.BCS: return 0x2;
          case Tokenizer.BVS: return 0x3;

          case Tokenizer.BGS: return 0x4;
          case Tokenizer.BLT: return 0x5;
          case Tokenizer.BLE: return 0x6;
          case Tokenizer.BJP: return 0x7;

          case Tokenizer.BPL: return 0x8;
          case Tokenizer.BNE: return 0x9;
          case Tokenizer.BCC: return 0xA;
          case Tokenizer.BVC: return 0xB;

          case Tokenizer.BLO: return 0xC;
          case Tokenizer.BGE: return 0xD;
          case Tokenizer.BGT: return 0xE;
          case Tokenizer.BNO: return 0xF;
        }

        return null; // internal error
      }

      _isMemoryMnemonic(token) {
        return (Tokenizer.LDR <= token && token <= Tokenizer.STB);
      }

      _isBranchMnemonic(token) {
        return (Tokenizer.BMI <= token && token <= Tokenizer.BNO);
      }

      // p q u v ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?
      // +-----+ +-----+ +-----+ +-----+ +---------------------+ +-----+
      // | (4) | |a : 4| |b : 4| |op: 4| |     unused : 12     | |id: 4|
      // +-----+ +-----+ +-----+ +-----+ +---------------------+ +-----+
      // 31   28 27   24 23   20 19   16 15                    4 3     0
      //
      // p = 0, q = 0
      getRR(op, a, b, c, x = op & (RSCAssembler.U_BIT | RSCAssembler.V_BIT)) {
        let upper = 0 | x;
        return upper | (a << 24) | (b << 20) | (op << 16) | c;
      }

      // p q u v ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?
      // +-----+ +-----+ +-----+ +-----+ +-----------------------------+
      // | (4) | |a : 4| |b : 4| |op: 4| |      immediate [i]: 16      |
      // +-----+ +-----+ +-----+ +-----+ +-----------------------------+
      // 31   28 27   24 23   20 19   16 15                            0
      //
      // p = 0, q = 1
      getRI(op, a, b, i, x = op & (RSCAssembler.U_BIT | RSCAssembler.V_BIT)) {
        const { Q_BIT } = RSCAssembler;
        const { V_BIT } = RSCAssembler;

        let upper = Q_BIT | x | (i < 0 ? V_BIT : 0);
        return upper | (a << 24) | (b << 20) | (op << 16) | (i & 0xFFFF);
      }

      // p q u v ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?
      // +-----+ +-----+ +-----+ +-------------------------------------+
      // | (4) | |a : 4| |b : 4| |             offset : 20             |
      // +-----+ +-----+ +-----+ +-------------------------------------+
      // 31   28 27   24 23   20 19                                    0
      //
      // p = 1, q = 0, u = op (where load = 0, store = 1)
      getLS(op, a, b, offset, x = op & RSCAssembler.V_BIT) {
        let upper = RSCAssembler.P_BIT | op | x;
        return (upper | (a << 24) | (b << 20) | (offset & 0xFFFFF)) >>> 0;
      }

      // p q u v ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?
      // +-----+ +-----+ +---------------------------------------------+
      // | (4) | |cd: 4| |                  dest : 24                  |
      // +-----+ +-----+ +---------------------------------------------+
      // 31   28 27   24 23                                            0
      //
      // p = 1, q = 1, v = op (where branch = 0, call = 1)
      getBC(op, cd, dest) {
        let upper = RSCAssembler.P_BIT | RSCAssembler.Q_BIT | op;
        return (upper | (cd << 24) | (dest & 0xFFFFFF)) >>> 0;
      }
    }

    RSCAssembler.MINTED_OVERRIDES = 1;
    RSCAssembler.HINTED_OVERRIDES = 2;

    RSCAssembler.P_BIT = 1 << 31;
    RSCAssembler.Q_BIT = 1 << 30;
    RSCAssembler.U_BIT = 1 << 29;
    RSCAssembler.V_BIT = 1 << 28;

  </script>


Presentation and compatibility
==============================

Suppose we copied the text of this document into a file, gave it a name with a
file extension typically associated with the HTML mimetype, and then opened
such a file in a web browser.  What would be the expected result?  If in that
page we also applied some CSS rules like the ones that follow, on examination
of the text here, it should be clear to readers with a good understanding of
CSS and the HTML5 parsing algorithm that this will result in the main text of
this document being displayed in the browser as plain text, in much the same
way that it appears in a text editor--with the content of the following code
block itself being the lone exception:

  <style>

    body { font-family: monospace; white-space: pre; }
    script::before { content: '  \3Cscript\3E\0D'; }
    script::after { content: '\0D\3C/script\3E'; }
    script:not([src]) { display: block; margin: -1em 0; }

  </style>

On the other hand, because of the particular way that the preceding block is
itself incorporated into this document, the process of copying the content
exactly as shown is sufficient to make sure those rules get applied.  We can
do better than that, though.  We can use the same trick to make sure that with
just a few more rules this section is displayed correctly in a web browser,
too.  Viz:

  <style>

    style::before { content: '  \3Cstyle\3E\0D'; }
    style::after { content: '\0D\3C/style\3E'; }
    style:not([src]) { display: block; margin: -1em 0; }

  </style>

What's more, if we had been conservative enough and careful in our choices
regarding the pseudocode notation in the modules presented here, then we could
achieve an effect much more useful than mere display equivalence.  By taking
care to make sure the pseudocode can parse as syntactically valid when fed to
the browser's JS engine and that it's semantically equivalent when
evaluated--or at least close enough to "semantically equivalent"--then the
reader could simply outsource the task of creating an assembler.  Rather than
a human using this document as a reference and implementing an assembler of
their own, this document itself can be used *directly* as the implementation.
In fact, we have been that careful, and that's been the plan all along.

Achieving the full effect only requires a few more pieces.


Implementing the system interface
---------------------------------

Using a bootstrap loader, such as the one that follows later, we can finesse
the preceding module definitions into our plan, by wiring them up to the
available browser APIs.  Doing this is as easy as implementing the minimal
`system` interface referenced in the `RSCListingReader` code.  Here's an
example implementation of such a system layer, which--you guessed it--is
itself correct and working code, and its inclusion here is also sufficient to
be able to actually use it.  All that would be needed beyond this system layer
would be to wire up the pieces with the bootstrap loader, presented later.

  <script>

    /// import { AppStateController } from "./AppStateController.src";
    /// import { RSCListingReader } from "./RSCListingReader.src";

    /// export
    class SystemB {
      read(path) {
        if (path == SystemB.INTRINSIC_PATH) {
          if (this._content == null) {
            this._content = this._extract(this._figureElement);
          }
          return this._content;
        }
        return new Error("unsupported path read...");
      }

      _extract(node) {
        let unindented = node.textContent.replace((/^    /mg), "");
        let [ firstLine ] = unindented.split("\n", 1);
        for (let i = firstLine.length, n = unindented.length; i < n; ++i) {
          if (unindented.charAt(i) != " " && unindented.charAt(i) != "\n") {
            return unindented.substring(i);
          }
        }
        return new Error("unexpected format for sample input...");
      }

      constructor(page) {
        this._page = page;
        this._app = new AppStateController(page.ownerDocument);

        this._content = null;
        this._figureElement = null;
      }

      attach(document) {
        // Requires sample input to be the first content block
        this._figureElement = this._page.querySelector("script");
        this._app.setAction((() => {
          let bytes = RSCListingReader.convert(this, SystemB.INTRINSIC_PATH);
          return this._formatHexDump(bytes);
        }));
      }

      _formatHexDump(bytes) {
        let result = "";

        for (let i = 0, n = bytes.length; i < n; i += 16) {
          let line = "";
          for (let j = 0; j < 16 && i + j < n; ++j) {
            line += bytes[i + j].toString(16).padStart(2, 0);
            if (j % 2) {
              line += " "
            }
          }
          result += line + "\n";
        }

        return result;
      }

      observe(thing) {
        if (typeof(console) != "undefined") {
          console.log(thing);
        } else {
          throw Error("panic!")
        }
      }
    }

    SystemB.INTRINSIC_PATH = "input.txt";

  </script>

Our system implementation satisfies the interface, because it implements both
`read` and `observe`, and it's free to implement it by whatever means
possible.

In an ideal implementation, for the `read` operation, we'd receive the path to
the file of interest and then read it.  However, since we're expected to
execute in the browser instead of a traditional, operating system-managed
process execution context, there *are* no paths of files to be read.  So we
fake it and support "reading" from exactly one path.  Because the system layer
itself is responsible for how `RSCListingReader.convert` gets called, its
`read` method can be hardcoded, as shown, to expect any path of our choosing.

Note that this implementation of the system interface defers to an external
controller `AppStateController`, which has not yet been defined.  We'll
need to do so in order to to have a complete working demo.  Unfortunately, the
Web platform APIs do not make for our task to be as trivial as we'd hope for,
given the expectations we have for even our simple interaction design, but
it's still manageable.

  <script>

    /// export
    class AppStateController {
      constructor(document) {
        this._doc = document;
        this.$action = null;
      }

      setAction($action) {
        const VIEW_FRAGMENT = "#" + AppStateController.OUTPUT_ID;

        this.$action = $action;

        if (this._doc.location.hash == VIEW_FRAGMENT) {
          this.invokeAction(true);
        } else {
          this.invalidateOutput();
        }

        this._doc.defaultView.addEventListener("pageshow", this);
        this._doc.defaultView.addEventListener("popstate", this);
      }

      handleEvent(ev) {
        switch (ev.type) {
          case "keypress": 
            if ((ev.key == "Enter" || ev.code == "Enter") && ev.ctrlKey) {
              this.invokeAction();
            }
          break;
          case "pageshow":
            if (!this._doc.location.hash) {
              this.invalidateOutput();
            }
          break;
          case "popstate":
            this.onStateChange();
          break;
          default:
            throw new Error("Unexpected event: " + ev.type);
          break;
        }
      }

      invokeAction(replace = false) {
        const VIEW_FRAGMENT = "#" + AppStateController.OUTPUT_ID;

        let content = this.$action.call();
        if (content != null) {
          this._doc.removeEventListener("keypress", this);

          let { history } = this._doc.defaultView;
          if (replace) {
            history.replaceState({ content: content }, null);
          } else {
            history.pushState({ content: content }, null, VIEW_FRAGMENT);
          }

          this.displayContent(content);
        }
        return content;
      }

      displayContent(content = this.getContent(this._doc.location.hash)) {
        const { OUTPUT_ID } = AppStateController;

        if (content == null) {
          this.invalidateOutput();
        } else {
          let newBody = this._doc.createElement("body");
          newBody.textContent = content;
          newBody.id = OUTPUT_ID;

          this._doc.body.parentNode.appendChild(newBody);
          this._doc.body.style.display = "none";
        }
      }

      onStateChange() {
        try {
          this.displayContent();
        } catch (ex) {
          if (ex instanceof AppStateController.NoStateError) {
            return void(this.invokeAction(true));
          }
          throw ex;
        }
      }

      getContent(fragment) {
        const { OUTPUT_ID } = AppStateController;

        if (fragment.substring(1) == OUTPUT_ID) {
          let { history } = this._doc.defaultView;
          if (!history.state) {
            throw new AppStateController.NoStateError;
          }
          return history.state.content;
        }
        return null;
      }

      invalidateOutput() {
        const { OUTPUT_ID } = AppStateController;

        this._doc.body.style.display = "";
        let outputBody = this._doc.getElementById(OUTPUT_ID);
        if (outputBody) {
          outputBody.parentNode.removeChild(outputBody);
        }

        this._doc.addEventListener("keypress", this);
      }
    }

    AppStateController.OUTPUT_ID = "?view=output";

    AppStateController.NoStateError = class NoStateError extends Error { };

  </script>

The controller implementation needs to be able to activate the bound action--
in our case, the closure over `RSCListingReader.convert`--and to do so while
gracefully handling several cases:

- Ordinary vanilla activation intended to put the results on the screen using
  Ctrl+Enter (i.e., the common case)
- Activation by editing the URL to insert the fragment, as on mobile (see
  below)
- Navigating directly to the output view by URL, e.g. in a new tab
- Pressing reload on the output view
- Various other conditions involving moving backwards and forwards between the
  browser history entries

Although it's verbose, the value of the controller implemented here is its
ability to handle these conditions.


Bootstrapping the system layer
------------------------------

And now, a bootstrap sequence:

  <script>

    /// import { SystemB } from "./oasm/SystemB.src";

    void function _start() {
      if (typeof(window) == "undefined") throw Error("panic!");
      if (typeof(document) == "undefined") throw Error("panic!");

      if (document.readyState == "complete") {
        return void(main(null, document));
      }
      window.onload = main;

      function main(event, document = event.target) {
        let system = new SystemB(document.body);
        system.attach(document);
      }

    } ()

    $path$: "main.src"

  </script>

That's it.  Try it out by making sure this file is named something like
"oasm.txt.htm" (or anything ending with `.htm` or `.html`) and then pointing
your Web browser to it, e.g. by drag-and-drop or by double-clicking it in your
system's file manager.  Activate the demo by pressing Ctrl-Enter on your
keyboard, or (particularly for devices without keyboards) append the URL
fragment `#?view=output` to the location shown in your browser's address bar.

If you edit your copy of this document, you can replace the sample input with
a program of your own and "re-run" the assembler on the new input by opening
it in the browser and repeating the steps to activate the assembler.  You
should find that you're presented with output corresponding to the modified
input, rather than the output of the original demo here.


Feedback
========

This has been an experiment in writing code in a way that approaches the
practice of literate programming, albeit using native features of the
WHATWG/W3C hypertext system rather than tooling specifically crafted for the
task, such as Knuth's CWEB.

If you'd like to provide feedback, you are encouraged to annotate this content
using Hypothesis:

<:https://via.hypothes.is/https://www.colbyrussell.com/LP/debut/plain.txt.htm>

At the time of publication, a blog post about the writing process of this
document is being drafted, although not yet published.  The evolution of
thought behind this and similar works, environmental constraints, and
motivating factors will be detailed there.  When published, it will be
announced at the URL:

<:https://www.colbyrussell.com/LP/debut/background-and-primer>