mirror of
https://github.com/lua/lua
synced 2024-12-15 15:22:35 +03:00
4112 lines
146 KiB
TeX
4112 lines
146 KiB
TeX
% $Id: manual.tex,v 1.54 2001/10/31 20:31:38 roberto Exp $
|
|
|
|
\documentclass[11pt,twoside,draft]{article}
|
|
\usepackage{fullpage}
|
|
\usepackage{bnf}
|
|
\usepackage{graphicx}
|
|
|
|
% no need for subscripts...
|
|
\catcode`\_=12
|
|
|
|
%\newcommand{\See}[1]{Section~\ref{#1}}
|
|
\newcommand{\See}[1]{\S\ref{#1}}
|
|
%\newcommand{\see}[1]{(see~\See{#1} on page \pageref{#1})}
|
|
\newcommand{\see}[1]{(see~\See{#1})}
|
|
\newcommand{\seepage}[1]{(see page~\pageref{#1})}
|
|
\newcommand{\M}[1]{{\rm\emph{#1}}}
|
|
\newcommand{\T}[1]{{\tt #1}}
|
|
\newcommand{\Math}[1]{$#1$}
|
|
\newcommand{\nil}{{\bf nil}}
|
|
\newcommand{\False}{{\bf false}}
|
|
\newcommand{\True}{{\bf true}}
|
|
%\def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}}
|
|
\def\tecgraf{{\sf TeCGraf}}
|
|
|
|
\newcommand{\Index}[1]{#1\index{#1@{\lowercase{#1}}}}
|
|
\newcommand{\IndexVerb}[1]{\T{#1}\index{#1@{\tt #1}}}
|
|
\newcommand{\IndexEmph}[1]{\emph{#1}\index{#1@{\lowercase{#1}}}}
|
|
\newcommand{\IndexTM}[1]{\index{#1 event@{``#1'' event}}\index{tag method!#1}}
|
|
\newcommand{\Def}[1]{\emph{#1}\index{#1}}
|
|
\newcommand{\IndexAPI}[1]{\T{#1}\DefAPI{#1}}
|
|
\newcommand{\IndexLIB}[1]{\T{#1}\DefLIB{#1}}
|
|
\newcommand{\DefLIB}[1]{\index{#1@{\tt #1}}}
|
|
\newcommand{\DefAPI}[1]{\index{C API!#1@{\tt #1}}}
|
|
\newcommand{\IndexKW}[1]{\index{keywords!#1@{\tt #1}}}
|
|
|
|
\newcommand{\ff}{$\bullet$\ }
|
|
|
|
\newcommand{\Version}{4.1 (beta)}
|
|
|
|
% changes to bnf.sty by LHF
|
|
\renewcommand{\Or}{$|$ }
|
|
\renewcommand{\rep}[1]{{\rm\{}\,#1\,{\rm\}}}
|
|
\renewcommand{\opt}[1]{{\rm [}\,#1\,{\,\rm]}}
|
|
\renewcommand{\ter}[1]{{\rm`{\tt#1}'}}
|
|
\newcommand{\NOTE}{\par\medskip\noindent\emph{NOTE}: }
|
|
|
|
\makeindex
|
|
|
|
\begin{document}
|
|
|
|
%{===============================================================
|
|
\thispagestyle{empty}
|
|
\pagestyle{empty}
|
|
|
|
{
|
|
\parindent=0pt
|
|
\vglue1.5in
|
|
{\LARGE\bf
|
|
The Programming Language Lua}
|
|
\hfill
|
|
\vskip4pt \hrule height 4pt width \hsize \vskip4pt
|
|
\hfill
|
|
Reference Manual for Lua version \Version
|
|
\\
|
|
\null
|
|
\hfill
|
|
Last revised on \today
|
|
\\
|
|
\vfill
|
|
\centering
|
|
\includegraphics[width=0.7\textwidth]{nolabel.ps}
|
|
\vfill
|
|
\vskip4pt \hrule height 2pt width \hsize
|
|
}
|
|
|
|
\newpage
|
|
\begin{quotation}
|
|
\parskip=10pt
|
|
\parindent=0pt
|
|
\footnotesize
|
|
\null\vfill
|
|
|
|
\noindent
|
|
Copyright \copyright\ 1994--2001 TeCGraf, PUC-Rio. All rights reserved.
|
|
|
|
Permission is hereby granted, without written agreement and without license
|
|
or royalty fees, to use, copy, modify, translate, and distribute
|
|
this software and its documentation (hereby called the ``package'')
|
|
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 package.
|
|
|
|
\item The origin of this package must not be misrepresented; you must not
|
|
claim that you wrote the original package. If you use this package 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 package.
|
|
\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 package 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 package
|
|
and its documentation.
|
|
|
|
The Lua language and this implementation have been entirely designed and
|
|
written by Waldemar Celes, Roberto Ierusalimschy, and Luiz Henrique de
|
|
Figueiredo at TeCGraf, PUC-Rio in Brazil.
|
|
|
|
This implementation contains no third-party code.
|
|
|
|
Copies of this manual can be obtained at
|
|
Lua's official web site,
|
|
\verb|www.lua.org|.
|
|
|
|
\bigskip
|
|
The Lua logo was designed by A. Nakonechny.
|
|
Copyright \copyright\ 1998. All rights reserved.
|
|
\end{quotation}
|
|
%}===============================================================
|
|
\newpage
|
|
|
|
\title{\Large\bf Reference Manual of the Programming Language Lua \Version}
|
|
|
|
\author{%
|
|
Roberto Ierusalimschy\qquad
|
|
Luiz Henrique de Figueiredo\qquad
|
|
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: 2001/10/31 20:31:38 $ $}}
|
|
|
|
\maketitle
|
|
|
|
\pagestyle{plain}
|
|
\pagenumbering{roman}
|
|
|
|
\begin{abstract}
|
|
\noindent
|
|
Lua is a powerful, light-weight programming language
|
|
designed for extending applications.
|
|
Lua is 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 opcodes,
|
|
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 Application Program Interface (API)
|
|
that allows interaction between Lua programs and their host C~programs.
|
|
\end{abstract}
|
|
|
|
\def\abstractname{Resumo}
|
|
\begin{abstract}
|
|
\noindent
|
|
Lua \'e uma linguagem de programa\c{c}\~ao
|
|
poderosa e leve,
|
|
projetada para estender aplica\c{c}\~oes.
|
|
Lua tamb\'em \'e frequentemente usada como uma linguagem de prop\'osito geral.
|
|
Lua combina programa\c{c}\~ao procedural
|
|
(com sintaxe semelhante \`a de Pascal)
|
|
com
|
|
poderosas constru\c{c}\~oes para descri\c{c}\~ao de dados,
|
|
baseadas em tabelas associativas e sem\^antica extens\'\i vel.
|
|
Lua \'e
|
|
tipada dinamicamente,
|
|
interpretada a partir de \emph{opcodes},
|
|
e tem gerenciamento autom\'atico de mem\'oria com coleta de lixo.
|
|
Essas caracter\'{\i}sticas fazem de Lua uma linguagem ideal para
|
|
configura\c{c}\~ao,
|
|
automa\c{c}\~ao (\emph{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{abstract}
|
|
|
|
\newpage
|
|
\null
|
|
\newpage
|
|
\tableofcontents
|
|
|
|
\newpage
|
|
\setcounter{page}{1}
|
|
\pagestyle{plain}
|
|
\pagenumbering{arabic}
|
|
|
|
%------------------------------------------------------------------------------
|
|
\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 powerful, light-weight
|
|
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} or simply the \emph{host}.
|
|
This host program can invoke functions to execute a piece of Lua code,
|
|
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 software,
|
|
and is provided as usual with no guarantees,
|
|
as stated in its copyright notice.
|
|
The implementation described in this manual is available
|
|
at Lua's official web site, \verb|www.lua.org|.
|
|
|
|
Like any other reference manual,
|
|
this document is dry in places.
|
|
For a discussion of the decisions behind the design of Lua,
|
|
see the papers below,
|
|
which are available at Lua's web site.
|
|
\begin{itemize}
|
|
\item
|
|
R.~Ierusalimschy, L.~H.~de Figueiredo, and W.~Celes.
|
|
Lua---an extensible extension language.
|
|
\emph{Software: Practice \& Experience} {\bf 26} \#6 (1996) 635--652.
|
|
\item
|
|
L.~H.~de Figueiredo, R.~Ierusalimschy, and W.~Celes.
|
|
The design and implementation of a language for extending applications.
|
|
\emph{Proceedings of XXI Brazilian Seminar on Software and Hardware} (1994) 273--283.
|
|
\item
|
|
L.~H.~de Figueiredo, R.~Ierusalimschy, and W.~Celes.
|
|
Lua: an extensible embedded language.
|
|
\emph{Dr. Dobb's Journal} {\bf 21} \#12 (Dec 1996) 26--33.
|
|
\item
|
|
R.~Ierusalimschy, L.~H.~de Figueiredo, and W.~Celes.
|
|
The evolution of an extension language: a history of Lua,
|
|
\emph{Proceedings of V Brazilian Symposium on Programming Languages} (2001) B-14--B-28.
|
|
\end{itemize}
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section{Lua Concepts}\label{concepts}
|
|
|
|
This section describes the main concepts of Lua as a language.
|
|
The syntax and semantics of Lua are described in \See{language}.
|
|
The discussion below is not purely conceptual;
|
|
it includes references to the C~API \see{API},
|
|
because Lua is designed to be embedded in host programs.
|
|
It also includes references to the standard libraries \see{libraries}.
|
|
|
|
|
|
\subsection{Environment and Chunks}
|
|
|
|
All statements in Lua are executed in a \Def{global environment}.
|
|
This environment 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.
|
|
If necessary,
|
|
the host programmer can create multiple independent global
|
|
environments, and freely switch between them \see{mangstate}.
|
|
|
|
The global environment can be manipulated by Lua code or
|
|
by the embedding program,
|
|
which can read and write global variables
|
|
using the API functions from the library that implements Lua.
|
|
|
|
The unit of execution of Lua is called a \Def{chunk}.
|
|
A chunk is simply a sequence of statements,
|
|
which are executed sequentially.
|
|
Statements are described in \See{stats}.
|
|
|
|
A chunk may be stored in a file or in a string inside the host program.
|
|
When a chunk is executed, first it is pre-compiled into opcodes for
|
|
a virtual machine,
|
|
and then the compiled statements are executed
|
|
by an interpreter for the virtual machine.
|
|
All modifications a chunk effects on the global environment persist
|
|
after the chunk ends.
|
|
|
|
Chunks may also be pre-compiled into binary form and stored in files;
|
|
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}
|
|
|
|
|
|
\subsection{\Index{Values and Types}} \label{TypesSec}
|
|
|
|
Lua is a \emph{dynamically typed language}.
|
|
This means that
|
|
variables do not have types; only values do.
|
|
Therefore, there are no type definitions in the language.
|
|
All values carry their own type.
|
|
|
|
There are seven \Index{basic types} in Lua:
|
|
\Def{nil}, \Def{boolean}, \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;
|
|
usually it represents the absence of a useful value.
|
|
\emph{Boolean} is the type of the values \False and \True.
|
|
In Lua, both \nil{} and \False make a condition fails,
|
|
and any other value makes it succeeds.
|
|
\emph{Number} represents real (double-precision floating-point) numbers.
|
|
\emph{String} represents arrays of characters.
|
|
\index{eight-bit clean}
|
|
Lua is 8-bit clean,
|
|
and so strings may contain any 8-bit character,
|
|
including embedded zeros (\verb|'\0'|) \see{lexical}.
|
|
|
|
Functions are considered \emph{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
|
|
\see{functioncall}.
|
|
|
|
The type \emph{userdata} is provided to allow
|
|
arbitrary \Index{C~pointers} to be stored in Lua variables.
|
|
This type corresponds to a \verb|void*|
|
|
and has no pre-defined operations in Lua,
|
|
except assignment and equality test.
|
|
However, by using \emph{metatables},
|
|
the programmer can define operations for userdata values
|
|
\see{metatables}.
|
|
Userdata values cannot be created or modified in Lua,
|
|
only through the C~API.
|
|
This guarantees the integrity of data owned by the host program.
|
|
|
|
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).
|
|
Moreover,
|
|
tables are \emph{heterogeneous},
|
|
that is, they can contain values of all types.
|
|
Tables are the sole data structuring mechanism in Lua;
|
|
they may be used not only to represent ordinary arrays,
|
|
but also symbol tables, sets, records, graphs, trees, etc.
|
|
To represent \Index{records}, Lua uses the field name as an index.
|
|
The language supports this representation by
|
|
providing \verb|a.name| as syntactic sugar for \verb|a["name"]|.
|
|
There are several convenient ways to create tables in Lua
|
|
\see{tableconstructor}.
|
|
|
|
Like indices, the value of a table field can be of any type.
|
|
In particular,
|
|
because functions are first class values,
|
|
table fields may contain functions.
|
|
So, tables may also carry \emph{methods}.
|
|
%The form \verb|t:f(x)| is syntactic sugar for \verb|t.f(t,x)|,
|
|
%which calls the method \verb|f| from the table \verb|t| passing
|
|
%the table itself as the first parameter \see{func-def}.
|
|
|
|
Tables, functions, and userdata values are \emph{objects}:
|
|
variables do not actually \emph{contain} these values,
|
|
only \emph{references} to them.
|
|
Assignment, parameter passing, and returns from functions
|
|
always manipulate references to these values,
|
|
and do not imply any kind of copy.
|
|
|
|
The library function \verb|type| returns a string describing the type
|
|
of a given value \see{pdf-type}.
|
|
|
|
\subsubsection{Metatables}
|
|
|
|
Each table or userdata object in Lua may have a \Index{metatable}.
|
|
|
|
You can change several aspects of the behavior
|
|
of an object by setting specific fields in its metatable.
|
|
For instance, when an object is the operand of an addition,
|
|
Lua checks for a function in the field \verb|"add"| in its metatable.
|
|
If it finds one,
|
|
Lua calls that function to perform the addition.
|
|
|
|
A metatable works as a kind of an extended ``type'' for the object.
|
|
Objects that share a metatable has identical behavior.
|
|
|
|
A metatable controls how an object behaves in arithmetic operations,
|
|
order comparisons, concatenation, and indexing.
|
|
A metatable can also defines a function to be called when a userdata
|
|
is garbage collected,
|
|
and how the garbage collector treats entries in a table
|
|
\see{weak-table}.
|
|
\See{metatable} gives a detailed description of which events you
|
|
can control with metatables.
|
|
|
|
You can query and change the metatable of an object
|
|
through the \verb|metatable| function \see{pdf-metatable}.
|
|
|
|
|
|
|
|
\subsection{\Index{Coercion}} \label{coercion}
|
|
|
|
Lua provides automatic conversion between string and number 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,
|
|
the number is converted to a string, in a reasonable format.
|
|
The format is chosen so that
|
|
a conversion from number to string then back to number
|
|
reproduces the original number \emph{exactly}.
|
|
For complete control of how numbers are converted to strings,
|
|
use the \verb|format| function \see{format}.
|
|
|
|
|
|
\subsection{Variables}
|
|
|
|
There are two kinds of variables in Lua:
|
|
global variables
|
|
and local variables.
|
|
\Index{Global variables} do not need to be declared.
|
|
Variables are assumed to be global unless explicitly declared local
|
|
\see{localvar}.
|
|
Before the first assignment, the value of a variable is \nil\ %
|
|
(this default can be changed for global variables; see \See{tag-method}).
|
|
|
|
An ordinary Lua table is used to keep all global names and values.
|
|
This table can be accessed and changed with the \verb|globals| function
|
|
\see{pdf-globals}.
|
|
|
|
\Index{Local variables} are lexically scoped.
|
|
Therefore, local variables can be freely accessed by functions
|
|
defined inside their scope \see{visibility}.
|
|
|
|
|
|
\subsection{Garbage Collection}\label{GC}
|
|
|
|
Lua does automatic memory management.
|
|
This means that
|
|
you do not have to worry about allocating memory for new objects
|
|
and freeing it when the objects are no longer needed.
|
|
Lua manages memory automatically by running
|
|
a \Index{garbage collector} from time to time
|
|
and
|
|
collecting all dead objects
|
|
(all objects that are no longer accessible from Lua).
|
|
All objects in Lua are subject to automatic management:
|
|
tables, userdata, functions, and strings.
|
|
|
|
Using the C~API,
|
|
you can set garbage-collector tag methods for user-defined
|
|
types based on userdata \see{tag-method}.
|
|
Lua calls those functions when it is about to free a userdata
|
|
of the corresponding type.
|
|
Using this facility, you can coordinate Lua's garbage collection
|
|
with external resource management
|
|
(such as closing files, network or database connections,
|
|
or freeing your own memory).
|
|
|
|
Lua uses two numbers to control its garbage-collection cycles.
|
|
One number counts how many bytes of dynamic memory Lua is using,
|
|
and the other is a threshold.
|
|
When the number of bytes crosses the threshold,
|
|
Lua runs the garbage collector,
|
|
which reclaims the memory of all dead objects.
|
|
The byte counter is corrected,
|
|
and then the threshold is reset to twice the value of the byte counter.
|
|
|
|
Through the C~API, you can query those numbers,
|
|
and change the threshold \see{GC-API}.
|
|
Setting the threshold to zero actually forces an immediate
|
|
garbage-collection cycle,
|
|
while setting it to a huge number effectively stops the garbage collector.
|
|
Using Lua code you have a more limited control over garbage-collection cycles,
|
|
through the functions \verb|gcinfo| and \verb|collectgarbage|
|
|
\see{predefined}.
|
|
|
|
|
|
\subsubsection{Weak Tables}\label{weak-table}
|
|
|
|
A \IndexEmph{weak table} is a table whose elements are
|
|
\IndexEmph{weak references}.
|
|
A weak reference is ignored by the garbage collector.
|
|
In other words,
|
|
if the only references to an object are weak references,
|
|
then the garbage collector will collect that object.
|
|
|
|
A weak table can have weak keys, weak values, or both.
|
|
A table with weak keys allows the collection of its keys,
|
|
but prevents the collection of its values.
|
|
A table with both weak keys and weak values allows the collection of
|
|
both keys and values
|
|
In any case, if either the key or the value is collected,
|
|
the whole pair is removed from the table.
|
|
The weakness of a table is controled by the
|
|
\verb|weakmode| field in its metatable \see{weakmode}.
|
|
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section{The Language}\label{language}
|
|
|
|
This section describes the lexis, the syntax, and the semantics of Lua.
|
|
In other words,
|
|
this section describes
|
|
which tokens are valid,
|
|
how they can be combined,
|
|
and what their combinations mean.
|
|
|
|
\subsection{Lexical Conventions} \label{lexical}
|
|
|
|
\IndexEmph{Identifiers} in Lua can be any string of letters,
|
|
digits, and underscores,
|
|
not beginning with a digit.
|
|
This coincides with the definition of identifiers in most languages.
|
|
(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 \IndexEmph{keywords} are reserved,
|
|
and cannot be used as identifiers:
|
|
\index{reserved words}
|
|
\begin{verbatim}
|
|
and break do else elseif
|
|
end false for function global
|
|
if in local nil not
|
|
or repeat return then true
|
|
until while
|
|
\end{verbatim}
|
|
(The keyword \rwd{global} is reserved for future use.)
|
|
|
|
Lua is a case-sensitive language:
|
|
\T{and} is a reserved word, but \T{And} and \T{\'and}
|
|
(if the locale permits) are two different, valid identifiers.
|
|
As a convention, identifiers starting with an underscore followed by
|
|
uppercase letters (such as \verb|_INPUT|)
|
|
are reserved for internal variables.
|
|
|
|
The following strings denote other \Index{tokens}:
|
|
\begin{verbatim}
|
|
+ - * / ^ %
|
|
~= <= >= < > == =
|
|
( ) { } [ ]
|
|
; : , . .. ...
|
|
\end{verbatim}
|
|
|
|
\IndexEmph{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|' (newline),
|
|
`\verb|\r|' (carriage return),
|
|
`\verb|\t|' (horizontal tab),
|
|
`\verb|\v|' (vertical tab),
|
|
`\verb|\\|' (backslash),
|
|
`\verb|\"|' (double quote),
|
|
`\verb|\'|' (single quote),
|
|
and `\verb|\|\emph{newline}' (that is, a backslash followed by a real newline,
|
|
which results in a newline in the string).
|
|
A character in a string may also be specified by its numerical value,
|
|
through the escape sequence `\verb|\|\emph{ddd}',
|
|
where \emph{ddd} is a sequence of up to three \emph{decimal} digits.
|
|
Strings in Lua may contain any 8-bit value, including embedded zeros,
|
|
which can be specified as `\verb|\000|'.
|
|
|
|
Literal strings can also be delimited by matching \verb|[[| $\ldots$ \verb|]]|.
|
|
Literals in this bracketed form may run for several lines,
|
|
may contain nested \verb|[[| $\ldots$ \verb|]]| pairs,
|
|
and do not interpret escape sequences.
|
|
For convenience,
|
|
when the opening \verb|[[| is immediately followed by a newline,
|
|
this newline is not included in the string.
|
|
This form is specially convenient for
|
|
writing strings that contain program pieces or
|
|
other quoted strings.
|
|
As an example, in a system using ASCII
|
|
(in which `\verb|a|' is coded as~97,
|
|
newline is coded as~10, and `\verb|1|' is coded as~49),
|
|
the following four literals below are equivalent:
|
|
\begin{verbatim}
|
|
1) "alo\n123\""
|
|
2) '\97lo\10\04923"'
|
|
3) [[alo
|
|
123"]]
|
|
4) [[
|
|
alo
|
|
123"]]
|
|
\end{verbatim}
|
|
|
|
\IndexEmph{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}
|
|
|
|
\IndexEmph{Comments} start anywhere outside a string with a
|
|
double hyphen (\verb|--|) and run until the end of the line.
|
|
(There are no block comments in Lua.)
|
|
For convenience,
|
|
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}.
|
|
|
|
|
|
\subsection{Variables}\label{variables}
|
|
|
|
Variables are places that store values.
|
|
%In Lua, variables are given by simple identifiers or by table fields.
|
|
|
|
A single name can denote a global variable, a local variable,
|
|
or a formal parameter in a function
|
|
(formal parameters are just local variables):
|
|
\begin{Produc}
|
|
\produc{var}{name}
|
|
\end{Produc}%
|
|
|
|
Square brackets are used to index a table:
|
|
\begin{Produc}
|
|
\produc{var}{prefixexp \ter{[} exp \ter{]}}
|
|
\end{Produc}%
|
|
The first expression should result in a table value,
|
|
and the second expression identifies a specific entry inside that table.
|
|
|
|
The syntax \verb|var.NAME| is just syntactic sugar for
|
|
\verb|var["NAME"]|:
|
|
\begin{Produc}
|
|
\produc{var}{prefixexp \ter{.} name}
|
|
\end{Produc}%
|
|
|
|
The expression denoting the table to be indexed has a restricted syntax;
|
|
\See{expressions} for details.
|
|
|
|
The meaning of assignments and evaluations of global and
|
|
indexed variables can be changed via metatables.
|
|
An assignment to a global variable \verb|x = val|
|
|
is equivalent to an assignment in the global table:
|
|
\verb|globals().x = val|.
|
|
An assignment to an indexed variable \verb|t[i] = val| is equivalent to
|
|
\verb|settable_event(t,i,val)|.
|
|
An access to a global variable \verb|x|
|
|
is equivalent to an access to the global table: \verb|globals().x|.
|
|
An access to an indexed variable \verb|t[i]| is equivalent to
|
|
a call \verb|gettable_event(t,i)|.
|
|
See \See{metatable} for a complete description of these functions.
|
|
(These functions are not defined in Lua.
|
|
We use them here only for explanatory purposes.)
|
|
|
|
|
|
\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{Chunks}\label{chunks}
|
|
The unit of execution of Lua is called a \Def{chunk}.
|
|
A chunk is simply a sequence of statements,
|
|
which are executed sequentially.
|
|
Each statement can be optionally followed by a semicolon:
|
|
\begin{Produc}
|
|
\produc{chunk}{\rep{stat \opt{\ter{;}}}}
|
|
\end{Produc}%
|
|
|
|
The notation used above is the usual extended BNF,
|
|
in which
|
|
\rep{\emph{a}}~means 0 or more \emph{a}'s, and
|
|
\opt{\emph{a}}~means an optional \emph{a}.
|
|
Non-terminals are shown in \emph{italics},
|
|
keywords are shown in {\bf bold},
|
|
and other terminal symbols are shown in {\tt typewriter} font,
|
|
enclosed in single quotes.
|
|
The complete syntax of Lua in EBNF is given on page~\pageref{BNF}.
|
|
|
|
\subsubsection{Blocks}
|
|
A \Index{block} is a list of statements;
|
|
syntactically, a block is equal to a chunk:
|
|
\begin{Produc}
|
|
\produc{block}{chunk}
|
|
\end{Produc}%
|
|
|
|
A block may be explicitly delimited:
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{do} block \rwd{end}}
|
|
\end{Produc}%
|
|
\IndexKW{do}
|
|
Explicit blocks are useful
|
|
to control the scope of local variables \see{localvar}.
|
|
Explicit blocks are also sometimes used to
|
|
add a \rwd{return} or \rwd{break} statement in the middle
|
|
of another block \see{control}.
|
|
|
|
\subsubsection{\Index{Assignment}} \label{assignment}
|
|
Lua 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.
|
|
The elements in both lists are separated by commas:
|
|
\begin{Produc}
|
|
\produc{stat}{varlist1 \ter{=} explist1}
|
|
\produc{varlist1}{var \rep{\ter{,} var}}
|
|
\produc{explist1}{exp \rep{\ter{,} exp}}
|
|
\end{Produc}%
|
|
Expressions are discussed in \See{expressions}.
|
|
|
|
Before the assignment,
|
|
the list of values is \emph{adjusted} to the length of
|
|
the list of variables.\index{adjustment}
|
|
If there are more values than are needed,
|
|
the excess values are thrown away.
|
|
If there are less values than are needed,
|
|
the list is extended with as many \nil's as needed.
|
|
If the list of expressions ends with a function call,
|
|
then all values returned by that function call enter in the list of values,
|
|
before the adjust
|
|
(except when the call is enclosed in parentheses; see \See{expressions}).
|
|
|
|
The assignment statement first evaluates all its expressions,
|
|
and only then makes the assignments.
|
|
So, the code
|
|
\begin{verbatim}
|
|
i = 3
|
|
i, a[i] = i+1, 20
|
|
\end{verbatim}
|
|
sets \verb|a[3]| to 20, but does not affect \verb|a[4]|
|
|
because the \verb|i| in \verb|a[i]| is evaluated
|
|
before it is assigned 4.
|
|
Similarly, the line
|
|
\begin{verbatim}
|
|
x, y = y, x
|
|
\end{verbatim}
|
|
exchanges the values of \verb|x| and \verb|y|.
|
|
|
|
\subsubsection{Control Structures}\label{control}
|
|
The control structures
|
|
\rwd{if}, \rwd{while}, and \rwd{repeat} have the usual meaning and
|
|
familiar syntax:
|
|
\index{while-do statement}\IndexKW{while}
|
|
\index{repeat-until statement}\IndexKW{repeat}\IndexKW{until}
|
|
\index{if-then-else statement}\IndexKW{if}\IndexKW{else}\IndexKW{elseif}
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{while} exp \rwd{do} block \rwd{end}}
|
|
\produc{stat}{\rwd{repeat} block \rwd{until} exp}
|
|
\produc{stat}{\rwd{if} exp \rwd{then} block
|
|
\rep{\rwd{elseif} exp \rwd{then} block}
|
|
\opt{\rwd{else} block} \rwd{end}}
|
|
\end{Produc}%
|
|
There is also a \rwd{for} statement in two flavors \see{for}.
|
|
|
|
The \Index{condition expression} \M{exp} of a
|
|
control structure may return any value.
|
|
All values different from \nil\ and \False\ are considered true;
|
|
both \False\ and \nil\ are considered false.
|
|
|
|
The \rwd{return} statement is used to return values
|
|
from a function or from a chunk.\IndexKW{return}
|
|
\label{return}%
|
|
\index{return statement}%
|
|
Functions and chunks may return more than one value,
|
|
and so the syntax for the \rwd{return} statement is
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{return} \opt{explist1}}
|
|
\end{Produc}%
|
|
|
|
The \rwd{break} statement can be used to terminate the execution of a
|
|
\rwd{while}, \rwd{repeat}, or \rwd{for} loop,
|
|
skipping to the next statement after the loop:\IndexKW{break}
|
|
\index{break statement}
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{break}}
|
|
\end{Produc}%
|
|
A \rwd{break} ends the innermost enclosing loop.
|
|
|
|
\NOTE
|
|
For syntactic reasons, \rwd{return} and \rwd{break}
|
|
statements can only be written as the \emph{last} statement of a block.
|
|
If it is really necessary to \rwd{return} or \rwd{break} in the
|
|
middle of a block,
|
|
then an explicit inner block can used,
|
|
as in the idioms
|
|
`\verb|do return end|' and
|
|
`\verb|do break end|',
|
|
because now \rwd{return} and \rwd{break} are the last statements in
|
|
their (inner) blocks.
|
|
In practice,
|
|
these idioms are only used during debugging.
|
|
(For instance, a line `\verb|do return end|' can be added at the
|
|
beginning of a chunk for syntax checking only.)
|
|
|
|
\subsubsection{For Statement} \label{for}\index{for statement}
|
|
|
|
The \rwd{for} statement has two forms,
|
|
one for numbers and one generic.
|
|
\IndexKW{for}\IndexKW{in}
|
|
|
|
The numerical \rwd{for} loop repeats a block of code while a
|
|
control variables runs through an arithmetic progression.
|
|
It has the following syntax:
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{for} name \ter{=} exp \ter{,} exp \opt{\ter{,} exp}
|
|
\rwd{do} block \rwd{end}}
|
|
\end{Produc}%
|
|
The \emph{block} is repeated for \emph{name} starting at the value of
|
|
the first \emph{exp}, until it reaches the second \emph{exp} by steps of the
|
|
third \emph{exp}.
|
|
More precisely, a \rwd{for} statement like
|
|
\begin{verbatim}
|
|
for var = e1, e2, e3 do block end
|
|
\end{verbatim}
|
|
is equivalent to the code:
|
|
\begin{verbatim}
|
|
do
|
|
local var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3)
|
|
if not (var and _limit and _step) then error() end
|
|
while (_step>0 and var<=_limit) or (_step<=0 and var>=_limit) do
|
|
block
|
|
var = var+_step
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
Note the following:
|
|
\begin{itemize}\itemsep=0pt
|
|
\item Both the limit and the step are evaluated only once,
|
|
before the loop starts.
|
|
\item \verb|_limit| and \verb|_step| are invisible variables.
|
|
The names are here for explanatory purposes only.
|
|
\item The behavior is \emph{undefined} if you assign to \verb|var| inside
|
|
the block.
|
|
\item If the third expression (the step) is absent, then a step of~1 is used.
|
|
\item You can use \rwd{break} to exit a \rwd{for} loop.
|
|
\item The loop variable \verb|var| is local to the statement;
|
|
you cannot use its value after the \rwd{for} ends or is broken.
|
|
If you need the value of the loop variable \verb|var|,
|
|
then assign it to another variable before breaking or exiting the loop.
|
|
\end{itemize}
|
|
|
|
The generic \rwd{for} statement works both over tables
|
|
and over functions.
|
|
When used with a \IndexEmph{generator function},
|
|
it calls this function to produce a new value for each iteration,
|
|
stopping when the new value is \nil.
|
|
It has the following syntax:
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{for} name \opt{\ter{,} name} \rwd{in} exp
|
|
\rwd{do} block \rwd{end}}
|
|
\end{Produc}%
|
|
A \rwd{for} statement like
|
|
\begin{verbatim}
|
|
for var1, var2 in exp do block end
|
|
\end{verbatim}
|
|
is equivalent to the code:
|
|
\begin{verbatim}
|
|
do
|
|
local _f = exp
|
|
while 1 do
|
|
local var1, var2 = _f()
|
|
if var1 == nil then break end
|
|
block
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
Note the following:
|
|
\begin{itemize}\itemsep=0pt
|
|
\item \verb|exp| is evaluated only once.
|
|
Its result is the function that will be evaluated for each loop.
|
|
\item \verb|_f| is an invisible variable.
|
|
The name is here for explanatory purposes only.
|
|
\item The behavior is \emph{undefined} if you assign to \verb|var1|
|
|
or \verb|var2| inside the block.
|
|
\item You can use \rwd{break} to exit a \rwd{for} loop.
|
|
\item The loop variables \verb|var1| and \verb|var2| are
|
|
local to the statement;
|
|
you cannot use their values after the \rwd{for} ends.
|
|
If you need these values,
|
|
then assign them to other variables before breaking or exiting the loop.
|
|
\item The absence of the optional variable \verb|var2| does not
|
|
change the meaning of the loop.
|
|
\end{itemize}
|
|
|
|
If the generator is a table \verb|t|,
|
|
then the loop works as if it has received the following generator function:
|
|
\begin{verbatim}
|
|
local k,v = nil
|
|
function generator ()
|
|
k,v = next(t, k)
|
|
return k,v
|
|
end
|
|
\end{verbatim}
|
|
That is, the loop iterates over the (key,value) pairs of the table.
|
|
|
|
|
|
\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.
|
|
The declaration may include an initial assignment:\IndexKW{local}
|
|
\begin{Produc}
|
|
\produc{stat}{\rwd{local} namelist \opt{\ter{=} explist1}}
|
|
\produc{namelist}{name \rep{\ter{,} name}}
|
|
\end{Produc}%
|
|
If present, an initial assignment has the same semantics
|
|
of a multiple assignment \see{assignment}.
|
|
Otherwise, all variables are initialized with \nil.
|
|
|
|
A chunk is also a block \see{chunks},
|
|
and so local variables can be declared outside any explicit block.
|
|
Such local variables die when the chunk ends.
|
|
|
|
Visibility rules for local variables are explained in \See{visibility}.
|
|
|
|
|
|
\subsection{\Index{Expressions}}\label{expressions}
|
|
|
|
%\subsubsection{\Index{Basic Expressions}}
|
|
The basic expressions in Lua are the following:
|
|
\begin{Produc}
|
|
\produc{exp}{prefixexp}
|
|
\produc{exp}{\rwd{nil} \Or \rwd{false} \Or \rwd{true}}
|
|
\produc{exp}{Number}
|
|
\produc{exp}{Literal}
|
|
\produc{exp}{function}
|
|
\produc{exp}{tableconstructor}
|
|
\produc{prefixexp}{var \Or functioncall \Or \ter{(} exp \ter{)}}
|
|
\end{Produc}%
|
|
\IndexKW{nil}
|
|
|
|
An expression enclosed in parentheses always results in only one value.
|
|
Thus,
|
|
\verb|(f(x,y,z))| is always a single value,
|
|
even if \verb|f| returns several values.
|
|
(The value of \verb|(f(x,y,z))| is the first value returned by \verb|f|
|
|
or \nil\ if \verb|f| does not return any values.)
|
|
|
|
\emph{Numbers} and \emph{literal strings} are explained in \See{lexical};
|
|
variables are explained in \See{variables};
|
|
function definitions are explained in \See{func-def};
|
|
function calls are explained in \See{functioncall};
|
|
table constructors are explained in \See{tableconstructor}.
|
|
|
|
Expressions can also be built with arithmetic operators, relational operators,
|
|
and logical operadors, all of which are explained below.
|
|
|
|
\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 \see{coercion},
|
|
then all operations except exponentiation have the usual meaning,
|
|
while exponentiation calls a global function \verb|pow|;
|
|
otherwise, an appropriate tag method is called \see{tag-method}.
|
|
The standard mathematical library defines function \verb|pow|,
|
|
giving the expected meaning to \Index{exponentiation}
|
|
\see{mathlib}.
|
|
|
|
\subsubsection{Relational Operators}\label{rel-ops}
|
|
The \Index{relational operators} in Lua are
|
|
\begin{verbatim}
|
|
== ~= < > <= >=
|
|
\end{verbatim}
|
|
These operators always result in \False\ or \True.
|
|
|
|
Equality (\verb|==|) first compares the type of its operands.
|
|
If the types are different, then the result is \False.
|
|
Otherwise, the values of the operands are compared.
|
|
Numbers and strings are compared in the usual way.
|
|
Tables, userdata, and functions are compared \emph{by reference},
|
|
that is,
|
|
two tables are considered equal only if they are the \emph{same} table.
|
|
|
|
Every time you create a new table (or userdata, or function),
|
|
this new value is different from any previously existing value.
|
|
|
|
\NOTE
|
|
The conversion rules of \See{coercion}
|
|
\emph{do not} apply to equality comparisons.
|
|
Thus, \verb|"0"==0| evaluates to \emph{false},
|
|
and \verb|t[0]| and \verb|t["0"]| denote different
|
|
entries in a table.
|
|
\medskip
|
|
|
|
The operator \verb|~=| is exactly the negation of equality (\verb|==|).
|
|
|
|
The order 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 according to the current locale.
|
|
Otherwise, the ``lt'' tag method is called \see{tag-method}.
|
|
|
|
|
|
\subsubsection{Logical Operators}
|
|
The \Index{logical operators} in Lua are
|
|
\index{and}\index{or}\index{not}
|
|
\begin{verbatim}
|
|
and or not
|
|
\end{verbatim}
|
|
Like the control structures \see{control},
|
|
all logical operators consider both \False\ and \nil\ as false
|
|
and anything else as true.
|
|
\IndexKW{and}\IndexKW{or}\IndexKW{not}
|
|
|
|
The operator \rwd{not} always return \False\ or \True.
|
|
|
|
The conjunction operator \rwd{and} returns its first argument
|
|
if its value is \False\ or \nil;
|
|
otherwise, \rwd{and} returns its second argument.
|
|
The disjunction operator \rwd{or} returns its first argument
|
|
if it is different from \nil and \False;
|
|
otherwise, \rwd{or} returns its second argument.
|
|
Both \rwd{and} and \rwd{or} use \Index{short-cut evaluation},
|
|
that is,
|
|
the second operand is evaluated only if necessary.
|
|
For example,
|
|
\begin{verbatim}
|
|
10 or error() -> 10
|
|
nil or "a" -> "a"
|
|
nil and 10 -> nil
|
|
false and error() -> false
|
|
false and nil -> false
|
|
false or nil -> nil
|
|
10 and 20 -> 20
|
|
\end{verbatim}
|
|
|
|
%There are two useful Lua idioms that use logical operators.
|
|
%The first idiom is
|
|
%\begin{verbatim}
|
|
% x = x or v
|
|
%\end{verbatim}
|
|
%which is equivalent to
|
|
%\begin{verbatim}
|
|
% if not x then x = v end
|
|
%\end{verbatim}
|
|
%This idiom sets \verb|x| to a default value \verb|v| when \verb|x| is not set
|
|
%(provided that \verb|x| is not a boolean value).
|
|
|
|
%The second idiom is
|
|
%\begin{verbatim}
|
|
% x = a and b or c
|
|
%\end{verbatim}
|
|
%which should be read as \verb|x = (a and b) or c|.
|
|
%This idiom is equivalent to
|
|
%\begin{verbatim}
|
|
% if a then x = b else x = c end
|
|
%\end{verbatim}
|
|
%provided that \verb|b| is not \nil.
|
|
|
|
\subsubsection{Concatenation} \label{concat}
|
|
The string \Index{concatenation} operator in Lua is
|
|
denoted by two dots (`\verb|..|').
|
|
If both operands are strings or numbers, then they are converted to
|
|
strings according to the rules mentioned in \See{coercion}.
|
|
Otherwise, the ``concat'' tag method is called \see{tag-method}.
|
|
|
|
\subsubsection{Precedence}
|
|
\Index{Operator precedence} in Lua follows the table below,
|
|
from lower to higher priority:
|
|
\begin{verbatim}
|
|
and or
|
|
< > <= >= ~= ==
|
|
..
|
|
+ -
|
|
* /
|
|
not - (unary)
|
|
^
|
|
\end{verbatim}
|
|
All binary operators are left associative,
|
|
except for \verb|^| (exponentiation),
|
|
which is right associative.
|
|
\NOTE
|
|
The pre-compiler may rearrange the order of evaluation of
|
|
associative operators,
|
|
and may exchange the operands of commutative operators,
|
|
as long as these optimizations do not change normal results.
|
|
However, these optimizations may change some results
|
|
if you define non-associative (or non-commutative)
|
|
tag methods for these operators.
|
|
|
|
\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 of its fields.
|
|
The general syntax for constructors is
|
|
\begin{Produc}
|
|
\produc{tableconstructor}{\ter{\{} \opt{fieldlist} \ter{\}}}
|
|
\produc{fieldlist}{field \rep{fieldsep field} \opt{fieldsep}}
|
|
\produc{field}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp \Or exp}
|
|
\produc{fieldsep}{\ter{,} \Or \ter{;}}
|
|
\end{Produc}%
|
|
|
|
Each field of the form \verb|[exp1] = exp2| adds to the new table an entry
|
|
with key \verb|exp1| and value \verb|exp2|.
|
|
A field of the form \verb|name = exp| is equivalent to
|
|
\verb|["name"] = exp|.
|
|
Finally, fields of the form \verb|exp| add to the new table entries
|
|
with the given expression indexed by consecutive numerical integers,
|
|
starting with 1.
|
|
Fields in the other formats do not affect this counting.
|
|
For example,
|
|
\begin{verbatim}
|
|
a = {[f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45}
|
|
\end{verbatim}
|
|
is equivalent to
|
|
\begin{verbatim}
|
|
do
|
|
local temp = {}
|
|
temp[f(1)] = g
|
|
temp[1] = "x" -- 1st exp
|
|
temp[2] = "y" -- 2nd exp
|
|
temp.x = 1 -- temp["x"] = 1
|
|
temp[3] = f(x) -- 3rd exp
|
|
temp[30] = 23
|
|
temp[4] = 45 -- 4th exp
|
|
a = temp
|
|
end
|
|
\end{verbatim}
|
|
|
|
If the last expression in the list is a function call,
|
|
then all values returned by the call enter the list consecutively
|
|
\see{functioncall}.
|
|
If you want to avoid this,
|
|
enclose the function call in parentheses.
|
|
|
|
The field list may have an optional trailing separator,
|
|
as a convenience for machine-generated code.
|
|
|
|
|
|
\subsubsection{Function Calls} \label{functioncall}
|
|
A \Index{function call} in Lua has the following syntax:
|
|
\begin{Produc}
|
|
\produc{functioncall}{prefixexp args}
|
|
\end{Produc}%
|
|
In a function call,
|
|
first \M{prefixexp} and \M{args} are evaluated.
|
|
If the value of \M{prefixexp} 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{prefixexp},
|
|
followed by the original call arguments
|
|
\see{tag-method}.
|
|
|
|
The form
|
|
\begin{Produc}
|
|
\produc{functioncall}{prefixexp \ter{:} name args}
|
|
\end{Produc}%
|
|
can be used to call ``methods''.
|
|
A call \verb|v:name(...)|
|
|
is syntactic sugar for \verb|v.name(v, ...)|,
|
|
except that \verb|v| is evaluated only once.
|
|
|
|
Arguments have the following syntax:
|
|
\begin{Produc}
|
|
\produc{args}{\ter{(} \opt{explist1} \ter{)}}
|
|
\produc{args}{tableconstructor}
|
|
\produc{args}{Literal}
|
|
\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 argument 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 argument list is a single literal string.
|
|
|
|
Because a function can return any number of results
|
|
\see{return},
|
|
the number of results must be adjusted before they are used.
|
|
If the function is called as a statement \see{funcstat},
|
|
then its return list is adjusted to~0 elements,
|
|
thus discarding all returned values.
|
|
If the function is called inside another expression,
|
|
or in the middle of a list of expressions,
|
|
then its return list is adjusted to~1 element,
|
|
thus discarding all returned values but the first one.
|
|
If the function is called as the last element of a list of expressions,
|
|
then no adjustment is made
|
|
(unless the call is enclosed in parentheses).
|
|
|
|
Here are some examples:
|
|
\begin{verbatim}
|
|
f() -- adjusted to 0 results
|
|
g(f(), x) -- f() is adjusted to 1 result
|
|
g(x, f()) -- g gets x plus all values returned by f()
|
|
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()
|
|
return x,y,f() -- returns x, y, and all values returned by f()
|
|
{f()} -- creates a list with all values returned by f()
|
|
{f(), nil} -- f() is adjusted to 1 result
|
|
\end{verbatim}
|
|
|
|
If you enclose a function call in parentheses,
|
|
then it is adjusted to return exactly one value:
|
|
\begin{verbatim}
|
|
return x,y,(f()) -- returns x, y, and the first value from f()
|
|
{(f())} -- creates a table with exactly one element
|
|
\end{verbatim}
|
|
|
|
As an exception to the format-free syntax of Lua,
|
|
you cannot put a line break before the \verb|(| in a function call.
|
|
That restriction avoids some ambiguities in the language.
|
|
If you write
|
|
\begin{verbatim}
|
|
a = f
|
|
(g).x(a)
|
|
\end{verbatim}
|
|
Lua would read that as \verb|a = f(g).x(a)|.
|
|
So, if you want two statements, you must add a semi-colon between them.
|
|
If you actually want to call \verb|f|,
|
|
you must remove the line break before \verb|(g)|.
|
|
|
|
|
|
\subsubsection{\Index{Function Definitions}} \label{func-def}
|
|
|
|
The syntax for function definition is\IndexKW{function}
|
|
\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 \rep{\ter{.} name} \opt{\ter{:} name}}
|
|
\end{Produc}%
|
|
The statement
|
|
\begin{verbatim}
|
|
function f () ... end
|
|
\end{verbatim}
|
|
is syntactic sugar for
|
|
\begin{verbatim}
|
|
f = function () ... end
|
|
\end{verbatim}
|
|
and the statement
|
|
\begin{verbatim}
|
|
function t.a.b.c.f () ... end
|
|
\end{verbatim}
|
|
is syntactic sugar for
|
|
\begin{verbatim}
|
|
t.a.b.c.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,
|
|
the function is \emph{instantiated} (or \emph{closed}).
|
|
This function instance (or \emph{closure})
|
|
is the final value of the expression.
|
|
Different instances of the same function
|
|
may refer to different non-local variables \see{visibility}.
|
|
|
|
Parameters act as local variables,
|
|
initialized with the argument values:
|
|
\begin{Produc}
|
|
\produc{parlist1}{namelist \opt{\ter{,} \ter{\ldots}}}
|
|
\produc{parlist1}{\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,
|
|
unless the function is a \Def{vararg function},
|
|
which is
|
|
indicated by three dots (`\verb|...|') at the end of its parameter list.
|
|
A vararg function does not adjust its argument list;
|
|
instead, it collects all extra arguments into an implicit parameter,
|
|
called \IndexLIB{arg}.
|
|
The value of \verb|arg| is a table,
|
|
with a field~\verb|n| whose value is the number of extra arguments,
|
|
and the extra arguments at positions 1,~2,~\ldots,~\verb|n|.
|
|
|
|
As an example, consider the following definitions:
|
|
\begin{verbatim}
|
|
function f(a, b) end
|
|
function g(a, b, ...) end
|
|
function r() return 1,2,3 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
|
|
f(r(), 10) a=1, b=10
|
|
f(r()) a=1, b=2
|
|
|
|
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}
|
|
g(5, r()) a=5, b=1, arg={2, 3; n=2}
|
|
\end{verbatim}
|
|
|
|
Results are returned using the \rwd{return} statement \see{return}.
|
|
If control reaches the end of a function
|
|
without encountering a \rwd{return} statement,
|
|
then the function returns with no results.
|
|
|
|
The \emph{colon} syntax
|
|
is used for defining \IndexEmph{methods},
|
|
that is, functions that have an implicit extra parameter \IndexVerb{self}.
|
|
Thus, the statement
|
|
\begin{verbatim}
|
|
function t.a.b.c:f (...) ... end
|
|
\end{verbatim}
|
|
is syntactic sugar for
|
|
\begin{verbatim}
|
|
t.a.b.c.f = function (self, ...) ... end
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Visibility Rules} \label{visibility}
|
|
\index{visibility}
|
|
|
|
Lua is a lexically scoped language.
|
|
The scope of local variables begins at the first statement \emph{after}
|
|
their declaration and lasts until the end of the innermost block that
|
|
includes the declaration.
|
|
For instance:
|
|
\begin{verbatim}
|
|
x = 10 -- global variable
|
|
do -- new block
|
|
local x = x -- new `x', with value 10
|
|
print(x) --> 10
|
|
x = x+1
|
|
do -- another block
|
|
local x = x+1 -- another x
|
|
print(x) --> 12
|
|
end
|
|
print(x) --> 11
|
|
end
|
|
print(x) --> 10 (the global one)
|
|
\end{verbatim}
|
|
Notice that, in a declaration like \verb|local x = x|,
|
|
the new \verb|x| being declared is not in scope yet,
|
|
so the second \verb|x| refers to the ``outside'' variable.
|
|
|
|
Because of this \Index{lexical scoping} rules,
|
|
local variables can be freely accessed by functions
|
|
defined inside their scope.
|
|
For instance:
|
|
\begin{verbatim}
|
|
local counter = 0
|
|
function inc (x)
|
|
counter = counter + x
|
|
return counter
|
|
end
|
|
\end{verbatim}
|
|
|
|
Notice that each execution of a \rwd{local} statement
|
|
``creates'' new local variables.
|
|
Consider the following example:
|
|
\begin{verbatim}
|
|
a = {}
|
|
local x = 20
|
|
for i=1,10 do
|
|
local y = 0
|
|
a[i] = function () y=y+1; return x+y end
|
|
end
|
|
\end{verbatim}
|
|
In that code,
|
|
each function uses a different \verb|y| variable,
|
|
while all of them share the same \verb|x|.
|
|
|
|
|
|
|
|
\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,
|
|
the function \verb|_ERRORMESSAGE| is called \DefLIB{_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_call|)
|
|
is terminated, returning an error condition.
|
|
|
|
Memory allocation errors are an exception to the previous rule.
|
|
When memory allocation fails, Lua may not be able to execute the
|
|
\verb|_ERRORMESSAGE| function.
|
|
So, for this kind of error, Lua does not call
|
|
the \verb|_ERRORMESSAGE| function;
|
|
instead, the corresponding function from the library
|
|
returns immediately with a special error code (\verb|LUA_ERRMEM|).
|
|
This and other error codes are defined in \verb|lua.h|
|
|
\see{luado}.
|
|
|
|
The only argument to \verb|_ERRORMESSAGE| is a string
|
|
describing the error.
|
|
The default definition for
|
|
this function calls \verb|_ALERT|, \DefLIB{_ALERT}
|
|
which prints the message to \verb|stderr| \see{alert}.
|
|
The standard I/O library redefines \verb|_ERRORMESSAGE|
|
|
and uses the debug interface \see{debugI}
|
|
to print some extra information,
|
|
such as a call-stack traceback.
|
|
|
|
Lua code can explicitly generate an error by calling the
|
|
function \verb|error| \see{pdf-error}.
|
|
Lua code can ``catch'' an error using the function
|
|
\verb|call| \see{pdf-call}.
|
|
|
|
|
|
\subsection{Metatables} \label{metatable}
|
|
|
|
Every table and userdata value in Lua may have a \emph{metatable}.
|
|
This \IndexEmph{metatable} is a table that defines the behavior of
|
|
the original table and userdata under some operations.
|
|
You can query and change the metatable of an object with
|
|
function \verb|metatable| \see{pdf-metatable}.
|
|
|
|
For each of these operations Lua associates a specific key.
|
|
When Lua performs one of these operations over a table or a userdata,
|
|
if checks whether that object has a metatable with the corresponding key.
|
|
If so, the value associated with that key (the \IndexEmph{handler})
|
|
controls how Lua will perform the operation.
|
|
|
|
Metatables control the operations listed next.
|
|
Each operation is identified by its corresponding key.
|
|
The semantics of these operations is better explained by a Lua function
|
|
describing how the interpreter executes that operation.
|
|
%Each function shows how a handler is called,
|
|
%its arguments (that is, its signature),
|
|
%its results,
|
|
%and the default behavior in the absence of a handler.
|
|
The code shown here in Lua is only illustrative;
|
|
the real behavior is hard coded in the interpreter,
|
|
and it is much more efficient than this simulation.
|
|
All functions used in these descriptions
|
|
(\verb|rawget|, \verb|tonumber|, \verb|call|, etc.)\
|
|
are described in \See{predefined}.
|
|
|
|
\begin{description}
|
|
|
|
\item[``add'':]\IndexTM{add}
|
|
the \verb|+| operation.
|
|
|
|
The function \verb|getbinhandler| below defines how Lua chooses a handler
|
|
for a binary operation.
|
|
First, Lua tries the first operand.
|
|
If its type does not define a handler for the operation,
|
|
then Lua tries the second operand.
|
|
\begin{verbatim}
|
|
function getbinhandler (op1, op2, event)
|
|
return metatable(op1)[event] or metatable(op2)[event]
|
|
end
|
|
\end{verbatim}
|
|
Using this function,
|
|
the behavior of the ``add'' operation is
|
|
\begin{verbatim}
|
|
function add_op (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 h = getbinhandler(op1, op2, "add")
|
|
if h then
|
|
-- call the handler with both operands
|
|
return h(op1, op2)
|
|
else -- no handler available: default behavior
|
|
error("unexpected type at arithmetic operation")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``sub'':]\IndexTM{sub}
|
|
the \verb|-| operation.
|
|
Behavior similar to the ``add'' operation.
|
|
|
|
\item[``mul'':]\IndexTM{mul}
|
|
the \verb|*| operation.
|
|
Behavior similar to the ``add'' operation.
|
|
|
|
\item[``div'':]\IndexTM{div}
|
|
the \verb|/| operation.
|
|
Behavior similar to the ``add'' operation.
|
|
|
|
\item[``pow'':]\IndexTM{pow}
|
|
the \verb|^| operation (exponentiation) operation.
|
|
\begin{verbatim} ??
|
|
function pow_op (op1, op2)
|
|
local h = getbinhandler(op1, op2, "pow")
|
|
if h then
|
|
-- call the handler with both operands
|
|
return h(op1, op2)
|
|
else -- no handler available: default behavior
|
|
error("unexpected type at arithmetic operation")
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``unm'':]\IndexTM{unm}
|
|
the unary \verb|-| operation.
|
|
\begin{verbatim}
|
|
function unm_op (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 handler from the operand;
|
|
local h = metatable(op).unm
|
|
if h then
|
|
-- call the handler with the operand and nil
|
|
return h(op, nil)
|
|
else -- no handler available: default behavior
|
|
error("unexpected type at arithmetic operation")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``lt'':]\IndexTM{lt}
|
|
the \verb|<| operation.
|
|
\begin{verbatim}
|
|
function lt_op (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 h = getbinhandler(op1, op2, "lt")
|
|
if h then
|
|
return h(op1, op2)
|
|
else
|
|
error("unexpected type at comparison");
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
The other order operators also use the \verb|lt_op| function,
|
|
according to the usual equivalences:
|
|
\begin{verbatim}
|
|
a>b <=> b<a
|
|
a<=b <=> not (b<a)
|
|
a>=b <=> not (a<b)
|
|
\end{verbatim}
|
|
|
|
\item[``concat'':]\IndexTM{concatenation}
|
|
the \verb|..| (concatenation) operation.
|
|
\begin{verbatim}
|
|
function concat_op (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 h = getbinhandler(op1, op2, "concat")
|
|
if h then
|
|
return h(op1, op2)
|
|
else
|
|
error("unexpected type for concatenation")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``index'':]\IndexTM{index}
|
|
This handler is called when Lua tries to retrieve the value of an index
|
|
not present in a table.
|
|
See the ``gettable'' operation for its semantics.
|
|
|
|
\item[``gettable'':]\IndexTM{gettable}
|
|
called whenever Lua accesses an indexed variable.
|
|
\begin{verbatim}
|
|
function gettable_op (table, key)
|
|
local h = metatable(table).gettable
|
|
if h == nil then
|
|
if type(table) ~= "table" then
|
|
error("indexed expression not a table");
|
|
else
|
|
local v = rawget(table, key)
|
|
if v ~= nil then return v end
|
|
h = metatable(table).index
|
|
if h == nil then return nil end
|
|
end
|
|
end
|
|
if type(h) == 'function' then
|
|
return h(table, key) -- call the handler
|
|
else return h[key] -- or repeat operation with it
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``settable'':]\IndexTM{settable}
|
|
called when Lua assigns to an indexed variable.
|
|
\begin{verbatim}
|
|
function settable_event (table, key, value)
|
|
local h = metatable(table).settable
|
|
if h == nil then
|
|
if type(table) ~= "table" then
|
|
error("indexed expression not a table")
|
|
rawset(table, key, value)
|
|
else
|
|
if type(h) == 'function' then
|
|
h(table, key, value) -- call the handler
|
|
else h[key] = value -- or repeat operation with it
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\item[``call'':]\IndexTM{call}
|
|
called when Lua calls a value.
|
|
\begin{verbatim}
|
|
function function_op (func, ...)
|
|
if type(func) == "function" then
|
|
return func(unpack(arg)) -- regular call
|
|
else
|
|
local h = metatable(func).call
|
|
if h then
|
|
tinsert(arg, 1, func)
|
|
return h(unpack(arg))
|
|
else
|
|
error("call expression not a function")
|
|
end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\end{description}
|
|
|
|
\subsubsection{Metatables and Garbage collection}
|
|
|
|
Metatables also control some aspects of the garbage collector.
|
|
First, they are used to define \IndexEmph{finalizer} methods
|
|
for userdata values.
|
|
For each userdata to be collected,
|
|
Lua does the equivalent of the following function:
|
|
\begin{verbatim}
|
|
function gc_op (obj)
|
|
local h = metatable(obj).gc
|
|
if h then
|
|
h(obj)
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
In a garbage-collection cycle,
|
|
the finalizers for userdata are called in \emph{reverse}
|
|
order of their creation,
|
|
that is, the first finalizer to be called is the one associated
|
|
with the last userdata created in the program
|
|
(among those to be collected in this cycle).
|
|
|
|
Second, metatables control the weakmode of tables \see{weak-table}.
|
|
The weakmode of a table \verb|t| is defined by a string:
|
|
\label{weakmode}
|
|
\begin{verbatim}
|
|
s = metatable(t).weakmode
|
|
\end{verbatim}
|
|
Valid values for this string are \verb|"k"| for weak keys,
|
|
\verb|"v"| for weak values,
|
|
and \verb|"kv"| for both.
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section{The Application Program Interface}\label{API}
|
|
\index{C API}
|
|
This section describes the API for Lua, that is,
|
|
the set of C~functions available to the host program to communicate
|
|
with Lua.
|
|
All API functions and related types and constants
|
|
are declared in the header file \verb|lua.h|.
|
|
|
|
\NOTE
|
|
Even when we use the term ``function'',
|
|
any facility in the API may be provided as a \emph{macro} instead.
|
|
All such macros use each of its arguments exactly once
|
|
(except for the first argument, which is always a Lua state),
|
|
and so do not generate hidden side-effects.
|
|
|
|
|
|
\subsection{States} \label{mangstate}
|
|
|
|
The Lua library is fully reentrant:
|
|
it has no global variables.
|
|
\index{state}
|
|
The whole state of the Lua interpreter
|
|
(global variables, stack, tag methods, etc.)\
|
|
is stored in a dynamically allocated structure of type \verb|lua_State|;
|
|
\DefAPI{lua_State}
|
|
this state must be passed as the first argument to
|
|
every function in the library (except \verb|lua_open| below).
|
|
|
|
Before calling any API function,
|
|
you must create a state by calling
|
|
\begin{verbatim}
|
|
lua_State *lua_open (int stacksize);
|
|
\end{verbatim}
|
|
\DefAPI{lua_open}
|
|
The sole argument to this function is the stack size for the interpreter.
|
|
(Each function call needs one stack position for each argument, local variable,
|
|
and temporary value, plus one position for book-keeping.
|
|
The stack must also have some 20 extra positions available.
|
|
For very small implementations, without recursive functions,
|
|
a stack size of~100 should be enough.)
|
|
If \verb|stacksize| is zero,
|
|
then a default size of~1024 is used.
|
|
|
|
To release a state created with \verb|lua_open|, call
|
|
\begin{verbatim}
|
|
void lua_close (lua_State *L);
|
|
\end{verbatim}
|
|
\DefAPI{lua_close}
|
|
This function destroys all objects in the given Lua environment
|
|
(calling the corresponding garbage-collection tag methods, if any)
|
|
and frees all dynamic memory used by that state.
|
|
Usually, you do not need to call this function,
|
|
because all resources are naturally released when your program ends.
|
|
On the other hand,
|
|
long-running programs ---
|
|
like a daemon or a web server ---
|
|
might need to release states as soon as they are not needed,
|
|
to avoid growing too large.
|
|
|
|
With the exception of \verb|lua_open|,
|
|
all functions in the Lua API need a state as their first argument.
|
|
|
|
|
|
\subsection{Threads}
|
|
|
|
Lua offers a partial support for multiple threads of execution.
|
|
If you have a C~library that offers multi-threading or co-routines,
|
|
then Lua can cooperate with it to implement the equivalent facility in Lua.
|
|
The following function creates a new ``thread'' in Lua:
|
|
\begin{verbatim}
|
|
lua_State *lua_newthread (lua_State *L, int stacksize);
|
|
\end{verbatim}
|
|
\DefAPI{lua_newthread}
|
|
The new state returned by this function shares with the original state
|
|
all global environment (such as tables, tag methods, etc.),
|
|
but has an independent run-time stack.
|
|
(The use of these multiple stacks must be ``syncronized'' with C.
|
|
How to explain that? TO BE WRITTEN.)
|
|
|
|
Each thread has an independent table for global variables.
|
|
When you create a thread, this table is the same as that of the given state,
|
|
but you can change each one independently.
|
|
|
|
You destroy threads with \DefAPI{lua_closethread}
|
|
\begin{verbatim}
|
|
void lua_closethread (lua_State *L, lua_State *thread);
|
|
\end{verbatim}
|
|
You cannot close the sole (or last) thread of a state.
|
|
Instead, you must close the state itself.
|
|
|
|
|
|
\subsection{The Stack and Indices}
|
|
|
|
Lua uses a \emph{stack} to pass values to and from C.
|
|
Each element in this stack represents a Lua value
|
|
(\nil, number, string, etc.).
|
|
|
|
For convenience,
|
|
most query operations in the API do not follow a strict stack discipline.
|
|
Instead, they can refer to any element in the stack by using an \emph{index}:
|
|
A positive index represents an \emph{absolute} stack position
|
|
(starting at~1);
|
|
a negative index represents an \emph{offset} from the top of the stack.
|
|
More specifically, if the stack has \M{n} elements,
|
|
then index~1 represents the first element
|
|
(that is, the element that was pushed onto the stack first),
|
|
and
|
|
index~\M{n} represents the last element;
|
|
index~\Math{-1} also represents the last element
|
|
(that is, the element at the top),
|
|
and index \Math{-n} represents the first element.
|
|
We say that an index is \emph{valid}
|
|
if it lies between~1 and the stack top
|
|
(that is, if \verb|1 <= abs(index) <= top|).
|
|
\index{stack index} \index{valid index}
|
|
|
|
At any time, you can get the index of the top element by calling
|
|
\begin{verbatim}
|
|
int lua_gettop (lua_State *L);
|
|
\end{verbatim}
|
|
\DefAPI{lua_gettop}
|
|
Because indices start at~1,
|
|
the result of \verb|lua_gettop| is equal to the number of elements in the stack
|
|
(and so 0~means an empty stack).
|
|
|
|
When you interact with Lua API,
|
|
\emph{you are responsible for controlling stack overflow}.
|
|
The function
|
|
\begin{verbatim}
|
|
int lua_stackspace (lua_State *L);
|
|
\end{verbatim}
|
|
\DefAPI{lua_stackspace}
|
|
returns the number of stack positions still available.
|
|
Whenever Lua calls C, \DefAPI{LUA_MINSTACK}
|
|
it ensures that
|
|
at least \verb|LUA_MINSTACK| positions are still available.
|
|
\verb|LUA_MINSTACK| is defined in \verb|lua.h| and is at least~16,
|
|
so that usually you do not have to worry about stack space
|
|
unless your code has loops pushing elements onto the stack.
|
|
|
|
Most query functions accept as indices any value inside the
|
|
available stack space.
|
|
Such indices are called \emph{acceptable indices}.
|
|
More formally, we define an \IndexEmph{acceptable index}
|
|
as follows:
|
|
\begin{verbatim}
|
|
(index < 0 && abs(index) <= top) || (index > 0 && index <= top + stackspace)
|
|
\end{verbatim}
|
|
Note that 0 is not an acceptable index.
|
|
|
|
Unless otherwise noticed,
|
|
any function that accepts valid indices can also be called with
|
|
\Index{pseudo-indices},
|
|
which represent some Lua values that are accessible to the C~code
|
|
but are not in the stack.
|
|
|
|
Pseudo-indices are used to access the table of globals \see{globals},
|
|
the registry, and the upvalues of a C function \see{c-closure}.
|
|
|
|
\subsection{Stack Manipulation}
|
|
The API offers the following functions for basic stack manipulation:
|
|
\begin{verbatim}
|
|
void lua_settop (lua_State *L, int index);
|
|
void lua_pushvalue (lua_State *L, int index);
|
|
void lua_remove (lua_State *L, int index);
|
|
void lua_insert (lua_State *L, int index);
|
|
void lua_replace (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_settop}\DefAPI{lua_pushvalue}
|
|
\DefAPI{lua_remove}\DefAPI{lua_insert}\DefAPI{lua_replace}
|
|
|
|
\verb|lua_settop| accepts any acceptable index,
|
|
or 0,
|
|
and sets the stack top to that index.
|
|
If the new top is larger than the old one,
|
|
then the new elements are filled with \nil.
|
|
If \verb|index| is 0, then all stack elements are removed.
|
|
A useful macro defined in the \verb|lua.h| is
|
|
\begin{verbatim}
|
|
#define lua_pop(L,n) lua_settop(L, -(n)-1)
|
|
\end{verbatim}
|
|
\DefAPI{lua_pop}
|
|
which pops \verb|n| elements from the stack.
|
|
|
|
\verb|lua_pushvalue| pushes onto the stack a \emph{copy} of the element
|
|
at the given index.
|
|
\verb|lua_remove| removes the element at the given position,
|
|
shifting down the elements above that position to fill the gap.
|
|
\verb|lua_insert| moves the top element into the given position,
|
|
shifting up the elements above that position to open space.
|
|
\verb|lua_replace| moves the top element into the given position,
|
|
without shifting any element (therefore it replaces the value at
|
|
the given position).
|
|
These functions accept only valid indices.
|
|
(Obviously, you cannot call \verb|lua_remove| or \verb|lua_insert| with
|
|
pseudo-indices, as they do not represent a stack position.)
|
|
|
|
As an example, if the stack starts as \verb|10 20 30 40 50*|
|
|
(from bottom to top; the \verb|*| marks the top),
|
|
then
|
|
\begin{verbatim}
|
|
lua_pushvalue(L, 3) --> 10 20 30 40 50 30*
|
|
lua_pushvalue(L, -1) --> 10 20 30 40 50 30 30*
|
|
lua_remove(L, -3) --> 10 20 30 40 30 30*
|
|
lua_remove(L, 6) --> 10 20 30 40 30*
|
|
lua_insert(L, 1) --> 30 10 20 30 40*
|
|
lua_insert(L, -1) --> 30 10 20 30 40* (no effect)
|
|
lua_replace(L, 2) --> 30 40 20 30*
|
|
lua_settop(L, -3) --> 30 40 20*
|
|
lua_settop(L, 6) --> 30 40 20 nil nil nil*
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
\subsection{Querying the Stack}
|
|
|
|
To check the type of a stack element,
|
|
the following functions are available:
|
|
\begin{verbatim}
|
|
int lua_type (lua_State *L, int index);
|
|
int lua_isnil (lua_State *L, int index);
|
|
int lua_isboolean (lua_State *L, int index);
|
|
int lua_isnumber (lua_State *L, int index);
|
|
int lua_isstring (lua_State *L, int index);
|
|
int lua_istable (lua_State *L, int index);
|
|
int lua_isfunction (lua_State *L, int index);
|
|
int lua_iscfunction (lua_State *L, int index);
|
|
int lua_isuserdata (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_type}
|
|
\DefAPI{lua_isnil}\DefAPI{lua_isnumber}\DefAPI{lua_isstring}
|
|
\DefAPI{lua_istable}\DefAPI{lua_isboolean}
|
|
\DefAPI{lua_isfunction}\DefAPI{lua_iscfunction}\DefAPI{lua_isuserdata}
|
|
These functions can be called with any acceptable index.
|
|
|
|
\verb|lua_type| returns the type of a value in the stack,
|
|
or \verb|LUA_TNONE| for a non-valid index
|
|
(that is, if that stack position is ``empty'').
|
|
The types are coded by the following constants
|
|
defined in \verb|lua.h|:
|
|
\verb|LUA_TNIL|,
|
|
\verb|LUA_TNUMBER|,
|
|
\verb|LUA_TBOOLEAN|,
|
|
\verb|LUA_TSTRING|,
|
|
\verb|LUA_TTABLE|,
|
|
\verb|LUA_TFUNCTION|,
|
|
\verb|LUA_TUSERDATA|.
|
|
The following function translates a tag to a type name:
|
|
\begin{verbatim}
|
|
const char *lua_type (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_typename}
|
|
|
|
The \verb|lua_is*| functions return~1 if the object is compatible
|
|
with the given type, and 0 otherwise.
|
|
(\verb|lua_isboolean| is an exception to this rule,
|
|
and it succeeds only for boolean values;
|
|
otherwise it would be useless,
|
|
as any value is compatible with a boolean.)
|
|
They always return 0 for a non-valid index.
|
|
\verb|lua_isnumber| accepts numbers and numerical strings,
|
|
\verb|lua_isstring| accepts strings and numbers \see{coercion},
|
|
and \verb|lua_isfunction| accepts both Lua functions and C~functions.
|
|
To distinguish between Lua functions and C~functions,
|
|
you should use \verb|lua_iscfunction|.
|
|
To distinguish between numbers and numerical strings,
|
|
you can use \verb|lua_rawtag| (or \verb|lua_tag|).
|
|
|
|
The API also has functions to compare two values in the stack:
|
|
\begin{verbatim}
|
|
int lua_equal (lua_State *L, int index1, int index2);
|
|
int lua_lessthan (lua_State *L, int index1, int index2);
|
|
\end{verbatim}
|
|
\DefAPI{lua_equal} \DefAPI{lua_lessthan}
|
|
These functions are equivalent to their counterparts in Lua \see{rel-ops}.
|
|
Specifically, \verb|lua_lessthan| is equivalent to the \verb|lt_event|
|
|
described in \See{tag-method}.
|
|
Both functions return 0 if any of the indices are non-valid.
|
|
|
|
\subsection{Getting Values from the Stack}
|
|
|
|
To translate a value in the stack to a specific C~type,
|
|
you can use the following conversion functions:
|
|
\begin{verbatim}
|
|
int lua_toboolean (lua_State *L, int index);
|
|
lua_Number lua_tonumber (lua_State *L, int index);
|
|
const char *lua_tostring (lua_State *L, int index);
|
|
size_t lua_strlen (lua_State *L, int index);
|
|
lua_CFunction lua_tocfunction (lua_State *L, int index);
|
|
void *lua_touserdata (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_tonumber}\DefAPI{lua_tostring}\DefAPI{lua_strlen}
|
|
\DefAPI{lua_tocfunction}\DefAPI{lua_touserdata}\DefAPI{lua_toboolean}
|
|
These functions can be called with any acceptable index.
|
|
When called with a non-valid index,
|
|
they act as if the given value had an incorrect type.
|
|
|
|
\verb|lua_toboolean| converts the Lua value at the given index
|
|
to a C ``boolean'' value (that is, (int)0 or (int)1).
|
|
Like all tests in Lua, it returns 1 for any Lua value different from
|
|
\False\ and \nil;
|
|
otherwise it returns 0.
|
|
It also returns 0 when called with a non-valid index.
|
|
(If you want to accept only real boolean values,
|
|
use \verb|lua_isboolean| to test the type of the value.)
|
|
|
|
\verb|lua_tonumber| converts the Lua value at the given index
|
|
to a number (by default, \verb|lua_Number| is \verb|double|).
|
|
\DefAPI{lua_Number}
|
|
The Lua value must be a number or a string convertible to number
|
|
\see{coercion}; otherwise, \verb|lua_tonumber| returns~0.
|
|
|
|
\verb|lua_tostring| converts the Lua value at the given index to a string
|
|
(\verb|const char*|).
|
|
The Lua value must be a string or a number;
|
|
otherwise, the function returns \verb|NULL|.
|
|
If the value is a number,
|
|
then \verb|lua_tostring| also
|
|
\emph{changes the actual value in the stack to a string}.
|
|
(This change confuses \verb|lua_next|
|
|
when \verb|lua_tostring| is applied to keys.)
|
|
\verb|lua_tostring| returns a fully aligned pointer
|
|
to a string inside the Lua environment.
|
|
This string always has a zero (\verb|'\0'|)
|
|
after its last character (as in~C),
|
|
but may contain other zeros in its body.
|
|
If you do not know whether a string may contain zeros,
|
|
you can use \verb|lua_strlen| to get its actual length.
|
|
Because Lua has garbage collection,
|
|
there is no guarantee that the pointer returned by \verb|lua_tostring|
|
|
will be valid after the corresponding value is removed from the stack.
|
|
So, if you need the string after the current function returns,
|
|
then you should duplicate it (or put it into the registry \see{registry}).
|
|
|
|
\verb|lua_tocfunction| converts a value in the stack to a C~function.
|
|
This value must be a C~function;
|
|
otherwise, \verb|lua_tocfunction| returns \verb|NULL|.
|
|
The type \verb|lua_CFunction| is explained in \See{LuacallC}.
|
|
|
|
\verb|lua_touserdata| converts a value to \verb|void*|.
|
|
This value must have type \emph{userdata};
|
|
otherwise, \verb|lua_touserdata| returns \verb|NULL|.
|
|
|
|
|
|
|
|
\subsection{Pushing Values onto the Stack}
|
|
|
|
The API has the following functions to
|
|
push C~values onto the stack:
|
|
\begin{verbatim}
|
|
void lua_pushboolean (lua_State *L, int b);
|
|
void lua_pushnumber (lua_State *L, lua_Number n);
|
|
void lua_pushlstring (lua_State *L, const char *s, size_t len);
|
|
void lua_pushstring (lua_State *L, const char *s);
|
|
void lua_pushnil (lua_State *L);
|
|
void lua_pushcfunction (lua_State *L, lua_CFunction f);
|
|
\end{verbatim}
|
|
\DefAPI{lua_pushnumber}\DefAPI{lua_pushlstring}\DefAPI{lua_pushstring}
|
|
\DefAPI{lua_pushcfunction}\DefAPI{lua_pushusertag}\DefAPI{lua_pushboolean}
|
|
\DefAPI{lua_pushnil}\label{pushing}
|
|
These functions receive a C~value,
|
|
convert it to a corresponding Lua value,
|
|
and push the result onto the stack.
|
|
In particular, \verb|lua_pushlstring| and \verb|lua_pushstring|
|
|
make an internal copy of the given string.
|
|
\verb|lua_pushstring| can only be used to push proper C~strings
|
|
(that is, strings that end with a zero and do not contain embedded zeros);
|
|
otherwise, you should use the more general \verb|lua_pushlstring|,
|
|
which accepts an explicit size.
|
|
|
|
|
|
\subsection{Controlling Garbage Collection}\label{GC-API}
|
|
|
|
Lua uses two numbers to control its garbage collection:
|
|
the \emph{count} and the \emph{threshold}
|
|
\see{GC}.
|
|
You can access the current values of these two numbers through the
|
|
following functions:
|
|
\begin{verbatim}
|
|
int lua_getgccount (lua_State *L);
|
|
int lua_getgcthreshold (lua_State *L);
|
|
\end{verbatim}
|
|
\DefAPI{lua_getgcthreshold} \DefAPI{lua_getgccount}
|
|
Both return their respective values in Kbytes.
|
|
You can change the threshold value with
|
|
\begin{verbatim}
|
|
void lua_setgcthreshold (lua_State *L, int newthreshold);
|
|
\end{verbatim}
|
|
\DefAPI{lua_setgcthreshold}
|
|
Again, the \verb|newthreshold| value is given in Kbytes.
|
|
When you call this function,
|
|
Lua sets the new threshold and checks it against the byte counter.
|
|
If the new threshold is smaller than the byte counter,
|
|
then Lua immediately runs the garbage collector.
|
|
In particular
|
|
\verb|lua_setgcthreshold(L,0)| forces a garbage collectiion.
|
|
After the collection,
|
|
a new threshold is set according to the previous rule.
|
|
%% TODO: What `previous rule'?
|
|
|
|
If you want to change the adaptive behavior of the garbage collector,
|
|
you can use the garbage-collection tag method for \nil\ %
|
|
to set your own threshold
|
|
(the tag method is called after Lua resets the threshold).
|
|
|
|
|
|
\subsection{Userdata}
|
|
|
|
You can create new userdata with the following functions:
|
|
\begin{verbatim}
|
|
void *lua_newuserdata (lua_State *L, size_t size);
|
|
void lua_newuserdatabox (lua_State *L, void *u);
|
|
\end{verbatim}
|
|
\DefAPI{lua_newuserdata}\DefAPI{lua_newuserdatabox}
|
|
The first function, \verb|lua_newuserdata|,
|
|
allocates a new block of memory with the given size,
|
|
pushes on the stack a new userdata with the block address,
|
|
and returns this address.
|
|
The second function, \verb|lua_newuserdatabox|,
|
|
gets a pointer and pushes on the stack a new userdata
|
|
with that pointer.
|
|
In this case, Lua does not care about the pointer's value.
|
|
By default, all userdata are created with a standard tag,
|
|
\verb|LUA_TUSERDATA|, which is defined in \verb|lua.h|.
|
|
|
|
When Lua collects a userdata created by \verb|lua_newuserdata|,
|
|
it automatically frees its corresponding memory.
|
|
On the other hand, Lua never accesses pointers in
|
|
userdata created with \verb|lua_newuserdatabox|;
|
|
it is up to you to free any associated memory,
|
|
setting a garbage-collection tag method, for instance.
|
|
|
|
|
|
\subsection{Metatables}
|
|
|
|
%% TODO
|
|
|
|
|
|
\subsection{Executing Lua Chunks}\label{luado}
|
|
A host program can execute Lua chunks written in a file or in a string
|
|
by using the following functions:
|
|
\begin{verbatim}
|
|
int lua_dofile (lua_State *L, const char *filename);
|
|
int lua_dostring (lua_State *L, const char *string);
|
|
int lua_dobuffer (lua_State *L, const char *buff,
|
|
size_t size, const char *name);
|
|
\end{verbatim}
|
|
\DefAPI{lua_dofile}\DefAPI{lua_dostring}\DefAPI{lua_dobuffer}%
|
|
These functions return
|
|
0 in case of success, or one of the following error codes
|
|
(defined in \verb|lua.h|)
|
|
if they fail:
|
|
\begin{itemize}
|
|
\item \IndexAPI{LUA_ERRRUN} ---
|
|
error while running the chunk.
|
|
\item \IndexAPI{LUA_ERRSYNTAX} ---
|
|
syntax error during pre-compilation.
|
|
\item \IndexAPI{LUA_ERRMEM} ---
|
|
memory allocation error.
|
|
For such errors, Lua does not call \verb|_ERRORMESSAGE| \see{error}.
|
|
\item \IndexAPI{LUA_ERRERR} ---
|
|
error while running \verb|_ERRORMESSAGE|.
|
|
For such errors, Lua does not call \verb|_ERRORMESSAGE| again, to avoid loops.
|
|
\item \IndexAPI{LUA_ERRFILE} ---
|
|
error opening the file (only for \verb|lua_dofile|).
|
|
In this case,
|
|
you may want to
|
|
check \verb|errno|,
|
|
call \verb|strerror|,
|
|
or call \verb|perror| to tell the user what went wrong.
|
|
\end{itemize}
|
|
|
|
When called with argument \verb|NULL|,
|
|
\verb|lua_dofile| executes the \verb|stdin| stream.
|
|
\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}).
|
|
\verb|lua_dostring| executes only source code,
|
|
given in textual form.
|
|
|
|
The fourth parameter to \verb|lua_dobuffer|
|
|
is the ``name of the chunk'',
|
|
which is used in error messages and debug information.
|
|
If \verb|name| is \verb|NULL|,
|
|
then Lua gives a default name to the chunk.
|
|
|
|
These functions push onto the stack
|
|
any values eventually returned by the chunk.
|
|
A chunk may return any number of values;
|
|
Lua takes care that these values fit into the stack space,
|
|
%% TODO: how? o que acontece se nao da'?
|
|
but after the call the responsibility is back to you.
|
|
If you need to push other elements after calling any of these functions,
|
|
and you want to ``play safe'',
|
|
you must either check the stack space
|
|
with \verb|lua_stackspace|
|
|
or remove the returned elements
|
|
from the stack (if you do not need them).
|
|
For instance, the following code
|
|
executes a chunk from a file and discards all results returned by this chunk,
|
|
leaving the stack as it was before the call:
|
|
\begin{verbatim}
|
|
{
|
|
int oldtop = lua_gettop(L);
|
|
lua_dofile(L, filename);
|
|
lua_settop(L, oldtop);
|
|
}
|
|
\end{verbatim}
|
|
|
|
\subsection{Loading Lua Chunks}
|
|
You can load Lua chunks without executing them with
|
|
\begin{verbatim}
|
|
int lua_loadfile (lua_State *L, const char *filename);
|
|
int lua_loadbuffer (lua_State *L, const char *buff,
|
|
size_t size, const char *name);
|
|
\end{verbatim}
|
|
The compiled chunk is left as a function on top of the stack.
|
|
The return values are the same as those of
|
|
\verb|lua_dofile| and \verb|lua_dobuffer|.
|
|
|
|
\subsection{Manipulating Tables}
|
|
|
|
Tables are created by calling
|
|
The function
|
|
\begin{verbatim}
|
|
void lua_newtable (lua_State *L);
|
|
\end{verbatim}
|
|
\DefAPI{lua_newtable}
|
|
This function creates a new, empty table and pushes it onto the stack.
|
|
|
|
To read a value from a table that resides somewhere in the stack,
|
|
call
|
|
\begin{verbatim}
|
|
void lua_gettable (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_gettable}
|
|
where \verb|index| refers to the table.
|
|
\verb|lua_gettable| pops a key from the stack
|
|
and returns (on the stack) the contents of the table at that key.
|
|
The table is left where it was in the stack;
|
|
this is convenient for getting multiple values from a table.
|
|
|
|
As in Lua, this function may trigger a tag method
|
|
for the ``gettable'' event \see{tag-method}.
|
|
To get the real value of any table key,
|
|
without invoking any tag method,
|
|
use the \emph{raw} version:
|
|
\begin{verbatim}
|
|
void lua_rawget (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_rawget}
|
|
|
|
To store a value into a table that resides somewhere in the stack,
|
|
you push the key and the value onto the stack
|
|
(in this order),
|
|
and then call
|
|
\begin{verbatim}
|
|
void lua_settable (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_settable}
|
|
where \verb|index| refers to the table.
|
|
\verb|lua_settable| pops from the stack both the key and the value.
|
|
The table is left where it was in the stack;
|
|
this is convenient for setting multiple values in a table.
|
|
|
|
As in Lua, this operation may trigger a tag method
|
|
for the ``settable'' event.
|
|
To set the real value of any table index,
|
|
without invoking any tag method,
|
|
use the \emph{raw} version:
|
|
\begin{verbatim}
|
|
void lua_rawset (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_rawset}
|
|
|
|
You can traverse a table with the function
|
|
\begin{verbatim}
|
|
int lua_next (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_next}
|
|
where \verb|index| refers to the table to be traversed.
|
|
The function pops a key from the stack,
|
|
and pushes a key-value pair from the table
|
|
(the ``next'' pair after the given key).
|
|
If there are no more elements, then \verb|lua_next| returns 0
|
|
(and pushes nothing).
|
|
Use a \nil\ key to signal the start of a traversal.
|
|
|
|
A typical traversal looks like this:
|
|
\begin{verbatim}
|
|
/* table is in the stack at index `t' */
|
|
lua_pushnil(L); /* first key */
|
|
while (lua_next(L, t) != 0) {
|
|
/* `key' is at index -2 and `value' at index -1 */
|
|
printf("%s - %s\n",
|
|
lua_typename(L, lua_type(L, -2)), lua_typename(L, lua_type(L, -1)));
|
|
lua_pop(L, 1); /* removes `value'; keeps `key' for next iteration */
|
|
}
|
|
\end{verbatim}
|
|
|
|
NOTE:
|
|
While traversing a table,
|
|
do not call \verb|lua_tostring| on a key,
|
|
unless you know the key is actually a string.
|
|
Recall that \verb|lua_tostring| \emph{changes} the value at the given index;
|
|
this confuses \verb|lua_next|.
|
|
|
|
\subsection{Manipulating Global Variables} \label{globals}
|
|
|
|
All global variables are kept in an ordinary Lua table.
|
|
This table is always at pseudo-index \IndexAPI{LUA_GLOBALSINDEX}.
|
|
|
|
To access and change the value of global variables,
|
|
you can use regular table operations over the global table.
|
|
For instance, to access the value of a global variable, do
|
|
\begin{verbatim}
|
|
lua_pushstring(L, varname);
|
|
lua_gettable(L, LUA_GLOBALSINDEX);
|
|
\end{verbatim}
|
|
|
|
You can change the global table of a Lua thread using \verb|lua_replace|.
|
|
|
|
|
|
\subsection{Using Tables as Arrays}
|
|
The API has functions that help to use Lua tables as arrays,
|
|
that is,
|
|
tables indexed by numbers only:
|
|
\begin{verbatim}
|
|
void lua_rawgeti (lua_State *L, int index, int n);
|
|
void lua_rawseti (lua_State *L, int index, int n);
|
|
int lua_getn (lua_State *L, int index);
|
|
\end{verbatim}
|
|
\DefAPI{lua_rawgeti}
|
|
\DefAPI{lua_rawseti}
|
|
\DefAPI{lua_getn}
|
|
|
|
\verb|lua_rawgeti| pushes the value of the \M{n}-th element of the table
|
|
at stack position \verb|index|.
|
|
|
|
\verb|lua_rawseti| sets the value of the \M{n}-th element of the table
|
|
at stack position \verb|index| to the value at the top of the stack,
|
|
removing this value from the stack.
|
|
|
|
\verb|lua_getn| returns the number of elements in the table
|
|
at stack position \verb|index|.
|
|
This number is the value of the table field \verb|n|,
|
|
if it has a numeric value,
|
|
or the largest numerical index with a non-\nil\ value in the table.
|
|
|
|
\subsection{Calling Functions}
|
|
|
|
Functions defined in Lua
|
|
(and C~functions registered in Lua)
|
|
can be called from the host program.
|
|
This is done using the following protocol:
|
|
First, the function to be called is pushed onto the stack;
|
|
then, the arguments to the function are pushed
|
|
in \emph{direct order}, that is, the first argument is pushed first.
|
|
Finally, the function is called using
|
|
\begin{verbatim}
|
|
int lua_call (lua_State *L, int nargs, int nresults);
|
|
\end{verbatim}
|
|
\DefAPI{lua_call}
|
|
This function returns the same error codes as \verb|lua_dostring| and
|
|
friends \see{luado}.
|
|
If you want to propagate the error,
|
|
%% TODO: explain 'propagate'.
|
|
instead of returning an error code,
|
|
use
|
|
\begin{verbatim}
|
|
void lua_rawcall (lua_State *L, int nargs, int nresults);
|
|
\end{verbatim}
|
|
\DefAPI{lua_rawcall}
|
|
|
|
In both functions,
|
|
\verb|nargs| is the number of arguments that you pushed onto the stack.
|
|
All arguments and the function value are popped from the stack,
|
|
and the function results are pushed.
|
|
The number of results are adjusted to \verb|nresults|,
|
|
unless \verb|nresults| is \IndexAPI{LUA_MULTRET}.
|
|
In that case, \emph{all} results from the function are pushed.
|
|
The function results are pushed onto the stack in direct order
|
|
(the first result is pushed first),
|
|
so that after the call the last result is on the top.
|
|
|
|
The following example shows how the host program may do the
|
|
equivalent to the Lua code:
|
|
\begin{verbatim}
|
|
a = f("how", t.x, 14)
|
|
\end{verbatim}
|
|
Here it is in~C:
|
|
\begin{verbatim}
|
|
lua_pushstring(L, "t");
|
|
lua_gettable(L, LUA_GLOBALSINDEX); /* global `t' (for later use) */
|
|
lua_pushstring(L, "a"); /* var name */
|
|
lua_pushstring(L, "f"); /* function name */
|
|
lua_gettable(L, LUA_GLOBALSINDEX); /* function to be called */
|
|
lua_pushstring(L, "how"); /* 1st argument */
|
|
lua_pushstring(L, "x"); /* push the string "x" */
|
|
lua_gettable(L, -5); /* push result of t.x (2nd arg) */
|
|
lua_pushnumber(L, 14); /* 3rd argument */
|
|
lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */
|
|
lua_settable(L, LUA_GLOBALSINDEX); /* set global variable `a' */
|
|
lua_pop(L, 1); /* remove `t' from the stack */
|
|
\end{verbatim}
|
|
Notice that the code above is ``balanced'':
|
|
at its end, the stack is back to its original configuration.
|
|
This is considered good programming practice.
|
|
|
|
(We did this example using only the raw functions provided by Lua's API,
|
|
to show all the details.
|
|
Usually programmers use several macros and auxiliar functions that
|
|
provide higher level access to Lua.)
|
|
|
|
\medskip
|
|
|
|
%% TODO: mover essas 2 para algum lugar melhor.
|
|
Some special Lua functions have their own C~interfaces.
|
|
The host program can generate a Lua error calling the function
|
|
\begin{verbatim}
|
|
void lua_error (lua_State *L, const char *message);
|
|
\end{verbatim}
|
|
\DefAPI{lua_error}
|
|
This function never returns.
|
|
If \verb|lua_error| is called from a C~function that 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(EXIT_FAILURE)|.
|
|
Before terminating execution,
|
|
the \verb|message| is passed to the error handler function,
|
|
\verb|_ERRORMESSAGE| \see{error}.
|
|
If \verb|message| is \verb|NULL|,
|
|
then \verb|_ERRORMESSAGE| is not called.
|
|
|
|
The function
|
|
\begin{verbatim}
|
|
void lua_concat (lua_State *L, int n);
|
|
\end{verbatim}
|
|
\DefAPI{lua_concat}
|
|
concatenates the \verb|n| values at the top of the stack,
|
|
pops them, and leaves the result at the top.
|
|
If \verb|n| is 1, the result is that single string
|
|
(that is, the function does nothing);
|
|
if \verb|n| is 0, the result is the empty string.
|
|
Concatenation is done following the usual semantics of Lua
|
|
\see{concat}.
|
|
|
|
|
|
\subsection{Defining C Functions} \label{LuacallC}
|
|
Lua can be extended with functions written in~C.
|
|
These functions must be of type \verb|lua_CFunction|,
|
|
which is defined as
|
|
\begin{verbatim}
|
|
typedef int (*lua_CFunction) (lua_State *L);
|
|
\end{verbatim}
|
|
\DefAPI{lua_CFunction}
|
|
A C~function receives a Lua environment and returns an integer,
|
|
the number of values it has returned to Lua.
|
|
|
|
In order to communicate properly with Lua,
|
|
a C~function must follow the following protocol,
|
|
which defines the way parameters and results are passed:
|
|
A C~function receives its arguments from Lua in the stack,
|
|
in direct order (the first argument is pushed first).
|
|
To return values to Lua, a C~function just pushes them onto the stack,
|
|
in direct order (the first result is pushed first),
|
|
and returns the number of results.
|
|
Like a Lua function, a C~function called by Lua can also return
|
|
many results.
|
|
|
|
As an example, the following function receives a variable number
|
|
of numerical arguments and returns their average and sum:
|
|
\begin{verbatim}
|
|
static int foo (lua_State *L) {
|
|
int n = lua_gettop(L); /* number of arguments */
|
|
lua_Number sum = 0;
|
|
int i;
|
|
for (i = 1; i <= n; i++) {
|
|
if (!lua_isnumber(L, i))
|
|
lua_error(L, "incorrect argument to function `average'");
|
|
sum += lua_tonumber(L, i);
|
|
}
|
|
lua_pushnumber(L, sum/n); /* first result */
|
|
lua_pushnumber(L, sum); /* second result */
|
|
return 2; /* number of results */
|
|
}
|
|
\end{verbatim}
|
|
|
|
To register a C~function to Lua,
|
|
there is the following convenience macro:
|
|
\begin{verbatim}
|
|
#define lua_register(L,n,f) \
|
|
(lua_pushstring(L, n), \
|
|
lua_pushcfunction(L, f), \
|
|
lua_settable(L, LUA_GLOBALSINDEX))
|
|
/* const char *n; */
|
|
/* lua_CFunction f; */
|
|
\end{verbatim}
|
|
\DefAPI{lua_register}
|
|
which receives the name the function will have in Lua,
|
|
and a pointer to the function.
|
|
Thus,
|
|
the C~function `\verb|foo|' above may be registered in Lua as `\verb|average|'
|
|
by calling
|
|
\begin{verbatim}
|
|
lua_register(L, "average", foo);
|
|
\end{verbatim}
|
|
|
|
\subsection{Defining C Closures} \label{c-closure}
|
|
|
|
When a C~function is created,
|
|
it is possible to associate some values to it,
|
|
thus creating a \IndexEmph{C~closure};
|
|
these values are then accessible to the function whenever it is called.
|
|
To associate values to a C~function,
|
|
first these values should be pushed onto the stack
|
|
(when there are multiple values, the first value is pushed first).
|
|
Then the function
|
|
\begin{verbatim}
|
|
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
|
|
\end{verbatim}
|
|
\DefAPI{lua_pushcclosure}
|
|
is used to push the C~function onto the stack,
|
|
with the argument \verb|n| telling how many values should be
|
|
associated with the function
|
|
(\verb|lua_pushcclosure| also pops these values from the stack);
|
|
in fact, the macro \verb|lua_pushcfunction| is defined as
|
|
\verb|lua_pushcclosure| with \verb|n| set to 0.
|
|
|
|
Then, whenever the C~function is called,
|
|
those values are located at specific pseudo-indices.
|
|
Those pseudo-indices are produced by a macro \IndexAPI{lua_upvalueindex}.
|
|
The first value associated with a function is at position
|
|
\verb|lua_upvalueindex(1)|, and so on.
|
|
|
|
For examples of C~functions and closures, see files
|
|
\verb|lbaselib.c|, \verb|liolib.c|, \verb|lmathlib.c|, and \verb|lstrlib.c|
|
|
in the official Lua distribution.
|
|
|
|
|
|
\subsubsection*{Registry} \label{registry}
|
|
|
|
Lua provides a pre-defined table that can be used by any C~code to
|
|
store whatever Lua value it needs to store,
|
|
especially if the C~code needs to keep that Lua value
|
|
outside the life span of a C~function.
|
|
This table is always located at pseudo-index
|
|
\IndexAPI{LUA_REGISTRYINDEX}.
|
|
Any C~library can store data into this table,
|
|
as long as it chooses a key different from other libraries.
|
|
The integer keys in the registry are used by the reference mechanism,
|
|
implemented by the auxiliar library,
|
|
and therefore should not be used by other purposes.
|
|
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section{The Debug 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 \verb|luadebug.h|.
|
|
|
|
\subsection{Stack and Function Information}
|
|
|
|
The main function to get information about the interpreter stack is
|
|
\begin{verbatim}
|
|
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
|
|
\end{verbatim}
|
|
\DefAPI{lua_getstack}
|
|
This function fills parts of a \verb|lua_Debug| structure with
|
|
an identification of the \emph{activation record}
|
|
of the function executing at a given level.
|
|
Level~0 is the current running function,
|
|
whereas level \Math{n+1} is the function that has called level \Math{n}.
|
|
Usually, \verb|lua_getstack| returns 1;
|
|
when called with a level greater than the stack depth,
|
|
it returns 0.
|
|
|
|
The structure \verb|lua_Debug| is used to carry different pieces of
|
|
information about an active function:
|
|
\begin{verbatim}
|
|
typedef struct lua_Debug {
|
|
const char *event; /* "call", "return" */
|
|
int currentline; /* (l) */
|
|
const char *name; /* (n) */
|
|
const char *namewhat; /* (n) global, tag method, local, field */
|
|
int nups; /* (u) number of upvalues */
|
|
int linedefined; /* (S) */
|
|
const char *what; /* (S) "Lua" function, "C" function, Lua "main" */
|
|
const char *source; /* (S) */
|
|
char short_src[LUA_IDSIZE]; /* (S) */
|
|
|
|
/* private part */
|
|
...
|
|
} lua_Debug;
|
|
\end{verbatim}
|
|
\DefAPI{lua_Debug}
|
|
\verb|lua_getstack| fills only the private part
|
|
of this structure, for future use.
|
|
To fill the other fields of \verb|lua_Debug| with useful information,
|
|
call
|
|
\begin{verbatim}
|
|
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
|
|
\end{verbatim}
|
|
\DefAPI{lua_getinfo}
|
|
This function returns 0 on error
|
|
(for instance, an invalid option in \verb|what|).
|
|
Each character in the string \verb|what|
|
|
selects some fields of \verb|ar| to be filled,
|
|
as indicated by the letter in parentheses in the definition of \verb|lua_Debug|
|
|
above:
|
|
`\verb|S|' fills in the fields \verb|source|, \verb|linedefined|,
|
|
and \verb|what|;
|
|
`\verb|l|' fills in the field \verb|currentline|, etc.
|
|
Moreover, `\verb|f|' pushes onto the stack the function that is
|
|
running at the given level.
|
|
|
|
To get information about a function that is not active (that is,
|
|
it is not in the stack),
|
|
you push the function onto the stack,
|
|
and start the \verb|what| string with the character `\verb|>|'.
|
|
For instance, to know in which line a function \verb|f| was defined,
|
|
you can write
|
|
\begin{verbatim}
|
|
lua_Debug ar;
|
|
lua_pushstring(L, "f");
|
|
lua_gettable(L, LUA_GLOBALSINDEX); /* get global `f' */
|
|
lua_getinfo(L, ">S", &ar);
|
|
printf("%d\n", ar.linedefined);
|
|
\end{verbatim}
|
|
The fields of \verb|lua_Debug| have the following meaning:
|
|
\begin{description}\leftskip=20pt
|
|
|
|
\item[source]
|
|
If the function was defined in a string,
|
|
then \verb|source| is that string;
|
|
if the function was defined in a file,
|
|
then \verb|source| starts with a \verb|@| followed by the file name.
|
|
|
|
\item[short\_src]
|
|
A ``printable'' version of \verb|source|, to be used in error messages.
|
|
|
|
\item[linedefined]
|
|
the line number where the definition of the function starts.
|
|
|
|
\item[what] the string \verb|"Lua"| if this is a Lua function,
|
|
\verb|"C"| if this is a C~function,
|
|
or \verb|"main"| if this is the main part of a chunk.
|
|
|
|
\item[currentline]
|
|
the current line where the given function is executing.
|
|
When no line information is available,
|
|
\verb|currentline| is set to \Math{-1}.
|
|
|
|
\item[name]
|
|
a reasonable name for the 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.
|
|
The \verb|lua_getinfo| function 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|name| points to the event name.
|
|
%% TODO: mas qual o tag? Agora que temos tipos com nome, seria util saber
|
|
%% o tipo de TM. Em particular para mensagens de erro.
|
|
If the given function is the value of a global variable,
|
|
then \verb|name| points to the variable name.
|
|
If the given function is neither a tag method nor a global variable,
|
|
then \verb|name| is set to \verb|NULL|.
|
|
|
|
\item[namewhat]
|
|
Explains the previous field.
|
|
If the function is a global variable,
|
|
\verb|namewhat| is \verb|"global"|;
|
|
if the function is a tag method,
|
|
\verb|namewhat| is \verb|"tag-method"|;
|
|
otherwise, it is \verb|""| (the empty string).
|
|
|
|
\item[nups]
|
|
Number of upvalues of the function.
|
|
|
|
\end{description}
|
|
|
|
|
|
\subsection{Manipulating Local Variables}
|
|
|
|
For the manipulation of local variables,
|
|
\verb|luadebug.h| uses indices:
|
|
The first parameter or local variable has index~1, and so on,
|
|
until the last active local variable.
|
|
|
|
The following functions allow the manipulation of the
|
|
local variables of a given activation record:
|
|
\begin{verbatim}
|
|
const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);
|
|
const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);
|
|
\end{verbatim}
|
|
\DefAPI{lua_getlocal}\DefAPI{lua_setlocal}
|
|
The parameter \verb|ar| must be a valid activation record,
|
|
filled by a previous call to \verb|lua_getstack| or
|
|
given as argument to a hook \see{sub-hooks}.
|
|
\verb|lua_getlocal| gets the index \verb|n| of a local variable,
|
|
pushes its value onto the stack,
|
|
and returns its name.
|
|
%% TODO: why return name?
|
|
\verb|lua_setlocal| assigns the value at the top of the stack
|
|
to the variable and returns its name.
|
|
Both functions return \verb|NULL| on failure,
|
|
that is
|
|
when the index is greater than
|
|
the number of active local variables.
|
|
|
|
As an example, the following function lists the names of all
|
|
local variables for a function at a given level of the stack:
|
|
\begin{verbatim}
|
|
int listvars (lua_State *L, int level) {
|
|
lua_Debug ar;
|
|
int i = 1;
|
|
const char *name;
|
|
if (lua_getstack(L, level, &ar) == 0)
|
|
return 0; /* failure: no such level in the stack */
|
|
while ((name = lua_getlocal(L, &ar, i++)) != NULL) {
|
|
printf("%s\n", name);
|
|
lua_pop(L, 1); /* remove variable value */
|
|
}
|
|
return 1;
|
|
}
|
|
\end{verbatim}
|
|
|
|
|
|
\subsection{Hooks}\label{sub-hooks}
|
|
|
|
The Lua interpreter offers two hooks for debugging purposes:
|
|
a \emph{call} hook and a \emph{line} hook.
|
|
Both have type \verb|lua_Hook|, defined as follows:
|
|
\begin{verbatim}
|
|
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
|
|
\end{verbatim}
|
|
\DefAPI{lua_Hook}
|
|
You can set the hooks with the following functions:
|
|
\begin{verbatim}
|
|
lua_Hook lua_setcallhook (lua_State *L, lua_Hook func);
|
|
lua_Hook lua_setlinehook (lua_State *L, lua_Hook func);
|
|
\end{verbatim}
|
|
\DefAPI{lua_setcallhook}\DefAPI{lua_setlinehook}
|
|
A hook is disabled when its value is \verb|NULL|,
|
|
which is the initial value of both hooks.
|
|
The functions \verb|lua_setcallhook| and \verb|lua_setlinehook|
|
|
set their corresponding hooks and return their previous values.
|
|
|
|
The call hook is called whenever the
|
|
interpreter enters or leaves a function.
|
|
The \verb|event| field of \verb|ar| has the string \verb|"call"|
|
|
or \verb|"return"|.
|
|
This \verb|ar| can then be used in calls to \verb|lua_getinfo|,
|
|
\verb|lua_getlocal|, and \verb|lua_setlocal|
|
|
to get more information about the function and to manipulate its
|
|
local variables.
|
|
|
|
The line hook is called every time the interpreter changes
|
|
the line of code it is executing.
|
|
The \verb|event| field of \verb|ar| has the string \verb|"line"|,
|
|
and the \verb|currentline| field has the new line number.
|
|
Again, you can use this \verb|ar| in other calls to the debug API.
|
|
|
|
While Lua is running a hook, it disables other calls to hooks.
|
|
Therefore, if a hook calls Lua to execute a function or a chunk,
|
|
this execution ocurrs without any calls to hooks.
|
|
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section{Standard Libraries}\label{libraries}
|
|
|
|
The standard libraries provide useful functions
|
|
that are implemented directly through the standard C~API.
|
|
Therefore, they are not essential to the language,
|
|
and are provided as separate C~modules.
|
|
Currently, Lua has the following standard libraries:
|
|
\begin{itemize}
|
|
\item basic library;
|
|
\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_baselibopen|,
|
|
\verb|lua_strlibopen|, \verb|lua_mathlibopen|,
|
|
and \verb|lua_iolibopen|, which are declared in \verb|lualib.h|.
|
|
\DefAPI{lua_baselibopen}
|
|
\DefAPI{lua_strlibopen}
|
|
\DefAPI{lua_mathlibopen}
|
|
\DefAPI{lua_iolibopen}
|
|
|
|
Lua's web site has links to Lua libraries written by users.
|
|
|
|
\subsection{Basic Functions} \label{predefined}
|
|
|
|
The basic library provides some core functions to Lua.
|
|
If you do not include this library in your application,
|
|
you should check carefully whether you need to provide some alternative
|
|
implementation for some facilities.
|
|
(For instance,
|
|
without an \verb|_ERRORMESSAGE| function,
|
|
Lua is unable to show error messages.)
|
|
|
|
The basic library also defines a global variable \IndexAPI{_VERSION}
|
|
with a string containing the current interpreter version.
|
|
The current content of this string is {\tt "Lua \Version"}.
|
|
|
|
\subsubsection*{\ff \T{_ALERT (message)}}\DefLIB{alert}\label{alert}
|
|
Prints its only string argument to \IndexVerb{stderr}.
|
|
All error messages in Lua are printed through the function stored
|
|
in the \verb|_ALERT| global variable
|
|
\see{error}.
|
|
Therefore, a program may assign another function to this variable
|
|
to change the way such messages are shown
|
|
(for instance, for systems without \verb|stderr|).
|
|
|
|
\subsubsection*{\ff \T{assert (v [, message])}}\DefLIB{assert}
|
|
Issues an \emph{``assertion failed!''} error
|
|
when its argument \verb|v| is \nil;
|
|
otherwise, returns this argument.
|
|
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
|
|
return v
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{call (func, arg [, mode [, errhandler]])}}\DefLIB{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}.
|
|
All results from \verb|func| are simply returned by \verb|call|.
|
|
|
|
By default,
|
|
if an error occurs during the call to \verb|func|,
|
|
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 \verb|errhandler| is provided,
|
|
the error function \verb|_ERRORMESSAGE| is temporarily set to \verb|errhandler|,
|
|
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])}}\DefLIB{collectgarbage}
|
|
|
|
Sets the garbage-collection threshold for the given limit
|
|
(in Kbytes), and checks it against the byte counter.
|
|
If the new threshold is smaller than the byte counter,
|
|
then Lua immediately runs the garbage collector \see{GC}.
|
|
If \verb|limit| is absent, it defaults to zero
|
|
(thus forcing a garbage-collection cycle).
|
|
|
|
\subsubsection*{\ff \T{dofile (filename)}}\DefLIB{dofile}
|
|
Receives a file name,
|
|
opens the named file, and executes its contents as a Lua chunk.
|
|
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{} plus one of the following strings
|
|
describing the error:
|
|
\verb|"file error"|, \verb|"run-time error"|,
|
|
\verb|"syntax error"|, \verb|"memory error"|, or
|
|
\verb|"error in error handling"|.
|
|
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.
|
|
|
|
\subsubsection*{\ff \T{dostring (string [, chunkname])}}\DefLIB{dostring}
|
|
Executes a given string as a Lua chunk.
|
|
If there is any error executing the string,
|
|
then \verb|dostring| returns \nil\ plus a string describing
|
|
the error (see \verb|dofile|).
|
|
Otherwise, it returns the values returned by the chunk,
|
|
or a non-\nil\ value if the chunk returns no values.
|
|
The optional parameter \verb|chunkname|
|
|
is the ``name of the chunk'',
|
|
used in error messages and debug information.
|
|
|
|
\subsubsection*{\ff \T{error ([message])}}\DefLIB{error}\label{pdf-error}
|
|
Calls the error handler \see{error} 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 absent, the error handler is not called.
|
|
Function \verb|error| never returns.
|
|
|
|
\subsubsection*{\ff \T{foreach (table, func)}}\DefLIB{foreach}
|
|
Executes the given \verb|func| 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 a non-\nil\ value,
|
|
then the loop is broken, and this value is returned
|
|
as the final value of \verb|foreach|.
|
|
This function is equivalent to the following Lua function:
|
|
\begin{verbatim}
|
|
function foreach (t, f)
|
|
for i, v in t do
|
|
local res = f(i, v)
|
|
if res then return res end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
The behavior of \verb|foreach| is \emph{undefined} if you change
|
|
the table \verb|t| during the traversal.
|
|
|
|
|
|
\subsubsection*{\ff \T{foreachi (table, func)}}\DefLIB{foreachi}
|
|
Executes the given \verb|func| 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 below).
|
|
If the function returns a non-\nil\ value,
|
|
then the loop is broken, and this value is returned
|
|
as the final value of \verb|foreachi|.
|
|
This function is equivalent to the following Lua function:
|
|
\begin{verbatim}
|
|
function foreachi (t, f)
|
|
for i=1,getn(t) do
|
|
local res = f(i, t[i])
|
|
if res then return res end
|
|
end
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{gcinfo ()}}\DefLIB{gcinfo}
|
|
Returns the number of Kbytes of dynamic memory Lua is using,
|
|
and (as a second result) the
|
|
current garbage collector threshold (also in Kbytes).
|
|
|
|
\subsubsection*{\ff \T{getn (table)}}\DefLIB{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 value is the ``size'' of the table.
|
|
Otherwise, the ``size'' is the largest numerical index with a non-\nil\
|
|
value in the table.
|
|
This function is equivalent to the following Lua function:
|
|
\begin{verbatim}
|
|
function getn (t)
|
|
if type(t.n) == "number" then return t.n end
|
|
local max = 0
|
|
for i, _ in t do
|
|
if type(i) == "number" and i>max then max=i end
|
|
end
|
|
return max
|
|
end
|
|
\end{verbatim}
|
|
|
|
\subsubsection*{\ff \T{globals ([table])}}\DefLIB{globals}\label{pdf-globals}
|
|
Returns the current table of globals.
|
|
If the argument \verb|table| is given,
|
|
then it also sets this table as the table of globals.
|
|
|
|
\subsubsection*{\ff \T{loadfile (filename)}}\DefLIB{loadfile}
|
|
Similar to \verb|dofile|,
|
|
but returns the contents of a Lua chunk as a function,
|
|
instead of executing it.
|
|
|
|
\subsubsection*{\ff \T{loadstring (string [, chunkname])}}\DefLIB{loadstring}
|
|
Similar to \verb|dostring|,
|
|
but returns the contents of a Lua chunk as a function,
|
|
instead of executing it.
|
|
|
|
\subsubsection*{\ff \T{newtype (name)}}\DefLIB{newtype}\label{pdf-newtype}
|
|
Creates a new type with the given name
|
|
(which can be used only for table objects).
|
|
Returns the tag of the new type.
|
|
|
|
\subsubsection*{\ff \T{next (table, [index])}}\DefLIB{next}
|
|
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.
|
|
\verb|next| returns the next index of the table and the
|
|
value associated with the index.
|
|
When called with \nil\ as its second argument,
|
|
\verb|next| returns the first index
|
|
of the table and its associated value.
|
|
When called with the last index,
|
|
or with \nil\ in an empty table,
|
|
\verb|next| returns \nil.
|
|
If the second argument is absent, then it is interpreted as \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, \verb|next| 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 numerical \rwd{for} or the function \verb|foreachi|).
|
|
|
|
The behavior of \verb|next| is \emph{undefined} if you change
|
|
the table during the traversal.
|
|
|
|
\subsubsection*{\ff \T{print (e1, e2, ...)}}\DefLIB{print}
|
|
Receives any number of arguments,
|
|
and prints their values in \verb|stdout|,
|
|
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,
|
|
typically for debugging.
|
|
For formatted output, see \verb|format| \see{format}.
|
|
|
|
\subsubsection*{\ff \T{rawget (table, index)}}\DefLIB{rawget}
|
|
Gets the real value of \verb|table[index]|,
|
|
without invoking any tag method.
|
|
\verb|table| must be a table;
|
|
\verb|index| is any value different from \nil.
|
|
|
|
\subsubsection*{\ff \T{rawset (table, index, value)}}\DefLIB{rawset}
|
|
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{require (module)}}\DefLIB{require}
|
|
|
|
TO BE WRITTEN.
|
|
|
|
\subsubsection*{\ff \T{sort (table [, comp])}}\DefLIB{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,
|
|
then 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,
|
|
then the standard Lua operator \verb|<| is used instead.
|
|
|
|
The sort algorithm is \emph{not} stable
|
|
(that is, elements considered equal by the given order
|
|
may have their relative positions changed by the sort).
|
|
|
|
\subsubsection*{\ff \T{tonumber (e [, base])}}\DefLIB{tonumber}
|
|
Tries to convert its argument 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' (in 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 unsigned integers are accepted.
|
|
|
|
\subsubsection*{\ff \T{tostring (e)}}\DefLIB{tostring}
|
|
Receives an argument of any type and
|
|
converts it to a string in a reasonable format.
|
|
For complete control of how numbers are converted,
|
|
use \verb|format| \see{format}.
|
|
|
|
|
|
\subsubsection*{\ff \T{tinsert (table, [pos,] value)}}\DefLIB{tinsert}
|
|
|
|
Inserts element \verb|value| at position \verb|pos| in \verb|table|,
|
|
shifting other elements up to open space, if necessary.
|
|
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|.
|
|
|
|
\subsubsection*{\ff \T{tremove (table [, pos])}}\DefLIB{tremove}
|
|
|
|
Removes from \verb|table| the element at position \verb|pos|,
|
|
shifting other elements down to close the space, if necessary.
|
|
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|.
|
|
|
|
\subsubsection*{\ff \T{type (v)}}\DefLIB{type}\label{pdf-type}
|
|
Returns the type of its only argument, 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{unpack (list)}}\DefLIB{unpack}
|
|
Returns all elements from the given list.
|
|
This function is equivalent to
|
|
\begin{verbatim}
|
|
return list[1], list[2], ..., list[n]
|
|
\end{verbatim}
|
|
except that the above code can be valid only for a fixed \M{n}.
|
|
The number \M{n} of returned values
|
|
is the result of \verb|getn(list)| \seepage{getn}.
|
|
|
|
\subsection{String Manipulation}
|
|
This library provides generic functions for string manipulation,
|
|
such as finding and extracting substrings and pattern matching.
|
|
When indexing a string in Lua, the first character is at position~1
|
|
(not at~0, as in C).
|
|
Indices are allowed to be negative and are interpreted as indexing backwards,
|
|
from the end of the string. Thus, the last character is at position \Math{-1},
|
|
and so on.
|
|
|
|
\subsubsection*{\ff \T{strbyte (s [, i])}}\DefLIB{strbyte}
|
|
Returns the internal numerical code of the \M{i}-th character of \verb|s|.
|
|
If \verb|i| is absent, then it is assumed to be~1.
|
|
\verb|i| may be negative.
|
|
|
|
\NOTE
|
|
Numerical codes are not necessarily portable across platforms.
|
|
|
|
\subsubsection*{\ff \T{strchar (i1, i2, \ldots)}}\DefLIB{strchar}
|
|
Receives 0 or more integers.
|
|
Returns a string with length equal to the number of arguments,
|
|
in which each character has the internal numerical code equal
|
|
to its correspondent argument.
|
|
|
|
\NOTE
|
|
Numerical codes are not necessarily portable across platforms.
|
|
|
|
\subsubsection*{\ff \T{strfind (s, pattern [, init [, plain]])}}\DefLIB{strfind}
|
|
Looks for the first \emph{match} of
|
|
\verb|pattern| in the string \verb|s|.
|
|
If it finds one, then \verb|strfind| returns the indices of \verb|s|
|
|
where this occurrence starts and ends;
|
|
otherwise, it returns \nil.
|
|
If the pattern specifies captures (see \verb|gsub| below),
|
|
the captured strings are returned as extra results.
|
|
A third, optional numerical argument \verb|init| specifies
|
|
where to start the search;
|
|
its default value is~1, and may be negative.
|
|
A value of \True\ as a fourth, optional argument \verb|plain|
|
|
turns off the pattern matching facilities,
|
|
so the function does a plain ``find substring'' operation,
|
|
with no characters in \verb|pattern| being considered ``magic''.
|
|
Note that if \verb|plain| is given, then \verb|init| must be given too.
|
|
|
|
\subsubsection*{\ff \T{strlen (s)}}\DefLIB{strlen}
|
|
Receives a string and returns its length.
|
|
The empty string \verb|""| has length 0.
|
|
Embedded zeros are counted,
|
|
and so \verb|"a\000b\000c"| has length 5.
|
|
|
|
\subsubsection*{\ff \T{strlower (s)}}\DefLIB{strlower}
|
|
Receives a string and returns a copy of that string with all
|
|
uppercase letters changed to lowercase.
|
|
All other characters are left unchanged.
|
|
The definition of what an uppercase letter is depends on the current locale.
|
|
|
|
\subsubsection*{\ff \T{strrep (s, n)}}\DefLIB{strrep}
|
|
Returns a string that is the concatenation of \verb|n| copies of
|
|
the string \verb|s|.
|
|
|
|
\subsubsection*{\ff \T{strsub (s, i [, j])}}\DefLIB{strsub}
|
|
Returns another string, which is a substring of \verb|s|,
|
|
starting at \verb|i| and running until \verb|j|;
|
|
\verb|i| and \verb|j| may be negative.
|
|
If \verb|j| is absent, then 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{strupper (s)}}\DefLIB{strupper}
|
|
Receives a string and returns a copy of that string with all
|
|
lowercase letters changed to uppercase.
|
|
All other characters are left unchanged.
|
|
The definition of what a lowercase letter is depends on the current locale.
|
|
|
|
\subsubsection*{\ff \T{format (formatstring, e1, e2, \ldots)}}\DefLIB{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|.
|
|
The \verb|q| 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}
|
|
|
|
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"|.
|
|
|
|
\NOTE
|
|
String values to be formatted with
|
|
\verb|%s| cannot contain embedded zeros.
|
|
|
|
\subsubsection*{\ff \T{gsub (s, pat, repl [, n])}}
|
|
\DefLIB{gsub}
|
|
Returns a copy of \verb|s|
|
|
in which all occurrences of the pattern \verb|pat| have been
|
|
replaced by a replacement string specified by \verb|repl|.
|
|
\verb|gsub| 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|%|\M{n},
|
|
with \M{n} between 1 and 9,
|
|
stands for the value of the \M{n}-th captured substring.
|
|
|
|
If \verb|repl| is a function, then this function is called every time a
|
|
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.
|
|
|
|
The 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="4.1"}
|
|
x = gsub("$name - $version", "%$(%w+)", function (v) return t[v] end)
|
|
--> x="Lua - 4.1"
|
|
|
|
local t = {}
|
|
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}\leftskip=20pt
|
|
\item[\emph{x}] (where \emph{x} is not one of the magic characters
|
|
\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 lowercase letters.
|
|
\item[\T{\%p}] --- represents all punctuation characters.
|
|
\item[\T{\%s}] --- represents all space characters.
|
|
\item[\T{\%u}] --- represents all uppercase letters.
|
|
\item[\T{\%w}] --- represents all alphanumeric characters.
|
|
\item[\T{\%x}] --- represents all hexadecimal 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.
|
|
We recommend that any punctuation character (even the non magic)
|
|
should be preceded by a \verb|%|
|
|
when used to represent itself in a pattern.
|
|
|
|
\item[\T{[\M{set}]}] ---
|
|
represents the class which is the union of all
|
|
characters in \M{set}.
|
|
A range of characters may be specified by
|
|
separating the end characters of the range with a \verb|-|.
|
|
All classes \verb|%|\emph{x} described above may also be used as
|
|
components in \M{set}.
|
|
All other characters in \M{set} represent themselves.
|
|
For example, \verb|[%w_]| (or \verb|[_%w]|)
|
|
represents all alphanumeric characters plus the underscore,
|
|
\verb|[0-7]| represents the octal digits,
|
|
and \verb|[0-7%l%-]| represents the octal digits plus
|
|
the lowercase letters plus the \verb|-| character.
|
|
|
|
The interaction between ranges and classes is not defined.
|
|
Therefore, patterns like \verb|[%a-z]| or \verb|[a-%%]|
|
|
have no meaning.
|
|
|
|
\item[\T{[\^\null\M{set}]}] ---
|
|
represents the complement of \M{set},
|
|
where \M{set} is interpreted as above.
|
|
\end{description}
|
|
For all classes represented by single letters (\verb|%a|, \verb|%c|, \ldots),
|
|
the corresponding uppercase 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 portability.
|
|
|
|
\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 \emph{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 \M{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}.
|
|
This means that, if one reads the string from left to right,
|
|
counting \Math{+1} for an \M{x} and \Math{-1} for a \M{y},
|
|
the ending \M{y} is the first \M{y} 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.
|
|
At other positions,
|
|
\verb|^| and \verb|$| have no special meaning and represent themselves.
|
|
|
|
\paragraph{Captures:}
|
|
A pattern may contain sub-patterns enclosed in parentheses;
|
|
they 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.
|
|
|
|
\NOTE
|
|
A pattern cannot contain embedded zeros. Use \verb|%z| instead.
|
|
|
|
|
|
\subsection{Mathematical Functions} \label{mathlib}
|
|
|
|
This library is an interface to most functions of the standard C~math library.
|
|
(Some have slightly different names.)
|
|
In addition,
|
|
it registers a tag method for the binary exponentiation operator \verb|^| that
|
|
returns \Math{x^y} when applied to numbers \verb|x^y|.
|
|
|
|
The library provides the following functions:
|
|
\DefLIB{abs}\DefLIB{acos}\DefLIB{asin}\DefLIB{atan}
|
|
\DefLIB{atan2}\DefLIB{ceil}\DefLIB{cos}\DefLIB{def}\DefLIB{exp}
|
|
\DefLIB{floor}\DefLIB{log}\DefLIB{log10}\DefLIB{max}\DefLIB{min}
|
|
\DefLIB{mod}\DefLIB{rad}\DefLIB{sin}\DefLIB{sqrt}\DefLIB{tan}
|
|
\DefLIB{frexp}\DefLIB{ldexp}\DefLIB{random}\DefLIB{randomseed}
|
|
\begin{verbatim}
|
|
abs acos asin atan atan2 ceil cos deg exp floor log log10
|
|
max min mod rad sin sqrt tan frexp ldexp random randomseed
|
|
\end{verbatim}
|
|
plus a global variable \IndexLIB{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.
|
|
The functions \verb|deg| and \verb|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.
|
|
(No guarantees can be given for their statistical properties.)
|
|
When called without arguments,
|
|
\verb|random| 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{Input and Output 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|.
|
|
\DefLIB{_INPUT}\DefLIB{_OUTPUT}
|
|
\DefLIB{_STDIN}\DefLIB{_STDOUT}\DefLIB{_STDERR}
|
|
|
|
A file handle is a userdata containing the file stream (\verb|FILE*|),
|
|
and with a distinctive tag created by the I/O library.
|
|
|
|
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)}}\DefLIB{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 \verb|mode| string can be any of the following:
|
|
\begin{description}\leftskip=20pt
|
|
\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 \verb|mode| string may also have a \verb|b| at the end,
|
|
which is needed in some systems to open the file in binary mode.
|
|
This string is exactly what is used in the standard~C function \verb|fopen|.
|
|
|
|
\subsubsection*{\ff \T{closefile (handle)}}\DefLIB{closefile}
|
|
|
|
This function closes the given file.
|
|
It does not modify either \verb|_INPUT| or \verb|_OUTPUT|.
|
|
|
|
\subsubsection*{\ff \T{readfrom (filename)}}\DefLIB{readfrom}
|
|
|
|
This function may be called in two ways.
|
|
When called with a file name, it opens the named file (in text mode),
|
|
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.
|
|
|
|
\NOTE
|
|
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.
|
|
|
|
\subsubsection*{\ff \T{writeto (filename)}}\DefLIB{writeto}
|
|
|
|
This function may be called in two ways.
|
|
When called with a file name,
|
|
it opens the named file (in text mode),
|
|
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.
|
|
|
|
\NOTE
|
|
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.
|
|
|
|
\subsubsection*{\ff \T{appendto (filename)}}\DefLIB{appendto}
|
|
|
|
Opens a file named \verb|filename| (in text mode)
|
|
sets its handle as the value of \verb|_OUTPUT|,
|
|
and returns this value.
|
|
Unlike the \verb|writeto| operation,
|
|
this function does not erase any previous contents of the file;
|
|
instead, anything written to the file is appended to its end.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{remove (filename)}}\DefLIB{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)}}\DefLIB{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])}}\DefLIB{flush}
|
|
|
|
Saves any written data to the given file.
|
|
If \verb|filehandle| is not specified,
|
|
then \verb|flush| flushes all open files.
|
|
If this function fails, it returns \nil,
|
|
plus a string describing the error.
|
|
|
|
\subsubsection*{\ff \T{seek (filehandle [, whence] [, offset])}}\DefLIB{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}\leftskip=20pt
|
|
\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 this function 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{tmpfile ()}}\DefLIB{tmpfile}
|
|
|
|
Returns a handle for a temporary file.
|
|
This file is open in read/write mode,
|
|
and it is automatically removed when the program ends.
|
|
|
|
\subsubsection*{\ff \T{tmpname ()}}\DefLIB{tmpname}
|
|
|
|
Returns a string with a file name that can
|
|
be used for a temporary file.
|
|
The file must be explicitly opened before its use
|
|
and removed when no longer needed.
|
|
|
|
This function is equivalent to the \verb|tmpnam| C~function,
|
|
and many people (and even some compilers!) advise against its use,
|
|
because between the time you call the function
|
|
and the time you open the file,
|
|
it is possible for another process
|
|
to create a file with the same name.
|
|
|
|
\subsubsection*{\ff \T{read ([filehandle,] format1, ...)}}\DefLIB{read}
|
|
|
|
Reads file \verb|_INPUT|,
|
|
or \verb|filehandle| if this argument is given,
|
|
according to the given formats, which specify what to read.
|
|
For each format,
|
|
the function returns a string (or a number) with the characters read,
|
|
or \nil\ if it cannot read data with the specified format.
|
|
When called without formats,
|
|
it uses a default format that reads the entire next line
|
|
(see below).
|
|
|
|
The available formats are
|
|
\begin{description}\leftskip=20pt
|
|
\item[``*n''] reads a number;
|
|
this is the only format that returns a number instead of a string.
|
|
\item[``*a''] reads the whole file, starting at the current position.
|
|
On end of file, it returns the empty string.
|
|
\item[``*u\emph{string}''] reads until the first occurence of
|
|
\emph{string} in the file.
|
|
The string itself is read, but it is not included in the result.
|
|
If \verb|read| cannot finds the string,
|
|
it reads (and returns) the file until its end,
|
|
or \nil\ if the file was already at its end.
|
|
\item[``*l''] equivalent to \verb|"*u\n"|.
|
|
Reads the next line (skipping the end of line),
|
|
returning \nil\ on end of file.
|
|
This is the default format.
|
|
\item[\emph{number}] reads a string with up to that number of characters,
|
|
or \nil\ on end of file.
|
|
If number is zero,
|
|
it reads nothing and returns an empty string,
|
|
or \nil\ on end of file.
|
|
\end{description}
|
|
|
|
\subsubsection*{\ff \T{write ([filehandle, ] value1, ...)}}\DefLIB{write}
|
|
|
|
Writes the value of each of its arguments to
|
|
filehandle \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.
|
|
|
|
\subsection{System Facilities} \label{libiosys}
|
|
|
|
\subsubsection*{\ff \T{clock ()}}\DefLIB{clock}
|
|
|
|
Returns an approximation of the amount of CPU time
|
|
used by the program, in seconds.
|
|
|
|
\subsubsection*{\ff \T{date ([format [, time]])}}\DefLIB{date}
|
|
|
|
Returns a string or a table containing date and time,
|
|
formatted according to the given string \verb|format|.
|
|
|
|
If the \verb|time| argument is present,
|
|
this is the time to be formatted
|
|
(see the \verb|time| function for a description of this value).
|
|
Otherwise, \verb|date| formats the current time.
|
|
|
|
If \verb|format| starts with \verb|!|,
|
|
then the date is formatted in Coordinated Universal Time.
|
|
|
|
After that optional character,
|
|
if \verb|format| is \verb|*t|,
|
|
then \verb|date| returns a table with the following fields:
|
|
\verb|year|, \verb|month| (1--12), \verb|day| (1--31),
|
|
\verb|hour| (0--23), \verb|min| (0--59), \verb|sec| (0--59),
|
|
\verb|wday| (weekday, Sunday is 1),
|
|
\verb|yday| (day of the year),
|
|
and \verb|isdst| (daylight saving flag).
|
|
|
|
If format is not \verb|*t|,
|
|
then \verb|date| returns the date as a string,
|
|
formatted according with the same rules as the C~function \verb|strftime|.
|
|
When called without arguments,
|
|
\verb|date| returns a reasonable date and time representation that depends on
|
|
the host system and on the current locale (thus, \verb|date()| is equivalent
|
|
to \verb|date("%c")|).
|
|
|
|
\subsubsection*{\ff \T{difftime (t1, t2)}}\DefLIB{difftime}
|
|
|
|
Returns the number of seconds from time \verb|t1| to time \verb|t2|.
|
|
In Posix, Windows, and some other systems,
|
|
this value is exactly \verb|t1|\Math{-}\verb|t2|.
|
|
|
|
\subsubsection*{\ff \T{execute (command)}}\DefLIB{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 a status code, which is system-dependent.
|
|
|
|
\subsubsection*{\ff \T{exit ([code])}}\DefLIB{exit}
|
|
|
|
Calls the C~function \verb|exit|,
|
|
with an optional \verb|code|,
|
|
to terminate the host program.
|
|
The default value for \verb|code| is the success code.
|
|
|
|
\subsubsection*{\ff \T{getenv (varname)}}\DefLIB{getenv}
|
|
|
|
Returns the value of the process environment variable \verb|varname|,
|
|
or \nil\ if the variable is not defined.
|
|
|
|
\subsubsection*{\ff \T{setlocale (locale [, category])}}\DefLIB{setlocale}
|
|
|
|
This function is an interface to the 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.
|
|
|
|
\subsubsection*{\ff \T{time ([table])}}\DefLIB{time}
|
|
|
|
Returns the current time when called without arguments,
|
|
or a time representing the date and time specified by the given table.
|
|
This table must have fields \verb|year|, \verb|month|, and \verb|day|,
|
|
and may have fields \verb|hour|, \verb|min|, \verb|sec|, and \verb|isdst|
|
|
(for a description of these fields, see the \verb|date| function).
|
|
|
|
The returned value is a number, whose meaning depends on your system.
|
|
In Posix, Windows, and some other systems, this number counts the number
|
|
of seconds since some given start time (the ``epoch'').
|
|
In other systems, the meaning is not specified,
|
|
and the number returned bt \verb|time| can be used only as an argument to
|
|
\verb|date| and \verb|difftime|.
|
|
|
|
\subsection{The Reflexive Debug Interface}
|
|
|
|
The library \verb|ldblib| provides
|
|
the functionality of the debug interface to Lua programs.
|
|
If you want to use this library,
|
|
your host application must open it,
|
|
by calling \verb|lua_dblibopen|.
|
|
\DefAPI{lua_dblibopen}
|
|
|
|
You should exert great care when using this library.
|
|
The functions provided here should be used exclusively for debugging
|
|
and similar tasks, such as profiling.
|
|
Please resist the temptation to use them as a
|
|
usual programming tool:
|
|
They can be \emph{very} slow.
|
|
Moreover, \verb|setlocal| and \verb|getlocal|
|
|
violate the privacy of local variables,
|
|
and therefore can compromise some (otherwise) secure code.
|
|
|
|
|
|
\subsubsection*{\ff \T{getinfo (function, [what])}}\DefLIB{getinfo}
|
|
|
|
This function returns a table with information about a function.
|
|
You can give the function directly,
|
|
or you can give a number as the value of \verb|function|,
|
|
which means the function running at level \verb|function| of the stack:
|
|
Level 0 is the current function (\verb|getinfo| itself);
|
|
level 1 is the function that called \verb|getinfo|;
|
|
and so on.
|
|
If \verb|function| is a number larger than the number of active functions,
|
|
then \verb|getinfo| returns \nil.
|
|
|
|
The returned table contains all the fields returned by \verb|lua_getinfo|,
|
|
with the string \verb|what| describing what to get.
|
|
The default for \verb|what| is to get all information available.
|
|
If present,
|
|
the option \verb|f|
|
|
adds a field named \verb|func| with the function itself.
|
|
|
|
For instance, the expression \verb|getinfo(1,"n").name| returns
|
|
the name of the current function, if a reasonable name can be found,
|
|
and \verb|getinfo(print)| returns a table with all available information
|
|
about the \verb|print| function.
|
|
|
|
|
|
\subsubsection*{\ff \T{getlocal (level, local)}}\DefLIB{getlocal}
|
|
|
|
This function returns the name and the value of the local variable
|
|
with index \verb|local| of the function at level \verb|level| of the stack.
|
|
(The first parameter or local variable has index~1, and so on,
|
|
until the last active local variable.)
|
|
The function returns \nil\ if there is no local
|
|
variable with the given index,
|
|
and raises an error when called with a \verb|level| out of range.
|
|
(You can call \verb|getinfo| to check whether the level is valid.)
|
|
|
|
\subsubsection*{\ff \T{setlocal (level, local, value)}}\DefLIB{setlocal}
|
|
|
|
This function assigns the value \verb|value| to the local variable
|
|
with index \verb|local| of the function at level \verb|level| of the stack.
|
|
The function returns \nil\ if there is no local
|
|
variable with the given index,
|
|
and raises an error when called with a \verb|level| out of range.
|
|
(You can call \verb|getinfo| to check whether the level is valid.)
|
|
|
|
\subsubsection*{\ff \T{setcallhook (hook)}}\DefLIB{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.
|
|
The only argument to the call hook is the event name (\verb|"call"| or
|
|
\verb|"return"|).
|
|
You can call \verb|getinfo| with level 2 to get more information about
|
|
the function being called or returning
|
|
(level~0 is the \verb|getinfo| function,
|
|
and level~1 is the hook function).
|
|
When called without arguments,
|
|
this function turns off call hooks.
|
|
\verb|setcallhook| returns the old call hook.
|
|
|
|
\subsubsection*{\ff \T{setlinehook (hook)}}\DefLIB{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 line hook is the line number the interpreter
|
|
is about to execute.
|
|
When called without arguments,
|
|
this function turns off line hooks.
|
|
\verb|setlinehook| returns the old line hook.
|
|
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section{\Index{Lua Stand-alone}} \label{lua-sa}
|
|
|
|
Although Lua has been designed as an extension language,
|
|
to be embedded in a host C~program,
|
|
it is also frequently used as a stand-alone language.
|
|
An interpreter for Lua as a stand-alone language,
|
|
called simply \verb|lua|,
|
|
is provided with the standard distribution.
|
|
This program can be called with any sequence of the following arguments:
|
|
\begin{description}\leftskip=20pt
|
|
\item[\T{-sNUM}] sets the stack size to \T{NUM}
|
|
(if present, this must be the first option);
|
|
\item[\T{-} ] executes \verb|stdin| as a file;
|
|
\item[\T{-c}] calls \verb|lua_close| after processing all arguments;
|
|
\item[\T{-e} \rm\emph{stat}] executes string \emph{stat};
|
|
\item[\T{-f} \rm\emph{filename}] executes file \emph{filename} with the
|
|
remaining arguments in table \verb|arg|;
|
|
\item[\T{-i}] enters interactive mode with prompt;
|
|
\item[\T{-q}] enters interactive mode without prompt;
|
|
\item[\T{-v}] prints version information;
|
|
\item[\T{var=}\rm\emph{value}] sets global \verb|var| to string \verb|"|\emph{value}\verb|"|;
|
|
\item[\emph{filename}] executes file \emph{filename}.
|
|
\end{description}
|
|
When called without arguments,
|
|
\verb|lua| behaves as \verb|lua -v -i| when \verb|stdin| is a terminal,
|
|
and as \verb|lua -| otherwise.
|
|
|
|
All arguments are handled in order, except \verb|-c|.
|
|
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| in \verb|stdin|,
|
|
then will set \verb|a| to \verb|"test"|,
|
|
and finally will run the file \verb|prog.lua|.
|
|
(Here,
|
|
\verb|$| is the shell prompt. Your prompt may be different.)
|
|
|
|
When the option \T{-f filename} is used,
|
|
all remaining arguments in the command line
|
|
are passed to the Lua program \verb|filename| in a table called \verb|arg|.
|
|
In this table,
|
|
the field \verb|n| gets the index of the last argument,
|
|
and the field 0 gets \verb|"filename"|.
|
|
For instance, in the call
|
|
\begin{verbatim}
|
|
$ lua a.lua -f b.lua t1 t3
|
|
\end{verbatim}
|
|
the interpreter first runs the file \T{a.lua},
|
|
then creates a table
|
|
\begin{verbatim}
|
|
arg = {"t1", "t3"; n = 2, [0] = "b.lua"}
|
|
\end{verbatim}
|
|
and finally runs the file \T{b.lua}.
|
|
|
|
The stand-alone interpreter includes
|
|
all standard libraries plus the reflexive debug interface.
|
|
It also provides a \verb|getargs| function that
|
|
can be used to access \emph{all} command line arguments.
|
|
\DefLIB{getargs}
|
|
For instance, if you call Lua with the line
|
|
\begin{verbatim}
|
|
$ lua -c a b
|
|
\end{verbatim}
|
|
then a call to \verb|getargs| in \verb|a| or \verb|b| will return the table
|
|
\begin{verbatim}
|
|
{[0] = "lua", [1] = "-c", [2] = "a", [3] = "b", n = 3}
|
|
\end{verbatim}
|
|
|
|
In interactive mode,
|
|
a multi-line statement can be written ending intermediate
|
|
lines with a backslash (`\verb|\|').
|
|
If the global variable \IndexVerb{_PROMPT} is defined as a string,
|
|
then its value is used as the prompt.
|
|
Therefore, the prompt can be changed directly on the command line:
|
|
\begin{verbatim}
|
|
$ lua _PROMPT='myprompt> ' -i
|
|
\end{verbatim}
|
|
or in any Lua programs by assigning to \verb|_PROMPT|.
|
|
Note the use of \verb|-i| to enter interactive mode; otherwise,
|
|
the program would end just after the assignment to \verb|_PROMPT|.
|
|
|
|
In Unix systems, Lua scripts can be made into executable programs
|
|
by using \verb|chmod +x| and the~\verb|#!| form,
|
|
as in \verb|#!/usr/local/bin/lua|,
|
|
or \verb|#!/usr/local/bin/lua -f| to get other arguments.
|
|
(Of course,
|
|
the location of the Lua interpreter may be different in your machine.
|
|
If \verb|lua| is in your \verb|PATH|,
|
|
then a more portable solution is \verb|#!/usr/bin/env lua|.)
|
|
|
|
|
|
%------------------------------------------------------------------------------
|
|
\section*{Acknowledgments}
|
|
|
|
The authors thank CENPES/PETROBRAS which,
|
|
jointly with \tecgraf, used early versions of
|
|
this system extensively and gave valuable comments.
|
|
The authors also thank Carlos Henrique Levy,
|
|
who found the name of the game.
|
|
Lua means ``moon'' in Portuguese.
|
|
|
|
|
|
\appendix
|
|
|
|
\section*{Incompatibilities with Previous Versions}
|
|
\addcontentsline{toc}{section}{Incompatibilities with Previous Versions}
|
|
|
|
We took a great care to avoid incompatibilities with
|
|
the previous public versions of Lua,
|
|
but some differences had to be introduced.
|
|
Here is a list of all these incompatibilities.
|
|
|
|
|
|
\subsection*{Incompatibilities with \Index{version 4.0}}
|
|
|
|
\subsubsection*{Changes in the Language}
|
|
\begin{itemize}
|
|
|
|
\item
|
|
Function calls written between parentheses result in exactly one value.
|
|
|
|
\item
|
|
A function call as the last expression in a list constructor
|
|
(like \verb|{a,b,f()}}|) has all its return values inserted in the list.
|
|
|
|
\item
|
|
\rwd{global} and \rwd{in} are reserved words.
|
|
|
|
\item
|
|
When a literal string of the form \verb|[[...]]| starts with a newline,
|
|
this newline is ignored.
|
|
|
|
\item Old pre-compiled code is obsolete, and must be re-compiled.
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection*{Changes in the Libraries}
|
|
\begin{itemize}
|
|
|
|
\item
|
|
The \verb|read| option \verb|*w| is obsolete.
|
|
|
|
\item
|
|
The \verb|format| option \verb|%n$| is obsolete.
|
|
|
|
\item
|
|
\verb|newtag| is deprecated, being replaced by \verb|newtype|.
|
|
Tags created in Lua with \verb|newtype| (or \verb|newtag|) can only
|
|
be used for tables.
|
|
|
|
\end{itemize}
|
|
|
|
|
|
\subsubsection*{Changes in the API}
|
|
\begin{itemize}
|
|
|
|
\item
|
|
The \verb|lua_pushuserdata| function has been replaced by
|
|
\verb|lua_newuserdatabox|.
|
|
|
|
\end{itemize}
|
|
|
|
%{===============================================================
|
|
\newpage
|
|
\section*{The Complete Syntax of Lua} \label{BNF}
|
|
|
|
\addcontentsline{toc}{section}{The Complete Syntax of Lua}
|
|
|
|
\renewenvironment{Produc}{\vspace{0.8ex}\par\noindent\hspace{3ex}\it\begin{tabular}{rrl}}{\end{tabular}\vspace{0.8ex}\par\noindent}
|
|
|
|
\renewcommand{\OrNL}{\\ & \Or & }
|
|
%\newcommand{\Nter}[1]{{\rm{\tt#1}}}
|
|
\newcommand{\Nter}[1]{#1}
|
|
|
|
\index{grammar}
|
|
|
|
\begin{Produc}
|
|
|
|
\produc{chunk}{\rep{stat \opt{\ter{;}}}}
|
|
|
|
\produc{block}{chunk}
|
|
|
|
\produc{stat}{%
|
|
varlist1 \ter{=} explist1
|
|
\OrNL functioncall
|
|
\OrNL \rwd{do} block \rwd{end}
|
|
\OrNL \rwd{while} exp \rwd{do} block \rwd{end}
|
|
\OrNL \rwd{repeat} block \rwd{until} exp
|
|
\OrNL \rwd{if} exp \rwd{then} block
|
|
\rep{\rwd{elseif} exp \rwd{then} block}
|
|
\opt{\rwd{else} block} \rwd{end}
|
|
\OrNL \rwd{return} \opt{explist1}
|
|
\OrNL \rwd{break}
|
|
\OrNL \rwd{for} \Nter{Name} \ter{=} exp \ter{,} exp \opt{\ter{,} exp}
|
|
\rwd{do} block \rwd{end}
|
|
\OrNL \rwd{for} \Nter{Name} \opt{\ter{,} \Nter{Name}} \rwd{in} exp
|
|
\rwd{do} block \rwd{end}
|
|
\OrNL \rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} block \rwd{end}
|
|
\OrNL \rwd{local} namelist \opt{init}
|
|
}
|
|
|
|
\produc{funcname}{\Nter{Name} \rep{\ter{.} \Nter{Name}}
|
|
\opt{\ter{:} \Nter{Name}}}
|
|
|
|
\produc{varlist1}{var \rep{\ter{,} var}}
|
|
|
|
\produc{var}{%
|
|
\Nter{Name}
|
|
\Or prefixexp \ter{[} exp \ter{]}
|
|
\Or prefixexp \ter{.} \Nter{Name}
|
|
}
|
|
|
|
\produc{namelist}{\Nter{Name} \rep{\ter{,} \Nter{Name}}}
|
|
|
|
\produc{init}{\ter{=} explist1}
|
|
|
|
\produc{explist1}{\rep{exp \ter{,}} exp}
|
|
|
|
\produc{exp}{%
|
|
\rwd{nil}
|
|
\Or \Nter{Number}
|
|
\Or \Nter{Literal}
|
|
\Or function
|
|
\Or prefixexp
|
|
\OrNL tableconstructor
|
|
\Or exp binop exp
|
|
\Or unop exp
|
|
}
|
|
|
|
\produc{prefixexp}{var \Or functioncall \Or \ter{(} exp \ter{)}}
|
|
|
|
\produc{functioncall}{%
|
|
prefixexp args
|
|
\Or prefixexp \ter{:} \Nter{Name} args
|
|
}
|
|
|
|
\produc{args}{%
|
|
\ter{(} \opt{explist1} \ter{)}
|
|
\Or tableconstructor
|
|
\Or \Nter{Literal}
|
|
}
|
|
|
|
\produc{function}{\rwd{function} \ter{(} \opt{parlist1} \ter{)} block \rwd{end}}
|
|
|
|
\produc{parlist1}{%
|
|
\Nter{Name} \rep{\ter{,} \Nter{Name}} \opt{\ter{,} \ter{\ldots}}
|
|
\Or \ter{\ldots}
|
|
}
|
|
|
|
\produc{tableconstructor}{\ter{\{} \opt{fieldlist} \ter{\}}}
|
|
\produc{fieldlist}{field \rep{fieldsep field} \opt{fieldsep}}
|
|
\produc{field}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp \Or exp}
|
|
\produc{fieldsep}{\ter{,} \Or \ter{;}}
|
|
|
|
\produc{binop}{\ter{+} \Or \ter{-} \Or \ter{*} \Or \ter{/} \Or \ter{\^{ }} \Or
|
|
\ter{..} \Or \ter{<} \Or \ter{<=} \Or \ter{>} \Or \ter{>=}
|
|
\Or \ter{==} \Or \ter{\~{ }=} \OrNL \rwd{and} \Or \rwd{or}}
|
|
|
|
\produc{unop}{\ter{-} \Or \rwd{not}}
|
|
|
|
\end{Produc}
|
|
|
|
%}===============================================================
|
|
|
|
% Index
|
|
|
|
\newpage
|
|
\addcontentsline{toc}{section}{Index}
|
|
\input{manual.id}
|
|
|
|
\end{document}
|