diff --git a/LUA_API.rst b/LUA_API.rst index e68a87a66..050714c72 100644 --- a/LUA_API.rst +++ b/LUA_API.rst @@ -209,7 +209,7 @@ Implemented features: * ``ref:insert(index,item)`` Inserts a new item at the specified index. To add at the end, - use ``#ref`` as index. + use ``#ref``, or just ``'#'`` as index. * ``ref:erase(index)`` @@ -428,6 +428,11 @@ Currently it defines the following features: If the thread owns the interactive console, shows a prompt and returns the entered string. Otherwise returns *nil, error*. + Depending on the context, this function may actually yield the + running coroutine and let the C++ code release the core suspend + lock. Using an explicit ``dfhack.with_suspend`` will prevent + this, forcing the function to block on input with lock held. + * ``dfhack.interpreter([prompt[,env[,history_filename]]])`` Starts an interactive lua interpreter, using the specified prompt @@ -449,6 +454,10 @@ Currently it defines the following features: Just like pcall, but also prints the error using printerr before returning. Intended as a convenience function. +* ``dfhack.saferesume(coroutine[,args...])`` + + Compares to coroutine.resume like dfhack.safecall vs pcall. + * ``dfhack.with_suspend(f[,args...])`` Calls ``f`` with arguments after grabbing the DF core suspend lock. @@ -813,3 +822,37 @@ Core context specific functions: * ``dfhack.is_core_context`` Boolean value; *true* in the core context. + +* ``dfhack.onStateChange.foo = function(code)`` + + Event. Receives the same codes as plugin_onstatechange in C++. + + +Event type +---------- + +An event is just a lua table with a predefined metatable that +contains a __call metamethod. When it is invoked, it loops +through the table with next and calls all contained values. +This is intended as an extensible way to add listeners. + +This type itself is available in any context, but only the +core context has the actual events defined by C++ code. + +Features: + +* ``dfhack.event.new()`` + + Creates a new instance of an event. + +* ``event[key] = function`` + + Sets the function as one of the listeners. + + **NOTE**: The ``df.NULL`` key is reserved for the use by + the C++ owner of the event, and has some special semantics. + +* ``event(args...)`` + + Invokes all listeners contained in the event in an arbitrary + order using ``dfhack.safecall``. diff --git a/Lua API.html b/Lua API.html index 38a375d86..cbf35f0eb 100644 --- a/Lua API.html +++ b/Lua API.html @@ -344,7 +344,10 @@ ul.auto-toc {
ref:insert(index,item)
Inserts a new item at the specified index. To add at the end, -use #ref as index.
+use #ref, or just '#' as index.ref:erase(index)
Removes the element at the given valid index.
@@ -705,6 +708,10 @@ works with DFHack output infrastructure.dfhack.lineedit([prompt[,history_filename]])
If the thread owns the interactive console, shows a prompt and returns the entered string. Otherwise returns nil, error.
+Depending on the context, this function may actually yield the +running coroutine and let the C++ code release the core suspend +lock. Using an explicit dfhack.with_suspend will prevent +this, forcing the function to block on input with lock held.
dfhack.interpreter([prompt[,env[,history_filename]]])
Starts an interactive lua interpreter, using the specified prompt @@ -722,6 +729,9 @@ in C++, and dfhack.safecall.
Just like pcall, but also prints the error using printerr before returning. Intended as a convenience function.
dfhack.saferesume(coroutine[,args...])
+Compares to coroutine.resume like dfhack.safecall vs pcall.
+dfhack.with_suspend(f[,args...])
Calls f with arguments after grabbing the DF core suspend lock. Suspending is necessary for accessing a consistent state of DF memory.
@@ -1021,9 +1031,36 @@ only context that can receive events from DF and plugins.dfhack.is_core_context
Boolean value; true in the core context.
dfhack.onStateChange.foo = function(code)
+Event. Receives the same codes as plugin_onstatechange in C++.
+An event is just a lua table with a predefined metatable that +contains a __call metamethod. When it is invoked, it loops +through the table with next and calls all contained values. +This is intended as an extensible way to add listeners.
+This type itself is available in any context, but only the +core context has the actual events defined by C++ code.
+Features:
+dfhack.event.new()
+Creates a new instance of an event.
+event[key] = function
+Sets the function as one of the listeners.
+NOTE: The df.NULL key is reserved for the use by +the C++ owner of the event, and has some special semantics.
+event(args...)
+Invokes all listeners contained in the event in an arbitrary +order using dfhack.safecall.
+