View Source Lua.API behaviour (Lua v0.0.17)
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, a Lua.Chunk.t/0
, 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 chunk directly using the c
modifier
on Lua.sigil_LUA/2
defmodule WithLua do
use Lua.API, scope: "whoa"
import Lua
@impl Lua.API
def install(_lua) do
~LUA[print("Hello at install time!")]c
end
end
Summary
Functions
Defines a function that can be exposed in Lua through Lua.load_api/3
Raises a runtime exception inside an API function, displaying contextual information about where the exception was raised.
Callbacks
@callback scope() :: [String.t()]
Functions
See deflua/3
Defines a function that can be exposed in Lua through Lua.load_api/3
deflua add_two(number) do
number + 2
end
Accessing state
Sometimes, you may want to access or modify the Lua environment in a deflua
. This
can be done by using the following syntax
deflua get_value(key), state do
# Access the Lua environment
Lua.get!(lua, [key])
end
To modify and return new state, return a tuple
deflua set_value(key, value), state do
# Return nothing but modify the state
{[], Lua.set!(lua, [key])}
end
Variadic functions
Technically, all Lua functions are variadic, which means they can receive
a variable number of arguments. As a convenience, Lua
applies your arguments to
deflua
functions so that they can be written in idiomatic Elixir.
If you need to handle variadic arguments, annotate the function with the @variadic
module attribute.
@variadic true
deflua print(args) do
IO.puts(Enum.join(args, " "))
end
@variadic behavior
When using the
@variadic
attribute, note that it is per-function.Lua
will reset this attribute after every function definition, so there is no need to manually reset it yourself
Raises a runtime exception inside an API function, displaying contextual information about where the exception was raised.