summaryrefslogtreecommitdiff
path: root/Lua API.html
diff options
context:
space:
mode:
authorAlexander Gavrilov2012-04-17 11:45:09 +0400
committerAlexander Gavrilov2012-04-17 11:45:09 +0400
commit3beb2ebf25b94736a3823c317f603a8fc8bd0f53 (patch)
tree3b1af8b380074ba53ff617ddb5177e82dbb83eb2 /Lua API.html
parent7946cafc8673401bcfa2ff2e116592755a0968f4 (diff)
downloaddfhack-3beb2ebf25b94736a3823c317f603a8fc8bd0f53.tar.gz
dfhack-3beb2ebf25b94736a3823c317f603a8fc8bd0f53.tar.bz2
dfhack-3beb2ebf25b94736a3823c317f603a8fc8bd0f53.tar.xz
Export the onStateChange event to core lua context & add some docs.
Diffstat (limited to 'Lua API.html')
-rw-r--r--Lua API.html39
1 files changed, 38 insertions, 1 deletions
diff --git a/Lua API.html b/Lua API.html
index 38a375d8..d5d849d9 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -344,7 +344,10 @@ ul.auto-toc {
<li><a class="reference internal" href="#maps-module" id="id18">Maps module</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#core-interpreter-context" id="id19">Core interpreter context</a></li>
+<li><a class="reference internal" href="#core-interpreter-context" id="id19">Core interpreter context</a><ul>
+<li><a class="reference internal" href="#event-type" id="id20">Event type</a></li>
+</ul>
+</li>
</ul>
</li>
</ul>
@@ -705,6 +708,10 @@ works with DFHack output infrastructure.</p>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.lineedit([prompt[,history_filename]])</span></tt></p>
<p>If the thread owns the interactive console, shows a prompt
and returns the entered string. Otherwise returns <em>nil, error</em>.</p>
+<p>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 <tt class="docutils literal">dfhack.with_suspend</tt> will prevent
+this, forcing the function to block on input with lock held.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.interpreter([prompt[,env[,history_filename]]])</span></tt></p>
<p>Starts an interactive lua interpreter, using the specified prompt
@@ -722,6 +729,9 @@ in C++, and dfhack.safecall.</p>
<p>Just like pcall, but also prints the error using printerr before
returning. Intended as a convenience function.</p>
</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.saferesume(coroutine[,args...])</span></tt></p>
+<p>Compares to coroutine.resume like dfhack.safecall vs pcall.</p>
+</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">dfhack.with_suspend(f[,args...])</span></tt></p>
<p>Calls <tt class="docutils literal">f</tt> with arguments after grabbing the DF core suspend lock.
Suspending is necessary for accessing a consistent state of DF memory.</p>
@@ -1021,9 +1031,36 @@ only context that can receive events from DF and plugins.</p>
<li><p class="first"><tt class="docutils literal">dfhack.is_core_context</tt></p>
<p>Boolean value; <em>true</em> in the core context.</p>
</li>
+<li><p class="first"><tt class="docutils literal">dfhack.onStateChange.foo = function(code)</tt></p>
+<p>Event. Receives the same codes as plugin_onstatechange in C++.</p>
+</li>
+</ul>
+<div class="section" id="event-type">
+<h3><a class="toc-backref" href="#id20">Event type</a></h3>
+<p>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.</p>
+<p>This type itself is available in any context, but only the
+core context has the actual events defined by C++ code.</p>
+<p>Features:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal">dfhack.event.new()</tt></p>
+<p>Creates a new instance of an event.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">event[key] = function</tt></p>
+<p>Sets the function as one of the listeners.</p>
+<p><strong>NOTE</strong>: The <tt class="docutils literal">df.NULL</tt> key is reserved for the use by
+the C++ owner of the event, and has some special semantics.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">event(args...)</span></tt></p>
+<p>Invokes all listeners contained in the event in an arbitrary
+order using <tt class="docutils literal">dfhack.safecall</tt>.</p>
+</li>
</ul>
</div>
</div>
</div>
+</div>
</body>
</html>