==========
Module lua
==========

.. lua:module:: lua

Lua scripting

**Accessing deai modules**

All deai modules is available under the global lua table named "di", such as
:code:`di.lua`, etc.

**Representation of deai objects**

In lua, a :lua:mod:`~deai.plugin.lua.Proxy` is created for each deai objects, which
function like normal lua tables. Properties and methods are accessible as table
entries. Note methods should be called like a lua method, i.e.
:code:`obj:method(...)`.

**Receiving signals**

Use the :lua:meth:`~deai.plugin.lua.Proxy.on` methods from the proxy to register
listeners on signals.

**Quirks**

In lua there's only table, there's no such thing as an array. To decide if a table is
an arraay deai will first check if it has integer 1 as a key, then the length of the
array is determined to be the largest contiguous integer key following 1, then deai
check if all these keys map to elements with the same type. If all passes, then that
table becomes a deai array.

Additionally, we don't know what exactly to do with an empty table. Should it be a
table or an array? Right now, it's treated as a table, thus translates to an object in
deai. So if you want to pass an empty array as argument, you would have to pass "nil".

See :lua:meth:`dbus <dbus>`, :lua:meth:`evdev <evdev>`, :lua:meth:`event <event>`, :lua:meth:`file <file>`, :lua:meth:`hwinfo <hwinfo>`, :lua:meth:`log <log>`, :lua:meth:`lua <lua>`, :lua:meth:`misc <misc>`, :lua:meth:`os <os>`, :lua:meth:`spawn <spawn>`, :lua:meth:`udev <udev>`, :lua:meth:`xorg <xorg>` for more information about this type

Properties
==========

.. list-table::
   :header-rows: 0

   * - :lua:attr:`globals <globals>`
     - Get the global variables from loaded lua scripts

.. lua:attribute:: globals: Globals

   :type: :lua:mod:`Globals <deai.plugin.lua.Globals>`

   Get the global variables from loaded lua scripts 

   This object is an accessor to all global variables in the loaded lua scripts. Each
   global variable is accessible as a property with the same name of this object.

Methods
==========

.. list-table::
   :header-rows: 0

   * - :lua:meth:`as_di_object(obj) <as_di_object>`
     - Convert a lua table to a di_object
   * - :lua:meth:`load_script(path) <load_script>`
     - Load a lua script

.. lua:method:: as_di_object(obj) -> object

   :rtype: object
   :type obj: object
   :param obj:

   Convert a lua table to a di_object 

   This is intended to be called from lua scripts. It converts a lua table to a
   di_object. It is kind of useless when called from outside lua, since what it does is
   just returning the object passed to it. The real magic is the inner workings of the
   lua plugin which allows external functions to be called from lua scripts.

.. lua:method:: load_script(path) -> tuple

   :rtype: tuple
   :param path: path to the script
   :type path: string

   Load a lua script 

   Load and execute a lua script. Returns whatever the script returns as a tuple.