nik/lush
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

last version before new API

Browse Source
This commit is contained in:
Roberto Ierusalimschy
2000-08-30 15:58:46 -03:00
parent a97f29f154
commit 2d3ebba537
1 changed files with 145 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
manual.tex
View File

@@ -1,4 +1,4 @@
% $Id: manual.tex,v 1.40 2000/08/09 19:09:20 roberto Exp roberto $ % $Id: manual.tex,v 1.41 2000/08/14 19:18:14 roberto Exp roberto $
\documentclass[11pt]{article} \documentclass[11pt]{article}
\usepackage{fullpage,bnf} \usepackage{fullpage,bnf}
@@ -27,6 +27,7 @@
% LHF % LHF
\renewcommand{\ter}[1]{{\rm`{\tt#1}'}} \renewcommand{\ter}[1]{{\rm`{\tt#1}'}}
\newcommand{\Nter}[1]{{\rm{\tt#1}}}
\newcommand{\NOTE}{\par\noindent\emph{NOTE}: } \newcommand{\NOTE}{\par\noindent\emph{NOTE}: }
\makeindex \makeindex
@@ -122,7 +123,7 @@ Waldemar Celes
\tecgraf\ --- Computer Science Department --- PUC-Rio \tecgraf\ --- Computer Science Department --- PUC-Rio
} }
\date{{\small \tt\$Date: 2000/08/09 19:09:20 $ $}} \date{{\small \tt\$Date: 2000/08/14 19:18:14 $ $}}
\maketitle \maketitle
@@ -267,7 +268,7 @@ A chunk is simply a sequence of statements,
which are executed sequentially. which are executed sequentially.
Each statement can be optionally followed by a semicolon: Each statement can be optionally followed by a semicolon:
\begin{Produc} \begin{Produc}
\produc{chunk}{\rep{stat} \opt{\ter{;}}} \produc{chunk}{\rep{stat \opt{\ter{;}}}}
\end{Produc}% \end{Produc}%
Statements are described in \See{stats}. Statements are described in \See{stats}.
(The notation above is the usual extended BNF, (The notation above is the usual extended BNF,
@@ -664,7 +665,7 @@ The table \rwd{for} statement traverses all pairs
index--value of a given table. index--value of a given table.
It has the following syntax: It has the following syntax:
\begin{Produc} \begin{Produc}
\produc{stat}{\rwd{for} name \ter{,} name \rwd{in} exp \produc{stat}{\rwd{for} name \ter{,} name \rwd{in} exp1
\rwd{do} block \rwd{end}} \rwd{do} block \rwd{end}}
\end{Produc}% \end{Produc}%
A \rwd{for} statement like A \rwd{for} statement like
@@ -974,7 +975,7 @@ Arguments have the following syntax:
\begin{Produc} \begin{Produc}
\produc{args}{\ter{(} \opt{explist1} \ter{)}} \produc{args}{\ter{(} \opt{explist1} \ter{)}}
\produc{args}{tableconstructor} \produc{args}{tableconstructor}
\produc{args}{\ter{literal}} \produc{args}{\Nter{literal}}
\produc{explist1}{\rep{exp1 \ter{,}} exp} \produc{explist1}{\rep{exp1 \ter{,}} exp}
\end{Produc}% \end{Produc}%
All argument expressions are evaluated before the call. All argument expressions are evaluated before the call.
@@ -1561,7 +1562,7 @@ the stack size for the interpreter and a boolean that
indicates whether the predefined functions should be loaded or not. indicates whether the predefined functions should be loaded or not.
Each function call needs one stack position for each local variable Each function call needs one stack position for each local variable
and temporary variables, plus one position for book-keeping. and temporary variables, plus one position for book-keeping.
The stack must also have at least ten extra positions available. The stack must also have some 20 extra positions available.
For very small implementations, without recursive functions, For very small implementations, without recursive functions,
a stack size of 100 should be enough. a stack size of 100 should be enough.
A value 0 for \verb|stacksize| uses a default size of 1024 positions. A value 0 for \verb|stacksize| uses a default size of 1024 positions.
@@ -1599,51 +1600,6 @@ to avoid growing too big.
With the exception of \verb|lua_newstate|, With the exception of \verb|lua_newstate|,
all functions in the API need a state as their first argument. all functions in the API need a state as their first argument.
>>>>>>>>>>>>
However, most applications use a single state.
To avoid the burden of passing this only state explicitly to all
functions, and also to keep compatibility with old versions of Lua,
the API provides a set of macros and one global variable that
take care of this state argument for single-state applications:
\begin{verbatim}
#ifndef LUA_REENTRANT
\end{verbatim}
\begin{verbatim}
extern lua_State *lua_state;
\end{verbatim}
\begin{verbatim}
#define lua_close() (lua_close)(lua_state)
#define lua_dofile(filename) (lua_dofile)(lua_state, filename)
#define lua_dostring(str) (lua_dostring)(lua_state, str)
...
\end{verbatim}
\begin{verbatim}
#endif
\end{verbatim}
For each function in the API, there is a macro with the same name
that supplies \verb|lua_state| as the first argument to the call.
(The parentheses around the function name avoid it being expanded
again as a macro.)
The only exception is \verb|lua_newstate|;
in this case, the corresponding macro is
\begin{verbatim}
#define lua_open() ((void)(lua_state?0:(lua_state=lua_newstate(0, 1))))
\end{verbatim}
This code checks whether the global state has been initialized;
if not, it creates a new state with default settings and
assigns it to \verb|lua_state|.
By default, the single-state macros are all active.
If you need to use multiple states,
and therefore will provide the state argument explicitly in each call,
you should define \IndexVerb{LUA_REENTRANT} before
including \verb|lua.h| in your code:
\begin{verbatim}
#define LUA_REENTRANT
#include "lua.h"
\end{verbatim}
<<<<<<<<<
\subsection{Exchanging Values between C and Lua} \label{valuesCLua} \subsection{Exchanging Values between C and Lua} \label{valuesCLua}
Because Lua has no static type system, Because Lua has no static type system,
@@ -1801,9 +1757,9 @@ nested blocks can be defined with the functions
void lua_beginblock (lua_State *L); void lua_beginblock (lua_State *L);
void lua_endblock (lua_State *L); void lua_endblock (lua_State *L);
\end{verbatim} \end{verbatim}
After the end of the block, At the end of a block,
all \verb|lua_Object|s created inside it are released. Lua releases all \verb|lua_Object|s created inside the block,
The \verb|lua_endblock| function also empties the C2Lua stack. and empties the C2lua stack.
\subsection{Garbage Collection}\label{GC} \subsection{Garbage Collection}\label{GC}
Because Lua has automatic memory management and garbage collection, Because Lua has automatic memory management and garbage collection,
@@ -2026,7 +1982,7 @@ equivalent to the Lua code:
lua_setglobal(L, "b"); /* set global variable 'b' */ lua_setglobal(L, "b"); /* set global variable 'b' */
\end{verbatim} \end{verbatim}
Some special Lua functions have exclusive interfaces. Some special Lua functions have direct interfaces.
The host program can generate a Lua error calling the function The host program can generate a Lua error calling the function
\Deffunc{lua_error} \Deffunc{lua_error}
\begin{verbatim} \begin{verbatim}
@@ -2071,13 +2027,13 @@ int lua_next (lua_State *L, lua_Object t, int i);
\end{verbatim} \end{verbatim}
Its first argument is the table to be traversed, Its first argument is the table to be traversed,
and the second is a \emph{cursor}; and the second is a \emph{cursor};
this cursor starts in 0, this cursor starts at 0,
and for each call the function returns a value to and for each call the function returns a value to
be used in the next call, be used in the next call,
or 0 to signal the end of the traversal. or 0 to signal the end of the traversal.
The function also returns, in the Lua2C array, The function also returns, in the lua2C array,
a key-value pair from the table. a key-value pair from the table.
A typical traversal looks like the following code: A typical traversal looks like this:
\begin{verbatim} \begin{verbatim}
int i; int i;
lua_Object t; lua_Object t;
@@ -2161,11 +2117,11 @@ If the C code needs to keep a \verb|lua_Object|
outside block boundaries, outside block boundaries,
then it must create a \Def{reference} to the object. then it must create a \Def{reference} to the object.
The routines to manipulate references are the following: The routines to manipulate references are the following:
\Deffunc{lua_ref}\Deffunc{lua_getref} \Deffunc{lua_ref}\Deffunc{lua_pushref}
\Deffunc{lua_unref} \Deffunc{lua_unref}
\begin{verbatim} \begin{verbatim}
int lua_ref (lua_State *L, int lock); int lua_ref (lua_State *L, int lock);
lua_Object lua_getref (lua_State *L, int ref); int lua_pushref (lua_State *L, int ref);
void lua_unref (lua_State *L, int ref); void lua_unref (lua_State *L, int ref);
\end{verbatim} \end{verbatim}
The function \verb|lua_ref| creates a reference The function \verb|lua_ref| creates a reference
@@ -2180,10 +2136,10 @@ If \verb|lock| is true, then the object is \emph{locked}:
this means the object will not be garbage collected. this means the object will not be garbage collected.
\emph{Unlocked references may be garbage collected}. \emph{Unlocked references may be garbage collected}.
Whenever the referenced object is needed in~C, Whenever the referenced object is needed in~C,
a call to \verb|lua_getref| a call to \verb|lua_pushref|
returns a handle to it; pushes that object into the C2lua stack;
if the object has been collected, if the object has been collected,
\verb|lua_getref| returns \verb|LUA_NOOBJECT|. \verb|lua_getref| returns 0 (and does not push anything).
When a reference is no longer needed, When a reference is no longer needed,
it can be released with a call to \verb|lua_unref|. it can be released with a call to \verb|lua_unref|.
@@ -3257,7 +3213,7 @@ it returns 0.
The structure \verb|lua_Debug| is used to carry different pieces of information The structure \verb|lua_Debug| is used to carry different pieces of information
about an active function: about an active function:
\begin{verbatim} \begin{verbatim}
struct lua_Debug { typedef struct lua_Debug {
const char *event; /* "call", "return" */ const char *event; /* "call", "return" */
const char *source; /* (S) */ const char *source; /* (S) */
int linedefined; /* (S) */ int linedefined; /* (S) */
@@ -3269,7 +3225,7 @@ struct lua_Debug {
lua_Object func; /* (f) function being executed */ lua_Object func; /* (f) function being executed */
/* private part */ /* private part */
... ...
}; } lua_Debug;
\end{verbatim} \end{verbatim}
The \verb|lua_getstack| function fills only the private part The \verb|lua_getstack| function fills only the private part
of this structure, for future use. of this structure, for future use.
@@ -3282,9 +3238,10 @@ This function returns 0 on error
(e.g., an invalid option in \verb|what|). (e.g., an invalid option in \verb|what|).
Each character in the string \verb|what| Each character in the string \verb|what|
selects some fields of \verb|ar| to be filled, selects some fields of \verb|ar| to be filled,
as indicated by the letter in parentheses in the definition of \verb|lua_Debug|; as indicated by the letter in parentheses in the definition of \verb|lua_Debug|:
that is, an \verb|S| fills the fields \verb|source| and \verb|linedefined|, An \verb|S| fills in the fields \verb|source|, \verb|linedefined|,
and \verb|l| fills the field \verb|currentline|, etc. and \verb|what|;
\verb|l| fills in the field \verb|currentline|, etc.
To get information about a function that is not active (that is, To get information about a function that is not active (that is,
it is not in the stack), it is not in the stack),
@@ -3310,7 +3267,7 @@ if the function was defined in a file,
\verb|source| starts with a \verb|@| followed by the file name. \verb|source| starts with a \verb|@| followed by the file name.
\item[linedefined] \item[linedefined]
the line number where starts the definition of the function. the line number where the definition of the function starts.
\item[what] the string \verb|"Lua"| if this is a Lua function, \item[what] the string \verb|"Lua"| if this is a Lua function,
\verb|"C"| if this is a C~function, \verb|"C"| if this is a C~function,
@@ -3345,9 +3302,7 @@ if the function is a tag method,
otherwise \verb|namewhat| is \verb|""| (the empty string). otherwise \verb|namewhat| is \verb|""| (the empty string).
\item[nups] \item[nups]
Number of upvalues of a C~function. Number of upvalues of a function.
If the function is not a C~function,
\verb|nups| is set to 0.
\item[func] \item[func]
The function being executed, as a \verb|lua_Object|. The function being executed, as a \verb|lua_Object|.
@@ -3388,24 +3343,20 @@ value of that variable.
For \verb|lua_setlocal|, For \verb|lua_setlocal|,
you fill the \verb|index| and the \verb|value| fields of \verb|v|, you fill the \verb|index| and the \verb|value| fields of \verb|v|,
and the function assigns that value to the variable. and the function assigns that value to the variable.
Both functions return 0 on failure, that happens Both functions return 0 on failure;
if the index is greater than the number of active local variables. that happens if the index is greater than the number of active local variables.
As an example, the following function lists the names of all As an example, the following function lists the names of all
local variables for a function in a given level of the stack: local variables for a function in a given level of the stack:
\begin{verbatim} \begin{verbatim}
int listvars (lua_State *L, int level) { int listvars (lua_State *L, int level) {
lua_Debug ar; lua_Debug ar;
int i; lua_Localvar v;
if (lua_getstack(L, level, &ar) == 0) if (lua_getstack(L, level, &ar) == 0)
return 0; /* failure: no such level on the stack */ return 0; /* failure: no such level on the stack */
for (i=1; ; i++) { for (v.index = 1; lua_getlocal(L, &ar, &v); v.index++)
lua_Localvar v;
v.index = i;
if (lua_getlocal(L, &ar, &v) == 0)
return 1; /* no more locals */
printf("%s\n", v.name); printf("%s\n", v.name);
} return 1;
} }
\end{verbatim} \end{verbatim}
@@ -3505,7 +3456,7 @@ until the last active local variable.)
The function returns \nil\ if there is no local The function returns \nil\ if there is no local
variable with the given index, variable with the given index,
and raises an error when called with a \verb|level| out of range. and raises an error when called with a \verb|level| out of range.
(You can call \verb|getstack| to check wheter the level is valid.) (You can call \verb|getstack| to check whether the level is valid.)
\subsubsection*{\ff \T{setlocal (level, local, value)}}\Deffunc{setlocal} \subsubsection*{\ff \T{setlocal (level, local, value)}}\Deffunc{setlocal}
@@ -3638,43 +3589,96 @@ some differences had to be introduced.
Here is a list of all these incompatibilities. Here is a list of all these incompatibilities.
\subsection*{Incompatibilities with \Index{version 3.2}} \subsection*{Incompatibilities with \Index{version 3.2}}
\subsubsection*{Changes in the Language}
\begin{itemize} \begin{itemize}
\item \item
General read patterns are now deprecated. All pragmas (\verb|$debug|, \verb|$if|, \ldots) are deprecated.
\item \rwd{for}, \rwd{break}, and \rwd{in} now are reserved words.
\item \item
Garbage-collection tag methods for tables is now deprecated. Garbage-collection tag methods for tables is now deprecated.
\item \item
\verb|setglobal|, \verb|rawsetglobal|, and \verb|sort| no longer return a value; There is now only one tag method for order operators.
\verb|type| no longer return a second value.
\item \item
In nested function calls like \verb|f(g(x))| In nested function calls like \verb|f(g(x))|
\emph{all} return values from \verb|g| are passed as arguments to \verb|f|. \emph{all} return values from \verb|g| are passed as arguments to \verb|f|.
(This only happens when \verb|g| is the last (This only happens when \verb|g| is the last
[or the only] argument to \verb|f|.) [or the only] argument to \verb|f|.)
\item \item
There is now only one tag method for order operators. The pre-compiler may assume that some operators are associative,
\item
The debug API has been completely rewritten.
\item
The pre-compiler may use the fact that some operators are associative,
for optimizations. for optimizations.
This may cause problems if these operators This may cause problems if these operators
have non-associative tag methods. have non-associative tag methods.
\item Old pre-compiled code is obsolete, and must be re-compiled.
\end{itemize}
\subsubsection*{Changes in the Libraries}
\begin{itemize}
\item \item
All functions from the old API are now macros. General read patterns are now deprecated.
\item
The functions \verb|rawgettable| and \verb|rawsettable|
were renamed to \verb|rawget| and \verb|rawset|.
\item
The functions \verb|foreachvar|, \verb|nextvar|,
\verb|rawsetglobal|, and \verb|rawgetglobal| are deprecated.
You can get their functionality using table operations
over the table of globals.
\item
\verb|setglobal| and \verb|sort| no longer return a value;
\verb|type| no longer returns a second value.
\end{itemize}
\subsubsection*{Changes in the API}
\begin{itemize}
\item
The whole API is now reentrant,
which means that all functions have
an extra first argument, a Lua state.
You can still use the old format:
If you define \verb|LUA_SINGLESTATE| before including \verb|lua.h|,
all functions from the old API are defined as macros.
You will also have to define a variable
\begin{verbatim}
lua_State *lua_state = NULL;
\end{verbatim}
somewhere in your program.
\item
The debug API has been completely rewritten.
\item \item
A \verb|const| qualifier has been added to \verb|char *| A \verb|const| qualifier has been added to \verb|char *|
in all API functions that handle C~strings. in all API functions that handle C~strings.
\item
Some types \verb|long| were changed to \verb|size_t|.
\item \item
\verb|luaL_openlib| no longer automatically calls \verb|lua_open|. \verb|luaL_openlib| no longer automatically calls \verb|lua_open|.
So, So,
you must now explicitly call \verb|lua_open| before opening you must now explicitly call \verb|lua_open| before opening
the standard libraries. the standard libraries.
\item \item
\verb|lua_type| now returns a string describing the type, \verb|lua_type| now returns a string describing the type,
and is no longer a synonym for \verb|lua_tag|. and is no longer a synonym for \verb|lua_tag|.
\item Old pre-compiled code is obsolete, and must be re-compiled.
\end{itemize} \end{itemize}
@@ -3687,7 +3691,7 @@ and is no longer a synonym for \verb|lua_tag|.
\begin{Produc} \begin{Produc}
\produc{chunk}{\rep{stat} \opt{\ter{;}}} \produc{chunk}{\rep{stat \opt{\ter{;}}}}
\produc{block}{chunk} \produc{block}{chunk}
@@ -3702,43 +3706,72 @@ and is no longer a synonym for \verb|lua_tag|.
\opt{\rwd{else} block} \rwd{end} \opt{\rwd{else} block} \rwd{end}
\OrNL \rwd{return} \opt{explist1} \OrNL \rwd{return} \opt{explist1}
\OrNL \rwd{break} \OrNL \rwd{break}
\OrNL \rwd{for} name \ter{=} exp1 \ter{,} exp1 \opt{\ter{,} exp1} \OrNL \rwd{for} \Nter{name} \ter{=} exp1 \ter{,} exp1 \opt{\ter{,} exp1}
\rwd{do} block \rwd{end}
\OrNL \rwd{for} \Nter{name} \ter{,} \Nter{name} \rwd{in} exp1
\rwd{do} block \rwd{end} \rwd{do} block \rwd{end}
\OrNL \rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} block \rwd{end} \OrNL \rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} block \rwd{end}
\OrNL \rwd{local} declist \opt{init} \OrNL \rwd{local} declist \opt{init}
} }
\produc{funcname}{%
\Nter{name}
\Or \Nter{name} \ter{.} \Nter{name}
\Or \Nter{name} \ter{:} \Nter{name}
}
\produc{varlist1}{var \rep{\ter{,} var}}
\produc{var}{% \produc{var}{%
name \Nter{name}
\OrNL varorfunc \ter{[} exp1 \ter{]} \Or varorfunc \ter{[} exp1 \ter{]}
\OrNL varorfunc \ter{.} name \Or varorfunc \ter{.} \Nter{name}
} }
\produc{varorfunc}{var \Or functioncall} \produc{varorfunc}{var \Or functioncall}
\produc{varlist1}{var \rep{\ter{,} var}} \produc{declist}{\Nter{name} \rep{\ter{,} \Nter{name}}}
\produc{declist}{name \rep{\ter{,} name}}
\produc{init}{\ter{=} explist1} \produc{init}{\ter{=} explist1}
\produc{explist1}{\rep{exp1 \ter{,}} exp}
\produc{exp1}{exp}
\produc{exp}{% \produc{exp}{%
\rwd{nil} \rwd{nil}
\Or number \Or \Nter{number}
\Or literal \Or \Nter{literal}
\Or var
\Or function \Or function
\Or upvalue \Or upvalue
\Or functioncall \OrNL functioncall
\Or tableconstructor \Or tableconstructor
\Or \ter{(} exp \ter{)} \Or \ter{(} exp \ter{)}
\Or exp binop exp \Or exp binop exp
\Or unop exp \Or unop exp
} }
\produc{exp1}{exp}
\produc{explist1}{\rep{exp1 \ter{,}} exp} \produc{functioncall}{%
varorfunc args
\Or varorfunc \ter{:} \Nter{name} args
}
\produc{args}{%
\ter{(} \opt{explist1} \ter{)}
\Or tableconstructor
\Or \Nter{literal}
}
\produc{function}{\rwd{function} \ter{(} \opt{parlist1} \ter{)} block \rwd{end}}
\produc{parlist1}{%
\ter{\ldots}
\Or \Nter{name} \rep{\ter{,} \Nter{name}} \opt{\ter{,} \ter{\ldots}}
}
\produc{upvalue}{\ter{\%} \Nter{name}}
\produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}} \produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}}
\produc{fieldlist}{% \produc{fieldlist}{%
@@ -3753,34 +3786,14 @@ and is no longer a synonym for \verb|lua_tag|.
\produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}} \produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}}
\produc{ffield}{% \produc{ffield}{%
\ter{[} exp \ter{]} \ter{=} exp \ter{[} exp \ter{]} \ter{=} exp
\Or name \ter{=} exp \Or \Nter{name} \ter{=} exp
} }
\produc{functioncall}{% \produc{binop}{\ter{+} \Or \ter{-} \Or \ter{*} \Or \ter{/} \Or \ter{\^{ }} \Or
varorfunc args \ter{..} \OrNL \ter{<} \Or \ter{<=} \Or \ter{>} \Or \ter{>=}
\Or varorfunc \ter{:} name args \Or \ter{==} \Or \ter{\~{ }=} \OrNL \rwd{and} \Or \rwd{or}}
}
\produc{args}{% \produc{unop}{\ter{-} \Or \rwd{not}}
\ter{(} \opt{explist1} \ter{)}
\Or tableconstructor
\Or \ter{literal}
}
\produc{function}{\rwd{function} \ter{(} \opt{parlist1} \ter{)} block \rwd{end}}
\produc{funcname}{%
name
\OrNL name \ter{.} name
\OrNL name \ter{:} name
}
\produc{parlist1}{%
\ter{\ldots}
\Or name \rep{\ter{,} name} \opt{\ter{,} \ter{\ldots}}
}
\produc{upvalue}{\ter{\%} name}
\end{Produc} \end{Produc}
%}=============================================================== %}===============================================================