`_shared` Namespace

ParseError

This class is simply used to bundle a message with a ReferenceRange, while it is primarily used to represent an error while parsing, it is also used for errors in compilation and other events where a message and a ReferenceRange are necessary.

export class ParseError {
    msg: string
    ref: ReferenceRange

    constructor(msg: string, ref: ReferenceRange);
    toString(): string;
}

SyntaxNode

This class can represent both a branch and a leaf node of a syntax tree. If these are generated by a parse call with source mapping turned off, it and all it's children will share a single instance of ReferenceRange with an invalid column and line number.

Please be mindful of this if you attempt to mutate the references on a non-source mapped SyntaxNode.

export class SyntaxNode {
    type : string; // the name of this branch/leaf
    start: number; // the byte index this node starts at
    end  : number; // the byte index this node ends at
    count: number; // the number of children, or number of bytes this holds (branch/leaf)
    value: SyntaxNode[] | string;
    ref: ReferenceRange;

    constructor (type: string, start: number, end: number, count: number, ref: ReferenceRange);
}

Reference

export class Reference {
    line : number; // numbering starts at 1
    col  : number; // numbering starts at 1
    index: number; // numbering starts at 0 (JS string index)

    constructor(line: number, col: number, index: number)
    clone(): Reference;
    toString(): string;

    static blank() {
        return new Reference(1,1,0);
    }
}

ReferenceRange

export class ReferenceRange {
    start: Reference;
    end:   Reference;

    constructor(from: Reference, to: Reference)
    span(other: ReferenceRange) // Merges itself with another range
    clone(): ReferenceRange
    toString(): string

  // Non-destructively takes two ranges, and returns a new range spanning both
    static union(a: ReferenceRange, b: ReferenceRange){
        return new ReferenceRange(
            a.start.index < b.start.index ? a.start.clone() : b.start.clone(), // Smallest
            a.end.index   > b.end.index   ? a.end.clone()   : b.end.clone(),   // Largest
        );
    }

  // Non-destructively takes two ranges, and returns a new range of the intersection of both
  // If the two ranges do not intersect you will end up with the range between them
    static intersection(a: ReferenceRange, b: ReferenceRange)

    static blank() {
        return new ReferenceRange(Reference.blank(), Reference.blank());
    }
}

AssertUnreachable

This function is simply a helper function for ensuring you have checked all possible states for a given node.

export function AssertUnreachable(x: never): never

Example

bnf

component ::= literal | constant | expr ;

typescript

switch (component.type) {
  case "literal": break;
  case "constant": break;
  default: AssertUnreachable(component); // will cause compile time error
                                          // as expr is missing
}

DecodeBase64

This function is simply used by artifacts, and not intended for end-user use, but could still be helpful.

export function DecodeBase64(base64: string): Uint8Array;

_shared Namespace