Introduction — WirePlumber 0.4.1 documentation

# Introduction

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

WirePlumber uses Lua version 5.3 to implement its engine. Another, more recent, version may be considered in the future, but do note that different Lua versions are not API-compatible and that will likely also affect WirePlumber’s Lua API.

There are currently two uses for Lua in WirePlumber:

> - To implement the scripting engine

> - To implement lua-based config files

This section is only documenting the API of the scripting engine

## Lua Reference

If you are not familiar with the Lua language and its API, please refer to the Lua 5.3 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 only to safe functions. Functions that interact with the file system, the lua modules system, the lua state, the process’s state, etc are not allowed.

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

>           _VERSION assert error    ipairs   next pairs  print
>           pcall    select tonumber tostring type xpcall

>           table utf8

>           math.abs   math.acos math.asin math.atan       math.ceil
>           math.cos   math.deg  math.exp  math.tointeger  math.floor      math.fmod
>           math.huge  math.ult  math.log  math.maxinteger math.mininteger math.max
>           math.min   math.modf math.pi   math.rad        math.random
>           math.sin   math.sqrt math.tan  math.type

>           string.byte string.char  string.find  string.format string.gmatch
>           string.gsub string.len   string.lower string.match  string.reverse
>           string.sub  string.upper

>           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")