sci2-ts 0.0.0-stage → 0.2.2

package/packages/sci/src/script/compiler.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The script compiler: SCI's Lisp-like source language to the assembly text that
+ * `assemble` builds (see assembly.ts). All of a game's scripts are compiled together, so a
+ * script can use classes, globals and procedures from any other.
+ *
+ *   (script 100)                                 the script's number
+ *   (include "game.sh")                          defines from another file
+ *   (define SPEED 6) (enum 1 LOOK DO TALK)       constants
+ *   (public lantern 0 helper 1)                  exports, by index
+ *   (local count [buf 10] (= name "x"))          script variables; script 0's are the globals
+ *   (global ego (= speed 6))                     more globals, declared by any script
+ *   (extern helper 100 1)                        a procedure exported by a script not compiled here
+ *   (class Lantern of Prop                       a class (no `of`: a root class)
+ *     (properties lit 0)
+ *     (method (doVerb theVerb &tmp i) ...))
+ *   (instance lamp of Lantern (properties x 10) (method ...))
+ *   (procedure (helper a b &tmp t) ...)
+ *
+ * Expressions: (= v e) (+= v e) (++ v), arithmetic + - * / mod << >> & | ^ ~, comparison
+ * == != < > <= >= u< u> u<= u>=, (and ...) (or ...) (not e), (if c ... else ...), (cond ...),
+ * (switch v (k ...) (else ...)), (switchto v (...) (...)), (while c ...), (repeat ...),
+ * (for (init) c (step) ...), (break), (continue), (return e). Sends: (obj sel: args sel2:
+ * args), (self ...), (super ...), (send e sel: ...); `sel?` reads a property; (obj [s] args)
+ * sends the selector in s. Calls: (proc args), (Kernel args),
+ * `&rest` passes on the caller's remaining arguments. [buf i] is an array element, @buf its
+ * address, #sel a selector, `a a character, $1F hex.
+ */
+export interface CompileSource {
+    file: string;
+    text: string;
+}
+/** A class defined outside the sources being compiled (an assembled script). */
+export interface ExternalClass {
+    species: number;
+    /** Properties after the object header, in order, with their default values. */
+    properties: {
+        name: string;
+        value: number;
+    }[];
+}
+export interface CompileContext {
+    kernelNames: readonly string[];
+    externalClass?(name: string): ExternalClass | undefined;
+    /** Species numbers classes outside these sources already use. */
+    takenSpecies?: ReadonlySet<number>;
+    /** The text of an included file, or undefined if there's no such file. */
+    include?(name: string, from: string): string | undefined;
+    /**
+     * Hears about likely mistakes that still compile: sends of a selector no class or object
+     * defines (as a property or a method). Only checked when every class is compiled here.
+     */
+    onWarning?(warning: CompileWarning): void;
+}
+export interface CompileWarning {
+    message: string;
+    file: string;
+    line: number;
+}
+export interface CompiledScript {
+    file: string;
+    number: number;
+    assembly: string;
+    /** Classes this script defines, by name. */
+    classes: Map<string, number>;
+    /** Its variables, by slot (an array's elements are name[i]); script 0's are the globals. */
+    variables: string[];
+}
+export declare class CompileError extends Error {
+    readonly file: string;
+    readonly line: number;
+    constructor(message: string, file: string, line: number);
+}
+/** The object header slots, in order; every class and instance begins with them. */
+export declare const OBJECT_HEADER: string[];
+export declare function compileScripts(sources: readonly CompileSource[], ctx: CompileContext): CompiledScript[];