mirror of
https://github.com/lua/lua
synced 2024-11-30 08:33:16 +03:00
2168 lines
74 KiB
TeX
2168 lines
74 KiB
TeX
% $Id: manual.tex,v 1.18 1996/06/18 20:08:40 roberto Exp roberto $
|
|
|
|
\documentstyle[fullpage,11pt,bnf]{article}
|
|
|
|
\newcommand{\rw}[1]{{\bf #1}}
|
|
\newcommand{\see}[1]{see Section~\ref{#1}}
|
|
\newcommand{\nil}{{\bf nil}}
|
|
\newcommand{\Line}{\rule{\linewidth}{.5mm}}
|
|
\def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}}
|
|
|
|
\newcommand{\Index}[1]{#1\index{#1}}
|
|
\newcommand{\IndexVerb}[1]{{\tt #1}\index{#1}}
|
|
\newcommand{\Def}[1]{{\em #1}\index{#1}}
|
|
\newcommand{\Deffunc}[1]{\index{#1}}
|
|
|
|
\newcommand{\Version}{2.4}
|
|
|
|
\makeindex
|
|
|
|
\begin{document}
|
|
|
|
\title{Reference Manual of the Programming Language Lua \Version}
|
|
|
|
\author{%
|
|
Roberto Ierusalimschy\quad
|
|
Luiz Henrique de Figueiredo\quad
|
|
Waldemar Celes Filho
|
|
\vspace{1.0ex}\\
|
|
%\small \tecgraf \ --- PUC-Rio\\
|
|
\smallskip
|
|
\small\tt lua@icad.puc-rio.br
|
|
\vspace{2.0ex}\\
|
|
%MCC 08/95 ---
|
|
\tecgraf\ --- Departamento de Inform\'atica --- PUC-Rio
|
|
}
|
|
|
|
\date{\small \verb$Date: 1996/06/18 20:08:40 $}
|
|
|
|
\maketitle
|
|
|
|
\begin{abstract}
|
|
\noindent
|
|
Lua is an extension programming language designed to be used
|
|
as a configuration language for any program that needs one.
|
|
This document describes version \Version\ of the Lua programming language and
|
|
the API that allows interaction between Lua programs and their host C programs.
|
|
The document also presents some examples of using the main
|
|
features of the system.
|
|
\end{abstract}
|
|
|
|
\vspace{4ex}
|
|
\begin{quotation}
|
|
\small
|
|
\begin{center}{\bf Sum\'ario}\end{center}
|
|
\vspace{1ex}
|
|
\noindent
|
|
Lua \'e uma linguagem de extens\~ao projetada para ser usada como
|
|
linguagem de configura\c{c}\~ao em qualquer programa que precise de
|
|
uma.
|
|
Este documento descreve a vers\~ao \Version\ da linguagem de
|
|
programa\c{c}\~ao Lua e a Interface de Programa\c{c}\~ao (API) que permite
|
|
a intera\c{c}\~ao entre programas Lua e programas C hospedeiros.
|
|
O documento tamb\'em apresenta alguns exemplos de uso das principais
|
|
ca\-racte\-r\'{\i}sticas do sistema.
|
|
\end{quotation}
|
|
|
|
|
|
\section{Introduction}
|
|
|
|
Lua is an extension programming language designed to support
|
|
general procedural programming features with data description
|
|
facilities.
|
|
It is intended to be used as a configuration language for any
|
|
program that needs one.
|
|
%Its main extensions are related to object-oriented facilities,
|
|
%and fallbacks,
|
|
%but it has some other minor contributions.
|
|
Lua has been designed and implemented by
|
|
W.~Celes~F., L.~H.~de Figueiredo and R.~Ierusalimschy.
|
|
|
|
Lua is implemented as a library, written in C.
|
|
Being an extension language, Lua has no notion of a ``main'' program:
|
|
it only works {\em embedded} in a host client,
|
|
called the {\em embedding} program.
|
|
This host program can invoke functions to execute a piece of
|
|
code in Lua, can write and read Lua variables,
|
|
and can register C functions to be called by Lua code.
|
|
Through the use of C functions, Lua can be augmented to cope with
|
|
rather different domains,
|
|
thus creating customized programming languages sharing a syntactical framework.
|
|
|
|
Lua is free-distribution software,
|
|
and provided as usual with no guarantees.
|
|
The implementation described in this manual is available
|
|
at the following URL's:
|
|
\begin{verbatim}
|
|
http://www.inf.puc-rio.br/~roberto/lua.html
|
|
ftp://ftp.icad.puc-rio.br/pub/lua/lua.tar.gz
|
|
\end{verbatim}
|
|
|
|
|
|
\section{Environment and Chunks}
|
|
|
|
All statements in Lua are executed in a \Def{global environment}.
|
|
This environment, which keeps all global variables and functions,
|
|
is initialized at the beginning of the embedding program and
|
|
persists until its end.
|
|
|
|
The global environment can be manipulated by Lua code or
|
|
by the embedding program,
|
|
which can read and write global variables
|
|
using functions in the library that implements Lua.
|
|
|
|
\Index{Global variables} do not need declaration.
|
|
Any variable is assumed to be global unless explicitly declared local
|
|
(\see{localvar}).
|
|
Before the first assignment, the value of a global variable is \nil.
|
|
|
|
The unit of execution of Lua is called a \Def{chunk}.
|
|
The syntax%
|
|
\footnote{As usual, \rep{{\em a}} means 0 or more {\em a\/}'s,
|
|
\opt{{\em a}} means an optional {\em a} and \oneormore{{\em a}} means
|
|
one or more {\em a\/}'s.}
|
|
for chunks is:
|
|
\begin{Produc}
|
|
\produc{chunk}{\rep{statement \Or function}}
|
|
\end{Produc}%
|
|
A chunk may contain statements and function definitions,
|
|
and may be in a file or in a string inside the host program.
|
|
When a chunk is executed, first all its functions and statements are compiled,
|
|
then the statements are executed in sequential order.
|
|
All modifications a chunk effects on the global environment persist
|
|
after its end.
|
|
Those include modifications to global variables and definitions
|
|
of new functions%
|
|
\footnote{Actually, a function definition is an
|
|
assignment to a global variable; \see{TypesSec}.}.
|
|
|
|
Chunks may be pre-compiled; see program \IndexVerb{luac} for details.
|
|
Text files with chunks and their binary pre-compiled forms
|
|
are interchangeable.
|
|
Lua automatically detects the file type and acts accordingly.
|
|
\index{pre-compilation}
|
|
|
|
\section{\Index{Types}} \label{TypesSec}
|
|
|
|
Lua is a dynamically typed language.
|
|
Variables do not have types; only values do.
|
|
All values carry their own type.
|
|
Therefore, there are no type definitions in the language.
|
|
|
|
There are seven \Index{basic types} in Lua: \Def{nil}, \Def{number},
|
|
\Def{string}, \Def{function}, \Def{CFunction}, \Def{userdata},
|
|
and \Def{table}.
|
|
{\em Nil} is the type of the value \nil,
|
|
whose main property is to be different from any other value.
|
|
{\em Number} represents real (floating point) numbers,
|
|
while {\em string} has the usual meaning.
|
|
|
|
Functions are considered first-class values in Lua.
|
|
This means that functions can be stored in variables,
|
|
passed as arguments to other functions and returned as results.
|
|
When a function is defined in Lua, its body is compiled and stored
|
|
in a given variable.
|
|
Lua can call (and manipulate) functions written in Lua and
|
|
functions written in C; the latter have type {\em CFunction\/}.
|
|
|
|
The type {\em userdata} is provided to allow
|
|
arbitrary \Index{C pointers} to be stored in Lua variables.
|
|
It corresponds to \verb'void*' and has no pre-defined operations in Lua,
|
|
besides assignment and equality test.
|
|
However, by using fallbacks, the programmer may define operations
|
|
for {\em userdata} values; \see{fallback}.
|
|
|
|
The type {\em table} implements \Index{associative arrays},
|
|
that is, \Index{arrays} that can be indexed not only with numbers,
|
|
but with any value (except \nil).
|
|
Therefore, this type may be used not only to represent ordinary arrays,
|
|
but also symbol tables, sets, records, etc.
|
|
To represent \Index{records}, Lua uses the field name as an index.
|
|
The language supports this representation by
|
|
providing \verb'a.name' as syntactic sugar for \verb'a["name"]'.
|
|
Tables may also carry methods.
|
|
Because functions are first class values,
|
|
table fields may contain functions.
|
|
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
|
|
itself as the first parameter.
|
|
|
|
It is important to notice that tables are objects, and not values.
|
|
Variables cannot contain tables, only references to them.
|
|
Assignment, parameter passing and returns always manipulate references
|
|
to tables, and do not imply any kind of copy.
|
|
Moreover, tables must be explicitly created before used
|
|
(\see{tableconstructor}).
|
|
|
|
|
|
|
|
\section{The Language}
|
|
|
|
This section describes the lexis, the syntax and the semantics of Lua.
|
|
|
|
|
|
\subsection{Lexical Conventions} \label{lexical}
|
|
|
|
Lua is a case sensitive language.
|
|
\Index{Identifiers} can be any string of letters, digits, and underscores,
|
|
not beginning with a digit.
|
|
The following words are reserved, and cannot be used as identifiers:
|
|
\index{reserved words}
|
|
\begin{verbatim}
|
|
and do else elseif
|
|
end function if local
|
|
nil not or repeat
|
|
return then until while
|
|
\end{verbatim}
|
|
|
|
The following strings denote other \Index{tokens}:
|
|
\begin{verbatim}
|
|
~= <= >= < > == = .. + - * /
|
|
% ( ) { } [ ] ; , .
|
|
\end{verbatim}
|
|
|
|
\Index{Literal strings} can be delimited by matching single or double quotes,
|
|
and can contain the C-like escape sequences
|
|
\verb-'\n'-, \verb-'\t'- and \verb-'\r'-.
|
|
Literal strings can also be delimited by matching \verb'[[ ... ]]'.
|
|
Literals in this bracketed form may run for several lines,
|
|
may contain nested \verb'[[ ... ]]' pairs,
|
|
and do not interpret escape sequences.
|
|
|
|
\Index{Comments} start anywhere outside a string with a
|
|
double hyphen (\verb'--') and run until the end of the line.
|
|
|
|
\Index{Numerical constants} may be written with an optional decimal part,
|
|
and an optional decimal exponent.
|
|
Examples of valid numerical constants are:
|
|
\begin{verbatim}
|
|
4 4.0 0.4 4.57e-3 0.3e12
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\Index{Coercion}} \label{coercion}
|
|
|
|
Lua provides some automatic conversions.
|
|
Any arithmetic operation applied to a string tries to convert
|
|
that string to a number, following the usual rules.
|
|
Conversely, whenever a number is used when a string is expected,
|
|
that number is converted to a string, according to the following rule:
|
|
if the number is an integer, it is written without exponent or decimal point;
|
|
otherwise, it is formatted following the \verb'%g'
|
|
conversion specification of the \verb'printf' function in the
|
|
standard C library.
|
|
|
|
|
|
|
|
\subsection{\Index{Adjustment}} \label{adjust}
|
|
|
|
Functions in Lua can return many values.
|
|
Because there are no type declarations,
|
|
the system does not know how many values a function will return,
|
|
or how many parameters it needs.
|
|
Therefore, sometimes, a list of values must be {\em adjusted\/}, at run time,
|
|
to a given length.
|
|
If there are more values than are needed, then the last values are thrown away.
|
|
If there are more needs than values, then the list is extended with as
|
|
many \nil's as needed.
|
|
Adjustment occurs in multiple assignment and function calls.
|
|
|
|
|
|
\subsection{Statements}
|
|
|
|
Lua supports an almost conventional set of \Index{statements}.
|
|
The conventional commands include
|
|
assignment, control structures and procedure calls.
|
|
Non-conventional commands include table constructors
|
|
(Section~\ref{tableconstructor}),
|
|
and local variable declarations (Section~\ref{localvar}).
|
|
|
|
\subsubsection{Blocks}
|
|
A \Index{block} is a list of statements, which is executed sequentially.
|
|
Any statement can be optionally followed by a semicolon:
|
|
\begin{Produc}
|
|
\produc{block}{\rep{stat sc} \opt{ret sc}}
|
|
\produc{sc}{\opt{\ter{;}}}
|
|
\end{Produc}%
|
|
For syntactic reasons, a \IndexVerb{return} statement can only be written
|
|
as the last statement of a block.
|
|
This restriction also avoids some ``statement not reached'' errors.
|
|
|
|
\subsubsection{\Index{Assignment}} \label{assignment}
|
|
The language allows \Index{multiple assignment}.
|
|
Therefore, the syntax defines a list of variables on the left side,
|
|
and a list of expressions on the right side.
|
|
Both lists have their elements separated by commas:
|
|
\begin{Produc}
|
|
\produc{stat}{varlist1 \ter{=} explist1}
|
|
\produc{varlist1}{var \rep{\ter{,} var}}
|
|
\end{Produc}%
|
|
This statement first evaluates all values on the right side
|
|
and eventual indices on the left side,
|
|
and then makes the assignments.
|
|
Therefore, it can be used to exchange two values, as in
|
|
\begin{verbatim}
|
|
x, y = y, x
|
|
\end{verbatim}
|
|
Before the assignment, the list of values is {\em adjusted} to
|
|
the length of the list of variables (\see{adjust}).
|
|
|
|
A single name can denote a global or a local variable,
|
|
or a formal parameter:
|
|
\begin{Produc}
|
|
\produc{var}{name}
|
|
\end{Produc}%
|
|
Square brackets are used to index a table:
|
|
\begin{Produc}
|
|
\produc{var}{var \ter{[} exp1 \ter{]}}
|
|
\end{Produc}%
|
|
If \verb'var' results in a table value,
|
|
the field indexed by the expression value gets the assigned value.
|
|
Otherwise, the fallback {\em settable} is called,
|
|
with three parameters: the value of \verb'var',
|
|
the value of expression, and the value being assigned to it;
|
|
\see{fallback}.
|
|
|
|
The syntax \verb'var.NAME' is just syntactic sugar for
|
|
\verb'var["NAME"]'.
|
|
\begin{Produc}
|
|
\produc{var}{var \ter{.} name}
|
|
\end{Produc}%
|
|
|
|
\subsubsection{Control Structures}
|
|
The \Index{condition expression} of a control structure can return any value.
|
|
All values different from \nil\ are considered true;
|
|
\nil\ is considered false.
|
|
{\tt if}'s, {\tt while}'s and {\tt repeat}'s have the usual meaning.
|
|
|
|
\index{while-do}\index{repeat-until}\index{if-then-else}
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{while} exp1 \rwd{do} block \rwd{end} \OrNL
|
|
\rwd{repeat} block \rwd{until} exp1 \OrNL
|
|
\rwd{if} exp1 \rwd{then} block \rep{elseif}
|
|
\opt{\rwd{else} block} \rwd{end}}
|
|
\produc{elseif}{\rwd{elseif} exp1 \rwd{then} block}
|
|
\end{Produc}
|
|
|
|
A {\tt return} is used to return values from a function. \label{return}
|
|
Because a function may return more than one value,
|
|
the syntax for a \Index{return statement} is:
|
|
\begin{Produc}
|
|
\produc{ret}{\rwd{return} explist}
|
|
\end{Produc}
|
|
|
|
\subsubsection{Function Calls as Statements} \label{funcstat}
|
|
Because of possible side-effects,
|
|
function calls can be executed as statements:
|
|
\begin{Produc}
|
|
\produc{stat}{functioncall}
|
|
\end{Produc}%
|
|
Eventual returned values are thrown away.
|
|
Function calls are explained in Section \ref{functioncall}.
|
|
|
|
\subsubsection{Local Declarations} \label{localvar}
|
|
\Index{Local variables} can be declared anywhere inside a block.
|
|
Their scope begins after the declaration and lasts until the
|
|
end of the block.
|
|
The declaration may include an initial assignment:
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{local} declist \opt{init}}
|
|
\produc{declist}{name \rep{\ter{,} name}}
|
|
\produc{init}{\ter{=} explist1}
|
|
\end{Produc}%
|
|
If present, an initial assignment has the same semantics
|
|
of a multiple assignment.
|
|
Otherwise, all variables are initialized with \nil.
|
|
|
|
|
|
\subsection{\Index{Expressions}}
|
|
|
|
\subsubsection{\Index{Simple Expressions}}
|
|
Simple expressions are:
|
|
\begin{Produc}
|
|
\produc{exp}{\ter{(} exp \ter{)}}
|
|
\produc{exp}{\rwd{nil}}
|
|
\produc{exp}{\ter{number}}
|
|
\produc{exp}{\ter{literal}}
|
|
\produc{exp}{var}
|
|
\end{Produc}%
|
|
Numbers (numerical constants) and
|
|
string literals are explained in Section~\ref{lexical}.
|
|
Variables are explained in Section~\ref{assignment}.
|
|
|
|
\subsubsection{Arithmetic Operators}
|
|
Lua supports the usual \Index{arithmetic operators}.
|
|
These operators are the binary
|
|
\verb'+', \verb'-', \verb'*', \verb'/' and \verb'^' (exponentiation),
|
|
and the unary \verb'-'.
|
|
If the operands are numbers, or strings that can be converted to
|
|
numbers, according to the rules given in Section \ref{coercion},
|
|
then all operations but exponentiation have the usual meaning.
|
|
Otherwise, the fallback ``arith'' is called (\see{fallback}).
|
|
An exponentiation always calls this fallback.
|
|
The standard mathematical library redefines this fallback,
|
|
giving the expected meaning to \Index{exponentiation}
|
|
(\see{mathlib}).
|
|
|
|
\subsubsection{Relational Operators}
|
|
Lua provides the following \Index{relational operators}:
|
|
\begin{verbatim}
|
|
< > <= >= ~= ==
|
|
\end{verbatim}
|
|
All these return \nil\ as false and a value different from \nil\
|
|
(actually the number 1) as true.
|
|
|
|
Equality first compares the types of its operands.
|
|
If they are different, then the result is \nil.
|
|
Otherwise, their values are compared.
|
|
Numbers and strings are compared in the usual way.
|
|
Tables, CFunctions, and functions are compared by reference,
|
|
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 other operators work as follows.
|
|
If both arguments are numbers, then they are compared as such.
|
|
Otherwise, if both arguments can be converted to strings,
|
|
their values are compared using lexicographical order.
|
|
Otherwise, the ``order'' fallback is called (\see{fallback}).
|
|
|
|
\subsubsection{Logical Operators}
|
|
Like control structures, all logical operators
|
|
consider \nil\ as false and anything else as true.
|
|
The \Index{logical operators} are:
|
|
\index{and}\index{or}\index{not}
|
|
\begin{verbatim}
|
|
and or not
|
|
\end{verbatim}
|
|
The operators \verb'and' and \verb'or' use \Index{short-cut evaluation},
|
|
that is,
|
|
the second operand is evaluated only if necessary.
|
|
|
|
\subsubsection{Concatenation}
|
|
Lua offers a string \Index{concatenation} operator,
|
|
denoted by ``\IndexVerb{..}''.
|
|
If operands are strings or numbers, then they are converted to
|
|
strings according to the rules in Section \ref{coercion}.
|
|
Otherwise, the fallback ``concat'' is called (\see{fallback}).
|
|
|
|
\subsubsection{Precedence}
|
|
\Index{Operator precedence} follows the table below,
|
|
from the lower to the higher priority:
|
|
\begin{verbatim}
|
|
and or
|
|
< > <= >= ~= ==
|
|
..
|
|
+ -
|
|
* /
|
|
not - (unary)
|
|
^
|
|
\end{verbatim}
|
|
All binary operators are left associative,
|
|
except for \verb'^' (exponentiation),
|
|
which is right associative.
|
|
|
|
\subsubsection{Table Constructors} \label{tableconstructor}
|
|
Table \Index{constructors} are expressions that create tables;
|
|
every time a constructor is evaluated, a new table is created.
|
|
Constructors can be used to create empty tables,
|
|
or to create a table and initialize some fields.
|
|
|
|
The general syntax for constructors is:
|
|
\begin{Produc}
|
|
\produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}}
|
|
\produc{fieldlist}{lfieldlist \Or ffieldlist \Or lfieldlist \ter{;} ffieldlist}
|
|
\produc{lfieldlist}{\opt{lfieldlist1}}
|
|
\produc{ffieldlist}{\opt{ffieldlist1}}
|
|
\end{Produc}
|
|
|
|
The form {\em lfieldlist1} is used to initialize lists.
|
|
\begin{Produc}
|
|
\produc{lfieldlist1}{exp \rep{\ter{,} exp} \opt{\ter{,}}}
|
|
\end{Produc}%
|
|
The expressions in the list are assigned to consecutive numerical indexes,
|
|
starting with 1.
|
|
For example:
|
|
\begin{verbatim}
|
|
a = {"v1", "v2", 34}
|
|
\end{verbatim}
|
|
is equivalent to:
|
|
\begin{verbatim}
|
|
temp = {}
|
|
temp[1] = "v1"
|
|
temp[2] = "v2"
|
|
temp[3] = 34
|
|
a = temp
|
|
\end{verbatim}
|
|
|
|
The next form initializes named fields in a table:
|
|
\begin{Produc}
|
|
\produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}}
|
|
\produc{ffield}{name \ter{=} exp}
|
|
\end{Produc}%
|
|
For example:
|
|
\begin{verbatim}
|
|
a = {x = 1, y = 3}
|
|
\end{verbatim}
|
|
is equivalent to:
|
|
\begin{verbatim}
|
|
temp = {}
|
|
temp.x = 1
|
|
temp.y = 3
|
|
a = temp
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection{Function Calls} \label{functioncall}
|
|
A \Index{function call} has the following syntax:
|
|
\begin{Produc}
|
|
\produc{functioncall}{var realParams}
|
|
\end{Produc}%
|
|
Here, \verb'var' can be any variable (global, local, indexed, etc).
|
|
If its type is {\em function\/} or {\em CFunction\/},
|
|
then this function is called.
|
|
Otherwise, the ``function'' fallback is called,
|
|
having as first parameter the value of \verb'var',
|
|
and then the original call parameters.
|
|
|
|
The form:
|
|
\begin{Produc}
|
|
\produc{functioncall}{var \ter{:} name realParams}
|
|
\end{Produc}%
|
|
can be used to call ``methods''.
|
|
A call \verb'var:name(...)'
|
|
is syntactic sugar for
|
|
\begin{verbatim}
|
|
var.name(var, ...)
|
|
\end{verbatim}
|
|
except that \verb'var' is evaluated only once.
|
|
|
|
\begin{Produc}
|
|
\produc{realParams}{\ter{(} \opt{explist1} \ter{)}}
|
|
\produc{realParams}{tableconstructor}
|
|
\produc{explist1}{exp1 \rep{\ter{,} exp1}}
|
|
\end{Produc}%
|
|
All argument expressions are evaluated before the call;
|
|
then the list of \Index{arguments} is adjusted to
|
|
the length of the list of parameters (\see{adjust});
|
|
finally, this list is assigned to the formal parameters.
|
|
A call of the form \verb'f{...}' is syntactic sugar for
|
|
\verb'f({...})', that is,
|
|
the parameter list is a single new table.
|
|
|
|
Because a function can return any number of results
|
|
(\see{return}),
|
|
the number of results must be adjusted before used.
|
|
If the function is called as a statement (\see{funcstat}),
|
|
its return list is adjusted to 0.
|
|
If the function is called in a place that needs a single value
|
|
(syntactically denoted by the non-terminal \verb'exp1'),
|
|
then its return list is adjusted to 1.
|
|
If the function is called in a place that can hold many values
|
|
(syntactically denoted by the non-terminal \verb'exp'),
|
|
then no adjustment is made.
|
|
|
|
|
|
\subsection{\Index{Function Definitions}}
|
|
|
|
Functions in Lua can be defined anywhere in the global level of a chunk.
|
|
The syntax for function definition is:
|
|
\begin{Produc}
|
|
\produc{function}{\rwd{function} var \ter{(} \opt{parlist1} \ter{)}
|
|
block \rwd{end}}
|
|
\end{Produc}
|
|
|
|
When Lua pre-compiles a chunk,
|
|
all its function bodies are pre-compiled, too.
|
|
Then, when Lua ``executes'' the function definition,
|
|
its body is stored, with type {\em function},
|
|
into the variable \verb'var'.
|
|
|
|
Parameters act as local variables,
|
|
initialized with the argument values.
|
|
\begin{Produc}
|
|
\produc{parlist1}{name \rep{\ter{,} name}}
|
|
\end{Produc}
|
|
|
|
Results are returned using the \verb'return' statement (\see{return}).
|
|
If control reaches the end of a function without a return instruction,
|
|
then the function returns with no results.
|
|
|
|
There is a special syntax for defining \Index{methods},
|
|
that is, functions that have an extra parameter \Def{self}.
|
|
\begin{Produc}
|
|
\produc{function}{\rwd{function} var \ter{:} name \ter{(} \opt{parlist1}
|
|
\ter{)} block \rwd{end}}
|
|
\end{Produc}%
|
|
Thus, a declaration like
|
|
\begin{verbatim}
|
|
function v:f (...)
|
|
...
|
|
end
|
|
\end{verbatim}
|
|
is equivalent to
|
|
\begin{verbatim}
|
|
function v.f (self, ...)
|
|
...
|
|
end
|
|
\end{verbatim}
|
|
that is, the function gets an extra formal parameter called \verb'self'.
|
|
Notice that
|
|
the variable \verb'v' must have been previously initialized with a table value.
|
|
|
|
|
|
\subsection{Fallbacks} \label{fallback}
|
|
|
|
Lua provides a powerful mechanism to extend its semantics,
|
|
called \Def{fallbacks}.
|
|
A fallback is a programmer defined function
|
|
that is called whenever Lua does not know how to proceed.
|
|
|
|
Lua supports the following fallbacks,
|
|
identified by the given strings:
|
|
\begin{description}
|
|
\item[``arith'':]\index{arithmetic fallback}
|
|
called when an arithmetic operation is applied to non numerical operands,
|
|
or when the binary \verb'^' operation is called.
|
|
It receives three arguments:
|
|
the two operands (the second one is nil when the operation is unary minus)
|
|
and one of the following strings describing the offended operator:
|
|
\begin{verbatim}
|
|
add sub mul div pow unm
|
|
\end{verbatim}
|
|
Its return value is the final result of the arithmetic operation.
|
|
The default function issues an error.
|
|
\item[``order'':]\index{order fallback}
|
|
called when an order comparison is applied to non numerical or
|
|
non string operands.
|
|
It receives three arguments:
|
|
the two operands and
|
|
one of the following strings describing the offended operator:
|
|
\begin{verbatim}
|
|
lt gt le ge
|
|
\end{verbatim}
|
|
Its return value is the final result of the comparison operation.
|
|
The default function issues an error.
|
|
\item[``concat'':]\index{concatenation fallback}
|
|
called when a concatenation is applied to non string operands.
|
|
It receives the two operands as arguments.
|
|
Its return value is the final result of the concatenation operation.
|
|
The default function issues an error.
|
|
\item[``index'':]\index{index fallback}
|
|
called when Lua tries to retrieve the value of an index
|
|
not present in a table.
|
|
It receives as arguments the table and the index.
|
|
Its return value is the final result of the indexing operation.
|
|
The default function returns nil.
|
|
\item[``getglobal'':]\index{index getglobal}
|
|
called when Lua tries to retrieve the value of a global variable
|
|
which has a nil value (or which has not been initialized).
|
|
It receives as argument the name of the variable.
|
|
Its return value is the final result of the expression.
|
|
The default function returns nil.
|
|
\item[``gettable'':]\index{gettable fallback}
|
|
called when Lua tries to index a non table value.
|
|
It receives as arguments the non table value and the index.
|
|
Its return value is the final result of the indexing operation.
|
|
The default function issues an error.
|
|
\item[``settable'':]\index{settable fallback}
|
|
called when Lua tries to assign indexed a non table value.
|
|
It receives as arguments the non table value,
|
|
the index, and the assigned value.
|
|
The default function issues an error.
|
|
\item[``function'':]\index{function falback}
|
|
called when Lua tries to call a non function value.
|
|
It receives as arguments the non function value and the
|
|
arguments given in the original call.
|
|
Its return values are the final results of the call operation.
|
|
The default function issues an error.
|
|
\item[``gc'':]
|
|
called during garbage collection.
|
|
It receives as argument the table being collected.
|
|
After each run of the collector this function is called with argument nil.
|
|
Because this function operates during garbage collection,
|
|
it must be used with great care,
|
|
and programmers should avoid the creation of new objects
|
|
(tables or strings) in this function.
|
|
The default function does nothing.
|
|
\item[``error'':]\index{error fallback}
|
|
called when an error occurs.
|
|
It receives as argument a string describing the error.
|
|
The default function prints the message on the standard error output.
|
|
\end{description}
|
|
|
|
The function \IndexVerb{setfallback} is used to change a fallback function.
|
|
Its first argument is the name of a fallback condition,
|
|
and the second argument is the new function to be called.
|
|
It returns the old function for the given fallback.
|
|
|
|
Section \ref{exfallback} shows an example of the use of fallbacks.
|
|
|
|
|
|
\subsection{Error Handling} \label{error}
|
|
|
|
Because Lua is an extension language,
|
|
all Lua actions start from C code calling a function from the Lua library.
|
|
Whenever an error occurs during Lua compilation or execution,
|
|
an ``error'' fallback function is called,
|
|
and then the corresponding function from the library
|
|
(\verb'lua_dofile', \verb'lua_dostring',
|
|
\verb'lua_call', and \verb'lua_callfunction')
|
|
is terminated returning an error condition.
|
|
|
|
The only argument to the ``error'' fallback function is a string
|
|
describing the error.
|
|
The standard I/O library redefines this fallback,
|
|
using the debug facilities (\see{debugI}),
|
|
in order to print some extra information,
|
|
like the call stack.
|
|
For more information about an error,
|
|
the Lua program can include the compilation pragma \verb'$debug'.
|
|
\index{debug pragma}\label{pragma}
|
|
This pragma must be written in a line by itself.
|
|
When an error occurs in a program compiled with this option,
|
|
the error routine is able to print also the lines where the calls
|
|
(and the error) were made.
|
|
If needed, it is possible to change the ``error'' fallback routine
|
|
(\see{fallback}).
|
|
|
|
Lua code can generate an error by calling the built-in
|
|
function \verb'error' (\see{pdf-error}).
|
|
|
|
|
|
\section{The Application Program Interface}
|
|
|
|
This section describes the API for Lua, that is,
|
|
the set of C functions available to the host program to communicate
|
|
with the library.
|
|
The API functions can be classified in the following categories:
|
|
\begin{enumerate}
|
|
\item executing Lua code;
|
|
\item converting values between C and Lua;
|
|
\item manipulating (reading and writing) Lua objects;
|
|
\item calling Lua functions;
|
|
\item C functions to be called by Lua;
|
|
\item references to Lua Objects.
|
|
\end{enumerate}
|
|
All API functions are declared in the header file \verb'lua.h'.
|
|
|
|
\subsection{Executing Lua Code}
|
|
A host program can execute Lua chunks written in a file or in a string,
|
|
using the following functions:
|
|
\Deffunc{lua_dofile}\Deffunc{lua_dostring}
|
|
\begin{verbatim}
|
|
int lua_dofile (char *filename);
|
|
int lua_dostring (char *string);
|
|
\end{verbatim}
|
|
Both functions return an error code:
|
|
0, in case of success; non zero, in case of errors.
|
|
More specifically, \verb'lua_dofile' returns 2 if for any reason
|
|
it could not open the file.
|
|
The function \verb'lua_dofile', if called with argument \verb'NULL' (0),
|
|
executes the {\tt stdin} stream.
|
|
Function \verb'lua_dofile' is also able to execute pre-compiled chunks.
|
|
It automatically detects whether the file is text or binary,
|
|
and loads it accordingly (see program \IndexVerb{luac}).
|
|
|
|
\subsection{Converting Values between C and Lua} \label{valuesCLua}
|
|
Because Lua has no static type system,
|
|
all values passed between Lua and C have type
|
|
\verb'lua_Object'\Deffunc{lua_Object},
|
|
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;
|
|
for instance,
|
|
the comparisson of two \verb"lua_Object's" is of no significance.
|
|
|
|
Because Lua has automatic memory management and garbage collection,
|
|
a \verb'lua_Object' has a limited scope,
|
|
and is only valid inside the {\em block\/} where it was created.
|
|
A C function called from Lua is a block,
|
|
and its parameters are valid only until its end.
|
|
A good programming practice is to convert Lua objects to C values
|
|
as soon as they are available,
|
|
and never to store \verb'lua_Object's in C global variables.
|
|
|
|
When C code calls Lua repeatedly, as in a loop,
|
|
objects returned by these calls accumulate,
|
|
and may create a memory problem.
|
|
To avoid this,
|
|
nested blocks can be defined with the functions:
|
|
\begin{verbatim}
|
|
void lua_beginblock (void);
|
|
void lua_endblock (void);
|
|
\end{verbatim}
|
|
After the end of the block,
|
|
all \verb'lua_Object''s created inside it are released.
|
|
|
|
To check the type of a \verb'lua_Object',
|
|
the following function is available:
|
|
\Deffunc{lua_type}
|
|
\begin{verbatim}
|
|
int lua_type (lua_Object object);
|
|
\end{verbatim}
|
|
plus the following macros and functions:
|
|
\Deffunc{lua_isnil}\Deffunc{lua_isnumber}\Deffunc{lua_isstring}
|
|
\Deffunc{lua_istable}\Deffunc{lua_iscfunction}\Deffunc{lua_isuserdata}
|
|
\Deffunc{lua_isfunction}
|
|
\begin{verbatim}
|
|
int lua_isnil (lua_Object object);
|
|
int lua_isnumber (lua_Object object);
|
|
int lua_isstring (lua_Object object);
|
|
int lua_istable (lua_Object object);
|
|
int lua_isfunction (lua_Object object);
|
|
int lua_iscfunction (lua_Object object);
|
|
int lua_isuserdata (lua_Object object);
|
|
\end{verbatim}
|
|
All macros return 1 if the object is compatible with the given type,
|
|
and 0 otherwise.
|
|
The function \verb'lua_isnumber' accepts numbers and numerical strings,
|
|
\verb'lua_isstring' accepts strings and numbers (\see{coercion}),
|
|
and \verb'lua_isfunction' accepts Lua and C functions.
|
|
The function \verb'lua_type' can be used to distinguish between
|
|
different kinds of user data.
|
|
|
|
To translate a value from type \verb'lua_Object' to a specific C type,
|
|
the programmer can use:
|
|
\Deffunc{lua_getnumber}\Deffunc{lua_getstring}
|
|
\Deffunc{lua_getcfunction}\Deffunc{lua_getuserdata}
|
|
\begin{verbatim}
|
|
double lua_getnumber (lua_Object object);
|
|
char *lua_getstring (lua_Object object);
|
|
lua_CFunction lua_getcfunction (lua_Object object);
|
|
void *lua_getuserdata (lua_Object object);
|
|
\end{verbatim}
|
|
\verb'lua_getnumber' converts a \verb'lua_Object' to a float.
|
|
This \verb'lua_Object' must be a number or a string convertible to number
|
|
(\see{coercion}); otherwise, the function returns 0.
|
|
|
|
\verb'lua_getstring' converts a \verb'lua_Object' to a string (\verb'char *').
|
|
This \verb'lua_Object' must be a string or a number;
|
|
otherwise, the function returns 0 (the null pointer).
|
|
This function does not create a new string, but returns a pointer to
|
|
a string inside the Lua environment.
|
|
Because Lua has garbage collection, there is no guarantee that such
|
|
pointer will be valid after the block ends.
|
|
|
|
\verb'lua_getcfunction' converts a \verb'lua_Object' to a C function.
|
|
This \verb'lua_Object' must have type {\em CFunction\/};
|
|
otherwise, the function returns 0 (the null pointer).
|
|
The type \verb'lua_CFunction' is explained in Section~\ref{LuacallC}.
|
|
|
|
\verb'lua_getuserdata' converts a \verb'lua_Object' to \verb'void*'.
|
|
This \verb'lua_Object' must have type {\em userdata\/};
|
|
otherwise, the function returns 0 (the null pointer).
|
|
|
|
The reverse process, that is, passing a specific C value to Lua,
|
|
is done by using the following functions:
|
|
\Deffunc{lua_pushnumber}\Deffunc{lua_pushstring}
|
|
\Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag}
|
|
\Deffunc{lua_pushuserdata}
|
|
\begin{verbatim}
|
|
void lua_pushnumber (double n);
|
|
void lua_pushstring (char *s);
|
|
void lua_pushcfunction (lua_CFunction f);
|
|
void lua_pushusertag (void *u, int tag);
|
|
\end{verbatim}
|
|
plus the macro:
|
|
\begin{verbatim}
|
|
void lua_pushuserdata (void *u);
|
|
\end{verbatim}
|
|
All of them receive a C value,
|
|
convert it to a corresponding \verb'lua_Object',
|
|
and leave the result on the top of the Lua stack,
|
|
where it can be assigned to a Lua variable,
|
|
passed as parameter to a Lua function, etc. \label{pushing}
|
|
|
|
User data can have different tags,
|
|
whose semantics are defined by the host program.
|
|
Any positive integer can be used to tag a user datum.
|
|
When a user datum is retrieved,
|
|
the function \verb'lua_type' can be used to get its tag.
|
|
|
|
To complete the set,
|
|
the value \nil\ or a \verb'lua_Object' can also be pushed onto the stack,
|
|
with:
|
|
\Deffunc{lua_pushnil}\Deffunc{lua_pushobject}
|
|
\begin{verbatim}
|
|
void lua_pushnil (void);
|
|
void lua_pushobject (lua_Object object);
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Manipulating Lua Objects}
|
|
To read the value of any global Lua variable,
|
|
one uses the function:
|
|
\Deffunc{lua_getglobal}
|
|
\begin{verbatim}
|
|
lua_Object lua_getglobal (char *varname);
|
|
\end{verbatim}
|
|
As in Lua, if the value of the global is \nil,
|
|
then the ``getglobal'' fallback is called.
|
|
|
|
To store a value previously pushed onto the stack in a global variable,
|
|
there is the function:
|
|
\Deffunc{lua_storeglobal}
|
|
\begin{verbatim}
|
|
void lua_storeglobal (char *varname);
|
|
\end{verbatim}
|
|
|
|
Tables can also be manipulated via the API.
|
|
The function
|
|
\Deffunc{lua_getsubscript}
|
|
\begin{verbatim}
|
|
lua_Object lua_getsubscript (void);
|
|
\end{verbatim}
|
|
expects on the stack a table and an index,
|
|
and returns the contents of the table at that index.
|
|
As in Lua, if the first object is not a table,
|
|
or the index is not present in the table,
|
|
the corresponding fallback is called.
|
|
|
|
%For compatibility with previous versions of the API,
|
|
%the following macros are supported:
|
|
%\Deffunc{lua_getindexed}\Deffunc{lua_getfield}
|
|
%\begin{verbatim}
|
|
%lua_Object lua_getindexed (lua_Object table, float index);
|
|
%lua_Object lua_getfield (lua_Object table, char *field);
|
|
%\end{verbatim}
|
|
%The first one is used for numeric indices,
|
|
%while the second can be used for any string index.
|
|
|
|
To store a value in an index,
|
|
the program must push onto the stack the table, the index,
|
|
and the value,
|
|
and then call the function:
|
|
\Deffunc{lua_storesubscript}
|
|
\begin{verbatim}
|
|
void lua_storesubscript (void);
|
|
\end{verbatim}
|
|
Again, the corresponding fallback is called if needed.
|
|
|
|
Finally, the function
|
|
\Deffunc{lua_createtable}
|
|
\begin{verbatim}
|
|
lua_Object lua_createtable (void);
|
|
\end{verbatim}
|
|
creates and returns a new table.
|
|
|
|
{\em Please Notice:\/}
|
|
Most functions from the Lua library receive parameters through Lua's stack.
|
|
Because other functions also use this stack,
|
|
it is important that these
|
|
parameters be pushed just before the corresponding call,
|
|
without intermediate calls to the Lua library.
|
|
For instance, suppose the user wants the value of \verb'a[i]'.
|
|
A simplistic solution would be:
|
|
\begin{verbatim}
|
|
/* Warning: WRONG CODE */
|
|
lua_Object result;
|
|
lua_pushobject(lua_getglobal("a")); /* push table */
|
|
lua_pushobject(lua_getglobal("i")); /* push index */
|
|
result = lua_getsubscript();
|
|
\end{verbatim}
|
|
However, the call \verb'lua_getglobal("i")' modifies the stack,
|
|
and invalidates the previous pushed value.
|
|
A correct solution could be:
|
|
\begin{verbatim}
|
|
lua_Object result;
|
|
lua_Object index = lua_getglobal("i");
|
|
lua_pushobject(lua_getglobal("a")); /* push table */
|
|
lua_pushobject(index); /* push index */
|
|
result = lua_getsubscript();
|
|
\end{verbatim}
|
|
|
|
\subsection{Calling Lua Functions}
|
|
Functions defined in Lua by a chunk executed with
|
|
\verb'dofile' or \verb'dostring' can be called from the host program.
|
|
This is done using the following protocol:
|
|
first, the arguments to the function are pushed onto the Lua stack
|
|
(\see{pushing}), in direct order, i.e., the first argument is pushed first.
|
|
Again, it is important to emphasize that, during this phase,
|
|
no other Lua function can be called.
|
|
|
|
Then, the function is called using
|
|
\Deffunc{lua_call}\Deffunc{lua_callfunction}
|
|
\begin{verbatim}
|
|
int lua_call (char *functionname);
|
|
\end{verbatim}
|
|
or
|
|
\begin{verbatim}
|
|
int lua_callfunction (lua_Object function);
|
|
\end{verbatim}
|
|
Both functions return an error code:
|
|
0, in case of success; non zero, in case of errors.
|
|
Finally, the returned values (a Lua function may return many values)
|
|
can be retrieved with the macro
|
|
\Deffunc{lua_getresult}
|
|
\begin{verbatim}
|
|
lua_Object lua_getresult (int number);
|
|
\end{verbatim}
|
|
where \verb'number' is the order of the result, starting with 1.
|
|
When called with a number larger than the actual number of results,
|
|
this function returns \verb'LUA_NOOBJECT'.
|
|
|
|
Two special Lua functions have exclusive interfaces:
|
|
\verb'error' and \verb'setfallback'.
|
|
A C function can generate a Lua error calling the function
|
|
\Deffunc{lua_error}
|
|
\begin{verbatim}
|
|
void lua_error (char *message);
|
|
\end{verbatim}
|
|
This function never returns.
|
|
If the C function has been called from Lua,
|
|
the corresponding Lua execution terminates,
|
|
as if an error had occurred inside Lua code.
|
|
Otherwise, the whole program terminates.
|
|
|
|
Fallbacks can be changed with:
|
|
\Deffunc{lua_setfallback}
|
|
\begin{verbatim}
|
|
lua_Object lua_setfallback (char *name, lua_CFunction fallback);
|
|
\end{verbatim}
|
|
The first parameter is the fallback name,
|
|
and the second a CFunction to be used as the new fallback.
|
|
This function returns a \verb'lua_Object',
|
|
which is the old fallback value,
|
|
or \nil\ on fail (invalid fallback name).
|
|
This old value can be used for chaining fallbacks.
|
|
|
|
An example of C code calling a Lua function is shown in
|
|
Section~\ref{exLuacall}.
|
|
|
|
|
|
\subsection{C Functions} \label{LuacallC}
|
|
To register a C function to Lua,
|
|
there is the following macro:
|
|
\Deffunc{lua_register}
|
|
\begin{verbatim}
|
|
#define lua_register(n,f) (lua_pushcfunction(f), lua_storeglobal(n))
|
|
/* char *n; */
|
|
/* lua_CFunction f; */
|
|
\end{verbatim}
|
|
which receives the name the function will have in Lua,
|
|
and a pointer to the function.
|
|
This pointer must have type \verb'lua_CFunction',
|
|
which is defined as
|
|
\Deffunc{lua_CFunction}
|
|
\begin{verbatim}
|
|
typedef void (*lua_CFunction) (void);
|
|
\end{verbatim}
|
|
that is, a pointer to a function with no parameters and no results.
|
|
|
|
In order to communicate properly with Lua,
|
|
a C function must follow a protocol,
|
|
which defines the way parameters and results are passed.
|
|
|
|
To access its arguments, a C function calls:
|
|
\Deffunc{lua_getparam}
|
|
\begin{verbatim}
|
|
lua_Object lua_getparam (int number);
|
|
\end{verbatim}
|
|
where \verb'number' starts with 1 to get the first argument.
|
|
When called with a number larger than the actual number of arguments,
|
|
this function returns
|
|
\verb'LUA_NOOBJECT'\Deffunc{LUA_NOOBJECT}.
|
|
In this way, it is possible to write functions that work with
|
|
a variable number of parameters.
|
|
|
|
To return values, a C function just pushes them onto the stack,
|
|
in direct order (\see{valuesCLua}).
|
|
Like a Lua function, a C function called by Lua can also return
|
|
many results.
|
|
|
|
Section~\ref{exCFunction} presents an example of a CFunction.
|
|
|
|
|
|
\subsection{References to Lua Objects}
|
|
|
|
As noted in Section~\ref{LuacallC}, \verb'lua_Object's are volatile.
|
|
If the C code needs to keep a \verb'lua_Object'
|
|
outside block boundaries,
|
|
it must create a \Def{reference} to the object.
|
|
The routines to manipulate references are the following:
|
|
\Deffunc{lua_ref}\Deffunc{lua_getref}
|
|
\Deffunc{lua_pushref}\Deffunc{lua_unref}
|
|
\begin{verbatim}
|
|
int lua_ref (int lock);
|
|
lua_Object lua_getref (int ref);
|
|
void lua_pushref (int ref);
|
|
void lua_unref (int ref);
|
|
\end{verbatim}
|
|
The function \verb'lua_ref' creates a reference
|
|
to the object that is on the top of the stack,
|
|
and returns this reference.
|
|
If \verb'lock' is true, the object is {\em locked}:
|
|
that means the object will not be garbage collected.
|
|
Notice that an unlocked reference may be garbage collected.
|
|
Whenever the referenced object is needed,
|
|
a call to \verb'lua_getref'
|
|
returns a handle to it,
|
|
whereas \verb'lua_pushref' pushes the object on the stack.
|
|
If the object has been collected,
|
|
then \verb'lua_getref' returns \verb'LUA_NOOBJECT',
|
|
and \verb'lua_pushobject' issues an error.
|
|
|
|
When a reference is no longer needed,
|
|
it can be freed with a call to \verb'lua_unref'.
|
|
|
|
|
|
|
|
\section{Predefined Functions and Libraries}
|
|
|
|
The set of \Index{predefined functions} in Lua is small but powerful.
|
|
Most of them provide features that allows some degree of
|
|
\Index{reflexivity} in the language.
|
|
Some of these features cannot be simulated with the rest of the
|
|
Language nor with the standard Lua API.
|
|
Others are just convenient interfaces to common API functions.
|
|
|
|
The libraries, on the other hand, provide useful routines
|
|
that are implemented directly through the standard API.
|
|
Therefore, they are not necessary to the language,
|
|
and are provided as separated C modules.
|
|
Currently there are three standard libraries:
|
|
\begin{itemize}
|
|
\item string manipulation;
|
|
\item mathematical functions (sin, cos, etc);
|
|
\item input and output (plus some system facilities).
|
|
\end{itemize}
|
|
In order to have access to these libraries,
|
|
the host program must call the functions
|
|
\verb-strlib_open-, \verb-mathlib_open-, and \verb-iolib_open-,
|
|
declared in \verb-lualib.h-.
|
|
|
|
|
|
\subsection{Predefined Functions}
|
|
|
|
\subsubsection*{{\tt dofile (filename)}}\Deffunc{dofile}
|
|
This function receives a file name,
|
|
opens it, and executes its contents as a Lua chunk,
|
|
or as pre-compiled chunks.
|
|
When called without arguments,
|
|
it executes the contents of the standard input (\verb'stdin').
|
|
It returns 1 if there are no errors, \nil\ otherwise.
|
|
It issues an error when called with a non string argument.
|
|
|
|
\subsubsection*{{\tt dostring (string)}}\Deffunc{dostring}
|
|
This function executes a given string as a Lua chunk.
|
|
It returns 1 if there are no errors, \nil\ otherwise.
|
|
|
|
\subsubsection*{{\tt next (table, index)}}\Deffunc{next}
|
|
This function allows a program to traverse all fields of a table.
|
|
Its first argument is a table and its second argument
|
|
is an index in this table.
|
|
It returns the next index of the table and the
|
|
value associated with the index.
|
|
When called with \nil\ as its second argument,
|
|
the function returns the first index
|
|
of the table (and its associated value).
|
|
When called with the last index, or with \nil\ in an empty table,
|
|
it returns \nil.
|
|
|
|
In Lua there is no declaration of fields;
|
|
semantically, there is no difference between a
|
|
field not present in a table or a field with value \nil.
|
|
Therefore, the function only considers fields with non nil values.
|
|
The order the indices are enumerated is not specified,
|
|
{\em even for numeric indices}.
|
|
|
|
See Section \ref{exnext} for an example of the use of this function.
|
|
|
|
\subsubsection*{{\tt nextvar (name)}}\Deffunc{nextvar}
|
|
This function is similar to the function \verb'next',
|
|
but iterates over the global variables.
|
|
Its single argument is the name of a global variable,
|
|
or \nil\ to get a first name.
|
|
Similarly to \verb'next', it returns the name of another variable
|
|
and its value,
|
|
or \nil\ if there are no more variables.
|
|
See Section \ref{exnext} for an example of the use of this function.
|
|
|
|
\subsubsection*{{\tt tostring (e)}}\Deffunc{tostring}
|
|
This function receives an argument of any type and
|
|
converts it to a string in a reasonable format.
|
|
|
|
\subsubsection*{{\tt print (e1, e2, ...)}}\Deffunc{print}
|
|
This function receives any number of arguments,
|
|
and prints their values in a reasonable format.
|
|
Each value is printed in a new line.
|
|
This function is not intended for formatted output,
|
|
but as a quick way to show a value,
|
|
for instance for error messages or debugging.
|
|
See Section~\ref{libio} for functions for formatted output.
|
|
|
|
\subsubsection*{{\tt tonumber (e)}}\Deffunc{tonumber}
|
|
This function receives one argument,
|
|
and tries to convert it to a number.
|
|
If the argument is already a number or a string convertible
|
|
to a number (\see{coercion}), then it returns that number;
|
|
otherwise, it returns \nil.
|
|
|
|
\subsubsection*{{\tt type (v)}}\Deffunc{type}
|
|
This function allows Lua to test the type of a value.
|
|
It receives one argument, and returns its type, coded as a string.
|
|
The possible results of this function are
|
|
\verb'"nil"' (a string, not the value \nil),
|
|
\verb'"number"',
|
|
\verb'"string"',
|
|
\verb'"table"',
|
|
\verb'"function"' (returned both for C functions and Lua functions),
|
|
and \verb'"userdata"'.
|
|
|
|
Besides this string, the function returns a second result,
|
|
which is the \Def{tag} of the value.
|
|
This tag can be used to distinguish between user
|
|
data with different tags,
|
|
and between C functions and Lua functions.
|
|
|
|
\subsubsection*{{\tt assert (v)}}\Deffunc{assert}
|
|
This function issues an {\em ``assertion failed!''} error
|
|
when its argument is \nil.
|
|
|
|
\subsubsection*{{\tt error (message)}}\Deffunc{error}\label{pdf-error}
|
|
This function issues an error message and terminates
|
|
the last called function from the library
|
|
(\verb'lua_dofile', \verb'lua_dostring', \ldots).
|
|
It never returns.
|
|
|
|
\subsubsection*{{\tt setglobal (name, value)}}\Deffunc{setglobal}
|
|
This function assigns the given value to a global variable.
|
|
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
|
|
\verb'm v 1' or \verb'34'.
|
|
It returns the value of its second argument.
|
|
|
|
\subsubsection*{{\tt getglobal (name)}}\Deffunc{getglobal}
|
|
This function retrieves the value of a global variable.
|
|
The string \verb'name' does not need to be a syntactically valid variable name.
|
|
|
|
\subsubsection*{{\tt setfallback (fallbackname, newfallback)}}
|
|
\Deffunc{setfallback}
|
|
This function sets a new fallback function to the given fallback.
|
|
It returns the old fallback function.
|
|
|
|
\subsection{String Manipulation}
|
|
This library provides generic functions for string manipulation,
|
|
such as finding and extracting substrings.
|
|
When indexing a string, the first character has position 1.
|
|
See Section \ref{exstring} for some examples on string manipulation
|
|
in Lua.
|
|
|
|
\subsubsection*{{\tt strfind (str, substr, [init, [end]])}}
|
|
\Deffunc{strfind}
|
|
Receives two string arguments,
|
|
and returns a number.
|
|
This number indicates the first position where the second argument appears
|
|
in the first argument.
|
|
If the second argument is not a substring of the first one,
|
|
then \verb'strfind' returns \nil.
|
|
A third optional numerical argument specifies where to start the search.
|
|
Another optional numerical argument specifies where to stop it.
|
|
|
|
\subsubsection*{{\tt strlen (s)}}\Deffunc{strlen}
|
|
Receives a string and returns its length.
|
|
|
|
\subsubsection*{{\tt strsub (s, i, [j])}}\Deffunc{strsub}
|
|
Returns another string, which is a substring of \verb's',
|
|
starting at \verb'i' and runing until \verb'j'.
|
|
If \verb'j' is absent,
|
|
it is assumed to be equal to the length of \verb's'.
|
|
In particular, the call \verb'strsub(s,1,j)' returns a prefix of \verb's'
|
|
with length \verb'j',
|
|
whereas the call \verb'strsub(s,i)' returns a suffix of \verb's',
|
|
starting at \verb'i'.
|
|
|
|
\subsubsection*{{\tt strlower (s)}}\Deffunc{strlower}
|
|
Receives a string and returns a copy of that string with all
|
|
upper case letters changed to lower case.
|
|
All other characters are left unchanged.
|
|
|
|
\subsubsection*{{\tt strupper (s)}}\Deffunc{strupper}
|
|
Receives a string and returns a copy of that string with all
|
|
lower case letters changed to upper case.
|
|
All other characters are left unchanged.
|
|
|
|
\subsubsection*{{\tt ascii (s, [i])}}\Deffunc{ascii}
|
|
Returns the ascii code of the character \verb's[i]'.
|
|
If \verb'i' is absent, then it is assumed to be 1.
|
|
|
|
\subsubsection*{{\tt format (formatstring, e1, e2, \ldots)}}\Deffunc{format}
|
|
\label{format}
|
|
This function returns a formated version of its variable number of arguments
|
|
following the description given in its first argument (which must be a string).
|
|
The format string follows the same rules as the \verb'printf' family of
|
|
standard C functions.
|
|
The only differences are that the options/modifiers
|
|
\verb'*', \verb'l', \verb'L', \verb'n', \verb'p',
|
|
and \verb'h' are not supported,
|
|
and there is an extra option, \verb'q'.
|
|
This option formats a string in a form suitable to be safely read
|
|
back by the Lua interpreter.
|
|
The string is written between double quotes,
|
|
and all double quotes, returns and backslashes in the string
|
|
are correctly escaped when written.
|
|
|
|
The options \verb'c', \verb'd', \verb'E', \verb'e', \verb'f',
|
|
\verb'g' \verb'i', \verb'o', \verb'u', \verb'X', and \verb'x' all
|
|
expect a number argument,
|
|
whereas \verb'q' and \verb's' expect a string.
|
|
|
|
|
|
\subsection{Mathematical Functions} \label{mathlib}
|
|
|
|
This library is an interface to some functions of the standard C math library.
|
|
Moreover, it registers a fallback for the binary operator \verb'^' which,
|
|
when applied to numbers \verb'x^y', returns $x^y$.
|
|
|
|
The library provides the following functions:
|
|
\Deffunc{abs}\Deffunc{acos}\Deffunc{asin}\Deffunc{atan}
|
|
\Deffunc{atan2}\Deffunc{ceil}\Deffunc{cos}\Deffunc{floor}
|
|
\Deffunc{log}\Deffunc{log10}\Deffunc{max}\Deffunc{min}
|
|
\Deffunc{mod}\Deffunc{sin}\Deffunc{sqrt}\Deffunc{tan}
|
|
\Deffunc{random}\Deffunc{randomseed}
|
|
\begin{verbatim}
|
|
abs acos asin atan atan2 ceil cos floor log log10
|
|
max min mod sin sqrt tan random randomseed
|
|
\end{verbatim}
|
|
Most of them
|
|
are only interfaces to the homonymous functions in the C library,
|
|
except that, for the trigonometric functions,
|
|
all angles are expressed in degrees, not radians.
|
|
|
|
The function \verb'max' returns the maximum
|
|
value of its numeric arguments.
|
|
Similarly, \verb'min' computes the minimum.
|
|
Both can be used with an unlimited number of arguments.
|
|
|
|
The function \verb'mod' is equivalent to the \verb'%' operator in C.
|
|
|
|
The functions \verb'random' and \verb'randomseed' are interfaces to
|
|
the simple random generator functions \verb'rand' and \verb'srand',
|
|
provided by ANSI C.
|
|
The function \verb'random' returns pseudo-random numbers in the range
|
|
$[0,1)$.
|
|
|
|
|
|
\subsection{I/O Facilities} \label{libio}
|
|
|
|
All I/O operations in Lua are done over two {\em current} files:
|
|
one for reading and one for writing.
|
|
Initially, the current input file is \verb'stdin',
|
|
and the current output file is \verb'stdout'.
|
|
|
|
Unless otherwise stated,
|
|
all I/O functions return 1 on success and \nil\ on failure.
|
|
|
|
\subsubsection*{{\tt readfrom (filename)}}\Deffunc{readfrom}
|
|
|
|
This function opens a file named \verb'filename' and sets it as the
|
|
{\em current} input file.
|
|
When called without parameters,
|
|
this function closes the current input file,
|
|
and restores \verb'stdin' as the current input file.
|
|
|
|
{\em System dependent:} if \verb'filename' starts with a \verb'|',
|
|
then a \Index{piped input} is open, via function \IndexVerb{popen}.
|
|
|
|
\subsubsection*{{\tt writeto (filename)}}\Deffunc{writeto}
|
|
|
|
This function opens a file named \verb'filename' and sets it as the
|
|
{\em current} output file.
|
|
Notice that, if the file already exists,
|
|
it will be {\em completely erased} with this operation.
|
|
When called without parameters,
|
|
this function closes the current output file,
|
|
and restores \verb'stdout' as the current output file.
|
|
\index{closing a file}
|
|
|
|
{\em System dependent:} if \verb'filename' starts with a \verb'|',
|
|
then a \Index{piped output} is open, via function \IndexVerb{popen}.
|
|
|
|
\subsubsection*{{\tt appendto (filename)}}\Deffunc{appendto}
|
|
|
|
This function opens a file named \verb'filename' and sets it as the
|
|
{\em current} output file.
|
|
Unlike the \verb'writeto' operation,
|
|
this function does not erase any previous content of the file.
|
|
|
|
\subsubsection*{{\tt remove (filename)}}\Deffunc{remove}
|
|
|
|
This function deletes the file with the given name.
|
|
|
|
\subsubsection*{{\tt rename (name1, name2)}}\Deffunc{rename}
|
|
|
|
This function renames file \verb'name1' to \verb'name2'.
|
|
|
|
\subsubsection*{{\tt tmpname ()}}\Deffunc{tmpname}
|
|
|
|
This function returns a string with a file name that can safely
|
|
be used for a temporary file.
|
|
|
|
\subsubsection*{{\tt read ([format])}}\Deffunc{read}
|
|
|
|
This function returns a value read from the current input.
|
|
An optional string argument specifies the way the input is interpreted.
|
|
|
|
Without a format argument, {\tt read} first skips blanks, tabs and newlines.
|
|
Then it checks whether the current character is \verb'"' or \verb-'-.
|
|
If so, it reads a string up to the ending quotation mark,
|
|
and returns this string, without the quotation marks.
|
|
Otherwise it reads up to a blank, tab or newline.
|
|
|
|
The format string can have the following format:
|
|
\begin{verbatim}
|
|
?[n]
|
|
\end{verbatim}
|
|
where \verb'?' can be:
|
|
\begin{description}
|
|
\item['s' or 'S'] to read a string;
|
|
\item['f' or 'F'] to read a real number;
|
|
\item['i' or 'I'] to read an integer.
|
|
\end{description}
|
|
The optional \verb'n' is a number which specifies how many characters
|
|
must be read to compose the input value.
|
|
Particularly, the format \verb'"s1"' reads a single character.
|
|
|
|
\subsubsection*{{\tt readuntil (char)}}\Deffunc{readuntil}
|
|
|
|
Reads the current input until the first ocurrence of the given character.
|
|
When called with no parameters,
|
|
reads until the end of the current input file.
|
|
Returns the string read.
|
|
The character itself is not read.
|
|
|
|
\subsubsection*{{\tt write (value, [format])}}\Deffunc{write}
|
|
|
|
This function writes the value of its first argument to the current output.
|
|
An optional second argument specifies the format to be used.
|
|
This format is given as a string, composed of four parts.
|
|
The first part is the only one not optional, and must be one of the
|
|
following characters:
|
|
\begin{description}
|
|
\item['s' or 'S'] to write strings;
|
|
\item['f' or 'F'] to write floats;
|
|
\item['i' or 'I'] to write integers;
|
|
\item['q' or 'Q'] to write quoted strings.
|
|
This format writes the string in a form suitable to be safely read
|
|
back by the Lua interpreter.
|
|
The string is written between double quotes,
|
|
and all double quotes, returns and backslashes in the string
|
|
are correctly escaped when written.
|
|
\end{description}
|
|
These characters can be followed by
|
|
\begin{verbatim}
|
|
[?][m][.n]
|
|
\end{verbatim}
|
|
where:
|
|
\begin{description}
|
|
\item[\verb'?'] indicates justification inside the field.
|
|
\begin{itemize}
|
|
\item['\verb'<''] right justification (default);
|
|
\item['\verb'>''] left justification;
|
|
\item['\verb'|''] center justification.
|
|
\end{itemize}
|
|
\item[\verb'm'] Indicates the field size in characters.
|
|
\item[\verb'.n'] For reals, indicates the number of digital places.
|
|
For integers, it is the minimum number of digits.
|
|
This option has no meaning for strings.
|
|
\end{description}
|
|
|
|
When called without a format string,
|
|
this function writes numbers using the \verb'%g' format
|
|
and strings with \verb'%s'.
|
|
For better format facilities,
|
|
the function \verb'format' should be used (\see{format}).
|
|
|
|
\subsubsection*{{\tt date ([format])}}\Deffunc{date}
|
|
|
|
This function returns a string containing date and time
|
|
formatted according to the given string \verb'format',
|
|
following the same rules of the ANSI C function \verb'strftime'.
|
|
When called without arguments,
|
|
it returns a reasonable date and time representation.
|
|
|
|
This function replaces functions \verb'date' and \verb'time' from
|
|
previous Lua versions.
|
|
|
|
\subsubsection*{{\tt exit ([code])}}\Deffunc{exit}
|
|
|
|
This function calls the C function \verb-exit-,
|
|
with an optional \verb-code-,
|
|
to terminate the program.
|
|
|
|
|
|
\section{The Debugger Interface} \label{debugI}
|
|
|
|
Lua has no built-in debugger facilities.
|
|
Instead, it offers a special interface,
|
|
by means of functions and {\em hooks},
|
|
which allows the construction of different
|
|
kinds of debugers, profilers, and other tools
|
|
that need ``inside information'' from the interpreter.
|
|
This interface is declared in the header file \verb'luadebug.h'.
|
|
|
|
\subsection{Stack and Function Information}
|
|
|
|
The main function to get information about the interpreter stack
|
|
is
|
|
\begin{verbatim}
|
|
lua_Function lua_stackedfunction (int level);
|
|
\end{verbatim}
|
|
It returns a handle (\verb'lua_Function') to the {\em activation record\/}
|
|
of the function executing at a given level.
|
|
Level 0 is the current running function,
|
|
while level $n+1$ is the function that has called level $n$.
|
|
When called with a level greater than the stack depth,
|
|
\verb'lua_stackedfunction' returns \verb'LUA_NOOBJECT'.
|
|
|
|
The type \verb'lua_Function' is just another name
|
|
to \verb'lua_Object'.
|
|
Although, in this library,
|
|
a \verb'lua_Function' can be used wherever a \verb'lua_Object' is required,
|
|
a parameter \verb'lua_Function' accepts only a handle returned by
|
|
\verb'lua_stackedfunction'.
|
|
|
|
Three other functions produce extra information about a function:
|
|
\begin{verbatim}
|
|
void lua_funcinfo (lua_Object func, char **filename, int *linedefined);
|
|
int lua_currentline (lua_Function func);
|
|
char *lua_getobjname (lua_Object o, char **name);
|
|
\end{verbatim}
|
|
\verb'lua_funcinfo' gives the file name and the line where the
|
|
given function has been defined.
|
|
If the ``function'' is in fact the main code of a chunk,
|
|
then \verb'linedefined' is 0.
|
|
If the function is a C function,
|
|
then \verb'linedefined' is -1, and \verb'filename' is \verb'"(C)"'.
|
|
|
|
The function \verb'lua_currentline' gives the current line where
|
|
a given function is executing.
|
|
It only works if the function has been pre-compiled with debug
|
|
information (\see{pragma}).
|
|
When no line information is available, it returns -1.
|
|
|
|
Function \verb'lua_getobjname' tries to find a reasonable name for
|
|
a given function.
|
|
Because functions in Lua are first class values,
|
|
they do not have a fixed name.
|
|
Some functions may be the value of many global variables,
|
|
while others may be stored only in a table field.
|
|
Function \verb'lua_getobjname' first checks whether the given
|
|
function is a fallback.
|
|
If so, it returns the string \verb'"fallback"',
|
|
and \verb'name' is set to point to the fallback name.
|
|
Otherwise, if the given function is the value of a global variable,
|
|
then \verb'lua_getobjname' returns the string \verb'"global"',
|
|
while \verb'name' points to the variable name.
|
|
If the given function is neither a fallback nor a global variable,
|
|
then \verb'lua_getobjname' returns the empty string,
|
|
and \verb'name' is set to \verb'NULL'.
|
|
|
|
\subsection{Manipulating Local Variables}
|
|
|
|
The following functions allow the manipulation of the
|
|
local variables of a given activation record.
|
|
They only work if the function has been pre-compiled with debug
|
|
information (\see{pragma}).
|
|
\begin{verbatim}
|
|
lua_Object lua_getlocal (lua_Function func, int local_number, char **name);
|
|
int lua_setlocal (lua_Function func, int local_number);
|
|
\end{verbatim}
|
|
The first one returns the value of a local variable,
|
|
and sets \verb'name' to point to the variable name.
|
|
\verb'local_number' is an index for local variables.
|
|
The first parameter has index 1, and so on, until the
|
|
last active local variable.
|
|
When called with a \verb'local_number' greater than the
|
|
number of active local variables,
|
|
or if the activation record has no debug information,
|
|
\verb'lua_getlocal' returns \verb'LUA_NOOBJECT'.
|
|
|
|
The function \verb'lua_setlocal' sets the local variable
|
|
\verb'local_number' to the value previously pushed on the stack
|
|
(\see{valuesCLua}).
|
|
If the function succeeds, then it returns 1.
|
|
If \verb'local_number' is greater than the number
|
|
of active local variables,
|
|
or if the activation record has no debug information,
|
|
then this function fails and returns 0.
|
|
|
|
\subsection{Hooks}
|
|
|
|
The Lua interpreter offers two hooks for debugging purposes:
|
|
\begin{verbatim}
|
|
typedef void (*lua_CHFunction) (lua_Function func, char *file, int line);
|
|
extern lua_CHFunction lua_callhook;
|
|
|
|
typedef void (*lua_LHFunction) (int line);
|
|
extern lua_LHFunction lua_linehook;
|
|
\end{verbatim}
|
|
The first one is called whenever the interpreter enters or leaves a
|
|
function.
|
|
When entering a function,
|
|
its parameters are a handle to the function activation record,
|
|
plus the file and the line where the function is defined (the same
|
|
information which is provided by \verb'lua_funcinfo');
|
|
when leaving a function, \verb'func' is \verb'LUA_NOOBJECT',
|
|
\verb'file' is \verb'"(return)"', and \verb'line' is 0.
|
|
|
|
The other hook is called every time the interpreter changes
|
|
the line of code it is executing.
|
|
Its only parameter is the line number
|
|
(the same information which is provided by the call
|
|
\verb'lua_currentline(lua_stackedfunction(0))').
|
|
This second hook is only called if the active function
|
|
has been pre-compiled with debug information (\see{pragma}).
|
|
|
|
A hook is disabled when its value is NULL (0),
|
|
which is the initial value of both hooks.
|
|
|
|
|
|
\section{Some Examples}
|
|
|
|
This section gives examples showing some features of Lua.
|
|
It does not intend to cover the whole language,
|
|
but only to illustrate some interesting uses of the system.
|
|
|
|
|
|
\subsection{\Index{Data Structures}}
|
|
Tables are a strong unifying data constructor.
|
|
They directly implement a multitude of data types,
|
|
like ordinary arrays, records, sets, bags, and lists.
|
|
|
|
Arrays need no explanations.
|
|
In Lua, it is conventional to start indices from 1,
|
|
but this is only a convention.
|
|
Arrays can be indexed by 0, negative numbers, or any other value (except \nil).
|
|
Records are also trivially implemented by the syntactic sugar
|
|
\verb'a.x'.
|
|
|
|
The best way to implement a set is to store
|
|
its elements as indices of a table.
|
|
The statement \verb's = {}' creates an empty set \verb's'.
|
|
The statement \verb's[x] = 1' inserts the value of \verb'x' into
|
|
the set \verb's'.
|
|
The expression \verb's[x]' is true if and only if
|
|
\verb'x' belongs to \verb's'.
|
|
Finally, the statement \verb's[x] = nil' removes \verb'x' from \verb's'.
|
|
|
|
Bags can be implemented similarly to sets,
|
|
but using the value associated to an element as its counter.
|
|
So, to insert an element,
|
|
the following code is enough:
|
|
\begin{verbatim}
|
|
if s[x] then s[x] = s[x]+1 else s[x] = 1 end
|
|
\end{verbatim}
|
|
and to remove an element:
|
|
\begin{verbatim}
|
|
if s[x] then s[x] = s[x]-1 end
|
|
if s[x] == 0 then s[x] = nil end
|
|
\end{verbatim}
|
|
|
|
Lisp-like lists also have an easy implementation.
|
|
The ``cons'' of two elements \verb'x' and \verb'y' can be
|
|
created with the code \verb'l = {car=x, cdr=y}'.
|
|
The expression \verb'l.car' extracts the header,
|
|
while \verb'l.cdr' extracts the tail.
|
|
An alternative way is to create the list directly with \verb'l={x,y}',
|
|
and then to extract the header with \verb'l[1]' and
|
|
the tail with \verb'l[2]'.
|
|
|
|
\subsection{The Functions {\tt next} and {\tt nextvar}} \label{exnext}
|
|
\Deffunc{next}\Deffunc{nextvar}
|
|
This example shows how to use the function \verb'next' to iterate
|
|
over the fields of a table.
|
|
Function \IndexVerb{clone} receives any table and returns a clone of it.
|
|
\begin{verbatim}
|
|
function clone (t) -- t is a table
|
|
local new_t = {} -- create a new table
|
|
local i, v = next(t, nil) -- i is an index of t, v = t[i]
|
|
while i do
|
|
new_t[i] = v
|
|
i, v = next(t, i) -- get next index
|
|
end
|
|
return new_t
|
|
end
|
|
\end{verbatim}
|
|
|
|
The next example prints the names of all global variables
|
|
in the system with non nil values:
|
|
\begin{verbatim}
|
|
function printGlobalVariables ()
|
|
local i, v = nextvar(nil)
|
|
while i do
|
|
print(i)
|
|
i, v = nextvar(i)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{String Manipulation} \label{exstring}
|
|
|
|
The first example is a function to trim extra blanks at the beginning
|
|
and end of a string.
|
|
\begin{verbatim}
|
|
function trim(s)
|
|
local l = 1
|
|
while strsub(s,l,l) == ' ' do
|
|
l = l+1
|
|
end
|
|
local r = strlen(s)
|
|
while strsub(s,r,r) == ' ' do
|
|
r = r-1
|
|
end
|
|
return strsub(s,l,r)
|
|
end
|
|
\end{verbatim}
|
|
|
|
The second example shows a function that eliminates all blanks
|
|
of a string.
|
|
\begin{verbatim}
|
|
function remove_blanks (s)
|
|
local b = strfind(s, ' ')
|
|
while b do
|
|
s = strsub(s, 1, b-1) .. strsub(s, b+1)
|
|
b = strfind(s, ' ')
|
|
end
|
|
return s
|
|
end
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{\Index{Variable number of arguments}}
|
|
Lua does not provide any explicit mechanism to deal with
|
|
variable number of arguments in function calls.
|
|
However, one can use table constructors to simulate this mechanism.
|
|
As an example, suppose a function to concatenate all its arguments.
|
|
It could be written like
|
|
\begin{verbatim}
|
|
function concat (o)
|
|
local i = 1
|
|
local s = ''
|
|
while o[i] do
|
|
s = s .. o[i]
|
|
i = i+1
|
|
end
|
|
return s
|
|
end
|
|
\end{verbatim}
|
|
To call it, one uses a table constructor to join all arguments:
|
|
\begin{verbatim}
|
|
x = concat{"hello ", "john", " and ", "mary"}
|
|
\end{verbatim}
|
|
|
|
\subsection{\Index{Persistence}}
|
|
Because of its reflexive facilities,
|
|
persistence in Lua can be achieved within the language.
|
|
This section shows some ways to store and retrieve values in Lua,
|
|
using a text file written in the language itself as the storage media.
|
|
|
|
To store a single value with a name,
|
|
the following code is enough:
|
|
\begin{verbatim}
|
|
function store (name, value)
|
|
write(format('\n%s =', name))
|
|
write_value(value)
|
|
end
|
|
\end{verbatim}
|
|
\begin{verbatim}
|
|
function write_value (value)
|
|
local t = type(value)
|
|
if t == 'nil' then write('nil')
|
|
elseif t == 'number' then write(value)
|
|
elseif t == 'string' then write(value, 'q')
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
In order to restore this value, a \verb'lua_dofile' suffices.
|
|
|
|
Storing tables is a little more complex.
|
|
Assuming that the table is a tree,
|
|
and that all indices are identifiers
|
|
(that is, the tables are being used as records),
|
|
then its value can be written directly with table constructors.
|
|
First, the function \verb'write_value' is changed to
|
|
\begin{verbatim}
|
|
function write_value (value)
|
|
local t = type(value)
|
|
if t == 'nil' then write('nil')
|
|
elseif t == 'number' then write(value)
|
|
elseif t == 'string' then write(value, 'q')
|
|
elseif t == 'table' then write_record(value)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
The function \verb'write_record' is:
|
|
\begin{verbatim}
|
|
function write_record(t)
|
|
local i, v = next(t, nil)
|
|
write('{') -- starts constructor
|
|
while i do
|
|
store(i, v)
|
|
write(', ')
|
|
i, v = next(t, i)
|
|
end
|
|
write('}') -- closes constructor
|
|
end
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Inheritance} \label{exfallback}
|
|
The fallback for absent indices can be used to implement many
|
|
kinds of \Index{inheritance} in Lua.
|
|
As an example,
|
|
the following code implements single inheritance:
|
|
\begin{verbatim}
|
|
function Index (t,f)
|
|
if f == 'parent' then -- to avoid loop
|
|
return OldIndex(t,f)
|
|
end
|
|
local p = t.parent
|
|
if type(p) == 'table' then
|
|
return p[f]
|
|
else
|
|
return OldIndex(t,f)
|
|
end
|
|
end
|
|
|
|
OldIndex = setfallback("index", Index)
|
|
\end{verbatim}
|
|
Whenever Lua attempts to access an absent field in a table,
|
|
it calls the fallback function \verb'Index'.
|
|
If the table has a field \verb'parent' with a table value,
|
|
then Lua attempts to access the desired field in this parent object.
|
|
This process is repeated ``upwards'' until a value
|
|
for the field is found or the object has no parent.
|
|
In the latter case, the previous fallback is called to supply a value
|
|
for the field.
|
|
|
|
When better performance is needed,
|
|
the same fallback may be implemented in C,
|
|
as illustrated in Figure~\ref{Cinher}.
|
|
\begin{figure}
|
|
\Line
|
|
\begin{verbatim}
|
|
#include "lua.h"
|
|
|
|
int lockedParentName; /* lock index for the string "parent" */
|
|
int lockedOldIndex; /* previous fallback function */
|
|
|
|
void callOldFallback (lua_Object table, lua_Object index)
|
|
{
|
|
lua_Object oldIndex = lua_getref(lockedOldIndex);
|
|
lua_pushobject(table);
|
|
lua_pushobject(index);
|
|
lua_callfunction(oldIndex);
|
|
}
|
|
|
|
void Index (void)
|
|
{
|
|
lua_Object table = lua_getparam(1);
|
|
lua_Object index = lua_getparam(2);
|
|
lua_Object parent;
|
|
if (lua_isstring(index) && strcmp(lua_getstring(index), "parent") == 0)
|
|
{
|
|
callOldFallback(table, index);
|
|
return;
|
|
}
|
|
lua_pushobject(table);
|
|
lua_pushref(lockedParentName);
|
|
parent = lua_getsubscript();
|
|
if (lua_istable(parent))
|
|
{
|
|
lua_pushobject(parent);
|
|
lua_pushobject(index);
|
|
/* return result from getsubscript */
|
|
lua_pushobject(lua_getsubscript());
|
|
}
|
|
else
|
|
callOldFallback(table, index);
|
|
}
|
|
\end{verbatim}
|
|
\caption{Inheritance in C.\label{Cinher}}
|
|
\Line
|
|
\end{figure}
|
|
This code must be registered with:
|
|
\begin{verbatim}
|
|
lua_pushstring("parent");
|
|
lockedParentName = lua_ref(1);
|
|
lua_pushobject(lua_setfallback("index", Index));
|
|
lockedOldIndex = lua_ref(1);
|
|
\end{verbatim}
|
|
Notice how the string \verb'"parent"' is kept
|
|
locked in Lua for optimal performance.
|
|
|
|
\subsection{\Index{Programming with Classes}}
|
|
There are many different ways to do object-oriented programming in Lua.
|
|
This section presents one possible way to
|
|
implement classes,
|
|
using the inheritance mechanism presented above.
|
|
{\em Please notice: the following examples only work
|
|
with the index fallback redefined according to
|
|
Section~\ref{exfallback}}.
|
|
|
|
As one could expect, a good way to represent a class is
|
|
with a table.
|
|
This table will contain all instance methods of the class,
|
|
plus optional default values for instance variables.
|
|
An instance of a class has its \verb'parent' field pointing to
|
|
the class,
|
|
and so it ``inherits'' all methods.
|
|
|
|
For instance, a class \verb'Point' can be described as in
|
|
Figure~\ref{Point}.
|
|
Function \verb'create' helps the creation of new points,
|
|
adding the parent field.
|
|
Function \verb'move' is an example of an instance method.
|
|
\begin{figure}
|
|
\Line
|
|
\begin{verbatim}
|
|
Point = {x = 0, y = 0}
|
|
|
|
function Point:create (o)
|
|
o.parent = self
|
|
return o
|
|
end
|
|
|
|
function Point:move (p)
|
|
self.x = self.x + p.x
|
|
self.y = self.y + p.y
|
|
end
|
|
|
|
...
|
|
|
|
--
|
|
-- creating points
|
|
--
|
|
p1 = Point:create{x = 10, y = 20}
|
|
p2 = Point:create{x = 10} -- y will be inherited until it is set
|
|
|
|
--
|
|
-- example of a method invocation
|
|
--
|
|
p1:move(p2)
|
|
\end{verbatim}
|
|
\caption{A Class {\tt Point}.\label{Point}}
|
|
\Line
|
|
\end{figure}
|
|
Finally, a subclass can be created as a new table,
|
|
with the \verb'parent' field pointing to its superclass.
|
|
It is interesting to notice how the use of \verb'self' in
|
|
method \verb'create' allows this method to work properly even
|
|
when inherited by a subclass.
|
|
As usual, a subclass may overwrite any inherited method with
|
|
its own version.
|
|
|
|
\subsection{\Index{Modules}}
|
|
Here we explain one possible way to simulate modules in Lua.
|
|
The main idea is to use a table to store the module functions.
|
|
|
|
A module should be written as a separate chunk, starting with:
|
|
\begin{verbatim}
|
|
if modulename then return end -- avoid loading twice the same module
|
|
modulename = {} -- create a table to represent the module
|
|
\end{verbatim}
|
|
After that, functions can be directly defined with the syntax
|
|
\begin{verbatim}
|
|
function modulename.foo (...)
|
|
...
|
|
end
|
|
\end{verbatim}
|
|
|
|
Any code that needs this module has only to execute
|
|
\verb'dofile("filename")', where \verb'filename' is the file
|
|
where the module is written.
|
|
After this, any function can be called with
|
|
\begin{verbatim}
|
|
modulename.foo(...)
|
|
\end{verbatim}
|
|
|
|
If a module function is going to be used many times,
|
|
the program can give a local name to it.
|
|
Because functions are values, it is enough to write
|
|
\begin{verbatim}
|
|
localname = modulename.foo
|
|
\end{verbatim}
|
|
Finally, a module may be {\em opened},
|
|
giving direct access to all its functions,
|
|
as shown in the code in Figure~\ref{openmod}.
|
|
\begin{figure}
|
|
\Line
|
|
\begin{verbatim}
|
|
function open (mod)
|
|
local n, f = next(mod, nil)
|
|
while n do
|
|
setglobal(n, f)
|
|
n, f = next(mod, n)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
\caption{Opening a module.\label{openmod}}
|
|
\Line
|
|
\end{figure}
|
|
|
|
\subsection{A CFunction} \label{exCFunction}\index{functions in C}
|
|
A CFunction to compute the maximum of a variable number of arguments
|
|
is shown in Figure~\ref{Cmax}.
|
|
\begin{figure}
|
|
\Line
|
|
\begin{verbatim}
|
|
void math_max (void)
|
|
{
|
|
int i=1; /* number of arguments */
|
|
double d, dmax;
|
|
lua_Object o;
|
|
/* the function must get at least one argument */
|
|
if ((o = lua_getparam(i++)) == LUA_NOOBJECT)
|
|
lua_error ("too few arguments to function `max'");
|
|
/* and this argument must be a number */
|
|
if (!lua_isnumber(o))
|
|
lua_error ("incorrect argument to function `max'");
|
|
dmax = lua_getnumber (o);
|
|
/* loops until there is no more arguments */
|
|
while ((o = lua_getparam(i++)) != LUA_NOOBJECT)
|
|
{
|
|
if (!lua_isnumber(o))
|
|
lua_error ("incorrect argument to function `max'");
|
|
d = lua_getnumber (o);
|
|
if (d > dmax) dmax = d;
|
|
}
|
|
/* push the result to be returned */
|
|
lua_pushnumber (dmax);
|
|
}
|
|
\end{verbatim}
|
|
\caption{C function {\tt math\_max}.\label{Cmax}}
|
|
\Line
|
|
\end{figure}
|
|
After registered with
|
|
\begin{verbatim}
|
|
lua_register ("max", math_max);
|
|
\end{verbatim}
|
|
this function is available in Lua, as follows:
|
|
\begin{verbatim}
|
|
i = max(4, 5, 10, -34) -- i receives 10
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Calling Lua Functions} \label{exLuacall}
|
|
|
|
This example illustrates how a C function can call the Lua function
|
|
\verb'remove_blanks' presented in Section~\ref{exstring}.
|
|
\begin{verbatim}
|
|
void remove_blanks (char *s)
|
|
{
|
|
lua_pushstring(s); /* prepare parameter */
|
|
lua_call("remove_blanks"); /* call Lua function */
|
|
strcpy(s, lua_getstring(lua_getresult(1))); /* copy result back to 's' */
|
|
}
|
|
\end{verbatim}
|
|
|
|
|
|
\section*{Acknowledgments}
|
|
|
|
The authors would like to thank CENPES/PETROBR\'AS which,
|
|
jointly with \tecgraf, used extensively early versions of
|
|
this system and gave valuable comments.
|
|
The authors would also like to thank Carlos Henrique Levy,
|
|
who found the name of the game.
|
|
Lua means {\em moon} in Portuguese.
|
|
|
|
|
|
|
|
\appendix
|
|
|
|
\section*{Incompatibilities with Previous Versions}
|
|
|
|
Although great care has been taken to avoid incompatibilities with
|
|
the previous public versions of Lua,
|
|
some differences had to be introduced.
|
|
Here is a list of all these differences.
|
|
|
|
\subsection*{Incompatibilities with \Index{version 2.2}}
|
|
\begin{itemize}
|
|
\item
|
|
Functions \verb'date' and \verb'time' (from \verb'iolib')
|
|
have been superseded by the new, more powerful version of function \verb'date'.
|
|
\item
|
|
Function \verb'append' (from \verb'iolib') now returns 1 whenever it succeeds,
|
|
whether the file is new or not.
|
|
\item
|
|
Function \verb'int2str' (from \verb'strlib') has been superseded by new
|
|
function \verb'format', with parameter \verb'"%c"'.
|
|
\item
|
|
The API lock mechanism has been superseded by the reference mechanism.
|
|
However, \verb-lua.h- provides compatibility macros,
|
|
so there is no need to change programs.
|
|
\item
|
|
The API function \verb'lua_pushliteral' now is just a macro to
|
|
\verb'lua_pushstring'.
|
|
\end{itemize}
|
|
|
|
\subsection*{Incompatibilities with \Index{version 2.1}}
|
|
\begin{itemize}
|
|
\item
|
|
The function \verb'type' now returns the string \verb'"function"'
|
|
both for C and Lua functions.
|
|
Because Lua functions and C functions are compatible,
|
|
this behavior is usually more useful.
|
|
When needed, the second result of function {\tt type} may be used
|
|
to distinguish between Lua and C functions.
|
|
\item
|
|
A function definition only assigns the function value to the
|
|
given variable at execution time.
|
|
\end{itemize}
|
|
|
|
\subsection*{Incompatibilities with \Index{version 1.1}}
|
|
\begin{itemize}
|
|
\item
|
|
The equality test operator now is denoted by \verb'==',
|
|
instead of \verb'='.
|
|
\item
|
|
The syntax for table construction has been greatly simplified.
|
|
The old \verb'@(size)' has been substituted by \verb'{}'.
|
|
The list constructor (formerly \verb'@[...]') and the record
|
|
constructor (formerly \verb'@{...}') now are both coded like
|
|
\verb'{...}'.
|
|
When the construction involves a function call,
|
|
like in \verb'@func{...}',
|
|
the new syntax does not use the \verb'@'.
|
|
More important, {\em a construction function must now
|
|
explicitly return the constructed table}.
|
|
\item
|
|
The function \verb'lua_call' no longer has the parameter \verb'nparam'.
|
|
\item
|
|
The function \verb'lua_pop' is no longer available,
|
|
since it could lead to strange behavior.
|
|
In particular,
|
|
to access results returned from a Lua function,
|
|
the new macro \verb'lua_getresult' should be used.
|
|
\item
|
|
The old functions \verb'lua_storefield' and \verb'lua_storeindexed'
|
|
have been replaced by
|
|
\begin{verbatim}
|
|
int lua_storesubscript (void);
|
|
\end{verbatim}
|
|
with the parameters explicitly pushed on the stack.
|
|
\item
|
|
The functionality of the function \verb'lua_errorfunction' has been
|
|
replaced by the {\em fallback} mechanism (\see{error}).
|
|
\item
|
|
When calling a function from the Lua library,
|
|
parameters passed through the stack
|
|
must be pushed just before the corresponding call,
|
|
with no intermediate calls to Lua.
|
|
Special care should be taken with macros like
|
|
\verb'lua_getindexed' and \verb'lua_getfield'.
|
|
\end{itemize}
|
|
|
|
\newcommand{\indexentry}[2]{\item {#1} #2}
|
|
%\catcode`\_=12
|
|
\begin{theindex}
|
|
\input{manual.id}
|
|
\end{theindex}
|
|
|
|
\pagebreak
|
|
\tableofcontents
|
|
|
|
\end{document}
|