LP Utilities

Common utilities and types

• DocumentRange:

  export type DocumentRange = {
    startLine: number;
    startCol?: number;
    endLine?: number;
    endCol?: number;
  };

  Values of this type represent the location of a section of code - useful to indicate what part of code is being executed, for example. Note that the section must be contiguous - i.e., you cannot represent a section of code including the 2nd line and the 4th line but not the 3rd.

  If you're implementing a language with instructions that may span across a non-contiguous section of code, please file an issue and I'll try to support your usecase.

• ParseError:

  import { ParseError } from "../worker-errors";
  /** ... while parsing code ... */
  throw new ParseError("Invalid instruction", location);

  This is a special Error class that represents a syntactic error in the user's program. This is used primarily for live syntax checking in the code editor. Along with the message, it also takes an argument of type DocumentRange that indicates what part of the code has the error.

• RuntimeError:

  import { RuntimeError } from "../worker-errors";
  /** ... while executing code ... */
  throw new RuntimeError("Cannot pop from empty stack");

  Another special Error class to be thrown if the user's program does something invalid at runtime. The location of the error is automatically set to be the currently executed instruction.

• toSafePrintableChar(asciiVal: number): string: (only for self-modifying esolangs)

  In self-modifying esolangs, the user's code may need to be edited in runtime to store data. This data (usually a number) is not necessarily ASCII code for a printable character, and may distort the code's alignment in the editor. Think changing a character to 10 (\n in ASCII) - it will split the line into two, making it hard for the user to understand what exactly happened.

  To avoid such effects, toSafePrintableChar converts a number to a string that is safe to add in code. This is done by transforming non-printable characters to representative Unicode characters, like \n -> ⤶.

  toSafePrintableChar actually only converts three characters (\n, \r and Tab) to representative Unicode versions. All other non-printable characters are properly rendered in the code editor using Monaco's renderControlCharacters setting.