Introduction

LuaScript is a Lua-flavored scripting language with Luau-style gradual types, implemented in Go as a compiler and a stack-based virtual machine. If you know Lua 5.4, you already know most of LuaScript: the same chunks, scoping rules, metatables, coroutines and standard-library shape. On top of that core it adds optional type annotations that are checked at compile time, a set of modern syntax features, a large library of native modules, and the tooling you expect from a modern language.

Why LuaScript

The implementation is a clean-room rewrite meant to be readable end to end. There is no LLVM, no JIT and no generated parser.

A taste

-- Plain Lua 5.4: closures, multiple returns, metatables
local function counter()
    local n = 0
    return function() n = n + 1; return n end
end
 
-- Optional types, checked at compile time and erased before bytecode
type Point = { x: number, y: number }
 
local function dist(p: Point): number
    return math.sqrt(p.x * p.x + p.y * p.y)
end
 
-- Tagged enums and pattern matching
enum Shape
    Circle(number),
    Rect(number, number),
end
 
local function area(s: Shape): number
    match s do
        Shape.Circle(r)  -> return math.pi * r * r
        Shape.Rect(w, h) -> return w * h
    end
    return 0
end
 
local next_id = counter()
next_id()
print(`id = {next_id()}`)       --> id = 2
print(dist({ x = 3, y = 4 }))   --> 5.0
print(area(Shape.Rect(2, 3)))   --> 6

Because the type checker runs before any code executes, a mistake like this is rejected at compile time instead of failing halfway through a run:

local function dist(x: number, y: number): number
    return math.sqrt(x * x + y * y)
end
 
print(dist(3, "4"))

luascript: Type "string" could not be converted into "number" at line 5

The standard library has hand-written signatures too, so math.sqrt(true) is a compile error, and require("json") with a literal module name gives you the module's real type.

How it is built

Source goes through a straight pipeline. The AST is the only contract between stages: the parser never produces instructions, and the VM never sees source text or types.

You can watch the later stages work with luascript -dis. Here the constant folder has already reduced 1 + 2 * 3 to 7 before any bytecode was generated:

print(1 + 2 * 3)

ProgramStart ProgramStart (0+ params, 0 locals, 0 upvalues, 4 instructions)
     0  [src    1]  getglobal        "print"
     1  [src    1]  loadint          7
     2  [src    1]  call             1 0
     3  [src    1]  leave

Read Architecture for the full tour of each stage.

Where to go next

• Installation: get a luascript binary, from a release or from source.
• Quick start: write and run your first script, and try the REPL.
• Basics: values, variables and control flow, the shared Lua foundation.
• Types: annotations, aliases, unions and narrowing. Then Strict mode, Structs, Enums, Match and Generics.
• Modern syntax: everything LuaScript adds on top of Lua 5.4.
• Native modules and Data science: the libraries that ship with the interpreter.
• CLI & tooling: every subcommand and flag.