From 7fa4ffeb9eec9924698560669c24d44bac790938 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Mr=C3=A1zek?= Date: Thu, 5 Apr 2012 02:39:38 +0200 Subject: [PATCH] Add a html version of the LUA API doc, package it. --- CMakeLists.txt | 2 +- Lua API.html | 580 +++++++++++++++++++++++++++++++++++++++++++++++++ Readme.html | 94 ++++---- fixTexts.sh | 1 + 4 files changed, 634 insertions(+), 43 deletions(-) create mode 100644 Lua API.html 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 @@ + + + + + + +DFHack Lua API + + + +
+

DFHack Lua API

+ + +
+

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

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

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

  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.

    +
    5. +
+

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.

    +
    • +
+
+
+
+ + diff --git a/Readme.html b/Readme.html index 3fc8f27a4..4e1a06eb1 100644 --- a/Readme.html +++ b/Readme.html @@ -467,33 +467,35 @@ access DF memory and allow for easier development of new tools.

  • tubefill
    • -
  • vdig
    • -
  • vdigx
    • -
  • expdig