GitHub/lua
1
0
Fork 0
mirror of https://github.com/lua/lua.git synced 2025-02-04 06:13:04 +08:00
Code Issues Projects Releases Wiki Activity

lhf corrections + new gsub

Browse Source
This commit is contained in:
Roberto Ierusalimschy 1997-06-18 17:14:52 -03:00
parent e931c7c0f6
commit 6b78040840
1 changed files with 254 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

370
manual.tex
View File

@ -1,4 +1,4 @@
% $Id: manual.tex,v 1.30 1997/06/09 18:16:33 roberto Exp roberto $ % $Id: manual.tex,v 2.0 1997/06/17 18:45:16 roberto Exp roberto $
\documentstyle[fullpage,11pt,bnf]{article} \documentstyle[fullpage,11pt,bnf]{article}
@ -31,13 +31,13 @@ Luiz Henrique de Figueiredo\quad
Waldemar Celes Waldemar Celes
\vspace{1.0ex}\\ \vspace{1.0ex}\\
\smallskip \smallskip
\small\tt lua@icad.puc-rio.br \small\tt lua@tecgraf.puc-rio.br
\vspace{2.0ex}\\ \vspace{2.0ex}\\
%MCC 08/95 --- %MCC 08/95 ---
\tecgraf\ --- Departamento de Inform\'atica --- PUC-Rio \tecgraf\ --- Computer Science Department --- PUC-Rio
} }
\date{\small \verb$Date: 1997/06/09 18:16:33 $} \date{\small \verb$Date: 1997/06/17 18:45:16 $}
\maketitle \maketitle
@ -71,8 +71,10 @@ a intera\c{c}\~ao entre programas Lua e programas C hospedeiros.
\begin{quotation} \begin{quotation}
\noindent \noindent
\footnotesize \footnotesize
Copyright (c) 1994--1997 TeCGraf, PUC-Rio. Written by Waldemar Celes Filho, Copyright \copyright\ 1994--1997 TeCGraf, PUC-Rio.
Roberto Ierusalimschy, Luiz Henrique de Figueiredo. All rights reserved. Written by Waldemar Celes Filho,
Roberto Ierusalimschy, Luiz Henrique de Figueiredo.
All rights reserved.
% %
Permission is hereby granted, without written agreement and without license or Permission is hereby granted, without written agreement and without license or
royalty fees, to use, copy, modify, and distribute this software and its royalty fees, to use, copy, modify, and distribute this software and its
@ -81,17 +83,20 @@ documentation for any purpose, subject to the following conditions:
The above copyright notice and this permission notice shall appear in all The above copyright notice and this permission notice shall appear in all
copies or substantial portions of this software. copies or substantial portions of this software.
% %
The name "Lua" cannot be used for any modified form of this software that does The name ``Lua'' cannot be used for any modified form
not originate from the authors. Nevertheless, the name "Lua" may and should be of this software that does not originate from the authors.
Nevertheless, the name ``Lua'' may and should be
used to designate the language implemented and described in this package, used to designate the language implemented and described in this package,
even if embedded in any other system, as long as its syntax and semantics even if embedded in any other system, as long as its syntax and semantics
remain unchanged. remain unchanged.
% %
The authors specifically disclaim any warranties, including, but not limited The authors specifically disclaim any warranties, including,
to, the implied warranties of merchantability and fitness for a particular but not limited to, the implied warranties of merchantability
purpose. The software provided hereunder is on an "as is" basis, and the and fitness for a particular purpose.
The software provided hereunder is on an ``as is'' basis, and the
authors have no obligation to provide maintenance, support, updates, authors have no obligation to provide maintenance, support, updates,
enhancements, or modifications. In no event shall TeCGraf, PUC-Rio, or the enhancements, or modifications.
In no event shall TeCGraf, PUC-Rio, or the
authors be liable to any party for direct, indirect, special, incidental, or authors be liable to any party for direct, indirect, special, incidental, or
consequential damages arising out of the use of this software and its consequential damages arising out of the use of this software and its
documentation. documentation.
@ -110,7 +115,7 @@ documentation.
\section{Introduction} \section{Introduction}
Lua is an extension programming language designed to support Lua is an extension programming language designed to support
general procedural programming features with data description general procedural programming with data description
facilities. facilities.
It is intended to be used as a light-weight, but powerful, It is intended to be used as a light-weight, but powerful,
configuration language for any program that needs one. configuration language for any program that needs one.
@ -127,11 +132,12 @@ This host program can invoke functions to execute a piece of
code in Lua, can write and read Lua variables, code in Lua, can write and read Lua variables,
and can register C functions to be called by Lua code. and can register C functions to be called by Lua code.
Through the use of C functions, Lua can be augmented to cope with Through the use of C functions, Lua can be augmented to cope with
many, completely different domains, a wide range of different domains,
thus creating customized programming languages sharing a syntactical framework. thus creating customized programming languages sharing a syntactical framework.
Lua is free-distribution software, Lua is free-distribution software,
and provided as usual with no guarantees. and provided as usual with no guarantees,
as stated in the copyright notice in the front page of this manual.
The implementation described in this manual is available The implementation described in this manual is available
at the following URL's: at the following URL's:
\begin{verbatim} \begin{verbatim}
@ -155,7 +161,8 @@ using functions in the library that implements Lua.
\Index{Global variables} do not need declaration. \Index{Global variables} do not need declaration.
Any variable is assumed to be global unless explicitly declared local Any variable is assumed to be global unless explicitly declared local
\see{localvar}. \see{localvar}.
Before the first assignment, the value of a global variable is \nil. Before the first assignment, the value of a global variable is \nil;
this default can be changed \see{tag-method}.
The unit of execution of Lua is called a \Def{chunk}. The unit of execution of Lua is called a \Def{chunk}.
The syntax% The syntax%
@ -178,7 +185,8 @@ of new functions%
\footnote{Actually, a function definition is an \footnote{Actually, a function definition is an
assignment to a global variable \see{TypesSec}.}. assignment to a global variable \see{TypesSec}.}.
Chunks may be pre-compiled; see program \IndexVerb{luac} for details. Chunks may be pre-compiled into binary form;
see program \IndexVerb{luac} for details.
Text files with chunks and their binary pre-compiled forms Text files with chunks and their binary pre-compiled forms
are interchangeable. are interchangeable.
Lua automatically detects the file type and acts accordingly. Lua automatically detects the file type and acts accordingly.
@ -196,10 +204,10 @@ There are six \Index{basic types} in Lua: \Def{nil}, \Def{number},
\Def{string}, \Def{function}, \Def{userdata}, and \Def{table}. \Def{string}, \Def{function}, \Def{userdata}, and \Def{table}.
{\em Nil\/} is the type of the value \nil, {\em Nil\/} is the type of the value \nil,
whose main property is to be different from any other value. whose main property is to be different from any other value.
{\em Number\/} represents real (floating point) numbers, {\em Number\/} represents real (floating-point) numbers,
while {\em string\/} has the usual meaning. while {\em string\/} has the usual meaning.
The function \verb|type| returns a string describing the type The function \verb|type| returns a string describing the type
of a given value. of a given value \see{pdf-type}.
Functions are considered first-class values in Lua. Functions are considered first-class values in Lua.
This means that functions can be stored in variables, This means that functions can be stored in variables,
@ -210,7 +218,8 @@ Lua can call (and manipulate) functions written in Lua and
functions written in C. functions written in C.
They can be distinguished by their tags: They can be distinguished by their tags:
all Lua functions have the same tag, all Lua functions have the same tag,
which is different from the tag for all C functions. and all C functions have the same tag,
which is different from the tag of a Lua function.
The type {\em userdata\/} is provided to allow The type {\em userdata\/} is provided to allow
arbitrary \Index{C pointers} to be stored in Lua variables. arbitrary \Index{C pointers} to be stored in Lua variables.
@ -233,7 +242,7 @@ Because functions are first class values,
table fields may contain functions. table fields may contain functions.
The form \verb|t:f(x)| is syntactic sugar for \verb|t.f(t,x)|, 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 which calls the method \verb|f| from the table \verb|t| passing
itself as the first parameter. itself as the first parameter \see{func-def}.
It is important to notice that tables are {\em objects}, and not values. It is important to notice that tables are {\em objects}, and not values.
Variables cannot contain tables, only {\em references\/} to them. Variables cannot contain tables, only {\em references\/} to them.
@ -244,10 +253,10 @@ Moreover, tables must be explicitly created before used
Tags are mainly used to select tag methods when Tags are mainly used to select tag methods when
some events occur \see{tag-method}. some events occur \see{tag-method}.
Each of the types nil, number and string have a different tag. Each of the types nil, number and string has a different tag.
All values of each of these types have this same pre-defined tag. All values of each of these types have this same pre-defined tag.
Values of type function may have two different tags, Values of type function can have two different tags,
depending whether they are Lua or C functions. depending on whether they are Lua or C functions.
Finally, Finally,
values of type userdata and table can have values of type userdata and table can have
as many different tags as needed \see{tag-method}. as many different tags as needed \see{tag-method}.
@ -264,7 +273,7 @@ This section describes the lexis, the syntax and the semantics of Lua.
\subsection{Lexical Conventions} \label{lexical} \subsection{Lexical Conventions} \label{lexical}
Lua is a case sensitive language. Lua is a case-sensitive language.
\Index{Identifiers} can be any string of letters, digits, and underscores, \Index{Identifiers} can be any string of letters, digits, and underscores,
not beginning with a digit. not beginning with a digit.
The following words are reserved, and cannot be used as identifiers: The following words are reserved, and cannot be used as identifiers:
@ -295,8 +304,8 @@ other quoted strings.
\Index{Comments} start anywhere outside a string with a \Index{Comments} start anywhere outside a string with a
double hyphen (\verb|--|) and run until the end of the line. double hyphen (\verb|--|) and run until the end of the line.
Moreover, if the first line of a chunk file starts with \verb|#|, Moreover,
this line is skipped% the first line of a chunk file is skipped if it starts with \verb|#|%
\footnote{This facility allows the use of Lua as a script interpreter \footnote{This facility allows the use of Lua as a script interpreter
in Unix systems \see{lua-sa}.}. in Unix systems \see{lua-sa}.}.
@ -314,10 +323,10 @@ The \verb|$| can be followed by any of the following directives:
\begin{description} \begin{description}
\item[{\tt debug}] --- turn on some debugging facilities \see{pragma}. \item[{\tt debug}] --- turn on some debugging facilities \see{pragma}.
\item[{\tt nodebug}] --- turn off some debugging facilities \see{pragma}. \item[{\tt nodebug}] --- turn off some debugging facilities \see{pragma}.
\item[{\tt if \M{cond}}] --- starts a condicional part. \item[{\tt if \M{cond}}] --- starts a conditional part.
If \M{cond} is false, this part is skiped by the lexical analizer. If \M{cond} is false, then this part is skipped by the lexical analyzer.
\item[{\tt ifnot \M{cond}}] --- starts a condicional part. \item[{\tt ifnot \M{cond}}] --- starts a conditional part.
If \M{cond} is true, this part is skiped by the lexical analizer. If \M{cond} is true, then this part is skipped by the lexical analyzer.
\item[{\tt end}] --- ends a conditional part. \item[{\tt end}] --- ends a conditional part.
\item[{\tt else}] --- starts an ``else'' conditional part, \item[{\tt else}] --- starts an ``else'' conditional part,
switching the ``skip'' status. switching the ``skip'' status.
@ -325,15 +334,16 @@ switching the ``skip'' status.
\end{description} \end{description}
Directives can be freely nested. Directives can be freely nested.
Particularlly, a \verb|$endinput| may ocurr inside a \verb|$if|; Particularly, a \verb|$endinput| may occur inside a \verb|$if|;
in that case, even the matching \verb|$end| is not parsed. in that case, even the matching \verb|$end| is not parsed.
A \M{cond} part may be: A \M{cond} part may be:
\begin{description} \begin{description}
\item[{\tt nil}] --- always false. \item[{\tt nil}] --- always false.
\item[{\tt 1}] --- always true. \item[{\tt 1}] --- always true.
\item[\M{name}] --- true if global variable \M{name} is different from \nil. \item[\M{name}] --- true if the value of the
Notice that this is evaluated before the chunk starts its execution. global variable \M{name} is different from \nil.
Notice that \M{name} is evaluated before the chunk starts its execution.
Therefore, actions in a chunk do not affect its own conditional directives. Therefore, actions in a chunk do not affect its own conditional directives.
\end{description} \end{description}
@ -389,7 +399,8 @@ This restriction also avoids some ``statement not reached'' conditions.
\subsubsection{\Index{Assignment}} \label{assignment} \subsubsection{\Index{Assignment}} \label{assignment}
The language allows \Index{multiple assignment}. The language allows \Index{multiple assignment}.
Therefore, the syntax defines a list of variables on the left side, Therefore, the syntax for assignment
defines a list of variables on the left side,
and a list of expressions on the right side. and a list of expressions on the right side.
Both lists have their elements separated by commas: Both lists have their elements separated by commas:
\begin{Produc} \begin{Produc}
@ -403,6 +414,7 @@ Therefore, it can be used to exchange two values, as in
\begin{verbatim} \begin{verbatim}
x, y = y, x x, y = y, x
\end{verbatim} \end{verbatim}
The two lists may have different lengths.
Before the assignment, the list of values is {\em adjusted\/} to Before the assignment, the list of values is {\em adjusted\/} to
the length of the list of variables \see{adjust}. the length of the list of variables \see{adjust}.
@ -422,10 +434,12 @@ The meaning of assignments and evaluations of global variables and
indexed variables can be changed by tag methods \see{tag-method}. indexed variables can be changed by tag methods \see{tag-method}.
Actually, Actually,
an assignment \verb|x = val|, where \verb|x| is a global variable, an assignment \verb|x = val|, where \verb|x| is a global variable,
is equivalent to a call \verb|setglobal('x', val)|, is equivalent to a call \verb|setglobal('x', val)|;
and an assignment \verb|t[i] = val| is equivalent to an assignment \verb|t[i] = val| is equivalent to
\verb|settable(t, i, val)|. \verb|settable_event(t, i, val)|.
See \See{tag-method} for a description of these ``functions''. See \See{tag-method} for a description of these functions%
\footnote{Function \verb|setglobal| is pre-defined in Lua.
Function {\tt settable\_event} is used only for explanation purposes.}.
The syntax \verb|var.NAME| is just syntactic sugar for The syntax \verb|var.NAME| is just syntactic sugar for
\verb|var["NAME"]|: \verb|var["NAME"]|:
@ -498,27 +512,27 @@ Variables are explained in Section~\ref{assignment}.
An access to a global variable \verb|x| is equivalent to a An access to a global variable \verb|x| is equivalent to a
call \verb|getglobal('x')|; call \verb|getglobal('x')|;
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(t, i)|. a call \verb|gettable_event(t, i)|.
See \See{tag-method} for a description of these ``functions''. See \See{tag-method} for a description of these functions%
\footnote{Function \verb|getglobal| is pre-defined in Lua.
Function {\tt gettable\_event} is used only for explanation purposes.}.
The non-terminal \verb|exp1| is used to indicate that the values The non-terminal \M{exp1} is used to indicate that the values
returned by an expression must be adjusted to one single value: returned by an expression must be adjusted to one single value:
\begin{Produc} \begin{Produc}
\produc{exp1}{exp} \produc{exp1}{exp}
\end{Produc} \end{Produc}
\subsubsection{Arithmetic Operators} \subsubsection{Arithmetic Operators}
Lua supports the usual \Index{arithmetic operators}. Lua supports the usual \Index{arithmetic operators}:
These operators are the binary the binary \verb|+| (addition),
\verb|+| (addition), \verb|-| (subtraction), \verb|*| (multiplication),
\verb|-| (subtraction),
\verb|*| (multiplication),
\verb|/| (division) and \verb|^| (exponentiation), \verb|/| (division) and \verb|^| (exponentiation),
and the unary \verb|-| (negation). and unary \verb|-| (negation).
If the operands are numbers, or strings that can be converted to If the operands are numbers, or strings that can be converted to
numbers, according to the rules given in Section~\ref{coercion}, numbers, according to the rules given in Section~\ref{coercion},
then all operations except exponentiation have the usual meaning. then all operations except exponentiation have the usual meaning.
Otherwise, a tag method is called \see{tag-method}. Otherwise, an appropriate tag method is called \see{tag-method}.
An exponentiation always calls a tag method. An exponentiation always calls a tag method.
The standard mathematical library redefines this method for numbers, The standard mathematical library redefines this method for numbers,
giving the expected meaning to \Index{exponentiation} giving the expected meaning to \Index{exponentiation}
@ -535,7 +549,7 @@ Equality first compares the types of its operands.
If they are different, then the result is \nil. If they are different, then the result is \nil.
Otherwise, their values are compared. Otherwise, their values are compared.
Numbers and strings are compared in the usual way. Numbers and strings are compared in the usual way.
Tables, userdatas and functions are compared by reference, Tables, userdata and functions are compared by reference,
that is, two tables are considered equal only if they are the same table. that is, two tables are considered equal only if they are the same table.
The operator \verb|~=| is exactly the negation of equality (\verb|==|). The operator \verb|~=| is exactly the negation of equality (\verb|==|).
Note that the conversion rules of Section~\ref{coercion} Note that the conversion rules of Section~\ref{coercion}
@ -560,10 +574,10 @@ The \Index{logical operators} are:
and or not and or not
\end{verbatim} \end{verbatim}
The operator \verb|and| returns \nil\ if its first argument is \nil; The operator \verb|and| returns \nil\ if its first argument is \nil;
otherwise it returns its second argument. otherwise, it returns its second argument.
The operator \verb|or| returns its first argument The operator \verb|or| returns its first argument
if it is different from \nil; if it is different from \nil;
otherwise it returns its second argument. otherwise, it returns its second argument.
Both \verb|and| and \verb|or| use \Index{short-cut evaluation}, Both \verb|and| and \verb|or| use \Index{short-cut evaluation},
that is, that is,
the second operand is evaluated only when necessary. the second operand is evaluated only when necessary.
@ -573,7 +587,7 @@ Lua offers a string \Index{concatenation} operator,
denoted by ``\IndexVerb{..}''. denoted by ``\IndexVerb{..}''.
If operands are strings or numbers, then they are converted to If operands are strings or numbers, then they are converted to
strings according to the rules in Section~\ref{coercion}. strings according to the rules in Section~\ref{coercion}.
Otherwise, the tag method ``concat'' is called \see{tag-method}. Otherwise, the ``concat'' tag method is called \see{tag-method}.
\subsubsection{Precedence} \subsubsection{Precedence}
\Index{Operator precedence} follows the table below, \Index{Operator precedence} follows the table below,
@ -615,7 +629,7 @@ For example:
\begin{verbatim} \begin{verbatim}
a = {"v1", "v2", 34} a = {"v1", "v2", 34}
\end{verbatim} \end{verbatim}
is essentialy equivalent to: is essentially equivalent to:
\begin{verbatim} \begin{verbatim}
temp = {} temp = {}
temp[1] = "v1" temp[1] = "v1"
@ -633,7 +647,7 @@ For example:
\begin{verbatim} \begin{verbatim}
a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c}
\end{verbatim} \end{verbatim}
is essentialy equivalent to: is essentially equivalent to:
\begin{verbatim} \begin{verbatim}
temp = {} temp = {}
temp[f(k)] = g(y) temp[f(k)] = g(y)
@ -642,22 +656,19 @@ is essentialy equivalent to:
temp[0] = b+c temp[0] = b+c
a = temp a = temp
\end{verbatim} \end{verbatim}
Notice that an expression like \verb|{x = 1, y = 4}| is An expression like \verb|{x = 1, y = 4}| is
in fact a syntactic sugar for in fact syntactic sugar for \verb|{["x"] = 1, ["y"] = 4}|.
\begin{verbatim}
{["x"] = 1, ["y"] = 4}
\end{verbatim}
\subsubsection{Function Calls} \label{functioncall} \subsubsection{Function Calls} \label{functioncall}
A \Index{function call} has the following syntax: A \Index{function call} has the following syntax:
\begin{Produc} \begin{Produc}
\produc{functioncall}{var realParams} \produc{functioncall}{var realParams}
\end{Produc}% \end{Produc}%
Here, \verb|var| can be any variable (global, local, indexed, etc). Here, \M{var} can be any variable (global, local, indexed, etc).
If its value has type {\em function\/}, If its value has type {\em function\/},
then this function is called. then this function is called.
Otherwise, the ``function'' tag method is called, Otherwise, the ``function'' tag method is called,
having as first parameter the value of \verb|var|, having as first parameter the value of \M{var},
and then the original call parameters. and then the original call parameters.
The form: The form:
@ -686,18 +697,18 @@ Because a function can return any number of results
\see{return}, \see{return},
the number of results must be adjusted before used. the number of results must be adjusted before used.
If the function is called as a statement \see{funcstat}, If the function is called as a statement \see{funcstat},
its return list is adjusted to 0, then its return list is adjusted to~0,
thus discarding all returned values. thus discarding all returned values.
If the function is called in a place that needs a single value If the function is called in a place that needs a single value
(syntactically denoted by the non-terminal \verb|exp1|), (syntactically denoted by the non-terminal \M{exp1}),
then its return list is adjusted to 1, then its return list is adjusted to~1,
thus discarding all returned values but the first one. thus discarding all returned values but the first one.
If the function is called in a place that can hold many values If the function is called in a place that can hold many values
(syntactically denoted by the non-terminal \verb|exp|), (syntactically denoted by the non-terminal \M{exp}),
then no adjustment is made. then no adjustment is made.
\subsection{\Index{Function Definitions}} \subsection{\Index{Function Definitions}} \label{func-def}
Functions in Lua can be defined anywhere in the global level of a chunk. Functions in Lua can be defined anywhere in the global level of a chunk.
The syntax for function definition is: The syntax for function definition is:
@ -731,7 +742,7 @@ instead, it collects any extra arguments in an implicit parameter,
called \Def{arg}. called \Def{arg}.
This parameter is always initialized as a table, This parameter is always initialized as a table,
with a field \verb|n| with the number of extra arguments, with a field \verb|n| with the number of extra arguments,
and the extra arguments at positions 1, 2, \ldots. and the extra arguments at positions 1, 2, \ldots
As an example, suppose definitions like: As an example, suppose definitions like:
\begin{verbatim} \begin{verbatim}
@ -783,14 +794,14 @@ previously initialized with a table value.
Lua provides a powerful mechanism to extend its semantics, Lua provides a powerful mechanism to extend its semantics,
called \Def{Tag Methods}. called \Def{Tag Methods}.
A tag method (TM) is a programmer defined function A tag method (TM) is a programmer-defined function
that can be called in many key points of the evaluation of a program, that can be called at many key points of the evaluation of a program,
allowing a programmer to change the standard Lua behavior at these points. allowing a programmer to change the standard Lua behavior at these points.
Each of these points is called an \Def{event}. Each of these points is called an \Def{event}.
The tag method called for any specific event is selected The tag method called for any specific event is selected
accordingly with the tag~\see{TypesSec} of the values involved according to the tag of the values involved
in the event. in the event \see{TypesSec}.
The function \IndexVerb{settagmethod} changes the tag method The function \IndexVerb{settagmethod} changes the tag method
associated with a given pair $<tag, event>$. associated with a given pair $<tag, event>$.
Its first parameter is the tag, the second the event name Its first parameter is the tag, the second the event name
@ -810,7 +821,7 @@ The function not only shows when a tag method is called,
but also its arguments, its results and the default behavior. but also its arguments, its results and the default behavior.
Please notice that the code shown here is only illustrative; Please notice that the code shown here is only illustrative;
the real behavior is hard coded in the interpreter, the real behavior is hard coded in the interpreter,
and it is much more eficient than this simulation. and it is much more efficient than this simulation.
All functions used in these descriptions All functions used in these descriptions
(\verb|rawgetglobal|, \verb|tonumber|, \verb|call|, etc) (\verb|rawgetglobal|, \verb|tonumber|, \verb|call|, etc)
are described in \See{predefined}. are described in \See{predefined}.
@ -822,10 +833,10 @@ called when a \verb|+| operation is applied to non numerical operands.
The function \verb|getbinmethod| defines how Lua chooses a tag method The function \verb|getbinmethod| defines how Lua chooses a tag method
for a binary operation. for a binary operation.
First Lua trys the first operand. First Lua tries the first operand.
If its tag does not define a tag method for the operation, If its tag does not define a tag method for the operation,
Lua trys the second operand. then Lua tries the second operand.
If it also fails, it gets a tag method from tag 0: If it also fails, then it gets a tag method from tag~0:
\begin{verbatim} \begin{verbatim}
function getbinmethod (op1, op2, event) function getbinmethod (op1, op2, event)
return gettagmethod(tag(op1), event) or return gettagmethod(tag(op1), event) or
@ -853,18 +864,18 @@ If it also fails, it gets a tag method from tag 0:
\item[``sub'':]\index{sub event} \item[``sub'':]\index{sub event}
called when a \verb|-| operation is applied to non numerical operands. called when a \verb|-| operation is applied to non numerical operands.
Behavior is similar to \verb|"add"| event. Behavior similar to \verb|"add"| event.
\item[``mul'':]\index{mul event} \item[``mul'':]\index{mul event}
called when a \verb|*| operation is applied to non numerical operands. called when a \verb|*| operation is applied to non numerical operands.
Behavior is similar to \verb|"add"| event. Behavior similar to \verb|"add"| event.
\item[``div'':]\index{div event} \item[``div'':]\index{div event}
called when a \verb|/| operation is applied to non numerical operands. called when a \verb|/| operation is applied to non numerical operands.
Behavior is similar to \verb|"add"| event. Behavior similar to \verb|"add"| event.
\item[``pow'':]\index{pow event} \item[``pow'':]\index{pow event}
called whenenver a \verb|^| operation is applied. called when a \verb|^| operation is applied.
\begin{verbatim} \begin{verbatim}
function pow_event (op1, op2) function pow_event (op1, op2)
local tm = getbinmethod(op1, op2, "pow") local tm = getbinmethod(op1, op2, "pow")
@ -924,17 +935,17 @@ or non string operands.
\item[``gt'':]\index{gt event} \item[``gt'':]\index{gt event}
called when a \verb|>| operation is applied to non numerical called when a \verb|>| operation is applied to non numerical
or non string operands. or non string operands.
Behavior is similar to \verb|"lt"| event. Behavior similar to \verb|"lt"| event.
\item[``le'':]\index{le event} \item[``le'':]\index{le event}
called when a \verb|<=| operation is applied to non numerical called when a \verb|<=| operation is applied to non numerical
or non string operands. or non string operands.
Behavior is similar to \verb|"lt"| event. Behavior similar to \verb|"lt"| event.
\item[``ge'':]\index{ge event} \item[``ge'':]\index{ge event}
called when a \verb|>=| operation is applied to non numerical called when a \verb|>=| operation is applied to non numerical
or non string operands. or non string operands.
Behavior is similar to \verb|"lt"| event. Behavior similar to \verb|"lt"| event.
\item[``concat'':]\index{concatenation event} \item[``concat'':]\index{concatenation event}
called when a concatenation is applied to non string operands. called when a concatenation is applied to non string operands.
@ -1011,8 +1022,7 @@ called whenever Lua accesses an indexed variable.
\end{verbatim} \end{verbatim}
\item[``settable'':]\index{settable event} \item[``settable'':]\index{settable event}
called whenever Lua assigns to an indexed variable. called when Lua assigns to an indexed variable.
in a table.
\begin{verbatim} \begin{verbatim}
function settable_event (table, index, value) function settable_event (table, index, value)
local tm = gettagmethod(tag(table), "settable") local tm = gettagmethod(tag(table), "settable")
@ -1062,8 +1072,8 @@ Lua does the equivalent of the following function:
end end
end end
\end{verbatim} \end{verbatim}
Moreover, at the end of a garbage collection cicle, Moreover, at the end of a garbage collection cycle,
Lua does the equivalent to the call \verb|gc_event(nil)|. Lua does the equivalent of the call \verb|gc_event(nil)|.
\end{description} \end{description}
@ -1086,14 +1096,15 @@ using the debug facilities \see{debugI},
in order to print some extra information, in order to print some extra information,
like the call stack. like the call stack.
To provide more information about errors, To provide more information about errors,
Lua programs can include the compilation pragma \verb|$debug|. Lua programs should include the compilation pragma \verb|$debug|.
\index{debug pragma}\label{pragma} \index{debug pragma}\label{pragma}
When an error occurs in a program compiled with this option, When an error occurs in a program compiled with this option,
the error routine is able to print the number of the lines where the calls the error routine is able to print the number of the lines where the calls
(and the error) were made. (and the error) were made.
If needed, it is possible to change the error method with the If needed, it is possible to change the error method with the
function \verb|seterrormethod|, function \verb|seterrormethod|,
which gets the new error handler as its only parameter. which gets the new error handler as its only parameter
\see{pdf-seterrormethod}.
Lua code can explicitly generate an error by calling the built-in Lua code can explicitly generate an error by calling the built-in
function \verb|error| \see{pdf-error}. function \verb|error| \see{pdf-error}.
@ -1103,7 +1114,7 @@ function \verb|error| \see{pdf-error}.
This section describes the API for Lua, that is, This section describes the API for Lua, that is,
the set of C functions available to the host program to communicate the set of C functions available to the host program to communicate
with the library. with the Lua library.
The API functions can be classified in the following categories: The API functions can be classified in the following categories:
\begin{enumerate} \begin{enumerate}
\item exchanging values between C and Lua; \item exchanging values between C and Lua;
@ -1123,7 +1134,7 @@ all values passed between Lua and C have type
which works like an abstract type in C that can hold any Lua value. which works like an abstract type in C that can hold any Lua value.
Values of type \verb|lua_Object| have no meaning outside Lua; Values of type \verb|lua_Object| have no meaning outside Lua;
for instance, for instance,
the comparisson of two \verb|lua_Object's| is undefined. the comparison of two \verb|lua_Object's| is undefined.
To check the type of a \verb|lua_Object|, To check the type of a \verb|lua_Object|,
the following functions are available: the following functions are available:
@ -1163,17 +1174,19 @@ char *lua_getstring (lua_Object object);
lua_CFunction lua_getcfunction (lua_Object object); lua_CFunction lua_getcfunction (lua_Object object);
void *lua_getuserdata (lua_Object object); void *lua_getuserdata (lua_Object object);
\end{verbatim} \end{verbatim}
\verb|lua_getnumber| converts a \verb|lua_Object| to a floating-point number. \verb|lua_getnumber| converts a \verb|lua_Object| to a floating-point number.
This \verb|lua_Object| must be a number or a string convertible to number This \verb|lua_Object| must be a number or a string convertible to number
\see{coercion}; otherwise, the function returns 0. \see{coercion}; otherwise, the function returns~0.
\verb|lua_getstring| converts a \verb|lua_Object| to a string (\verb|char*|). \verb|lua_getstring| converts a \verb|lua_Object| to a string (\verb|char*|).
This \verb|lua_Object| must be a string or a number; This \verb|lua_Object| must be a string or a number;
otherwise, the function returns 0 (the \verb|NULL| pointer). otherwise, the function returns~0 (the \verb|NULL| pointer).
This function does not create a new string, This function does not create a new string,
but returns a pointer to a string inside the Lua environment. but returns a pointer to a string inside the Lua environment.
Because Lua has garbage collection, Because Lua has garbage collection,
there is no guarantee that such pointer will be valid after the block ends. there is no guarantee that such pointer will be valid after the block ends
(see below).
\verb|lua_getcfunction| converts a \verb|lua_Object| to a C function. \verb|lua_getcfunction| converts a \verb|lua_Object| to a C function.
This \verb|lua_Object| must have type {\em CFunction\/}; This \verb|lua_Object| must have type {\em CFunction\/};
@ -1193,18 +1206,18 @@ It is good programming practice to convert Lua objects to C values
as soon as they are available, as soon as they are available,
and never to store \verb|lua_Object|s in C global variables. and never to store \verb|lua_Object|s in C global variables.
A garbage collection cicle can be forced by: A garbage collection cycle can be forced by:
\Deffunc{lua_collectgarbage} \Deffunc{lua_collectgarbage}
\begin{verbatim} \begin{verbatim}
long lua_collectgarbage (long limit); long lua_collectgarbage (long limit);
\end{verbatim} \end{verbatim}
This function returns the number of objects collected. This function returns the number of objects collected.
The argument \verb|limit| makes the next cicle occur when that number The argument \verb|limit| makes the next cycle occur only
of new objects have been created. when that number of new objects have been created.
If \verb|limit|=0, Lua uses an adaptative algorithm to set this limit. If \verb|limit|=0, then Lua uses an adaptable heuristics to set this limit.
All comunication between Lua and C is done through two All communication between Lua and C is done through two
abstract data types, called \Def{lua2C} and \Def{C2lua}. abstract data types, called \Def{lua2C} and \Def{C2lua}.
The first one, as the name implies, is used to pass values The first one, as the name implies, is used to pass values
from Lua to C: parameters when Lua calls C and results when C calls Lua. from Lua to C: parameters when Lua calls C and results when C calls Lua.
@ -1227,7 +1240,7 @@ Notice that the structure lua2C cannot be directly modified by C code.
The second structure, C2lua, is a stack. The second structure, C2lua, is a stack.
Pushing elements into this stack Pushing elements into this stack
is done by using the following functions: is done with the following functions:
\Deffunc{lua_pushnumber}\Deffunc{lua_pushstring} \Deffunc{lua_pushnumber}\Deffunc{lua_pushstring}
\Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag} \Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag}
\Deffunc{lua_pushnil}\Deffunc{lua_pushobject} \Deffunc{lua_pushnil}\Deffunc{lua_pushobject}
@ -1263,7 +1276,7 @@ If this function is called with
\verb|tag|=\verb|LUA_ANYTAG|\Deffunc{LUA_ANYTAG}, \verb|tag|=\verb|LUA_ANYTAG|\Deffunc{LUA_ANYTAG},
then Lua will try to find any userdata with the given value, then Lua will try to find any userdata with the given value,
no matter its tag. no matter its tag.
If there is no userdata with that value, a new one is created, If there is no userdata with that value, then a new one is created,
with tag=0. with tag=0.
Userdata can have different tags, Userdata can have different tags,
@ -1283,8 +1296,8 @@ void lua_settag (int tag);
\verb|tag| must be a value created with \verb|lua_newtag|. \verb|tag| must be a value created with \verb|lua_newtag|.
When C code calls Lua repeatedly, as in a loop, When C code calls Lua repeatedly, as in a loop,
objects returned by these calls accumulate, objects returned by these calls can accumulate,
and may create a memory problem. and may cause a stack overflow.
To avoid this, To avoid this,
nested blocks can be defined with the functions: nested blocks can be defined with the functions:
\begin{verbatim} \begin{verbatim}
@ -1297,7 +1310,7 @@ The use of explicit nested blocks is strongly encouraged.
\subsection{Executing Lua Code} \subsection{Executing Lua Code}
A host program can execute Lua chunks written in a file or in a string A host program can execute Lua chunks written in a file or in a string
using the following functions: using the following functions:%
\Deffunc{lua_dofile}\Deffunc{lua_dostring} \Deffunc{lua_dofile}\Deffunc{lua_dostring}
\begin{verbatim} \begin{verbatim}
int lua_dofile (char *filename); int lua_dofile (char *filename);
@ -1325,7 +1338,7 @@ one uses the function:
\begin{verbatim} \begin{verbatim}
lua_Object lua_getglobal (char *varname); lua_Object lua_getglobal (char *varname);
\end{verbatim} \end{verbatim}
As in Lua, this function may call a tag method. As in Lua, this function may trigger a tag method.
To read the real value of any global variable, To read the real value of any global variable,
without invoking any tag method, without invoking any tag method,
this function has a {\em raw\/} version: this function has a {\em raw\/} version:
@ -1336,11 +1349,11 @@ lua_Object lua_rawgetglobal (char *varname);
To store a value previously pushed onto C2lua in a global variable, To store a value previously pushed onto C2lua in a global variable,
there is the function: there is the function:
\Deffunc{lua_storeglobal} \Deffunc{lua_setglobal}
\begin{verbatim} \begin{verbatim}
void lua_setglobal (char *varname); void lua_setglobal (char *varname);
\end{verbatim} \end{verbatim}
As in Lua, this function may call a tag method. As in Lua, this function may trigger a tag method.
To set the real value of any global variable, To set the real value of any global variable,
without invoking any tag method, without invoking any tag method,
this function has a {\em raw\/} version: this function has a {\em raw\/} version:
@ -1357,7 +1370,7 @@ lua_Object lua_gettable (void);
\end{verbatim} \end{verbatim}
pops from the stack C2lua a table and an index, pops from the stack C2lua a table and an index,
and returns the contents of the table at that index. and returns the contents of the table at that index.
As in Lua, this operation may call a tag method. As in Lua, this operation may trigger a tag method.
To get the real value of any table index, To get the real value of any table index,
without invoking any tag method, without invoking any tag method,
this function has a {\em raw\/} version: this function has a {\em raw\/} version:
@ -1458,7 +1471,7 @@ the second is the event name \see{tag-method},
and the third is a CFunction to be used as the new method. and the third is a CFunction to be used as the new method.
This function returns a \verb|lua_Object|, This function returns a \verb|lua_Object|,
which is the old tag method value. which is the old tag method value.
To only get the current value of a tag method, To get just the current value of a tag method,
there is the function there is the function
\Deffunc{lua_gettagmethod} \Deffunc{lua_gettagmethod}
\begin{verbatim} \begin{verbatim}
@ -1471,7 +1484,7 @@ To register a C function to Lua,
there is the following macro: there is the following macro:
\Deffunc{lua_register} \Deffunc{lua_register}
\begin{verbatim} \begin{verbatim}
#define lua_register(n,f) (lua_pushcfunction(f), lua_storeglobal(n)) #define lua_register(n,f) (lua_pushcfunction(f), lua_setglobal(n))
/* char *n; */ /* char *n; */
/* lua_CFunction f; */ /* lua_CFunction f; */
\end{verbatim} \end{verbatim}
@ -1505,7 +1518,7 @@ For some examples, see files \verb|strlib.c|,
As noted in Section~\ref{LuacallC}, \verb|lua_Object|s are volatile. As noted in Section~\ref{LuacallC}, \verb|lua_Object|s are volatile.
If the C code needs to keep a \verb|lua_Object| If the C code needs to keep a \verb|lua_Object|
outside block boundaries, outside block boundaries,
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_getref}
\Deffunc{lua_unref} \Deffunc{lua_unref}
@ -1537,7 +1550,7 @@ The set of \Index{predefined functions} in Lua is small but powerful.
Most of them provide features that allow some degree of Most of them provide features that allow some degree of
\Index{reflexivity} in the language. \Index{reflexivity} in the language.
Some of these features cannot be simulated with the rest of the Some of these features cannot be simulated with the rest of the
Language nor with the standard Lua API. language nor with the standard Lua API.
Others are just convenient interfaces to common API functions. Others are just convenient interfaces to common API functions.
The libraries, on the other hand, provide useful routines The libraries, on the other hand, provide useful routines
@ -1558,7 +1571,7 @@ declared in \verb|lualib.h|.
\subsection{Predefined Functions} \label{predefined} \subsection{Predefined Functions} \label{predefined}
\subsection*{\ff{\tt call (func, arg, [retmode])}}\Deffunc{call} \subsubsection*{\ff {\tt call (func, arg, [retmode])}}\Deffunc{call}
This function calls function \verb|func| with This function calls function \verb|func| with
the arguments given by the table \verb|arg|. the arguments given by the table \verb|arg|.
The call is equivalent to The call is equivalent to
@ -1566,34 +1579,35 @@ The call is equivalent to
func(arg[1], arg[2], ..., arg[arg.n]) func(arg[1], arg[2], ..., arg[arg.n])
\end{verbatim} \end{verbatim}
If \verb|arg.n| is not defined, If \verb|arg.n| is not defined,
Lua gets the arguments from \verb|arg[1]| until the first nil value. then Lua stops getting arguments at the first nil value.
If \verb|retmode| is equal to \verb|"plain"| or is absent, If \verb|retmode| is absent,
all results from \verb|func| are just returned by the call. all results from \verb|func| are just returned by the call.
If \verb|retmode| is equal to \verb|"pack"|, If \verb|retmode| is equal to \verb|"pack"|,
the results are {\em packed\/} in a single table.\index{packed results} the results are {\em packed\/} in a single table.\index{packed results}
That is, \verb|call| returns just one table. That is, \verb|call| returns just one table.
At index \verb|n| the table has the total number of results At index \verb|n|, the table has the total number of results
from the call; from the call;
the first result is at index 1, etc. the first result is at index 1, etc.
For instance, the following calls produce the following results: For instance, the following calls produce the following results:
\begin{verbatim} \begin{verbatim}
a = call(sin, {5}) -- a = 0.0871557 = sin(5) a = call(sin, {5}) --> a = 0.0871557 = sin(5)
a = call(max, {1,4,5; n=2}) -- a = 4 (only 1 and 4 are arguments) a = call(max, {1,4,5; n=2}) --> a = 4 (only 1 and 4 are arguments)
t = {x=1} t = {x=1}
a = call(next, {t,nil;n=2}, "pack") -- a={"x", 1; n=2} a = call(next, {t,nil;n=2}, "pack") --> a={"x", 1; n=2}
\end{verbatim} \end{verbatim}
\subsection*{\ff{\tt callgc ([nextgc])}}\Deffunc{callgc} \subsubsection*{\ff {\tt collectgarbage ([limit])}}\Deffunc{collectgarbage}
Forces a garbage collection cicle. Forces a garbage collection cycle.
Returns the number of objects collected. Returns the number of objects collected.
An optional argument, \verb|nextgc|, is a number that An optional argument, \verb|limit|, is a number that
makes the next cicle occur when that number of new makes the next cycle occur when that number of new
objects have been created. objects have been created.
If absent, Lua uses an adaptative algorithm to set If absent, Lua uses an adaptable algorithm to set
this limit. this limit.
\verb|nextgc| is simply an interface to \verb|lua_collectgarbage|. \verb|collectgarbage| is equivalent to
the API function \verb|lua_collectgarbage|.
\subsubsection*{\ff {\tt dofile (filename)}}\Deffunc{dofile} \subsubsection*{\ff {\tt dofile (filename)}}\Deffunc{dofile}
This function receives a file name, This function receives a file name,
@ -1601,22 +1615,23 @@ opens it, and executes its contents as a Lua chunk,
or as pre-compiled chunks. or as pre-compiled chunks.
When called without arguments, When called without arguments,
it executes the contents of the standard input (\verb|stdin|). it executes the contents of the standard input (\verb|stdin|).
If there is any error executing the file, it returns \nil. If there is any error executing the file,
then \verb|dofile| returns \nil.
Otherwise, it returns the values returned by the chunk, Otherwise, it returns the values returned by the chunk,
or a non \nil\ value if the chunk returns no values. or a non \nil\ value if the chunk returns no values.
It issues an error when called with a non string argument. It issues an error when called with a non string argument.
\verb|dofile| is simply an interface to \verb|lua_dofile|. \verb|dofile| is equivalent to the API function \verb|lua_dofile|.
\subsubsection*{\ff {\tt dostring (string)}}\Deffunc{dostring} \subsubsection*{\ff {\tt dostring (string)}}\Deffunc{dostring}
This function executes a given string as a Lua chunk. This function executes a given string as a Lua chunk.
If there is any error executing the string, it returns \nil. If there is any error executing the string, it returns \nil.
Otherwise, it returns the values returned by the chunk, Otherwise, it returns the values returned by the chunk,
or a non \nil\ value if the chunk returns no values. or a non \nil\ value if the chunk returns no values.
\verb|dostring| is simply an interface to \verb|lua_dostring|. \verb|dostring| is equivalent to the API function \verb|lua_dostring|.
\subsubsection*{\ff {\tt newtag ()}}\Deffunc{newtag}\label{pdf-newtag} \subsubsection*{\ff {\tt newtag ()}}\Deffunc{newtag}\label{pdf-newtag}
Returns a new tag. Returns a new tag.
\verb|newtag| is simply an interface to \verb|lua_newtag|. \verb|newtag| is equivalent to the API function \verb|lua_newtag|.
\subsubsection*{\ff {\tt next (table, index)}}\Deffunc{next} \subsubsection*{\ff {\tt next (table, index)}}\Deffunc{next}
This function allows a program to traverse all fields of a table. This function allows a program to traverse all fields of a table.
@ -1635,7 +1650,7 @@ semantically, there is no difference between a
field not present in a table or a field with value \nil. field not present in a table or a field with value \nil.
Therefore, the function only considers fields with non \nil\ values. Therefore, the function only considers fields with non \nil\ values.
The order in which the indices are enumerated is not specified, The order in which the indices are enumerated is not specified,
{\em even for numeric indices}. {\em not even for numeric indices}.
If the table is modified in any way during a traversal, If the table is modified in any way during a traversal,
the semantics of \verb|next| is undefined. the semantics of \verb|next| is undefined.
@ -1674,7 +1689,7 @@ If the argument is already a number or a string convertible
to a number \see{coercion}, then it returns that number; to a number \see{coercion}, then it returns that number;
otherwise, it returns \nil. otherwise, it returns \nil.
\subsubsection*{\ff{\tt type (v)}}\Deffunc{type} \subsubsection*{\ff {\tt type (v)}}\Deffunc{type}\label{pdf-type}
This function allows Lua to test the type of a value. This function allows Lua to test the type of a value.
It receives one argument, and returns its type, coded as a string. It receives one argument, and returns its type, coded as a string.
The possible results of this function are The possible results of this function are
@ -1684,18 +1699,19 @@ The possible results of this function are
\verb|"table"|, \verb|"table"|,
\verb|"function"|, \verb|"function"|,
and \verb|"userdata"|. and \verb|"userdata"|.
\verb|type| is equivalent to the API function \verb|lua_type|.
\verb|type| is simply an interface to \verb|lua_type|.
\subsubsection*{\ff {\tt tag (v)}}\Deffunc{tag} \subsubsection*{\ff {\tt tag (v)}}\Deffunc{tag}
This function allows Lua to test the tag of a value \see{TypesSec}. This function allows Lua to test the tag of a value \see{TypesSec}.
It receives one argument, and returns its tag (a number). It receives one argument, and returns its tag (a number).
\verb|tag| is equivalent to the API function \verb|lua_tag|.
\subsubsection*{\ff {\tt settag (o, tag)}}\Deffunc{settag} \subsubsection*{\ff {\tt settag (o, tag)}}\Deffunc{settag}
This function sets the tag of a given object \see{TypesSec}. This function sets the tag of a given object \see{TypesSec}.
The object \verb|o| must be a userdata or a table. The object \verb|o| must be a userdata or a table.
\verb|tag| must be a value created with \verb|newtag| \verb|tag| must be a value created with \verb|newtag|
\see{pdf-newtag}. \see{pdf-newtag}.
\verb|settag| is equivalent to the API function \verb|lua_settag|.
\subsubsection*{\ff {\tt assert (v)}}\Deffunc{assert} \subsubsection*{\ff {\tt assert (v)}}\Deffunc{assert}
This function issues an {\em ``assertion failed!''} error This function issues an {\em ``assertion failed!''} error
@ -1706,7 +1722,7 @@ This function issues an error message and terminates
the last called function from the library the last called function from the library
(\verb|lua_dofile|, \verb|lua_dostring|, or \verb|lua_callfunction|). (\verb|lua_dofile|, \verb|lua_dostring|, or \verb|lua_callfunction|).
It never returns. It never returns.
\verb|error| is simply an interface to \verb|lua_error|. \verb|error| is equivalent to the API function \verb|lua_error|.
\subsubsection*{\ff {\tt rawgettable (table, index)}}\Deffunc{rawgettable} \subsubsection*{\ff {\tt rawgettable (table, index)}}\Deffunc{rawgettable}
Gets the real value of \verb|table[index]|, Gets the real value of \verb|table[index]|,
@ -1725,7 +1741,7 @@ and \verb|value| is any Lua value.
This function assigns the given value to a global variable. This function assigns the given value to a global variable.
The string \verb|name| does not need to be a syntactically valid variable name. The string \verb|name| does not need to be a syntactically valid variable name.
Therefore, this function can set global variables with strange names like Therefore, this function can set global variables with strange names like
\verb|`m v 1'| or \verb|34|. \verb|"m v 1"| or \verb|34|.
It returns the value of its second argument. It returns the value of its second argument.
\subsubsection*{\ff {\tt setglobal (name, value)}}\Deffunc{setglobal} \subsubsection*{\ff {\tt setglobal (name, value)}}\Deffunc{setglobal}
@ -1744,10 +1760,11 @@ or calls a tag method.
Its full semantics is explained in \See{tag-method}. Its full semantics is explained in \See{tag-method}.
\subsubsection*{\ff {\tt seterrormethod (newmethod)}} \subsubsection*{\ff {\tt seterrormethod (newmethod)}}
\label{pdf-seterrormethod}
Sets the error handler \see{error}. Sets the error handler \see{error}.
\verb|newmethod| must be a function or \nil, \verb|newmethod| must be a function or \nil,
in which case the error handler does nothing. in which case the error handler does nothing.
Returns the old handler. Returns the old error handler.
\subsubsection*{\ff {\tt settagmethod (tag, event, newmethod)}} \subsubsection*{\ff {\tt settagmethod (tag, event, newmethod)}}
\Deffunc{settagmethod} \Deffunc{settagmethod}
@ -1765,30 +1782,31 @@ for a given pair $<tag, event>$.
\subsection{String Manipulation} \subsection{String Manipulation}
This library provides generic functions for string manipulation, This library provides generic functions for string manipulation,
such as finding and extracting substrings and pattern matching. such as finding and extracting substrings and pattern matching.
When indexing a string, the first character is at position 1, When indexing a string, the first character is at position~1,
not 0, as in C. not~0, as in C.
\subsubsection*{\ff {\tt strfind (str, pattern [, init [, plain]])}} \subsubsection*{\ff {\tt strfind (str, pattern [, init [, plain]])}}
\Deffunc{strfind} \Deffunc{strfind}
This function looks for the first {\em match\/} of This function looks for the first {\em match\/} of
\verb|pattern| in \verb|str|. \verb|pattern| in \verb|str|.
If it finds one, then it returns the indices on \verb|str| If it finds one, then it returns the indices on \verb|str|
where this occurence starts and ends; where this occurrence starts and ends;
otherwise, it returns \nil. otherwise, it returns \nil.
If the pattern specifies captures, If the pattern specifies captures,
the captured strings are returned as extra results. the captured strings are returned as extra results.
A third optional numerical argument specifies where to start the search; A third optional numerical argument specifies where to start the search;
its default value is 1. its default value is 1.
A value of 1 as a forth optional argument A value of 1 as a fourth optional argument
turns off the pattern matching facilities, turns off the pattern matching facilities,
so the function does a plain ``find substring'' operation. so the function does a plain ``find substring'' operation,
with no characters in \verb|pattern| being considered ``magic''.
\subsubsection*{\ff {\tt strlen (s)}}\Deffunc{strlen} \subsubsection*{\ff {\tt strlen (s)}}\Deffunc{strlen}
Receives a string and returns its length. Receives a string and returns its length.
\subsubsection*{\ff {\tt strsub (s, i [, j])}}\Deffunc{strsub} \subsubsection*{\ff {\tt strsub (s, i [, j])}}\Deffunc{strsub}
Returns another string, which is a substring of \verb|s|, Returns another string, which is a substring of \verb|s|,
starting at \verb|i| and runing until \verb|j|. starting at \verb|i| and running until \verb|j|.
If \verb|i| or \verb|j| are negative, If \verb|i| or \verb|j| are negative,
they are replaced by the length of the string minus their they are replaced by the length of the string minus their
absolute value plus 1. absolute value plus 1.
@ -1855,7 +1873,8 @@ the appropriate format string.
For example, \verb|"%*g"| can be simulated with For example, \verb|"%*g"| can be simulated with
\verb|"%"..width.."g"|. \verb|"%"..width.."g"|.
\subsubsection*{\ff{\tt gsub (s, pat, repl [, n])}}\Deffunc{gsub} \subsubsection*{\ff {\tt gsub (s, pat, repl [, table] [, n])}}
\Deffunc{gsub}
Returns a copy of \verb|s|, Returns a copy of \verb|s|,
where all occurrences of the pattern \verb|pat| have been where all occurrences of the pattern \verb|pat| have been
replaced by a replacement string specified by \verb|repl|. replaced by a replacement string specified by \verb|repl|.
@ -1868,38 +1887,53 @@ with \verb|n| between 1 and 9
stands for the value of the n-th captured substring. stands for the value of the 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 as parameters match occurs, with the following arguments:
(see below). If \verb|table| is present, it is the first argument;
then all captured substrings, in order (see below);
finally, the last argument is a match counter
(1 for the first call).
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.
An optional parameter \verb|n| limits A last optional parameter \verb|n| limits
the maximum number of substitutions to occur. the maximum number of substitutions to occur.
For instance, when \verb|n| is 1 only the first occurrence of For instance, when \verb|n| is 1 only the first occurrence of
\verb|pat| is replaced. \verb|pat| is replaced.
As an example, in the following expression each occurrence of the form See some examples below:
\verb|$name| calls the function \verb|getenv|,
passing \verb|name| as argument
(because only this part of the pattern is captured).
The value returned by \verb|getenv| will replace the pattern.
Therefore, the whole expression:
\begin{verbatim} \begin{verbatim}
gsub("home = $HOME, user = $USER", "$(%w%w*)", getenv) x = gsub("hello world", "(%w%w*)", "%1 %1", 1)
\end{verbatim} --> x="hello hello world"
returns a string like:
\begin{verbatim} x = gsub("home = $HOME, user = $USER", "$(%w%w*)", getenv)
home = /home/roberto, user = roberto --> x="home = /home/roberto, user = roberto" (for instance)
x = gsub("4+5 = $return 4+5$", "$(.-)%$", dostring)
--> x="4+5 = 9"
t = {name="lua", version="3.0"}
x = gsub("$name - $version", "$(%w%w*)", rawgettable, t)
--> x="lua - 3.0"
t = {"apple", "orange", "lime"}
x = gsub("x and x and x", "x", rawgettable, t)
--> x="apple and orange and lime"
function f(t,v,i) t[i]=v end
t = {}
gsub("first second word", "(%w%w*)", f, t)
--> t={"first", "second", "word"}
\end{verbatim} \end{verbatim}
\subsubsection*{Patterns} \label{pm} \subsubsection*{Patterns} \label{pm}
\paragraph{Character Class:} \paragraph{Character Class:}
a \Def{character class} is used to represent a set of characters. a \Def{character class} is used to represent a set of characters.
The following combinations are allowed in describing a character class: The following combinations are allowed in describing a character class:
\begin{description} \begin{description}
\item[{\em x}] (where {\em x} is any character not in the list \verb|()%.[*?|) \item[{\em x}] (where {\em x} is any character not in the list \verb|()%.[*-?|)
--- represents the character {\em x} itself. --- represents the character {\em x} itself.
\item[{\tt .}] --- represents all characters. \item[{\tt .}] --- represents all characters.
\item[{\tt \%a}] --- represents all letters. \item[{\tt \%a}] --- represents all letters.
@ -1916,7 +1950,7 @@ The following combinations are allowed in describing a character class:
\item[{\tt \%W}] --- represents all non alphanumeric characters. \item[{\tt \%W}] --- represents all non alphanumeric characters.
\item[{\tt \%\M{x}}] (where \M{x} is any non alphanumeric character) --- \item[{\tt \%\M{x}}] (where \M{x} is any non alphanumeric character) ---
represents the character \M{x}. represents the character \M{x}.
This is the standard way to escape the magic characters \verb|()%.[*?|. This is the standard way to escape the magic characters \verb|()%.[*-?|.
\item[{\tt [char-set]}] --- \item[{\tt [char-set]}] ---
Represents the class which is the union of all Represents the class which is the union of all
characters in char-set. characters in char-set.
@ -1943,12 +1977,12 @@ which matches any single character in the class;
\item \item
a single character class followed by \verb|*|, a single character class followed by \verb|*|,
which matches 0 or more repetitions of characters in the class. which matches 0 or more repetitions of characters in the class.
These repetition itens will always match the longest possible sequence. These repetition items will always match the longest possible sequence.
\item \item
a single character class followed by \verb|-|, a single character class followed by \verb|-|,
which also matches 0 or more repetitions of characters in the class. which also matches 0 or more repetitions of characters in the class.
Unlike \verb|*|, Unlike \verb|*|,
these repetition itens will always match the shortest possible sequence. these repetition items will always match the shortest possible sequence.
\item \item
a single character class followed by \verb|?|, a single character class followed by \verb|?|,
which matches 0 or 1 occurrence of a character in the class; which matches 0 or 1 occurrence of a character in the class;
@ -1958,12 +1992,12 @@ such item matches a sub-string equal to the n-th captured string
(see below); (see below);
\item \item
{\tt \%b\M{xy}}, where \M{x} and \M{y} are two distinct characters; {\tt \%b\M{xy}}, where \M{x} and \M{y} are two distinct characters;
such item mathes strings that start with \M{x}, end with \M{y}, such item matches strings that start with \M{x}, end with \M{y},
and where the \M{x} and \M{y} are {\em balanced}. and where the \M{x} and \M{y} are {\em balanced}.
That means that, if one reads the string from left to write, That means that, if one reads the string from left to write,
counting plus 1 for an \M{x} and minus 1 for a \M{y}, counting plus 1 for an \M{x} and minus 1 for a \M{y},
the ending \M{y} is the first where the count reaches 0. the ending \M{y} is the first where the count reaches 0.
For instance, the item \verb|%()| matches expressions with For instance, the item \verb|%b()| matches expressions with
balanced parentheses. balanced parentheses.
\end{itemize} \end{itemize}
@ -2021,7 +2055,7 @@ range \M{[0,1)}.
\subsection{I/O Facilities} \label{libio} \subsection{I/O Facilities} \label{libio}
All input and outpu operations in Lua are done over two {\em current\/} files: All input and output operations in Lua are done over two {\em current\/} files:
one for reading and one for writing. one for reading and one for writing.
Initially, the current input file is \verb|stdin|, Initially, the current input file is \verb|stdin|,
and the current output file is \verb|stdout|. and the current output file is \verb|stdout|.
@ -2039,7 +2073,7 @@ sets it as the {\em current\/} input file,
and returns a {\em handle\/} to the file and returns a {\em handle\/} to the file
(this handle is a userdata containing the file stream \verb|FILE*|). (this handle is a userdata containing the file stream \verb|FILE*|).
It does not close the current input file. It does not close the current input file.
When called with a file handle, returned by a previous call, When called with a file handle returned by a previous call,
it restores the file as the current input. it restores the file as the current input.
When called without parameters, When called without parameters,
it closes the current input file, it closes the current input file,
@ -2068,8 +2102,8 @@ and returns a {\em handle\/} to the file
(this handle is a user data containing the file stream \verb|FILE*|). (this handle is a user data containing the file stream \verb|FILE*|).
It does not close the current output file. It does not close the current output file.
Notice that, if the file already exists, Notice that, if the file already exists,
it will be {\em completely erased\/} with this operation. then it will be {\em completely erased\/} with this operation.
When called with a file handle, returned by a previous call, When called with a file handle returned by a previous call,
it restores the file as the current output. it restores the file as the current output.
When called without parameters, When called without parameters,
this function closes the current output file, this function closes the current output file,
@ -2119,6 +2153,7 @@ plus a string describing the error.
This function returns a string with a file name that can safely This function returns a string with a file name that can safely
be used for a temporary file. be used for a temporary file.
The file must be explicitly removed when no longer needed.
\subsubsection*{\ff {\tt read ([readpattern])}}\Deffunc{read} \subsubsection*{\ff {\tt read ([readpattern])}}\Deffunc{read}
@ -2301,7 +2336,6 @@ or if the activation record has no debug information,
Formal parameters are the first local variables. Formal parameters are the first local variables.
The function \verb|lua_setlocal| sets the local variable The function \verb|lua_setlocal| sets the local variable
%%LHF: please, lua_setglobal!
\verb|local_number| to the value previously pushed on the stack \verb|local_number| to the value previously pushed on the stack
\see{valuesCLua}. \see{valuesCLua}.
If the function succeeds, then it returns 1. If the function succeeds, then it returns 1.