//! *To avoid a duplication of efforts, Ziglua does not contain full

//! documentation on the Lua C API. Please refer to the [Lua C API Documentation](https://www.lua.org/manual/5.5/manual.html#4)

//! for full details.*

//!

//! ## Basics

//!

//! To create a Lua state, use the function `Lua.init()`.

//!

//! ```zig

//! const std = @import("std");

//! const zlua = @import("zlua");

//!

//! const Lua = zlua.Lua;

//!

//! pub fn main(init: std.process.Init) !void {

//! // Initialize the Lua vm

//! var lua: Lua = try .init(init.gpa);

//! defer lua.deinit();

//!

//! // Load all Lua standard libraries (print, math, io, etc.).

//! lua.openLibs();

//!

//! // Add an integer to the Lua stack and retrieve it

//! lua.pushInteger(42);

//! std.debug.print("{}\n", .{try lua.toInteger(1)});

//! }

//! ```

//!

//! To bind a Zig function to Lua, the function must accept a single `*Lua`

//! parameter and must return `i32` (an error union is allowed). This is the

//! Zig equivalent of `lua_CFunction typedef int (*lua_CFunction) (lua_State *L)` in the C API.

//!

//! ```zig

//! fn adder(lua: *Lua) i32 {

//! // The arguments are on the stack at indexes 1 and 2.

//! const a = lua.toInteger(1) catch 0;

//! const b = lua.toInteger(2) catch 0;

//!

//! // Push the result to the stack.

//! lua.pushInteger(a + b);

//!

//! // Returns the number of results pushed to the stack.

//! return 1;

//! }

//! ```

//!

//! While there are many different ways to make the function accessible from Lua, one

//! way is to save the function as a global variable.

//!

//! ```

//! // zlua.wrap converts the Zig function into a `lua_CFunction` that the C API expects.

//! // Pushes that function to the stack.

//! lua.pushFunction(zlua.wrap(adder));

//!

//! // Sets the global "adder" to the value on the top of the stack.

//! lua.setGlobal("adder");

//!

//! // Now the Zig function adder is accessible from Lua!

//! try lua.doString(

//! \\local sum = adder(10, 32)

//! \\print(sum)

//! );

//! ```

//!

//! ## Error Handling

//!

//! Similar to the Lua C API documentation, each function has an indicator to describe how interacts with the stack and which errors it may raise.

//!

//! Instead of using the `[-o, +p, x]` notation found in the Lua reference manual, zlua uses the **Pops from Stack**, **Pushes to Stack**, and **Lua Runtime Errors** for clarity.

//!

//! * **Pops from Stack**: how many elements the function pops from the stack.

//! * **Pushes to Stack**: how many elements the function pushes onto the stack.

//! (Any function always pushes its results after popping its arguments.)

//! * A field in the form `x|y` means the function can push (or pop) x or y elements, depending on the situation

//! * an interrogation mark `?` means that we cannot know how many elements the function pops/pushes by looking only at its arguments (For instance, they may depend on what is in the stack.)

//! * **Lua Runtime Errors**: tells whether the function may raise Lua errors:

//! * `none` means the function never raises any error.

//! * `memory` means the function may raise only out-of-memory errors.

//! * `see docs` means the function may raise the errors explained in the docs.

//! * `any` means the function can run arbitrary Lua code, either directly or through metamethods, and therefore may raise any errors.

//!

//! If a Lua error is raised in a protected environment (created by calling either `pcall()` or `lua.protectedCall()`), the error is

//! handled and returned to the caller. An error raised outside a protected environment panics and aborts the process.

//! See https://www.lua.org/manual/5.5/manual.html#4.4 for more details.

//!

//! See [Lua](#zlua.Lua) for documentation on the Lua state.

const std = @import("std");

pub const def = @import("define.zig");

pub const define = def.define;

const config = @import("config");

/// Access to the full Lua C API for the selected version of Lua (see `lang`).

///

/// This is exposed in case a function or constant is missing from the ziglua

/// bindings, or one of the wrapper functions imposes a limitation that

/// requires access to the C function.

pub const c = @import("c");

/// Lua language version targeted

pub const lang = config.lang;

/// The length of Luau vector values, either 3 or 4.

pub const luau_vector_size = if (config.luau_use_4_vector) 4 else 3;

/// This function is defined in luau.cpp and must be called to define the assertion printer

extern "c" fn zig_registerAssertionHandler() void;

/// This function is defined in luau.cpp and ensures Zig uses the correct free when compiling luau code

extern "c" fn zig_luau_free(ptr: *anyopaque) void;

const Allocator = std.mem.Allocator;

// Types

//

// Lua constants and types are declared below in alphabetical order

// For constants that have a logical grouping (like Operators), Zig enums are used for type safety

const ArithOperator52 = enum(u4) {

add = c.LUA_OPADD,

sub = c.LUA_OPSUB,

mul = c.LUA_OPMUL,

div = c.LUA_OPDIV,

mod = c.LUA_OPMOD,

pow = c.LUA_OPPOW,

negate = c.LUA_OPUNM,

};

const ArithOperator53 = enum(u4) {

add = c.LUA_OPADD,

sub = c.LUA_OPSUB,

mul = c.LUA_OPMUL,

div = c.LUA_OPDIV,

int_div = c.LUA_OPIDIV,

mod = c.LUA_OPMOD,

pow = c.LUA_OPPOW,

negate = c.LUA_OPUNM,

bnot = c.LUA_OPBNOT,

band = c.LUA_OPBAND,

bor = c.LUA_OPBOR,

bxor = c.LUA_OPBXOR,

shl = c.LUA_OPSHL,

shr = c.LUA_OPSHR,

};

/// Operations supported by `Lua.arith()`

pub const ArithOperator = switch (lang) {

.lua53, .lua54, .lua55 => ArithOperator53,

else => ArithOperator52,

};

/// Type for C functions

/// See https://www.lua.org/manual/5.4/manual.html#lua_CFunction for the protocol

pub const CFn = *const fn (state: ?*LuaState) callconv(.c) c_int;

/// Operations supported by `Lua.compare()`

pub const CompareOperator = enum(u2) {

eq = c.LUA_OPEQ,

lt = c.LUA_OPLT,

le = c.LUA_OPLE,

};

/// Type for C userdata destructors

pub const CUserdataDtorFn = *const fn (userdata: *anyopaque) callconv(.c) void;

/// Type for C interrupt callback

pub const CInterruptCallbackFn = *const fn (state: ?*LuaState, gc: c_int) callconv(.c) void;

/// Type for C useratom callback

pub const CUserAtomCallbackFn = *const fn (state: ?*LuaState, str: [*c]const u8, len: usize) callconv(.c) i16;

/// The internal Lua debug structure

const Debug = c.lua_Debug;

pub const DebugInfo51 = struct {

source: [:0]const u8 = undefined,

src_len: usize = 0,

short_src: [c.LUA_IDSIZE:0]u8 = undefined,

name: ?[:0]const u8 = undefined,

name_what: NameType = undefined,

what: FnType = undefined,

current_line: ?i32 = null,

first_line_defined: ?i32 = null,

last_line_defined: ?i32 = null,

is_vararg: bool = false,

private: c_int = undefined,

pub const NameType = enum { global, local, method, field, upvalue, other };

pub const FnType = enum { lua, c, main };

pub const Options = packed struct {

@">": bool = false,

f: bool = false,

l: bool = false,

n: bool = false,

S: bool = false,

u: bool = false,

L: bool = false,

fn toString(options: Options) [10:0]u8 {

var str = [_:0]u8{0} ** 10;

var index: u8 = 0;

inline for (std.meta.fields(Options)) |field| {

if (@field(options, field.name)) {

str[index] = field.name[0];

index += 1;

}

}

while (index < str.len) : (index += 1) str[index] = 0;

return str;

}

};

};

const DebugInfo52 = struct {

source: [:0]const u8 = undefined,

src_len: usize = 0,

short_src: [c.LUA_IDSIZE:0]u8 = undefined,

name: ?[:0]const u8 = undefined,

name_what: NameType = undefined,

what: FnType = undefined,

current_line: ?i32 = null,

first_line_defined: ?i32 = null,

last_line_defined: ?i32 = null,

num_upvalues: u8 = 0,

num_params: u8 = 0,

is_vararg: bool = false,

is_tail_call: bool = false,

private: *anyopaque = undefined,

pub const NameType = enum { global, local, method, field, upvalue, other };

pub const FnType = enum { lua, c, main };

pub const Options = packed struct {

@">": bool = false,

f: bool = false,

l: bool = false,

n: bool = false,

S: bool = false,

t: bool = false,

u: bool = false,

L: bool = false,

fn toString(options: Options) [10:0]u8 {

var str = [_:0]u8{0} ** 10;

var index: u8 = 0;

inline for (std.meta.fields(Options)) |field| {

if (@field(options, field.name)) {

str[index] = field.name[0];

index += 1;

}

}

while (index < str.len) : (index += 1) str[index] = 0;

return str;

}

};

};

/// The Lua debug interface structure

const DebugInfo54 = struct {

source: [:0]const u8 = undefined,

src_len: usize = 0,

short_src: [c.LUA_IDSIZE:0]u8 = undefined,

name: ?[:0]const u8 = undefined,

name_what: NameType = undefined,

what: FnType = undefined,

current_line: ?i32 = null,

first_line_defined: ?i32 = null,

last_line_defined: ?i32 = null,

num_upvalues: u8 = 0,

num_params: u8 = 0,

is_vararg: bool = false,

is_tail_call: bool = false,

first_transfer: u16 = 0,

num_transfer: u16 = 0,

private: *anyopaque = undefined,

pub const NameType = enum { global, local, method, field, upvalue, other };

pub const FnType = enum { lua, c, main };

pub const Options = packed struct {

@">": bool = false,

f: bool = false,

l: bool = false,

n: bool = false,

r: bool = false,

S: bool = false,

t: bool = false,

u: bool = false,

L: bool = false,

fn toString(options: Options) [10:0]u8 {

var str = [_:0]u8{0} ** 10;

var index: u8 = 0;

inline for (std.meta.fields(Options)) |field| {

if (@field(options, field.name)) {

str[index] = field.name[0];

index += 1;

}

}

while (index < str.len) : (index += 1) str[index] = 0;

return str;

}

};

};

/// The Lua debug interface structure for Lua 5.5

const DebugInfo55 = struct {

source: [:0]const u8 = undefined,

src_len: usize = 0,

short_src: [c.LUA_IDSIZE:0]u8 = undefined,

name: ?[:0]const u8 = undefined,

name_what: NameType = undefined,

what: FnType = undefined,

current_line: ?i32 = null,

first_line_defined: ?i32 = null,

last_line_defined: ?i32 = null,

num_upvalues: u8 = 0,

num_params: u8 = 0,

is_vararg: bool = false,

is_tail_call: bool = false,

first_transfer: i32 = 0,

num_transfer: i32 = 0,

private: *anyopaque = undefined,

pub const NameType = enum { global, local, method, field, upvalue, other };

pub const FnType = enum { lua, c, main };

pub const Options = packed struct {

@">": bool = false,

f: bool = false,

l: bool = false,

n: bool = false,

r: bool = false,

S: bool = false,

t: bool = false,

u: bool = false,

L: bool = false,

fn toString(options: Options) [10:0]u8 {

var str = [_:0]u8{0} ** 10;

var index: u8 = 0;

inline for (std.meta.fields(Options)) |field| {

if (@field(options, field.name)) {

str[index] = field.name[0];

index += 1;

}

}

while (index < str.len) : (index += 1) str[index] = 0;

return str;

}

};

};

pub const DebugInfoLuau = struct {

source: [:0]const u8 = undefined,

src_len: usize = 0,

short_src: [c.LUA_IDSIZE:0]u8 = undefined,

name: ?[:0]const u8 = undefined,

what: FnType = undefined,

current_line: ?i32 = null,

first_line_defined: ?i32 = null,

is_vararg: bool = false,

pub const NameType = enum { global, local, method, field, upvalue, other };

pub const FnType = enum { lua, c, main, tail };

pub const Options = packed struct {

f: bool = false,

l: bool = false,

n: bool = false,

s: bool = false,

u: bool = false,

L: bool = false,

fn toString(options: Options) [10:0]u8 {

var str = [_:0]u8{0} ** 10;

var index: u8 = 0;

inline for (std.meta.fields(Options)) |field| {

if (@field(options, field.name)) {

str[index] = field.name[0];

index += 1;

}

}

while (index < str.len) : (index += 1) str[index] = 0;

return str;

}

};

};

pub const DebugInfo = switch (lang) {

.lua51, .luajit => DebugInfo51,

.lua52, .lua53 => DebugInfo52,

.lua54 => DebugInfo54,

.lua55 => DebugInfo55,

.luau => DebugInfoLuau,

};

const Event51 = enum(u3) {

call = c.LUA_HOOKCALL,

ret = c.LUA_HOOKRET,

line = c.LUA_HOOKLINE,

count = c.LUA_HOOKCOUNT,

};

/// The type of event that triggers a hook

const Event52 = enum(u3) {

call = c.LUA_HOOKCALL,

ret = c.LUA_HOOKRET,

line = c.LUA_HOOKLINE,

count = c.LUA_HOOKCOUNT,

tail_call = c.LUA_HOOKTAILCALL,

};

pub const Event = switch (lang) {

.lua51, .luajit => Event51,

.lua52, .lua53, .lua54, .lua55 => Event52,

// TODO: probably something better than void here

.luau => void,

};

/// Type for arrays of functions to be registered

pub const FnReg = struct {

name: [:0]const u8,

func: ?CFn,

};

/// The index of the global environment table

pub const globals_index = c.LUA_GLOBALSINDEX;

/// Type for debugging hook functions

pub const CHookFn = *const fn (state: ?*LuaState, ar: ?*Debug) callconv(.c) void;

/// Specifies on which events the hook will be called

pub const HookMask = packed struct {

call: bool = false,

ret: bool = false,

line: bool = false,

count: bool = false,

/// Converts a HookMask to an integer bitmask

pub fn toInt(mask: HookMask) i32 {

var bitmask: i32 = 0;

if (mask.call) bitmask |= mask_call;

if (mask.ret) bitmask |= mask_ret;

if (mask.line) bitmask |= mask_line;

if (mask.count) bitmask |= mask_count;

return bitmask;

}

/// Converts an integer bitmask into a HookMask

pub fn fromInt(mask: i32) HookMask {

return .{

.call = (mask & mask_call) != 0,

.ret = (mask & mask_ret) != 0,

.line = (mask & mask_line) != 0,

.count = (mask & mask_count) != 0,

};

}

};

/// Hook event codes

pub const hook_call = c.LUA_HOOKCALL;

pub const hook_count = c.LUA_HOOKCOUNT;

pub const hook_line = c.LUA_HOOKLINE;

pub const hook_ret = c.LUA_HOOKRET;

pub const hook_tail_call = c.LUA_HOOKTAILCALL;

/// Type of integers in Lua (typically an i64)

pub const Integer = c.lua_Integer;

/// Type for continuation-function contexts (usually isize)

pub const Context = isize;

/// Type for continuation functions

pub const CContFn = *const fn (state: ?*LuaState, status: c_int, ctx: Context) callconv(.c) c_int;

pub const Libs51 = packed struct {

base: bool = false,

package: bool = false,

string: bool = false,

utf8: bool = false,

table: bool = false,

math: bool = false,

io: bool = false,

os: bool = false,

debug: bool = false,

};

pub const Libs52 = packed struct {

base: bool = false,

coroutine: bool = false,

package: bool = false,

string: bool = false,

table: bool = false,

math: bool = false,

io: bool = false,

os: bool = false,

debug: bool = false,

bit: bool = false,

};

pub const Libs53 = packed struct {

base: bool = false,

coroutine: bool = false,

package: bool = false,

string: bool = false,

utf8: bool = false,

table: bool = false,

math: bool = false,

io: bool = false,

os: bool = false,

debug: bool = false,

};

/// The type of the opaque structure that points to a thread and the state of a Lua interpreter

pub const LuaState = c.lua_State;

/// Lua types

/// Must be a signed integer because LuaType.none is -1

pub const LuaType = switch (lang) {

.luau => enum(i5) {

none = c.LUA_TNONE,

nil = c.LUA_TNIL,

boolean = c.LUA_TBOOLEAN,

light_userdata = c.LUA_TLIGHTUSERDATA,

number = c.LUA_TNUMBER,

vector = c.LUA_TVECTOR,

string = c.LUA_TSTRING,

table = c.LUA_TTABLE,

function = c.LUA_TFUNCTION,

userdata = c.LUA_TUSERDATA,

thread = c.LUA_TTHREAD,

},

else => enum(i5) {

none = c.LUA_TNONE,

nil = c.LUA_TNIL,

boolean = c.LUA_TBOOLEAN,

light_userdata = c.LUA_TLIGHTUSERDATA,

number = c.LUA_TNUMBER,

string = c.LUA_TSTRING,

table = c.LUA_TTABLE,

function = c.LUA_TFUNCTION,

userdata = c.LUA_TUSERDATA,

thread = c.LUA_TTHREAD,

},

};

/// Modes used for `Lua.load()`

pub const Mode = enum(u2) { binary, text, binary_text };

/// Event masks

pub const mask_call = c.LUA_MASKCALL;

pub const mask_count = c.LUA_MASKCOUNT;

pub const mask_line = c.LUA_MASKLINE;

pub const mask_ret = c.LUA_MASKRET;

/// The maximum integer value that `Integer` can store

pub const max_integer = c.LUA_MAXINTEGER;

/// The minimum integer value that `Integer` can store

pub const min_integer = c.LUA_MININTEGER;

/// The minimum Lua stack available to a function

pub const min_stack = c.LUA_MINSTACK;

/// Option for multiple returns in `Lua.protectedCall()` and `Lua.call()`

pub const mult_return = c.LUA_MULTRET;

/// Type of floats in Lua (typically an f64)

pub const Number = c.lua_Number;

/// The type of the reader function used by `Lua.load()`

pub const CReaderFn = *const fn (state: ?*LuaState, data: ?*anyopaque, size: [*c]usize) callconv(.c) [*c]const u8;

/// The possible status of a call to `Lua.resumeThread`

pub const ResumeStatus = enum(u1) {

ok = StatusCode.ok,

yield = StatusCode.yield,

};

/// Reference constants

pub const ref_nil = c.LUA_REFNIL;

pub const no_ref = c.LUA_NOREF;

/// Index of the registry in the stack (pseudo-index).

///

/// See https://www.lua.org/manual/5.5/manual.html#4.3

pub const registry_index = c.LUA_REGISTRYINDEX;

/// Index of globals in the registry

pub const ridx_globals = c.LUA_RIDX_GLOBALS;

/// Index of the main thread in the registry

pub const ridx_mainthread = c.LUA_RIDX_MAINTHREAD;

/// Status that a thread can be in

/// Usually errors are reported by a Zig error rather than a status enum value

pub const Status = enum(u3) {

ok = StatusCode.ok,

yield = StatusCode.yield,

err_runtime = StatusCode.err_runtime,

err_syntax = StatusCode.err_syntax,

err_memory = StatusCode.err_memory,

err_error = StatusCode.err_error,

};

/// Status codes

/// Not public, because typically Status.ok is returned from a function implicitly;

/// Any function that returns an error usually returns a Zig error, and a void return

/// is an implicit Status.ok.

/// In the rare case that the status code is required from a function, an enum is

/// used for that specific function's return type

/// TODO: see where this is used and check if a null can be used instead

const StatusCode = struct {

pub const ok = if (@hasDecl(c, "LUA_OK")) c.LUA_OK else 0;

pub const yield = c.LUA_YIELD;

pub const err_runtime = c.LUA_ERRRUN;

pub const err_syntax = c.LUA_ERRSYNTAX;

pub const err_memory = c.LUA_ERRMEM;

pub const err_error = c.LUA_ERRERR;

pub const err_gcmm = switch (lang) {

.lua52, .lua53 => c.LUA_ERRGCMM,

else => unreachable,

};

};

// Only used in loadFileX, so no need to group with Status

pub const err_file = c.LUA_ERRFILE;

/// The standard representation for file handles used by the standard IO library

pub const Stream = c.luaL_Stream;

/// The unsigned version of Integer

pub const Unsigned = c.lua_Unsigned;

/// The type of warning functions used by Lua to emit warnings

pub const CWarnFn = *const fn (data: ?*anyopaque, msg: [*c]const u8, to_cont: c_int) callconv(.c) void;

/// The type of the writer function used by `Lua.dump()`

pub const CWriterFn = *const fn (state: ?*LuaState, buf: ?*const anyopaque, size: usize, data: ?*anyopaque) callconv(.c) c_int;

/// For bundling a parsed value with an arena allocator

/// Copied from std.json.Parsed

pub fn Parsed(comptime T: type) type {

return struct {

arena: *std.heap.ArenaAllocator,

value: T,

pub fn deinit(self: @This()) void {

const allocator = self.arena.child_allocator;

self.arena.deinit();

allocator.destroy(self.arena);

}

};

}

/// The key in the registry that holds a table of all loaded modules. The `package.loaded` table in Lua.

pub const loaded_table = if (@hasDecl(c, "LUA_LOADED_TABLE")) c.LUA_LOADED_TABLE else "_LOADED";

/// The key in the registry that holds a table of preloaded loaders. The `package.preload` table in Lua.

pub const preload_table = if (@hasDecl(c, "LUA_PRELOAD_TABLE")) c.LUA_PRELOAD_TABLE else "_PRELOAD";

/// A Zig wrapper around the Lua C API

/// Represents a Lua state or thread and contains the entire state of the Lua interpreter

pub const Lua = opaque {

const alignment = @alignOf(std.c.max_align_t);

/// Allows Lua to allocate memory using a Zig allocator passed in via data.

/// See https://www.lua.org/manual/5.4/manual.html#lua_Alloc for more details

fn alloc(data: ?*anyopaque, ptr: ?*anyopaque, osize: usize, nsize: usize) callconv(.c) ?*align(alignment) anyopaque {

// just like malloc() returns a pointer "which is suitably aligned for any built-in type",

// the memory allocated by this function should also be aligned for any type that Lua may

// desire to allocate. use the largest alignment for the target

const allocator_ptr: *Allocator = @ptrCast(@alignCast(data.?));

if (@as(?[*]align(alignment) u8, @ptrCast(@alignCast(ptr)))) |prev_ptr| {

const prev_slice = prev_ptr[0..osize];

// when nsize is zero the allocator must behave like free and return null

if (nsize == 0) {

allocator_ptr.free(prev_slice);

return null;

}

// when nsize is not zero the allocator must behave like realloc

const new_ptr = allocator_ptr.realloc(prev_slice, nsize) catch return null;

return new_ptr.ptr;

} else if (nsize == 0) {

return null;

} else {

const builtin = @import("builtin"); // FIXME: remove when zig-0.15 is released and 0.14 can be dropped

// ptr is null, allocate a new block of memory

const new_ptr = (if (builtin.zig_version.major == 0 and builtin.zig_version.minor < 15)

allocator_ptr.alignedAlloc(u8, alignment, nsize)

else

allocator_ptr.alignedAlloc(u8, .fromByteUnits(alignment), nsize)) catch return null;

return new_ptr.ptr;

}

}

/// Initialize a Lua state with the given allocator. Use `Lua.deinit()` to close the state and free memory.

///

/// Creates a new independent state and returns its main thread.

/// Returns an error if it cannot create the state (due to lack of memory).

/// Lua will do all memory allocation for this state through the passed Allocator (see lua_Alloc).

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `0`

/// * Lua Runtime Errors: `none`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_newstate

pub fn init(a: Allocator) error{OutOfMemory}!*Lua {

if (lang == .luau) zig_registerAssertionHandler();

// the userdata passed to alloc needs to be a pointer with a consistent address

// so we allocate an Allocator struct to hold a copy of the allocator's data

const allocator_ptr = try a.create(Allocator);

allocator_ptr.* = a;

if (switch (lang) {

.lua55 => c.lua_newstate(alloc, allocator_ptr, 0),

else => c.lua_newstate(alloc, allocator_ptr),

}) |state| {

return @ptrCast(state);

} else return error.OutOfMemory;

}

/// Deinitialize a Lua state and free all memory

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_close

pub fn deinit(lua: *Lua) void {

// First get a reference to the allocator

var data: ?*Allocator = undefined;

_ = c.lua_getallocf(@ptrCast(lua), @ptrCast(&data)).?;

c.lua_close(@ptrCast(lua));

if (data) |a| {

const alloc_ = a;

alloc_.destroy(a);

}

}

/// Returns the `std.mem.Allocator` used to initialize this Lua state

pub fn allocator(lua: *Lua) Allocator {

var data: ?*Allocator = undefined;

_ = c.lua_getallocf(@ptrCast(lua), @ptrCast(&data)).?;

// The pointer should never be null because the only way to create a Lua state requires

// passing a Zig allocator.

// Although the Allocator is passed to Lua as a pointer, return a copy to make use more convenient.

return data.?.*;

}

// Library functions

//

// Library functions are included in alphabetical order.

// Each is kept similar to the original C API function while also making it easy to use from Zig

/// Converts the acceptable index idx into an equivalent absolute index (that is, one that does not depend on the stack size)

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `0`

/// * Lua Runtime Errors: `none`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_absindex

pub fn absIndex(lua: *Lua, index: i32) i32 {

switch (lang) {

.lua51, .luajit => {

if (index > 0 or index <= registry_index) {

return index;

} else {

const result = lua.getTop() + 1 + index;

return @intCast(result);

}

},

else => {

return c.lua_absindex(@ptrCast(lua), index);

},

}

}

/// Arithmetic functions for values on the stack

///

/// Performs an arithmetic or bitwise operation over the two values (or one, in the

/// case of negations) at the top of the stack, with the value on the top being the

/// second operand, pops these values, and pushes the result of the operation. The

/// function follows the semantics of the corresponding Lua operator (that is, it

/// may call metamethods).

///

/// Not implemented in Lua 5.1, LuaJIT, or Luau

///

/// * Pops from Stack: `(2|1)`

/// * Pushes to Stack: `1`

/// * Lua Runtime Errors: `any`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_arith

pub fn arith(lua: *Lua, op: ArithOperator) void {

c.lua_arith(@ptrCast(lua), @intFromEnum(op));

}

/// Sets a new panic function and returns the old one

///

/// Not implemented in Luau

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `0`

/// * Lua Runtime Errors: `none`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_atpanic

pub fn atPanic(lua: *Lua, panic_fn: CFn) ?CFn {

if (lang == .luau) @compileError(@src().fn_name ++ " is not implemented in Luau.");

return c.lua_atpanic(@ptrCast(lua), panic_fn);

}

pub const CallArgs = struct {

/// The number of args passed to the function from the stack

args: i32 = 0,

/// The number of results the function pushes to the stack upon returning

results: i32 = 0,

};

/// Calls a function

///

/// Like regular Lua calls, `Lua.call()` respects the `__call` metamethod. So, here the word "function" means any callable value.

///

/// To do a call you must use the following protocol:

/// * First, the function to be called is pushed onto the stack

/// * Then, the arguments to the call are pushed in direct order that is, the first argument is pushed first.

/// * Finally you call `Lua.call()`

/// * `args.args` is the number of arguments that you pushed onto the stack. When the function returns, all arguments and

/// the function value are popped and the call results are pushed onto the stack.

/// * The number of results is adjusted to `args.results`, unless `args.results` is `zlua.mult_return`. In this case, all results from the function are pushed

/// * Lua takes care that the returned values fit into the stack space, but it does not ensure any extra space in the stack. The function results

/// are pushed onto the stack in direct order (the first result is pushed first), so that after the call the last result is

/// on the top of the stack.

///

/// Any error while calling and running the function is propagated upwards (with a longjmp).

///

/// * Pops from Stack: `(args.args+1)`

/// * Pushes to Stack: `args.results`

/// * Lua Runtime Errors: `any`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_call

pub fn call(lua: *Lua, args: CallArgs) void {

switch (lang) {

.lua51, .luajit, .luau => c.lua_call(@ptrCast(lua), args.args, args.results),

else => c.lua_callk(@ptrCast(lua), args.args, args.results, 0, null),

}

}

/// Continuations are supported in Lua 5.2, 5.3, and 5.4

/// See https://www.lua.org/manual/5.4/manual.html#4.5

pub const CallContArgs = struct {

/// The number of args passed to the function from the stack

args: i32 = 0,

/// The number of results the function pushes to the stack upon returning

results: i32 = 0,

/// Context value passed to the continuation function

ctx: switch (lang) {

.lua52 => i32,

.lua53, .lua54, .lua55 => Context,

else => void,

},

/// The continuation function

k: switch (lang) {

.lua52 => CFn,

.lua53, .lua54, .lua55 => CContFn,

else => void,

},

};

/// This function behaves exactly like `Lua.call()`, but allows the called function to yield

///

/// Not implemented in Lua 5.1, LuaJIT, or Luau

///

/// * Pops from Stack: `(args.args + 1)`

/// * Pushes to Stack: `args.results`

/// * Lua Runtime Errors: `any`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_callk

pub fn callCont(lua: *Lua, args: CallContArgs) void {

c.lua_callk(@ptrCast(lua), args.args, args.results, args.ctx, args.k);

}

/// Ensures that the stack has space for at least `n` extra elements, that is, that you can safely push up to `n` values into

/// it. It returns an error if it cannot fulfill the request, either because it would cause the stack to be greater than a

/// fixed maximum size (typically at least several thousand elements) or because it cannot allocate memory for the extra

/// space. This function never shrinks the stack; if the stack already has space for the extra elements, it is left

/// unchanged.

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `0`

/// * Lua Runtime Errors: `memory` (Lua 5.1, LuaJIT, Luau)

/// * Lua Runtime Errors: `none` (Lua 5.2, 5.3, 5.4)

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_checkstack

pub fn checkStack(lua: *Lua, n: i32) error{NoSpace}!void {

if (c.lua_checkstack(@ptrCast(lua), n) == 0) return error.NoSpace;

}

/// Close the to-be-closed slot at the given index and set its value to nil. The index must be the last index previously

/// marked to be closed (see `Lua.toClose()`) that is still active (that is, not closed yet).

/// A `__close` metamethod cannot yield when called through this function.

///

/// Only implemented in Lua 5.4

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `0`

/// * Lua Runtime Errors: `any`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_closeslot

pub fn closeSlot(lua: *Lua, index: i32) void {

c.lua_closeslot(@ptrCast(lua), index);

}

/// Resets a thread, cleaning its call stack and closing all pending to-be-closed variables. Returns an

/// error if an error occurs (either the original error that stopped the thread or errors in closing

/// methods) and leaves the error object on the top of the stack.

///

/// The parameter `from` represents the coroutine that is resetting `lua`. If there is no such coroutine, this parameter can be

/// `null`.

///

/// Only implemented in Lua 5.4 and 5.5

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `?`

/// * Lua Runtime Errors: `none`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_closethread

pub fn closeThread(lua: *Lua, from: ?*Lua) error{CallError}!void {

if (c.lua_closethread(@ptrCast(lua), if (from) |f| @ptrCast(f) else null) != StatusCode.ok) return error.CallError;

}

/// Compares two Lua values.

///

/// Returns `true` if the value at index `index1` satisfies `op` when compared with the value at index

/// `index2`, following the semantics of the corresponding Lua operator (that is, it may call metamethods). Otherwise returns

/// `false`. Also returns `false` if any of the indices is not valid.

///

/// Not implemented in Lua 5.1, LuaJIT, or Luau

///

/// * Pops from Stack: `0`

/// * Pushes to Stack: `0`

/// * Lua Runtime Errors: `any`

///

/// See https://www.lua.org/manual/5.4/manual.html#lua_compare

pub fn compare(lua: *Lua, index1: i32, index2: i32, op: CompareOperator) bool {

return c.lua_compare(@ptrCast(lua), index1, index2, @intFromEnum(op)) != 0;

}

/// Concatenates the `n` values at the top of the stack, pops them, and leaves the result at the top

/// If the number of values is 1, the result is a single value on the stack (nothing changes)

/// If the number of values is 0, the result is the empty string

///

/// * Pops from Stack: `n`