diff --git a/CMakeLists.txt b/CMakeLists.txt index 60286c925..3cbbe6a1f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -140,7 +140,7 @@ add_subdirectory(depends) IF(BUILD_LIBRARY) add_subdirectory (library) ## install the default documentation files - install(FILES LICENSE Readme.html Compile.html DESTINATION ${DFHACK_USERDOC_DESTINATION}) + install(FILES LICENSE Readme.html Compile.html Lua\ API.html DESTINATION ${DFHACK_USERDOC_DESTINATION}) endif() #build the plugins diff --git a/Lua API.html b/Lua API.html new file mode 100644 index 000000000..86b9c00c8 --- /dev/null +++ b/Lua API.html @@ -0,0 +1,580 @@ + + + +
+ + +Contents
+ +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:
+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.
+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.
+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.
+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.
+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.
+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 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.
+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.
+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 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++.
+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.
+Fills all the adamantine veins again. Veins that were empty will be filled in too, but might still trigger a demon invasion (this is a known bug).
-Designates a whole vein for digging. Requires an active in-game cursor placed over a vein tile. With the 'x' option, it will traverse z-levels (putting stairs between the same-material tiles).
A permanent alias for 'vdig x'.
+A permanent alias for 'digv x'.
Designates layer stone for digging. Requires an active in-game cursor placed over a layer stone tile. With the 'x' option, it will traverse z-levels (putting stairs between the same-material tiles). With the 'undo' option it will remove the dig designation instead (if you realize that digging out a 50 z-level deep layer was not such a good idea after all).
+A permanent alias for 'digl x'.
+This command can be used for exploratory mining.
See: http://df.magmawiki.com/index.php/DF2010:Exploratory_mining
There are two variables that can be set: pattern and filter.