diff options
| -rw-r--r-- | LUA_API.rst | 80 | ||||
| -rw-r--r-- | Lua API.html | 89 |
2 files changed, 161 insertions, 8 deletions
diff --git a/LUA_API.rst b/LUA_API.rst index d9b75c48..b098aa05 100644 --- a/LUA_API.rst +++ b/LUA_API.rst @@ -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 diff --git a/Lua API.html b/Lua API.html index 0da65b5f..f30bb6ec 100644 --- a/Lua API.html +++ b/Lua API.html @@ -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.<name>')</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 |
