Add docs for the lua wrapper.

develop
Alexander Gavrilov 2012-04-02 22:00:38 +04:00
parent a8fe0eccb4
commit 59d1971df1
1 changed files with 299 additions and 0 deletions

@ -0,0 +1,299 @@
##############
DFHack Lua API
##############
.. contents::
====================
DF structure wrapper
====================
DF structures described by the xml files in library/xml are exported
to lua code as a tree of objects and functions under the ``df`` global,
which broadly maps to the ``df`` namespace in C++.
**WARNING**: The wrapper provides almost raw access to the memory
of the game, so mistakes in manipulating objects are as likely to
crash the game as equivalent plain C++ code would be. E.g. NULL
pointer access is safely detected, but dangling pointers aren't.
Objects managed by the wrapper can be broadly classified into the following groups:
1. Typed object pointers (references).
References represent objects in DF memory with a known type.
In addition to fields and methods defined by the wrapped type,
every reference has some built-in properties and methods.
2. Untyped pointers
Represented as lightuserdata.
In assignment to a pointer NULL can be represented either as
``nil``, or a NULL lightuserdata; reading a NULL pointer field
returns ``nil``.
3. Named types
Objects in the ``df`` tree that represent identity of struct, class,
enum and bitfield types. They host nested named types, static
methods, builtin properties & methods, and, for enums and bitfields,
the bi-directional mapping between key names and values.
4. The ``global`` object
``df.global`` corresponds to the ``df::global`` namespace, and
behaves as a mix between a named type and a reference, containing
both nested types and fields corresponding to global symbols.
In addition to the ``global`` object and top-level types the ``df``
global also contains a few global builtin utility functions.
Typed object references
=======================
The underlying primitive lua object is userdata with a metatable.
Every structured field access produces a new userdata instance.
All typed objects have the following built-in features:
* ``ref1 == ref2``, ``tostring(ref)``
References implement equality by type & pointer value, and string conversion.
* ``pairs(ref)``
Returns an iterator for the sequence of actual C++ field names
and values. Fields are enumerated in memory order. Methods and
lua wrapper properties are not included in the iteration.
* ``ref._kind``
Returns one of: ``primitive``, ``struct``, ``container``,
or ``bitfield``, as appropriate for the referenced object.
* ``ref._type``
Returns the named type object or a string that represents
the referenced object type.
* ``ref:sizeof()``
Returns *size, address*
* ``ref:new()``
Allocates a new instance of the same type, and copies data
from the current object.
* ``ref:delete()``
Destroys the object with the C++ ``delete`` operator.
If destructor is not available, returns *false*.
**WARNING**: the lua reference object remains as a dangling
pointer, like a raw C++ pointer would.
* ``ref:assign(object)``
Assigns data from object to ref. Object must either be another
ref of a compatible type, or a lua table; in the latter case
special recursive assignment rules are applied.
* ``ref:_displace(index[,step])``
Returns a new reference with the pointer adjusted by index*step.
Step defaults to the natural object size.
Primitive references
--------------------
References of the *_kind* ``'primitive'`` are used for objects
that don't fit any of the other reference types. Such
references can only appear as a value of a pointer field,
or as a result of calling the ``_field()`` method.
They behave as structs with one field ``value`` of the right type.
Struct references
-----------------
Struct references are used for class and struct objects.
They implement the following features:
* ``ref.field``, ``ref.field = value``
Valid fields of the structure may be accessed by subscript.
In case of inheritance, *superclass* fields have precedence
over the subclass, but fields shadowed in this way can still
be accessed as ``ref['subclasstype.field']``.
This shadowing order is necessary because vtable-based classes
are automatically exposed in their exact type, and the reverse
rule would make access to superclass fields unreliable.
* ``ref._field(field)``
Returns a reference to a valid field. That is, unlike regular
subscript, it returns a pointer reference even for primitive
typed fields.
* ``ref:vmethod(args...)``
Named virtual methods are also exposed, subject to the same
shadowing rules.
* ``pairs(ref)``
Enumerates all real fields (but not methods) in memory
(= declaration) order.
Container references
--------------------
Containers represent vectors and arrays, possibly resizable.
A container field can associate an enum to the container
reference, which allows accessing elements using string keys
instead of numerical indices.
Implemented features:
* ``ref._enum``
If the container has an associated enum, returns the matching
named type object.
* ``#ref``
Returns the *length* of the container.
* ``ref[index]``
Accesses the container element, using either a *0-based* numerical
index, or, if an enum is associated, a valid enum key string.
Accessing an invalid index is an error, but some container types
may return a default value, or auto-resize instead for convenience.
Currently this relaxed mode is implemented by df-flagarray aka BitArray.
* ``ref._field(index)``
Like with structs, returns a pointer to the array element, if possible.
Flag and bit arrays cannot return such pointer, so it fails with an error.
* ``pairs(ref)``, ``ipairs(ref)``
If the container has no associated enum, both behave identically,
iterating over numerical indices in order. Otherwise, ipairs still
uses numbers, while pairs tries to substitute enum keys whenever
possible.
* ``ref:resize(new_size)``
Resizes the container if supported, or fails with an error.
* ``ref:insert(index,item)``
Inserts a new item at the specified index. To add at the end,
use ``#ref`` as index.
* ``ref:erase(index)``
Removes the element at the given valid index.
Bitfield references
-------------------
Bitfields behave like special fixed-size containers.
The ``_enum`` property points to the bitfield type.
Numerical indices correspond to the shift value,
and if a subfield occupies multiple bits, the
``ipairs`` order would have a gap.
Named types
===========
Named types are exposed in the ``df`` tree with names identical
to the C++ version, except for the ``::`` vs ``.`` difference.
All types and the global object have the following features:
* ``type._kind``
Evaluates to one of ``struct-type``, ``class-type``, ``enum-type``,
``bitfield-type`` or ``global``.
* ``type._identity``
Contains a lightuserdata pointing to the underlying
DFHack::type_instance object.
Types excluding the global object also support:
* ``type:sizeof()``
Returns the size of an object of the type.
* ``type:new()``
Creates a new instance of an object of the type.
* ``type:is_instance(object)``
Returns true if object is same or subclass type, or a reference
to an object of same or subclass type. It is permissible to pass
nil, NULL or non-wrapper value as object; in this case the
method returns nil.
In addition to this, enum and bitfield types contain a
bi-directional mapping between key strings and values, and
also map ``_first_item`` and ``_last_item`` to the min and
max values.
Struct and class types with instance-vector attribute in the
xml have a ``type.find(key)`` function that wraps the find
method provided in C++.
Global functions
================
The ``df`` table itself contains the following functions and values:
* ``NULL``, ``df.NULL``
Contains the NULL lightuserdata.
* ``df.isnull(obj)``
Evaluates to true if obj is nil or NULL; false otherwise.
* ``df.isvalid(obj[,allow_null])``
For supported objects returns one of ``type``, ``voidptr``, ``ref``.
If *allow_null* is true, and obj is nil or NULL, returns ``null``.
Otherwise returns *nil*.
* ``df.sizeof(obj)``
For types and refs identical to ``obj:sizeof()``.
For lightuserdata returns *nil, address*
* ``df.new(obj)``, ``df.delete(obj)``, ``df.assign(obj, obj2)``
Equivalent to using the matching methods of obj.
* ``df._displace(obj,index[,step])``
For refs equivalent to the method, but also works with
lightuserdata (step is mandatory then).
* ``df.is_instance(type,obj)``
Equivalent to the method, but also allows a reference as proxy for its type.