Defines the Behaviour for defining a Lua API

To create a module that exports functions to the global scope

defmodule MyAPI do
  use Lua.API

  # Can be called via `print("hi")` in lua
  deflua print(msg), do: IO.puts msg
end

Optionally, you can provide a scope

defmodule SpecificAPI do
  use Lua.API, scope: "namespace.domain"

  # Can be called via `namespace.domain.foo(5)` in lua
  deflua foo(v), do: v
end

You can access Lua state

defmodule State do
  use Lua.API

  deflua bar(name), state do
    # Pull's the value of `number` out of state
    val = Lua.get!(state, [:number])

    2 * val
  end
end

Regular functions are not exported

defmodule SpecificAPI do
  use Lua.API

  # Won't be exposed
  def baz(v), do: v
end

Installing an API

A Lua.API can provide an optional install/1 callback, which can run arbitrary Lua code or change the Lua state in any way.

An install/1 callback takes a Lua.t/0 and should either return a Lua script to be evaluated, or return a new Lua.t/0

defmodule WithInstall do
  use Lua.API, scope: "install"

  @impl Lua.API
  def install(lua) do
    Lua.set!(lua, [:foo], "bar")
  end
end

If you don't need to write Elixir, but want to execute some Lua to setup global variables, modify state, or expose some additonal APIs, you can simply return a Lua script directly

defmodule WithLua do
  use Lua.API, scope: "whoa"

  import Lua

  @impl Lua.API
  def install(_lua) do
    ~LUA[print("Hello at install time!")]
  end
end