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.

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.

Index

• func DisplayValue(v Value) string
• func IsBuiltin(name string) bool
• func ParseSource(src string) (*parser.Program, error)
• 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) 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 FunctionValue(f *Function) 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

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 Env

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

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) 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
}

func ArrayValue

func ArrayValue(a []Value) Value

func BoolValue

func BoolValue(b bool) Value

func FunctionValue

func FunctionValue(f *Function) 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
)