stdlib

package
v1.5.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package stdlib provides type definitions for Lua's standard library.

This package defines typed signatures for all Lua built-in functions and library tables. These definitions enable the type checker to validate calls to standard library functions and infer result types.

The library includes:

  • Global functions: print, type, pairs, ipairs, assert, error, etc.
  • Math library: math.floor, math.sin, math.random, etc.
  • String library: string.sub, string.find, string.format, etc.
  • Table library: table.insert, table.remove, table.sort, etc.
  • Coroutine library: coroutine.create, coroutine.resume, etc.
  • Debug library: debug.traceback, debug.getinfo, etc.
  • UTF8 library: utf8.codes, utf8.len, etc.
  • Package library: package.path, package.loaded, etc.
  • Errors library: errors.new, errors.wrap, errors.is, etc.

Usage: 

lib := stdlib.Library()
mathType := lib["math"]
printType := lib["print"]

Index

Constants

This section is empty.

Variables

View Source 
var (
	// assert(v, message?) -> v
	// When assert returns, v is truthy (not nil/false)
	Assert = typ.Func().
			Param("v", typ.Any).
			OptParam("message", typ.String).
			Returns(typ.Any).
			Effects(effect.Throws()).
			WithRefinement(&constraint.FunctionEffect{
			OnReturn: constraint.FromConstraints(
				constraint.Truthy{Path: constraint.ParamPath(0)},
			),
		}).
		Build()

	// error(message, level?) -> never
	Error = typ.Func().
			Param("message", typ.Any).
			OptParam("level", typ.Number).
			Returns(typ.Never).
			Effects(effect.Throws()).
			Build()

	// getmetatable(object) -> table?
	GetMetatable = typ.Func().
					Param("object", typ.Any).
					Returns(typ.NewOptional(typ.Any)).
					Build()

	// setmetatable(table, metatable) -> table
	SetMetatable = func() typ.Type {
		tp := typ.NewTypeParam("T", nil)
		return typ.Func().
			TypeParam("T", nil).
			Param("table", tp).
			Param("metatable", typ.NewOptional(typ.Any)).
			Returns(tp).
			Effects(effect.StoresParam(1, 0)).
			Build()
	}()

	// ipairs(t) -> iterator, t, 0
	Ipairs = typ.Func().
			Param("t", typ.Any).
			Returns(typ.Any, typ.Any, typ.Integer).
			Spec(ipairsSpec).
			Build()

	// pairs(t) -> iterator, t, nil
	Pairs = typ.Func().
			Param("t", typ.Any).
			Returns(typ.Any, typ.Any, typ.Nil).
			Spec(pairsSpec).
			Build()

	// next(table, index?) -> key?, value?
	Next = typ.Func().
			Param("table", typ.Any).
			OptParam("index", typ.Any).
			Returns(typ.NewOptional(typ.Any), typ.NewOptional(typ.Any)).
			Build()

	// pcall(f, ...) -> success, result...
	Pcall = typ.Func().
			Param("f", typ.Any).
			Variadic(typ.Any).
			Returns(typ.Boolean, typ.Any).
			Effects(effect.BorrowsOnly()).
			Spec(pcallSpec).
			Build()

	// cpcall(f, ...) -> success, result... (coroutine-safe pcall)
	Cpcall = typ.Func().
			Param("f", typ.Any).
			Variadic(typ.Any).
			Returns(typ.Boolean, typ.Any).
			Effects(effect.BorrowsOnly()).
			Spec(pcallSpec).
			Build()

	// xpcall(f, msgh, ...) -> success, result...
	Xpcall = typ.Func().
			Param("f", typ.Any).
			Param("msgh", typ.Any).
			Variadic(typ.Any).
			Returns(typ.Boolean, typ.Any).
			Effects(effect.BorrowsOnly()).
			Spec(xpcallSpec).
			Build()

	// print(...) -> nil
	Print = typ.Func().
			Variadic(typ.Any).
			Effects(effect.BorrowsOnly().With(effect.IO{})).
			Build()

	// type(v) -> string
	Type = typ.Func().
			Param("v", typ.Any).
			Returns(typ.String).
			Effects(effect.BorrowsOnly().With(effect.TypePredicate{})).
			Build()

	// tostring(v) -> string
	ToString = typ.Func().
				Param("v", typ.Any).
				Returns(typ.String).
				Effects(effect.BorrowsOnly()).
				Build()

	// tonumber(v, base?) -> number?
	ToNumber = typ.Func().
				Param("v", typ.Any).
				OptParam("base", typ.Integer).
				Returns(typ.NewOptional(typ.Number)).
				Effects(effect.BorrowsOnly()).
				Build()

	// number(v) -> number
	Number = typ.Func().
			Param("v", typ.Any).
			Returns(typ.Number).
			Effects(effect.BorrowsOnly()).
			Build()

	// integer(v) -> integer
	Integer = typ.Func().
			Param("v", typ.Any).
			Returns(typ.Integer).
			Effects(effect.BorrowsOnly()).
			Build()

	// rawequal(v1, v2) -> boolean
	RawEqual = typ.Func().
				Param("v1", typ.Any).
				Param("v2", typ.Any).
				Returns(typ.Boolean).
				Effects(effect.BorrowsOnly()).
				Build()

	// rawget(table, index) -> any
	RawGet = typ.Func().
			Param("table", typ.Any).
			Param("index", typ.Any).
			Returns(typ.Any).
			Effects(effect.BorrowsOnly()).
			Build()

	// rawset(table, index, value) -> table
	RawSet = typ.Func().
			Param("table", typ.Any).
			Param("index", typ.Any).
			Param("value", typ.Any).
			Returns(typ.Any).
			Effects(effect.StoresParam(2, 0)).
			Build()

	// rawlen(v) -> integer
	RawLen = typ.Func().
			Param("v", typ.Any).
			Returns(typ.Integer).
			Effects(effect.BorrowsOnly()).
			Build()

	// select(index, ...) -> ...
	Select = typ.NewUnion(
		typ.Func().
			Param("index", typ.LiteralString("#")).
			Variadic(typ.Any).
			Returns(typ.Integer).
			Effects(effect.WithVariadicTransform()).
			Build(),
		typ.Func().
			Param("index", typ.Integer).
			Variadic(typ.Any).
			Returns(typ.Any).
			Effects(effect.WithVariadicTransform()).
			Build(),
	)

	// require(modname) -> any
	Require = typ.Func().
			Param("modname", typ.String).
			Returns(typ.Any).
			Effects(effect.WithModuleLoad().With(effect.Throw{})).
			Build()

	// unpack(list, i?, j?) -> ...
	Unpack = typ.Func().
			Param("list", typ.Any).
			OptParam("i", typ.Integer).
			OptParam("j", typ.Integer).
			Returns(typ.Any).
			Effects(effect.BorrowsOnly()).
			Build()

	// dofile(filename?) -> ...
	DoFile = typ.Func().
			OptParam("filename", typ.String).
			Returns(typ.Any).
			Effects(effect.Throws().With(effect.IO{})).
			Build()

	// collectgarbage(opt?, arg?) -> any
	CollectGarbage = typ.Func().
					OptParam("opt", typ.String).
					OptParam("arg", typ.Any).
					Returns(typ.Any).
					Build()
)

Global function type definitions.

View Source 
var CallStack = typ.NewRecord().
	Field("thread", typ.String).
	Field("frames", typ.NewArray(StackFrame)).
	Build()

CallStack is the type for structured call stack information attached to errors.

View Source 
var CoroutineLib typ.Type = coroutineMethods

CoroutineLib provides types for Lua's coroutine management functions.

View Source 
var DebugLib typ.Type = debugMethods

DebugLib provides types for Lua's debug and introspection functions.

View Source 
var ErrorsLib typ.Type = errorsMethods

ErrorsLib provides types for structured error handling functions and kind constants.

View Source 
var MathLib typ.Type = mathMethods

MathLib provides types for Lua's math library functions and constants.

View Source 
var PackageLib typ.Type = packageMethods

PackageLib provides types for Lua's module loading configuration.

View Source 
var StackFrame = typ.NewRecord().
	Field("level", typ.Number).
	Field("source", typ.String).
	Field("line", typ.Number).
	Field("name", typ.String).
	Field("type", typ.String).
	Build()

StackFrame is the type for a single stack frame in error call stacks.

View Source 
var StringLib typ.Type = stringMethods

StringLib provides types for Lua's string library functions. These methods are also available on string values via method syntax.

View Source 
var TableLib typ.Type = tableMethods

TableLib provides types for Lua's table manipulation functions.

View Source 
var UTF8Lib typ.Type = utf8Methods

UTF8Lib provides types for Lua's UTF-8 encoding functions.

Functions

func EngineConfig 

func EngineConfig() core.StdlibConfig

EngineConfig returns configuration for the type query engine. This enables method resolution on primitive types (e.g., "hello":upper()).

func Library 

func Library() map[string]typ.Type

Library returns the complete standard library type map. The returned map is shared and should not be modified.

func Lookup 

func Lookup(path string) typ.Type

Lookup resolves a standard library path to its type. Accepts both simple names ("print") and dotted paths ("string.upper"). Returns nil if the path does not match any standard library entry.

func MathMaxSpec 

func MathMaxSpec() *contract.Spec

MathMaxSpec defines the contract for math.max ensuring result equals maximum of inputs.

func MathMinSpec 

func MathMinSpec() *contract.Spec

MathMinSpec defines the contract for math.min ensuring result equals minimum of inputs.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.