From a94cba4b88a940cba7a35244b8a1b393f33a905c Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Thu, 19 Jul 2001 10:36:18 -0300 Subject: [PATCH] ready for 4.1 alpha? --- manual.tex | 792 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 488 insertions(+), 304 deletions(-) diff --git a/manual.tex b/manual.tex index 6e1d490f..8284b989 100644 --- a/manual.tex +++ b/manual.tex @@ -1,4 +1,4 @@ -% $Id: manual.tex,v 1.48 2001/01/29 19:33:55 roberto Exp roberto $ +% $Id: manual.tex,v 1.49 2001/01/31 19:53:01 roberto Exp roberto $ \documentclass[11pt]{article} \usepackage{fullpage} @@ -29,7 +29,7 @@ \newcommand{\ff}{$\bullet$\ } -\newcommand{\Version}{4.0} +\newcommand{\Version}{4.1 (alpha)} % LHF \renewcommand{\ter}[1]{{\rm`{\tt#1}'}} @@ -71,7 +71,7 @@ Last revised on \today \null\vfill \noindent -Copyright \copyright\ 1994--2000 TeCGraf, PUC-Rio. All rights reserved. +Copyright \copyright\ 1994--2001 TeCGraf, PUC-Rio. All rights reserved. \noindent Permission is hereby granted, without written agreement and without license @@ -110,7 +110,7 @@ This implementation contains no third-party code. \noindent Copies of this manual can be obtained at -\verb|http://www.tecgraf.puc-rio.br/lua/|. +\verb|http://www.lua.org|. \bigskip \noindent @@ -134,7 +134,7 @@ Waldemar Celes \tecgraf\ --- Computer Science Department --- PUC-Rio } -\date{{\small \tt\$Date: 2001/01/29 19:33:55 $ $}} +\date{{\small \tt\$Date: 2001/01/31 19:53:01 $ $}} \maketitle @@ -228,8 +228,8 @@ as stated in its copyright notice. The implementation described in this manual is available at the following URL's: \begin{verbatim} - http://www.tecgraf.puc-rio.br/lua/ - ftp://ftp.tecgraf.puc-rio.br/pub/lua/ + http://www.lua.org + ftp://ftp.lua.org \end{verbatim} Like any other reference manual, @@ -305,6 +305,7 @@ are interchangeable. Lua automatically detects the file type and acts accordingly. \index{pre-compilation} + \section{\Index{Types and Tags}} \label{TypesSec} Lua is a \emph{dynamically typed language}. @@ -365,23 +366,92 @@ to tables, and do not imply any kind of copy. Moreover, tables must be explicitly created before used \see{tableconstructor}. -Each of the types \M{nil}, \M{number}, and \M{string} has a different tag. -All values of each of these types have the same pre-defined tag. -As explained above, -values of type \M{function} can have two different tags, -depending on whether they are Lua functions or C~functions. -Finally, -values of type \M{userdata} and \M{table} can have variable tags, -assigned by the programmer \see{tag-method}. -The \verb|tag| function returns the tag of a given value. -User tags are created with the function \verb|newtag|. -The \verb|settag| function -is used to change the tag of a table \see{pdf-newtag}. -The tag of userdata values can only be set from~C \see{C-tags}. -Tags are mainly used to select \emph{tag methods} when -some events occur. -Tag methods are the main mechanism for extending the -semantics of Lua \see{tag-method}. + +\subsection{Tags} + +Each type has a \emph{name}, +and a numerical identifier, +called a \Index{tag}. +Tags are mainly used by C code, +to avoid the manipulation of strings. +Most operations over types, in the C API, +require a tag to identify the type. +In Lua, all operations over types work +both with type names or tags. + + +\subsection{User-defined Types} + +Lua programs can create new types, +called \Index{User-defined Types}. +A user-defined type is always based on a base type, +either a table or a userdata. +Objects of an extended type have an internal structure +identical to the corresponding base type, +but may have diferent semantics for each operation. + +The \verb|newtype| function creates a new type \see{pdf-newtype}. +Types created by Lua programs are always based upon tables; +types created by C can be based upon tables or upon userdata. +The \verb|settagmethod| function defines new semantics for +the operations of this new type \see{tag-method}. +The \verb|settype| function changes the type of a given object +\see{pdf-settype}. + + +\section{Garbage Collection}\label{GC} + +Lua does automatic memory management. +To do that, +Lua runs a \Index{garbage collector} from time to time. +All objects in Lua are subjected to automatic management: +tables, userdata, functions, and strings. + +Lua uses two numbers to control its garbage-collection cycles. +One number counts how many bytes of dynamic memory Lua is using, +and the other is a threshold. +When the number of bytes crosses the threshold, +Lua runs the garbage collector, +which reclaims the memory of all ``dead'' objects +(that is, objects no longer accessible from Lua). +The byte counter is corrected, +and then the threshold is reset to twice the value of the byte counter. + +Through the C API, you can consult those numbers, +and change the threshold \see{GC-API}. +Setting the threshold to zero actually forces an immediate +garbage-collection cycle, +while setting it to a huge number stops the garbage collector. +Using Lua code you have a more limited control of memory management, +through functions \verb|gcinfo| and \verb|collectgarbage|. + + +You can set garbage-collector tag methods for user-defined +types based on userdata \see{tag-method}. +Lua calls those functions when it is about to free a userdata +of the corresponding type. +Using this facility, you can coordinate Lua's garbage collection +with external resourse management +(such as closing files or freeing your own memory). + + +\subsection{Weak Tables}\label{weak-table} + +A \IndexEmph{weak table} is a table whose elements are +\IndexEmph{weak references}. +A weak reference is ignored by the garbage collector, +so that if the only references to an object are weak references, +the garbage collector will collect that object. + +A weak table can have weak keys, weak values, or both. +A table with weak keys allows the collection of its keys, +but avoids the collection of its values. +A table with both weak keys and weak values allow the collection of both. +In any case, if either the key or the value is collected, +the whole pair is removed from the table. +The weakness of a table is controled by the +function \verb|weakmode| \see{weakmode}. + \section{The Language} @@ -398,14 +468,16 @@ except that the definition of letter depends on the current locale: Any character considered alphabetic by the current locale can be used in an identifier. -The following words are \emph{reserved}, and cannot be used as identifiers: +The following words are \emph{reserved}, +and cannot be used as identifiers: \index{reserved words} \begin{verbatim} and break do else elseif - end for function if in - local nil not or repeat - return then until while + end for function global if + in local nil not or + repeat return then until while \end{verbatim} +(\rwd{global} is reserved for future use.) Lua is a case-sensitive language: \T{and} is a reserved word, but \T{And} and \T{\'and} @@ -447,6 +519,8 @@ Literal strings can also be delimited by matching \verb|[[| \dots\ \verb|]]|. Literals in this bracketed form may run for several lines, may contain nested \verb|[[| \dots\ \verb|]]| pairs, and do not interpret escape sequences. +When the \verb|[[| is immediatly followed by a newline, +this newline is not included in the string. This form is specially convenient for writing strings that contain program pieces or other quoted strings. @@ -457,6 +531,9 @@ the following three literals are equivalent: 2) '\97lo\10\04923"' 3) [[alo 123"]] + 4) [[ + alo + 123"]] \end{verbatim} \IndexEmph{Comments} start anywhere outside a string with a @@ -489,22 +566,6 @@ For complete control of how numbers are converted to strings, use the \verb|format| function \see{format}. -\subsection{\Index{Adjustment}} \label{adjust} - -Functions in Lua can return many values. -Because there are no type declarations, -when a function is called -the system does not know how many values the function will return, -or how many parameters it needs. -Therefore, sometimes, a list of values must be \emph{adjusted}, at run time, -to a given length. -If there are more values than are needed, -then the excess values are thrown away. -If there are less values than are needed, -then the list is extended with as many \nil's as needed. -This adjustment occurs in multiple assignments \see{assignment} -and in function calls \see{functioncall}. - \subsection{Statements}\label{stats} @@ -560,9 +621,15 @@ Multiple assignment can be used to exchange two values, as in x, y = y, x \end{verbatim} -The two lists in a multiple assignment may have different lengths. Before the assignment, the list of values is adjusted to -the length of the list of variables \see{adjust}. +the length of the list of variables. +If there are more values than are needed, +the excess values are thrown away. +If there are less values than are needed, +the list is extended with as many \nil's as needed. +If the list of expressions (\M{explist1}) ends with a function call, +all values returned by the function call enter in the list of values, +before the adjust. A single name can denote a global variable, a local variable, or a formal parameter: @@ -572,17 +639,16 @@ or a formal parameter: Square brackets are used to index a table: \begin{Produc} -\produc{var}{varorfunc \ter{[} exp1 \ter{]}} -\produc{varorfunc}{var \Or functioncall} +\produc{var}{exp \ter{[} exp \ter{]}} \end{Produc}% -The \M{varorfunc} should result in a table value, -from where the field indexed by the expression \M{exp1} +The first expression (\M{exp}) should result in a table value, +from where the field indexed by the expression \M{exp} value gets the assigned value. The syntax \verb|var.NAME| is just syntactic sugar for \verb|var["NAME"]|: \begin{Produc} -\produc{var}{varorfunc \ter{.} name} +\produc{var}{exp \ter{.} name} \end{Produc}% The meaning of assignments and evaluations of global variables and @@ -605,13 +671,14 @@ familiar syntax \index{repeat-until statement} \index{if-then-else statement} \begin{Produc} -\produc{stat}{\rwd{while} exp1 \rwd{do} block \rwd{end}} -\produc{stat}{\rwd{repeat} block \rwd{until} exp1} -\produc{stat}{\rwd{if} exp1 \rwd{then} block - \rep{\rwd{elseif} exp1 \rwd{then} block} +\produc{stat}{\rwd{while} exp \rwd{do} block \rwd{end}} +\produc{stat}{\rwd{repeat} block \rwd{until} exp} +\produc{stat}{\rwd{if} exp \rwd{then} block + \rep{\rwd{elseif} exp \rwd{then} block} \opt{\rwd{else} block} \rwd{end}} \end{Produc}% -The \Index{condition expression} \M{exp1} of a control structure may return any value. +The \Index{condition expression} \M{exp} of a +control structure may return any value. All values different from \nil\ are considered true; only \nil\ is considered false. @@ -650,7 +717,7 @@ one for numbers and one for tables. \newpage The numerical \rwd{for} loop has the following syntax: \begin{Produc} -\produc{stat}{\rwd{for} name \ter{=} exp1 \ter{,} exp1 \opt{\ter{,} exp1} +\produc{stat}{\rwd{for} name \ter{=} exp \ter{,} exp \opt{\ter{,} exp} \rwd{do} block \rwd{end}} \end{Produc}% A \rwd{for} statement like @@ -688,7 +755,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} exp1 +\produc{stat}{\rwd{for} name \ter{,} name \rwd{in} exp \rwd{do} block \rwd{end}} \end{Produc}% A \rwd{for} statement like @@ -699,10 +766,10 @@ is equivalent to the code: \begin{verbatim} do local _t = exp - local index, value = next(t, nil) + local index, value = next(_t, nil) while index do block - index, value = next(t, index) + index, value = next(_t, index) end end \end{verbatim} @@ -774,6 +841,9 @@ The basic expressions in Lua are \produc{exp}{tableconstructor} \end{Produc}% +An expression enclosed in parentheses always results +in only one value. + Numbers (numerical constants) and literal strings are explained in \See{lexical}; variables are explained in \See{assignment}; @@ -790,11 +860,6 @@ See \See{tag-method} for a description of these functions (\verb|getglobal| is in the basic library; \T{gettable\_event} is used for explanatory purposes only). -The non-terminal \M{exp1} is used to indicate that the values -returned by an expression must be adjusted to one single value: -\begin{Produc} -\produc{exp1}{exp} -\end{Produc}% \subsubsection{Arithmetic Operators} Lua supports the usual \Index{arithmetic operators}: @@ -823,7 +888,10 @@ If they are different, then the result is \nil. Otherwise, their values are compared. Numbers and strings are compared in the usual way. Tables, userdata, and functions are compared by reference, -that is, two tables are considered equal only if they are the \emph{same} table. +that is, +two tables are considered equal only if they are the \emph{same} table. +Every time you create a new table (or userdata, or function) this +new value is different from any previously existing value. The operator \verb|~=| is exactly the negation of equality (\verb|==|). \NOTE @@ -904,10 +972,10 @@ except for \verb|^| (exponentiation), which is right associative. \NOTE The pre-compiler may rearrange the order of evaluation of -associative operators (such as~\verb|..| or~\verb|+|), +associative or commutative operators, as long as these optimizations do not change normal results. However, these optimizations may change some results -if you define non-associative +if you define non-associative (or non-commutative) tag methods for these operators. \subsubsection{Table Constructors} \label{tableconstructor} @@ -920,14 +988,11 @@ The general syntax for constructors is \produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}} \produc{fieldlist}{lfieldlist \Or ffieldlist \Or lfieldlist \ter{;} ffieldlist \Or ffieldlist \ter{;} lfieldlist} -\produc{lfieldlist}{\opt{lfieldlist1}} +\produc{lfieldlist}{\opt{explist1 \opt{\ter{,}}}} \produc{ffieldlist}{\opt{ffieldlist1}} \end{Produc}% -The form \emph{lfieldlist1} is used to initialize lists: -\begin{Produc} -\produc{lfieldlist1}{exp \rep{\ter{,} exp} \opt{\ter{,}}} -\end{Produc}% +The form \emph{explist1} is used to initialize lists. The expressions in the list are assigned to consecutive numerical indices, starting with~1. For example, @@ -944,6 +1009,8 @@ is equivalent to a = temp end \end{verbatim} +If the last expression in the list is a function call, +all values returned by the call enter the list \see{functioncall}. The form \emph{ffieldlist1} initializes other fields in a table: \begin{Produc} @@ -982,20 +1049,20 @@ For example, all forms below are correct. \subsubsection{Function Calls} \label{functioncall} A \Index{function call} in Lua has the following syntax: \begin{Produc} -\produc{functioncall}{varorfunc args} +\produc{functioncall}{exp args} \end{Produc}% -First, \M{varorfunc} is evaluated. -If its value has type \emph{function}, +First, \M{exp} and \M{args} are evaluated. +If the value of \M{exp} has type \emph{function}, then this function is called, with the given arguments. Otherwise, the ``function'' tag method is called, -having as first parameter the value of \M{varorfunc}, -and then the original call arguments +having as first parameter the value of \M{exp}, +followed by the original call arguments \see{tag-method}. The form \begin{Produc} -\produc{functioncall}{varorfunc \ter{:} name args} +\produc{functioncall}{exp \ter{:} name args} \end{Produc}% can be used to call ``methods''. A call \verb|v:name(...)| @@ -1005,9 +1072,9 @@ except that \verb|v| is evaluated only once. Arguments have the following syntax: \begin{Produc} \produc{args}{\ter{(} \opt{explist1} \ter{)}} +\produc{explist1}{\rep{exp \ter{,}} exp} \produc{args}{tableconstructor} \produc{args}{literal} -\produc{explist1}{\rep{exp1 \ter{,}} exp} \end{Produc}% All argument expressions are evaluated before the call. A call of the form \verb|f{...}| is syntactic sugar for @@ -1020,20 +1087,16 @@ the argument list is a single literal string. Because a function can return any number of results \see{return}, -the number of results must be adjusted before they are used \see{adjust}. +the number of results must be adjusted before they are used. If the function is called as a statement \see{funcstat}, then its return list is adjusted to~0, thus discarding all returned values. -If the function is called in a place that needs a single value -(syntactically denoted by the non-terminal \M{exp1}), +If the function is called inside another expression, +or in the middle of a list of expressions, then its return list is adjusted to~1, thus discarding all returned values but the first one. -If the function is called in a place that can hold many values -(syntactically denoted by the non-terminal \M{exp}), +If the function is called as the last element of a list of expressions, then no adjustment is made. -The only places that can hold many values -is the last (or the only) expression in an assignment, -in an argument list, or in the \rwd{return} statement. Here are some examples: \begin{verbatim} f() -- adjusted to 0 results @@ -1043,7 +1106,16 @@ Here are some examples: a,b,c = x, f() -- f() is adjusted to 2 a,b,c = f() -- f() is adjusted to 3 return f() -- returns all values returned by f() - return x,y,f() -- returns a, b, and all values returned by f() + return x,y,f() -- returns x, y, and all values returned by f() + {f()} -- creates a list with all values returned by f() + {f(), nil} -- f() is adjusted to 1 result +\end{verbatim} + +If you embrace a function call in parentheses, +then it is adjusted to return exactly one value: +\begin{verbatim} + return x, y, (f()) -- returns x, y, and one value from f() + {(f())} -- create a table with exactly one element \end{verbatim} \subsubsection{\Index{Function Definitions}} \label{func-def} @@ -1054,7 +1126,7 @@ The syntax for function definition is block \rwd{end}} \produc{stat}{\rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} block \rwd{end}} -\produc{funcname}{name \Or name \ter{.} name \Or name \ter{:} name} +\produc{funcname}{name \rep{\ter{.} name} \opt{\ter{:} name}} \end{Produc}% The statement \begin{verbatim} @@ -1066,11 +1138,11 @@ is just syntactic sugar for \end{verbatim} and the statement \begin{verbatim} - function v.f () ... end + function v.c.f () ... end \end{verbatim} is syntactic sugar for \begin{verbatim} - v.f = function () ... end + v.c.f = function () ... end \end{verbatim} A function definition is an executable expression, @@ -1094,7 +1166,7 @@ initialized with the argument values: \label{vararg}% When a function is called, the list of \Index{arguments} is adjusted to -the length of the list of parameters \see{adjust}, +the length of the list of parameters, unless the function is a \Def{vararg function}, which is indicated by three dots (`\verb|...|') at the end of its parameter list. @@ -1132,20 +1204,17 @@ If control reaches the end of a function without encountering a \rwd{return} statement, then the function returns with no results. -The syntax -\begin{Produc} -\produc{funcname}{name \ter{:} name} -\end{Produc}% +The \emph{colon} syntax is used for defining \IndexEmph{methods}, that is, functions that have an implicit extra parameter \IndexVerb{self}. The statement \begin{verbatim} - function v:f (...) ... end + function v.c:f (...) ... end \end{verbatim} is just syntactic sugar for \begin{verbatim} - v.f = function (self, ...) ... end + v.c.f = function (self, ...) ... end \end{verbatim} Note that the function gets an extra formal parameter called \verb|self|. @@ -1192,7 +1261,7 @@ Here are some examples: local y -- a and y are local to g p = a -- OK, access local `a' p = c -- OK, access global `c' - p = b -- ERROR: cannot access a variable in outer scope + p = b -- ERROR: cannot access a variable in outer function p = %b -- OK, access frozen value of `b' (local to `f') %b = 3 -- ERROR: cannot change an upvalue %b.x = 3 -- OK, change the table contents @@ -1245,34 +1314,33 @@ Lua code can ``catch'' an error using the function \subsection{Tag Methods} \label{tag-method}\index{tag method} -Lua provides a powerful mechanism to extend its semantics, -called \emph{tag methods}. A tag method is a programmer-defined function -that is called at specific key points during the execution of a Lua program, -allowing the programmer to change the standard Lua behavior at these points. -Each of these points is called an \Def{event}. +that defines how Lua operations act over user-defined types +(and, sometimes, over basic types as well). +An \Def{event} is any operation that may invoke a tag method. -The tag method called for any specific event is selected -according to the tag of the values involved +Lua selects the tag method called for any specific event +according to the types of the values involved in the event \see{TypesSec}. The function \IndexLIB{settagmethod} changes the tag method -associated with a given pair \M{(tag, event)}. -Its first parameter is the tag, the second parameter is the event name -(a string; see below), +associated with a given pair \M{(type, event)}. +Its first parameter is the type (its name or its tag), +the second parameter is the event name (a string; see below), and the third parameter is the new method (a function), or \nil\ to restore the default behavior for the pair. -The \verb|settagmethod| function returns the previous tag method for that pair. A companion function \IndexLIB{gettagmethod} -receives a tag and an event name and returns the +receives a type and an event name and returns the current method associated with the pair. Tag methods are called in the following events, identified by the given names. The semantics of tag methods is better explained by a Lua function describing the behavior of the interpreter at each event. -This function not only shows when a tag method is called, -but also its arguments, its results, and the default behavior. -The code shown here is only \emph{illustrative}; +Each event-handler function shows how a tag method is called, +its arguments (that is, its signature), +its results, +and the default behavior in the absence of a tag method. +The code shown here in Lua is only illustrative; the real behavior is hard coded in the interpreter, and it is much more efficient than this simulation. All functions used in these descriptions @@ -1287,7 +1355,7 @@ called when a \verb|+| operation is applied to non-numerical operands. The function \verb|getbinmethod| below defines how Lua chooses a tag method for a binary operation. First, Lua tries the first operand. -If its tag does not define a tag method for the operation, +If its type does not define a tag method for the operation, then Lua tries the second operand. If it also fails, then it gets a tag method from tag~0. \begin{verbatim} @@ -1307,9 +1375,8 @@ the tag method for the ``add'' event is else -- at least one of the operands is not numeric local tm = getbinmethod(op1, op2, "add") if tm then - -- call the method with both operands and an extra - -- argument with the event name - return tm(op1, op2, "add") + -- call the method with both operands + return tm(op1, op2) else -- no tag method available: default behavior error("unexpected type at arithmetic operation") end @@ -1336,9 +1403,8 @@ even for numerical operands. function pow_event (op1, op2) local tm = getbinmethod(op1, op2, "pow") if tm then - -- call the method with both operands and an extra - -- argument with the event name - return tm(op1, op2, "pow") + -- call the method with both operands + return tm(op1, op2) else -- no tag method available: default behavior error("unexpected type at arithmetic operation") end @@ -1358,9 +1424,8 @@ called when a unary \verb|-| operation is applied to a non-numerical operand. local tm = gettagmethod(tag(op), "unm") or gettagmethod(0, "unm") if tm then - -- call the method with the operand, nil, and an extra - -- argument with the event name - return tm(op, nil, "unm") + -- call the method with the operand and nil + return tm(op, nil) else -- no tag method available: default behavior error("unexpected type at arithmetic operation") end @@ -1381,15 +1446,15 @@ It corresponds to the \verb|<| operator. else local tm = getbinmethod(op1, op2, "lt") if tm then - return tm(op1, op2, "lt") + return tm(op1, op2) else error("unexpected type at comparison"); end end end \end{verbatim} -The other order operators use this tag method according to the -usual equivalences: +The other order operators use the \verb|"lt"| tag method +according to the usual equivalences: \begin{verbatim} a>b <=> b not (b