# `AshLua`
[🔗](https://github.com/ash-project/ash_lua/blob/v0.1.0/lib/ash_lua.ex#L5)

AshLua exposes Ash actions to Lua scripts evaluated through the [`lua`](https://hex.pm/packages/lua)
Elixir package, ensuring a consistent actor / tenant / context are propagated into every Ash call.

The Lua surface is derived from `Ash.Info.Manifest.generate/1` — every public action becomes a
callable at `<domain>.<resource>.<action>` (names overridable via the `AshLua.Domain` and
`AshLua.Resource` DSL extensions).

## Example

    defmodule MyApp.Accounts do
      use Ash.Domain, otp_app: :my_app, extensions: [AshLua.Domain]

      resources do
        resource MyApp.Accounts.User
      end
    end

    defmodule MyApp.Accounts.User do
      use Ash.Resource,
        domain: MyApp.Accounts,
        extensions: [AshLua.Resource]

      # ... attributes / actions ...
    end

    AshLua.eval!("""
      local user, err = accounts.user.create({ name = "Zach" })
      assert(err == nil)
      return user.id
    """, otp_app: :my_app, actor: current_user)

Action callables always return `(result, nil)` on success and `(nil, err_table)` on failure.
Wrap a call in Lua's built-in `assert()` for raise semantics:

    local user = assert(accounts.user.create({ name = "Zach" }))

## Actor / tenant / context

All three are host-supplied via the eval opts and are never reflected to or mutable from the
script — there is no way for a Lua script to read or change the actor, tenant, or context.

# `eval!`

```elixir
@spec eval!(
  String.t(),
  keyword()
) :: {list(), Lua.t()}
```

Evaluates a Lua script in a freshly-built VM and returns `{results, %Lua{}}`.

## Options

  * `:otp_app` (required unless `:manifest` is given) — passed to `Ash.Info.Manifest.generate/1`.
  * `:actor`, `:tenant`, `:context` — host-supplied; merged into every Ash call.
  * `:manifest` — a pre-built `%Ash.Info.Manifest{}` to skip regeneration.
  * `:lua` — a pre-built `%Lua{}` to install bindings on (e.g. with extra `Lua.set!/3` callbacks).
  * `:decode` — forwarded to `Lua.eval!/3`; defaults to `true`.

# `new`

```elixir
@spec new(keyword()) :: Lua.t()
```

Builds a `%Lua{}` VM with Ash bindings installed, ready for repeated `Lua.eval!/2` calls.

Accepts the same `:otp_app` / `:actor` / `:tenant` / `:context` / `:manifest` / `:lua`
options as `eval!/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*