| 1 |
.. _lua_introduction: |
| 2 |
|
| 3 |
Introduction |
| 4 |
============ |
| 5 |
|
| 6 |
`Lua <https://www.lua.org/>`_ is a powerful, efficient, lightweight, |
| 7 |
embeddable scripting language. |
| 8 |
|
| 9 |
WirePlumber uses `Lua version 5.4 <https://www.lua.org/versions.html>`_ to |
| 10 |
implement its engine. For older systems, Lua 5.3 is also supported. |
| 11 |
|
| 12 |
Scripts can be ran with the ``wpexec`` tool. |
| 13 |
|
| 14 |
Example scripts can be found in the `tests/examples` directory of the wireplumber source tree. |
| 15 |
|
| 16 |
Lua Reference |
| 17 |
------------- |
| 18 |
|
| 19 |
If you are not familiar with the Lua language and its API, please refer to |
| 20 |
the `Lua 5.4 Reference Manual <https://www.lua.org/manual/5.4/manual.html>`_ |
| 21 |
|
| 22 |
Sandbox |
| 23 |
------- |
| 24 |
|
| 25 |
WirePlumber's scripting engine sandboxes the lua scripts to a safe environment. |
| 26 |
In this environment, the following rules apply: |
| 27 |
|
| 28 |
- Scripts are isolated from one another; global variables in one script |
| 29 |
are not visible from another, even though they are actually executed in |
| 30 |
the same ``lua_State`` |
| 31 |
|
| 32 |
- Tables that hold API methods are not writable. While this may sound strange, |
| 33 |
standard Lua allows you to change standard API, for instance |
| 34 |
``string.format = rogue_format`` is valid outside the sandbox. |
| 35 |
WirePlumber does not allow that. |
| 36 |
|
| 37 |
- The standard Lua API is limited to a subset of safe functions. For instance, |
| 38 |
functions that interact with the file system (io.*) and the process's state |
| 39 |
(ex.: os.exit) are **not** allowed. |
| 40 |
|
| 41 |
Here is a full list of Lua functions (and API tables) that are exposed: |
| 42 |
|
| 43 |
.. literalinclude:: ../../../../modules/module-lua-scripting/wplua/sandbox.lua |
| 44 |
:language: lua |
| 45 |
:lines: 27-30 |
| 46 |
|
| 47 |
- Object methods are not exposed in public tables. To call an object method |
| 48 |
you must use the method call syntax of Lua, i.e. ``object:method(params)`` |
| 49 |
|
| 50 |
The following, for instance, is **not** valid: |
| 51 |
|
| 52 |
.. code-block:: lua |
| 53 |
|
| 54 |
-- this will cause an exception |
| 55 |
local node = ... |
| 56 |
Node.send_command(node, "Suspend") |
| 57 |
|
| 58 |
The correct form is this: |
| 59 |
|
| 60 |
.. code-block:: lua |
| 61 |
|
| 62 |
local node = ... |
| 63 |
node:send_command("Suspend") |