f3f89b8fc1
Also: - rename some files to remove redundant information from the filenames - rename many labels to match the filename and its place in the hierarchy - move lua_api under the scripting section
64 lines
2.0 KiB
ReStructuredText
64 lines
2.0 KiB
ReStructuredText
.. _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")
|