69 lines
2.2 KiB
ReStructuredText
69 lines
2.2 KiB
ReStructuredText
.. _lua_introduction:
|
|
|
|
Introduction
|
|
============
|
|
|
|
`Lua <https://www.lua.org/>`_ is a powerful, efficient, lightweight,
|
|
embeddable scripting language.
|
|
|
|
WirePlumber uses `Lua version 5.3 <https://www.lua.org/versions.html>`_ 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 :ref:`config files <daemon-configuration>`
|
|
|
|
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 <https://www.lua.org/manual/5.3/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 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:
|
|
|
|
.. literalinclude:: ../../../lib/wplua/sandbox.lua
|
|
:language: lua
|
|
:lines: 40-55
|
|
|
|
- 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")
|