lua.carp

(defmodule String
  (defn from-cstr-or [cs default] (if (null? cs) default (from-cstr cs))))

(register-type Lua "lua_State")

(defndynamic luax--make-push-calls [lua push-exprs]
  (if (empty? push-exprs)
    '()
    (let [expr (car push-exprs)
          call (cons (car expr) (cons lua (cdr expr)))]
      (cons `(ignore %call) (luax--make-push-calls lua (cdr push-exprs))))))

(defndynamic luax--make-field-stmts [lua field-specs]
  (if (empty? field-specs)
    '()
    (let [spec (car field-specs)
          field-name (car spec)
          push-expr (cadr spec)
          call (cons (car push-expr) (cons lua (cdr push-expr)))]
      (cons
        `(do
          (ignore %call)
          (Lua.set-field %lua -2 (cstr %(Symbol.str field-name))))
        (luax--make-field-stmts lua (cdr field-specs))))))

(defndynamic luax--to-c-ident [s]
  (if (= (Dynamic.String.length s) 0)
    ""
    (let [ch (Dynamic.String.slice s 0 1)
          rest (Dynamic.String.slice s 1 (Dynamic.String.length s))
          repl (cond
            (= ch "-") "_MINUS_"
            (= ch ".") "_"
            (= ch "?") "_QMARK_"
            (= ch "!") "_BANG_"
            ch)]
      (Dynamic.String.concat [repl (luax--to-c-ident rest)]))))

(defndynamic luax--fn-c-name [sym]
  (Dynamic.String.concat ["luax_cfn_" (luax--to-c-ident (Symbol.str sym))]))

(defmacro luax--def-maybe-get [suffix type-const getter article type-article]
  (let [fn-name (Symbol.concat ['maybe-get- suffix])
        doc-str (Dynamic.String.concat
          ["Read the value at `index` as "
           article
           ", returning `Nothing` if it is not "
           type-article
           ". Leaves the stack unchanged."])]
    `(do
      (doc %fn-name %doc-str)
      (defn %fn-name [lua index]
        (if (= (Lua.type-of lua index) %type-const)
          (Maybe.Just (%getter lua index))
          (Maybe.Nothing))))))

(defmacro luax--def-set-global [suffix pusher]
  (let [fn-name (Symbol.concat ['set- suffix '-global])]
    `(do
      (doc %fn-name "Push `value` and assign it to the global `name`.")
      (defn %fn-name [lua name value]
        (do (%pusher lua value) (Lua.set-global lua (cstr name)))))))

(defmacro luax--def-get-global [suffix article type-article]
  (let [fn-name (Symbol.concat ['get- suffix '-global])
        maybe-get (Symbol.concat ['maybe-get- suffix])
        doc-str (Dynamic.String.concat
          ["Fetch the global `name` as "
           article
           ". Returns `Nothing` if the global is nil or not "
           type-article
           ". Pops the global from the stack internally."])]
    `(do
      (doc %fn-name %doc-str)
      (defn %fn-name [lua name]
        (do
          (Lua.get-global lua (cstr name))
          (let-do [result (%maybe-get lua -1)] (Lua.pop lua 1) result))))))

(defmacro luax--def-set-field [suffix pusher]
  (let [fn-name (Symbol.concat ['set- suffix '-field])]
    `(do
      (doc %fn-name
        "Set field `name` to `value` on the table at `index`. Handles the stack index shift from pushing the value internally.")
      (defn %fn-name [lua index name value]
        (do
          (%pusher lua value)
          (Lua.set-field lua (if (< index 0) (- index 1) index) (cstr name)))))))

(defmacro luax--def-get-field [suffix article type-article]
  (let [fn-name (Symbol.concat ['get- suffix '-field])
        maybe-get (Symbol.concat ['maybe-get- suffix])
        doc-str (Dynamic.String.concat
          ["Read field `name` from the table at `index` as "
           article
           ". Returns `Nothing` if the field is nil or not "
           type-article
           ". Pops the field value from the stack internally, leaving only the table."])]
    `(do
      (doc %fn-name %doc-str)
      (defn %fn-name [lua index name]
        (do
          (ignore (Lua.get-field lua index (cstr name)))
          (let-do [result (%maybe-get lua -1)] (Lua.pop lua 1) result))))))

(defmodule Lua
  (doc OK "Status code returned on success.")
  (register OK Int "LUA_OK")
  (doc RUNTIME_ERROR "Status code returned when a runtime error occurs.")
  (register RUNTIME_ERROR Int "LUA_ERRRUN")
  (doc MEMORY_ERROR "Status code returned when a memory allocation fails.")
  (register MEMORY_ERROR Int "LUA_ERRMEM")
  (doc HANDLER_ERROR "Status code returned when the error handler itself fails.")
  (register HANDLER_ERROR Int "LUA_ERRERR")
  (doc GC_ERROR
    "Status code returned when the garbage collector metamethod fails.")
  (register GC_ERROR Int "LUA_ERRGCMM")
  (doc YIELD "Status code returned when a coroutine yields.")
  (register YIELD Int "LUA_YIELD")

  (doc setup "Set up Lua includes and linking. `location` is the include path
(e.g. `\"lua\"` or `\"lua5.4\"`). An optional second argument overrides the
library name for linking (defaults to `\"lua\"`).")
  (defndynamic setup [location :rest cflag]
    (eval
      `(do
        (system-include %(Dynamic.String.concat [location "/lua.h"]))
        (system-include %(Dynamic.String.concat [location "/lauxlib.h"]))
        (system-include %(Dynamic.String.concat [location "/lualib.h"]))
        (add-cflag
          %(Dynamic.String.concat
            ["-l" (if (> (length cflag) 0) (car cflag) "lua")])))))

  (doc new "Create a new Lua state. Must be closed with [`close`](#close) when
done, or use [`with-lua-do`](#with-lua-do) to manage the lifecycle
automatically.")
  (register new (Fn [] &Lua) "luaL_newstate")
  (doc libs "Open all standard Lua libraries in the given state.")
  (register libs (Fn [&Lua] ()) "luaL_openlibs")
  (doc close "Close a Lua state and free all associated resources.")
  (register close (Fn [&Lua] ()) "lua_close")

  (doc pop "Remove `n` elements from the top of the stack.")
  (register pop (Fn [&Lua Int] ()) "lua_pop")
  (doc push-bool "Push a boolean onto the stack.")
  (register push-bool (Fn [&Lua Bool] ()) "lua_pushboolean")
  (doc push-global-table "Push the global table onto the stack.")
  (register push-global-table (Fn [&Lua] ()) "lua_pushglobaltable")
  (doc push-int "Push an integer onto the stack.")
  (register push-int (Fn [&Lua Int] ()) "lua_pushinteger")
  (doc push-light-user-data "Push a light userdata pointer onto the stack.")
  (register push-light-user-data (Fn [&Lua (Ptr ())] ()) "lua_pushlightuserdata")
  (doc push-nil "Push nil onto the stack.")
  (register push-nil (Fn [&Lua] ()) "lua_pushnil")
  (doc push-double "Push a double (Lua number) onto the stack.")
  (register push-double (Fn [&Lua Double] ()) "lua_pushnumber")
  (doc push-float "Push a float onto the stack as a Lua number.")
  (defn push-float [lua f] (push-double lua (Double.from-float f)))
  (doc push-string "Push a C string onto the stack. For Carp strings, use
[`push-carp-str`](#push-carp-str) instead.")
  (deftemplate push-string
               (Fn [&Lua (Ptr CChar)] (Ptr CChar))
               "char* $NAME(lua_State* l, const char* s)"
               "$DECL { return (char*) lua_pushstring(l, s); }")
  (doc push-thread "Push the current thread onto the stack.")
  (register push-thread (Fn [&Lua] ()) "lua_pushthread")
  (doc push-copy
    "Push a copy of the element at `index` onto the top of the stack.")
  (register push-copy (Fn [&Lua Int] ()) "lua_pushvalue")
  (doc get-global "Push the value of the named global onto the stack.")
  (register get-global (Fn [&Lua (Ptr CChar)] ()) "lua_getglobal")
  (doc set-global
    "Pop the top value from the stack and set it as the named global.")
  (register set-global (Fn [&Lua (Ptr CChar)] ()) "lua_setglobal")
  (doc get-top "Return the index of the top element, which equals the number of
elements on the stack.")
  (register get-top (Fn [&Lua] Int) "lua_gettop")
  (doc get-bool "Read the value at `index` as a boolean.")
  (register get-bool (Fn [&Lua Int] Bool) "lua_toboolean")
  (doc get-int "Read the value at `index` as an integer. Does not check the
type—use [`Luax.maybe-get-int`](#maybe-get-int) for a safe version.")
  (register get-int (Fn [&Lua Int] Int) "lua_tointeger")
  (doc get-double "Read the value at `index` as a double. Does not check the
type—use [`Luax.maybe-get-double`](#maybe-get-double) for a safe version.")
  (register get-double (Fn [&Lua Int] Double) "lua_tonumber")
  (doc get-float "Read the value at `index` as a float. Lua numbers are doubles,
so this narrows; use [`get-double`](#get-double) instead. Does not check the
type—use [`Luax.maybe-get-float`](#maybe-get-float) for a safe version.")
  (defn get-float [lua index] (Double.to-float (get-double lua index)))
  (doc get-string "Read the value at `index` as a C string pointer. Returns a
raw pointer; prefer [`Luax.get-carp-str`](#get-carp-str) or
[`Luax.maybe-get-string`](#maybe-get-string) for safe access.")
  (register get-string (Fn [&Lua Int] (Ptr CChar)) "lua_tostring")
  (doc get-user-data "Read the value at `index` as a userdata pointer.")
  (register get-user-data (Fn [&Lua Int] (Ptr ())) "lua_touserdata")

  (doc load-buffer "Load a Lua chunk from a buffer without executing it. Returns
a status code.")
  (register load-buffer
    (Fn [&Lua (Ptr CChar) Int (Ptr CChar)] Int)
    "luaL_loadbuffer")
  (doc call "Call a function on the stack with `nargs` arguments and `nresults`
expected results. The last argument is the error handler stack index (0 for
none). Returns a status code; use [`Luax.call-fn`](#call-fn) for a safer
interface.")
  (register call (Fn [&Lua Int Int Int] Int) "lua_pcall")
  (doc do-string "Compile and execute a Lua string. Returns a status code.
Use [`Luax.do-in`](#do-in) for a version that returns `Result`.")
  (register do-string (Fn [&Lua (Ptr CChar)] Int) "luaL_dostring")

  (doc TYPE_NIL "Type constant for nil values.")
  (register TYPE_NIL Int "LUA_TNIL")
  (doc TYPE_BOOLEAN "Type constant for boolean values.")
  (register TYPE_BOOLEAN Int "LUA_TBOOLEAN")
  (doc TYPE_NUMBER "Type constant for numeric values (both integer and float).")
  (register TYPE_NUMBER Int "LUA_TNUMBER")
  (doc TYPE_STRING "Type constant for string values.")
  (register TYPE_STRING Int "LUA_TSTRING")
  (doc TYPE_TABLE "Type constant for table values.")
  (register TYPE_TABLE Int "LUA_TTABLE")
  (doc TYPE_FUNCTION "Type constant for function values.")
  (register TYPE_FUNCTION Int "LUA_TFUNCTION")
  (doc TYPE_USERDATA "Type constant for full userdata values.")
  (register TYPE_USERDATA Int "LUA_TUSERDATA")
  (doc TYPE_LIGHTUSERDATA "Type constant for light userdata values.")
  (register TYPE_LIGHTUSERDATA Int "LUA_TLIGHTUSERDATA")
  (doc TYPE_THREAD "Type constant for thread (coroutine) values.")
  (register TYPE_THREAD Int "LUA_TTHREAD")
  (doc type-of
    "Return the type constant of the value at `index`. Compare against
`TYPE_NIL`, `TYPE_NUMBER`, etc.")
  (register type-of (Fn [&Lua Int] Int) "lua_type")

  (doc create-table
    "Push a new empty table onto the stack. `narr` and `nrec` are
size hints for the array and hash parts.")
  (register create-table (Fn [&Lua Int Int] ()) "lua_createtable")
  (doc set-field "Pop the top value and set it as field `name` on the table at
`index`. Note: pushing a value shifts relative stack indices, so if the table
is at -1, use -2 as the index after pushing. See [`Luax.set-int-field`](#set-int-field)
and friends for a safer interface.")
  (register set-field (Fn [&Lua Int (Ptr CChar)] ()) "lua_setfield")
  (doc get-field "Push the value of field `name` from the table at `index` onto
the stack. Returns a type constant.")
  (register get-field (Fn [&Lua Int (Ptr CChar)] Int) "lua_getfield")
  (doc set-table
    "Pop a key and value from the stack and set them on the table at
`index`. The value must be on top, with the key below it.")
  (register set-table (Fn [&Lua Int] ()) "lua_settable")
  (doc get-table "Pop a key from the stack and push the corresponding value from
the table at `index`. Returns a type constant.")
  (register get-table (Fn [&Lua Int] Int) "lua_gettable")
  (doc next "Pop a key and push the next key-value pair from the table at
`index`. Returns 0 when there are no more entries. Used for iterating tables
with [`push-nil`](#push-nil) as the initial key.")
  (register next (Fn [&Lua Int] Int) "lua_next")

  (doc raw-get
    "Like [`get-table`](#get-table) but bypasses metamethods. Pops the
key from the stack and pushes the value. Returns the type of the result.")
  (register raw-get (Fn [&Lua Int] Int) "lua_rawget")
  (doc raw-set
    "Like [`set-table`](#set-table) but bypasses metamethods. Pops both
the key and the value from the stack.")
  (register raw-set (Fn [&Lua Int] ()) "lua_rawset")
  (doc raw-geti
    "Push `t[n]` onto the stack without invoking metamethods, where `t`
is the table at `index`. Returns the type of the result.")
  (register raw-geti (Fn [&Lua Int Int] Int) "lua_rawgeti")
  (doc raw-seti "Pop the top value and set it as `t[n]` without invoking
metamethods, where `t` is the table at `index`.")
  (register raw-seti (Fn [&Lua Int Int] ()) "lua_rawseti")
  (doc raw-len "Return the raw length of the value at `index` (table, string, or
full userdata) without invoking the `__len` metamethod.")
  (deftemplate raw-len
               (Fn [&Lua Int] Int)
               "int $NAME(lua_State* l, int i)"
               "$DECL { return (int) lua_rawlen(l, i); }")

  (doc get-metatable "Push the metatable of the value at `index` onto the stack.
Returns `true` if the value has a metatable, `false` otherwise (and nothing is
pushed).")
  (register get-metatable (Fn [&Lua Int] Bool) "lua_getmetatable")
  (doc set-metatable "Pop the table from the top of the stack and set it as the
metatable for the value at `index`.")
  (deftemplate set-metatable
               (Fn [&Lua Int] ())
               "void $NAME(lua_State* l, int i)"
               "$DECL { lua_setmetatable(l, i); }")
  (doc new-metatable
    "Create or look up a named metatable in the Lua registry and
push it onto the stack. Returns `true` if a new table was created, `false` if
the name already existed. Either way the metatable is on top of the stack
afterward.")
  (register new-metatable (Fn [&Lua (Ptr CChar)] Bool) "luaL_newmetatable")
  (doc set-named-metatable
    "Set the metatable of the value on top of the stack to
the metatable associated with `name` in the registry. The value remains on the
stack.")
  (register set-named-metatable (Fn [&Lua (Ptr CChar)] ()) "luaL_setmetatable")

  (doc new-userdata "Allocate `size` bytes as a full userdata, push it onto the
stack, and return a pointer to the allocated block. The userdata is
garbage-collected by Lua. Use [`set-metatable`](#set-metatable) or
[`set-named-metatable`](#set-named-metatable) to attach a metatable.")
  (deftemplate new-userdata
               (Fn [&Lua Int] (Ptr ()))
               "void* $NAME(lua_State* l, int sz)"
               "$DECL { return lua_newuserdata(l, (size_t) sz); }")
  (doc check-userdata "Return a pointer to the userdata at `index` if it has the
metatable `name` from the registry. Raises a Lua error otherwise (catchable with
[`call`](#call)).")
  (register check-userdata
    (Fn [&Lua Int (Ptr CChar)] (Ptr ()))
    "luaL_checkudata")
  (doc test-userdata
    "Like [`check-userdata`](#check-userdata) but returns a null
pointer instead of raising a Lua error when the check fails.")
  (register test-userdata (Fn [&Lua Int (Ptr CChar)] (Ptr ())) "luaL_testudata")

  ; === Coroutines ===

  (doc new-thread "Create a new coroutine as a thread of the given state. Pushes
the new thread onto the stack and returns a pointer to it. The coroutine shares
the global environment with the parent but has its own execution stack. Do not
call [`close`](#close) on the returned thread—it is garbage-collected by the
parent state.")
  (register new-thread (Fn [&Lua] &Lua) "lua_newthread")
  (doc coroutine-status "Return the status of a coroutine: [`OK`](#OK) if the
coroutine has not started or finished successfully, [`YIELD`](#YIELD) if it is
suspended, or an error code if it terminated with an error.")
  (register coroutine-status (Fn [&Lua] Int) "lua_status")
  (doc is-yieldable? "Return `true` if the given coroutine can yield.")
  (deftemplate is-yieldable?
               (Fn [&Lua] Bool)
               "bool $NAME(lua_State* l)"
               "$DECL { return lua_isyieldable(l); }")
  (doc resume "Resume a suspended coroutine. Before the first resume, push the
function to call onto the coroutine’s stack; on subsequent resumes, push values
to return from [`yield`](#yield). `nargs` is the number of values pushed.
`from` is the calling state. Returns [`OK`](#OK) when the coroutine finishes,
[`YIELD`](#YIELD) when it suspends, or an error code. Results are left on the
coroutine’s stack.")
  (deftemplate resume
               (Fn [&Lua &Lua Int] Int)
               "int $NAME(lua_State* co, lua_State* from, int nargs)"
               "$DECL { int nres; return lua_resume(co, from, nargs, &nres); }")
  (doc yield "Yield the current coroutine with `nresults` values from the top of
the stack. Can only be used as the return expression of a C function registered
with [`prepare-cfunction`](#prepare-cfunction).")
  (deftemplate yield
               (Fn [&Lua Int] Int)
               "int $NAME(lua_State* l, int n)"
               "$DECL { return lua_yield(l, n); }")
  (doc to-thread "Read the value at `index` as a `Lua` state pointer. Returns a
null pointer if the value is not a thread.")
  (deftemplate to-thread
               (Fn [&Lua Int] &Lua)
               "lua_State* $NAME(lua_State* l, int i)"
               "$DECL { return lua_tothread(l, i); }")

  (doc do-file "Load and execute a Lua file. Returns a status code. Use
[`eval-file`](#eval-file) for a version that returns `Result`.")
  (deftemplate do-file
               (Fn [&Lua (Ptr CChar)] Int)
               "int $NAME(lua_State* l, const char* f)"
               "$DECL { return luaL_dofile(l, f); }")

  (doc to-string "Read the value at `index` as a C string pointer. Low-level
alias; prefer [`Luax.get-carp-str`](#get-carp-str).")
  (deftemplate to-string
               (Fn [&Lua Int] (Ptr CChar))
               "char* $NAME(Lua* l, int i)"
               "$DECL { return (char*) lua_tostring(l, i); }")

  (doc with-lua-as "Create a Lua state bound to `name`, evaluate `body`, then
close the state. Returns the result of `body`.

```
(Lua.with-lua-as L
  (do (Lua.libs L) (Lua.do-string L (cstr \"print('hi')\"))))
```")
  (defmacro with-lua-as [name body]
    (let [s (gensym)] `(let-do [%name (Lua.new)
                                %s %body] (Lua.close %name) %s)))

  (doc with-lua
    "Like [`with-lua-as`](#with-lua-as) but binds the state to `lua`.")
  (defmacro with-lua [body] `(Lua.with-lua-as lua %body))

  (doc with-lua-do "Like [`with-lua`](#with-lua) but wraps multiple body forms
in a `do` block. This is the most common entry point.

```
(Lua.with-lua-do
  (Lua.libs lua)
  (Lua.push-int lua 42)
  (IO.println &(str (Lua.get-int lua -1))))
```")
  (defmacro with-lua-do [:rest body] `(Lua.with-lua-as lua %(cons 'do body)))

  (doc evaluate "Create a temporary Lua state, evaluate the expression `s`, and
return its string representation as a `Result`. Useful for one-off evaluations
without managing a state manually.

```
(match (Lua.evaluate \"1 + 2\")
  (Result.Success v) (IO.println &v)
  (Result.Error e) (IO.errorln &e))
```")
  (defn evaluate [s]
    (Lua.with-lua-do (libs lua)
                     (let [code (do-string lua
                                           (cstr &(fmt "return tostring(%s);" s)))
                           res (from-cstr-or (to-string lua -1) @"")]
                       ((if (/= OK code) Result.Error Result.Success) res))))

  (doc push-carp-str "Push a Carp `String` reference onto the Lua stack. Wraps
[`push-string`](#push-string) with automatic `cstr` conversion.")
  (defn push-carp-str [lua s] (ignore (push-string lua (cstr s))))

  (doc set-string-global "Push `s` and assign it to the global `name`. For other
types, see [`Luax.set-int-global`](#set-int-global) and friends.")
  (defn set-string-global [lua name s]
    (do (push-carp-str lua s) (set-global lua (cstr name))))

  (doc get-string-global "Fetch the global `name` and return it as a Carp
`String`. Returns an empty string if the global is nil or not a string. Pops the
global from the stack internally. For a safe version returning `Maybe`, see
[`Luax.get-string-global`](#get-string-global).")
  (defn get-string-global [lua name]
    (do
      (get-global lua (cstr name))
      (let-do [result (String.from-cstr-or (to-string lua -1) @"")]
        (pop lua 1)
        result)))

  (doc global-exists? "Check whether the global `name` is defined (non-nil).
Pushes and pops internally, leaving the stack unchanged.")
  (defn global-exists? [lua name]
    (do
      (get-global lua (cstr name))
      (let-do [exists (/= (type-of lua -1) TYPE_NIL)] (pop lua 1) exists)))

  (doc eval-file
    "Load and execute the Lua file at `path`. Returns `(Success \"\")`
on success or `(Error msg)` with the Lua error message on failure. Leaves the
stack unchanged in both cases.")
  (sig eval-file (Fn [&Lua &String] (Result String String)))
  (defn eval-file [lua path]
    (let [res (do-file lua (cstr path))]
      (if (= res OK)
        (Result.Success @"")
        (let-do [err (String.from-cstr-or (to-string lua -1) @"unknown error")]
          (pop lua 1)
          (Result.Error err)))))

  (doc table-length "Count the entries in the table at `index` by iterating with
[`next`](#next). Returns -1 if the value at `index` is not a table. Leaves the
stack unchanged.")
  (defn table-length [lua index]
    (if (/= (type-of lua index) TYPE_TABLE)
      -1
      (do
        (push-nil lua)
        (let-do [count 0]
          (while-do (/= 0 (next lua (if (< index 0) (- index 1) index)))
            (set! count (+ count 1))
            (pop lua 1))
          count))))

  (doc val "Evaluate the Lua expression `value` and assign the result to the
global `name`. Returns `OK` on success. On failure the Lua error object is
discarded, leaving the stack unchanged; use [`Luax.do-in`](#do-in) if you need
the message.

```
(Lua.val lua \"pi\" \"3.14159\")
```")
  (defn val [lua name value]
    (let-do [res (Lua.do-string lua (cstr &(fmt "return %s" value)))]
      (if (= res Lua.OK) (Lua.set-global lua (cstr name)) (Lua.pop lua 1))
      res))

  (doc fun "Define a Lua function from a Carp macro call. `name` becomes a Lua
global, `args` is a list of parameter names, and `body` is the Lua source.

```
(Lua.fun lua add [x y] \"return x + y\")
```")
  (defmacro fun [lua name args body]
    (list 'Lua.val
          lua
          (Symbol.str name)
          (String.concat
            ["function("
             (if (empty? args)
               ""
               (Dynamic.reduce
                 (fn [acc s] (String.concat [acc "," (Symbol.str s)]))
                 (Symbol.str (car args))
                 (cdr args)))
             ") "
             body
             " end"])))

  (doc prepare-cfunction "Declare a Carp function as pushable onto a Lua stack.
Must be called at the top level, before any use of
[`push-cfunction`](#push-cfunction) or [`register-fn`](#register-fn) with this
function. The function must be a top-level `defn` with signature
`(Fn [&Lua] Int)`.

```
(defn square [l]
  (let [x (Lua.get-int l 1)]
    (do (Lua.push-int l (* x x)) 1)))

(Lua.prepare-cfunction square)
```")
  (defmacro prepare-cfunction [fn-sym]
    (let [cfn (luax--fn-c-name fn-sym)
          helper (Symbol.concat ['luax--push-cfn-- fn-sym])
          the-type '(Fn [(Ref Lua)] ())]
      `(do
        (c-name %fn-sym %cfn)
        (deftemplate %helper
                     %the-type
                     %(Dynamic.String.concat
                       ["int " cfn "(lua_State*); void $NAME(lua_State* l)"])
                     %(Dynamic.String.concat
                       ["$DECL { lua_pushcfunction(l, " cfn "); }"])))))

  (doc push-cfunction "Push a prepared Carp function onto the Lua stack as a
C function. The function must have been declared with
[`prepare-cfunction`](#prepare-cfunction) at the top level first.

```
(defn square [l]
  (let [x (Lua.get-int l 1)]
    (do (Lua.push-int l (* x x)) 1)))

(Lua.prepare-cfunction square)

(Lua.with-lua-do
  (Lua.push-cfunction lua square)
  (Lua.set-global lua (cstr \"square\")))
```")
  (defmacro push-cfunction [lua fn-sym]
    (let [helper (Symbol.concat ['luax--push-cfn-- fn-sym])] `(%helper %lua)))

  (doc register-fn "Register a Carp function as a Lua global, making it callable
from Lua scripts. The function must have been declared with
[`prepare-cfunction`](#prepare-cfunction) at the top level first. `name` is the
Lua-side name (a symbol).

The function must be a top-level `defn` with signature `(Fn [&Lua] Int)`:
it receives arguments via the Lua stack (1-indexed from the bottom) and
must return the number of results pushed.

```
(defn my-add [l]
  (let [a (Lua.get-int l 1)
        b (Lua.get-int l 2)]
    (do (Lua.push-int l (+ a b)) 1)))

(Lua.prepare-cfunction my-add)

(Lua.with-lua-do
  (Lua.libs lua)
  (Lua.register-fn lua add my-add)
  (ignore (Lua.do-string lua (cstr \"print(add(3, 4))\"))))
```")
  (defmacro register-fn [lua name fn-sym]
    `(do
      (Lua.push-cfunction %lua %fn-sym)
      (Lua.set-global %lua (cstr %(Symbol.str name))))))

(doc Lua "provides bindings for embedding Lua in Carp. It wraps the Lua C API
directly, following its stack-based model: you push values onto a virtual stack,
call Lua operations, and read results back from the stack.

All interaction starts with a Lua state. Use [`with-lua-do`](#with-lua-do) to
create one, do work, and close it automatically. Call [`libs`](#libs) to make
the Lua standard library available.

```
(Lua.with-lua-do
  (Lua.libs lua)
  (ignore (Lua.do-string lua (cstr \"print('hello from lua')\"))))
```

Values are passed between Carp and Lua through the stack. Push values with
[`push-int`](#push-int), [`push-double`](#push-double),
[`push-bool`](#push-bool), [`push-carp-str`](#push-carp-str), etc. Read them
back with [`get-int`](#get-int), [`get-double`](#get-double), and so on, using
negative indices to address from the top of the stack (-1 is the top element).

```
; push two values, read the top one
(Lua.push-int lua 42)
(Lua.push-double lua 3.14)
(let [d (Lua.get-double lua -1)   ; 3.14
      i (Lua.get-int lua -2)]     ; 42
  (Lua.pop lua 2))
```

A Lua number is a C double. [`push-float`](#push-float) widens exactly, but
[`get-float`](#get-float) narrows on the way back, so a number read through it
loses everything past single precision and anything above the float range comes
back as an infinity.

To call a Lua function at the low level, push the function, then its arguments,
then use [`call`](#call) with the argument and result counts. The result
replaces the function and arguments on the stack.

```
(Lua.get-global lua (cstr \"math\"))
(ignore (Lua.get-field lua -1 (cstr \"sqrt\")))
(Lua.push-double lua 9.0)
(ignore (Lua.call lua 1 1 0))
(IO.println &(str (Lua.get-double lua -1)))  ; 3.0
(Lua.pop lua 2)  ; pop result and math table
```

Tables are built by creating an empty table with [`create-table`](#create-table),
setting fields with [`set-field`](#set-field), and optionally assigning the
table to a global with [`set-global`](#set-global). Raw table access
([`raw-get`](#raw-get), [`raw-set`](#raw-set), [`raw-geti`](#raw-geti),
[`raw-seti`](#raw-seti)) bypasses metamethods for direct table manipulation.

Metatables enable object-oriented patterns and operator overloading. Use
[`new-metatable`](#new-metatable) to create a named metatable in the registry,
[`set-metatable`](#set-metatable) to attach it to a table or userdata, and
[`get-metatable`](#get-metatable) to retrieve it.

Full userdata ([`new-userdata`](#new-userdata)) allocates GC-managed memory on
the Lua side, useful for exposing Carp-created objects to Lua scripts with
metatables for method dispatch.

Coroutines are created with [`new-thread`](#new-thread), which returns a new
execution context sharing the parent’s globals. Push a function onto the
coroutine’s stack, then drive it with [`resume`](#resume). The coroutine
yields values back via `coroutine.yield()` (Lua side) or [`yield`](#yield)
(C function side, tail-call only). Check [`coroutine-status`](#coroutine-status)
or the return value of `resume` ([`OK`](#OK) vs [`YIELD`](#YIELD)) to
distinguish completion from suspension.

```
(Lua.with-lua-do
  (Lua.libs lua)
  (ignore (Lua.do-string lua
    (cstr \"function gen() coroutine.yield(1); return 2 end\")))
  (let [co (Lua.new-thread lua)]
    (do
      (Lua.get-global co (cstr \"gen\"))
      (ignore (Lua.resume co lua 0))       ; yields 1
      (IO.println &(str (Lua.get-int co -1)))
      (Lua.pop co 1)
      (ignore (Lua.resume co lua 0))       ; returns 2
      (IO.println &(str (Lua.get-int co -1))))))
```

The module also provides convenience macros: [`fun`](#fun) defines a Lua
function from inline source, [`val`](#val) evaluates a Lua expression into
a global, and [`register-fn`](#register-fn) registers a Carp function as a
Lua global so that Lua scripts can call back into Carp:

```
(defn double-it [l]
  (let [x (Lua.get-int l 1)]
    (do (Lua.push-int l (* x 2)) 1)))

(Lua.prepare-cfunction double-it)

(Lua.with-lua-do
  (Lua.libs lua)
  (Lua.register-fn lua double double-it)
  (ignore (Lua.do-string lua (cstr \"print(double(21))\"))))
```

For higher-level functions that handle type checking and error
wrapping automatically, see [`Luax`](#Luax).")

(doc Luax "provides a safe, higher-level interface over [`Lua`](#Lua). Where the
`Lua` module returns raw values and status codes, `Luax` returns `Maybe` and
`Result` types, manages stack cleanup internally, and provides macros that
reduce boilerplate for common patterns.

**Safe stack access.** The `maybe-get-*` family type-checks before reading and
returns `Nothing` on mismatch, so you never get garbage from reading the wrong
type:

```
(Lua.push-int lua 42)
(match (Luax.maybe-get-int lua -1)
  (Maybe.Just n) (IO.println &(fmt \"got %d\" n))
  (Maybe.Nothing) (IO.errorln \"not a number\"))
(match (Luax.maybe-get-string lua -1)
  (Maybe.Just _) ()  ; won't match — it's an int
  (Maybe.Nothing) (IO.println \"correctly rejected\"))
(Lua.pop lua 1)
```

**Globals.** `set-*-global` and `get-*-global` handle the push/pop cycle for
you. The getters return `Maybe` and clean up the stack regardless of success:

```
(Luax.set-int-global lua \"score\" 100)
(Luax.set-bool-global lua \"debug\" true)
(match (Luax.get-int-global lua \"score\")
  (Maybe.Just n) (IO.println &(fmt \"score: %d\" n))
  (Maybe.Nothing) (IO.errorln \"missing\"))
```

**Table fields.** `get-*-field` reads a field from a table already on the stack
and pops the field value afterward, so you can read multiple fields in sequence
without manual stack management. `set-*-field` handles the index shift from
pushing the value:

```
(Lua.get-global lua (cstr \"player\"))
(match (Luax.get-string-field lua -1 \"name\")
  (Maybe.Just name) (IO.println &name)
  (Maybe.Nothing) (IO.errorln \"no name\"))
(match (Luax.get-int-field lua -1 \"hp\")
  (Maybe.Just hp) (IO.println &(fmt \"hp: %d\" hp))
  (Maybe.Nothing) (IO.errorln \"no hp\"))
(Luax.set-int-field lua -1 \"hp\" 0)
(Lua.pop lua 1)
```

**Calling functions.** [`call-fn`](#call-fn) looks up a global function, pushes
arguments, calls it, and reads the result — returning `(Error msg)` if the
function is undefined or raises a Lua error:

```
(match (Luax.call-fn lua add Lua.get-int
         (Lua.push-int 3) (Lua.push-int 4))
  (Result.Success v) (IO.println &(fmt \"3 + 4 = %d\" v))
  (Result.Error e) (IO.errorln &e))
```

**Building tables.** [`make-table`](#make-table) creates a table, sets fields,
and assigns it to a global in one expression:

```
(Luax.make-table lua point
  (x (Lua.push-int 10))
  (y (Lua.push-int 20)))
; point is now a Lua global with fields x=10, y=20
```

**Code execution.** [`do-in`](#do-in) wraps [`Lua.do-string`](#do-string) with
`Result` error handling:

```
(match (Luax.do-in lua \"x = 1 + nil\")
  (Result.Success _) ()
  (Result.Error e) (IO.println &(fmt \"caught: %s\" &e)))
```

**Coroutines.** [`resume-coroutine`](#resume-coroutine) wraps
[`Lua.resume`](#resume) with `Result` error handling, and
[`coroutine-suspended?`](#coroutine-suspended?) /
[`coroutine-finished?`](#coroutine-finished?) provide status predicates:

```
(let [co (Lua.new-thread lua)]
  (do
    (Lua.get-global co (cstr \"gen\"))
    (match (Luax.resume-coroutine co lua 0)
      (Result.Success status)
        (when (= status Lua.YIELD)
          (IO.println &(str (Lua.get-int co -1))))
      (Result.Error e) (IO.errorln &e))))
```")

(defmodule Luax
  (doc get-carp-str "Read the value at `index` as a Carp `String`, using Lua's
`tostring` coercion. Returns an empty string if the conversion fails.")
  (defn get-carp-str [lua index]
    (String.from-cstr-or (Lua.to-string lua index) @""))

  (luax--def-maybe-get double
                       Lua.TYPE_NUMBER
                       Lua.get-double
                       "a double"
                       "a number")
  (luax--def-maybe-get float Lua.TYPE_NUMBER Lua.get-float "a float" "a number")
  (luax--def-maybe-get bool
                       Lua.TYPE_BOOLEAN
                       Lua.get-bool
                       "a boolean"
                       "a boolean")
  (luax--def-maybe-get string
                       Lua.TYPE_STRING
                       get-carp-str
                       "a Carp `String`"
                       "a string")

  (defn- exact-int [d]
    (if (and (>= d (Double.from-int Int.MIN))
             (<= d (Double.from-int Int.MAX))
             (= d (Double.floor d)))
      (Maybe.Just (Double.to-int d))
      (Maybe.Nothing)))

  (doc maybe-get-int "Read the value at `index` as an integer, returning
`Nothing` if it is not a whole number that fits in an `Int`. Leaves the stack
unchanged.")
  (defn maybe-get-int [lua index]
    (Maybe.and-then (maybe-get-double lua index) &exact-int))

  (doc maybe-get-userdata "Read the value at `index` as a userdata pointer,
returning `Nothing` if it is not a full or light userdata. Leaves the stack
unchanged.")
  (defn maybe-get-userdata [lua index]
    (let [t (Lua.type-of lua index)]
      (if (or (= t Lua.TYPE_USERDATA) (= t Lua.TYPE_LIGHTUSERDATA))
        (Maybe.Just (Lua.get-user-data lua index))
        (Maybe.Nothing))))

  (luax--def-set-global int Lua.push-int)
  (luax--def-set-global double Lua.push-double)
  (luax--def-set-global float Lua.push-float)
  (luax--def-set-global bool Lua.push-bool)
  ; `string` is defined explicitly rather than via luax--def-set-global: the
  ; macro's eval-generated defn fails to bind when a sibling `Lua.set-string-global`
  ; already exists. int/float/bool have no such name collision.
  (doc set-string-global "Push `value` and assign it to the global `name`.")
  (defn set-string-global [lua name value]
    (do (Lua.push-carp-str lua value) (Lua.set-global lua (cstr name))))

  (luax--def-get-global int "an integer" "a whole number that fits in an `Int`")
  (luax--def-get-global double "a double" "a number")
  (luax--def-get-global float "a float" "a number")
  (luax--def-get-global bool "a boolean" "a boolean")
  ; `string` defined explicitly for the same reason as set-string-global above.
  (doc get-string-global
    "Fetch the global `name` as a Carp `String`. Returns `Nothing` if the global is nil or not a string. Pops the global from the stack internally.")
  (defn get-string-global [lua name]
    (do
      (Lua.get-global lua (cstr name))
      (let-do [result (if (= (Lua.type-of lua -1) Lua.TYPE_STRING)
                 (Maybe.Just (get-carp-str lua -1))
                 (Maybe.Nothing))]
        (Lua.pop lua 1)
        result)))

  (luax--def-set-field int Lua.push-int)
  (luax--def-set-field double Lua.push-double)
  (luax--def-set-field float Lua.push-float)
  (luax--def-set-field bool Lua.push-bool)
  (luax--def-set-field string Lua.push-carp-str)

  (luax--def-get-field int "an integer" "a whole number that fits in an `Int`")
  (luax--def-get-field double "a double" "a number")
  (luax--def-get-field float "a float" "a number")
  (luax--def-get-field bool "a boolean" "a boolean")
  (luax--def-get-field string "a Carp `String`" "a string")

  (doc do-in
    "Compile and execute the Lua string `code`. Returns `(Success \"\")`
on success or `(Error msg)` with the Lua error message on failure. Wraps
[`Lua.do-string`](#do-string) with `Result` handling, leaving the stack
unchanged in both cases.")
  (sig do-in (Fn [&Lua &String] (Result String String)))
  (defn do-in [lua code]
    (let [res (Lua.do-string lua (cstr code))]
      (if (= res Lua.OK)
        (Result.Success @"")
        (let-do [err (String.from-cstr-or (Lua.to-string lua -1)
                                          @"unknown error")]
          (Lua.pop lua 1)
          (Result.Error err)))))

  (doc call-fn "Call the Lua function `name` and read the result with `getter`.
Arguments are passed as push expressions—the `lua` state argument is inserted
automatically. Returns `(Error msg)` if the function is undefined or if the
call raises a Lua error.

```
(Luax.call-fn lua add Lua.get-int
  (Lua.push-int 3)
  (Lua.push-int 4))
```")
  (defmacro call-fn [lua name getter :rest push-exprs]
    (let [nargs (length push-exprs)
          pushes (luax--make-push-calls lua push-exprs)
          result-sym (gensym)
          error-str (Dynamic.String.concat
            ["undefined function: " (Symbol.str name)])]
      `(do
        (Lua.get-global %lua (cstr %(Symbol.str name)))
        (if (= (Lua.type-of %lua -1) Lua.TYPE_NIL)
          (do (Lua.pop %lua 1) (Result.Error @%error-str))
          (do
            %@pushes
            (let [%result-sym (Lua.call %lua %nargs 1 0)]
              (if (= %result-sym Lua.OK)
                (let-do [res (%getter %lua -1)]
                  (Lua.pop %lua 1)
                  (Result.Success res))
                (let-do [err (String.from-cstr-or (Lua.to-string %lua -1)
                                                  @"unknown error")]
                  (Lua.pop %lua 1)
                  (Result.Error err)))))))))

  (doc make-table "Create a Lua table with the given fields and assign it to the
global `name`. Each field spec is `(field-name (push-expr))`, where the `lua`
state argument is inserted into the push expression automatically.

```
(Luax.make-table lua player
  (name (Lua.push-carp-str \"Ada\"))
  (hp (Lua.push-int 100)))
```")
  (defmacro make-table [lua name :rest field-specs]
    (let [n (length field-specs)
          stmts (luax--make-field-stmts lua field-specs)]
      `(do
        (Lua.create-table %lua 0 %n)
        %@stmts
        (Lua.set-global %lua (cstr %(Symbol.str name))))))

  ; === Coroutine helpers ===

  (doc coroutine-suspended?
    "Return `true` if the coroutine is suspended (has yielded).")
  (defn coroutine-suspended? [co] (= (Lua.coroutine-status co) Lua.YIELD))

  (doc coroutine-finished?
    "Return `true` if the coroutine has finished or has not yet started.")
  (defn coroutine-finished? [co] (= (Lua.coroutine-status co) Lua.OK))

  (doc resume-coroutine
    "Resume the coroutine `co` from state `from` with `nargs`
arguments already pushed onto `co`’s stack. Returns `(Success status)` where
`status` is [`OK`](#OK) (coroutine finished) or [`YIELD`](#YIELD) (coroutine
suspended), or `(Error msg)` if the coroutine raised an error. Results or
yielded values are left on `co`’s stack.")
  (sig resume-coroutine (Fn [&Lua &Lua Int] (Result Int String)))
  (defn resume-coroutine [co from nargs]
    (let [status (Lua.resume co from nargs)]
      (if (or (= status Lua.OK) (= status Lua.YIELD))
        (Result.Success status)
        (Result.Error
          (String.from-cstr-or (Lua.to-string co -1) @"coroutine error"))))))