# Introduction

Lua is a powerful, efficient, lightweight, embeddable scripting language.

WirePlumber uses Lua version 5.4 to implement its engine. For older systems, Lua 5.3 is also supported.

Scripts can be ran with the `wpexec` tool.

Example scripts can be found in the tests/examples directory of the wireplumber source tree.

## Lua Reference

If you are not familiar with the Lua language and its API, please refer to the Lua 5.4 Reference Manual

## Sandbox

WirePlumber's scripting engine sandboxes the lua scripts to a safe environment. In this environment, the following rules apply:

> - Scripts are isolated from one another; global variables in one script are not visible from another, even though they are actually executed in the same `lua_State`

> - Tables that hold API methods are not writable. While this may sound strange, standard Lua allows you to change standard API, for instance `string.format = rogue_format` is valid outside the sandbox. WirePlumber does not allow that.

> - The standard Lua API is limited to a subset of safe functions. For instance, functions that interact with the file system (io.*) and the process's state (ex.: os.exit) are not allowed.

>   Here is a full list of Lua functions (and API tables) that are exposed:

>           ([[ _VERSION assert error ipairs   next pairs  tonumber
>               pcall    select print tostring type xpcall require
>               table    string math  package  utf8 debug  coroutine
>               os.clock  os.difftime os.time  os.date     os.getenv

> - Object methods are not exposed in public tables. To call an object method you must use the method call syntax of Lua, i.e. `object:method(params)`

>   The following, for instance, is not valid:

>       -- this will cause an exception
>       local node = ...
>       Node.send_command(node, "Suspend")

>   The correct form is this:

>       local node = ...
>       node:send_command("Suspend")