mirror of
https://github.com/lua/lua
synced 2024-11-30 00:23:24 +03:00
3295 lines
118 KiB
TeX
3295 lines
118 KiB
TeX
% $Id: manual.tex,v 1.32 1999/05/11 20:46:28 roberto Exp roberto $
|
|
|
|
\documentclass[11pt]{article}
|
|
\usepackage{fullpage,bnf}
|
|
|
|
\catcode`\_=12
|
|
|
|
\newcommand{\See}[1]{Section~\ref{#1}}
|
|
\newcommand{\see}[1]{(see \See{#1})}
|
|
\newcommand{\M}[1]{\emph{#1}}
|
|
\newcommand{\T}[1]{{\tt #1}}
|
|
\newcommand{\Math}[1]{$#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]{\T{#1}\index{#1}}
|
|
\newcommand{\Def}[1]{\emph{#1}\index{#1}}
|
|
\newcommand{\Deffunc}[1]{\index{#1}}
|
|
|
|
\newcommand{\ff}{$\bullet$\ }
|
|
|
|
\newcommand{\Version}{3.2}
|
|
|
|
\makeindex
|
|
|
|
\begin{document}
|
|
|
|
\title{Reference Manual of the Programming Language Lua \Version}
|
|
|
|
\author{%
|
|
Roberto Ierusalimschy\quad
|
|
Luiz Henrique de Figueiredo\quad
|
|
Waldemar Celes
|
|
\vspace{1.0ex}\\
|
|
\smallskip
|
|
\small\tt lua@tecgraf.puc-rio.br
|
|
\vspace{2.0ex}\\
|
|
%MCC 08/95 ---
|
|
\tecgraf\ --- Computer Science Department --- PUC-Rio
|
|
}
|
|
|
|
\date{{\small \tt\$Date: 1999/05/11 20:46:28 $ $}}
|
|
|
|
\maketitle
|
|
|
|
\thispagestyle{empty}
|
|
\pagestyle{empty}
|
|
|
|
\begin{abstract}
|
|
\noindent
|
|
Lua is a programming language originally designed for extending applications,
|
|
but also frequently used as a general-purpose, stand-alone language.
|
|
Lua combines simple procedural syntax (similar to Pascal)
|
|
with powerful data description constructs based on associative
|
|
arrays and extensible semantics.
|
|
Lua is dynamically typed, interpreted from bytecodes,
|
|
and has automatic memory management with garbage collection,
|
|
making it ideal for configuration, scripting, and rapid prototyping.
|
|
|
|
This document describes version \Version\ of the Lua programming language
|
|
and the API that allows interaction between Lua programs and their
|
|
host C programs.
|
|
\end{abstract}
|
|
\vspace{4ex}
|
|
\begin{quotation}
|
|
\small
|
|
\begin{center}{\bf Sum\'ario}\end{center}
|
|
\vspace{1ex}
|
|
\noindent
|
|
Lua \'e uma linguagem de programa\c{c}\~ao originalmente projetada para
|
|
extens\~ao de aplica\c{c}\~oes,
|
|
e que \'e tamb\'em frequentemente usada como uma linguagem de
|
|
prop\'osito geral.
|
|
Lua combina uma sintaxe procedural simples (similar a Pascal)
|
|
com poderosas facilidades para descri\c{c}\~ao de dados baseadas
|
|
em tabelas associativas e uma sem\^antica estens\'{\i}vel.
|
|
Lua tem tipagem din\^amica, \'e interpretada via bytecodes,
|
|
e tem gerenciamento autom\'atico de mem\'oria com coleta de lixo,
|
|
tornando-se ideal para configura\c{c}\~ao, scripting,
|
|
e prototipagem r\'apida.
|
|
|
|
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.
|
|
\end{quotation}
|
|
|
|
|
|
\newpage
|
|
\begin{quotation}
|
|
\parskip=10pt
|
|
\noindent
|
|
\footnotesize
|
|
Copyright \copyright\ 1994--1999 TeCGraf, PUC-Rio. All rights reserved.
|
|
|
|
\noindent
|
|
Permission is hereby granted, without written agreement and without license
|
|
or royalty fees, to use, copy, modify, and distribute this software and its
|
|
documentation for any purpose, including commercial applications, subject to
|
|
the following conditions:
|
|
\begin{itemize}
|
|
\item The above copyright notice and this permission notice shall appear in all
|
|
copies or substantial portions of this software.
|
|
|
|
\item The origin of this software must not be misrepresented; you must not
|
|
claim that you wrote the original software. If you use this software in a
|
|
product, an acknowledgment in the product documentation would be greatly
|
|
appreciated (but it is not required).
|
|
|
|
\item Altered source versions must be plainly marked as such, and must not be
|
|
misrepresented as being the original software.
|
|
\end{itemize}
|
|
The authors specifically disclaim any warranties, including, but not limited
|
|
to, the implied warranties of merchantability 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,
|
|
enhancements, or modifications. In no event shall TeCGraf, PUC-Rio, or the
|
|
authors be held liable to any party for direct, indirect, special,
|
|
incidental, or consequential damages arising out of the use of this software
|
|
and its documentation.
|
|
|
|
\noindent
|
|
The Lua language and this implementation have been entirely designed and
|
|
written by Waldemar Celes, Roberto Ierusalimschy and Luiz Henrique de
|
|
Figueiredo at TeCGraf, PUC-Rio.
|
|
|
|
\noindent
|
|
This implementation contains no third-party code.
|
|
\end{quotation}
|
|
|
|
\newpage
|
|
|
|
\tableofcontents
|
|
|
|
\newpage
|
|
\setcounter{page}{1}
|
|
\pagestyle{plain}
|
|
|
|
|
|
\section{Introduction}
|
|
|
|
Lua is an extension programming language designed to support
|
|
general procedural programming with data description
|
|
facilities.
|
|
Lua is intended to be used as a light-weight, but powerful,
|
|
configuration language for any program that needs one.
|
|
|
|
Lua is implemented as a library, written in C.
|
|
Being an extension language, Lua has no notion of a ``main'' program:
|
|
it only works \emph{embedded} in a host client,
|
|
called the \emph{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
|
|
a wide range of different domains,
|
|
thus creating customized programming languages sharing a syntactical framework.
|
|
|
|
Lua is free-distribution software,
|
|
and provided as usual with no guarantees,
|
|
as stated in the copyright notice.
|
|
The implementation described in this manual is available
|
|
at the following URL's:
|
|
\begin{verbatim}
|
|
http://www.tecgraf.puc-rio.br/lua/
|
|
ftp://ftp.tecgraf.puc-rio.br/pub/lua/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,
|
|
is initialized with a call from the embedding program to
|
|
\verb|lua_open| and
|
|
persists until a call to \verb|lua_close|,
|
|
or the end of the embedding program.
|
|
Optionally, a user can create multiple independent global
|
|
environments \see{mangstate}.
|
|
|
|
The global environment can be manipulated by Lua code or
|
|
by the embedding program,
|
|
which can read and write global variables
|
|
using API functions from 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;
|
|
this default can be changed \see{tag-method}.
|
|
|
|
The unit of execution of Lua is called a \Def{chunk}.
|
|
A chunk is simply a sequence of statements:
|
|
\begin{Produc}
|
|
\produc{chunk}{\rep{stat} \opt{ret}}
|
|
\end{Produc}%
|
|
Statements are described in \See{stats}.
|
|
(As usual, \rep{\emph{a}} means 0 or more \emph{a}'s,
|
|
\opt{\emph{a}} means an optional \emph{a} and \oneormore{\emph{a}} means
|
|
one or more \emph{a}'s.)
|
|
|
|
A chunk may be in a file or in a string inside the host program.
|
|
A chunk may optionally end with a \verb|return| statement \see{return}.
|
|
When a chunk is executed, first all its code is pre-compiled,
|
|
then the statements are executed in sequential order.
|
|
All modifications a chunk effects on the global environment persist
|
|
after the chunk end.
|
|
|
|
Chunks may also be pre-compiled into binary form;
|
|
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 and Tags}} \label{TypesSec}
|
|
|
|
Lua is a dynamically typed language.
|
|
Variables do not have types; only values do.
|
|
Therefore, there are no type definitions in the language.
|
|
All values carry their own type.
|
|
Besides a type, all values also have a \Index{tag}.
|
|
|
|
There are six \Index{basic types} in Lua: \Def{nil}, \Def{number},
|
|
\Def{string}, \Def{function}, \Def{userdata}, and \Def{table}.
|
|
\emph{Nil} is the type of the value \nil,
|
|
whose main property is to be different from any other value.
|
|
\emph{Number} represents real (double-precision floating-point) numbers,
|
|
while \emph{string} has the usual meaning.
|
|
Lua is \Index{eight-bit clean},
|
|
and so strings may contain any 8-bit character,
|
|
\emph{including} embedded zeros (\verb|'\0'|).
|
|
The function \verb|type| returns a string describing the type
|
|
of a given value \see{pdf-type}.
|
|
|
|
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.
|
|
Lua can call (and manipulate) functions written in Lua and
|
|
functions written in C.
|
|
They can be distinguished by their tags:
|
|
all Lua functions have the same tag,
|
|
and all C functions have the same tag,
|
|
which is different from the tag of Lua functions.
|
|
|
|
The type \emph{userdata} is provided to allow
|
|
arbitrary \Index{C pointers} to be stored in Lua variables.
|
|
It corresponds to a \verb|void*| and has no pre-defined operations in Lua,
|
|
besides assignment and equality test.
|
|
However, by using \emph{tag methods},
|
|
the programmer can define operations for \emph{userdata} values
|
|
\see{tag-method}.
|
|
|
|
The type \emph{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.
|
|
Tables are the main data structuring mechanism in Lua.
|
|
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 \see{func-def}.
|
|
|
|
Note that tables are \emph{objects}, and not values.
|
|
Variables cannot contain tables, only \emph{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}.
|
|
|
|
Tags are mainly used to select tag methods when
|
|
some events occur.
|
|
Tag methods are the main mechanism for extending the
|
|
semantics of Lua \see{tag-method}.
|
|
Each of the types \M{nil}, \M{number} and \M{string} has a different tag.
|
|
All values of each of these types have this same pre-defined tag.
|
|
Values of type \M{function} can have two different tags,
|
|
depending on whether they are Lua functions or C functions.
|
|
Finally,
|
|
values of type \M{userdata} and \M{table} can have
|
|
as many different tags as needed \see{tag-method}.
|
|
Tags are created with the function \verb|newtag|,
|
|
and the function \verb|tag| returns the tag of a given value.
|
|
To change the tag of a given table,
|
|
there is the function \verb|settag| \see{pdf-newtag}.
|
|
|
|
|
|
\section{The Language}
|
|
|
|
This section describes the lexis, the syntax and the semantics of Lua.
|
|
|
|
|
|
\subsection{Lexical Conventions} \label{lexical}
|
|
|
|
\Index{Identifiers} in Lua can be any string of letters,
|
|
digits, and underscores,
|
|
not beginning with a digit.
|
|
The definition of letter depends on the current locale:
|
|
Any character considered alphabetic by the current locale
|
|
can be used in an identifier.
|
|
The following words are 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}
|
|
Lua is a case-sensitive language:
|
|
\T{and} is a reserved word, but \T{And} and \T{\'and}
|
|
(if the locale permits) are two other different identifiers.
|
|
As a convention, identifiers starting with underscore followed by
|
|
uppercase letters are reserved for internal variables.
|
|
|
|
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|'\a'| (bell),
|
|
\verb|'\b'| (backspace),
|
|
\verb|'\f'| (form feed),
|
|
\verb|'\n'| (new line),
|
|
\verb|'\r'| (carriage return),
|
|
\verb|'\t'| (horizontal tab),
|
|
\verb|'\v'| (vertical tab),
|
|
\verb|'\\'|, (backslash),
|
|
\verb|'\"'|, (double quote),
|
|
and \verb|'\''| (single quote).
|
|
A character in a string may also be specified by its numerical value,
|
|
through the escape sequence \verb|'\ddd'|,
|
|
where \verb|ddd| is a sequence of up to three \emph{decimal} digits.
|
|
Strings in Lua may contain any 8-bit value, including embedded 0.
|
|
|
|
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.
|
|
This form is specially convenient for
|
|
writing strings that contain program pieces or
|
|
other quoted strings.
|
|
As an example, in a system using ASCII,
|
|
the following three literals are equivalent:
|
|
\begin{verbatim}
|
|
1) "alo\n123\""
|
|
2) '\97lo\10\04923"'
|
|
3) [[alo
|
|
123"]]
|
|
\end{verbatim}
|
|
|
|
|
|
\Index{Comments} start anywhere outside a string with a
|
|
double hyphen (\verb|--|) and run until the end of the line.
|
|
Moreover,
|
|
the first line of a chunk is skipped if it starts with \verb|#|.
|
|
This facility allows the use of Lua as a script interpreter
|
|
in Unix systems \see{lua-sa}.
|
|
|
|
\Index{Numerical constants} may be written with an optional decimal part,
|
|
and an optional decimal exponent.
|
|
Examples of valid numerical constants are
|
|
\begin{verbatim}
|
|
3 3.0 3.1416 314.16e-2 0.31416E1
|
|
\end{verbatim}
|
|
|
|
\subsection{The \Index{Pre-processor}} \label{pre-processor}
|
|
|
|
All lines that start with a \verb|$| sign are handled by a pre-processor.
|
|
The \verb|$| sign must be immediately
|
|
followed by one of the following directives:
|
|
\begin{description}
|
|
\item[\T{debug}] --- turn on debugging facilities \see{pragma}.
|
|
\item[\T{nodebug}] --- turn off debugging facilities \see{pragma}.
|
|
\item[\T{if \M{cond}}] --- starts a conditional part.
|
|
If \M{cond} is false, then this part is skipped by the lexical analyzer.
|
|
\item[\T{ifnot \M{cond}}] --- starts a conditional part.
|
|
If \M{cond} is true, then this part is skipped by the lexical analyzer.
|
|
\item[\T{end}] --- ends a conditional part.
|
|
\item[\T{else}] --- starts an ``else'' conditional part,
|
|
flipping the ``skip'' status.
|
|
\item[\T{endinput}] --- ends the lexical parse of the file.
|
|
\end{description}
|
|
|
|
Directives may be freely nested.
|
|
Particularly, a \verb|$endinput| may occur inside a \verb|$if|;
|
|
in that case, even the matching \verb|$end| is not parsed.
|
|
|
|
A \M{cond} part may be
|
|
\begin{description}
|
|
\item[\T{nil}] --- always false.
|
|
\item[\T{1}] --- always true.
|
|
\item[\M{name}] --- true if the value of the
|
|
global variable \M{name} is different from \nil.
|
|
Note that \M{name} is evaluated \emph{before} the chunk starts its execution.
|
|
Therefore, actions in a chunk do not affect its own conditional directives.
|
|
\end{description}
|
|
|
|
\subsection{\Index{Coercion}} \label{coercion}
|
|
|
|
Lua provides some automatic conversions between values at run time.
|
|
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, in a reasonable format.
|
|
For complete control on how numbers are converted to strings,
|
|
use the \verb|format| function \see{format}.
|
|
|
|
|
|
\subsection{\Index{Adjustment}} \label{adjust}
|
|
|
|
Functions in Lua can return many values.
|
|
Because there are no type declarations,
|
|
when a function is called
|
|
the system does not know how many values a function will return,
|
|
or how many parameters it needs.
|
|
Therefore, sometimes, a list of values must be \emph{adjusted}, at run time,
|
|
to a given length.
|
|
If there are more values than are needed,
|
|
then the excess values are thrown away.
|
|
If there are more needs than values,
|
|
then the list is extended with as many \nil's as needed.
|
|
Adjustment occurs in multiple assignment \see{assignment}
|
|
and function calls \see{functioncall}.
|
|
|
|
|
|
\subsection{Statements}\label{stats}
|
|
|
|
Lua supports an almost conventional set of \Index{statements},
|
|
similar to those in Pascal or C.
|
|
The conventional commands include
|
|
assignment, control structures and procedure calls.
|
|
Non-conventional commands include table constructors
|
|
\see{tableconstructor},
|
|
and local variable declarations \see{localvar}.
|
|
|
|
\subsubsection{Blocks}
|
|
A \Index{block} is a list of statements, which are executed sequentially.
|
|
A statement may be optionally followed by a semicolon:
|
|
\begin{Produc}
|
|
\produc{block}{\rep{stat sc} \opt{ret}}
|
|
\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'' conditions.
|
|
|
|
A block may be explicitly delimited:
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{do} block \rwd{end}}
|
|
\end{Produc}%
|
|
This is useful to control the scope of local variables \see{localvar}.
|
|
|
|
\subsubsection{\Index{Assignment}} \label{assignment}
|
|
The language allows \Index{multiple assignment}.
|
|
Therefore, the syntax for assignment
|
|
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}
|
|
The two lists may have different lengths.
|
|
Before the assignment, the list of values is \emph{adjusted} to
|
|
the length of the list of variables \see{adjust}.
|
|
|
|
A single name can denote a global variable, 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}{simpleexp \ter{[} exp1 \ter{]}}
|
|
\end{Produc}%
|
|
The \M{simpleexp} should result in a table value,
|
|
from where the field indexed by the expression
|
|
value gets the assigned value.
|
|
|
|
The syntax \verb|var.NAME| is just syntactic sugar for
|
|
\verb|var["NAME"]|:
|
|
\begin{Produc}
|
|
\produc{var}{simpleexp \ter{.} name}
|
|
\end{Produc}%
|
|
|
|
The meaning of assignments and evaluations of global variables and
|
|
indexed variables can be changed by tag methods \see{tag-method}.
|
|
Actually,
|
|
an assignment \verb|x = val|, where \verb|x| is a global variable,
|
|
is equivalent to a call \verb|setglobal('x', val)|;
|
|
an assignment \verb|t[i] = val| is equivalent to
|
|
\verb|settable_event(t, i, val)|.
|
|
See \See{tag-method} for a complete description of these functions.
|
|
(Function \verb|setglobal| is pre-defined in Lua.
|
|
Function \T{settable\_event} is used only for explanatory purposes.)
|
|
|
|
\subsubsection{Control Structures}
|
|
The \Index{condition expression} of a control structure may return any value.
|
|
All values different from \nil\ are considered true;
|
|
only \nil\ is considered false.
|
|
\T{if}'s, \T{while}'s and \T{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{\rwd{elseif} exp1 \rwd{then} block}
|
|
\opt{\rwd{else} block} \rwd{end}}
|
|
\end{Produc}
|
|
|
|
A \T{return} is used to return values from a function or from a chunk.
|
|
\label{return}
|
|
Because they may return more than one value,
|
|
the syntax for a \Index{return statement} is
|
|
\begin{Produc}
|
|
\produc{ret}{\rwd{return} \opt{explist1} \opt{sc}}
|
|
\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}%
|
|
In this case, all returned values are thrown away.
|
|
Function calls are explained in \See{functioncall}.
|
|
|
|
\subsubsection{Local Declarations} \label{localvar}
|
|
\Index{Local variables} may 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{Basic Expressions}}
|
|
Basic expressions are
|
|
\begin{Produc}
|
|
\produc{exp}{\ter{(} exp \ter{)}}
|
|
\produc{exp}{\rwd{nil}}
|
|
\produc{exp}{\ter{number}}
|
|
\produc{exp}{\ter{literal}}
|
|
\produc{exp}{function}
|
|
\produc{exp}{simpleexp}
|
|
\end{Produc}%
|
|
\begin{Produc}
|
|
\produc{simpleexp}{var}
|
|
\produc{simpleexp}{upvalue}
|
|
\produc{simpleexp}{functioncall}
|
|
\end{Produc}%
|
|
|
|
Numbers (numerical constants) and
|
|
string literals are explained in \See{lexical};
|
|
variables are explained in \See{assignment};
|
|
upvalues are explained in \See{upvalue};
|
|
function definitions (\M{function}) are explained in \See{func-def};
|
|
function calls are explained in \See{functioncall}.
|
|
|
|
An access to a global variable \verb|x| is equivalent to a
|
|
call \verb|getglobal('x')|;
|
|
an access to an indexed variable \verb|t[i]| is equivalent to
|
|
a call \verb|gettable_event(t, i)|.
|
|
See \See{tag-method} for a description of these functions.
|
|
(Function \verb|getglobal| is pre-defined in Lua.
|
|
Function \T{gettable\_event} is used only for explanatory purposes.)
|
|
|
|
The non-terminal \M{exp1} is used to indicate that the values
|
|
returned by an expression must be adjusted to one single value:
|
|
\begin{Produc}
|
|
\produc{exp1}{exp}
|
|
\end{Produc}
|
|
|
|
\subsubsection{Arithmetic Operators}
|
|
Lua supports the usual \Index{arithmetic operators}:
|
|
the binary \verb|+| (addition),
|
|
\verb|-| (subtraction), \verb|*| (multiplication),
|
|
\verb|/| (division) and \verb|^| (exponentiation),
|
|
and unary \verb|-| (negation).
|
|
If the operands are numbers, or strings that can be converted to
|
|
numbers (according to the rules given in \See{coercion}),
|
|
then all operations except exponentiation have the usual meaning.
|
|
Otherwise, an appropriate tag method is called \see{tag-method}.
|
|
An exponentiation always calls a tag method.
|
|
The standard mathematical library redefines this method for numbers,
|
|
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\ as true.
|
|
|
|
Equality first compares the tags 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, userdata 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|==|).
|
|
Note that the conversion rules of \See{coercion}
|
|
\emph{do not} apply to equality comparisons.
|
|
Thus, \verb|"0"==0| evaluates to false,
|
|
and \verb|t[0]| and \verb|t["0"]| denote different
|
|
entries in a table.
|
|
|
|
The other operators work as follows.
|
|
If both arguments are numbers, then they are compared as such.
|
|
Otherwise, if both arguments are strings,
|
|
then their values are compared using lexicographical order.
|
|
Otherwise, the ``order'' tag method is called \see{tag-method}.
|
|
|
|
\subsubsection{Logical Operators}
|
|
The \Index{logical operators} are
|
|
\index{and}\index{or}\index{not}
|
|
\begin{verbatim}
|
|
and or not
|
|
\end{verbatim}
|
|
Like control structures, all logical operators
|
|
consider \nil\ as false and anything else as true.
|
|
The operator \verb|and| returns \nil\ if its first argument is \nil;
|
|
otherwise, it returns its second argument.
|
|
The operator \verb|or| returns its first argument
|
|
if it is different from \nil;
|
|
otherwise, it returns its second argument.
|
|
Both \verb|and| and \verb|or| use \Index{short-cut evaluation},
|
|
that is,
|
|
the second operand is evaluated only when necessary.
|
|
|
|
A useful Lua idiom is \verb|x = x or v|,
|
|
which is equivalent to
|
|
\begin{verbatim}
|
|
if x == nil then x = v end
|
|
\end{verbatim}
|
|
i.e., it sets \verb|x| to a default value \verb|v| when
|
|
\verb|x| is not set.
|
|
|
|
\subsubsection{Concatenation}
|
|
The string \Index{concatenation} operator in Lua is
|
|
denoted by ``\IndexVerb{..}''.
|
|
If both operands are strings or numbers, they are converted to
|
|
strings according to the rules in \See{coercion}.
|
|
Otherwise, the ``concat'' tag method is called \see{tag-method}.
|
|
|
|
\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
|
|
\Or ffieldlist \ter{;} lfieldlist}
|
|
\produc{lfieldlist}{\opt{lfieldlist1}}
|
|
\produc{ffieldlist}{\opt{ffieldlist1}}
|
|
\end{Produc}
|
|
|
|
The form \emph{lfieldlist1} is used to initialize lists:
|
|
\begin{Produc}
|
|
\produc{lfieldlist1}{exp \rep{\ter{,} exp} \opt{\ter{,}}}
|
|
\end{Produc}%
|
|
The expressions in the list are assigned to consecutive numerical indices,
|
|
starting with 1.
|
|
For example,
|
|
\begin{verbatim}
|
|
a = {"v1", "v2", 34}
|
|
\end{verbatim}
|
|
is equivalent to
|
|
\begin{verbatim}
|
|
do
|
|
local temp = {}
|
|
temp[1] = "v1"
|
|
temp[2] = "v2"
|
|
temp[3] = 34
|
|
a = temp
|
|
end
|
|
\end{verbatim}
|
|
|
|
The form \emph{ffieldlist1} initializes other fields in a table:
|
|
\begin{Produc}
|
|
\produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}}
|
|
\produc{ffield}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp}
|
|
\end{Produc}%
|
|
For example,
|
|
\begin{verbatim}
|
|
a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c}
|
|
\end{verbatim}
|
|
is equivalent to
|
|
\begin{verbatim}
|
|
do
|
|
local temp = {}
|
|
temp[f(k)] = g(y)
|
|
temp.x = 1 -- or temp["x"] = 1
|
|
temp.y = 3 -- or temp["y"] = 3
|
|
temp[0] = b+c
|
|
a = temp
|
|
end
|
|
\end{verbatim}
|
|
An expression like \verb|{x = 1, y = 4}| is
|
|
in fact syntactic sugar for \verb|{["x"] = 1, ["y"] = 4}|.
|
|
|
|
Both forms may have an optional trailing comma,
|
|
and can be used in the same constructor separated by
|
|
a semi-collon.
|
|
For example, all forms below are correct:
|
|
\begin{verbatim}
|
|
x = {;}
|
|
x = {'a', 'b',}
|
|
x = {type='list'; 'a', 'b'}
|
|
x = {f(0), f(1), f(2),; n=3,}
|
|
\end{verbatim}
|
|
|
|
\subsubsection{Function Calls} \label{functioncall}
|
|
A \Index{function call} has the following syntax:
|
|
\begin{Produc}
|
|
\produc{functioncall}{simpleexp args}
|
|
\end{Produc}%
|
|
First, \M{simpleexp} is evaluated.
|
|
If its value has type \emph{function},
|
|
then this function is called,
|
|
with the given arguments.
|
|
Otherwise, the ``function'' tag method is called,
|
|
having as first parameter the value of \M{simpleexp},
|
|
and then the original call parameters.
|
|
|
|
The form:
|
|
\begin{Produc}
|
|
\produc{functioncall}{simpleexp \ter{:} name args}
|
|
\end{Produc}%
|
|
can be used to call ``methods''.
|
|
A call \verb|simpleexp:name(...)|
|
|
is syntactic sugar for
|
|
\begin{verbatim}
|
|
simpleexp.name(simpleexp, ...)
|
|
\end{verbatim}
|
|
except that \verb|simpleexp| is evaluated only once.
|
|
|
|
Arguments have the following syntax:
|
|
\begin{Produc}
|
|
\produc{args}{\ter{(} \opt{explist1} \ter{)}}
|
|
\produc{args}{tableconstructor}
|
|
\produc{args}{\ter{literal}}
|
|
\produc{explist1}{exp1 \rep{\ter{,} exp1}}
|
|
\end{Produc}%
|
|
All argument expressions are evaluated before the call.
|
|
A call of the form \verb|f{...}| is syntactic sugar for
|
|
\verb|f({...})|, that is,
|
|
the parameter list is a single new table.
|
|
A call of the form \verb|f'...'|
|
|
(or \verb|f"..."| or \verb|f[[...]]|) is syntactic sugar for
|
|
\verb|f('...')|, that is,
|
|
the parameter list is a single literal string.
|
|
|
|
Because a function can return any number of results
|
|
\see{return},
|
|
the number of results must be adjusted before used.
|
|
If the function is called as a statement \see{funcstat},
|
|
then its return list is adjusted to~0,
|
|
thus discarding all returned values.
|
|
If the function is called in a place that needs a single value
|
|
(syntactically denoted by the non-terminal \M{exp1}),
|
|
then its return list is adjusted to~1,
|
|
thus discarding all returned values but the first one.
|
|
If the function is called in a place that can hold many values
|
|
(syntactically denoted by the non-terminal \M{exp}),
|
|
then no adjustment is made.
|
|
Note that the only place that can hold many values
|
|
is the last (or the only) expression in an assignment
|
|
or in a return statement; see examples below.
|
|
\begin{verbatim}
|
|
f(); -- adjusted to 0
|
|
g(x, f()); -- f() is adjusted to 1
|
|
a,b,c = f(), x; -- f() is adjusted to 1 result (and c gets nil)
|
|
a,b,c = x, f(); -- f() is adjusted to 2
|
|
a,b,c = f(); -- f() is adjusted to 3
|
|
return f(); -- returns all values returned by f()
|
|
\end{verbatim}
|
|
|
|
\subsubsection{\Index{Function Definitions}} \label{func-def}
|
|
|
|
The syntax for function definition is
|
|
\begin{Produc}
|
|
\produc{function}{\rwd{function} \ter{(} \opt{parlist1} \ter{)}
|
|
block \rwd{end}}
|
|
\produc{stat}{\rwd{function} funcname \ter{(} \opt{parlist1} \ter{)}
|
|
block \rwd{end}}
|
|
\produc{funcname}{name \Or name \ter{.} name}
|
|
\end{Produc}
|
|
The statement
|
|
\begin{verbatim}
|
|
function f (...)
|
|
...
|
|
end
|
|
\end{verbatim}
|
|
is just syntactic sugar for
|
|
\begin{verbatim}
|
|
f = function (...)
|
|
...
|
|
end
|
|
\end{verbatim}
|
|
|
|
A function definition is an executable expression,
|
|
whose value has type \emph{function}.
|
|
When Lua pre-compiles a chunk,
|
|
all its function bodies are pre-compiled, too.
|
|
Then, whenever Lua executes the function definition,
|
|
its upvalues are fixed \see{upvalue},
|
|
and the function is \emph{instantiated} (or ``closed'').
|
|
This function instance (or ``closure'')
|
|
is the final value of the expression.
|
|
Different instances of a same function
|
|
may have different upvalues.
|
|
|
|
Parameters act as local variables,
|
|
initialized with the argument values:
|
|
\begin{Produc}
|
|
\produc{parlist1}{\ter{\ldots}}
|
|
\produc{parlist1}{name \rep{\ter{,} name} \opt{\ter{,} \ter{\ldots}}}
|
|
\end{Produc}
|
|
\label{vararg}
|
|
When a function is called,
|
|
the list of \Index{arguments} is adjusted to
|
|
the length of the list of parameters \see{adjust},
|
|
unless the function is a \Def{vararg} function,
|
|
indicated by the dots (\ldots) at the end of its parameter list.
|
|
A vararg function does not adjust its argument list;
|
|
instead, it collects any extra arguments into an implicit parameter,
|
|
called \IndexVerb{arg}.
|
|
This parameter is always initialized as a table,
|
|
with a field \verb|n| whose value is the number of extra arguments,
|
|
and the extra arguments at positions 1,~2,~\ldots
|
|
|
|
As an example, suppose definitions like:
|
|
\begin{verbatim}
|
|
function f(a, b) end
|
|
function g(a, b, ...) end
|
|
\end{verbatim}
|
|
Then, we have the following mapping from arguments to parameters:
|
|
\begin{verbatim}
|
|
CALL PARAMETERS
|
|
|
|
f(3) a=3, b=nil
|
|
f(3, 4) a=3, b=4
|
|
f(3, 4, 5) a=3, b=4
|
|
|
|
g(3) a=3, b=nil, arg={n=0}
|
|
g(3, 4) a=3, b=4, arg={n=0}
|
|
g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2}
|
|
\end{verbatim}
|
|
|
|
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 implicit extra parameter \IndexVerb{self}:
|
|
\begin{Produc}
|
|
\produc{function}{\rwd{function} name \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}
|
|
v.f = function (self, ...)
|
|
...
|
|
end
|
|
\end{verbatim}
|
|
that is, the function gets an extra formal parameter called \verb|self|.
|
|
Note that the variable \verb|v| must have been
|
|
previously initialized with a table value.
|
|
|
|
|
|
\subsection{Visibility and Upvalues} \label{upvalue}
|
|
\index{Visibility} \index{Upvalues}
|
|
|
|
A function body may refer to its own local variables
|
|
(which includes its parameters) and to global variables,
|
|
as long as they are not shadowed by local
|
|
variables from enclosing functions.
|
|
A function \emph{cannot} access a local
|
|
variable from an enclosing function,
|
|
since such variables may no longer exist when the function is called.
|
|
However, a function may access the \emph{value} of a local variable
|
|
from an enclosing function, using \emph{upvalues}.
|
|
|
|
\begin{Produc}
|
|
\produc{upvalue}{\ter{\%} name}
|
|
\end{Produc}
|
|
An upvalue is somewhat similar to a variable expression,
|
|
but whose value is frozen when the function wherein it
|
|
appears is instantiated.
|
|
The name used in an upvalue may be the name of any variable visible
|
|
at the point where the function is defined.
|
|
|
|
Here are some examples:
|
|
\begin{verbatim}
|
|
a,b,c = 1,2,3 -- global variables
|
|
function f (x)
|
|
local b -- x and b are local to f
|
|
local g = function (a)
|
|
local y -- a and y are local to g
|
|
p = a -- OK, access local 'a'
|
|
p = c -- OK, access global 'c'
|
|
p = b -- ERROR: cannot access a variable in outer scope
|
|
p = %b -- OK, access frozen value of 'b' (local to 'f')
|
|
p = %c -- OK, access frozen value of global 'c'
|
|
p = %y -- ERROR: 'y' is not visible where 'g' is defined
|
|
end -- g
|
|
end -- f
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Tag Methods} \label{tag-method}
|
|
|
|
Lua provides a powerful mechanism to extend its semantics,
|
|
called \Def{tag methods}.
|
|
A tag method is a programmer-defined function
|
|
that is called at specific key points during the evaluation of a program,
|
|
allowing the programmer to change the standard Lua behavior at these points.
|
|
Each of these points is called an \Def{event}.
|
|
|
|
The tag method called for any specific event is selected
|
|
according to the tag of the values involved
|
|
in the event \see{TypesSec}.
|
|
The function \IndexVerb{settagmethod} changes the tag method
|
|
associated with a given pair \M{(tag, event)}.
|
|
Its first parameter is the tag, the second parameter is the event name
|
|
(a string; see below),
|
|
and the third parameter is the new method (a function),
|
|
or \nil\ to restore the default behavior for the pair.
|
|
The function returns the previous tag method for that pair.
|
|
Another function, \IndexVerb{gettagmethod},
|
|
receives a tag and an event name and returns the
|
|
current method associated with the pair.
|
|
|
|
Tag methods are called in the following events,
|
|
identified by the given names.
|
|
The semantics of tag methods is better explained by a Lua function
|
|
describing the behavior of the interpreter at each event.
|
|
The function not only shows when a tag method is called,
|
|
but also its arguments, its results and the default behavior.
|
|
Please notice that the code shown here is only illustrative;
|
|
the real behavior is hard coded in the interpreter,
|
|
and it is much more efficient than this simulation.
|
|
All functions used in these descriptions
|
|
(\verb|rawgetglobal|, \verb|tonumber|, \verb|call|, etc.)
|
|
are described in \See{predefined}.
|
|
|
|
\begin{description}
|
|
|
|
\item[``add'':]\index{add event}
|
|
called when a \verb|+| operation is applied to non numerical operands.
|
|
|
|
The function \verb|getbinmethod| defines how Lua chooses a tag method
|
|
for a binary operation.
|
|
First, Lua tries the first operand.
|
|
If its tag does not define a tag method for the operation,
|
|
then Lua tries the second operand.
|
|
If it also fails, then it gets a tag method from tag~0:
|
|
\begin{verbatim}
|
|
function getbinmethod (op1, op2, event)
|
|
return gettagmethod(tag(op1), event) or
|
|
gettagmethod(tag(op2), event) or
|
|
gettagmethod(0, event)
|
|
end
|
|
\end{verbatim}
|
|
\begin{verbatim}
|
|
function add_event (op1, op2)
|
|
local o1, o2 = tonumber(op1), tonumber(op2)
|
|
if o1 and o2 then -- both operands are numeric
|
|
return o1+o2 -- '+' here is the primitive 'add'
|
|
else -- at least one of the operands is not numeric
|
|
local tm = getbinmethod(op1, op2, "add")
|
|
if tm then
|
|
-- call the method with both operands and an extra
|
|
-- argument with the event name
|
|
return tm(op1, op2, "add")
|
|
else -- no tag method available: default behavior
|
|
error("unexpected type at arithmetic operation")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``sub'':]\index{sub event}
|
|
called when a \verb|-| operation is applied to non numerical operands.
|
|
Behavior similar to the \verb|"add"| event.
|
|
|
|
\item[``mul'':]\index{mul event}
|
|
called when a \verb|*| operation is applied to non numerical operands.
|
|
Behavior similar to the \verb|"add"| event.
|
|
|
|
\item[``div'':]\index{div event}
|
|
called when a \verb|/| operation is applied to non numerical operands.
|
|
Behavior similar to the \verb|"add"| event.
|
|
|
|
\item[``pow'':]\index{pow event}
|
|
called when a \verb|^| operation is applied.
|
|
\begin{verbatim}
|
|
function pow_event (op1, op2)
|
|
local tm = getbinmethod(op1, op2, "pow")
|
|
if tm then
|
|
-- call the method with both operands and an extra
|
|
-- argument with the event name
|
|
return tm(op1, op2, "pow")
|
|
else -- no tag method available: default behavior
|
|
error("unexpected type at arithmetic operation")
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``unm'':]\index{unm event}
|
|
called when an unary \verb|-| operation is applied to a non numerical operand.
|
|
\begin{verbatim}
|
|
function unm_event (op)
|
|
local o = tonumber(op)
|
|
if o then -- operand is numeric
|
|
return -o -- '-' here is the primitive 'unm'
|
|
else -- the operand is not numeric.
|
|
-- Try to get a tag method from the operand;
|
|
-- if it does not have one, try a "global" one (tag 0)
|
|
local tm = gettagmethod(tag(op), "unm") or
|
|
gettagmethod(0, "unm")
|
|
if tm then
|
|
-- call the method with the operand, nil, and an extra
|
|
-- argument with the event name
|
|
return tm(op, nil, "unm")
|
|
else -- no tag method available: default behavior
|
|
error("unexpected type at arithmetic operation")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``lt'':]\index{lt event}
|
|
called when a \verb|<| operation is applied to non numerical
|
|
or non string operands.
|
|
\begin{verbatim}
|
|
function lt_event (op1, op2)
|
|
if type(op1) == "number" and type(op2) == "number" then
|
|
return op1 < op2 -- numeric comparison
|
|
elseif type(op1) == "string" and type(op2) == "string" then
|
|
return op1 < op2 -- lexicographic comparison
|
|
else
|
|
local tm = getbinmethod(op1, op2, "lt")
|
|
if tm then
|
|
return tm(op1, op2, "lt")
|
|
else
|
|
error("unexpected type at comparison");
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``gt'':]\index{gt event}
|
|
called when a \verb|>| operation is applied to non numerical
|
|
or non string operands.
|
|
Behavior similar to the \verb|"lt"| event.
|
|
|
|
\item[``le'':]\index{le event}
|
|
called when a \verb|<=| operation is applied to non numerical
|
|
or non string operands.
|
|
Behavior similar to the \verb|"lt"| event.
|
|
|
|
\item[``ge'':]\index{ge event}
|
|
called when a \verb|>=| operation is applied to non numerical
|
|
or non string operands.
|
|
Behavior similar to the \verb|"lt"| event.
|
|
|
|
\item[``concat'':]\index{concatenation event}
|
|
called when a concatenation is applied to non string operands.
|
|
\begin{verbatim}
|
|
function concat_event (op1, op2)
|
|
if (type(op1) == "string" or type(op1) == "number") and
|
|
(type(op2) == "string" or type(op2) == "number") then
|
|
return op1..op2 -- primitive string concatenation
|
|
else
|
|
local tm = getbinmethod(op1, op2, "concat")
|
|
if tm then
|
|
return tm(op1, op2, "concat")
|
|
else
|
|
error("unexpected type for concatenation")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``index'':]\index{index event}
|
|
called when Lua tries to retrieve the value of an index
|
|
not present in a table.
|
|
See event \verb|"gettable"| for its semantics.
|
|
|
|
\item[``getglobal'':]\index{getglobal event}
|
|
called whenever Lua needs the value of a global variable.
|
|
This method can only be set for \nil\ and for tags
|
|
created by \verb|newtag|.
|
|
\begin{verbatim}
|
|
function getglobal (varname)
|
|
local value = rawgetglobal(varname)
|
|
local tm = gettagmethod(tag(value), "getglobal")
|
|
if not tm then
|
|
return value
|
|
else
|
|
return tm(varname, value)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
The function \verb|getglobal| is pre-defined in Lua \see{predefined}.
|
|
|
|
\item[``setglobal'':]\index{setglobal event}
|
|
called whenever Lua assigns to a global variable.
|
|
This method cannot be set for numbers, strings, and tables and
|
|
userdata with default tags.
|
|
\begin{verbatim}
|
|
function setglobal (varname, newvalue)
|
|
local oldvalue = rawgetglobal(varname)
|
|
local tm = gettagmethod(tag(oldvalue), "setglobal")
|
|
if not tm then
|
|
return rawsetglobal(varname, newvalue)
|
|
else
|
|
return tm(varname, oldvalue, newvalue)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
Notice: the function \verb|setglobal| is pre-defined in Lua \see{predefined}.
|
|
|
|
\item[``gettable'':]\index{gettable event}
|
|
called whenever Lua accesses an indexed variable.
|
|
This method cannot be set for tables with default tag.
|
|
\begin{verbatim}
|
|
function gettable_event (table, index)
|
|
local tm = gettagmethod(tag(table), "gettable")
|
|
if tm then
|
|
return tm(table, index)
|
|
elseif type(table) ~= "table" then
|
|
error("indexed expression not a table");
|
|
else
|
|
local v = rawgettable(table, index)
|
|
tm = gettagmethod(tag(table), "index")
|
|
if v == nil and tm then
|
|
return tm(table, index)
|
|
else
|
|
return v
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``settable'':]\index{settable event}
|
|
called when Lua assigns to an indexed variable.
|
|
This method cannot be set for tables with default tag.
|
|
\begin{verbatim}
|
|
function settable_event (table, index, value)
|
|
local tm = gettagmethod(tag(table), "settable")
|
|
if tm then
|
|
tm(table, index, value)
|
|
elseif type(table) ~= "table" then
|
|
error("indexed expression not a table")
|
|
else
|
|
rawsettable(table, index, value)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``function'':]\index{function event}
|
|
called when Lua tries to call a non function value.
|
|
\begin{verbatim}
|
|
function function_event (func, ...)
|
|
if type(func) == "function" then
|
|
return call(func, arg)
|
|
else
|
|
local tm = gettagmethod(tag(func), "function")
|
|
if tm then
|
|
local i = arg.n
|
|
while i > 0 do
|
|
arg[i+1] = arg[i]
|
|
i = i-1
|
|
end
|
|
arg.n = arg.n+1
|
|
arg[1] = func
|
|
return call(tm, arg)
|
|
else
|
|
error("call expression not a function")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``gc'':]\index{gc event}
|
|
called when Lua is ``garbage collecting'' an object.
|
|
This method cannot be set for strings, numbers, functions,
|
|
and userdata with default tag.
|
|
For each object to be collected,
|
|
Lua does the equivalent of the following function:
|
|
\begin{verbatim}
|
|
function gc_event (obj)
|
|
local tm = gettagmethod(tag(obj), "gc")
|
|
if tm then
|
|
tm(obj)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
Moreover, at the end of a garbage collection cycle,
|
|
Lua does the equivalent of the call \verb|gc_event(nil)|.
|
|
|
|
\end{description}
|
|
|
|
|
|
|
|
\subsection{Error Handling} \label{error}
|
|
|
|
Because Lua is an extension language,
|
|
all Lua actions start from C code in the host program
|
|
calling a function from the Lua library.
|
|
Whenever an error occurs during Lua compilation or execution,
|
|
function \verb|_ERRORMESSAGE| is called \Deffunc{_ERRORMESSAGE}
|
|
(provided it is different from \nil),
|
|
and then the corresponding function from the library
|
|
(\verb|lua_dofile|, \verb|lua_dostring|,
|
|
\verb|lua_dobuffer|, or \verb|lua_callfunction|)
|
|
is terminated, returning an error condition.
|
|
|
|
The only argument to \verb|_ERRORMESSAGE| is a string
|
|
describing the error.
|
|
The default definition for this function calls \verb|_ALERT|,
|
|
which prints the message to \verb|stderr| \see{alert}.
|
|
The standard I/O library redefines \verb|_ERRORMESSAGE|,
|
|
and uses the debug facilities \see{debugI}
|
|
to print some extra information,
|
|
such as the call stack.
|
|
|
|
To provide more information about errors,
|
|
Lua programs should include the compilation pragma \verb|$debug|.
|
|
\index{debug pragma}\label{pragma}
|
|
When an error occurs in a chunk compiled with this option,
|
|
the I/O error routine is able to print the number of the
|
|
lines where the calls (and the error) were made.
|
|
|
|
Lua code can explicitly generate an error by calling the built-in
|
|
function \verb|error| \see{pdf-error}.
|
|
Lua code can ``catch'' an error using the built-in function
|
|
\verb|call| \see{pdf-call}.
|
|
|
|
|
|
|
|
\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 Lua library.
|
|
The API functions can be classified in the following categories:
|
|
\begin{enumerate}
|
|
\item managing states;
|
|
\item exchanging values between C and Lua;
|
|
\item executing Lua code;
|
|
\item manipulating (reading and writing) Lua objects;
|
|
\item calling Lua functions;
|
|
\item C functions to be called by Lua;
|
|
\item manipulating references to Lua Objects.
|
|
\end{enumerate}
|
|
All API functions and related types and constants
|
|
are declared in the header file \verb|lua.h|.
|
|
|
|
\subsection{Managing States} \label{mangstate}
|
|
The whole state of the Lua interpreter
|
|
(global variables, stack, tag methods, etc)
|
|
is stored in a dynamic structure pointed by\Deffunc{lua_state}
|
|
\begin{verbatim}
|
|
typedef struct lua_State lua_State;
|
|
extern lua_State *lua_state;
|
|
\end{verbatim}
|
|
The variable \verb|lua_state| is the only C global variable in
|
|
the Lua library.
|
|
|
|
Before calling any API function,
|
|
this state must be initialized.
|
|
This is done by calling\Deffunc{lua_open}
|
|
\begin{verbatim}
|
|
void lua_open (void);
|
|
\end{verbatim}
|
|
This function allocates and initializes some internal structures,
|
|
and defines all pre-defined functions of Lua.
|
|
If \verb|lua_state| is already different from \verb|NULL|,
|
|
\verb|lua_open| has no effect;
|
|
therefore, it is safe to call this function multiple times.
|
|
All standard libraries call \verb|lua_open| when they are opened.
|
|
|
|
Function \verb|lua_setstate| is used to change the current state
|
|
of Lua:\Deffunc{lua_setstate}
|
|
\begin{verbatim}
|
|
lua_State *lua_setstate (lua_State *st);
|
|
\end{verbatim}
|
|
It sets \verb|lua_state| to \verb|st| and returns the old state.
|
|
|
|
Multiple, independent states may be created.
|
|
For that, you must set \verb|lua_state| back to \verb|NULL| before
|
|
calling \verb|lua_open|.
|
|
An easy way to do that is defining an auxiliary function:
|
|
\begin{verbatim}
|
|
lua_State *lua_newstate (void) {
|
|
lua_State *old = lua_setstate(NULL);
|
|
lua_open();
|
|
return lua_setstate(old);
|
|
}
|
|
\end{verbatim}
|
|
This function creates a new state without changing the current state
|
|
of the interpreter.
|
|
Note that any new state is created with all predefined functions,
|
|
but any additional library (such as the standard libraries) must be
|
|
explicitly open in the new state, if needed.
|
|
|
|
If necessary, a state may be released by calling\Deffunc{lua_close}
|
|
\begin{verbatim}
|
|
void lua_close (void);
|
|
\end{verbatim}
|
|
This function destroys all objects in the current Lua environment
|
|
(calling the correspondent garbage collector tag methods),
|
|
frees all dynamic memory used by the state,
|
|
and then sets \verb|lua_state| to \verb|NULL|.
|
|
Usually, there is no need to call this function,
|
|
since these resources are naturally released when the program ends.
|
|
If \verb|lua_state| is already \verb|NULL|,
|
|
\verb|lua_close| has no effect.
|
|
|
|
If you are using multiple states,
|
|
you may find useful to define the following function,
|
|
which releases a given state:
|
|
\begin{verbatim}
|
|
void lua_freestate (lua_State *st) {
|
|
lua_State *old = lua_setstate(st);
|
|
lua_close();
|
|
if (old != st) lua_setstate(old);
|
|
}
|
|
\end{verbatim}
|
|
|
|
\subsection{Exchanging 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 comparison of two \verb|lua_Object's| is undefined.
|
|
|
|
To check the type of a \verb|lua_Object|,
|
|
the following functions are available:
|
|
\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}
|
|
These functions return 1 if the object is compatible with the given type,
|
|
and 0 otherwise.
|
|
The function \verb|lua_isnumber| accepts numbers and numerical strings,
|
|
whereas
|
|
\verb|lua_isstring| accepts strings and numbers \see{coercion},
|
|
and \verb|lua_isfunction| accepts Lua functions and C functions.
|
|
|
|
To get the tag of a \verb|lua_Object|,
|
|
the following function is available:
|
|
\Deffunc{lua_tag}
|
|
\begin{verbatim}
|
|
int lua_tag (lua_Object object);
|
|
\end{verbatim}
|
|
|
|
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_strlen}
|
|
\Deffunc{lua_getcfunction}\Deffunc{lua_getuserdata}
|
|
\begin{verbatim}
|
|
double lua_getnumber (lua_Object object);
|
|
char *lua_getstring (lua_Object object);
|
|
long lua_strlen (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 floating-point number.
|
|
This \verb|lua_Object| must be a number or a string convertible to number
|
|
\see{coercion}; otherwise, \verb|lua_getnumber| 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 \verb|NULL| pointer).
|
|
This function does not create a new string,
|
|
but returns a pointer to a string inside the Lua environment.
|
|
Those strings always have a 0 after their last character (like in C),
|
|
but may contain other zeros in their body.
|
|
If you do not know whether a string may contain zeros,
|
|
you can use \verb|lua_strlen| to get the actual length.
|
|
Because Lua has garbage collection,
|
|
there is no guarantee that the pointer returned by \verb|lua_getstring|
|
|
will be valid after the block ends
|
|
\see{GC}.
|
|
|
|
\verb|lua_getcfunction| converts a \verb|lua_Object| to a C function.
|
|
This \verb|lua_Object| must have type \emph{CFunction};
|
|
otherwise, \verb|lua_getcfunction| returns 0 (the \verb|NULL| pointer).
|
|
The type \verb|lua_CFunction| is explained in \See{LuacallC}.
|
|
|
|
\verb|lua_getuserdata| converts a \verb|lua_Object| to \verb|void*|.
|
|
This \verb|lua_Object| must have type \emph{userdata};
|
|
otherwise, \verb|lua_getuserdata| returns 0 (the \verb|NULL| pointer).
|
|
|
|
\subsection{Garbage Collection}\label{GC}
|
|
Because Lua has automatic memory management and garbage collection,
|
|
a \verb|lua_Object| has a limited scope,
|
|
and is only valid inside the \emph{block} where it has been created.
|
|
A C function called from Lua is a block,
|
|
and its parameters are valid only until its end.
|
|
It is good programming practice 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.
|
|
|
|
A garbage collection cycle can be forced by:
|
|
\Deffunc{lua_collectgarbage}
|
|
\begin{verbatim}
|
|
long lua_collectgarbage (long limit);
|
|
\end{verbatim}
|
|
This function returns the number of objects collected.
|
|
The argument \verb|limit| makes the next cycle occur only
|
|
after that number of new objects have been created.
|
|
If \verb|limit|=0, then Lua uses an adaptive heuristics to set this limit.
|
|
|
|
|
|
All communication between Lua and C is done through two
|
|
abstract data types, called \Def{lua2C} and \Def{C2lua}.
|
|
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.
|
|
The structure C2lua is used in the reverse direction:
|
|
parameters when C calls Lua and results when Lua calls C.
|
|
|
|
The structure lua2C is an abstract array,
|
|
which can be indexed with the function:
|
|
\Deffunc{lua_lua2C}
|
|
\begin{verbatim}
|
|
lua_Object lua_lua2C (int number);
|
|
\end{verbatim}
|
|
where \verb|number| starts with 1.
|
|
When called with a number larger than the array size,
|
|
this function returns \verb|LUA_NOOBJECT|\Deffunc{LUA_NOOBJECT}.
|
|
In this way, it is possible to write C functions that receive
|
|
a variable number of parameters,
|
|
and to call Lua functions that return a variable number of results.
|
|
Note that the structure lua2C cannot be directly modified by C code.
|
|
|
|
The second structure, C2lua, is an abstract stack.
|
|
Pushing elements into this stack
|
|
is done with the following functions:
|
|
\Deffunc{lua_pushnumber}\Deffunc{lua_pushlstring}\Deffunc{lua_pushstring}
|
|
\Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag}
|
|
\Deffunc{lua_pushnil}\Deffunc{lua_pushobject}
|
|
\Deffunc{lua_pushuserdata}\label{pushing}
|
|
\begin{verbatim}
|
|
void lua_pushnumber (double n);
|
|
void lua_pushlstring (char *s, long len);
|
|
void lua_pushstring (char *s);
|
|
void lua_pushusertag (void *u, int tag);
|
|
void lua_pushnil (void);
|
|
void lua_pushobject (lua_Object object);
|
|
void lua_pushcfunction (lua_CFunction f); /* macro */
|
|
\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 C2lua.
|
|
In particular, functions \verb|lua_pushlstring| and \verb|lua_pushstring|
|
|
make an internal copy of the given string.
|
|
Function \verb|lua_pushstring| can only be used to push proper C strings
|
|
(that is, strings that do not contain zeros and end with a zero);
|
|
otherwise you should use the more generic \verb|lua_pushlstring|.
|
|
The function
|
|
\Deffunc{lua_pop}
|
|
\begin{verbatim}
|
|
lua_Object lua_pop (void);
|
|
\end{verbatim}
|
|
returns a reference to the object at the top of the C2lua stack,
|
|
and pops it.
|
|
|
|
As a general rule, all API functions pop from the stack
|
|
all elements they use.
|
|
|
|
Because userdata are objects,
|
|
the function \verb|lua_pushusertag| may create a new userdata.
|
|
If Lua has a userdata with the given value (\verb|void*|) and tag,
|
|
that userdata is pushed.
|
|
Otherwise, a new userdata is created, with the given value and tag.
|
|
If this function is called with
|
|
\verb|tag| equal to \verb|LUA_ANYTAG|\Deffunc{LUA_ANYTAG},
|
|
then Lua will try to find any userdata with the given value,
|
|
regardless of its tag.
|
|
If there is no userdata with that value, then a new one is created,
|
|
with tag equal to 0.
|
|
|
|
Userdata can have different tags,
|
|
whose semantics are only known to the host program.
|
|
Tags are created with the function:
|
|
\Deffunc{lua_newtag}
|
|
\begin{verbatim}
|
|
int lua_newtag (void);
|
|
\end{verbatim}
|
|
The function \verb|lua_settag| changes the tag of
|
|
the object on the top of C2lua (and pops it);
|
|
the object must be a userdata or a table.
|
|
\Deffunc{lua_settag}
|
|
\begin{verbatim}
|
|
void lua_settag (int tag);
|
|
\end{verbatim}
|
|
\verb|tag| must be a value created with \verb|lua_newtag|.
|
|
|
|
When C code calls Lua repeatedly, as in a loop,
|
|
objects returned by these calls can accumulate,
|
|
and may cause a stack overflow.
|
|
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.
|
|
The use of explicit nested blocks is good programming practice
|
|
and is strongly encouraged.
|
|
|
|
\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}\Deffunc{lua_dobuffer}
|
|
\begin{verbatim}
|
|
int lua_dofile (char *filename);
|
|
int lua_dostring (char *string);
|
|
int lua_dobuffer (char *buff, int size, char *name);
|
|
\end{verbatim}
|
|
All these 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.
|
|
When called with argument \verb|NULL|,
|
|
\verb|lua_dofile| executes the \verb|stdin| stream.
|
|
Functions \verb|lua_dofile| and \verb|lua_dobuffer|
|
|
are both able to execute pre-compiled chunks.
|
|
They automatically detect whether the chunk is text or binary,
|
|
and load it accordingly (see program \IndexVerb{luac}).
|
|
Function \verb|lua_dostring| executes only source code.
|
|
|
|
The third parameter to \verb|lua_dobuffer| (\verb|name|)
|
|
is the ``name of the chunk'',
|
|
used in error messages and debug information.
|
|
If \verb|name| is \verb|NULL|,
|
|
Lua gives a default name to the chunk.
|
|
|
|
These functions return, in structure lua2C,
|
|
any values eventually returned by the chunks.
|
|
They also empty the stack C2lua.
|
|
|
|
|
|
\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, this function may trigger a tag method.
|
|
To read the real value of any global variable,
|
|
without invoking any tag method,
|
|
use the \emph{raw} version:
|
|
\Deffunc{lua_rawgetglobal}
|
|
\begin{verbatim}
|
|
lua_Object lua_rawgetglobal (char *varname);
|
|
\end{verbatim}
|
|
|
|
To store a value previously pushed onto C2lua in a global variable,
|
|
there is the function:
|
|
\Deffunc{lua_setglobal}
|
|
\begin{verbatim}
|
|
void lua_setglobal (char *varname);
|
|
\end{verbatim}
|
|
As in Lua, this function may trigger a tag method.
|
|
To set the real value of any global variable,
|
|
without invoking any tag method,
|
|
use the \emph{raw} version:
|
|
\Deffunc{lua_rawgetglobal}
|
|
\begin{verbatim}
|
|
void lua_rawsetglobal (char *varname);
|
|
\end{verbatim}
|
|
|
|
Tables can also be manipulated via the API.
|
|
The function
|
|
\Deffunc{lua_gettable}
|
|
\begin{verbatim}
|
|
lua_Object lua_gettable (void);
|
|
\end{verbatim}
|
|
pops a table and an index from the stack C2lua,
|
|
and returns the contents of the table at that index.
|
|
As in Lua, this operation may trigger a tag method.
|
|
To get the real value of any table index,
|
|
without invoking any tag method,
|
|
use the \emph{raw} version:
|
|
\Deffunc{lua_rawgetglobal}
|
|
\begin{verbatim}
|
|
lua_Object lua_rawgettable (void);
|
|
\end{verbatim}
|
|
|
|
To store a value in an index,
|
|
the program must push the table, the index,
|
|
and the value onto C2lua,
|
|
and then call the function
|
|
\Deffunc{lua_settable}
|
|
\begin{verbatim}
|
|
void lua_settable (void);
|
|
\end{verbatim}
|
|
Again, the tag method for ``settable'' may be called.
|
|
To set the real value of any table index,
|
|
without invoking any tag method,
|
|
use the \emph{raw} version:
|
|
\Deffunc{lua_rawsettable}
|
|
\begin{verbatim}
|
|
void lua_rawsettable (void);
|
|
\end{verbatim}
|
|
|
|
Finally, the function
|
|
\Deffunc{lua_createtable}
|
|
\begin{verbatim}
|
|
lua_Object lua_createtable (void);
|
|
\end{verbatim}
|
|
creates and returns a new, empty table.
|
|
|
|
|
|
\subsection{Calling Lua Functions}
|
|
Functions defined in Lua by a chunk
|
|
can be called from the host program.
|
|
This is done using the following protocol:
|
|
first, the arguments to the function are pushed onto C2lua
|
|
\see{pushing}, in direct order, i.e., the first argument is pushed first.
|
|
Then, the function is called using
|
|
\Deffunc{lua_callfunction}
|
|
\begin{verbatim}
|
|
int lua_callfunction (lua_Object function);
|
|
\end{verbatim}
|
|
This function returns an error code:
|
|
0, in case of success; non zero, in case of errors.
|
|
Finally, the results (a Lua function may return many values)
|
|
are returned in structure lua2C,
|
|
and can be retrieved with the macro \verb|lua_getresult|,
|
|
\Deffunc{lua_getresult}
|
|
which is just another name to function \verb|lua_lua2C|.
|
|
Note that function \verb|lua_callfunction|
|
|
pops all elements from the C2lua stack.
|
|
|
|
The following example shows how a C program may do the
|
|
equivalent to the Lua code:
|
|
\begin{verbatim}
|
|
a,b = f("how", t.x, 4)
|
|
\end{verbatim}
|
|
\begin{verbatim}
|
|
lua_pushstring("how"); /* 1st argument */
|
|
lua_pushobject(lua_getglobal("t")); /* push value of global 't' */
|
|
lua_pushstring("x"); /* push the string 'x' */
|
|
lua_pushobject(lua_gettable()); /* push result of t.x (2nd arg) */
|
|
lua_pushnumber(4); /* 3rd argument */
|
|
lua_callfunction(lua_getglobal("f")); /* call Lua function */
|
|
lua_pushobject(lua_getresult(1)); /* push first result of the call */
|
|
lua_setglobal("a"); /* set global variable 'a' */
|
|
lua_pushobject(lua_getresult(2)); /* push second result of the call */
|
|
lua_setglobal("b"); /* set global variable 'b' */
|
|
\end{verbatim}
|
|
|
|
Some special Lua functions have exclusive interfaces.
|
|
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,
|
|
then the corresponding Lua execution terminates,
|
|
as if an error had occurred inside Lua code.
|
|
Otherwise, the whole host program terminates with a call to \verb|exit(1)|.
|
|
The \verb|message| is passed to the error handler function,
|
|
\verb|_ERRORMESSAGE|.
|
|
If \verb|message| is \verb|NULL|,
|
|
then \verb|_ERRORMESSAGE| is not called.
|
|
|
|
Tag methods can be changed with: \Deffunc{lua_settagmethod}
|
|
\begin{verbatim}
|
|
lua_Object lua_settagmethod (int tag, char *event);
|
|
\end{verbatim}
|
|
The first parameter is the tag,
|
|
and the second is the event name \see{tag-method};
|
|
the new method is pushed from C2lua.
|
|
This function returns a \verb|lua_Object|,
|
|
which is the old tag method value.
|
|
To get just the current value of a tag method,
|
|
use the function \Deffunc{lua_gettagmethod}
|
|
\begin{verbatim}
|
|
lua_Object lua_gettagmethod (int tag, char *event);
|
|
\end{verbatim}
|
|
|
|
It is also possible to copy all tag methods from one tag
|
|
to another: \Deffunc{lua_copytagmethods}
|
|
\begin{verbatim}
|
|
int lua_copytagmethods (int tagto, int tagfrom);
|
|
\end{verbatim}
|
|
This function returns \verb|tagto|.
|
|
|
|
|
|
\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_setglobal(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.
|
|
|
|
A C function receives its arguments in structure lua2C;
|
|
to access them, it uses the macro \verb|lua_getparam|, \Deffunc{lua_getparam}
|
|
again just another name for \verb|lua_lua2C|.
|
|
To return values, a C function just pushes them onto the stack C2lua,
|
|
in direct order \see{valuesCLua}.
|
|
Like a Lua function, a C function called by Lua can also return
|
|
many results.
|
|
|
|
When a C function is created,
|
|
it is possible to associate some \emph{upvalues} to it,
|
|
thus creating a C closure;
|
|
then these values are passed to the function whenever it is called,
|
|
as common arguments.
|
|
To associate upvalues to a function,
|
|
first these values must be pushed on C2lua.
|
|
Then the function
|
|
\Deffunc{lua_pushcclosure}
|
|
\begin{verbatim}
|
|
void lua_pushcclosure (lua_CFunction fn, int n);
|
|
\end{verbatim}
|
|
is used to put the C function on C2lua,
|
|
with the argument \verb|n| telling how many upvalues must be
|
|
associated with the function;
|
|
in fact, the macro \verb|lua_pushcfunction| is defined as
|
|
\verb|lua_pushcclosure| with \verb|n| set to 0.
|
|
Then, any time the function is called,
|
|
these upvalues are inserted as the first arguments to the function,
|
|
before the actual arguments provided in the call.
|
|
|
|
For some examples of C functions, see files \verb|lstrlib.c|,
|
|
\verb|liolib.c| and \verb|lmathlib.c| in the official Lua distribution.
|
|
|
|
\subsection{References to Lua Objects}
|
|
|
|
As noted in \See{GC}, \verb|lua_Object|s are volatile.
|
|
If the C code needs to keep a \verb|lua_Object|
|
|
outside block boundaries,
|
|
then it must create a \Def{reference} to the object.
|
|
The routines to manipulate references are the following:
|
|
\Deffunc{lua_ref}\Deffunc{lua_getref}
|
|
\Deffunc{lua_unref}
|
|
\begin{verbatim}
|
|
int lua_ref (int lock);
|
|
lua_Object lua_getref (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 \emph{locked}:
|
|
this means the object will not be garbage collected.
|
|
Note 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;
|
|
if the object has been collected,
|
|
\verb|lua_getref| returns \verb|LUA_NOOBJECT|.
|
|
|
|
When a reference is no longer needed,
|
|
it can be released 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 allow 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 separate C modules.
|
|
Currently, there are three standard libraries:
|
|
\begin{itemize}
|
|
\item string manipulation;
|
|
\item mathematical functions (sin, log, etc);
|
|
\item input and output (plus some system facilities).
|
|
\end{itemize}
|
|
To have access to these libraries,
|
|
the C host program must call the functions
|
|
\verb|lua_strlibopen|, \verb|lua_mathlibopen|,
|
|
and \verb|lua_iolibopen|, declared in \verb|lualib.h|.
|
|
\Deffunc{lua_strlibopen}\Deffunc{lua_mathlibopen}\Deffunc{lua_iolibopen}
|
|
|
|
|
|
\subsection{Predefined Functions} \label{predefined}
|
|
|
|
\subsubsection*{\ff \T{call (func, arg [, mode [, errhandler]])}}\Deffunc{call}
|
|
\label{pdf-call}
|
|
Calls function \verb|func| with
|
|
the arguments given by the table \verb|arg|.
|
|
The call is equivalent to
|
|
\begin{verbatim}
|
|
func(arg[1], arg[2], ..., arg[n])
|
|
\end{verbatim}
|
|
where \verb|n| is the result of \verb|getn(arg)| \see{getn}.
|
|
|
|
By default,
|
|
all results from \verb|func| are just returned by the call.
|
|
If the string \verb|mode| contains \verb|"p"|,
|
|
the results are \emph{packed} in a single table.\index{packed results}
|
|
That is, \verb|call| returns just one table;
|
|
at index \verb|n|, the table has the total number of results
|
|
from the call;
|
|
the first result is at index 1, etc.
|
|
For instance, the following calls produce the following results:
|
|
\begin{verbatim}
|
|
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}, "p") --> a = {4; n=1}
|
|
t = {x=1}
|
|
a = call(next, {t,nil;n=2}, "p") --> a={"x", 1; n=2}
|
|
\end{verbatim}
|
|
|
|
By default,
|
|
if an error occurs during the function call,
|
|
the error is propagated.
|
|
If the string \verb|mode| contains \verb|"x"|,
|
|
then the call is \emph{protected}.\index{protected calls}
|
|
In this mode, function \verb|call| does not propagate an error,
|
|
regardless of what happens during the call.
|
|
Instead, it returns \nil\ to signal the error
|
|
(besides calling the appropriated error handler).
|
|
|
|
If provided,
|
|
\verb|errhandler| is temporarily set as the error function
|
|
\verb|_ERRORMESSAGE|, while \verb|func| runs.
|
|
In particular, if \verb|errhandler| is \nil,
|
|
no error messages will be issued during the execution of the called function.
|
|
|
|
\subsubsection*{\ff \T{collectgarbage ([limit])}}\Deffunc{collectgarbage}
|
|
Forces a garbage collection cycle.
|
|
Returns the number of objects collected.
|
|
An optional argument, \verb|limit|, is a number that
|
|
makes the next cycle occur only after that number of new
|
|
objects have been created.
|
|
If \verb|limit| is absent or equal to 0,
|
|
Lua uses an adaptive algorithm to set this limit.
|
|
\verb|collectgarbage| is equivalent to
|
|
the API function \verb|lua_collectgarbage|.
|
|
|
|
\subsubsection*{\ff \T{dofile (filename)}}\Deffunc{dofile}
|
|
Receives a file name,
|
|
opens the file, and executes the file contents as a Lua chunk,
|
|
or as pre-compiled chunks.
|
|
When called without arguments,
|
|
\verb|dofile| executes the contents of the standard input (\verb|stdin|).
|
|
If there is any error executing the file,
|
|
then \verb|dofile| returns \nil.
|
|
Otherwise, it returns the values returned by the chunk,
|
|
or a non \nil\ value if the chunk returns no values.
|
|
It issues an error when called with a non string argument.
|
|
\verb|dofile| is equivalent to the API function \verb|lua_dofile|.
|
|
|
|
\subsubsection*{\ff \T{dostring (string [, chunkname])}}\Deffunc{dostring}
|
|
Executes a given string as a Lua chunk.
|
|
If there is any error executing the string,
|
|
\verb|dostring| returns \nil.
|
|
Otherwise, it returns the values returned by the chunk,
|
|
or a non \nil\ value if the chunk returns no values.
|
|
An optional second parameter (\verb|chunkname|)
|
|
is the ``name of the chunk'',
|
|
used in error messages and debug information.
|
|
\verb|dostring| is equivalent to the API function \verb|lua_dostring|.
|
|
|
|
\subsubsection*{\ff \T{newtag ()}}\Deffunc{newtag}\label{pdf-newtag}
|
|
Returns a new tag.
|
|
\verb|newtag| is equivalent to the API function \verb|lua_newtag|.
|
|
|
|
\subsubsection*{\ff \T{next (table, index)}}\Deffunc{next}
|
|
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.
|
|
|
|
Lua has 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 in which the indices are enumerated is not specified,
|
|
\emph{even for numeric indices}
|
|
(to traverse a table in numeric order,
|
|
use a counter or the function \verb|foreachi|).
|
|
If the table indices are modified in any way during a traversal,
|
|
the semantics of \verb|next| is undefined.
|
|
|
|
This function cannot be written with the standard API.
|
|
|
|
\subsubsection*{\ff \T{nextvar (name)}}\Deffunc{nextvar}
|
|
This function is similar to the function \verb|next|,
|
|
but iterates instead 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.
|
|
There can be no creation of new global variables during the traversal;
|
|
otherwise the semantics of \verb|nextvar| is undefined.
|
|
|
|
This function cannot be written with the standard API.
|
|
|
|
\subsubsection*{\ff \T{tostring (e)}}\Deffunc{tostring}
|
|
Receives an argument of any type and
|
|
converts it to a string in a reasonable format.
|
|
For complete control on how numbers are converted,
|
|
use function \verb|format|.
|
|
|
|
\subsubsection*{\ff \T{print (e1, e2, ...)}}\Deffunc{print}
|
|
Receives any number of arguments,
|
|
and prints their values using the strings returned by \verb|tostring|.
|
|
This function is not intended for formatted output,
|
|
but only as a quick way to show a value,
|
|
for instance for debugging.
|
|
See \See{libio} for functions for formatted output.
|
|
|
|
\subsubsection*{\ff \T{_ALERT (message)}}\Deffunc{alert}\label{alert}
|
|
Prints its only string argument to \IndexVerb{stderr}.
|
|
All error messages in Lua are printed through this function.
|
|
Therefore, a program may redefine it
|
|
to change the way such messages are shown
|
|
(for instance, for systems without \verb|stderr|).
|
|
|
|
\subsubsection*{\ff \T{tonumber (e [, base])}}\Deffunc{tonumber}
|
|
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, then \verb|tonumber| returns that number;
|
|
otherwise, it returns \nil.
|
|
|
|
An optional argument specifies the base to interpret the numeral.
|
|
The base may be any integer between 2 and 36 inclusive.
|
|
In bases above 10, the letter `A' (either upper or lower case)
|
|
represents 10, `B' represents 11, and so forth, with `Z' representing 35.
|
|
|
|
In base 10 (the default), the number may have a decimal part,
|
|
as well as an optional exponent part \see{coercion}.
|
|
In other bases, only integers are accepted.
|
|
|
|
\subsubsection*{\ff \T{type (v)}}\Deffunc{type}\label{pdf-type}
|
|
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"|,
|
|
and \verb|"userdata"|.
|
|
|
|
\subsubsection*{\ff \T{tag (v)}}\Deffunc{tag}
|
|
Allows Lua to test the tag of a value \see{TypesSec}.
|
|
It receives one argument, and returns its tag (a number).
|
|
\verb|tag| is equivalent to the API function \verb|lua_tag|.
|
|
|
|
\subsubsection*{\ff \T{settag (t, tag)}}\Deffunc{settag}
|
|
Sets the tag of a given table \see{TypesSec}.
|
|
\verb|tag| must be a value created with \verb|newtag|
|
|
\see{pdf-newtag}.
|
|
It returns the value of its first argument (the table).
|
|
For security reasons,
|
|
it is impossible to change the tag of a userdata from Lua.
|
|
|
|
|
|
\subsubsection*{\ff \T{assert (v [, message])}}\Deffunc{assert}
|
|
Issues an \emph{``assertion failed!''} error
|
|
when its argument is \nil.
|
|
This function is equivalent to the following Lua function:
|
|
\begin{verbatim}
|
|
function assert (v, m)
|
|
if not v then
|
|
m = m or ""
|
|
error("assertion failed! " .. m)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{error (message)}}\Deffunc{error}\label{pdf-error}
|
|
Calls the error handler and then terminates
|
|
the last protected function called
|
|
(in~C: \verb|lua_dofile|, \verb|lua_dostring|,
|
|
\verb|lua_dobuffer|, or \verb|lua_callfunction|;
|
|
in Lua: \verb|dofile|, \verb|dostring|, or \verb|call| in protected mode).
|
|
If \verb|message| is \nil, the error handler is not called.
|
|
Function \verb|error| never returns.
|
|
\verb|error| is equivalent to the API function \verb|lua_error|.
|
|
|
|
\subsubsection*{\ff \T{rawgettable (table, index)}}\Deffunc{rawgettable}
|
|
Gets the real value of \verb|table[index]|,
|
|
without invoking any tag method.
|
|
\verb|table| must be a table,
|
|
and \verb|index| is any value different from \nil.
|
|
|
|
\subsubsection*{\ff \T{rawsettable (table, index, value)}}\Deffunc{rawsettable}
|
|
Sets the real value of \verb|table[index]| to \verb|value|,
|
|
without invoking any tag method.
|
|
\verb|table| must be a table,
|
|
\verb|index| is any value different from \nil,
|
|
and \verb|value| is any Lua value.
|
|
|
|
\subsubsection*{\ff \T{rawsetglobal (name, value)}}\Deffunc{rawsetglobal}
|
|
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|.
|
|
Function \verb|rawsetglobal| returns the value of its second argument.
|
|
|
|
\subsubsection*{\ff \T{setglobal (name, value)}}\Deffunc{setglobal}
|
|
Assigns the given value to a global variable,
|
|
or calls a tag method.
|
|
Its full semantics is explained in \See{tag-method}.
|
|
The string \verb|name| does not need to be a
|
|
syntactically valid variable name.
|
|
Function \verb|setglobal| returns the value of its second argument.
|
|
|
|
\subsubsection*{\ff \T{rawgetglobal (name)}}\Deffunc{rawgetglobal}
|
|
Retrieves the value of a global variable.
|
|
The string \verb|name| does not need to be a
|
|
syntactically valid variable name.
|
|
|
|
\subsubsection*{\ff \T{getglobal (name)}}\Deffunc{getglobal}
|
|
Retrieves the value of a global variable,
|
|
or calls a tag method.
|
|
Its full semantics is explained in \See{tag-method}.
|
|
The string \verb|name| does not need to be a
|
|
syntactically valid variable name.
|
|
|
|
\subsubsection*{\ff \T{settagmethod (tag, event, newmethod)}}
|
|
\Deffunc{settagmethod}
|
|
Sets a new tag method to the given pair \M{(tag, event)}.
|
|
It returns the old method.
|
|
If \verb|newmethod| is \nil,
|
|
\verb|settagmethod| restores the default behavior for the given event.
|
|
|
|
\subsubsection*{\ff \T{gettagmethod (tag, event)}}
|
|
\Deffunc{gettagmethod}
|
|
Returns the current tag method
|
|
for a given pair \M{(tag, event)}.
|
|
|
|
\subsubsection*{\ff \T{copytagmethods (tagto, tagfrom)}}
|
|
\Deffunc{copytagmethods}
|
|
Copies all tag methods from one tag to another;
|
|
it returns \verb|tagto|.
|
|
|
|
\subsubsection*{\ff \T{getn (table)}}\Deffunc{getn}\label{getn}
|
|
Returns the ``size'' of a table, when seen as a list.
|
|
If the table has an \verb|n| field with a numeric value,
|
|
this is its ``size''.
|
|
Otherwise, the size is the largest numerical index with a non-nil
|
|
value in the table.
|
|
This function could be defined in Lua:
|
|
\begin{verbatim}
|
|
function getn (t)
|
|
if type(t.n) == 'number' then return t.n end
|
|
local max = 0
|
|
local i = next(t, nil)
|
|
while i do
|
|
if type(i) == 'number' and i>max then max=i end
|
|
i = next(t, i)
|
|
end
|
|
return max
|
|
end
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection*{\ff \T{foreach (table, function)}}\Deffunc{foreach}
|
|
Executes the given \verb|function| over all elements of \verb|table|.
|
|
For each element, the function is called with the index and
|
|
respective value as arguments.
|
|
If the function returns any non-\nil\ value,
|
|
the loop is broken, and the value is returned
|
|
as the final value of \verb|foreach|.
|
|
|
|
This function could be defined in Lua:
|
|
\begin{verbatim}
|
|
function foreach (t, f)
|
|
local i, v = next(t, nil)
|
|
while i do
|
|
local res = f(i, v)
|
|
if res then return res end
|
|
i, v = next(t, i)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection*{\ff \T{foreachi (table, function)}}\Deffunc{foreachi}
|
|
Executes the given \verb|function| over the
|
|
numerical indices of \verb|table|.
|
|
For each index, the function is called with the index and
|
|
respective value as arguments.
|
|
Indices are visited in sequential order,
|
|
from 1 to \verb|n|,
|
|
where \verb|n| is the result of \verb|getn(table)| \see{getn}.
|
|
If the function returns any non-\nil\ value,
|
|
the loop is broken, and the value is returned
|
|
as the final value of \verb|foreachi|.
|
|
|
|
This function could be defined in Lua:
|
|
\begin{verbatim}
|
|
function foreachi (t, f)
|
|
local i, n = 1, getn(t)
|
|
while i <= n do
|
|
local res = f(i, t[i])
|
|
if res then return res end
|
|
i = i+1
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{foreachvar (function)}}\Deffunc{foreachvar}
|
|
Executes \verb|function| over all global variables.
|
|
For each variable,
|
|
the function is called with its name and its value as arguments.
|
|
If the function returns any non-nil value,
|
|
the loop is broken, and the value is returned
|
|
as the final value of \verb|foreachvar|.
|
|
|
|
This function could be defined in Lua:
|
|
\begin{verbatim}
|
|
function foreachvar (f)
|
|
local n, v = nextvar(nil)
|
|
while n do
|
|
local res = f(n, v)
|
|
if res then return res end
|
|
n, v = nextvar(n)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{tinsert (table [, pos] , value)}}\Deffunc{tinsert}
|
|
|
|
Inserts element \verb|value| at table position \verb|pos|,
|
|
shifting other elements to open space.
|
|
The default value for \verb|pos| is \verb|n+1|
|
|
(where \verb|n| is the result of \verb|getn(table)| \see{getn})
|
|
so that a call \verb|tinsert(t,x)| inserts \verb|x| at the end
|
|
of table \verb|t|.
|
|
|
|
This function also sets or increments the field \verb|n| of the table,
|
|
to \verb|n+1|.
|
|
|
|
This function is equivalent to the following Lua function,
|
|
except that the table accesses are all raw (that is, without tag methods):
|
|
\begin{verbatim}
|
|
function tinsert (t, ...)
|
|
local pos, value
|
|
local n = getn(t)
|
|
if arg.n == 1 then
|
|
pos = n+1; value = arg[1]
|
|
else
|
|
pos = arg[1]; value = arg[2]
|
|
end
|
|
t.n = n+1;
|
|
while n >= pos do
|
|
t[n+1] = t[n]
|
|
n = n-1
|
|
end
|
|
t[pos] = value
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{tremove (table [, pos])}}\Deffunc{tremove}
|
|
|
|
Removes from \verb|table| the element at position \verb|pos|,
|
|
shifting other elements to close the space.
|
|
Returns the value of the removed element.
|
|
The default value for \verb|pos| is \verb|n|
|
|
(where \verb|n| is the result of \verb|getn(table)| \see{getn}),
|
|
so that a call \verb|tremove(t)| removes the last element
|
|
of table \verb|t|.
|
|
|
|
This function also sets or decrements the field \verb|n| of the table,
|
|
to \verb|n-1|.
|
|
|
|
This function is equivalent to the following Lua function,
|
|
except that the table accesses are all raw (that is, without tag methods):
|
|
\begin{verbatim}
|
|
function tremove (t, pos)
|
|
local n = getn(t)
|
|
pos = pos or n
|
|
local value = t[pos]
|
|
if n<=0 then return end
|
|
while pos < n do
|
|
t[pos] = t[pos+1]
|
|
pos = pos+1
|
|
end
|
|
t[n] = nil
|
|
t.n = n-1
|
|
return value
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{sort (table [, comp])}}\Deffunc{sort}
|
|
Sorts table elements in a given order, \emph{in-place},
|
|
from \verb|table[1]| to \verb|table[n]|,
|
|
where \verb|n| is the result of \verb|getn(table)| \see{getn}.
|
|
If \verb|comp| is given,
|
|
it must be a function that receives two table elements,
|
|
and returns true when the first is less than the second
|
|
(so that \verb|not comp(a[i+1], a[i])| will be true after the sort).
|
|
If \verb|comp| is not given,
|
|
the standard \verb|<| Lua operator is used instead.
|
|
|
|
Function \verb|sort| returns the (sorted) table.
|
|
|
|
|
|
\subsection{String Manipulation}
|
|
This library provides generic functions for string manipulation,
|
|
such as finding and extracting substrings and pattern matching.
|
|
When indexing a string, the first character is at position~1
|
|
(not at~0, as in C).
|
|
|
|
\subsubsection*{\ff \T{strfind (str, pattern [, init [, plain]])}}
|
|
\Deffunc{strfind}
|
|
Looks for the first \emph{match} of
|
|
\verb|pattern| in \verb|str|.
|
|
If it finds one, then it returns the indices on \verb|str|
|
|
where this occurrence starts and ends;
|
|
otherwise, it returns \nil.
|
|
If the pattern specifies captures,
|
|
the captured strings are returned as extra results.
|
|
A third optional numerical argument specifies where to start the search;
|
|
its default value is 1.
|
|
If \verb|init| is negative,
|
|
it is replaced by the length of the string minus its
|
|
absolute value plus 1.
|
|
Therefore, \Math{-1} points to the last character of \verb|str|.
|
|
A value of 1 as a fourth optional argument
|
|
turns off the pattern matching facilities,
|
|
so the function does a plain ``find substring'' operation,
|
|
with no characters in \verb|pattern| being considered ``magic''.
|
|
|
|
\subsubsection*{\ff \T{strlen (s)}}\Deffunc{strlen}
|
|
Receives a string and returns its length.
|
|
|
|
\subsubsection*{\ff \T{strsub (s, i [, j])}}\Deffunc{strsub}
|
|
Returns another string, which is a substring of \verb|s|,
|
|
starting at \verb|i| and running until \verb|j|.
|
|
If \verb|i| or \verb|j| are negative,
|
|
they are replaced by the length of the string minus their
|
|
absolute value plus 1.
|
|
Therefore, \Math{-1} points to the last character of \verb|s|
|
|
and \Math{-2} to the previous one.
|
|
If \verb|j| is absent, it is assumed to be equal to \Math{-1}
|
|
(which is the same as the string length).
|
|
In particular,
|
|
the call \verb|strsub(s,1,j)| returns a prefix of \verb|s|
|
|
with length \verb|j|,
|
|
and the call \verb|strsub(s, -i)| returns a suffix of \verb|s|
|
|
with length \verb|i|.
|
|
|
|
\subsubsection*{\ff \T{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.
|
|
The definition of what is an upper case
|
|
letter depends on the current locale.
|
|
|
|
\subsubsection*{\ff \T{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.
|
|
The definition of what is a lower case
|
|
letter depends on the current locale.
|
|
|
|
\subsubsection*{\ff \T{strrep (s, n)}}\Deffunc{strrep}
|
|
Returns a string that is the concatenation of \verb|n| copies of
|
|
the string \verb|s|.
|
|
|
|
\subsubsection*{\ff \T{strbyte (s [, i])}}\Deffunc{strbyte}
|
|
Returns the internal numerical code of the character \verb|s[i]|.
|
|
If \verb|i| is absent, then it is assumed to be 1.
|
|
If \verb|i| is negative,
|
|
it is replaced by the length of the string minus its
|
|
absolute value plus 1.
|
|
Therefore, \Math{-1} points to the last character of \verb|s|.
|
|
|
|
Note that numerical codes are not necessarily portable across platforms.
|
|
|
|
\subsubsection*{\ff \T{strchar (i1, i2, \ldots)}}\Deffunc{strchar}
|
|
Receives 0 or more integers.
|
|
Returns a string with length equal to the number of arguments,
|
|
wherein each character has the internal numerical code equal
|
|
to its correspondent argument.
|
|
|
|
Note that numerical codes are not necessarily portable across platforms.
|
|
|
|
\subsubsection*{\ff \T{format (formatstring, e1, e2, \ldots)}}\Deffunc{format}
|
|
\label{format}
|
|
Returns a formatted 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.
|
|
For instance, the call
|
|
\begin{verbatim}
|
|
format('%q', 'a string with "quotes" and \n new line')
|
|
\end{verbatim}
|
|
will produce the string:
|
|
\begin{verbatim}
|
|
"a string with \"quotes\" and \
|
|
new line"
|
|
\end{verbatim}
|
|
|
|
Conversions can be applied to the n-th argument in the argument list,
|
|
rather than the next unused argument.
|
|
In this case, the conversion character \verb|%| is replaced
|
|
by the sequence \verb|%d$|, where \verb|d| is a
|
|
decimal digit in the range [1,9],
|
|
giving the position of the argument in the argument list.
|
|
For instance, the call \verb|format("%2$d -> %1$03d", 1, 34)| will
|
|
result in \verb|"34 -> 001"|.
|
|
The same argument can be used in more than one conversion.
|
|
|
|
The options \verb|c|, \verb|d|, \verb|E|, \verb|e|, \verb|f|,
|
|
\verb|g|, \verb|G|, \verb|i|, \verb|o|, \verb|u|, \verb|X|, and \verb|x| all
|
|
expect a number as argument,
|
|
whereas \verb|q| and \verb|s| expect a string.
|
|
The \verb|*| modifier can be simulated by building
|
|
the appropriate format string.
|
|
For example, \verb|"%*g"| can be simulated with
|
|
\verb|"%"..width.."g"|.
|
|
|
|
\emph{Note: function \T{format} can only be used with strings that do not
|
|
contain zeros.}
|
|
|
|
\subsubsection*{\ff \T{gsub (s, pat, repl [, n])}}
|
|
\Deffunc{gsub}
|
|
Returns a copy of \verb|s|,
|
|
where all occurrences of the pattern \verb|pat| have been
|
|
replaced by a replacement string specified by \verb|repl|.
|
|
This function also returns, as a second value,
|
|
the total number of substitutions made.
|
|
|
|
If \verb|repl| is a string, then its value is used for replacement.
|
|
Any sequence in \verb|repl| of the form \verb|%n|
|
|
with \verb|n| between 1 and 9
|
|
stands for the value of the n-th captured substring.
|
|
|
|
If \verb|repl| is a function, then this function is called every time a
|
|
match occurs, with all captured substrings passed as arguments,
|
|
in order (see below).
|
|
If the value returned by this function is a string,
|
|
then it is used as the replacement string;
|
|
otherwise, the replacement string is the empty string.
|
|
|
|
A last optional parameter \verb|n| limits
|
|
the maximum number of substitutions to occur.
|
|
For instance, when \verb|n| is 1 only the first occurrence of
|
|
\verb|pat| is replaced.
|
|
|
|
Here are some examples:
|
|
\begin{verbatim}
|
|
x = gsub("hello world", "(%w+)", "%1 %1")
|
|
--> x="hello hello world world"
|
|
|
|
x = gsub("hello world", "(%w+)", "%1 %1", 1)
|
|
--> x="hello hello world"
|
|
|
|
x = gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
|
|
--> x="world hello Lua from"
|
|
|
|
x = gsub("home = $HOME, user = $USER", "%$(%w+)", getenv)
|
|
--> x="home = /home/roberto, user = roberto" (for instance)
|
|
|
|
x = gsub("4+5 = $return 4+5$", "%$(.-)%$", dostring)
|
|
--> x="4+5 = 9"
|
|
|
|
local t = {name="lua", version="3.2"}
|
|
x = gsub("$name - $version", "%$(%w+)", function (v) return %t[v] end)
|
|
--> x="lua - 3.2"
|
|
|
|
t = {n=0}
|
|
gsub("first second word", "(%w+)", function (w) tinsert(%t, w) end)
|
|
--> t={"first", "second", "word"; n=3}
|
|
\end{verbatim}
|
|
|
|
|
|
\subsubsection*{Patterns} \label{pm}
|
|
|
|
\paragraph{Character Class:}
|
|
a \Def{character class} is used to represent a set of characters.
|
|
The following combinations are allowed in describing a character class:
|
|
\begin{description}
|
|
\item[\emph{x}] (where \emph{x} is any character not in the list
|
|
\verb|^$()%.[]*+-?|)
|
|
--- represents the character \emph{x} itself.
|
|
\item[\T{.}] --- (a dot) represents all characters.
|
|
\item[\T{\%a}] --- represents all letters.
|
|
\item[\T{\%c}] --- represents all control characters.
|
|
\item[\T{\%d}] --- represents all digits.
|
|
\item[\T{\%l}] --- represents all lower case letters.
|
|
\item[\T{\%p}] --- represents all punctuation characters.
|
|
\item[\T{\%s}] --- represents all space characters.
|
|
\item[\T{\%u}] --- represents all upper case letters.
|
|
\item[\T{\%w}] --- represents all alphanumeric characters.
|
|
\item[\T{\%x}] --- represents all hexa-decimal digits.
|
|
\item[\T{\%z}] --- represents the character with representation 0.
|
|
\item[\T{\%\M{x}}] (where \M{x} is any non alphanumeric character) ---
|
|
represents the character \M{x}.
|
|
This is the standard way to escape the magic characters \verb|()%.[]*-?|.
|
|
It is strongly recommended that any control character (even the non magic),
|
|
when used to represent itself in a pattern, should be preceded by a \verb|%|.
|
|
\item[\T{[char-set]}] ---
|
|
Represents the class which is the union of all
|
|
characters in char-set.
|
|
To include a \verb|]| in char-set, it must be the first character.
|
|
A range of characters may be specified by
|
|
separating the end characters of the range with a \verb|-|.
|
|
If \verb|-| appears as the first or last character of char-set,
|
|
then it represents itself.
|
|
All classes \verb|%|\emph{x} described above can also be used as
|
|
components in a char-set.
|
|
All other characters in char-set represent themselves.
|
|
E.g., assuming an \emph{ascii} character set,
|
|
\verb|[%dA-Fa-f]| specifies the hexa-decimal digits.
|
|
\item[\T{[\^{ }char-set]}] ---
|
|
represents the complement of char-set,
|
|
where char-set is interpreted as above.
|
|
\end{description}
|
|
For all classes represented by single letters (\verb|%a|, \verb|%c|, \ldots),
|
|
the correspondent upper-case letter represents the complement of the class.
|
|
For instance, \verb|%S| represents all non-space characters.
|
|
|
|
The definitions of letter, space, etc. depend on the current locale.
|
|
In particular, the class \verb|[a-z]| may not be equivalent to \verb|%l|.
|
|
The second form should be preferred for more portable programs.
|
|
|
|
\paragraph{Pattern Item:}
|
|
a \Def{pattern item} may be
|
|
\begin{itemize}
|
|
\item
|
|
a single character class,
|
|
which matches any single character in the class;
|
|
\item
|
|
a single character class followed by \verb|*|,
|
|
which matches 0 or more repetitions of characters in the class.
|
|
These repetition items will always match the longest possible sequence;
|
|
\item
|
|
a single character class followed by \verb|+|,
|
|
which matches 1 or more repetitions of characters in the class.
|
|
These repetition items will always match the longest possible sequence;
|
|
\item
|
|
a single character class followed by \verb|-|,
|
|
which also matches 0 or more repetitions of characters in the class.
|
|
Unlike \verb|*|,
|
|
these repetition items will always match the shortest possible sequence;
|
|
\item
|
|
a single character class followed by \verb|?|,
|
|
which matches 0 or 1 occurrence of a character in the class;
|
|
\item
|
|
\T{\%\M{n}}, for \M{n} between 1 and 9;
|
|
such item matches a sub-string equal to the n-th captured string
|
|
(see below);
|
|
\item
|
|
\T{\%b\M{xy}}, where \M{x} and \M{y} are two distinct characters;
|
|
such item matches strings that start with \M{x}, end with \M{y},
|
|
and where the \M{x} and \M{y} are \emph{balanced}.
|
|
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},
|
|
the ending \M{y} is the first where the count reaches 0.
|
|
For instance, the item \verb|%b()| matches expressions with
|
|
balanced parentheses.
|
|
\end{itemize}
|
|
|
|
\paragraph{Pattern:}
|
|
a \Def{pattern} is a sequence of pattern items.
|
|
A \verb|^| at the beginning of a pattern anchors the match at the
|
|
beginning of the subject string.
|
|
A \verb|$| at the end of a pattern anchors the match at the
|
|
end of the subject string.
|
|
|
|
\paragraph{Captures:}
|
|
a pattern may contain sub-patterns enclosed in parentheses,
|
|
that describe \Def{captures}.
|
|
When a match succeeds, the sub-strings of the subject string
|
|
that match captures are stored (\emph{captured}) for future use.
|
|
Captures are numbered according to their left parentheses.
|
|
For instance, in the pattern \verb|"(a*(.)%w(%s*))"|,
|
|
the part of the string matching \verb|"a*(.)%w(%s*)"| is
|
|
stored as the first capture (and therefore has number~1);
|
|
the character matching \verb|.| is captured with number~2,
|
|
and the part matching \verb|%s*| has number~3.
|
|
|
|
|
|
\subsection{Mathematical Functions} \label{mathlib}
|
|
|
|
This library is an interface to some functions of the standard C math library.
|
|
In addition, it registers a tag method for the binary operator \verb|^| that
|
|
returns \Math{x^y} when applied to numbers \verb|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{frexp}\Deffunc{ldexp}
|
|
\Deffunc{random}\Deffunc{randomseed}
|
|
\begin{verbatim}
|
|
abs acos asin atan atan2 ceil cos deg floor log log10
|
|
max min mod rad sin sqrt tan frexp ldexp
|
|
random randomseed
|
|
\end{verbatim}
|
|
plus a global variable \IndexVerb{PI}.
|
|
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 \emph{degrees}, not radians.
|
|
Functions \IndexVerb{deg} and \IndexVerb{rad} can be used to convert
|
|
between radians and degrees.
|
|
|
|
The function \verb|max| returns the maximum
|
|
value of its numeric arguments.
|
|
Similarly, \verb|min| computes the minimum.
|
|
Both can be used with 1, 2 or more arguments.
|
|
|
|
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|, when called without arguments,
|
|
returns a pseudo-random real number in the range \Math{[0,1)}.
|
|
When called with a number \Math{n},
|
|
\verb|random| returns a pseudo-random integer in the range \Math{[1,n]}.
|
|
When called with two arguments, \Math{l} and \Math{u},
|
|
\verb|random| returns a pseudo-random integer in the range \Math{[l,u]}.
|
|
|
|
|
|
\subsection{I/O Facilities} \label{libio}
|
|
|
|
All input and output operations in Lua are done, by default,
|
|
over two \Def{file handles}, one for reading and one for writing.
|
|
These handles are stored in two Lua global variables,
|
|
called \verb|_INPUT| and \verb|_OUTPUT|.
|
|
The global variables
|
|
\verb|_STDIN|, \verb|_STDOUT| and \verb|_STDERR|
|
|
are initialized with file descriptors for
|
|
\verb|stdin|, \verb|stdout| and \verb|stderr|.
|
|
Initially, \verb|_INPUT=_STDIN| and \verb|_OUTPUT=_STDOUT|.
|
|
\Deffunc{_INPUT}\Deffunc{_OUTPUT}
|
|
\Deffunc{_STDIN}\Deffunc{_STDOUT}\Deffunc{_STDERR}
|
|
|
|
A file handle is a userdata containing the file stream \verb|FILE*|,
|
|
and with a distinctive tag created by the I/O library.
|
|
Whenever a file handle is collected by the garbage collector,
|
|
its correspondent stream is automatically closed.
|
|
|
|
Unless otherwise stated,
|
|
all I/O functions return \nil\ on failure and
|
|
some value different from \nil\ on success.
|
|
|
|
\subsubsection*{\ff \T{openfile (filename, mode)}}\Deffunc{openfile}
|
|
|
|
This function opens a file,
|
|
in the mode specified in the string \verb|mode|.
|
|
It returns a new file handle,
|
|
or, in case of errors, \nil\ plus a string describing the error.
|
|
This function does not modify either \verb|_INPUT| or \verb|_OUTPUT|.
|
|
|
|
The string mode can be any of the following:
|
|
\begin{description}
|
|
\item["r"] read mode;
|
|
\item["w"] write mode;
|
|
\item["a"] append mode;
|
|
\item["r+"] update mode, all previous data is preserved;
|
|
\item["w+"] update mode, all previous data is erased;
|
|
\item["a+"] append update mode, previous data is preserved,
|
|
writing is only allowed at the end of file.
|
|
\end{description}
|
|
The string mode may also have a \verb|b| at the end,
|
|
which is needed in some systems to open the file in binary mode.
|
|
|
|
\subsubsection*{\ff \T{closefile (handle)}}\Deffunc{closefile}
|
|
|
|
This function closes the given file.
|
|
It does not modify either \verb|_INPUT| or \verb|_OUTPUT|.
|
|
|
|
\subsubsection*{\ff \T{readfrom (filename)}}\Deffunc{readfrom}
|
|
|
|
This function may be called in two ways.
|
|
When called with a file name, it opens the named file,
|
|
sets its handle as the value of \verb|_INPUT|,
|
|
and returns this value.
|
|
It does not close the current input file.
|
|
When called without parameters,
|
|
it closes the \verb|_INPUT| file,
|
|
and restores \verb|stdin| as the value of \verb|_INPUT|.
|
|
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\begin{quotation}
|
|
\noindent
|
|
\emph{System dependent}: if \verb|filename| starts with a \verb-|-,
|
|
then a \Index{piped input} is opened, via function \IndexVerb{popen}.
|
|
Not all systems implement pipes.
|
|
Moreover,
|
|
the number of files that can be open at the same time is
|
|
usually limited and depends on the system.
|
|
\end{quotation}
|
|
|
|
\subsubsection*{\ff \T{writeto (filename)}}\Deffunc{writeto}
|
|
|
|
This function may be called in two ways.
|
|
When called with a file name,
|
|
it opens the named file,
|
|
sets its handle as the value of \verb|_OUTPUT|,
|
|
and returns this value.
|
|
It does not close the current output file.
|
|
Note that, if the file already exists,
|
|
then it will be \emph{completely erased} with this operation.
|
|
When called without parameters,
|
|
this function closes the \verb|_OUTPUT| file,
|
|
and restores \verb|stdout| as the value of \verb|_OUTPUT|.
|
|
\index{closing a file}
|
|
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\begin{quotation}
|
|
\noindent
|
|
\emph{System dependent}: if \verb|filename| starts with a \verb-|-,
|
|
then a \Index{piped output} is opened, via function \IndexVerb{popen}.
|
|
Not all systems implement pipes.
|
|
Moreover,
|
|
the number of files that can be open at the same time is
|
|
usually limited and depends on the system.
|
|
\end{quotation}
|
|
|
|
\subsubsection*{\ff \T{appendto (filename)}}\Deffunc{appendto}
|
|
|
|
Opens a file named \verb|filename| and sets it as the
|
|
value of \verb|_OUTPUT|.
|
|
Unlike the \verb|writeto| operation,
|
|
this function does not erase any previous content of the file.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{remove (filename)}}\Deffunc{remove}
|
|
|
|
Deletes the file with the given name.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{rename (name1, name2)}}\Deffunc{rename}
|
|
|
|
Renames file named \verb|name1| to \verb|name2|.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{flush ([filehandle])}}\Deffunc{flush}
|
|
|
|
Saves any written data to the given file.
|
|
If \verb|filehandle| is not specified,
|
|
flushes all open files.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{seek (filehandle [, whence] [, offset])}}\Deffunc{seek}
|
|
|
|
Sets and gets the file position,
|
|
measured in bytes from the beginning of the file,
|
|
to the position given by \verb|offset| plus a base
|
|
specified by the string \verb|whence|, as follows:
|
|
\begin{description}
|
|
\item["set"] base is position 0 (beginning of the file);
|
|
\item["cur"] base is current position;
|
|
\item["end"] base is end of file;
|
|
\end{description}
|
|
In case of success, function \verb|seek| returns the final file position,
|
|
measured in bytes from the beginning of the file.
|
|
If the call fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
The default value for \verb|whence| is \verb|"cur"|,
|
|
and for \verb|offset| is 0.
|
|
Therefore, the call \verb|seek(file)| returns the current
|
|
file position, without changing it;
|
|
the call \verb|seek(file, "set")| sets the position to the
|
|
beginning of the file (and returns 0);
|
|
and the call \verb|seek(file, "end")| sets the position to the
|
|
end of the file, and returns its size.
|
|
|
|
\subsubsection*{\ff \T{tmpname ()}}\Deffunc{tmpname}
|
|
|
|
Returns a string with a file name that can safely
|
|
be used for a temporary file.
|
|
The file must be explicitly removed when no longer needed.
|
|
|
|
\subsubsection*{\ff \T{read ([filehandle,] readpattern1, ...)}}\Deffunc{read}
|
|
|
|
Reads file \verb|_INPUT|,
|
|
or \verb|filehandle| if this argument is given,
|
|
according to read patterns, which specify how much to read.
|
|
For each pattern,
|
|
the function returns a string with the characters read,
|
|
even if the pattern succeeds only partially,
|
|
or \nil\ if the read pattern fails \emph{and}
|
|
the result string would be empty.
|
|
When called without patterns,
|
|
it uses a default pattern that reads the next line
|
|
(see below).
|
|
|
|
A \Def{read pattern} is a sequence of read pattern items.
|
|
An item may be a single character class
|
|
or a character class followed by \verb|?|, by \verb|*|, or by \verb|+|.
|
|
A single character class reads the next character from the input
|
|
if it belongs to the class, otherwise it fails.
|
|
A character class followed by \verb|?| reads the next character
|
|
from the input if it belongs to the class;
|
|
it never fails.
|
|
A character class followed by \verb|*| reads until a character that
|
|
does not belong to the class, or end of file;
|
|
since it can match a sequence of zero characters, it never fails.
|
|
A character class followed by \verb|+| reads until a character that
|
|
does not belong to the class, or end of file;
|
|
it fails if it cannot read at least one character.
|
|
Note that the behavior of read patterns is slightly different from
|
|
the regular pattern matching behavior,
|
|
where a \verb|*| expands to the maximum length \emph{such that}
|
|
the rest of the pattern does not fail.
|
|
With the read pattern behavior
|
|
there is no need for backtracking the reading.
|
|
|
|
A pattern item may contain sub-patterns enclosed in curly brackets,
|
|
that describe \Def{skips}.
|
|
Characters matching a skip are read,
|
|
but are not included in the resulting string.
|
|
|
|
There are some predefined patterns, as follows:
|
|
\begin{description}
|
|
\item[``*n''] reads a number;
|
|
this is the only pattern that returns a number instead of a string.
|
|
\item[``*l''] returns the next line
|
|
(skipping the end of line), or \nil\ on end of file.
|
|
This is the default pattern.
|
|
It is equivalent to the pattern \verb|"[^\n]*{\n}"|.
|
|
\item[``*a''] reads the whole file.
|
|
It is equivalent to the pattern \verb|".*"|.
|
|
\item[``*w''] returns the next word
|
|
(maximal sequence of non white-space characters),
|
|
skipping spaces if necessary, or \nil\ on end of file.
|
|
It is equivalent to the pattern \verb|"{%s*}%S+"|.
|
|
\end{description}
|
|
|
|
\subsubsection*{\ff \T{write ([filehandle, ] value1, ...)}}\Deffunc{write}
|
|
|
|
Writes the value of each of its arguments to
|
|
file \verb|_OUTPUT|,
|
|
or to \verb|filehandle| if this argument is given.
|
|
The arguments must be strings or numbers.
|
|
To write other values,
|
|
use \verb|tostring| or \verb|format| before \verb|write|.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{date ([format])}}\Deffunc{date}
|
|
|
|
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 that depends on
|
|
the host system and on the locale.
|
|
|
|
\subsubsection*{\ff \T{clock ()}}\Deffunc{clock}
|
|
|
|
Returns an approximation of the amount of CPU time
|
|
used by the program, in seconds.
|
|
|
|
\subsubsection*{\ff \T{exit ([code])}}\Deffunc{exit}
|
|
|
|
Calls the C function \verb|exit|,
|
|
with an optional \verb|code|,
|
|
to terminate the program.
|
|
The default value for \verb|code| is 1.
|
|
|
|
\subsubsection*{\ff \T{getenv (varname)}}\Deffunc{getenv}
|
|
|
|
Returns the value of the process environment variable \verb|varname|,
|
|
or \nil\ if the variable is not defined.
|
|
|
|
\subsubsection*{\ff \T{execute (command)}}\Deffunc{execute}
|
|
|
|
This function is equivalent to the C function \verb|system|.
|
|
It passes \verb|command| to be executed by an operating system shell.
|
|
It returns an error code, which is system-dependent.
|
|
|
|
\subsubsection*{\ff \T{setlocale (locale [, category])}}\Deffunc{setlocale}
|
|
|
|
This function is an interface to the ANSI C function \verb|setlocale|.
|
|
\verb|locale| is a string specifying a locale;
|
|
\verb|category| is an optional string describing which category to change:
|
|
\verb|"all"|, \verb|"collate"|, \verb|"ctype"|,
|
|
\verb|"monetary"|, \verb|"numeric"|, or \verb|"time"|;
|
|
the default category is \verb|"all"|.
|
|
The function returns the name of the new locale,
|
|
or \nil\ if the request cannot be honored.
|
|
|
|
|
|
\section{The Debugger Interface} \label{debugI}
|
|
|
|
Lua has no built-in debugging facilities.
|
|
Instead, it offers a special interface,
|
|
by means of functions and \emph{hooks},
|
|
which allows the construction of different
|
|
kinds of debuggers, 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 \emph{activation record}
|
|
of the function executing at a given level.
|
|
Level~0 is the current running function,
|
|
while level \Math{n+1} is the function that has called level \Math{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,
|
|
when a parameter has type \verb|lua_Function|
|
|
it 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 **source, int *linedefined);
|
|
int lua_currentline (lua_Function func);
|
|
char *lua_getobjname (lua_Object o, char **name);
|
|
\end{verbatim}
|
|
\verb|lua_funcinfo| gives the source and the line where the
|
|
given function has been defined:
|
|
If the function was defined in a string,
|
|
\verb|source| is that string;
|
|
If the function was defined in a file,
|
|
\verb|source| starts with a \verb|@| followed by the file name.
|
|
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 \Math{-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 compiled with debug
|
|
information.
|
|
When no line information is available,
|
|
\verb|lua_currentline| returns \Math{-1}.
|
|
|
|
The generation of debug information is controled by an internal flag,
|
|
which can be switched with
|
|
\begin{verbatim}
|
|
int lua_setdebug (int debug);
|
|
\end{verbatim}
|
|
This function sets the flag and returns its previous value.
|
|
This flag can also be set from Lua~\see{pragma}.
|
|
|
|
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| checks whether the given
|
|
function is a tag method or the value of a global variable.
|
|
If the given function is a tag method, then \verb|lua_getobjname|
|
|
returns the string \verb|"tag-method"|,
|
|
and \verb|name| is set to point to the event name.
|
|
If the given function is the value of a global variable,
|
|
then \verb|lua_getobjname| returns the string \verb|"global"|,
|
|
and \verb|name| points to the variable name.
|
|
If the given function is neither a tag method 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 compiled with debug
|
|
information \see{pragma}.
|
|
Moreover, for these functions, a local variable becomes
|
|
visible in the line after its definition.
|
|
\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}
|
|
\verb|lua_getlocal| 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|.
|
|
Formal parameters are the first local variables.
|
|
|
|
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);
|
|
lua_CHFunction lua_setcallhook (lua_CHFunction func);
|
|
|
|
typedef void (*lua_LHFunction) (int line);
|
|
lua_LHFunction lua_setlinehook (lua_LHFunction func);
|
|
\end{verbatim}
|
|
The first hook 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 called only if the active function
|
|
has been compiled with debug information \see{pragma}.
|
|
|
|
A hook is disabled when its value is \verb|NULL|,
|
|
which is the initial value of both hooks.
|
|
Both \verb|lua_setcallhook| and \verb|lua_setlinehook|
|
|
set their corresponding hooks and return their previous values.
|
|
|
|
|
|
|
|
\subsection{The Reflexive Debugger Interface}
|
|
|
|
The library \verb|ldblib| provides
|
|
the functionallity of the debugger interface to Lua programs.
|
|
If you want to use this library,
|
|
your host application must open it,
|
|
calling \verb|lua_dblibopen|.
|
|
|
|
You should exert great care when using this library.
|
|
The functions provided here should be used exclusively for debugging
|
|
and similar tasks (e.g. profiling).
|
|
Please resist the temptation to use them as a
|
|
usual programming tool.
|
|
They are slow and violate some (otherwise) secure aspects of the
|
|
language (e.g. privacy of local variables).
|
|
As a general rule, if your program does not need this library,
|
|
do not open it.
|
|
|
|
|
|
\subsubsection*{\ff \T{funcinfo (function)}}\Deffunc{funcinfo}
|
|
|
|
This function returns a table with information about the given function.
|
|
The table contains the following fields:
|
|
\begin{description}
|
|
\item[kind]: may be \verb|"C"|, if this is a C function,
|
|
\verb|"chunk"|, if this is the main part of a chunk,
|
|
or \verb|"Lua"| if this is a Lua function.
|
|
|
|
\item[source] the source where the function was defined.
|
|
If the function was defined in a string,
|
|
\verb|source| is that string;
|
|
If the function was defined in a file,
|
|
\verb|source| starts with a \verb|@| followed by the file name.
|
|
|
|
\item[def\_line] the line where the function was defined in the source
|
|
(only valid if this is a Lua function).
|
|
|
|
\item[where] can be \verb|"global"| if this function has a global name,
|
|
or \verb|"tag-method"| if this function is a tag method handler.
|
|
|
|
\item[name] if \verb|where| = \verb|global|,
|
|
\verb|name| is the global name of the function;
|
|
if \verb|where| = \verb|tag-method|,
|
|
\verb|name| is the event name of the tag method.
|
|
\end{description}
|
|
|
|
\subsubsection*{\ff \T{getstack (index)}}\Deffunc{getstack}
|
|
|
|
This function returns a table with informations about the function
|
|
running at level \verb|index| of the stack.
|
|
Index 0 is the current function (\verb|getstack| itself).
|
|
If \verb|index| is bigger than the number of active functions,
|
|
the function returns \nil.
|
|
The table contains all the fields returned by \verb|funcinfo|,
|
|
plus the following:
|
|
\begin{description}
|
|
\item[func] the function at that level.
|
|
\item[current] the current line on the function execution;
|
|
this will be available only when the function is
|
|
precompiled with debug information.
|
|
\end{description}
|
|
|
|
\subsubsection*{\ff \T{getlocal (index [, local])}}\Deffunc{getlocal}
|
|
|
|
This function returns information about the local variables of the
|
|
function at level \verb|index| of the stack.
|
|
It can be called in three ways.
|
|
When called without a \verb|local| argument,
|
|
it returns a table, which associates variable names to their values.
|
|
When called with a name (a string) as \verb|local|,
|
|
it returns the value of the local variable with that name.
|
|
Finally, when called with an index (a number),
|
|
it returns the value and the name of the local variable
|
|
with that index.
|
|
(The first parameter has index 1, and so on,
|
|
until the last active local variable.)
|
|
In that case, the function returns \nil\ if there is no local
|
|
variable with the given index.
|
|
The specification by index is the only way to distinguish
|
|
homonym variables in a function.
|
|
|
|
\subsubsection*{\ff \T{setlocal (index, local, newvalue)}}\Deffunc{setlocal}
|
|
|
|
This function changes the values of the local variables of the
|
|
function at level \verb|index| of the stack.
|
|
The local variable can be specified by name or by index;
|
|
see function \verb|getlocal|.
|
|
|
|
\subsubsection*{\ff \T{setcallhook (hook)}}\Deffunc{setcallhook}
|
|
|
|
Sets the function \verb|hook| as the call hook;
|
|
this hook will be called every time the interpreter starts and
|
|
exits the execution of a function.
|
|
When Lua enters a function,
|
|
the hook is called with the function been called,
|
|
plus the source and the line where the function is defined.
|
|
When Lua exits a function,
|
|
the hook is called with no arguments.
|
|
|
|
When called without arguments,
|
|
this function turns off call hooks.
|
|
|
|
\subsubsection*{\ff \T{setlinehook (hook)}}\Deffunc{setlinehook}
|
|
|
|
Sets the function \verb|hook| as the line hook;
|
|
this hook will be called every time the interpreter changes
|
|
the line of code it is executing.
|
|
The only argument to the hook is the line number the interpreter
|
|
is about to execut.
|
|
This hook is called only if the active function
|
|
has been compiled with debug information \see{pragma}.
|
|
|
|
When called without arguments,
|
|
this function turns off line hooks.
|
|
|
|
|
|
\section{\Index{Lua Stand-alone}} \label{lua-sa}
|
|
|
|
Although Lua has been designed as an extension language,
|
|
the language can also be used as a stand-alone interpreter.
|
|
An implementation of such an interpreter,
|
|
called simply \verb|lua|,
|
|
is provided with the standard distribution.
|
|
This program can be called with any sequence of the following arguments:
|
|
\begin{description}
|
|
\item[\T{-v}] prints version information.
|
|
\item[\T{-d}] turns on debug information.
|
|
\item[\T{-e stat}] executes \verb|stat| as a Lua chunk.
|
|
\item[\T{-i}] runs interactively,
|
|
accepting commands from standard input until an \verb|EOF|.
|
|
Each line entered is immediately executed.
|
|
\item[\T{-q}] same as \T{-i}, but without a prompt (quiet mode).
|
|
\item[\T{-}] executes \verb|stdin| as a file.
|
|
\item[\T{var=value}] sets global \verb|var| with string \verb|"value"|.
|
|
\item[\T{filename}] executes file \verb|filename| as a Lua chunk.
|
|
\end{description}
|
|
When called without arguments,
|
|
Lua behaves as \verb|lua -v -i| when \verb|stdin| is a terminal,
|
|
and as \verb|lua -| otherwise.
|
|
|
|
All arguments are handled in order.
|
|
For instance, an invocation like
|
|
\begin{verbatim}
|
|
$ lua -i a=test prog.lua
|
|
\end{verbatim}
|
|
will first interact with the user until an \verb|EOF|,
|
|
then will set \verb|a| to \verb|"test"|,
|
|
and finally will run the file \verb|prog.lua|.
|
|
|
|
When in interactive mode,
|
|
a multi-line statement can be written finishing intermediate
|
|
lines with a backslash (\verb|\|).
|
|
The prompt presented is the value of the global variable \verb|_PROMPT|.
|
|
Therefore, the prompt can be changed like below:
|
|
\begin{verbatim}
|
|
$ lua _PROMPT='myprompt> ' -i
|
|
\end{verbatim}
|
|
|
|
In Unix systems, Lua scripts can be made into executable programs
|
|
by using the \verb|#!| form,
|
|
as in \verb|#!/usr/local/bin/lua|.
|
|
|
|
\section*{Acknowledgments}
|
|
|
|
The authors would like to thank CENPES/PETROBRAS 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 \emph{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 incompatibilities.
|
|
|
|
\subsection*{Incompatibilities with \Index{version 3.1}}
|
|
\begin{itemize}
|
|
\item
|
|
In the debug API, the old variables \verb|lua_debug|,
|
|
\verb|lua_callhook| and \verb|lua_linehook| now live inside \verb|lua_state|.
|
|
Therefore, they are no longer directly accessible, and must be
|
|
manipulated only through the new functions \verb|lua_setdebug|,
|
|
\verb|lua_setcallhook| and \verb|lua_setlinehook|.
|
|
|
|
\item Old pre-compiled code is obsolete, and must be re-compiled.
|
|
\end{itemize}
|
|
|
|
\subsection*{Incompatibilities with \Index{version 3.0}}
|
|
\begin{itemize}
|
|
|
|
\item To support multiple contexts,
|
|
Lua 3.1 must be explicitly opened before used,
|
|
with function \verb|lua_open|.
|
|
However, all standard libraries check whether Lua is already opened,
|
|
so any existing program that opens at least one standard
|
|
library before calling Lua does not need to be modified.
|
|
|
|
\item Function \verb|dostring| no longer accepts an optional second argument,
|
|
with a temporary error handler.
|
|
This facility is now provided by function \verb|call|.
|
|
|
|
\item Function \verb|gsub| no longer accepts an optional fourth argument
|
|
(a callback data, a table).
|
|
Closures replace this feature with advantage.
|
|
|
|
\item The syntax for function declaration is now more restricted;
|
|
for instance, the old syntax \verb|function f[exp] (x) ... end| is not
|
|
accepted in Lua 3.1.
|
|
In these cases,
|
|
programs should use an explicit assignment instead, such as
|
|
\verb|f[exp] = function (x) ... end|.
|
|
|
|
\item Old pre-compiled code is obsolete, and must be re-compiled.
|
|
|
|
\item The option \verb|a=b| in Lua stand-alone now sets \verb|a| to the
|
|
\M{string} \verb|b|, and not to the value of \verb|b|.
|
|
|
|
\end{itemize}
|
|
|
|
% restore underscore to usual meaning
|
|
\catcode`\_=8
|
|
|
|
\newcommand{\indexentry}[2]{\item {#1} #2}
|
|
\begin{theindex}
|
|
\input{manual.id}
|
|
\end{theindex}
|
|
|
|
|
|
\end{document}
|
|
|
|
|