From 3beb2ebf25b94736a3823c317f603a8fc8bd0f53 Mon Sep 17 00:00:00 2001
From: Alexander Gavrilov
Date: Tue, 17 Apr 2012 11:45:09 +0400
Subject: [PATCH 1/2] Export the onStateChange event to core lua context & add
some docs.
---
LUA_API.rst | 43 ++++++++++++++++++++++++
Lua API.html | 39 +++++++++++++++++++++-
library/LuaTools.cpp | 58 ++++++++++++++++++++++++++-------
library/PluginManager.cpp | 2 ++
library/include/LuaTools.h | 3 ++
library/include/PluginManager.h | 14 ++++----
library/lua/dfhack.lua | 11 +++++++
7 files changed, 151 insertions(+), 19 deletions(-)
diff --git a/LUA_API.rst b/LUA_API.rst
index e68a87a66..1a38c4edc 100644
--- a/LUA_API.rst
+++ b/LUA_API.rst
@@ -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..d5d849d91 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -344,7 +344,10 @@ ul.auto-toc {
Maps module
-Core interpreter context
+Core interpreter context
+
@@ -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.
+
+