mirror of https://github.com/lua/lua
last version before new API
This commit is contained in:
Roberto Ierusalimschy
parent
a97f29f154
commit
2d3ebba537
277
manual.tex
277
manual.tex
|
|
@ -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}
|
||||
\usepackage{fullpage,bnf}
|
||||
|
|
@ -27,6 +27,7 @@
|
|||
|
||||
% LHF
|
||||
\renewcommand{\ter}[1]{{\rm`{\tt#1}'}}
|
||||
\newcommand{\Nter}[1]{{\rm{\tt#1}}}
|
||||
\newcommand{\NOTE}{\par\noindent\emph{NOTE}: }
|
||||
|
||||
\makeindex
|
||||
|
|
@ -122,7 +123,7 @@ Waldemar Celes
|
|||
\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
|
||||
|
||||
|
|
@ -267,7 +268,7 @@ A chunk is simply a sequence of statements,
|
|||
which are executed sequentially.
|
||||
Each statement can be optionally followed by a semicolon:
|
||||
\begin{Produc}
|
||||
\produc{chunk}{\rep{stat} \opt{\ter{;}}}
|
||||
\produc{chunk}{\rep{stat \opt{\ter{;}}}}
|
||||
\end{Produc}%
|
||||
Statements are described in \See{stats}.
|
||||
(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.
|
||||
It has the following syntax:
|
||||
\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}}
|
||||
\end{Produc}%
|
||||
A \rwd{for} statement like
|
||||
|
|
@ -974,7 +975,7 @@ Arguments have the following syntax:
|
|||
\begin{Produc}
|
||||
\produc{args}{\ter{(} \opt{explist1} \ter{)}}
|
||||
\produc{args}{tableconstructor}
|
||||
\produc{args}{\ter{literal}}
|
||||
\produc{args}{\Nter{literal}}
|
||||
\produc{explist1}{\rep{exp1 \ter{,}} exp}
|
||||
\end{Produc}%
|
||||
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.
|
||||
Each function call needs one stack position for each local variable
|
||||
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,
|
||||
a stack size of 100 should be enough.
|
||||
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|,
|
||||
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}
|
||||
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_endblock (lua_State *L);
|
||||
\end{verbatim}
|
||||
After the end of the block,
|
||||
all \verb|lua_Object|s created inside it are released.
|
||||
The \verb|lua_endblock| function also empties the C2Lua stack.
|
||||
At the end of a block,
|
||||
Lua releases all \verb|lua_Object|s created inside the block,
|
||||
and empties the C2lua stack.
|
||||
|
||||
\subsection{Garbage Collection}\label{GC}
|
||||
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' */
|
||||
\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
|
||||
\Deffunc{lua_error}
|
||||
\begin{verbatim}
|
||||
|
|
@ -2071,13 +2027,13 @@ int lua_next (lua_State *L, lua_Object t, int i);
|
|||
\end{verbatim}
|
||||
Its first argument is the table to be traversed,
|
||||
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
|
||||
be used in the next call,
|
||||
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 typical traversal looks like the following code:
|
||||
A typical traversal looks like this:
|
||||
\begin{verbatim}
|
||||
int i;
|
||||
lua_Object t;
|
||||
|
|
@ -2161,12 +2117,12 @@ If the C code needs to keep a \verb|lua_Object|
|
|||
outside block boundaries,
|
||||
then it must create a \Def{reference} to the object.
|
||||
The routines to manipulate references are the following:
|
||||
\Deffunc{lua_ref}\Deffunc{lua_getref}
|
||||
\Deffunc{lua_ref}\Deffunc{lua_pushref}
|
||||
\Deffunc{lua_unref}
|
||||
\begin{verbatim}
|
||||
int lua_ref (lua_State *L, int lock);
|
||||
lua_Object lua_getref (lua_State *L, int ref);
|
||||
void lua_unref (lua_State *L, int ref);
|
||||
int lua_ref (lua_State *L, int lock);
|
||||
int lua_pushref (lua_State *L, int ref);
|
||||
void lua_unref (lua_State *L, int ref);
|
||||
\end{verbatim}
|
||||
The function \verb|lua_ref| creates a reference
|
||||
to the object that is on the top of the stack,
|
||||
|
|
@ -2180,10 +2136,10 @@ If \verb|lock| is true, then the object is \emph{locked}:
|
|||
this means the object will not be garbage collected.
|
||||
\emph{Unlocked references may be garbage collected}.
|
||||
Whenever the referenced object is needed in~C,
|
||||
a call to \verb|lua_getref|
|
||||
returns a handle to it;
|
||||
a call to \verb|lua_pushref|
|
||||
pushes that object into the C2lua stack;
|
||||
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,
|
||||
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
|
||||
about an active function:
|
||||
\begin{verbatim}
|
||||
struct lua_Debug {
|
||||
typedef struct lua_Debug {
|
||||
const char *event; /* "call", "return" */
|
||||
const char *source; /* (S) */
|
||||
int linedefined; /* (S) */
|
||||
|
|
@ -3269,7 +3225,7 @@ struct lua_Debug {
|
|||
lua_Object func; /* (f) function being executed */
|
||||
/* private part */
|
||||
...
|
||||
};
|
||||
} lua_Debug;
|
||||
\end{verbatim}
|
||||
The \verb|lua_getstack| function fills only the private part
|
||||
of this structure, for future use.
|
||||
|
|
@ -3282,9 +3238,10 @@ This function returns 0 on error
|
|||
(e.g., an invalid option in \verb|what|).
|
||||
Each character in the string \verb|what|
|
||||
selects some fields of \verb|ar| to be filled,
|
||||
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|,
|
||||
and \verb|l| fills the field \verb|currentline|, etc.
|
||||
as indicated by the letter in parentheses in the definition of \verb|lua_Debug|:
|
||||
An \verb|S| fills in the fields \verb|source|, \verb|linedefined|,
|
||||
and \verb|what|;
|
||||
\verb|l| fills in the field \verb|currentline|, etc.
|
||||
|
||||
To get information about a function that is not active (that is,
|
||||
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.
|
||||
|
||||
\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,
|
||||
\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).
|
||||
|
||||
\item[nups]
|
||||
Number of upvalues of a C~function.
|
||||
If the function is not a C~function,
|
||||
\verb|nups| is set to 0.
|
||||
Number of upvalues of a function.
|
||||
|
||||
\item[func]
|
||||
The function being executed, as a \verb|lua_Object|.
|
||||
|
|
@ -3388,24 +3343,20 @@ value of that variable.
|
|||
For \verb|lua_setlocal|,
|
||||
you fill the \verb|index| and the \verb|value| fields of \verb|v|,
|
||||
and the function assigns that value to the variable.
|
||||
Both functions return 0 on failure, that happens
|
||||
if the index is greater than the number of active local variables.
|
||||
Both functions return 0 on failure;
|
||||
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
|
||||
local variables for a function in a given level of the stack:
|
||||
\begin{verbatim}
|
||||
int listvars (lua_State *L, int level) {
|
||||
lua_Debug ar;
|
||||
int i;
|
||||
lua_Localvar v;
|
||||
if (lua_getstack(L, level, &ar) == 0)
|
||||
return 0; /* failure: no such level on the stack */
|
||||
for (i=1; ; i++) {
|
||||
lua_Localvar v;
|
||||
v.index = i;
|
||||
if (lua_getlocal(L, &ar, &v) == 0)
|
||||
return 1; /* no more locals */
|
||||
for (v.index = 1; lua_getlocal(L, &ar, &v); v.index++)
|
||||
printf("%s\n", v.name);
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
\end{verbatim}
|
||||
|
||||
|
|
@ -3505,7 +3456,7 @@ until the last active local variable.)
|
|||
The function returns \nil\ if there is no local
|
||||
variable with the given index,
|
||||
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}
|
||||
|
||||
|
|
@ -3638,43 +3589,96 @@ some differences had to be introduced.
|
|||
Here is a list of all these incompatibilities.
|
||||
|
||||
\subsection*{Incompatibilities with \Index{version 3.2}}
|
||||
|
||||
\subsubsection*{Changes in the Language}
|
||||
\begin{itemize}
|
||||
|
||||
\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
|
||||
Garbage-collection tag methods for tables is now deprecated.
|
||||
|
||||
\item
|
||||
\verb|setglobal|, \verb|rawsetglobal|, and \verb|sort| no longer return a value;
|
||||
\verb|type| no longer return a second value.
|
||||
There is now only one tag method for order operators.
|
||||
|
||||
\item
|
||||
In nested function calls like \verb|f(g(x))|
|
||||
\emph{all} return values from \verb|g| are passed as arguments to \verb|f|.
|
||||
(This only happens when \verb|g| is the last
|
||||
[or the only] argument to \verb|f|.)
|
||||
|
||||
\item
|
||||
There is now only one tag method for order operators.
|
||||
\item
|
||||
The debug API has been completely rewritten.
|
||||
\item
|
||||
The pre-compiler may use the fact that some operators are associative,
|
||||
The pre-compiler may assume that some operators are associative,
|
||||
for optimizations.
|
||||
This may cause problems if these operators
|
||||
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
|
||||
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
|
||||
A \verb|const| qualifier has been added to \verb|char *|
|
||||
in all API functions that handle C~strings.
|
||||
|
||||
\item
|
||||
Some types \verb|long| were changed to \verb|size_t|.
|
||||
|
||||
\item
|
||||
\verb|luaL_openlib| no longer automatically calls \verb|lua_open|.
|
||||
So,
|
||||
you must now explicitly call \verb|lua_open| before opening
|
||||
the standard libraries.
|
||||
|
||||
\item
|
||||
\verb|lua_type| now returns a string describing the type,
|
||||
and is no longer a synonym for \verb|lua_tag|.
|
||||
\item Old pre-compiled code is obsolete, and must be re-compiled.
|
||||
|
||||
\end{itemize}
|
||||
|
||||
|
|
@ -3687,7 +3691,7 @@ and is no longer a synonym for \verb|lua_tag|.
|
|||
|
||||
\begin{Produc}
|
||||
|
||||
\produc{chunk}{\rep{stat} \opt{\ter{;}}}
|
||||
\produc{chunk}{\rep{stat \opt{\ter{;}}}}
|
||||
|
||||
\produc{block}{chunk}
|
||||
|
||||
|
|
@ -3702,43 +3706,72 @@ and is no longer a synonym for \verb|lua_tag|.
|
|||
\opt{\rwd{else} block} \rwd{end}
|
||||
\OrNL \rwd{return} \opt{explist1}
|
||||
\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}
|
||||
\OrNL \rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} block \rwd{end}
|
||||
\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}{%
|
||||
name
|
||||
\OrNL varorfunc \ter{[} exp1 \ter{]}
|
||||
\OrNL varorfunc \ter{.} name
|
||||
\Nter{name}
|
||||
\Or varorfunc \ter{[} exp1 \ter{]}
|
||||
\Or varorfunc \ter{.} \Nter{name}
|
||||
}
|
||||
|
||||
\produc{varorfunc}{var \Or functioncall}
|
||||
|
||||
\produc{varlist1}{var \rep{\ter{,} var}}
|
||||
|
||||
\produc{declist}{name \rep{\ter{,} name}}
|
||||
\produc{declist}{\Nter{name} \rep{\ter{,} \Nter{name}}}
|
||||
|
||||
\produc{init}{\ter{=} explist1}
|
||||
|
||||
\produc{explist1}{\rep{exp1 \ter{,}} exp}
|
||||
|
||||
\produc{exp1}{exp}
|
||||
|
||||
\produc{exp}{%
|
||||
\rwd{nil}
|
||||
\Or number
|
||||
\Or literal
|
||||
\Or \Nter{number}
|
||||
\Or \Nter{literal}
|
||||
\Or var
|
||||
\Or function
|
||||
\Or upvalue
|
||||
\Or functioncall
|
||||
\OrNL functioncall
|
||||
\Or tableconstructor
|
||||
\Or \ter{(} exp \ter{)}
|
||||
\Or exp binop 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{fieldlist}{%
|
||||
|
|
@ -3753,34 +3786,14 @@ and is no longer a synonym for \verb|lua_tag|.
|
|||
\produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}}
|
||||
\produc{ffield}{%
|
||||
\ter{[} exp \ter{]} \ter{=} exp
|
||||
\Or name \ter{=} exp
|
||||
\Or \Nter{name} \ter{=} exp
|
||||
}
|
||||
|
||||
\produc{functioncall}{%
|
||||
varorfunc args
|
||||
\Or varorfunc \ter{:} name args
|
||||
}
|
||||
\produc{binop}{\ter{+} \Or \ter{-} \Or \ter{*} \Or \ter{/} \Or \ter{\^{ }} \Or
|
||||
\ter{..} \OrNL \ter{<} \Or \ter{<=} \Or \ter{>} \Or \ter{>=}
|
||||
\Or \ter{==} \Or \ter{\~{ }=} \OrNL \rwd{and} \Or \rwd{or}}
|
||||
|
||||
\produc{args}{%
|
||||
\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}
|
||||
\produc{unop}{\ter{-} \Or \rwd{not}}
|
||||
|
||||
\end{Produc}
|
||||
%}===============================================================
|
||||
|
|
|
|||
Loading…
Reference in New Issue