MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document the lua class module.

develop
Alexander Gavrilov 2012-09-21 15:21:04 +04:00
parent c5101b2ea4
commit 7a06c949c7
2 changed files with 161 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
LUA_API.rst
Unescape Escape View File

@ -1831,6 +1831,86 @@ function:
argument specifies the indentation step size in spaces. For
the other arguments see the original documentation link above.
class
=====
Implements a trivial single-inheritance class system.
* ``Foo = defclass(Foo[, ParentClass])``
Defines or updates class Foo. The ``Foo = defclass(Foo)`` syntax
is needed so that when the module or script is reloaded, the
class identity will be preserved through the preservation of
global variable values.
The ``defclass`` function is defined as a stub in the global
namespace, and using it will auto-load the class module.
* ``Class.super``
This class field is set by defclass to the parent class, and
allows a readable ``Class.super.method(self, ...)`` syntax for
calling superclass methods.
* ``Class.ATTRS { foo = xxx, bar = yyy }``
Declares certain instance fields to be attributes, i.e. auto-initialized
from fields in the table used as the constructor argument. If omitted,
they are initialized with the default values specified in this declaration.
If the default value should be *nil*, use ``ATTRS { foo = DEFAULT_NIL }``.
* ``new_obj = Class{ foo = arg, bar = arg, ... }``
Calling the class as a function creates and initializes a new instance.
Initialization happens in this order:
1. An empty instance table is created, and its metatable set.
2. The ``preinit`` method is called via ``invoke_before`` (see below)
with the table used as argument to the class. This method is intended
for validating and tweaking that argument table.
3. Declared ATTRS are initialized from the argument table or their default values.
4. The ``init`` method is called via ``invoke_after`` with the argument table.
This is the main constructor method.
5. The ``postinit`` method is called via ``invoke_after`` with the argument table.
Place code that should be called after the object is fully constructed here.
Predefined instance methods:
* ``instance:assign{ foo = xxx }``
Assigns all values in the input table to the matching instance fields.
* ``instance:callback(method_name, [args...])``
Returns a closure that invokes the specified method of the class,
properly passing in self, and optionally a number of initial arguments too.
The arguments given to the closure are appended to these.
* ``instance:invoke_before(method_name, args...)``
Navigates the inheritance chain of the instance starting from the most specific
class, and invokes the specified method with the arguments if it is defined in
that specific class. Equivalent to the following definition in every class::
function Class:invoke_before(method, ...)
if rawget(Class, method) then
rawget(Class, method)(self, ...)
end
Class.super.invoke_before(method, ...)
end
* ``instance:invoke_after(method_name, args...)``
Like invoke_before, only the method is called after the recursive call to super,
i.e. invocations happen in the parent to child order.
These two methods are inspired by the Common Lisp before and after methods, and
are intended for implementing similar protocols for certain things. The class
library itself uses them for constructors.
To avoid confusion, these methods cannot be redefined.
=======
Plugins

89
Lua API.html
Unescape Escape View File

@ -366,14 +366,15 @@ ul.auto-toc {
<li><a class="reference internal" href="#global-environment" id="id32">Global environment</a></li>
<li><a class="reference internal" href="#utils" id="id33">utils</a></li>
<li><a class="reference internal" href="#dumper" id="id34">dumper</a></li>
<li><a class="reference internal" href="#class" id="id35">class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugins" id="id35">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id36">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id37">sort</a></li>
<li><a class="reference internal" href="#plugins" id="id36">Plugins</a><ul>
<li><a class="reference internal" href="#burrows" id="id37">burrows</a></li>
<li><a class="reference internal" href="#sort" id="id38">sort</a></li>
</ul>
</li>
<li><a class="reference internal" href="#scripts" id="id38">Scripts</a></li>
<li><a class="reference internal" href="#scripts" id="id39">Scripts</a></li>
</ul>
</div>
<p>The current version of DFHack has extensive support for
@ -1930,16 +1931,88 @@ the other arguments see the original documentation link above.</p>
</li>
</ul>
</div>
<div class="section" id="class">
<h2><a class="toc-backref" href="#id35">class</a></h2>
<p>Implements a trivial single-inheritance class system.</p>
<ul>
<li><p class="first"><tt class="docutils literal">Foo = defclass(Foo[, ParentClass])</tt></p>
<p>Defines or updates class Foo. The <tt class="docutils literal">Foo = defclass(Foo)</tt> syntax
is needed so that when the module or script is reloaded, the
class identity will be preserved through the preservation of
global variable values.</p>
<p>The <tt class="docutils literal">defclass</tt> function is defined as a stub in the global
namespace, and using it will auto-load the class module.</p>
</li>
<li><p class="first"><tt class="docutils literal">Class.super</tt></p>
<p>This class field is set by defclass to the parent class, and
allows a readable <tt class="docutils literal">Class.super.method(self, <span class="pre">...)</span></tt> syntax for
calling superclass methods.</p>
</li>
<li><p class="first"><tt class="docutils literal">Class.ATTRS { foo = xxx, bar = yyy }</tt></p>
<p>Declares certain instance fields to be attributes, i.e. auto-initialized
from fields in the table used as the constructor argument. If omitted,
they are initialized with the default values specified in this declaration.</p>
<p>If the default value should be <em>nil</em>, use <tt class="docutils literal">ATTRS { foo = DEFAULT_NIL }</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">new_obj = Class{ foo = arg, bar = arg, ... }</tt></p>
<p>Calling the class as a function creates and initializes a new instance.
Initialization happens in this order:</p>
<ol class="arabic simple">
<li>An empty instance table is created, and its metatable set.</li>
<li>The <tt class="docutils literal">preinit</tt> method is called via <tt class="docutils literal">invoke_before</tt> (see below)
with the table used as argument to the class. This method is intended
for validating and tweaking that argument table.</li>
<li>Declared ATTRS are initialized from the argument table or their default values.</li>
<li>The <tt class="docutils literal">init</tt> method is called via <tt class="docutils literal">invoke_after</tt> with the argument table.
This is the main constructor method.</li>
<li>The <tt class="docutils literal">postinit</tt> method is called via <tt class="docutils literal">invoke_after</tt> with the argument table.
Place code that should be called after the object is fully constructed here.</li>
</ol>
</li>
</ul>
<p>Predefined instance methods:</p>
<ul>
<li><p class="first"><tt class="docutils literal">instance:assign{ foo = xxx }</tt></p>
<p>Assigns all values in the input table to the matching instance fields.</p>
</li>
<li><p class="first"><tt class="docutils literal">instance:callback(method_name, <span class="pre">[args...])</span></tt></p>
<p>Returns a closure that invokes the specified method of the class,
properly passing in self, and optionally a number of initial arguments too.
The arguments given to the closure are appended to these.</p>
</li>
<li><p class="first"><tt class="docutils literal">instance:invoke_before(method_name, <span class="pre">args...)</span></tt></p>
<p>Navigates the inheritance chain of the instance starting from the most specific
class, and invokes the specified method with the arguments if it is defined in
that specific class. Equivalent to the following definition in every class:</p>
<pre class="literal-block">
function Class:invoke_before(method, ...)
if rawget(Class, method) then
rawget(Class, method)(self, ...)
end
Class.super.invoke_before(method, ...)
end
</pre>
</li>
<li><p class="first"><tt class="docutils literal">instance:invoke_after(method_name, <span class="pre">args...)</span></tt></p>
<p>Like invoke_before, only the method is called after the recursive call to super,
i.e. invocations happen in the parent to child order.</p>
<p>These two methods are inspired by the Common Lisp before and after methods, and
are intended for implementing similar protocols for certain things. The class
library itself uses them for constructors.</p>
</li>
</ul>
<p>To avoid confusion, these methods cannot be redefined.</p>
</div>
</div>
<div class="section" id="plugins">
<h1><a class="toc-backref" href="#id35">Plugins</a></h1>
<h1><a class="toc-backref" href="#id36">Plugins</a></h1>
<p>DFHack plugins may export native functions and events
to lua contexts. They are automatically imported by
<tt class="docutils literal"><span class="pre">mkmodule('plugins.&lt;name&gt;')</span></tt>; this means that a lua
module file is still necessary for <tt class="docutils literal">require</tt> to read.</p>
<p>The following plugins have lua support.</p>
<div class="section" id="burrows">
<h2><a class="toc-backref" href="#id36">burrows</a></h2>
<h2><a class="toc-backref" href="#id37">burrows</a></h2>
<p>Implements extended burrow manipulations.</p>
<p>Events:</p>
<ul>
@ -1977,13 +2050,13 @@ set is the same as used by the command line.</p>
<p>The lua module file also re-exports functions from <tt class="docutils literal">dfhack.burrows</tt>.</p>
</div>
<div class="section" id="sort">
<h2><a class="toc-backref" href="#id37">sort</a></h2>
<h2><a class="toc-backref" href="#id38">sort</a></h2>
<p>Does not export any native functions as of now. Instead, it
calls lua code to perform the actual ordering of list items.</p>
</div>
</div>
<div class="section" id="scripts">
<h1><a class="toc-backref" href="#id38">Scripts</a></h1>
<h1><a class="toc-backref" href="#id39">Scripts</a></h1>
<p>Any files with the .lua extension placed into hack/scripts/*
are automatically used by the DFHack core as commands. The
matching command name consists of the name of the file sans