mirrors
/
lua
mirror of https://github.com/lua/lua
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

API for functions to manipulate global state.

This commit is contained in:
Roberto Ierusalimschy 1998-06-02 17:37:04 -03:00
parent 741c6f5006
commit 02a6891939
5 changed files with 98 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
lbuffer.c
View File

@ -1,5 +1,5 @@
/*
** $Id: lbuffer.c,v 1.1 1997/12/23 19:24:36 roberto Exp roberto $
** $Id: lbuffer.c,v 1.2 1998/03/06 16:54:42 roberto Exp roberto $
** Auxiliar functions for building Lua libraries
** See Copyright Notice in lua.h
*/
@ -22,7 +22,7 @@
static void Openspace (int size)
{
LState *l = L; /* to optimize */
lua_State *l = L; /* to optimize */
int base = l->Mbuffbase-l->Mbuffer;
l->Mbuffsize *= 2;
if (l->Mbuffnext+size > l->Mbuffsize) /* still not big enough? */

14
lstate.c
View File

@ -1,5 +1,5 @@
/*
** $Id: lstate.c,v 1.4 1997/12/11 14:48:46 roberto Exp roberto $
** $Id: lstate.c,v 1.5 1997/12/17 20:48:58 roberto Exp roberto $
** Global State
** See Copyright Notice in lua.h
*/
@ -17,13 +17,13 @@
#include "ltm.h"
LState *lua_state = NULL;
lua_State *lua_state = NULL;
void lua_open (void)
{
if (lua_state) return;
lua_state = luaM_new(LState);
lua_state = luaM_new(lua_State);
L->numCblocks = 0;
L->Cstack.base = 0;
L->Cstack.lua2C = 0;
@ -76,3 +76,11 @@ void lua_close (void)
printf("total de memoria: %ld\n", totalmem);
#endif
}
lua_State *lua_setstate (lua_State *st) {
lua_State *old = lua_state;
lua_state = st;
return old;
}

23
lstate.h
View File

@ -1,5 +1,5 @@
/*
** $Id: lstate.h,v 1.7 1998/01/09 14:57:43 roberto Exp $
** $Id: lstate.h,v 1.8 1998/05/27 13:03:40 roberto Exp roberto $
** Global State
** See Copyright Notice in lua.h
*/
@ -8,6 +8,7 @@
#define lstate_h
#include "lobject.h"
#include "lua.h"
#define MAX_C_BLOCKS 10
@ -44,10 +45,18 @@ struct ref {
};
typedef struct LState {
struct lua_State {
/* trhead-specific state */
struct Stack stack; /* Lua stack */
struct C_Lua_Stack Cstack; /* C2lua struct */
void *errorJmp; /* current error recover point */
char *Mbuffer; /* global buffer */
char *Mbuffbase; /* current first position of Mbuffer */
int Mbuffsize; /* size of Mbuffer */
int Mbuffnext; /* next position to fill in Mbuffer */
struct C_Lua_Stack Cblocks[MAX_C_BLOCKS];
int numCblocks; /* number of nested Cblocks */
/* global state */
TObject errorim; /* error tag method */
GCnode rootproto; /* list of all prototypes */
GCnode rootcl; /* list of all closures */
@ -61,16 +70,10 @@ typedef struct LState {
int refSize; /* size of refArray */
unsigned long GCthreshold;
unsigned long nblocks; /* number of 'blocks' currently allocated */
char *Mbuffer; /* global buffer */
char *Mbuffbase; /* current first position of Mbuffer */
int Mbuffsize; /* size of Mbuffer */
int Mbuffnext; /* next position to fill in Mbuffer */
struct C_Lua_Stack Cblocks[MAX_C_BLOCKS];
int numCblocks; /* number of nested Cblocks */
} LState;
};
extern LState *lua_state;
extern lua_State *lua_state;
#define L lua_state

7
lua.h
View File

@ -1,5 +1,5 @@
/*
** $Id: lua.h,v 1.17 1998/03/06 18:47:42 roberto Exp roberto $
** $Id: lua.h,v 1.18 1998/05/18 22:26:03 roberto Exp roberto $
** Lua - An Extensible Extension Language
** TeCGraf: Grupo de Tecnologia em Computacao Grafica, PUC-Rio, Brazil
** e-mail: lua@tecgraf.puc-rio.br
@ -55,9 +55,12 @@
typedef void (*lua_CFunction) (void);
typedef unsigned int lua_Object;
typedef struct lua_State lua_State;
extern lua_State *lua_state;
void lua_open (void);
void lua_close (void);
lua_State *lua_setstate (lua_State *st);
lua_Object lua_settagmethod (int tag, char *event); /* In: new method */
lua_Object lua_gettagmethod (int tag, char *event);
@ -70,6 +73,8 @@ void lua_settag (int tag); /* In: object */
void lua_error (char *s);
int lua_dofile (char *filename); /* Out: returns */
int lua_dostring (char *string); /* Out: returns */
int lua_dobuffer (char *buff, int size);
/* Out: returns */
int lua_callfunction (lua_Object f);
/* In: parameters; Out: returns */

82
manual.tex
View File

@ -1,4 +1,4 @@
% $Id: manual.tex,v 1.10 1998/05/20 22:21:35 roberto Exp roberto $
% $Id: manual.tex,v 1.11 1998/05/27 19:09:39 roberto Exp roberto $
\documentstyle[fullpage,11pt,bnf]{article}
@ -38,7 +38,7 @@ Waldemar Celes
\tecgraf\ --- Computer Science Department --- PUC-Rio
}
\date{\small \verb$Date: 1998/05/20 22:21:35 $}
\date{\small \verb$Date: 1998/05/27 19:09:39 $}
\maketitle
@ -1291,6 +1291,7 @@ the set of C functions available to the host program to communicate
with the Lua library.
The API functions can be classified in the following categories:
\begin{enumerate}
\item managing states;
\item exchanging values between C and Lua;
\item executing Lua code;
\item manipulating (reading and writing) Lua objects;
@ -1301,30 +1302,76 @@ The API functions can be classified in the following categories:
All API functions and related types and constants
are declared in the header file \verb|lua.h|.
\subsection{Managing States}
The whole state of the Lua interpreter
(global variables, stack, tag methods, etc)
is stored in a dynamic structure pointed by\Deffunc{lua_state}
\begin{verbatim}
typedef struct lua_State lua_State;
extern lua_State *lua_state;
\end{verbatim}
Before calling any API function,
the library must be initalizated.
This is done by calling:\Deffunc{lua_open}
this state must be initialized.
This is done by calling\Deffunc{lua_open}
\begin{verbatim}
void lua_open (void);
\end{verbatim}
This function allocates and initializes some internal structures,
and defines all pre-defined functions of Lua.
If the library is already opened,
this function has no effect.
If \verb|lua_state| is already different from \verb|NULL|,
this function has no effect;
therefore, it is safe to call this function multiple times.
All standard libraries call \verb|lua_open| when they are opened.
If necessary, the library may be closed:\Deffunc{lua_close}
Function \verb|lua_setstate| is used to change the current state
of Lua:\Deffunc{lua_setstate}
\begin{verbatim}
lua_State *lua_setstate (lua_State *st);
\end{verbatim}
It sets \verb|lua_state| to \verb|st| and returns the old state.
Multiple, independent, states may be created.
For that, you must set \verb|lua_state| back to \verb|NULL| before
calling \verb|lua_open|.
An easy way to do that is defining an auxiliary function:
\begin{verbatim}
lua_State *lua_newstate (void) {
lua_State *old = lua_setstate(NULL);
lua_open();
return lua_setstate(old);
}
\end{verbatim}
This function creates a new state without changing the current state
of the interpreter.
Notice that any new state is built with all predefined functions;
any additional library (such as the standard libraries) must be
explicitly open in the new state, if needed.
If necessary, a state may be released:\Deffunc{lua_close}
\begin{verbatim}
void lua_close (void);
\end{verbatim}
This function destroys all objects in the Lua environment
This function destroys all objects in the current Lua environment
(calling the correspondent garbage collector tag methods),
and then frees all dynamic memory used by the library.
frees all dynamic memory used by the state,
and then sets \verb|lua_state| to \verb|NULL|.
Usually, there is no need to call this function,
since these resources are naturally released when the program ends.
If the library is already closed,
If \verb|lua_state| is already \verb|NULL|,
this function has no effect.
If you are using multiple states,
you may find useful the following function,
which releases a given state:
\begin{verbatim}
void lua_freestate (lua_State *st) {
lua_State *old = lua_setstate(st);
lua_close();
if (old != st) lua_setstate(old);
}
\end{verbatim}
\subsection{Exchanging Values between C and Lua} \label{valuesCLua}
Because Lua has no static type system,
all values passed between Lua and C have type
@ -1522,12 +1569,13 @@ The use of explicit nested blocks is strongly encouraged.
\subsection{Executing Lua Code}
A host program can execute Lua chunks written in a file or in a string
using the following functions:
\Deffunc{lua_dofile}\Deffunc{lua_dostring}
\Deffunc{lua_dofile}\Deffunc{lua_dostring}\Deffunc{lua_dobuffer}
\begin{verbatim}
int lua_dofile (char *filename);
int lua_dostring (char *string);
int lua_dobuffer (char *buff, int size);
\end{verbatim}
Both functions return an error code:
All these functions return an error code:
0, in case of success; non zero, in case of errors.
More specifically, \verb|lua_dofile| returns 2 if for any reason
it could not open the file.
@ -1536,6 +1584,8 @@ executes the \verb|stdin| stream.
Function \verb|lua_dofile| is also able to execute pre-compiled chunks.
It automatically detects whether the file is text or binary,
and loads it accordingly (see program \IndexVerb{luac}).
Function \verb|lua_dostring| executes only source code,
and function \verb|lua_dobuffer| executes only pre-compiled chunks.
These functions return, in structure lua2C,
any values eventually returned by the chunks.
@ -1975,7 +2025,7 @@ converts it to a string in a reasonable format.
\subsubsection*{\ff \T{print (e1, e2, ...)}}\Deffunc{print}
This function receives any number of arguments,
and prints their values in a reasonable format.
and prints their values using the strings returned by \verb|tostring|.
This function is not intended for formatted output,
but as a quick way to show a value,
for instance for error messages or debugging.
@ -2177,7 +2227,7 @@ letter depends on the current locale.
Returns a string that is the concatenation of \verb|n| copies of
the string \verb|s|.
\subsubsection*{\ff \T{ascii (s [, i])}}\Deffunc{ascii}
\subsubsection*{\ff \T{strbyte (s [, i])}}\Deffunc{strbyte}
Returns the internal numerical code of the character \verb|s[i]|.
If \verb|i| is absent, then it is assumed to be 1.
If \verb|i| is negative,
@ -2185,10 +2235,10 @@ it is replaced by the length of the string minus its
absolute value plus 1.
Therefore, \M{-1} points to the last character of \verb|s|.
\subsubsection*{\ff \T{int2str (i1, i2, \ldots)}}\Deffunc{int2str}
\subsubsection*{\ff \T{strchar (i1, i2, \ldots)}}\Deffunc{strchar}
Receives 0 or more integers.
Returns a string with length equal to the number of arguments,
wherein each character has ascii value equal
wherein each character has the internal numerical code equal
to its correspondent argument.
\subsubsection*{\ff \T{format (formatstring, e1, e2, \ldots)}}\Deffunc{format}