Add docs for the lua wrapper.

LUA_API.rst

@@ -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.