ziglua

# Ziglua
[![shield showing current tests status](https://github.com/natecraddock/ziglua/actions/workflows/tests.yml/badge.svg)](https://github.com/natecraddock/ziglua/actions/workflows/tests.yml)
[![Discord](https://img.shields.io/discord/1196908820140671077?style=flat&logo=discord)](https://discord.com/invite/XpZqDFvAtK)

Zig bindings for the [Lua C API](https://www.lua.org/manual/5.5/manual.html#4). Ziglua currently supports the latest releases of Lua 5.1, 5.2, 5.3, 5.4, 5.5, [LuaJIT](https://luajit.org) and [Luau](https://luau-lang.org).

Ziglua can be used in two ways, either
* **embedded** to statically embed the Lua VM in a Zig program,
* or as a shared **module** to create Lua libraries that can be loaded at runtime in other Lua-based software.

In both cases, Ziglua will compile Lua from source and link against your Zig code making it easy to create software that integrates with Lua without requiring any system Lua libraries.

Ziglua `main` is kept up to date with Zig `master`. See the [`zig-0.15.2`](https://github.com/natecraddock/ziglua/tree/zig-0.15.2) branch for Zig 0.15.2 support.

## Documentation
Docs are automatically generated and contain a guide on getting started with ziglua. Most functions and public declarations are documented:
* [Ziglua Docs](https://natecraddock.github.io/ziglua/#zlua)

Example code is included in the [examples](https://github.com/natecraddock/ziglua/tree/main/examples) directory.
* Run an example with `zig build run-example-<name>`
* Install an example with `zig build install-example-<name>`

An additional example (`examples/lpeg`) shows how to compile and link a Lua module written in C like LPeg.

## Why use Ziglua?
Ziglua is a simple wrapper around the C API. Ziglua aims to mirror the [Lua C API](https://www.lua.org/manual/5.5/manual.html#4) as closely as possible, while improving ergonomics using Zig's features. For example:

* Zig error unions to require failure state handling
* Null-terminated slices instead of C strings
* Type-checked enums for parameters and return values
* Compiler-enforced checking of optional pointers
* Better types in many cases (e.g. `bool` instead of `int`)
* Comptime convenience functions to make binding creation easier

Nearly every function in the C API is exposed in Ziglua. Additional convenience functions like `toAny` and `pushAny` use comptime reflection to make the API easier to use.

## Integrating Ziglua in your project

Run `zig fetch --save git+https://github.com/natecraddock/ziglua` to add the most recent commit of ziglua to your `build.zig.zon` file.

Add a `#<tag>` to the url to use a specific tagged release or commit like `zig fetch --save git+https://github.com/natecraddock/ziglua#0.3.0`

Then in your `build.zig` file you can use the dependency.

```zig
pub fn build(b: *std.Build) void {
    // ... snip ...

    const lua_dep = b.dependency("zlua", .{
        .target = target,
        .optimize = optimize,
    });

    // ... snip ...

    // add the zlua modul