Merge branch 'ui_pairs' into 'master'

Implement pairs and ipairs for ui.content and ui.layers. Document all iterable types in a uniform way.

See merge request OpenMW/openmw!1643

docs/source/reference/lua-scripting/api.rst

@@ -25,6 +25,7 @@ Lua API reference
     openmw_aux_time
     interface_ai
     interface_camera
+    iterables
 
 
 - :ref:`Engine handlers reference`

docs/source/reference/lua-scripting/iterables.rst

@@ -0,0 +1,50 @@
+Iterable types
+==============
+
+List Iterable
+-------------
+
+An iterable with defined size and order.
+
+.. code-block:: Lua
+
+   -- can iterate over the list with pairs
+   for i, v in pairs(list) do
+   -- ...
+   end
+
+.. code-block:: Lua
+
+   -- can iterate over the list with ipairs
+   for i, v in ipairs(list) do
+   -- ...
+   end
+
+.. code-block:: Lua
+
+   -- can get total size with the size # operator
+   local length = #list
+
+.. code-block:: Lua
+
+   -- can index the list with numbers
+   for i = 1, length do
+   list[i]
+   end
+
+Map Iterable
+------------
+
+An iterable with undefined order.
+
+.. code-block:: Lua
+
+   -- can iterate over the map with pairs
+   for k, v in pairs(map) do
+   -- ...
+   end
+
+.. code-block:: Lua
+
+   -- can index the map by key
+   map[key]

docs/source/reference/lua-scripting/overview.rst

@@ -498,7 +498,7 @@ At some moment it will send the 'DamagedByDarkPower' event to all nearby actors:
     local nearby = require('openmw.nearby')
 
     local function onActivated()
-        for i, actor in nearby.actors:ipairs() do
+        for i, actor in ipairs(nearby.actors) do
             local dist = (self.position - actor.position):length()
             if dist < 500 then
                 local damage = (1 - dist / 500) * 200