1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
.. _lua_introduction:
Introduction
============
`Lua <https://www.lua.org/>`_ is a powerful, efficient, lightweight,
embeddable scripting language.
WirePlumber uses `Lua version 5.4 <https://www.lua.org/versions.html>`_ 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 <https://www.lua.org/manual/5.4/manual.html>`_
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:
.. literalinclude:: ../../../../modules/module-lua-scripting/wplua/sandbox.lua
:language: lua
:lines: 27-30
- 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:
.. code-block:: lua
-- this will cause an exception
local node = ...
Node.send_command(node, "Suspend")
The correct form is this:
.. code-block:: lua
local node = ...
node:send_command("Suspend")
|
