4.1 Funktionen und Typen Korrektur einreichen Original anzeigen

Hier führen wir alle Funktionen und Typen der Hilfsbibliothek in alphabetischer Reihenfolge auf.

luaL_addchar
void luaL_addchar(luaL_Buffer *B, char c);

Fügt das Zeichen c dem Puffer B hinzu (s. luaL_Buffer).

luaL_addlstring
void luaL_addlstring(luaL_Buffer *B, const char *s, size_t l);

Fügt die Zeichenkette, auf welche s zeigt, mit der Länge l dem Puffer B hinzu (s. luaL_Buffer). Die Zeichenkette darf eingebettete Nullen enthalten.

luaL_addsize
void luaL_addsize(luaL_Buffer *B, size_t n);

Fügt dem Puffer B (s. luaL_Buffer) eine Zeichenkette der Länge n hinzu, welche zuvor in den Pufferbereich kopiert wurde (s. luaL_prepbuffer).

luaL_addstring
void luaL_addstring(luaL_Buffer *B, const char *s);

Fügt die nullterminierte Zeichenkette, auf welche s zeigt, dem Puffer B hinzu (s. luaL_Buffer). Die Zeichenkette darf keine eingebetteten Nullen enthalten.

luaL_addvalue
void luaL_addvalue(luaL_Buffer *B);

Legt den Wert auf dem Stapelspeicher des Puffers von B ab (s. luaL_Buffer). Entfernt den Wert.

Dies ist die einzige auf Zeichenkettenpuffer-bezogene Funktion, welche mit einem zusätzlichen Element auf dem Stapelspeicher aufgerufen werden kann (und muss), welches jenes ist, welches dem Puffer hinzugefügt wird.

luaL_argcheck
void luaL_argcheck (lua_State *L,
                    int cond,
                    int narg,
                    const char *extramsg);

Prüft, ob cond wahr ist. Wenn dies nicht der Fall ist, wird ein Fehler mit folgender Nachricht geworfen, wobei func vom Aufrufstapel stammt:

bad argument # to  ()
luaL_argerror
int luaL_argerror(lua_State *L, int narg, const char *extramsg);

Wirft einen Fehler mit folgender Nachricht, wobei func vom Aufrufstapel kommt:

bad argument # to  ()

Diese Funktion liefert nichts zurück; es ist ein Idiom zur Verwendung in C-Funktionen als return luaL_argerror(args).

luaL_Buffer
typedef struct luaL_Buffer luaL_Buffer;

Typ für einen Zeichenketten-Puffer.

Ein Zeichenketten-Puffer erlaubt C-Code, Lua-Zeichenketten stückweise zu generieren. Das Vorgehensmuster ist dabei wie folgt:

  • Zuerst deklarieren Sie eine Variable b des Typs luaL_Buffer.
  • Dann initialisieren Sie diese mit einem Aufruf von luaL_buffinit(L,&b).
  • Anschließend fügen Sie Zeichenketten durch einen Aufruf der luaL_add*-Funktionen dem Puffer hinzu.
  • Abschließend stellen Sie dies durch einen Aufruf von luaL_pushresult(&b) fertig. Dieser Aufruf belässt die finale Zeichenkette auf dem Stapelspeicher.

Während der normalen Verwendung benutzt ein Zeichenkette-Puffer eine variable Anzahl von Plätzen im Stapelspeicher. Während der Verwendung eines Puffers können Sie somit nicht davon ausgehen, die obere Position des Stapelspeichers zu kennen. Sie können den Stapelspeicher zwischen sukzessiven Aufrufen der Puffer-Funktionen verwenden, sofern diese Verwendung balanciert ist; d. h. wenn Sie eine Puffer-Operation aufrufen, ist der Stapelspeicher auf gleicher Ebene, wie er unmittelbar nach der vorherigen Puffer-Operation war. (Die einzige Ausnahme zu dieser Regel ist luaL_addvalue.) Nach dem Aufruf von luaL_pushresult besitzt der Stapelspeicher die gleiche Höhe wie zum Zeitpunkt als der Puffer initialisiert wurde, plus die finale Zeichenkette ganz oben.

luaL_buffinit
void luaL_buffinit(lua_State *L, luaL_Buffer *B);

Initialisiert einen Puffer B. Diese Funktion alloziert keinen Speicher; der Puffer muss als Variable deklariert werden (s. luaL_Buffer).

luaL_callmeta
int luaL_callmeta(lua_State *L, int obj, const char *e);

Ruft eine Metamethode auf.

Wenn das Objekt beim Index obj eine Metatabelle besitzt und diese das Feld e, ruft diese Funktion dieses Feld auf und übergibt das Objekt als einziges Argument. In diesem Fall liefert die Funktion 1 und legt den vom Aufruf zurückgegebenen Wert auf dem Stapelspeicher ab. Falls keine Metatabelle oder Metamethode existiert, liefert diese Funktion 0 (ohne einen Wert auf dem Stapelspeicher abzulegen).

luaL_checkany
void luaL_checkany(lua_State *L, int narg);

Prüft, ob die Funktion ein Argument beliebigen Typs (inkl. nil) an Position narg besitzt.

luaL_checkint
int luaL_checkint(lua_State *L, int narg);

Prüft, ob das Funktionsargument narg eine Zahl ist und liefert diese zu int konvertiert.

luaL_checkinteger
lua_Integer luaL_checkinteger(lua_State *L, int narg);

Prüft, ob das Funktionsargument narg eine Zahl ist und liefert diese zu einem lua_Integer konvertiert.

luaL_checklong
long luaL_checklong(lua_State *L, int narg);

Prüft, ob das Funktionsargument narg eine Zahl ist und liefert diese zu long konvertiert.

luaL_checklstring
const char *luaL_checklstring(lua_State *L, int narg, size_t *l);

Prüft, ob das Funktionsargument narg eine Zeichenkette ist und liefert diese; sofern l nicht NULL ist, wird *l mit der Länge der Zeichenkette befüllt.

Diese Funktion verwendet lua_tolstring um ihr Ergebnis zu erhalten, so dass alle Konvertierungen und Hinweise dieser Funktion hier zum Tragen kommen.

luaL_checknumber
lua_Number luaL_checknumber(lua_State *L, int narg);

Prüft, ob das Argument narg eine Zahl ist und liefert diese Zahl.

luaL_checkoption
int luaL_checkoption (lua_State *L,
                      int narg,
                      const char *def,
                      const char *const lst[]);

Prüft, ob das Funktionsargument narg eine Zeichenkette ist und sucht im Feld lst (welches nullterminiert sein muss) nach dieser. Liefert den Index des Feldes, an welchem die Zeichenkette gefunden wurde. Wirft einen Fehler, wenn das Argument keine Zeichenkette war oder diese nicht gefunden werden konnte.

Wenn def nicht NULL ist, verwendet die Funktion def als Standardwert, wenn es kein Argument narg gibt oder dieses nil ist.

Dies ist eine nützliche Funktion zum Mapping von Zeichenketten auf C-Aufzählungen. (Die gewöhnliche Konvention verwendet in Lua-Bibliotheken Zeichenketten statt Nummern zur Auswahl von Optionen.)

luaL_checkstack
void luaL_checkstack(lua_State *L, int sz, const char *msg);

Vergrößert den Stapelspeicher auf top + sz Elemente, wobei ein Fehler geworfen wird, wenn der Stapelspeicher nicht zu dieser Größe anwachsen kann. msg ist ein zusätzlicher Text für die Fehlernachricht.

luaL_checkstring
const char *luaL_checkstring(lua_State *L, int narg);

Prüft, ob das Funktionsargument narg eine Zeichenkette ist und liefert diese.

Diese Funktion verwendet lua_tolstring um ihr Ergebnis zu erhalten, so dass alle Konvertierungen und Hinweise dieser Funktion hier zum Tragen kommen.

luaL_checktype
void luaL_checktype(lua_State *L, int narg, int t);

Prüft, ob das Funktionsargument narg vom Typ t ist. Siehe lua_type für die Kodierung der Typen für t.

luaL_checkudata
void *luaL_checkudata(lua_State *L, int narg, const char *tname);

Prüft, ob das Funktionsargument narg Benutzerdaten des Typs tname sind (s. luaL_newmetatable).

luaL_dofile
int luaL_dofile(lua_State *L, const char *filename);

Lädt die gegebene Datei und führt diese aus. Sie wird durch folgendes Makro definiert:

(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))

Liefert im Erfolgsfall 0, oder 1 wenn Fehler auftreten.

luaL_dostring
int luaL_dostring(lua_State *L, const char *str);

Lädt die gegebene Zeichenkette und führt diese aus. Sie wird durch folgendes Makro definiert:

(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))

Liefert im Erfolgsfall 0, oder 1 wenn Fehler auftreten.

luaL_error
int luaL_error(lua_State *L, const char *fmt, ...);

Wirft einen Fehler. Das Format der Fehlernachricht wird durch fmt und alle zusätzlichen Argumente definiert, wobei nach der gleichen Vorgehensweise wie bei lua_pushfstring verfahren wird. Am Anfang der Nachricht wird außerdem der Dateiname und ggf. die Fehlerzeile hinzugefügt, sofern diese Informationen verfügbar sind.

Diese Funktion liefert nichts zurück; es ist ein Idiom zur Verwendung in C-Funktionen als return luaL_error(args).

luaL_getmetafield
int luaL_getmetafield (lua_State *L, int obj, const char *e);

Legt das Feld e der Metatabelle des Objekts am Index obj auf dem Stapelspeicher ab. Wenn das Objekt keine Metatabelle besitzt oder die Metatabelle das Feld nicht besitzt, wird 0 geliefert und nichts abgelegt.

luaL_getmetatable
void luaL_getmetatable (lua_State *L, const char *tname);

Legt die mit dem Namen tname assoziierte Metatabelle aus der Registry auf dem Stapelspeicher ab (s. luaL_newmetatable).

luaL_gsub
const char *luaL_gsub (lua_State *L,
                       const char *s,
                       const char *p,
                       const char *r);

Erzeugt eine Kopie der Zeichenkette s, wobei jedes Auftreten der Zeichenkette p durch die Zeichenkette r ersetzt wird. Legt die sich ergebende Zeichenkette auf dem Stapelspeicher ab und liefert sie zurück.

luaL_loadbuffer
int luaL_loadbuffer (lua_State *L,
                     const char *buff,
                     size_t sz,
                     const char *name);

Lädt einen Puffer als Lua-Code. Diese Funktion verwendet lua_load, um den Code aus dem Puffer, auf welchen von buff mit der Größe sz gezeigt wird, zu laden.

Diese Funktion liefert die gleichen Ergebnisse wie lua_load. name ist der Bezeichner, welcher für Debug-Informationen und Fehlermeldungen genutzt wird.

luaL_loadfile
int luaL_loadfile (lua_State *L, const char *filename);

Lädt eine Datei als Lua-Code. Diese Funktion verwendet lua_load, um den Code in die Datei namens filename zu laden. Wenn filename NULL ist, wird von der Standardeingabe geladen. Die erste Zeile der Datei wird ignoriert, wenn diese mit # beginnt.

Diese Funktion liefert die gleichen Ergebnisse wie lua_load, besitzt jedoch einen zusätzlichen Fehlercode LUA_ERRFILE, wenn die Datei nicht geöffnet/geladen werden kann.

Genauso wie lua_load lädt diese Funktion den Code lediglich; er wird nicht ausgeführt.

luaL_loadstring
int luaL_loadfile(lua_State *L, const char *filename);

Lädt eine Zeichenkette als Lua-Code. Diese Funktion verwendet lua_load um den Code in die nullterminierte Zeichenkette s zu laden.

Diese Funktion liefert das gleiche Ergebnis wie lua_load.

Genauso wie lua_load lädt diese Funktion den Code lediglich; er wird nicht ausgeführt.

luaL_newmetatable
int luaL_newmetatable(lua_State *L, const char *tname);

Wenn die Registry bereits den Schlüssel tname enthält, wird 0 geliefert. Andernfalls wird eine neue Tabelle zur Verwendung als Metatabelle für die Benutzerdaten erzeugt, der Registry mit dem Schlüssel tname hinzugefügt und 1 geliefert.

In beiden Fällen wird der finale mit tname in der Registrierung verküpfte Wert auf dem Stapelspeicher abgelegt.

luaL_newstate
lua_State *luaL_newstate(void);

Erstellt einen neuen Lua-Status. Es wird die Funktion lua_newstate mit einem auf der standardmäßigen C-Funktion realloc basierten Allocator aufgerufen und anschließend eine "panic"-Funktion gesetzt (s. lua_atpanic), welche im Falle eines fatalen Fehlers eine Fehlermeldung auf der Standard-Fehlerausgabe ausgibt.

Liefert den neuen Status oder NULL, wenn ein Fehler bei der Speicheranforderung auftritt.

luaL_openlibs
void luaL_openlibs(lua_State *L);

Öffnet alle Lua-Standardbibliotheken im gegebenen Status.

luaL_optint
int luaL_optint(lua_State *L, int narg, int d);

Wenn das Funktionsargument narg eine Zahl ist, wird diese zu einem int konvertiert geliefert. Falls das Argument nicht angegeben wird oder nil ist, wird d geliefert. Andernfalls wird ein Fehler geworfen.

luaL_optinteger
lua_Integer luaL_optinteger (lua_State *L,
                             int narg,
                             lua_Integer d);

Wenn das Funktionsargument narg eine Zahl ist, wird diese zu lua_Integer konvertiert geliefert. Falls das Argument nicht angegeben wird oder nil ist, wird d geliefert. Andernfalls wird ein Fehler geworfen.

luaL_optlong
long luaL_optlong(lua_State *L, int narg, long d);

Wenn das Funktionsargument narg eine Zahl ist, wird diese zu long konvertiert geliefert. Falls das Argument nicht angegeben wird oder nil ist, wird d geliefert. Andernfalls wird ein Fehler geworfen.

luaL_optlstring
const char *luaL_optlstring (lua_State *L,
                             int narg,
                             const char *d,
                             size_t *l);

Wenn das Funktionsargument narg eine Zeichenkette ist, wird diese geliefert. Falls das Argument nicht angegeben wird oder nil ist, wird d geliefert. Andernfalls wird ein Fehler geworfen.

Wenn l nicht NULL ist, wird die Position *l mit der Länge des Ergebnisses befüllt.

luaL_optnumber
lua_Number luaL_optnumber(lua_State *L, int narg, lua_Number d);

Wenn das Funktionsargument narg eine Zahl ist, wird diese geliefert. Falls das Argument nicht angegeben wird oder nil ist, wird d geliefert. Andernfalls wird ein Fehler geworfen.

luaL_optstring
const char *luaL_optstring (lua_State *L,
                            int narg,
                            const char *d);

Wenn das Funktionsargument narg eine Zeichenkette ist, wird diese geliefert. Falls das Argument nicht angegeben wird oder nil ist, wird d geliefert. Andernfalls wird ein Fehler geworfen.

luaL_prepbuffer
char *luaL_prepbuffer(luaL_Buffer *B);

Liefert die Adresse zu einem Speicherplatz der Größe LUAL_BUFFERSIZE, wohin Sie eine Zeichenkette kopieren können, welche dem Puffer B hinzugefügt werden soll (s. luaL_Buffer). Nach dem Kopieren der Zeichenkette in diesen Bereich müssen Sie luaL_addsize mit der Länge der Zeichenkette aufrufen, um das eigentliche Hinzufügen zum Puffer durchzuführen.

luaL_pushresult
void luaL_pushresult(luaL_Buffer *B);

Beendet die Verwendung des Puffers B, wobei die verbleibende Zeichenkette auf dem Stapelspeicher belassen wird.

luaL_ref
int luaL_ref(lua_State *L, int t);

Erzeugt und liefert eine Referenz in der Tabelle beim Index t für das Objekt auf dem Stapelspeicher (und entfernt dieses).

Eine Referenz ist ein eindeutiger, ganzzahliger Schlüssel. Sofern Sie keine ganzzahligen Schlüssel manuell in die Tabelle t hinzufügen, sichert luaL_ref die Eindeutigkeit der gelieferten Schlüssel zu. Sie können ein durch die Referenz r verwiesenes Objekt durch einen Aufruf von lua_rawgeti(L,t,r) erhalten. Die Funktion luaL_unref entfernt eine Referenz und das damit verbundene Objekt.

Falls das Objekt auf dem Stapelspeicher nil ist, liefert luaL_ref die Konstante LUA_REFNIL. Die Konstante LUA_NOREF unterscheidet sich garantiert von jeder von luaL_ref gelieferten Referenz.

luaL_Reg
typedef struct luaL_Reg {
  const char *name;
  lua_CFunction func;
} luaL_Reg;

Typ für Felder von Funktion, um per luaL_register registriert zu werden. name ist der Funktionsname und func ist ein Zeiger auf die Funktion. Jedes Feld des Typs luaL_Reg muss mit einem Markierungseintrag enden, bei welchem sowohl name als auch func NULL sind.

luaL_register
void luaL_register (lua_State *L,
                    const char *libname,
                    const luaL_Reg *l);

Öffnet eine Bibliothek.

Wenn der Aufruf mit NULL als libname erfolgt, werden lediglich alle Funktionen der Liste l (s. luaL_Reg) in der Tabelle auf dem Stapelspeicher registriert.

Wenn der Aufruf mit einem von NULL verschiedenen libname erfolgt, erzeugt luaL_register eine neue Tabelle t, setzt diese als Wert der globalen Variable libname und von package.loaded[libname] und registriert darin alle Funktionen aus der Liste l. Falls sich eine Tabelle unter package.loaded[libname] oder in der Variablen libname befindet, wird diese genutzt anstatt eine neue zu erzeugen.

In jedem Fall belässt die Funktion die Tabelle auf dem Stapelspeicher.

luaL_typename
const char *luaL_typename(lua_State *L, int index);

Liefert den Namen des Typs des Wertes am gegebenen index.

luaL_typerror
int luaL_typerror(lua_State *L, int narg, const char *tname);

Erzeugt einen Fehler mit einer Nachricht wie der Folgenden:

location: bad argument narg to 'func' (tname expected, got rt)

… wobei location durch luaL_where erzeugt wird, func der Bezeichner der aktuellen Funktion ist und rt der Name des Typs des eigentlichen Arguments.

luaL_unref
void luaL_unref(lua_State *L, int t, int ref);

Entfernt die Referenz ref von der Tabelle am Index t (s. luaL_ref). Der Eintrag von der Tabelle wird entfernt, so dass das referenzierte Objekt bereinigt werden kann. Die Referenz ref wird darüber hinaus zur Wiederverwendung freigegeben.

Wenn ref LUA_NOREF oder LUA_REFNIL entspricht, führt luaL_unref keine Aktion durch.

luaL_where
void luaL_where(lua_State *L, int lvl);

Legt auf dem Stapelspeicher eine Zeichenkette ab, welche die aktuelle Position des Ablaufs des Levels lvl auf dem Aufrufstapel identifiziert. Typischerweise hat diese Zeichenkette das folgende Format:

chunkname:currentline:

Level 0 ist die laufende Funktion, Level 1 ist die die laufende Funktion aufrufende Funktion etc.

Diese Funktion wird zur Erzeugung eines Präfix für Fehlermeldungen verwendet.