Integration Guide

The Autolang Sandbox Compiler allows you to easily embed and run Autolang code directly within your JavaScript or TypeScript projects, both natively and in the browser using WebAssembly.

📦 Installation

You can easily install the sandbox compiler using npm. It contains the bundled WebAssembly module out of the box.

Terminal

$npm install autolang-compiler

🚀 Basic Usage

Once installed, you can import and instantiate the compiler asynchronously. Here is a simple example to get started.

import { ACompiler } from 'autolang-compiler';

// Create the compiler instance (loads the WebAssembly module)
const compiler = await ACompiler.create();

compiler.registerBuiltInLibrary("testing/print", `
    
    @native("testPrint")
    func testPrint(helloText: String, name: String): String

`, false, {
    "testPrint": (args: AutolangArgs) => {
        return "${args[0]} ${args[1]}";
    }
})

// Clear the output buffer before running to avoid mixed logs from previous runs
compiler.outputBuffer = "";

// Now you can compile and run Autolang code
compiler.compileAndRun("main.al", `

    @import("testing/print")
    
    println(testPrint("Hello from ", "Autolang"))

`);

// You can access the standard output via outputBuffer
console.log(compiler.outputBuffer);
// Output: Hello from Autolang

💡

Standard Output Capture

In the Sandbox environment, the standard print and println functions do not log directly to the JavaScript console. Instead, their output is automatically captured and appended to the compiler's outputBuffer property. You can read this property synchronously immediately after execution to retrieve the entire printed output.

Important: To support running multiple code blocks sequentially without losing previous output, the buffer is never cleared automatically. You must manually clear it (e.g., compiler.outputBuffer = "") before executing new code if you want a fresh output state.

📄 Type Definitions

The package provides robust TypeScript definitions for interacting with the compiler and registering custom native modules securely.

export type AutolangPointer = number;

export type AutolangType = number | null | undefined | string | boolean | void | AutolangPointer;
export type AutolangArgs = AutolangType[];
export type AutolangNativeFunc = (args: AutolangArgs) => AutolangType;

export class ACompiler {
    public outputBuffer: string = "";

    // Creates a new instance of the compiler
    static async create(customWasmUrl?: string): Promise<ACompiler>;

    // Registers a custom built-in library, accessible within Autolang
    registerBuiltInLibrary(
        name: string, 
        source: string, 
        autoImport: boolean = true, 
        methods: Record<string, AutolangNativeFunc>
    ): void;

    // Compiles and immediately runs the code
    compileAndRun(path: string, code: string): boolean;

    // Compiles the code without running
    compile(path: string, code: string): boolean;

    // Runs the previously compiled code
    run(): boolean;

    // Checks if the compiler encountered any errors
    hasError(): boolean;

    // Refreshes/resets the compiler state
    refresh(): void;
}