interpreter

Documentation

Overview

builtins.go installs the MX Script standard library into the global environment. Every native function is registered here so they're available in every .mx program without an import.

Package interpreter is the heart of MX Script. It walks the parsed AST, evaluates expressions, drives the standard library, and (when route declarations are present) starts an HTTP server that dispatches incoming requests to user-defined route bodies.

jobs.go — durable background job queue backed by SQLite.

Two-line worker:

let q = jobs.create({ db: "./jobs.db", queue: "emails" })
q.enqueue({ to: "alice@example.com", subject: "Hi" })
q.process(2, fn(job) { email.send(...job) })   # 2 workers

Each job carries: id, queue, payload (JSON), status (pending | running | done | failed), attempts, last_error, run_at, created_at. Failed jobs retry with exponential backoff up to `max_attempts` (default 3). After that they stay marked `failed` in the table for inspection.

parse_helper.go wires the interpreter's import statement to the lexer and parser without forcing the consumer of this package to do it themselves.

sql.go — SQLite via the pure-Go modernc.org/sqlite driver. Exposed through the `sql` namespace:

let db = sql.open("./data.db")           # opens / creates a database
sql.exec(db, "CREATE TABLE users (...)")
sql.exec(db, "INSERT ... VALUES (?, ?)", "Jassim", 30)
let rows = sql.query(db, "SELECT * FROM users WHERE name = ?", "Jassim")
loop rows as u { print(u.name) }
let one = sql.query_one(db, "SELECT * FROM users WHERE id = ?", 1)
sql.close(db)

websocket.go — minimal RFC 6455 WebSocket server in pure stdlib. No extensions, no permessage-deflate, no fragmented messages over 16 MB. Good enough for chat / live updates / collaborative editors. If you need the heavyweight features, drop in gorilla/websocket and call Interpreter.Handler() to keep the rest of the framework.

Index

• func DisplayValue(v Value) string
• func IsBuiltin(name string) bool
• func ParseSource(src string) (*parser.Program, error)
• type Channel
  • func (c *Channel) Close()
• type Coverage
  • func (c *Coverage) ExecutedLines() []int
  • func (c *Coverage) Hit(line int)
• type Env
  • func NewEnv(parent *Env) *Env
  • func (e *Env) Assign(name string, v Value)
  • func (e *Env) Get(name string) (Value, bool)
  • func (e *Env) Keys() []string
  • func (e *Env) Set(name string, v Value)
• type Function
• type Interpreter
  • func New() *Interpreter
  • func (i *Interpreter) CallByName(name string, args []Value) (Value, error)
  • func (i *Interpreter) Coverage() *Coverage
  • func (i *Interpreter) EnableCoverage() *Coverage
  • func (i *Interpreter) Exec(prog *parser.Program) (Value, error)
  • func (i *Interpreter) Globals() *Env
  • func (i *Interpreter) Handler() http.Handler
  • func (i *Interpreter) HasRoutes() bool
  • func (i *Interpreter) Load(prog *parser.Program) error
  • func (i *Interpreter) Run(prog *parser.Program) error
  • func (i *Interpreter) SetFile(path string)
  • func (i *Interpreter) SetPort(p int)
• type MXError
  • func (e *MXError) Error() string
• type OrderedMap
  • func NewOrderedMap() *OrderedMap
  • func (o *OrderedMap) Get(k string) (Value, bool)
  • func (o *OrderedMap) Set(k string, v Value)
• type Response
• type StackFrame
• type Value
  • func ArrayValue(a []Value) Value
  • func BoolValue(b bool) Value
  • func ChannelValue(c *Channel) Value
  • func FunctionValue(f *Function) Value
  • func HandleValue(h any) Value
  • func NullValue() Value
  • func NumberValue(n float64) Value
  • func ObjectValue(o *OrderedMap) Value
  • func ResponseValue(r *Response) Value
  • func StringValue(s string) Value
  • func (v Value) Display() string
  • func (v Value) IsTruthy() bool
• type ValueKind
• type WSConn
  • func (c *WSConn) ReadMessage() (string, bool, error)
  • func (c *WSConn) WriteBinary(b []byte) error
  • func (c *WSConn) WriteClose(code int, reason string) error
  • func (c *WSConn) WriteText(s string) error

Functions

func DisplayValue

func DisplayValue(v Value) string

DisplayValue formats a value for human-readable output, used by the REPL.

func IsBuiltin

func IsBuiltin(name string) bool

IsBuiltin reports whether a global name was installed by the standard library rather than the user's program.

func ParseSource

func ParseSource(src string) (*parser.Program, error)

ParseSource lexes and parses a string of MX Script source code.

Types

type Channel

type Channel struct {
	C chan Value
	// contains filtered or unexported fields
}

Channel wraps a Go channel of MX values. Allocated by chan(); operated on with send(ch, v), recv(ch), close_chan(ch).

func (*Channel) Close

func (c *Channel) Close()

type Coverage

type Coverage struct {
	// contains filtered or unexported fields
}

Coverage tracks which source lines were executed during a run. Filled in by the interpreter when EnableCoverage is called and queried by the CLI's `mx test --cover` reporter.

func (*Coverage) ExecutedLines

func (c *Coverage) ExecutedLines() []int

ExecutedLines returns a sorted snapshot of the line numbers that ran.

func (*Coverage) Hit

func (c *Coverage) Hit(line int)

Hit publicly records that `line` ran. Used by the test runner to merge per-test coverage into a file-level aggregate.

type Env

type Env struct {
	// contains filtered or unexported fields
}

Env is the lexical scope. RWMutex protects the vars map so spawned goroutines can read/write the closure safely. (Programs that share MUTABLE state across spawns still race on the values themselves — use channels for coordination.)

func NewEnv

func NewEnv(parent *Env) *Env

func (*Env) Assign

func (e *Env) Assign(name string, v Value)

Assign walks up parents until the variable is found, then replaces it. If not found, defines it in the current scope.

func (*Env) Get

func (e *Env) Get(name string) (Value, bool)

func (*Env) Keys

func (e *Env) Keys() []string

Keys returns the names defined directly in this scope (not parents). Used by the REPL to show what the user has bound.

func (*Env) Set

func (e *Env) Set(name string, v Value)

type Function

type Function struct {
	Name    string
	Params  []string
	Body    []parser.Stmt
	Closure *Env
	Native  func(interp *Interpreter, args []Value) (Value, error)
}

type Interpreter

type Interpreter struct {
	// contains filtered or unexported fields
}

func New

func New() *Interpreter

New constructs an interpreter pre-populated with all built-ins.

func (*Interpreter) CallByName

func (i *Interpreter) CallByName(name string, args []Value) (Value, error)

CallByName invokes a user-defined function in the global scope by name. Used by the test runner to call discovered `test_*` functions.

func (*Interpreter) Coverage

func (i *Interpreter) Coverage() *Coverage

Coverage returns the active coverage tracker (nil if disabled).

func (*Interpreter) EnableCoverage

func (i *Interpreter) EnableCoverage() *Coverage

EnableCoverage turns on per-statement line tracking. Called by `mx test --cover`; off by default for normal runs (zero overhead).

func (*Interpreter) Exec

func (i *Interpreter) Exec(prog *parser.Program) (Value, error)

Exec runs every statement in the program against the global scope and returns the value of the last expression statement (if any). Unlike Run, it does NOT start an HTTP server even if the program defined routes. This is intended for the REPL, where we want immediate feedback.

func (*Interpreter) Globals

func (i *Interpreter) Globals() *Env

Globals returns the interpreter's top-level environment. It's exposed so embedders (notably the REPL) can evaluate statements that read or write the same scope across multiple calls.

func (*Interpreter) Handler

func (i *Interpreter) Handler() http.Handler

Handler returns the fully-wrapped HTTP handler for the loaded program: the route mux composed with the configured CORS, logging, and request body size middleware.

Call Load before Handler so the program's routes, middleware, and server config are registered. Handler is safe to call multiple times; each call returns a freshly-composed handler chain over the same underlying state.

This is the entry point for embedders (e.g. the Vercel adapter) that want to mount an MX Script app inside their own HTTP server.

func (*Interpreter) HasRoutes

func (i *Interpreter) HasRoutes() bool

HasRoutes reports whether the loaded program defined any HTTP routes or static mounts. Useful for embedders deciding whether to start a server.

func (*Interpreter) Load

func (i *Interpreter) Load(prog *parser.Program) error

Load evaluates every top-level statement in the program against the global scope. It registers any `server { ... }` config, route, middleware and `static` mount, but does NOT start an HTTP server.

Embedders that want to mount the resulting routes in their own server (for example, the Vercel adapter generated by `mx build --vercel`) should call Load followed by Handler.

func (*Interpreter) Run

func (i *Interpreter) Run(prog *parser.Program) error

Run executes a parsed program. If the program declared any routes, it boots an HTTP server and blocks; otherwise it returns once the top-level statements have all been evaluated.

func (*Interpreter) SetFile

func (i *Interpreter) SetFile(path string)

SetFile records the source file path for error messages.

func (*Interpreter) SetPort

func (i *Interpreter) SetPort(p int)

SetPort marks the CLI-provided port. It overrides any port set by the program's `server { port: ... }` block so `mx run --port 3000` always wins.

type MXError

type MXError struct {
	Message string
	Line    int
	Col     int
	File    string
	Stack   []StackFrame
}

MXError is a structured runtime error with file/line context and the active call stack at the moment of failure.

func (*MXError) Error

func (e *MXError) Error() string

type OrderedMap

type OrderedMap struct {
	Keys   []string
	Values map[string]Value
}

OrderedMap preserves insertion order of object keys for predictable JSON output.

func NewOrderedMap

func NewOrderedMap() *OrderedMap

func (*OrderedMap) Get

func (o *OrderedMap) Get(k string) (Value, bool)

func (*OrderedMap) Set

func (o *OrderedMap) Set(k string, v Value)

type Response

type Response struct {
	Status      int
	ContentType string
	Body        Value
	Headers     map[string]string
	Cookies     []*http.Cookie
}

type StackFrame

type StackFrame struct {
	Name string
	Line int
	Col  int
}

StackFrame describes one active call when an error fired.

type Value

type Value struct {
	Kind     ValueKind
	Bool     bool
	Number   float64
	String   string
	Array    []Value
	Object   *OrderedMap
	Function *Function
	Response *Response
	Channel  *Channel
	// Handle is a generic opaque pointer for resources that don't fit
	// the standard value shapes — DB connections, future file handles,
	// etc. Treated as a black box by the interpreter.
	Handle any
}

func ArrayValue

func ArrayValue(a []Value) Value

func BoolValue

func BoolValue(b bool) Value

func ChannelValue

func ChannelValue(c *Channel) Value

func FunctionValue

func FunctionValue(f *Function) Value

func HandleValue

func HandleValue(h any) Value

func NullValue

func NullValue() Value

Helpers to construct values.

func NumberValue

func NumberValue(n float64) Value

func ObjectValue

func ObjectValue(o *OrderedMap) Value

func ResponseValue

func ResponseValue(r *Response) Value

func StringValue

func StringValue(s string) Value

func (Value) Display

func (v Value) Display() string

String produces a human-readable representation, used by print().

func (Value) IsTruthy

func (v Value) IsTruthy() bool

IsTruthy follows the rules: null/false/0/""/[]/{} are falsy; anything else is truthy.

type ValueKind

type ValueKind int

const (
	KindNull ValueKind = iota
	KindBool
	KindNumber
	KindString
	KindArray
	KindObject
	KindFunction
	KindResponse
	KindChannel
	KindHandle
)

type WSConn

type WSConn struct {
	// contains filtered or unexported fields
}

WSConn is the per-connection handle exposed to .mx code. Methods are safe for concurrent use; the underlying conn is guarded by writeMu.

func (*WSConn) ReadMessage

func (c *WSConn) ReadMessage() (string, bool, error)

ReadMessage reads one application-level message from the peer. It transparently handles continuation frames, ping/pong, and close frames. Returns the raw payload as a string and a boolean indicating whether the message is text (true) or binary (false). On normal close it returns io.EOF; on protocol error it returns a descriptive error.

func (*WSConn) WriteBinary

func (c *WSConn) WriteBinary(b []byte) error

WriteBinary sends a binary frame.

func (*WSConn) WriteClose

func (c *WSConn) WriteClose(code int, reason string) error

WriteClose sends a close frame with the given code and reason and then closes the underlying TCP connection. Subsequent calls are no-ops.

func (*WSConn) WriteText

func (c *WSConn) WriteText(s string) error

WriteText sends a text frame containing the given UTF-8 string.