Debian Codegraph @

docs/rst/scripting/lua_api/lua_introduction.rst

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