basic.md

Basic functions and globals

Reference index · Official Lua 5.2 basic library · C Lua 5.2.4 source · Implementation

Install with state.OpenBasicLibrary(). Functions are globals. The shared string, numeric-text, cancellation, and host-object behavior applies throughout.

API / official reference	Inputs and result	Lua-CSharp implementation notes and differences
assert(v [, message])	Returns all arguments when v is truthy; otherwise raises an assertion error. The default message is assertion failed!.	The host receives a LuaAssertionException. Lua 5.2's message is string-like: a number is converted to text; an arbitrary table is not an assertion error object.
collectgarbage([opt [, arg]])	Recognizes collect, stop, restart, count, step, setpause, setstepmul, setmajorinc, isrunning, incremental, and generational.	Limitation: every recognized option calls GC.Collect() and returns no values. arg is ignored. Thus count does not report memory, stop does not stop GC, and tuning/mode options do not tune it. The implementation delegates to .NET GC without implementing Lua's collector control protocol.
dofile([filename])	Loads and executes a file, or standard input for an omitted/nil filename; returns its results and raises load/runtime failures.	Files use LuaPlatform.FileSystem; standard input uses LuaPlatform.StandardIO.Input and remains open. Paths are decoded to .NET text in byte mode.
error(message [, level])	Raises the supplied error object. At positive levels, numbers become strings and string messages receive a source prefix when that level exists. At level 0 or below, the original object is preserved.	Host-facing errors use LuaRuntimeException; stack descriptions include managed frames. Numeric text follows NumberFormat.
_G	The initial global environment table.	Installed from the state's managed environment. Assigning _G does not rewrite a function's _ENV.
getmetatable(value)	Returns the metatable, its protected __metatable value, or nil.	Also works with managed userdata.
ipairs(t)	Uses __ipairs when present; otherwise returns an iterator, the table, and 0, stopping at the first missing integer element. The default iterator converts its control value to an integer and returns one nil at exhaustion, as in Lua 5.2.	__ipairs cannot yield across the library callback boundary.
load(ld [, source [, mode [, env]]])	Compiles source/bytecode from a string or a reader function. Returns a function, or nil, error; an empty reader result ends input. mode defaults to bt. Explicit env, including nil, initializes the first upvalue.	Limitation: reader pieces are collected before parsing, so readers can be called past the point where C Lua would detect a syntax error or finish a binary chunk. This follows the current whole-input compiler interface. Reader callbacks cannot Lua-yield, but C# readers can await. Raw binary strings work in either mode; see dumping.
loadfile([filename [, mode [, env]]])	Compiles a file, or standard input for an omitted/nil filename; returns a function or nil, error. Recognizes an initial UTF-8 BOM and first-line # comment.	Uses the configured filesystem, with byte-mode paths decoded to .NET text. Standard input uses LuaPlatform.StandardIO.Input, independently of io.input/io.stdin assignments, has chunk name =stdin, and remains open on success or failure. Mode/environment handling is the same for both sources; bytecode requires an input provider exposing raw bytes through ILuaByteStream, as the default console provider does.
next(t [, index])	Returns the next key/value, or nil after the last key. Omitted/nil index starts traversal.	Order follows the managed table storage and is unspecified. Limitation: an unknown hash key such as next({}, 'missing') returns nil instead of C Lua's invalid-key error: the managed lookup treats that missing iteration position as the end.
pairs(t)	Uses __pairs, or returns the default iterator, table, and nil.	__pairs cannot Lua-yield across the library callback boundary.
pcall(f [, ...])	Returns true, ...results, or false, errorObject. Callable values with __call are supported.	Host execution cancellation escapes to C# rather than being consumed as a script error.
print(...)	Calls the global tostring for each argument and writes tab-separated output plus a newline.	Host-dependent: writes to LuaPlatform.StandardIO.Output, which may be a console, redirected stream, or Unity logger. As in C Lua, selecting io.output does not redirect print. Numeric text uses NumberFormat; the tostring callbacks cannot Lua-yield.
rawequal(a, b)	Compares values without __eq; strings compare by contents.	Tables, functions, threads, and userdata use managed object identity, corresponding to Lua's identity comparison for these types.
rawget(t, key)	Reads a table slot without __index.
rawlen(v)	Returns the raw table length or string length without __len.	String length counts UTF-16 code units in default mode and bytes in byte mode.
rawset(t, key, value)	Writes without __newindex and returns t.	Host-frozen tables still reject writes; raw access bypasses metamethods, not the managed table's read-only state.
select(index, ...)	"#" returns the argument count. A numeric index selects a suffix; negative indices count from the end.
setmetatable(t, mt)	Assigns a table metatable or removes it with nil; returns t. Protected metatables cannot be changed.	Host-frozen tables also prevent replacing their metatable.
tonumber(v [, base])	Parses numeric text or returns nil. With an explicit base, accepts bases 2–36 and a signed integer string.	A numeric v with an explicit base is first formatted using NumberFormat, which can affect parsing. Explicit-base digits accumulate in a double, as in the default C Lua 5.2 implementation; no newer Lua integer-subtype arithmetic is used.
tostring(v)	Uses __tostring when present; otherwise produces the value's standard text.	Numeric output uses NumberFormat; managed identities replace C pointer-like representations. __tostring cannot Lua-yield through this callback.
type(v)	Reports a Lua type name, including userdata for host objects and thread for Lua states.	C# functions are reported as function; .NET types are not exposed as separate Lua type names.
_VERSION	The string "Lua 5.2".	Reports the language target, not the Lua-CSharp NuGet/package version.
xpcall(f, msgh [, ...])	Calls f protected; on failure invokes msgh(error) before unwinding and returns false, handledError. On success returns true, ...results.	A handler failure produces error in error handling. The implementation terminates handler failure directly instead of repeatedly re-entering the same handler. Host execution cancellation propagates to C#.

Compatibility names

Lua-CSharp does not install the deprecated Lua 5.1 names loadstring, global unpack, getfenv, setfenv, or module. Use load, table.unpack, and Lua 5.2 _ENV-based modules. See the official library changes.