GitHub/lua
1
0
Fork 0
mirror of https://github.com/lua/lua.git synced 2025-01-14 05:43:00 +08:00
Code Issues Projects Releases Wiki Activity

on the way to 5.0

Browse Source
This commit is contained in:
Roberto Ierusalimschy 2002-06-06 09:49:28 -03:00
parent e3cddc950c
commit dc6e6c48bb
1 changed files with 165 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

316
manual.tex
View File

@ -1,4 +1,4 @@
% $Id: manual.tex,v 1.54 2001/10/31 20:31:38 roberto Exp $ % $Id: manual.tex,v 1.55 2002/02/14 21:48:32 roberto Exp roberto $
\documentclass[11pt,twoside,draft]{article} \documentclass[11pt,twoside,draft]{article}
\usepackage{fullpage} \usepackage{fullpage}
@ -20,7 +20,7 @@
\newcommand{\False}{{\bf false}} \newcommand{\False}{{\bf false}}
\newcommand{\True}{{\bf true}} \newcommand{\True}{{\bf true}}
%\def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}} %\def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}}
\def\tecgraf{{\sf TeCGraf}} \def\tecgraf{{\sf Tecgraf}}
\newcommand{\Index}[1]{#1\index{#1@{\lowercase{#1}}}} \newcommand{\Index}[1]{#1\index{#1@{\lowercase{#1}}}}
\newcommand{\IndexVerb}[1]{\T{#1}\index{#1@{\tt #1}}} \newcommand{\IndexVerb}[1]{\T{#1}\index{#1@{\tt #1}}}
@ -81,39 +81,31 @@ Last revised on \today
\null\vfill \null\vfill
\noindent \noindent
Copyright \copyright\ 1994--2001 TeCGraf, PUC-Rio. All rights reserved. Copyright \copyright\ 2002 Tecgraf, PUC-Rio. All rights reserved.
Permission is hereby granted, without written agreement and without license Permission is hereby granted, free of charge,
or royalty fees, to use, copy, modify, translate, and distribute to any person obtaining a copy of this software
this software and its documentation (hereby called the ``package'') and associated documentation files (the "Software"),
for any purpose, including commercial applications, subject to to deal in the Software without restriction,
the following conditions: including without limitation the rights to use, copy, modify,
\begin{itemize} merge, publish, distribute, sublicense,
\item The above copyright notice and this permission notice shall appear in all and/or sell copies of the Software,
copies or substantial portions of this package. and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
\item The origin of this package must not be misrepresented; you must not The above copyright notice and this permission notice shall be
claim that you wrote the original package. If you use this package in a included in all copies or substantial portions of the Software.
product, an acknowledgment in the product documentation would be greatly
appreciated (but it is not required).
\item Altered source versions must be plainly marked as such, and must not be THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
misrepresented as being the original package. EXPRESS OR IMPLIED,
\end{itemize} INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
The authors specifically disclaim any warranties, including, but not limited FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
to, the implied warranties of merchantability and fitness for a particular IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
purpose. The package provided hereunder is on an ``as~is'' basis, and the FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
authors have no obligation to provide maintenance, support, updates, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
enhancements, or modifications. In no event shall TeCGraf, PUC-Rio, or the ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
authors be held liable to any party for direct, indirect, special, OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
incidental, or consequential damages arising out of the use of this package
and its documentation.
The Lua language and this implementation have been entirely designed and
written by Waldemar Celes, Roberto Ierusalimschy, and Luiz Henrique de
Figueiredo at TeCGraf, PUC-Rio in Brazil.
This implementation contains no third-party code.
Copies of this manual can be obtained at Copies of this manual can be obtained at
Lua's official web site, Lua's official web site,
@ -140,7 +132,7 @@ Waldemar Celes
\tecgraf\ --- Computer Science Department --- PUC-Rio \tecgraf\ --- Computer Science Department --- PUC-Rio
} }
%\date{{\small \tt\$Date: 2001/10/31 20:31:38 $ $}} %\date{{\small \tt\$Date: 2002/02/14 21:48:32 $ $}}
\maketitle \maketitle
@ -282,12 +274,10 @@ environments, and freely switch between them \see{mangstate}.
The global environment can be manipulated by Lua code or The global environment can be manipulated by Lua code or
by the embedding program, by the embedding program,
which can read and write global variables
using the API functions from the library that implements Lua. using the API functions from the library that implements Lua.
The unit of execution of Lua is called a \Def{chunk}. The unit of execution of Lua is called a \Def{chunk}.
A chunk is simply a sequence of statements, A chunk is simply a sequence of statements.
which are executed sequentially.
Statements are described in \See{stats}. Statements are described in \See{stats}.
A chunk may be stored in a file or in a string inside the host program. A chunk may be stored in a file or in a string inside the host program.
@ -330,7 +320,7 @@ Lua is 8-bit clean,
and so strings may contain any 8-bit character, and so strings may contain any 8-bit character,
including embedded zeros (\verb|'\0'|) \see{lexical}. including embedded zeros (\verb|'\0'|) \see{lexical}.
Functions are considered \emph{first-class values} in Lua. Functions are \emph{first-class values} in Lua.
This means that functions can be stored in variables, This means that functions can be stored in variables,
passed as arguments to other functions, and returned as results. passed as arguments to other functions, and returned as results.
Lua can call (and manipulate) functions written in Lua and Lua can call (and manipulate) functions written in Lua and
@ -353,7 +343,7 @@ The type \emph{table} implements \Index{associative arrays},
that is, \Index{arrays} that can be indexed not only with numbers, that is, \Index{arrays} that can be indexed not only with numbers,
but with any value (except \nil). but with any value (except \nil).
Moreover, Moreover,
tables are \emph{heterogeneous}, tables can be \emph{heterogeneous},
that is, they can contain values of all types. that is, they can contain values of all types.
Tables are the sole data structuring mechanism in Lua; Tables are the sole data structuring mechanism in Lua;
they may be used not only to represent ordinary arrays, they may be used not only to represent ordinary arrays,
@ -368,10 +358,7 @@ Like indices, the value of a table field can be of any type.
In particular, In particular,
because functions are first class values, because functions are first class values,
table fields may contain functions. table fields may contain functions.
So, tables may also carry \emph{methods}. So, tables may also carry \emph{methods} \see{func-def}.
%The form \verb|t:f(x)| is syntactic sugar for \verb|t.f(t,x)|,
%which calls the method \verb|f| from the table \verb|t| passing
%the table itself as the first parameter \see{func-def}.
Tables, functions, and userdata values are \emph{objects}: Tables, functions, and userdata values are \emph{objects}:
variables do not actually \emph{contain} these values, variables do not actually \emph{contain} these values,
@ -394,7 +381,7 @@ Lua checks for a function in the field \verb|"add"| in its metatable.
If it finds one, If it finds one,
Lua calls that function to perform the addition. Lua calls that function to perform the addition.
A metatable works as a kind of an extended ``type'' for the object. A metatable works as a kind of an extended ``type'' for the object:
Objects that share a metatable has identical behavior. Objects that share a metatable has identical behavior.
A metatable controls how an object behaves in arithmetic operations, A metatable controls how an object behaves in arithmetic operations,
@ -413,7 +400,8 @@ through the \verb|metatable| function \see{pdf-metatable}.
\subsection{\Index{Coercion}} \label{coercion} \subsection{\Index{Coercion}} \label{coercion}
Lua provides automatic conversion between string and number values at run time. Lua provides automatic conversion between
string and number values at run time.
Any arithmetic operation applied to a string tries to convert Any arithmetic operation applied to a string tries to convert
that string to a number, following the usual rules. that string to a number, following the usual rules.
Conversely, whenever a number is used when a string is expected, Conversely, whenever a number is used when a string is expected,
@ -430,15 +418,16 @@ use the \verb|format| function \see{format}.
There are two kinds of variables in Lua: There are two kinds of variables in Lua:
global variables global variables
and local variables. and local variables.
\Index{Global variables} do not need to be declared.
Variables are assumed to be global unless explicitly declared local Variables are assumed to be global unless explicitly declared local
\see{localvar}. \see{localvar}.
Before the first assignment, the value of a variable is \nil\ % Before the first assignment, the value of a variable is \nil.
(this default can be changed for global variables; see \See{tag-method}).
An ordinary Lua table is used to keep all global names and values. All global variables live as fields in ordinary Lua tables.
This table can be accessed and changed with the \verb|globals| function Usually, globals live in a table called \Index{table of globals}.
\see{pdf-globals}. However, a function can individually change its global table,
so that all global variables in that function will refer to that table.
This mechanism allows the creation of \Index{namespaces} and other
modularization facilities.
\Index{Local variables} are lexically scoped. \Index{Local variables} are lexically scoped.
Therefore, local variables can be freely accessed by functions Therefore, local variables can be freely accessed by functions
@ -501,11 +490,11 @@ A weak table can have weak keys, weak values, or both.
A table with weak keys allows the collection of its keys, A table with weak keys allows the collection of its keys,
but prevents the collection of its values. but prevents the collection of its values.
A table with both weak keys and weak values allows the collection of A table with both weak keys and weak values allows the collection of
both keys and values both keys and values.
In any case, if either the key or the value is collected, In any case, if either the key or the value is collected,
the whole pair is removed from the table. the whole pair is removed from the table.
The weakness of a table is controled by the The weakness of a table is controled by the
\verb|weakmode| field in its metatable \see{weakmode}. \verb|__weakmode| field in its metatable \see{weakmode}.
%------------------------------------------------------------------------------ %------------------------------------------------------------------------------
@ -538,13 +527,12 @@ and cannot be used as identifiers:
or repeat return then true or repeat return then true
until while until while
\end{verbatim} \end{verbatim}
(The keyword \rwd{global} is reserved for future use.)
Lua is a case-sensitive language: Lua is a case-sensitive language:
\T{and} is a reserved word, but \T{And} and \T{\'and} \T{and} is a reserved word, but \T{And} and \T{\'and}
(if the locale permits) are two different, valid identifiers. (if the locale permits) are two different, valid identifiers.
As a convention, identifiers starting with an underscore followed by As a convention, identifiers starting with an underscore followed by
uppercase letters (such as \verb|_INPUT|) uppercase letters (such as \verb|_VERSION|)
are reserved for internal variables. are reserved for internal variables.
The following strings denote other \Index{tokens}: The following strings denote other \Index{tokens}:
@ -574,7 +562,7 @@ A character in a string may also be specified by its numerical value,
through the escape sequence `\verb|\|\emph{ddd}', through the escape sequence `\verb|\|\emph{ddd}',
where \emph{ddd} is a sequence of up to three \emph{decimal} digits. where \emph{ddd} is a sequence of up to three \emph{decimal} digits.
Strings in Lua may contain any 8-bit value, including embedded zeros, Strings in Lua may contain any 8-bit value, including embedded zeros,
which can be specified as `\verb|\000|'. which can be specified as `\verb|\0|'.
Literal strings can also be delimited by matching \verb|[[| $\ldots$ \verb|]]|. Literal strings can also be delimited by matching \verb|[[| $\ldots$ \verb|]]|.
Literals in this bracketed form may run for several lines, Literals in this bracketed form may run for several lines,
@ -589,7 +577,7 @@ other quoted strings.
As an example, in a system using ASCII As an example, in a system using ASCII
(in which `\verb|a|' is coded as~97, (in which `\verb|a|' is coded as~97,
newline is coded as~10, and `\verb|1|' is coded as~49), newline is coded as~10, and `\verb|1|' is coded as~49),
the following four literals below are equivalent: the four literals below denote the same string:
\begin{verbatim} \begin{verbatim}
1) "alo\n123\"" 1) "alo\n123\""
2) '\97lo\10\04923"' 2) '\97lo\10\04923"'
@ -608,8 +596,14 @@ Examples of valid numerical constants are
\end{verbatim} \end{verbatim}
\IndexEmph{Comments} start anywhere outside a string with a \IndexEmph{Comments} start anywhere outside a string with a
double hyphen (\verb|--|) and run until the end of the line. double hyphen (\verb|--|);
(There are no block comments in Lua.) If the text after \verb|--| is different from \verb|[[|,
the comment is a short comment,
that runs until the end of the line.
Otherwise, it is a long comment,
that runs until the corresponding \verb|]]|.
Long comments may run for several lines,
and may contain nested \verb|[[| $\ldots$ \verb|]]| pairs.
For convenience, For convenience,
the first line of a chunk is skipped if it starts with \verb|#|. the first line of a chunk is skipped if it starts with \verb|#|.
This facility allows the use of Lua as a script interpreter This facility allows the use of Lua as a script interpreter
@ -647,15 +641,19 @@ The expression denoting the table to be indexed has a restricted syntax;
The meaning of assignments and evaluations of global and The meaning of assignments and evaluations of global and
indexed variables can be changed via metatables. indexed variables can be changed via metatables.
An assignment to a global variable \verb|x = val| An assignment to a global variable \verb|x = val|
is equivalent to an assignment in the global table: is equivalent to the assignment
\verb|globals().x = val|. \verb|_glob.x = val|,
where \verb|_glob| is the table of globals of the running function
(\see{global-table} for a discussion about the table of globals).
An assignment to an indexed variable \verb|t[i] = val| is equivalent to An assignment to an indexed variable \verb|t[i] = val| is equivalent to
\verb|settable_event(t,i,val)|. \verb|settable_event(t,i,val)|.
An access to a global variable \verb|x| An access to a global variable \verb|x|
is equivalent to an access to the global table: \verb|globals().x|. is equivalent to \verb|_glob.x|
(again, \see{global-table} for a discussion about \verb|_glob|).
An access to an indexed variable \verb|t[i]| is equivalent to An access to an indexed variable \verb|t[i]| is equivalent to
a call \verb|gettable_event(t,i)|. a call \verb|gettable_event(t,i)|.
See \See{metatable} for a complete description of these functions. See \See{metatable} for a complete description of the
\verb|settable_event| and \verb|gettable_event| functions.
(These functions are not defined in Lua. (These functions are not defined in Lua.
We use them here only for explanatory purposes.) We use them here only for explanatory purposes.)
@ -667,8 +665,7 @@ similar to those in Pascal or C.
The conventional commands include The conventional commands include
assignment, control structures, and procedure calls. assignment, control structures, and procedure calls.
Non-conventional commands include table constructors Non-conventional commands include table constructors
\see{tableconstructor} and variable declarations.
and local variable declarations \see{localvar}.
\subsubsection{Chunks}\label{chunks} \subsubsection{Chunks}\label{chunks}
The unit of execution of Lua is called a \Def{chunk}. The unit of execution of Lua is called a \Def{chunk}.
@ -687,7 +684,7 @@ Non-terminals are shown in \emph{italics},
keywords are shown in {\bf bold}, keywords are shown in {\bf bold},
and other terminal symbols are shown in {\tt typewriter} font, and other terminal symbols are shown in {\tt typewriter} font,
enclosed in single quotes. enclosed in single quotes.
The complete syntax of Lua in EBNF is given on page~\pageref{BNF}. The complete syntax of Lua in extended BNF is given on page~\pageref{BNF}.
\subsubsection{Blocks} \subsubsection{Blocks}
A \Index{block} is a list of statements; A \Index{block} is a list of statements;
@ -702,7 +699,7 @@ A block may be explicitly delimited:
\end{Produc}% \end{Produc}%
\IndexKW{do} \IndexKW{do}
Explicit blocks are useful Explicit blocks are useful
to control the scope of local variables \see{localvar}. to control the scope of variable declarations.
Explicit blocks are also sometimes used to Explicit blocks are also sometimes used to
add a \rwd{return} or \rwd{break} statement in the middle add a \rwd{return} or \rwd{break} statement in the middle
of another block \see{control}. of another block \see{control}.
@ -723,9 +720,9 @@ Expressions are discussed in \See{expressions}.
Before the assignment, Before the assignment,
the list of values is \emph{adjusted} to the length of the list of values is \emph{adjusted} to the length of
the list of variables.\index{adjustment} the list of variables.\index{adjustment}
If there are more values than are needed, If there are more values than needed,
the excess values are thrown away. the excess values are thrown away.
If there are less values than are needed, If there are less values than needed,
the list is extended with as many \nil's as needed. the list is extended with as many \nil's as needed.
If the list of expressions ends with a function call, If the list of expressions ends with a function call,
then all values returned by that function call enter in the list of values, then all values returned by that function call enter in the list of values,
@ -739,7 +736,7 @@ So, the code
i = 3 i = 3
i, a[i] = i+1, 20 i, a[i] = i+1, 20
\end{verbatim} \end{verbatim}
sets \verb|a[3]| to 20, but does not affect \verb|a[4]| sets \verb|a[3]| to 20, without affecting \verb|a[4]|
because the \verb|i| in \verb|a[i]| is evaluated because the \verb|i| in \verb|a[i]| is evaluated
before it is assigned 4. before it is assigned 4.
Similarly, the line Similarly, the line
@ -762,11 +759,12 @@ familiar syntax:
\rep{\rwd{elseif} exp \rwd{then} block} \rep{\rwd{elseif} exp \rwd{then} block}
\opt{\rwd{else} block} \rwd{end}} \opt{\rwd{else} block} \rwd{end}}
\end{Produc}% \end{Produc}%
There is also a \rwd{for} statement in two flavors \see{for}. Lua also has a \rwd{for} statement, in two flavors \see{for}.
The \Index{condition expression} \M{exp} of a The \Index{condition expression} \M{exp} of a
control structure may return any value. control structure may return any value.
All values different from \nil\ and \False\ are considered true; All values different from \nil\ and \False\ are considered true
(in particular, the number 0 and the empty string are also true);
both \False\ and \nil\ are considered false. both \False\ and \nil\ are considered false.
The \rwd{return} statement is used to return values The \rwd{return} statement is used to return values
@ -858,51 +856,45 @@ it calls this function to produce a new value for each iteration,
stopping when the new value is \nil. stopping when the new value is \nil.
It has the following syntax: It has the following syntax:
\begin{Produc} \begin{Produc}
\produc{stat}{\rwd{for} name \opt{\ter{,} name} \rwd{in} exp \produc{stat}{\rwd{for} name \rep{\ter{,} name} \rwd{in} explist1
\rwd{do} block \rwd{end}} \rwd{do} block \rwd{end}}
\end{Produc}% \end{Produc}%
A \rwd{for} statement like A \rwd{for} statement like
\begin{verbatim} \begin{verbatim}
for var1, var2 in exp do block end for var_1, ..., var_n in explist do block end
\end{verbatim} \end{verbatim}
is equivalent to the code: is equivalent to the code:
\begin{verbatim} \begin{verbatim}
do do
local _f = exp local _f, _s, var_1 = explist
while 1 do while 1 do
local var1, var2 = _f() local var_2, ..., var_n
if var1 == nil then break end var_1, ..., var_n = _f(_s, var_1)
if var_1 == nil then break end
block block
end end
end end
\end{verbatim} \end{verbatim}
Note the following: Note the following:
\begin{itemize}\itemsep=0pt \begin{itemize}\itemsep=0pt
\item \verb|exp| is evaluated only once. \item \verb|explist| is evaluated only once.
Its result is the function that will be evaluated for each loop. Its results are a ``generator'' function,
\item \verb|_f| is an invisible variable. a ``state'', and an initial value for the ``iterator variable''.
The name is here for explanatory purposes only. \item \verb|_f| and \verb|_s| are invisible variables.
\item The behavior is \emph{undefined} if you assign to \verb|var1| The names are here for explanatory purposes only.
or \verb|var2| inside the block. \item The behavior is \emph{undefined} if you assign to any
\verb|var_i| inside the block.
\item You can use \rwd{break} to exit a \rwd{for} loop. \item You can use \rwd{break} to exit a \rwd{for} loop.
\item The loop variables \verb|var1| and \verb|var2| are \item The loop variables \verb|var_i| are local to the statement;
local to the statement;
you cannot use their values after the \rwd{for} ends. you cannot use their values after the \rwd{for} ends.
If you need these values, If you need these values,
then assign them to other variables before breaking or exiting the loop. then assign them to other variables before breaking or exiting the loop.
\item The absence of the optional variable \verb|var2| does not
change the meaning of the loop.
\end{itemize} \end{itemize}
If the generator is a table \verb|t|, If the first result of the expression list is a table \verb|t|
then the loop works as if it has received the following generator function: (instead of a function),
\begin{verbatim} then the loop works as if it has received \verb|next, t| as its
local k,v = nil expression list.
function generator ()
k,v = next(t, k)
return k,v
end
\end{verbatim}
That is, the loop iterates over the (key,value) pairs of the table. That is, the loop iterates over the (key,value) pairs of the table.
@ -1341,7 +1333,7 @@ is syntactic sugar for
\index{visibility} \index{visibility}
Lua is a lexically scoped language. Lua is a lexically scoped language.
The scope of local variables begins at the first statement \emph{after} The scope of variables begins at the first statement \emph{after}
their declaration and lasts until the end of the innermost block that their declaration and lasts until the end of the innermost block that
includes the declaration. includes the declaration.
For instance: For instance:
@ -1352,7 +1344,7 @@ For instance:
print(x) --> 10 print(x) --> 10
x = x+1 x = x+1
do -- another block do -- another block
local x = x+1 -- another x local x = x+1 -- another `x'
print(x) --> 12 print(x) --> 12
end end
print(x) --> 11 print(x) --> 11
@ -1390,8 +1382,6 @@ In that code,
each function uses a different \verb|y| variable, each function uses a different \verb|y| variable,
while all of them share the same \verb|x|. while all of them share the same \verb|x|.
\subsection{Error Handling} \label{error} \subsection{Error Handling} \label{error}
Because Lua is an extension language, Because Lua is an extension language,
@ -1446,7 +1436,11 @@ If so, the value associated with that key (the \IndexEmph{handler})
controls how Lua will perform the operation. controls how Lua will perform the operation.
Metatables control the operations listed next. Metatables control the operations listed next.
Each operation is identified by its corresponding key. Each operation is identified by its corresponding name.
The key for each operation is a string with its name prefixed by
two underscores;
for instance, the key for operation ``add'' is the
string \verb|"__add"|.
The semantics of these operations is better explained by a Lua function The semantics of these operations is better explained by a Lua function
describing how the interpreter executes that operation. describing how the interpreter executes that operation.
%Each function shows how a handler is called, %Each function shows how a handler is called,
@ -1483,7 +1477,7 @@ the behavior of the ``add'' operation is
if o1 and o2 then -- both operands are numeric if o1 and o2 then -- both operands are numeric
return o1+o2 -- '+' here is the primitive 'add' return o1+o2 -- '+' here is the primitive 'add'
else -- at least one of the operands is not numeric else -- at least one of the operands is not numeric
local h = getbinhandler(op1, op2, "add") local h = getbinhandler(op1, op2, "__add")
if h then if h then
-- call the handler with both operands -- call the handler with both operands
return h(op1, op2) return h(op1, op2)
@ -1510,7 +1504,7 @@ Behavior similar to the ``add'' operation.
the \verb|^| operation (exponentiation) operation. the \verb|^| operation (exponentiation) operation.
\begin{verbatim} ?? \begin{verbatim} ??
function pow_op (op1, op2) function pow_op (op1, op2)
local h = getbinhandler(op1, op2, "pow") local h = getbinhandler(op1, op2, "__pow")
if h then if h then
-- call the handler with both operands -- call the handler with both operands
return h(op1, op2) return h(op1, op2)
@ -1529,7 +1523,7 @@ the unary \verb|-| operation.
return -o -- '-' here is the primitive 'unm' return -o -- '-' here is the primitive 'unm'
else -- the operand is not numeric. else -- the operand is not numeric.
-- Try to get a handler from the operand; -- Try to get a handler from the operand;
local h = metatable(op).unm local h = metatable(op).__unm
if h then if h then
-- call the handler with the operand and nil -- call the handler with the operand and nil
return h(op, nil) return h(op, nil)
@ -1549,7 +1543,7 @@ the \verb|<| operation.
elseif type(op1) == "string" and type(op2) == "string" then elseif type(op1) == "string" and type(op2) == "string" then
return op1 < op2 -- lexicographic comparison return op1 < op2 -- lexicographic comparison
else else
local h = getbinhandler(op1, op2, "lt") local h = getbinhandler(op1, op2, "__lt")
if h then if h then
return h(op1, op2) return h(op1, op2)
else else
@ -1574,7 +1568,7 @@ the \verb|..| (concatenation) operation.
(type(op2) == "string" or type(op2) == "number") then (type(op2) == "string" or type(op2) == "number") then
return op1..op2 -- primitive string concatenation return op1..op2 -- primitive string concatenation
else else
local h = getbinhandler(op1, op2, "concat") local h = getbinhandler(op1, op2, "__concat")
if h then if h then
return h(op1, op2) return h(op1, op2)
else else
@ -1593,14 +1587,14 @@ See the ``gettable'' operation for its semantics.
called whenever Lua accesses an indexed variable. called whenever Lua accesses an indexed variable.
\begin{verbatim} \begin{verbatim}
function gettable_op (table, key) function gettable_op (table, key)
local h = metatable(table).gettable local h = metatable(table).__gettable
if h == nil then if h == nil then
if type(table) ~= "table" then if type(table) ~= "table" then
error("indexed expression not a table"); error("indexed expression not a table");
else else
local v = rawget(table, key) local v = rawget(table, key)
if v ~= nil then return v end if v ~= nil then return v end
h = metatable(table).index h = metatable(table).__index
if h == nil then return nil end if h == nil then return nil end
end end
end end
@ -1614,7 +1608,7 @@ called whenever Lua accesses an indexed variable.
called when Lua assigns to an indexed variable. called when Lua assigns to an indexed variable.
\begin{verbatim} \begin{verbatim}
function settable_event (table, key, value) function settable_event (table, key, value)
local h = metatable(table).settable local h = metatable(table).__settable
if h == nil then if h == nil then
if type(table) ~= "table" then if type(table) ~= "table" then
error("indexed expression not a table") error("indexed expression not a table")
@ -1634,7 +1628,7 @@ called when Lua calls a value.
if type(func) == "function" then if type(func) == "function" then
return func(unpack(arg)) -- regular call return func(unpack(arg)) -- regular call
else else
local h = metatable(func).call local h = metatable(func).__call
if h then if h then
tinsert(arg, 1, func) tinsert(arg, 1, func)
return h(unpack(arg)) return h(unpack(arg))
@ -1656,7 +1650,7 @@ For each userdata to be collected,
Lua does the equivalent of the following function: Lua does the equivalent of the following function:
\begin{verbatim} \begin{verbatim}
function gc_op (obj) function gc_op (obj)
local h = metatable(obj).gc local h = metatable(obj).__gc
if h then if h then
h(obj) h(obj)
end end
@ -1673,7 +1667,7 @@ Second, metatables control the weakmode of tables \see{weak-table}.
The weakmode of a table \verb|t| is defined by a string: The weakmode of a table \verb|t| is defined by a string:
\label{weakmode} \label{weakmode}
\begin{verbatim} \begin{verbatim}
s = metatable(t).weakmode s = metatable(t).__weakmode
\end{verbatim} \end{verbatim}
Valid values for this string are \verb|"k"| for weak keys, Valid values for this string are \verb|"k"| for weak keys,
\verb|"v"| for weak values, \verb|"v"| for weak values,
@ -1713,17 +1707,9 @@ every function in the library (except \verb|lua_open| below).
Before calling any API function, Before calling any API function,
you must create a state by calling you must create a state by calling
\begin{verbatim} \begin{verbatim}
lua_State *lua_open (int stacksize); lua_State *lua_open (void);
\end{verbatim} \end{verbatim}
\DefAPI{lua_open} \DefAPI{lua_open}
The sole argument to this function is the stack size for the interpreter.
(Each function call needs one stack position for each argument, local variable,
and temporary value, plus one position for book-keeping.
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.)
If \verb|stacksize| is zero,
then a default size of~1024 is used.
To release a state created with \verb|lua_open|, call To release a state created with \verb|lua_open|, call
\begin{verbatim} \begin{verbatim}
@ -1752,7 +1738,7 @@ If you have a C~library that offers multi-threading or co-routines,
then Lua can cooperate with it to implement the equivalent facility in Lua. then Lua can cooperate with it to implement the equivalent facility in Lua.
The following function creates a new ``thread'' in Lua: The following function creates a new ``thread'' in Lua:
\begin{verbatim} \begin{verbatim}
lua_State *lua_newthread (lua_State *L, int stacksize); lua_State *lua_newthread (lua_State *L);
\end{verbatim} \end{verbatim}
\DefAPI{lua_newthread} \DefAPI{lua_newthread}
The new state returned by this function shares with the original state The new state returned by this function shares with the original state
@ -1811,19 +1797,22 @@ When you interact with Lua API,
\emph{you are responsible for controlling stack overflow}. \emph{you are responsible for controlling stack overflow}.
The function The function
\begin{verbatim} \begin{verbatim}
int lua_stackspace (lua_State *L); int lua_checkstack (lua_State *L, int size);
\end{verbatim} \end{verbatim}
\DefAPI{lua_stackspace} \DefAPI{lua_checkstack}
returns the number of stack positions still available. returns true if there is at lease \verb|size|
stack positions still available.
Whenever Lua calls C, \DefAPI{LUA_MINSTACK} Whenever Lua calls C, \DefAPI{LUA_MINSTACK}
it ensures that it ensures that \verb|lua_checkstack(L, LUA_MINSTACK)| is true,
that is, that
at least \verb|LUA_MINSTACK| positions are still available. at least \verb|LUA_MINSTACK| positions are still available.
\verb|LUA_MINSTACK| is defined in \verb|lua.h| and is at least~16, \verb|LUA_MINSTACK| is defined in \verb|lua.h| as 20,
so that usually you do not have to worry about stack space so that usually you do not have to worry about stack space
unless your code has loops pushing elements onto the stack. unless your code has loops pushing elements onto the stack.
Most query functions accept as indices any value inside the Most query functions accept as indices any value inside the
available stack space. available stack space, that is, indices up to the maximum stack size
you (or Lua) have checked through \verb|lua_checkstack|.
Such indices are called \emph{acceptable indices}. Such indices are called \emph{acceptable indices}.
More formally, we define an \IndexEmph{acceptable index} More formally, we define an \IndexEmph{acceptable index}
as follows: as follows:
@ -2178,7 +2167,7 @@ but after the call the responsibility is back to you.
If you need to push other elements after calling any of these functions, If you need to push other elements after calling any of these functions,
and you want to ``play safe'', and you want to ``play safe'',
you must either check the stack space you must either check the stack space
with \verb|lua_stackspace| with \verb|lua_checkstack|
or remove the returned elements or remove the returned elements
from the stack (if you do not need them). from the stack (if you do not need them).
For instance, the following code For instance, the following code
@ -2573,7 +2562,7 @@ information about an active function:
const char *event; /* "call", "return" */ const char *event; /* "call", "return" */
int currentline; /* (l) */ int currentline; /* (l) */
const char *name; /* (n) */ const char *name; /* (n) */
const char *namewhat; /* (n) global, tag method, local, field */ const char *namewhat; /* (n) `global', `local', `field', `method' */
int nups; /* (u) number of upvalues */ int nups; /* (u) number of upvalues */
int linedefined; /* (S) */ int linedefined; /* (S) */
const char *what; /* (S) "Lua" function, "C" function, Lua "main" */ const char *what; /* (S) "Lua" function, "C" function, Lua "main" */
@ -2661,11 +2650,10 @@ then \verb|name| is set to \verb|NULL|.
\item[namewhat] \item[namewhat]
Explains the previous field. Explains the previous field.
If the function is a global variable, It can be \verb|"global"|, \verb|"local"|, \verb|"method"|,
\verb|namewhat| is \verb|"global"|; \verb|"field"|, or \verb|""| (the empty string),
if the function is a tag method, according to how the function was called.
\verb|namewhat| is \verb|"tag-method"|; (Lua uses the empty string when no other option seems to apply.)
otherwise, it is \verb|""| (the empty string).
\item[nups] \item[nups]
Number of upvalues of the function. Number of upvalues of the function.
@ -2974,11 +2962,6 @@ Similar to \verb|dostring|,
but returns the contents of a Lua chunk as a function, but returns the contents of a Lua chunk as a function,
instead of executing it. instead of executing it.
\subsubsection*{\ff \T{newtype (name)}}\DefLIB{newtype}\label{pdf-newtype}
Creates a new type with the given name
(which can be used only for table objects).
Returns the tag of the new type.
\subsubsection*{\ff \T{next (table, [index])}}\DefLIB{next} \subsubsection*{\ff \T{next (table, [index])}}\DefLIB{next}
Allows a program to traverse all fields of a table. Allows a program to traverse all fields of a table.
Its first argument is a table and its second argument Its first argument is a table and its second argument
@ -3027,9 +3010,45 @@ without invoking any tag method.
\verb|index| is any value different from \nil; \verb|index| is any value different from \nil;
and \verb|value| is any Lua value. and \verb|value| is any Lua value.
\subsubsection*{\ff \T{require (module)}}\DefLIB{require} \subsubsection*{\ff \T{require (packagename)}}\DefLIB{require}
Loads the given package.
The function starts by looking into the table \IndexVerb{_LOADED}
whether \verb|packagename| is already loaded.
If it is, then \verb|require| is done.
Otherwise, it searches a path looking for a file to load.
If the global variable \IndexVerb{LUA_PATH} is a string,
this string is the path.
Otherwise, \verb|require| tries the environment variable \verb|LUA_PATH|.
In the last resort, it uses a predefined path.
The path is a sequence of \emph{templates} separated by semicolons.
For each template, \verb|require| will change an eventual interrogation
mark in the template to \verb|packagename|,
and then will try to load the resulting file name.
So, for instance, if the path is
\begin{verbatim}
"./?.lua;./?.lc;/usr/local/?/init.lua;/lasttry"
\end{verbatim}
a \verb|require "mod"| will try to load the files
\verb|./mod.lua|,
\verb|./mod.lc|,
\verb|/usr/local/mod/init.lua|,
and \verb|/lasttry|, in that order.
The function stops the search as soon as it can load a file,
and then it runs the file.
If there is any error loading or running the file,
or if it cannot find any file in the path,
then \verb|require| signals an error.
Otherwise, it marks in table \verb|_LOADED|
that the package is loaded, and returns.
While running a packaged file,
\verb|require| defines the global variable \IndexVerb{_REQUIREDNAME}
with the package name.
TO BE WRITTEN.
\subsubsection*{\ff \T{sort (table [, comp])}}\DefLIB{sort} \subsubsection*{\ff \T{sort (table [, comp])}}\DefLIB{sort}
Sorts table elements in a given order, \emph{in-place}, Sorts table elements in a given order, \emph{in-place},
@ -3241,7 +3260,9 @@ stands for the value of the \M{n}-th captured substring.
If \verb|repl| is a function, then this function is called every time a If \verb|repl| is a function, then this function is called every time a
match occurs, with all captured substrings passed as arguments, match occurs, with all captured substrings passed as arguments,
in order (see below). in order (see below);
if the pattern specifies no captures,
then the whole match is passed as a sole argument.
If the value returned by this function is a string, If the value returned by this function is a string,
then it is used as the replacement string; then it is used as the replacement string;
otherwise, the replacement string is the empty string. otherwise, the replacement string is the empty string.
@ -3273,7 +3294,7 @@ Here are some examples:
--> x="Lua - 4.1" --> x="Lua - 4.1"
local t = {} local t = {}
gsub("first second word", "(%w+)", function (w) tinsert(t, w) end) gsub("first second word", "%w+", function (w) tinsert(t, w) end)
--> t={"first", "second", "word"; n=3} --> t={"first", "second", "word"; n=3}
\end{verbatim} \end{verbatim}
@ -3628,14 +3649,7 @@ The available formats are
this is the only format that returns a number instead of a string. this is the only format that returns a number instead of a string.
\item[``*a''] reads the whole file, starting at the current position. \item[``*a''] reads the whole file, starting at the current position.
On end of file, it returns the empty string. On end of file, it returns the empty string.
\item[``*u\emph{string}''] reads until the first occurence of \item[``*l''] reads the next line (skipping the end of line),
\emph{string} in the file.
The string itself is read, but it is not included in the result.
If \verb|read| cannot finds the string,
it reads (and returns) the file until its end,
or \nil\ if the file was already at its end.
\item[``*l''] equivalent to \verb|"*u\n"|.
Reads the next line (skipping the end of line),
returning \nil\ on end of file. returning \nil\ on end of file.
This is the default format. This is the default format.
\item[\emph{number}] reads a string with up to that number of characters, \item[\emph{number}] reads a string with up to that number of characters,
@ -4033,7 +4047,7 @@ The \verb|lua_pushuserdata| function has been replaced by
\OrNL \rwd{break} \OrNL \rwd{break}
\OrNL \rwd{for} \Nter{Name} \ter{=} exp \ter{,} exp \opt{\ter{,} exp} \OrNL \rwd{for} \Nter{Name} \ter{=} exp \ter{,} exp \opt{\ter{,} exp}
\rwd{do} block \rwd{end} \rwd{do} block \rwd{end}
\OrNL \rwd{for} \Nter{Name} \opt{\ter{,} \Nter{Name}} \rwd{in} exp \OrNL \rwd{for} \Nter{Name} \rep{\ter{,} \Nter{Name}} \rwd{in} explist1
\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} namelist \opt{init} \OrNL \rwd{local} namelist \opt{init}