commit 83f0d6ef1ac9ddd2e9771e721aab2af8117a18a1
parent 3088ebd95b7c509ff1a049ef4a10a1c016883490
Author: Roberto Ierusalimschy <roberto@inf.puc-rio.br>
Date: Fri, 24 Jan 2003 14:37:56 -0200
DEPRECATED (new manual uses an independent format instead of LaTeX)
Diffstat:
| D | manual.tex | | | 4539 | ------------------------------------------------------------------------------ |
1 file changed, 0 insertions(+), 4539 deletions(-)
diff --git a/manual.tex b/manual.tex
@@ -1,4539 +0,0 @@
-% $Id: manual.tex,v 2.1 2003/01/22 16:29:38 roberto Exp roberto $
-%{[(
-
-\documentclass[11pt,twoside]{article}
-\usepackage{fullpage}
-\usepackage{iso}
-\usepackage{graphicx}
-
-
-
-% Right arrow (internal use)
-\newcommand{\ra}{\(\rightarrow\)\ }
-
-% Terminal Simbols
-\newcommand{\ter}[1]{{\rm`{\tt#1}'}}
-%reserved words
-\newcommand{\rwd}[1]{{\bf\lowercase{#1}}}
-% empty production
-\newcommand{\emptyprod}{$\epsilon$ }
-
-% repetitions and optionals
-\newcommand{\rep}[1]{{\rm\{}\,#1\,{\rm\}}}
-\newcommand{\opt}[1]{{\rm [}\,#1\,{\,\rm]}}
-\newcommand{\oneormore}[1]{{\rm\{}#1{\/\rm\}$^+$}}
-
-\newcommand{\prg}[1]{{\it #1\/}}
-
-%productions: \produc{non-terminal}{rule}
-\newcommand{\produc}[2]{#1 & \ra & #2\index{grammar!#1}\\}
-
-%new line inside a production
-\newcommand{\NL}{\\ & &}
-%new line indented
-\newcommand{\NLI}{\NL\hspace{2ex}}
-
-% 'or'
-\newcommand{\Or}{$|$ }
-
-% 'or' in a new line
-\newcommand{\OrNL}{\\ & \Or & }
-
-%Environment for productions
-\newenvironment{Produc}{\vspace{0.8ex}\par\noindent\hspace{5ex}\it\begin{tabular}{rrl}}{\end{tabular}\vspace{0.8ex}\par\noindent}
-
-
-%\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@{\Q{#1} event}}\index{metamethod!#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{\Q}[1]{``#1''}
-\newcommand{\Em}{---}
-\newcommand{\En}{--}
-\newcommand{\C}[1]{}
-
-\newcommand{\ff}{$\bullet$\ }
-
-\newcommand{\Version}{5.0 (beta)}
-
-\newcommand{\Nter}[1]{{\tt#1}}
-\newcommand{\NOTE}{\par\medskip\noindent\emph{NOTE}: }
-
-\newcommand{\At}{{\tt @}} %{\verb|@|}
-\newcommand{\Nb}{~}
-
-\makeindex
-
-\begin{document}
-
-%{===============================================================
-\thispagestyle{empty}
-\pagestyle{empty}
-
-{
-\parindent=0pt
-\vglue1.5in
-{\LARGE\bf
-The Lua Programming Language}
-\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\ 2002 Tecgraf, PUC-Rio. All rights reserved.
-
-Permission is hereby granted, free of charge,
-to any person obtaining a copy of this software
-and associated documentation files (the "Software"),
-to deal in the Software without restriction,
-including without limitation the rights to use, copy, modify,
-merge, publish, distribute, sublicense,
-and/or sell copies of the Software,
-and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED,
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
-FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
-OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
-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: 2003/01/22 16:29: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 é uma linguagem de programação
-poderosa e leve,
-projetada para estender aplicações.
-Lua também é frequentemente usada como uma linguagem de propósito geral.
-Lua combina programação procedural
-(com sintaxe semelhante à de Pascal)
-com
-poderosas construções para descrição de dados,
-baseadas em tabelas associativas e semântica extensível.
-Lua é
-tipada dinamicamente,
-interpretada a partir de \emph{opcodes},
-e tem gerenciamento automático de memória com coleta de lixo.
-Essas características fazem de Lua uma linguagem ideal para
-configuração,
-automação (\emph{scripting})
-e prototipagem rápida.
-
-Este documento descreve a versão \Version{} da linguagem de
-programação Lua e a Interface de Programação (API) que permite
-a interação entre programas Lua e programas C~hospedeiros.
-\end{abstract}
-
-\newpage
-\null
-\newpage
-\tableofcontents
-
-\newpage
-\setcounter{page}{1}
-\pagestyle{plain}
-\pagenumbering{arabic}
-
-\catcode`\_=12
-\catcode`\$=12
-\catcode`\#=12
-\catcode`\%=12
-\catcode`\^=12
-\catcode`\~=12
-\catcode`\&=12
-
-
-
-\C{-------------------------------------------------------------------------}
-\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 \Q{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\Nb{}functions to be called by Lua code.
-Through the use of C\Nb{}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.\Nb{}Ierusalimschy, L.\Nb{}H.\Nb{}de Figueiredo, and W.\Nb{}Celes.
-Lua\Em{}an extensible extension language.
-\emph{Software: Practice & Experience} {\bf 26} #6 (1996) 635\En{}652.
-\item
-L.\Nb{}H.\Nb{}de Figueiredo, R.\Nb{}Ierusalimschy, and W.\Nb{}Celes.
-The design and implementation of a language for extending applications.
-\emph{Proceedings of XXI Brazilian Seminar on Software and Hardware} (1994) 273\En{}283.
-\item
-L.\Nb{}H.\Nb{}de Figueiredo, R.\Nb{}Ierusalimschy, and W.\Nb{}Celes.
-Lua: an extensible embedded language.
-\emph{Dr. Dobb's Journal} {\bf 21} #12 (Dec 1996) 26\En{}33.
-\item
-R.\Nb{}Ierusalimschy, L.\Nb{}H.\Nb{}de Figueiredo, and W.\Nb{}Celes.
-The evolution of an extension language: a history of Lua,
-\emph{Proceedings of V Brazilian Symposium on Programming Languages} (2001) B-14\En{}B-28.
-\end{itemize}
-
-Lua means \Q{moon} in Portuguese.
-
-\C{-------------------------------------------------------------------------}
-\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\Nb{}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.
-The host program can create multiple independent global
-environments, and freely switch among them \see{mangstate}.
-
-The unit of execution of Lua is called a \Def{chunk}.
-A chunk is simply a sequence of statements.
-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 that a chunk makes to 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.
-Programs in source and compiled forms are interchangeable;
-Lua automatically detects the file type and acts accordingly.
-\index{pre-compilation}
-
-
-\subsection{Table of Globals} \label{global-table}
-
-????
-
-\subsection{\Index{Values and Types}} \label{TypesSec}
-
-Lua is a \emph{dynamically typed language}.
-That means that
-variables do not have types; only values do.
-There are no type definitions in the language.
-All values carry their own type.
-
-There are eight \Index{basic types} in Lua:
-\Def{nil}, \Def{boolean}, \Def{number},
-\Def{string}, \Def{function}, \Def{userdata}, \Def{thread}, 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 false,
-and any other value makes it true.
-\emph{Number} represents real (double-precision floating-point) numbers.
-(It is not difficult to build Lua interpreters that use other
-internal representations for numbers,
-such as single-precision float or long integers.)
-\emph{String} represents arrays of characters.
-\index{eight-bit clean}
-Lua is 8-bit clean,
-so strings may contain any 8-bit character,
-including embedded zeros (\verb|'\0'|) \see{lexical}.
-
-Functions are \emph{first-class values} in Lua.
-That 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 C data to
-be stored in Lua variables.
-This type corresponds to a block of raw memory
-and has no pre-defined operations in Lua,
-except assignment and identity test.
-However, by using \emph{metatables},
-the programmer can define operations for userdata values
-\see{metatable}.
-Userdata values cannot be created or modified in Lua,
-only through the C\Nb{}API.
-This guarantees the integrity of data owned by the host program.
-
-The type \Def{thread} represents independent threads of execution,
-and it is used to implement coroutines.
-(This is an experimental area; it needs more documentation,
-and is subject to changes in the future.)
-
-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 can be \emph{heterogeneous},
-that is, they can contain values of all types (except \nil{}).
-Tables are the sole data structuring mechanism in Lua;
-they may be used to represent not only 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.
-Thus tables may also carry \emph{methods} \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 function returns
-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 and 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.
-
-We call the keys in a metatable \Index{events},
-and the values \Index{metamethods}.
-In the previous example, \verb|"add"| is the event,
-and the function is the metamethod that performs the addition.
-
-A metatable controls how an object behaves in arithmetic operations,
-order comparisons, concatenation, and indexing.
-A metatable can also define a function to be called when a userdata
-is garbage collected.
-\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|setmetatable| and \verb|getmetatable|
-functions \see{pdf-getmetatable}.
-
-
-
-\subsection{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 where 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.
-Variables are assumed to be global unless explicitly declared local
-\see{localvar}.
-Before the first assignment to a variable, its value is \nil{}.
-
-All global variables live as fields in ordinary Lua tables.
-Usually, globals live in a table called \Index{table of globals}.
-However, a function can individually change its global table,
-so that all global variables in that function will refer to that table.
-This mechanism allows the creation of \Index{namespaces} and other
-modularization facilities.
-
-\Index{Local variables} are lexically scoped.
-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.
-That 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\Nb{}API,
-you can set garbage-collector metamethods for userdata \see{metatable}.
-When it is about to free a userdata,
-Lua calls the metamethod associated with event \verb|gc| in the
-userdata's metatable.
-Using such 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 adjusted,
-and then the threshold is reset to twice the new value of the byte counter.
-
-Through the C\Nb{}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 controlled by the value of the
-\verb|__mode| field of its metatable.
-If the \verb|__mode| field is a string containing the character \verb|k|,
-the keys in the table are weak.
-If \verb|__mode| contains \verb|v|,
-the values in the table are weak.
-
-
-\C{-------------------------------------------------------------------------}
-\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 if
- in local nil not or
- repeat return then true until
- while
-\end{verbatim}
-
-Lua is a case-sensitive language:
-\T{and} is a reserved word, but \T{And} and \T{AND}
-are two different, valid identifiers.
-As a convention, identifiers starting with an underscore followed by
-uppercase letters (such as \verb|_VERSION|)
-are reserved for internal variables used by Lua.
-
-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|\"|' (quotation mark),
-`\verb|\'|' (apostrophe),
-`\verb|\[|' (left square bracket),
-`\verb|\]|' (right square bracket),
-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
-using 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|\0|'.
-
-Literal strings can also be delimited by matching
-\verb|[[| \Math{\ldots} \verb|]]|.
-Literals in this bracketed form may run for several lines,
-may contain nested \verb|[[| \Math{\ldots} \verb|]]| pairs,
-and do not interpret escape sequences.
-For convenience,
-when the opening \verb|[[| is immediately followed by a newline,
-the newline is not included in the string. \C{ ]]}
-That 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\Nb{}97,
-newline is coded as\Nb{}10, and `\verb|1|' is coded as\Nb{}49),
-the four literals below denote the same string:
-\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|--|);
-If the text after \verb|--| is different from \verb|[[|,
-the comment is a short comment,
-that runs until the end of the line.
-Otherwise, it is a long comment,
-that runs until the corresponding \verb|]]|.
-Long comments may run for several lines,
-and may contain nested \verb|[[| \Math{\ldots} \verb|]]| pairs.
-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.
-\C{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}{\Nter{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{.} \Nter{Name}}
-\end{Produc}
-
-The expression denoting the table to be indexed has a restricted syntax;
-see \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 the assignment
-\verb|_glob.x = val|,
-where \verb|_glob| is the table of globals of the running function
-(see \See{global-table} for a discussion about the table of globals).
-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 \verb|_glob.x|
-(again, see \See{global-table} for a discussion about \verb|_glob|).
-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 the
-\verb|settable_event| and \verb|gettable_event| functions.
-(These functions are not defined or callable 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
-and variable declarations.
-
-\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}
-
-\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 to produce a single statement:
-\begin{Produc}
-\produc{stat}{\rwd{do} block \rwd{end}}
-\end{Produc}
-\IndexKW{do}
-Explicit blocks are useful
-to control the scope of variable declarations.
-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 needed,
-the excess values are thrown away.
-If there are fewer values than 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 adjustment
-(except when the call is enclosed in parentheses; see \See{expressions}).
-
-The assignment statement first evaluates all its expressions,
-and only then are the assignments performed.
-Thus the code
-\begin{verbatim}
- i = 3
- i, a[i] = i+1, 20
-\end{verbatim}
-sets \verb|a[3]| to 20, without affecting \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}
-Lua also has a \rwd{for} statement, in two flavors \see{for}.
-
-The \Index{condition expression} \M{exp} of a
-control structure may return any value.
-Both \False{} and \nil{} are considered false.
-All values different from \nil{} and \False{} are considered true
-(in particular, the number 0 and the empty string are also true).
-
-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,
-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,
-and to skip 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,
-those 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 numeric and one generic.
-\IndexKW{for}\IndexKW{in}
-
-The numeric \rwd{for} loop repeats a block of code while a
-control variable runs through an arithmetic progression.
-It has the following syntax:
-\begin{Produc}
-\produc{stat}{\rwd{for} \Nter{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 passes 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\Nb{}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 over functions,
-called \Index{generators}.
-It calls its generator 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} \Nter{Name} \rep{\ter{,} \Nter{Name}} \rwd{in} explist1
- \rwd{do} block \rwd{end}}
-\end{Produc}
-A \rwd{for} statement like
-\begin{verbatim}
- for var_1, ..., var_n in explist do block end
-\end{verbatim}
-is equivalent to the code:
-\begin{verbatim}
- do
- local _f, _s, var_1, ..., var_n = explist
- while true do
- var_1, ..., var_n = _f(_s, var_1)
- if var_1 == nil then break end
- block
- end
- end
-\end{verbatim}
-Note the following:
-\begin{itemize}\itemsep=0pt
-\item \verb|explist| is evaluated only once.
-Its results are a \Q{generator} function,
-a \Q{state}, and an initial value for the first \Q{iterator variable}.
-\item \verb|_f| and \verb|_s| are invisible variables.
-The names are here for explanatory purposes only.
-\item The behavior is \emph{undefined} if you assign to any
-\verb|var_i| inside the block.
-\item You can use \rwd{break} to exit a \rwd{for} loop.
-\item The loop variables \verb|var_i| 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.
-\end{itemize}
-
-
-\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}{\Nter{Name} \rep{\ter{,} \Nter{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},
-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}
-
-\C{\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}\IndexKW{false}\IndexKW{true}
-
-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 operators, 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 metamethod is called \see{metatable}.
-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.
-
-\C{TODO eq metamethod}
-
-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 \Q{lt} or the \Q{le} metamethod is called \see{metatable}.
-
-
-\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}
-
-\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 \Q{concat} metamethod is called \see{metatable}.
-
-\subsubsection{Precedence}
-\Index{Operator precedence} in Lua follows the table below,
-from lower to higher priority:
-\begin{verbatim}
- or
- and
- < > <= >= ~= ==
- ..
- + -
- * /
- not - (unary)
- ^
-\end{verbatim}
-The \verb|..| (concatenation) and \verb|^| (exponentiation)
-operators are right associative.
-All other binary operators are left associative.
-
-\subsubsection{Table Constructors} \label{tableconstructor}
-Table \Index{constructors} are expressions that create tables;
-every time a constructor is evaluated, a new table is created.
-Constructors can be used to create empty tables,
-or to create a table and initialize some 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
- \Nter{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| are equivalent to
-\verb|[i] = exp|, where \verb|i| are 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 that function is called,
-with the given arguments.
-Otherwise, its \Q{call} metamethod is called,
-having as first parameter the value of \M{prefixexp},
-followed by the original call arguments
-\see{metatable}.
-
-The form
-\begin{Produc}
-\produc{functioncall}{prefixexp \ter{:} \Nter{name} args}
-\end{Produc}
-can be used to call \Q{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\Nb{}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\Nb{}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} funcbody}
-\produc{funcbody}{\ter{(} \opt{parlist1} \ter{)} block \rwd{end}}
-\end{Produc}
-
-The following syntactic sugar simplifies function definitions:
-\begin{Produc}
-\produc{stat}{\rwd{function} funcname funcbody}
-\produc{stat}{\rwd{local} \rwd{function} \Nter{name} funcbody}
-\produc{funcname}{\Nter{name} \rep{\ter{.} \Nter{name}} \opt{\ter{:} \Nter{name}}}
-\end{Produc}
-The statement
-\begin{verbatim}
- function f () ... end
-\end{verbatim}
-translates to
-\begin{verbatim}
- f = function () ... end
-\end{verbatim}
-The statement
-\begin{verbatim}
- function t.a.b.c.f () ... end
-\end{verbatim}
-translates to
-\begin{verbatim}
- t.a.b.c.f = function () ... end
-\end{verbatim}
-The statement
-\begin{verbatim}
- local function f () ... end
-\end{verbatim}
-translates to
-\begin{verbatim}
- local f; 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}
-and may have different tables of globals \see{global-table}.
-
-Parameters act as local variables that are
-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\Nb{}\verb|n| whose value is the number of extra arguments,
-and with the extra arguments at positions 1,\Nb{}2,\Nb{}\ldots,\Nb{}\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 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 \Q{outside} variable.
-
-Because of these \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
-\Q{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}
-The loop creates ten closures
-(that is, instances of the anonymous function).
-Each of these closures 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\Nb{}code in the host program
-calling a function from the Lua library \see{pcall}.
-Whenever an error occurs during Lua compilation or execution,
-control returns to C,
-which can take appropriate measures
-(such as to print an error message).
-
-Lua code can explicitly generate an error by calling the
-function \verb|error| \see{pdf-error}.
-If you need to catch errors in Lua,
-you can use the \verb|pcall| function \see{pdf-pcall}.
-
-
-\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 certain special operations.
-You can query and change the metatable of an object with
-functions \verb|setmetatable| and \verb|getmetatable| \see{pdf-getmetatable}.
-
-For each of those operations Lua associates a specific key
-called an \emph{event}.
-When Lua performs one of those operations over a table or a userdata,
-it checks whether that object has a metatable with the corresponding event.
-If so, the value associated with that key (the \IndexEmph{metamethod})
-controls how Lua will perform the operation.
-
-Metatables control the operations listed next.
-Each operation is identified by its corresponding name.
-The key for each operation is a string with its name prefixed by
-two underscores;
-for instance, the key for operation \Q{add} is the
-string \verb|"__add"|.
-The semantics of these operations is better explained by a Lua function
-describing how the interpreter executes that operation.
-\C{Each function shows how a handler is called,}
-\C{its arguments (that is, its signature),}
-\C{its results,}
-\C{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|, etc.)
-are described in \See{predefined}.
-
-\begin{description}
-
-\item[\Q{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 that function,
-the behavior of the \Q{add} operation is
-\begin{verbatim}
- function add_event (op1, op2)
- local o1, o2 = tonumber(op1), tonumber(op2)
- if o1 and o2 then -- both operands are numeric
- return o1+o2 -- '+' here is the primitive 'add'
- else -- at least one of the operands is not numeric
- local 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[\Q{sub}:]\IndexTM{sub}
-the \verb|-| operation.
-Behavior similar to the \Q{add} operation.
-
-\item[\Q{mul}:]\IndexTM{mul}
-the \verb|*| operation.
-Behavior similar to the \Q{add} operation.
-
-\item[\Q{div}:]\IndexTM{div}
-the \verb|/| operation.
-Behavior similar to the \Q{add} operation.
-
-\item[\Q{pow}:]\IndexTM{pow}
-the \verb|^| operation (exponentiation) operation.
-\begin{verbatim} ??
- function pow_event (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[\Q{unm}:]\IndexTM{unm}
-the unary \verb|-| operation.
-\begin{verbatim}
- function unm_event (op)
- local o = tonumber(op)
- if o then -- operand is numeric
- return -o -- '-' here is the primitive 'unm'
- else -- the operand is not numeric.
- -- Try to get a 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[\Q{lt}:]\IndexTM{lt}
-the \verb|<| operation.
-\begin{verbatim}
- function lt_event (op1, op2)
- if type(op1) == "number" and type(op2) == "number" then
- return op1 < op2 -- numeric comparison
- elseif type(op1) == "string" and type(op2) == "string" then
- return op1 < op2 -- lexicographic comparison
- else
- local h = getbinhandler(op1, op2, "__lt")
- if h then
- return h(op1, op2)
- else
- error("unexpected type at comparison");
- end
- end
- end
-\end{verbatim}
-\verb|a>b| is equivalent to \verb|b<a|.
-
-\item[\Q{le}:]\IndexTM{lt}
-the \verb|<=| operation.
-\begin{verbatim}
- function le_event (op1, op2)
- if type(op1) == "number" and type(op2) == "number" then
- return op1 <= op2 -- numeric comparison
- elseif type(op1) == "string" and type(op2) == "string" then
- return op1 <= op2 -- lexicographic comparison
- else
- local h = getbinhandler(op1, op2, "__le")
- if h then
- return h(op1, op2)
- else
- h = getbinhandler(op1, op2, "__lt")
- if h then
- return not h(op2, op1)
- else
- error("unexpected type at comparison");
- end
- end
- end
- end
-\end{verbatim}
-\verb|a>=b| is equivalent to \verb|b<=a|.
-Notice that, in the absence of a \Q{le} metamethod,
-Lua tries the \Q{lt}, assuming that \verb|a<=b| is
-equivalent to \verb|not (b<a)|.
-
-
-\item[\Q{concat}:]\IndexTM{concatenation}
-the \verb|..| (concatenation) operation.
-\begin{verbatim}
- function concat_event (op1, op2)
- if (type(op1) == "string" or type(op1) == "number") and
- (type(op2) == "string" or type(op2) == "number") then
- return op1..op2 -- primitive string concatenation
- else
- local h = getbinhandler(op1, op2, "__concat")
- if h then
- return h(op1, op2)
- else
- error("unexpected type for concatenation")
- end
- end
- end
-\end{verbatim}
-
-\item[\Q{index}:]\IndexTM{index}
-The \Q{gettable} operation \verb|table[key]|.
-\begin{verbatim}
- function gettable_event (table, key)
- local h
- if type(table) == "table" then
- local v = rawget(table, key)
- if v ~= nil then return v end
- h = metatable(table).__index
- if h == nil then return nil end
- else
- h = metatable(table).__index
- if h == nil then
- error("indexed expression not a table");
- 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[\Q{newindex}:]\IndexTM{index}
-The \Q{settable} operation \verb|table[key] = value|.
-\begin{verbatim}
- function settable_event (table, key, value)
- local h
- if type(table) == "table" then
- local v = rawget(table, key)
- if v ~= nil then rawset(table, key, value); return end
- h = metatable(table).__newindex
- if h == nil then rawset(table, key, value); return end
- else
- h = metatable(table).__newindex
- if h == nil then
- error("indexed expression not a table");
- end
- end
- if type(h) == "function" then
- return h(table, key,value) -- call the handler
- else h[key] = value -- or repeat operation with it
- end
-\end{verbatim}
-
-
-\item[\Q{call}:]\IndexTM{call}
-called when Lua calls a value.
-\begin{verbatim}
- function function_event (func, ...)
- if type(func) == "function" then
- return func(unpack(arg)) -- regular call
- else
- local h = metatable(func).__call
- if h then
- table.insert(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 may also 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_event (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 the same cycle).
-
-
-
-\subsection{Coroutines}
-
-Lua supports coroutines,
-also called \emph{semi-coroutines}
-or \emph{collaborative multithreading}.
-A coroutine in Lua represents an independent thread of execution.
-Unlike \Q{real} threads, however,
-a coroutine only suspends its execution by explicitly calling
-an yield function.
-
-You create a coroutine with a call to \IndexVerb{coroutine.create}.
-Its sole argument is a function
-that is the main function of the coroutine.
-The \verb|coroutine.create| only creates a new coroutine and
-returns a handle to it (an object of type \emph{thread}).
-It does not start the coroutine execution.
-
-When you first call \IndexVerb{coroutine.resume},
-passing as argument the thread returned by \verb|coroutine.create|,
-the coroutine starts its execution,
-at the first line of its main function.
-Extra arguments passed to \verb|coroutine.resume| are given as
-parameters for the coroutine main function.
-After the coroutine starts running,
-it runs until it terminates or it \emph{yields}.
-
-A coroutine can terminate its execution in two ways:
-Normally, when its main function returns
-(explicitly or implicitly, after the last instruction);
-and abnormally, if there is an unprotected error.
-In the first case, \verb|coroutine.resume| returns \True{},
-plus any values returned by the coroutine main function.
-In case of errors, \verb|coroutine.resume| returns \False{}
-plus an error message.
-
-A coroutine yields by calling \IndexVerb{coroutine.yield}.
-When a coroutine yields,
-the corresponding \verb|coroutine.resume| returns immediately,
-even if the yield happens inside nested function calls
-(that is, not in the main function,
-but in a function directly or indirectly called by the main function).
-In the case of a yield, \verb|coroutine.resume| also returns \True{},
-plus any values passed to \verb|coroutine.yield|.
-The next time you resume the same coroutine,
-it continues its execution from the point where it yielded,
-with the call to \verb|coroutine.yield| returning any extra
-arguments passed to \verb|coroutine.resume|.
-
-The \IndexVerb{coroutine.wrap} function creates a coroutine
-like \verb|coroutine.create|,
-but instead of returning the coroutine itself,
-it returns a function that, when called, resumes the coroutine.
-Any arguments passed to that function
-go as extra arguments to resume.
-The function returns all the values returned by resume,
-but the first one (the boolean error code).
-Unlike \verb|coroutine.resume|,
-this function does not catch errors;
-any error is propagated to the caller.
-
-As a complete example,
-consider the next code:
-\begin{verbatim}
-function foo1 (a)
- print("foo", a)
- return coroutine.yield(2*a)
-end
-
-co = coroutine.create(function (a,b)
- print("co-body", a, b)
- local r = foo1(a+1)
- print("co-body", r)
- local r, s = coroutine.yield(a+b, a-b)
- print("co-body", r, s)
- return b, "end"
-end)
-
-a, b = coroutine.resume(co, 1, 10)
-print("main", a, b)
-a, b, c = coroutine.resume(co, "r")
-print("main", a, b, c)
-a, b, c = coroutine.resume(co, "x", "y")
-print("main", a, b, c)
-a, b = coroutine.resume(co, "x", "y")
-print("main", a, b)
-\end{verbatim}
-When you run it, it produces the following output:
-\begin{verbatim}
-co-body 1 10
-foo 2
-main true 4
-co-body r
-main true 11 -9
-co-body x y
-main true 10 end
-main false cannot resume dead coroutine
-\end{verbatim}
-
-
-
-\C{-------------------------------------------------------------------------}
-\section{The Application Program Interface}\label{API}
-\index{C API}
-
-This section describes the API for Lua, that is,
-the set of C\Nb{}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 \Q{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, 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 (void);
-\end{verbatim}
-\DefAPI{lua_open}
-
-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 metamethods, if any)
-and frees all dynamic memory used by that state.
-On several platforms, you may not need to call this function,
-because all resources are naturally released when the host program ends.
-On the other hand,
-long-running programs \Em{}
-like a daemon or a web server \Em{}
-might need to release states as soon as they are not needed,
-to avoid growing too large.
-
-
-\subsection{Threads}
-
-Lua offers partial support for multiple threads of execution.
-If you have a C\Nb{}library that offers multi-threading,
-then Lua can cooperate with it to implement the equivalent facility in Lua.
-Also, Lua implements its own coroutine system on top of threads.
-The following function creates a new \Q{thread} in Lua:
-\begin{verbatim}
- lua_State *lua_newthread (lua_State *L);
-\end{verbatim}
-\DefAPI{lua_newthread}
-The new state returned by this function shares with the original state
-all global environment (such as tables),
-but has an independent run-time stack.
-(The use of these multiple stacks must be \Q{synchronized} 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 virtual \emph{stack} to pass values to and from C.
-Each element in this stack represents a Lua value
-(\nil{}, number, string, etc.).
-
-Each C invocation has its own stack.
-Whenever Lua calls C, the called function gets a new stack,
-which is independent of previous stacks and of stacks of still
-active C functions.
-That stack initially contains any arguments to the C function,
-and it is where the C function pushes its results \see{LuacallC}.
-
-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\Nb{}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\Nb{}1 represents the first element
-(that is, the element that was pushed onto the stack first),
-and
-index\Nb{}\M{n} represents the last element;
-index\Nb{}\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\Nb{}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\Nb{}1,
-the result of \verb|lua_gettop| is equal to the number of elements in the stack
-(and so 0\Nb{}means an empty stack).
-
-When you interact with Lua API,
-\emph{you are responsible for controlling stack overflow}.
-The function
-\begin{verbatim}
- int lua_checkstack (lua_State *L, int extra);
-\end{verbatim}
-\DefAPI{lua_checkstack}
-grows the stack size to \verb|top + extra| elements;
-it returns false if it cannot grow the stack to that size.
-This function never shrinks the stack;
-if the stack is already bigger than the new size,
-it is left unchanged.
-
-Whenever Lua calls C, \DefAPI{LUA_MINSTACK}
-it ensures that \verb|lua_checkstack(L, LUA_MINSTACK)| is true,
-that is,
-at least \verb|LUA_MINSTACK| positions are still available.
-\verb|LUA_MINSTACK| is defined in \verb|lua.h| as 20,
-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, that is, indices up to the maximum stack size
-you (or Lua) have set through \verb|lua_checkstack|.
-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 never an acceptable index.
-
-Unless otherwise noted,
-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\Nb{}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 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 replacing 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*
- lua_settop(L, 6) --> 30 40 nil 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);
- int lua_islightuserdata (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}\DefAPI{lua_islightuserdata}
-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 \Q{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|,
-\verb|LUA_TTHREAD|,
-\verb|LUA_TLIGHTUSERDATA|.
-The following function translates such constants to a type name:
-\begin{verbatim}
- const char *lua_typename (lua_State *L, int type);
-\end{verbatim}
-\DefAPI{lua_typename}
-
-The \verb|lua_is*| functions return\Nb{}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 has a boolean value).
-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},
-\verb|lua_isfunction| accepts both Lua functions and C\Nb{}functions,
-and \verb|lua_isuserdata| accepts both full and light userdata.
-To distinguish between Lua functions and C\Nb{}functions,
-you should use \verb|lua_iscfunction|.
-To distinguish between full and light userdata,
-you can use \verb|lua_islightuserdata|.
-To distinguish between numbers and numerical strings,
-you can use \verb|lua_type|.
-
-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}.
-Both functions return 0 if any of the indices are non-valid.
-
-\subsection{Getting Values from the Stack}\label{lua-to}
-
-To translate a value in the stack to a specific C\Nb{}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 \Q{boolean} value (that is, 0 or 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\Nb{}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\Nb{}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.
-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\Nb{}function.
-This value must be a C\Nb{}function;
-otherwise, \verb|lua_tocfunction| returns \verb|NULL|.
-The type \verb|lua_CFunction| is explained in \See{LuacallC}.
-
-\verb|lua_touserdata| is explained in \See{userdata}.
-
-
-\subsection{Pushing Values onto the Stack}
-
-The API has the following functions to
-push C\Nb{}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);
- void lua_pushlightuserdata (lua_State *L, void *p);
-\end{verbatim}
-
-\DefAPI{lua_pushnumber}\DefAPI{lua_pushlstring}\DefAPI{lua_pushstring}
-\DefAPI{lua_pushcfunction}\DefAPI{lua_pushlightuserdata}\DefAPI{lua_pushboolean}
-\DefAPI{lua_pushnil}\label{pushing}
-These functions receive a C\Nb{}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\Nb{}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.
-
-You can also push \Q{formatted} strings:
-\begin{verbatim}
- const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
- const char *lua_pushvfstring (lua_State *L, const char *fmt,
- va_list argp);
-\end{verbatim}
-\DefAPI{lua_pushfstring}\DefAPI{lua_pushvfstring}
-Both functions push onto the stack a formatted string,
-and return a pointer to that string.
-These functions are similar to \verb|sprintf| and \verb|vsprintf|,
-but with some important differences:
-\begin{itemize}
-\item You do not have to allocate the space for the result;
-the result is a Lua string, and Lua takes care of memory allocation
-(and deallocation, later).
-\item The conversion specifiers are quite restricted.
-There are no flags, widths, or precisions.
-The conversion specifiers can be simply
-\verb|%%| (inserts a \verb|%| in the string),
-\verb|%s| (inserts a zero-terminated string, with no size restrictions),
-\verb|%f| (inserts a \verb|lua_Number|),
-\verb|%d| (inserts an \verb|int|),
-\verb|%c| (inserts an \verb|int| as a character).
-\end{itemize}
-
-
-\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}.
-The first counts the amount of memory in use by Lua;
-when the count reaches the threshold,
-Lua runs its garbage collector.
-After the collection, the count is updated,
-and the threshold is set to twice the count value.
-
-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 collection.
-After the collection,
-a new threshold is set according to the previous rule.
-
-\C{TODO do we need a new way to do that??}
-\C{ If you want to change the adaptive behavior of the garbage collector,}
-\C{ you can use the garbage-collection tag method for \nil{} }
-\C{ to set your own threshold}
-\C{ (the tag method is called after Lua resets the threshold).}
-
-
-\subsection{Userdata}\label{userdata}
-
-Userdata represents C values in Lua.
-Lua supports two types of userdata:
-\Def{full userdata} and \Def{light userdata}.
-
-A full userdata represents a block of memory.
-It is an object (like a table):
-You must create it, it can have its own metatable,
-and you can detect when it is being collected.
-A full userdata is only equal to itself (under raw equality).
-
-A light userdata represents a pointer.
-It is a value (like a number):
-You do not create it, it has no metatables,
-it is not collected (as it was never created).
-A light userdata is equal to \Q{any}
-light userdata with the same address.
-
-In Lua code, there is no way to test whether a userdata is full or light;
-both have type \verb|userdata|.
-In C code, \verb|lua_type| returns \verb|LUA_TUSERDATA| for full userdata,
-and \verb|LUA_LIGHTUSERDATA| for light userdata.
-
-You can create new full userdata with the following function:
-\begin{verbatim}
- void *lua_newuserdata (lua_State *L, size_t size);
-\end{verbatim}
-\DefAPI{lua_newuserdata}
-It 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.
-
-To push a light userdata into the stack you use
-\verb|lua_pushlightuserdata| \see{pushing}.
-
-\verb|lua_touserdata| \see{lua-to} retrieves the value of a userdata.
-When applied on a full userdata, it returns the address of its block;
-when applied on a light userdata, it returns its pointer;
-when applied on a non-userdata value, it returns \verb|NULL|.
-
-When Lua collects a full userdata,
-it calls its \verb|gc| metamethod, if any,
-and then it frees its corresponding memory.
-
-
-\subsection{Metatables}
-
-The following functions allow you to manipulate the metatables
-of an object:
-\begin{verbatim}
- int lua_getmetatable (lua_State *L, int objindex);
- int lua_setmetatable (lua_State *L, int objindex);
-\end{verbatim}
-\DefAPI{lua_getmetatable}\DefAPI{lua_setmetatable}
-Both get at \verb|objindex| a valid index for an object.
-\verb|lua_getmetatable| pushes on the stack the metatable of that object;
-\verb|lua_setmetatable| sets the table on the top of the stack as the
-new metatable for that object (and pops the table).
-
-If the object does not have a metatable,
-\verb|lua_getmetatable| returns 0, and pushes nothing on the stack.
-\verb|lua_setmetatable| returns 0 when it cannot
-set the metatable of the given object
-(that is, when the object is not a userdata nor a table);
-even then it pops the table from the stack.
-
-\subsection{Loading Lua Chunks}
-
-You can load a Lua chunk with
-\begin{verbatim}
- typedef const char * (*lua_Chunkreader)
- (lua_State *L, void *data, size_t *size);
-
- int lua_load (lua_State *L, lua_Chunkreader reader, void *data,
- const char *chunkname);
-\end{verbatim}
-\DefAPI{Chunkreader}\DefAPI{lua_load}
-The return values of \verb|lua_load| are:
-\begin{itemize}
-\item 0 \Em{} no errors;
-\item \IndexAPI{LUA_ERRSYNTAX} \Em{}
-syntax error during pre-compilation.
-\item \IndexAPI{LUA_ERRMEM} \Em{}
-memory allocation error.
-\end{itemize}
-If there are no errors,
-\verb|lua_load| pushes the compiled chunk as a Lua
-function on top of the stack.
-Otherwise, it pushes an error message.
-
-\verb|lua_load| automatically detects whether the chunk is text or binary,
-and loads it accordingly (see program \IndexVerb{luac}).
-
-\verb|lua_load| uses the \emph{reader} to read the chunk.
-Everytime it needs another piece of the chunk,
-it calls the reader,
-passing along its \verb|data| parameter.
-The reader must return a pointer to a block of memory
-with a new part of the chunk,
-and set \verb|size| to the block size.
-To signal the end of the chunk, the reader must return \verb|NULL|.
-The reader function may return pieces of any size greater than zero.
-
-In the current implementation,
-the reader function cannot call any Lua function;
-to ensure that, it always receives \verb|NULL| as the Lua state.
-
-The \emph{chunkname} is used for error messages
-and debug information \see{debugI}.
-
-See the auxiliary library (\verb|lauxlib|)
-for examples of how to use \verb|lua_load|,
-and for some ready-to-use functions to load chunks
-from files and from strings.
-
-\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| points 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 metamethod
-for the \Q{index} event \see{metatable}.
-To get the real value of any table key,
-without invoking any metamethod,
-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| points 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 metamethod
-for the \Q{settable} or \Q{newindex} events.
-To set the real value of any table index,
-without invoking any metamethod,
-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| points to the table to be traversed.
-The function pops a key from the stack,
-and pushes a key-value pair from the table
-(the \Q{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 the next call to \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);
-\end{verbatim}
-\DefAPI{lua_rawgeti}
-\DefAPI{lua_rawseti}
-
-\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.
-
-
-\subsection{Calling Functions}
-
-Functions defined in Lua
-and C\Nb{}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}
- void lua_call (lua_State *L, int nargs, int nresults);
-\end{verbatim}
-\DefAPI{lua_call}
-\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.
-Lua takes care that the returned values fit into the stack space.
-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 this Lua code:
-\begin{verbatim}
- a = f("how", t.x, 14)
-\end{verbatim}
-Here it is in\Nb{}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 \Q{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 auxiliary functions that
-provide higher level access to Lua.)
-
-
-\subsection{Protected Calls}\label{pcall}
-
-When you call a function with \verb|lua_call|,
-any error inside the called function is propagated upwards
-(with a \verb|longjmp|).
-If you need to handle errors,
-then you should use \verb|lua_pcall|:
-\begin{verbatim}
- int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
-\end{verbatim}
-Both \verb|nargs| and \verb|nresults| have the same meaning as
-in \verb|lua_call|.
-If there are no errors during the call,
-\verb|lua_pcall| behaves exactly like \verb|lua_call|.
-Like \verb|lua_call|,
-\verb|lua_pcall| always removes the function
-and its arguments from the stack.
-However, if there is any error,
-\verb|lua_pcall| catches it,
-pushes a single value at the stack (the error message),
-and returns an error code.
-
-If \verb|errfunc| is 0,
-then the error message returned is exactly the original error message.
-Otherwise, \verb|errfunc| gives the stack index for an
-\emph{error handler function}.
-(In the current implementation, that index cannot be a pseudo-index.)
-In case of runtime errors,
-that function will be called with the error message,
-and its return value will be the message returned by \verb|lua_pcall|.
-
-Typically, the error handler function is used to add more debug
-information to the error message, such as a stack traceback.
-Such information cannot be gathered after the return of \verb|lua_pcall|,
-since by then the stack has unwound.
-
-The \verb|lua_pcall| function returns 0 in case of success,
-or one of the following error codes
-(defined in \verb|lua.h|):
-\begin{itemize}
-\item \IndexAPI{LUA_ERRRUN} \Em{} a runtime error.
-\item \IndexAPI{LUA_ERRMEM} \Em{} memory allocation error.
-For such errors, Lua does not call the error handler function.
-\item \IndexAPI{LUA_ERRERR} \Em{}
-error while running the error handler function.
-\end{itemize}
-
-
-\medskip
-
->>>>
-\C{ TODO: mover essas 2 para algum lugar melhor.}
-Some special Lua functions have their own C\Nb{}interfaces.
-The host program can generate a Lua error calling the function
-\begin{verbatim}
- void lua_error (lua_State *L);
-\end{verbatim}
-\DefAPI{lua_error}
-The error message (which actually can be any type of object)
-is popped from the stack.
-This function never returns.
-If \verb|lua_error| is called from a C\Nb{}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)|.
-\C{ TODO: at_panic}
-
-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\Nb{}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\Nb{}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\Nb{}function must follow the following protocol,
-which defines the way parameters and results are passed:
-A C\Nb{}function receives its arguments from Lua in its stack,
-in direct order (the first argument is pushed first).
-So, when the function starts,
-its first argument (if any) is at index 1.
-To return values to Lua, a C\Nb{}function just pushes them onto the stack,
-in direct order (the first result is pushed first),
-and returns the number of results.
-Any other value in the stack below the results will be properly
-discharged by Lua.
-Like a Lua function, a C\Nb{}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_pushstring(L, "incorrect argument to function `average'");
- lua_error(L);
- }
- 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\Nb{}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\Nb{}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\Nb{}function is created,
-it is possible to associate some values with it,
-thus creating a \IndexEmph{C\Nb{}closure};
-these values are then accessible to the function whenever it is called.
-To associate values with a C\Nb{}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\Nb{}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\Nb{}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\Nb{}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\Nb{}code to
-store whatever Lua value it needs to store,
-especially if the C\Nb{}code needs to keep that Lua value
-outside the life span of a C\Nb{}function.
-This table is always located at pseudo-index
-\IndexAPI{LUA_REGISTRYINDEX}.
-Any C\Nb{}library can store data into this table,
-as long as it chooses keys different from other libraries.
-Typically, you should use as key a string containing your library name,
-or a light userdata with the address of a C object in your code.
-
-The integer keys in the registry are used by the reference mechanism,
-implemented by the auxiliary library,
-and therefore should not be used by other purposes.
-
-
-\C{-------------------------------------------------------------------------}
-\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}.
-This interface allows the construction of different
-kinds of debuggers, profilers, and other tools
-that need \Q{inside information} from the interpreter.
-
-\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\Nb{}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 {
- int event;
- const char *name; /* (n) */
- const char *namewhat; /* (n) `global', `local', `field', `method' */
- const char *what; /* (S) `Lua' function, `C' function, Lua `main' */
- const char *source; /* (S) */
- int currentline; /* (l) */
- int nups; /* (u) number of upvalues */
- int linedefined; /* (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 \At{} followed by the file name.
-
-\item[short_src]
-A \Q{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\Nb{}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 how the function was
-called or whether it is the value of a global variable to
-find a suitable name.
-If it cannot find a name,
-then \verb|name| is set to \verb|NULL|.
-
-\item[namewhat]
-Explains the previous field.
-It can be \verb|"global"|, \verb|"local"|, \verb|"method"|,
-\verb|"field"|, or \verb|""| (the empty string),
-according to how the function was called.
-(Lua uses the empty string when no other option seems to apply.)
-
-\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\Nb{}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 that was
-filled by a previous call to \verb|lua_getstack| or
-was given as argument to a hook \see{sub-hooks}.
-\verb|lua_getlocal| gets the index \verb|n| of a local variable,
-pushes the variable's value onto the stack,
-and returns its 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|
-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 a mechanism of hooks, which are
-user-defined C functions that are called during the program execution.
-A hook may be called in four different events:
-a \emph{call} event, when Lua calls a function;
-a \emph{return} event, when Lua returns from a function;
-a \emph{line} event, when Lua starts executing a new line of code;
-and a \emph{count} event, which happens every \Q{count} instructions.
-Lua identifies them with the following constants:
-\verb|LUA_HOOKCALL|\DefAPI{LUA_HOOKCALL},
-\verb|LUA_HOOKRET|\DefAPI{LUA_HOOKRET},
-\verb|LUA_HOOKLINE|\DefAPI{LUA_HOOKLINE},
-and \verb|LUA_HOOKCOUNT|\DefAPI{LUA_HOOKCOUNT}.
-
-A hook has 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 hook with the following function:
-\begin{verbatim}
- int lua_sethook (lua_State *L, lua_Hook func, unsigned long mask);
-\end{verbatim}
-\DefAPI{lua_sethook}
-\verb|func| is the hook,
-and \verb|mask| specifies at which events it will be called.
-It is formed by a disjunction of the constants
-\verb|LUA_MASKCALL|,
-\verb|LUA_MASKRET|,
-\verb|LUA_MASKLINE|,
-plus the macro \verb|LUA_MASKCOUNT(count)|.
-For each event, the hook is called as explained below:
-\begin{description}
-\item{The call hook} is called when the interpreter calls a function.
-The hook is called just after Lua \Q{enters} the new function.
-\item{The return hook} is called when the interpreter returns from a function.
-The hook is called just before Lua \Q{leaves} the function.
-\item{The line hook} is called when the interpreter is about to
-start the execution of a new line of code,
-or when it jumps back (even for the same line).
-(For obvious reasons, this event does not happen while Lua is executing
-a C function.)
-\item{The count hook} is called after the interpreter executes every
-\verb|count| instructions.
-(For obvious reasons, this event does not happen while Lua is executing
-a C function.)
-\end{description}
-
-A hook is disabled with the mask zero.
-
-You can get the current hook and the current mask with the next functions:
-\begin{verbatim}
- lua_Hook lua_gethook (lua_State *L);
- unsigned long lua_gethookmask (lua_State *L);
-\end{verbatim}
-\DefAPI{lua_gethook}\DefAPI{lua_gethookmask}
-You can get the count inside a mask with the macro \verb|lua_getmaskcount|.
-
-Whenever a hook is called, its \verb|ar| argument has its field
-\verb|event| set to the specific event that triggered the hook.
-Moreover, for line events, the field \verb|currentline| is also set.
-For the value of any other field, the hook must call \verb|lua_getinfo|.
-
-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,
-that execution occurs without any calls to hooks.
-
-
-\C{-------------------------------------------------------------------------}
-\section{Standard Libraries}\label{libraries}
-
-The standard libraries provide useful functions
-that are implemented directly through the standard C\Nb{}API.
-Some of these functions provide essential services to the language
-(e.g. \verb|type| and \verb|getmetatable|);
-others provide access to \Q{outside} services (e.g. I/O);
-and others could be implemented in Lua itself,
-but are quite useful or have critical performance to
-deserve an implementation in C (e.g. \verb|sort|).
-
-All libraries are implemented through the official C API,
-and are provided as separate C\Nb{}modules.
-Currently, Lua has the following standard libraries:
-\begin{itemize}
-\item basic library;
-\item string manipulation;
-\item table manipulation;
-\item mathematical functions (sin, log, etc.);
-\item input and output;
-\item operating system facilities;
-\item debug facilities.
-\end{itemize}
-Except for the basic library,
-each library provides all its functions as fields of a global table
-or as methods of its objects.
-
-To have access to these libraries,
-the C\Nb{}host program must call the functions
-\verb|lua_baselibopen| (for the basic library),
-\verb|lua_strlibopen| (for the string library),
-\verb|lua_tablibopen| (for the table library),
-\verb|lua_mathlibopen| (for the mathematical library),
-\verb|lua_iolibopen| (for the I/O and the Operating System libraries),
-and \verb|lua_dblibopen| (for the debug library),
-which are declared in \verb|lualib.h|.
-\DefAPI{lua_baselibopen}
-\DefAPI{lua_strlibopen}
-\DefAPI{lua_tablibopen}
-\DefAPI{lua_mathlibopen}
-\DefAPI{lua_iolibopen}
-\DefAPI{lua_dblibopen}
-
-
-\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.
-
-The basic library also defines a global variable \IndexLIB{_VERSION}
-with a string containing the current interpreter version.
-The current content of this string is {\tt "Lua \Version"}.
-
-\subsubsection*{\ff \T{assert (v [, message])}}\DefLIB{assert}
-Issues an \emph{\Q{assertion failed!}} error
-when its argument \verb|v| is \nil{} or \False{};
-otherwise, returns this argument.
-This function is equivalent to the following Lua function:
-\begin{verbatim}
- function assert (v, m)
- if not v then
- error(m or "assertion failed!")
- end
- return v
- end
-\end{verbatim}
-
-\subsubsection*{\ff \T{collectgarbage ([limit])}}\DefLIB{collectgarbage}
-
-Sets the garbage-collection threshold to 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|).
-Returns any value returned by the chunk.
-
-\subsubsection*{\ff \T{error (message [, level])}}
-\DefLIB{error}\label{pdf-error}
-Terminates the last protected function called,
-and returns \verb|message| as the error message.
-Function \verb|error| never returns.
-
-The \verb|level| argument specifies where the error
-message points the error.
-With level 1 (the default), the error position is where the
-\verb|error| function was called.
-Level 2 points the error to where the function
-that called \verb|error| was called; and so on.
-
-\subsubsection*{\ff \T{getglobals (function)}}\DefLIB{getglobals}
-Returns the current table of globals in use by the function.
-\verb|function| can be a Lua function or a number,
-which specifies the function at that stack level:
-Level 1 is the function calling \verb|getglobals|.
-If the given function is not a Lua function,
-returns the \Q{global} table of globals.
-The default for \verb|function| is 1.
-
-\subsubsection*{\ff \T{getmetatable (object)}}
-\DefLIB{getmetatable}\label{pdf-getmetatable}
-
-Returns the metatable of the given object.
-If the object does not have a metatable, returns \nil{}.
-
-\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{ipairs (t)}}\DefLIB{ipairs}
-
-Returns a generator function and the table \verb|t|,
-so that the construction
-\begin{verbatim}
- for i,v in ipairs(t) do ... end
-\end{verbatim}
-will iterate over the pairs \verb|1, t[1]|, \verb|2, t[2]|, \ldots,
-up to the first nil value of the table.
-
-\subsubsection*{\ff \T{loadfile (filename)}}\DefLIB{loadfile}
-Loads a file as a Lua chunk.
-If there are no errors,
-returns the compiled chunk as a function;
-otherwise, returns \nil{} plus an error message.
-
-\subsubsection*{\ff \T{loadstring (string [, chunkname])}}\DefLIB{loadstring}
-Loads a string as a Lua chunk.
-If there are no errors,
-returns the compiled chunk as a function;
-otherwise, returns \nil{} plus an error message.
-
-The optional parameter \verb|chunkname|
-is the \Q{name of the chunk},
-which is used in error messages and debug information.
-
-To load and run a given string, use the idiom
-\begin{verbatim}
- assert(loadstring(s))()
-\end{verbatim}
-
-\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|ipairs|.)
-
-The behavior of \verb|next| is \emph{undefined} if you modify
-the table during the traversal.
-
-\subsubsection*{\ff \T{pairs (t)}}\DefLIB{pairs}
-
-Returns the function \verb|next| and the table \verb|t| (plus a \nil{}),
-so that the construction
-\begin{verbatim}
- for k,v in pairs(t) do ... end
-\end{verbatim}
-will iterate over all pairs of key\En{}value of table \verb|t|.
-
-\subsubsection*{\ff \T{pcall (func, arg1, arg2, ...)}}\DefLIB{pcall}
-\label{pdf-pcall}
-Calls function \verb|func| with
-the given arguments in protected mode.
-That means that any error inside \verb|func| is not propagated;
-instead, \verb|pcall| catches the error
-and returns a status code.
-Its first result is the status code (a boolean),
-which is true if the call succeeds without errors.
-In such case, \verb|pcall| also returns all results from the call,
-after this first result.
-In case of any error, \verb|pcall| returns false plus the error message.
-
-\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 metamethod.
-\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 metamethod.
-\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 (packagename)}}\DefLIB{require}
-
-Loads the given package.
-The function starts by looking into the table \IndexVerb{_LOADED}
-to determine whether \verb|packagename| is already loaded.
-If it is, then \verb|require| is done.
-Otherwise, it searches a path looking for a file to load.
-
-If the global variable \IndexVerb{LUA_PATH} is a string,
-this string is the path.
-Otherwise, \verb|require| tries the environment variable \verb|LUA_PATH|.
-As a last resort, it uses a predefined path.
-
-The path is a sequence of \emph{templates} separated by semicolons.
-For each template, \verb|require| will change an eventual interrogation
-mark in the template to \verb|packagename|,
-and then will try to load the resulting file name.
-So, for instance, if the path is
-\begin{verbatim}
- "./?.lua;./?.lc;/usr/local/?/init.lua;/lasttry"
-\end{verbatim}
-a \verb|require "mod"| will try to load the files
-\verb|./mod.lua|,
-\verb|./mod.lc|,
-\verb|/usr/local/mod/init.lua|,
-and \verb|/lasttry|, in that order.
-
-The function stops the search as soon as it can load a file,
-and then it runs the file.
-If there is any error loading or running the file,
-or if it cannot find any file in the path,
-then \verb|require| signals an error.
-Otherwise, it marks in table \verb|_LOADED|
-that the package is loaded, and returns.
-
-While running a packaged file,
-\verb|require| defines the global variable \IndexVerb{_REQUIREDNAME}
-with the package name.
-
-\subsubsection*{\ff \T{setglobals (function, table)}}\DefLIB{setglobals}
-Sets the current table of globals to be used by the given function.
-\verb|function| can be a Lua function or a number,
-which specifies the function at that stack level:
-Level 1 is the function calling \verb|setglobals|.
-
-\subsubsection*{\ff \T{setmetatable (table, metatable)}}\DefLIB{setmetatable}
-
-Sets the metatable for the given table.
-(You cannot change the metatable of a userdata from Lua.)
-If \verb|metatable| is \nil{}, removes the metatable of the given table.
-
-\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\Nb{}10, the letter `A' (in either upper or lower case)
-represents\Nb{}10, `B' represents\Nb{}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{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 either the value of \verb|list.n|, if it is a number,
-or one less the index of the first absent (\nil{}) value.
-
-\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\Nb{}1
-(not at\Nb{}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.
-
-The string library provides all its functions inside the table
-\IndexLIB{string}.
-
-\subsubsection*{\ff \T{string.byte (s [, i])}}\DefLIB{string.byte}
-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\Nb{}1.
-\verb|i| may be negative.
-
-\NOTE
-Numerical codes are not necessarily portable across platforms.
-
-\subsubsection*{\ff \T{string.char (i1, i2, \ldots)}}\DefLIB{string.char}
-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{string.find (s, pattern [, init [, plain]])}}
-\DefLIB{string.find}
-Looks for the first \emph{match} of
-\verb|pattern| in the string \verb|s|.
-If it finds one, then \verb|find| returns the indices of \verb|s|
-where this occurrence starts and ends;
-otherwise, it returns \nil{}.
-If the pattern specifies captures (see \verb|string.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\Nb{}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 \Q{find substring} operation,
-with no characters in \verb|pattern| being considered \Q{magic}.
-Note that if \verb|plain| is given, then \verb|init| must be given too.
-
-\subsubsection*{\ff \T{string.len (s)}}\DefLIB{string.len}
-Receives a string and returns its length.
-The empty string \verb|""| has length 0.
-Embedded zeros are counted,
-so \verb|"a\000b\000c"| has length 5.
-
-\subsubsection*{\ff \T{string.lower (s)}}\DefLIB{string.lower}
-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 is an uppercase letter depends on the current locale.
-
-\subsubsection*{\ff \T{string.rep (s, n)}}\DefLIB{string.rep}
-Returns a string that is the concatenation of \verb|n| copies of
-the string \verb|s|.
-
-\subsubsection*{\ff \T{string.sub (s, i [, j])}}\DefLIB{string.sub}
-Returns another string, which is the substring of \verb|s| that
-starts at \verb|i| and continues 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|string.sub(s,1,j)| returns a prefix of \verb|s|
-with length \verb|j|,
-and the call \verb|string.sub(s, -i)| returns a suffix of \verb|s|
-with length \verb|i|.
-
-\subsubsection*{\ff \T{string.upper (s)}}\DefLIB{string.upper}
-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 is a lowercase letter depends on the current locale.
-
-\subsubsection*{\ff \T{string.format (formatstring, e1, e2, \ldots)}}
-\DefLIB{string.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\Nb{}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}
- string.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{string.gfind (s, pat)}}
-
-Returns a generator function that,
-each time it is called,
-returns the next captures from pattern \verb|pat| over string \verb|s|.
-
-If \verb|pat| specifies no captures,
-then the whole match is produced in each call.
-
-As an example, the following loop
-\begin{verbatim}
- s = "hello world from Lua"
- for w in string.gfind(s, "%a+") do
- print(w)
- end
-\end{verbatim}
-will iterate over all the words from string \verb|s|,
-printing one per line.
-The next example collects all pairs \verb|key=value| from the
-given string into a table:
-\begin{verbatim}
- t = {}
- s = "from=world, to=Lua"
- for k, v in string.gfind(s, "(%w+)=(%w+)") do
- t[k] = v
- end
-\end{verbatim}
-
-\subsubsection*{\ff \T{string.gsub (s, pat, repl [, n])}}
-\DefLIB{string.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 pattern specifies no captures,
-then the whole match is passed as a sole argument.
-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 = string.gsub("hello world", "(%w+)", "%1 %1")
- --> x="hello hello world world"
-
- x = string.gsub("hello world", "(%w+)", "%1 %1", 1)
- --> x="hello hello world"
-
- x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
- --> x="world hello Lua from"
-
- x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
- --> x="home = /home/roberto, user = roberto" (for instance)
-
- x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
- return loadstring(s)()
- end)
- --> x="4+5 = 9"
-
- local t = {name="Lua", version="5.0"}
- x = string.gsub("$name - $version", "%$(%w+)", function (v)
- return t[v]
- end)
- --> x="Lua - 5.0"
-\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|^$()%.[]*+-?|)
-\Em{} represents the character \emph{x} itself.
-\item[\T{.}] \Em{} (a dot) represents all characters.
-\item[\T{%a}] \Em{} represents all letters.
-\item[\T{%c}] \Em{} represents all control characters.
-\item[\T{%d}] \Em{} represents all digits.
-\item[\T{%l}] \Em{} represents all lowercase letters.
-\item[\T{%p}] \Em{} represents all punctuation characters.
-\item[\T{%s}] \Em{} represents all space characters.
-\item[\T{%u}] \Em{} represents all uppercase letters.
-\item[\T{%w}] \Em{} represents all alphanumeric characters.
-\item[\T{%x}] \Em{} represents all hexadecimal digits.
-\item[\T{%z}] \Em{} represents the character with representation 0.
-\item[\T{%\M{x}}] (where \M{x} is any non-alphanumeric character) \Em{}
-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}]}] \Em{}
-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{[^\M{set}]}] \Em{}
-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 substring 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\Nb{}\M{x}, end with\Nb{}\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 substrings 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\Nb{}1);
-the character matching \verb|.| is captured with number\Nb{}2,
-and the part matching \verb|%s*| has number\Nb{}3.
-
-As a special case, the empty capture \verb|()| captures
-the current string position (a number).
-For instance, if we apply the pattern \verb|"()aa()"| on the
-string \verb|"flaaap"|, there will be two captures: 3 and 5.
-
-\NOTE
-A pattern cannot contain embedded zeros. Use \verb|%z| instead.
-
-
-\subsection{Table Manipulation}
-This library provides generic functions for table manipulation.
-It provides all its functions inside the table \IndexLIB{table}.
-
-Most functions in the table library assume that the table
-represents an array or a list.
-For those functions, an important concept is the \emph{size} of the array.
-There are three ways to specify that size:
-\begin{itemize}
-\item the field \verb|"n"| \Em{}
-When the table has a field \verb|"n"| with a numerical value,
-that value is assumed as its size.
-\item \verb|setn| \Em{}
-You can call the \verb|table.setn| function to explicitly set
-the size of a table.
-\item implicit size \Em{}
-Otherwise, the size of the object is one less the first integer index
-with a \nil{} value.
-\end{itemize}
-For more details, see the descriptions of the \verb|table.getn| and
-\verb|table.setn| functions.
-
-\subsubsection*{\ff \T{table.concat (table [, sep [, i [, j]]])}}
-\DefLIB{table.concat}
-Returns \verb|table[i]..sep..table[i+1] ... sep..table[j]|.
-The default value for \verb|sep| is the empty string,
-the default for \verb|i| is 1,
-and the default for \verb|j| is the size of the table.
-If \verb|i| is greater than \verb|j|, returns the empty string.
-
-\subsubsection*{\ff \T{table.foreach (table, func)}}\DefLIB{table.foreach}
-Executes the given \verb|func| over all elements of \verb|table|.
-For each element, \verb|func| is called with the index and
-respective value as arguments.
-If \verb|func| returns a non-\nil{} value,
-then the loop is broken, and this value is returned
-as the final value of \verb|foreach|.
-
-The behavior of \verb|foreach| is \emph{undefined} if you change
-the table \verb|t| during the traversal.
-
-
-\subsubsection*{\ff \T{table.foreachi (table, func)}}\DefLIB{table.foreachi}
-Executes the given \verb|func| over the
-numerical indices of \verb|table|.
-For each index, \verb|func| is called with the index and
-respective value as arguments.
-Indices are visited in sequential order,
-from\Nb{}1 to \verb|n|,
-where \verb|n| is the size of the table \see{getn}.
-If \verb|func| returns a non-\nil{} value,
-then the loop is broken, and this value is returned
-as the final value of \verb|foreachi|.
-
-\subsubsection*{\ff \T{table.getn (table)}}\DefLIB{table.getn}\label{getn}
-Returns the \Q{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 \Q{size} of the table.
-Otherwise, if there was a previous call to
-\verb|table.getn| or to \verb|table.setn| over this table,
-the respective value is returned.
-Otherwise, the \Q{size} is one less the first integer index with
-a \nil{} value.
-
-Notice that the last option happens only once for a table.
-If you call \verb|table.getn| again over the same table,
-it will return the same previous result,
-even if the table has been modified.
-The only way to change the value of \verb|table.getn| is by calling
-\verb|table.setn| or assigning to field \verb|"n"| in the table.
-
-\subsubsection*{\ff \T{table.sort (table [, comp])}}\DefLIB{table.sort}
-Sorts table elements in a given order, \emph{in-place},
-from \verb|table[1]| to \verb|table[n]|,
-where \verb|n| is the size of the 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{table.insert (table, [pos,] value)}}\DefLIB{table.insert}
-
-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 size of the table \see{getn},
-so that a call \verb|table.insert(t,x)| inserts \verb|x| at the end
-of table \verb|t|.
-This function also updates the size of the table by
-calling \verb|table.setn(table, n+1)|.
-
-\subsubsection*{\ff \T{table.remove (table [, pos])}}\DefLIB{table.remove}
-
-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 size of the table \see{getn},
-so that a call \verb|tremove(t)| removes the last element
-of table \verb|t|.
-This function also updates the size of the table by
-calling \verb|table.setn(table, n-1)|.
-
-\subsubsection*{\ff \T{table.setn (table, n)}}\DefLIB{table.setn}
-
-Updates the \Q{size} of a table.
-If the table has a field \verb|"n"| with a numerical value,
-that value is changed to the given \verb|n|.
-Otherwise, it updates an internal state of the \verb|table| library
-so that subsequent calls to \verb|table.getn(table)| return \verb|n|.
-
-
-\subsection{Mathematical Functions} \label{mathlib}
-
-This library is an interface to most of the functions of the
-standard C\Nb{}math library.
-(Some have slightly different names.)
-It provides all its functions inside the table \IndexLIB{math}.
-In addition,
-it registers a ??tag method for the binary exponentiation operator \verb|^|
-that returns \Math{x\sp{y}} when applied to numbers \verb|x| and \verb|y|.
-
-The library provides the following functions:
-\DefLIB{math.abs}\DefLIB{math.acos}\DefLIB{math.asin}\DefLIB{math.atan}
-\DefLIB{math.atan2}\DefLIB{math.ceil}\DefLIB{math.cos}
-\DefLIB{math.def}\DefLIB{math.exp}
-\DefLIB{math.floor}\DefLIB{math.log}\DefLIB{math.log10}
-\DefLIB{math.max}\DefLIB{math.min}
-\DefLIB{math.mod}\DefLIB{math.rad}\DefLIB{math.sin}
-\DefLIB{math.sqrt}\DefLIB{math.tan}
-\DefLIB{math.frexp}\DefLIB{math.ldexp}\DefLIB{math.random}
-\DefLIB{math.randomseed}
-\begin{verbatim}
- math.abs math.acos math.asin math.atan math.atan2
- math.ceil math.cos math.deg math.exp math.floor
- math.log math.log10 math.max math.min math.mod
- math.rad math.sin math.sqrt math.tan math.frexp
- math.ldexp math.random math.randomseed
-\end{verbatim}
-plus a variable \IndexLIB{math.pi}.
-Most of them
-are only interfaces to the corresponding functions in the C\Nb{}library.
-All trigonometric functions work in radians.
-The functions \verb|math.deg| and \verb|math.rad| convert
-between radians and degrees.
-
-The function \verb|math.max| returns the maximum
-value of its numeric arguments.
-Similarly, \verb|math.min| computes the minimum.
-Both can be used with 1, 2, or more arguments.
-
-The functions \verb|math.random| and \verb|math.randomseed|
-are interfaces to the simple random generator functions
-\verb|rand| and \verb|srand| that are provided by ANSI\Nb{}C.
-(No guarantees can be given for their statistical properties.)
-When called without arguments,
-\verb|math.random| returns a pseudo-random real number
-in the range \Math{[0,1)}. \C{]}
-When called with a number \Math{n},
-\verb|math.random| returns a pseudo-random integer in the range \Math{[1,n]}.
-When called with two arguments, \Math{l} and \Math{u},
-\verb|math.random| returns a pseudo-random integer in the range \Math{[l,u]}.
-The \verb|math.randomseed| function sets a \Q{seed}
-for the pseudo-random generator:
-Equal seeds produce equal sequences of numbers.
-
-
-\subsection{Input and Output Facilities} \label{libio}
-
-The I/O library provides two different styles for file manipulation.
-The first one uses implicit file descriptors;
-that is, there are operations to set a default input file and a
-default output file,
-and all input/output operations are over those default files.
-The second style uses explicit file descriptors.
-
-When using implicit file descriptors,
-all operations are supplied by table \IndexLIB{io}.
-When using explicit file descriptors,
-the operation \IndexLIB{io.open} returns a file descriptor,
-and then all operations are supplied as methods by the file descriptor.
-
-The table \verb|io| also provides
-three predefined file descriptors with their usual meanings from C:
-\IndexLIB{io.stdin}, \IndexLIB{io.stdout}, and \IndexLIB{io.stderr}.
-
-A file handle is a userdata containing the file stream (\verb|FILE*|),
-with a distinctive metatable created by the I/O library.
-
-Unless otherwise stated,
-all I/O functions return \nil{} on failure
-(plus an error message as a second result)
-and some value different from \nil{} on success.
-
-\subsubsection*{\ff \T{io.close ([file])}}\DefLIB{io.close}
-
-Equivalent to \verb|file:close()|.
-Without a \verb|file|, closes the default output file.
-
-\subsubsection*{\ff \T{io.flush ()}}\DefLIB{io.flush}
-
-Equivalent to \verb|file:flush| over the default output file.
-
-\subsubsection*{\ff \T{io.input ([file])}}\DefLIB{io.input}
-
-When called with a file name, it opens the named file (in text mode),
-and sets its handle as the default input file
-(and returns nothing).
-When called with a file handle,
-it simply sets that file handle as the default input file.
-When called without parameters,
-it returns the current default input file.
-
-In case of errors this function raises the error,
-instead of returning an error code.
-
-\subsubsection*{\ff \T{io.lines ([filename])}}\DefLIB{io.lines}
-
-Opens the given file name in read mode,
-and returns a generator function that,
-each time it is called,
-returns a new line from the file.
-Therefore, the construction
-\begin{verbatim}
- for line in io.lines(filename) do ... end
-\end{verbatim}
-will iterate over all lines of the file.
-When the generator function detects the end of file,
-it returns nil (to finish the loop) and automatically closes the file.
-
-The call \verb|io.lines()| (without a file name) is equivalent
-to \verb|io.input():lines()|, that is, it iterates over the
-lines of the default input file.
-
-\subsubsection*{\ff \T{io.open (filename [, mode])}}\DefLIB{io.open}
-
-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 an error message.
-
-The \verb|mode| string can be any of the following:
-\begin{description}\leftskip=20pt
-\item[\Q{r}] read mode (the default);
-\item[\Q{w}] write mode;
-\item[\Q{a}] append mode;
-\item[\Q{r+}] update mode, all previous data is preserved;
-\item[\Q{w+}] update mode, all previous data is erased;
-\item[\Q{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\Nb{}C function \verb|fopen|.
-
-\subsubsection*{\ff \T{io.output ([file])}}\DefLIB{io.output}
-
-Similar to \verb|io.input|, but operates over the default output file.
-
-\subsubsection*{\ff \T{io.read (format1, ...)}}\DefLIB{io.read}
-
-Equivalent to \verb|file:read| over the default input file.
-
-\subsubsection*{\ff \T{io.tmpfile ()}}\DefLIB{io.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{io.write (value1, ...)}}\DefLIB{io.write}
-
-Equivalent to \verb|file:write| over the default output file.
-
-
-
-\subsubsection*{\ff \T{file:close ()}}\DefLIB{file:close}
-
-Closes the file \verb|file|.
-
-\subsubsection*{\ff \T{file:flush ()}}\DefLIB{file:flush}
-
-Saves any written data to the file \verb|file|.
-
-\subsubsection*{\ff \T{file:lines ()}}\DefLIB{file:lines}
-
-Returns a generator function that,
-each time it is called,
-returns a new line from the file.
-Therefore, the construction
-\begin{verbatim}
- for line in file:lines() do ... end
-\end{verbatim}
-will iterate over all lines of the file.
-(Unlike \verb|io.lines|, this function does not close the file
-when the loop ends.)
-
-\subsubsection*{\ff \T{file:read (format1, ...)}}\DefLIB{file:read}
-
-Reads the file \verb|file|,
-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[\Q{*n}] reads a number;
-this is the only format that returns a number instead of a string.
-\item[\Q{*a}] reads the whole file, starting at the current position.
-On end of file, it returns the empty string.
-\item[\Q{*l}] 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{file:seek ([whence] [, offset])}}\DefLIB{file: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[\Q{set}] base is position 0 (beginning of the file);
-\item[\Q{cur}] base is current position;
-\item[\Q{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|file:seek()| returns the current
-file position, without changing it;
-the call \verb|file:seek("set")| sets the position to the
-beginning of the file (and returns 0);
-and the call \verb|file:seek("end")| sets the position to the
-end of the file, and returns its size.
-
-\subsubsection*{\ff \T{file:write (value1, ...)}}\DefLIB{file:write}
-
-Writes the value of each of its arguments to
-the filehandle \verb|file|.
-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{Operating System Facilities} \label{libiosys}
-
-This library is implemented through table \IndexLIB{os}.
-
-\subsubsection*{\ff \T{os.clock ()}}\DefLIB{os.clock}
-
-Returns an approximation of the amount of CPU time
-used by the program, in seconds.
-
-\subsubsection*{\ff \T{os.date ([format [, time]])}}\DefLIB{os.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| (four digits), \verb|month| (1--12), \verb|day| (1--31),
-\verb|hour| (0--23), \verb|min| (0--59), \verb|sec| (0--61),
-\verb|wday| (weekday, Sunday is 1),
-\verb|yday| (day of the year),
-and \verb|isdst| (daylight saving flag, a boolean).
-
-If format is not \verb|*t|,
-then \verb|date| returns the date as a string,
-formatted according with the same rules as the C\Nb{}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
-(that is, \verb|os.date()| is equivalent to \verb|os.date("%c")|).
-
-\subsubsection*{\ff \T{os.difftime (t2, t1)}}\DefLIB{os.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|t2|\Math{-}\verb|t1|.
-
-\subsubsection*{\ff \T{os.execute (command)}}\DefLIB{os.execute}
-
-This function is equivalent to the C\Nb{}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{os.exit ([code])}}\DefLIB{os.exit}
-
-Calls the C\Nb{}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{os.getenv (varname)}}\DefLIB{os.getenv}
-
-Returns the value of the process environment variable \verb|varname|,
-or \nil{} if the variable is not defined.
-
-\subsubsection*{\ff \T{os.remove (filename)}}\DefLIB{os.remove}
-
-Deletes the file with the given name.
-If this function fails, it returns \nil{},
-plus a string describing the error.
-
-\subsubsection*{\ff \T{os.rename (name1, name2)}}\DefLIB{os.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{os.setlocale (locale [, category])}}\DefLIB{os.setlocale}
-
-This function is an interface to the C\Nb{}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{os.time ([table])}}\DefLIB{os.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|os.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 \Q{epoch}).
-In other systems, the meaning is not specified,
-and the number returned by \verb|time| can be used only as an argument to
-\verb|date| and \verb|difftime|.
-
-\subsubsection*{\ff \T{os.tmpname ()}}\DefLIB{os.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\Nb{}function,
-and many people (and even some compilers!) advise against its use,
-because between the time you call this function
-and the time you open the file,
-it is possible for another process
-to create a file with the same name.
-
-
-\subsection{The Reflexive Debug Interface}
-
-The library \verb|ldblib| provides
-the functionality of the debug interface to Lua programs.
-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 very slow.
-Moreover, \verb|setlocal| and \verb|getlocal|
-violate the privacy of local variables,
-and therefore can compromise some (otherwise) secure code.
-
-All functions in this library are provided
-inside a \IndexVerb{debug} table.
-
-
-\subsubsection*{\ff \T{debug.getinfo (function, [what])}}\DefLIB{debug.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 which fields to fill in.
-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|debug.getinfo(1,"n").name| returns
-the name of the current function, if a reasonable name can be found,
-and \verb|debug.getinfo(print)| returns a table with all available information
-about the \verb|print| function.
-
-
-\subsubsection*{\ff \T{debug.getlocal (level, local)}}\DefLIB{debug.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\Nb{}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{debug.setlocal (level, local, value)}}
-\DefLIB{debug.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{debug.sethook (hook, mask [, count])}}
-\DefLIB{debug.sethook}
-
-Sets the given function as a hook.
-The string \verb|mask| and the number \verb|count| describe
-when the hook will be called.
-The string mask may have the following characters,
-with the given meaning:
-\begin{description}
-\item[{\tt "c"}] The hook is called every time Lua calls a function;
-\item[{\tt "r"}] The hook is called every time Lua returns from a function;
-\item[{\tt "l"}] The hook is called every time Lua enters a new line of code.
-\end{description}
-With a \verb|count| different from zero,
-the hook is called after every \verb|count| instructions.
-
-When called without arguments,
-the \verb|debug.sethook| function turns off the hook.
-
-When the hook is called, its first parameter is always a string
-describing the event that triggered its call:
-\verb|"call"|, \verb|"return"|, \verb|"line"|, and \verb|"count"|.
-Moreover, for line events,
-it also gets as its second parameter the new line number.
-Inside a hook,
-you can call \verb|getinfo| with level 2 to get more information about
-the running function
-(level\Nb{}0 is the \verb|getinfo| function,
-and level\Nb{}1 is the hook function).
-
-\subsubsection*{\ff \T{debug.gethook ()}}\DefLIB{debug.gethook}
-
-Returns the current hook settings, as three values:
-the current hook function, the current hook mask,
-and the current hook count (as set by the \verb|debug.sethook| function).
-
-
-\C{-------------------------------------------------------------------------}
-\section{\Index{Lua Stand-alone}} \label{lua-sa}
-
-Although Lua has been designed as an extension language,
-to be embedded in a host C\Nb{}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.
-The stand-alone interpreter includes
-all standard libraries plus the reflexive debug interface.
-Its usage is:
-\begin{verbatim}
- lua [options] [script [args]]
-\end{verbatim}
-The options are:
-\begin{description}\leftskip=20pt
-\item[\T{-} ] executes \verb|stdin| as a file;
-\item[\T{-e} \rm\emph{stat}] executes string \emph{stat};
-\item[\T{-l} \rm\emph{file}] \Q{requires} \emph{file};
-\item[\T{-i}] enters interactive mode after running \emph{script};
-\item[\T{-v}] prints version information;
-\item[\T{--}] stop handling options.
-\end{description}
-After handling its options, \verb|lua| runs the given \emph{script},
-passing to it the given \emph{args}.
-When called without arguments,
-\verb|lua| behaves as \verb|lua -v -i| when \verb|stdin| is a terminal,
-and as \verb|lua -| otherwise.
-
-Before running any argument,
-the interpreter checks for an environment variable \IndexVerb{LUA_INIT}.
-If its format is \At{}\emph{filename},
-then lua executes the file.
-Otherwise, lua executes the string itself.
-
-All options are handled in order, except \verb|-i|.
-For instance, an invocation like
-\begin{verbatim}
- $ lua -e'a=1' -e 'print(a)' script.lua
-\end{verbatim}
-will first set \verb|a| to 1, then print \verb|a|,
-and finally run the file \verb|script.lua|.
-(Here, \verb|$| is the shell prompt. Your prompt may be different.)
-
-Before starting to run the script,
-\verb|lua| collects all arguments in the command line
-in a global table called \verb|arg|.
-The script name is stored in index 0,
-the first argument after the script name goes to index 1,
-and so on.
-The field \verb|n| gets the number of arguments after the script name.
-Any arguments before the script name
-(that is, the interpreter name plus the options)
-go to negative indices.
-For instance, in the call
-\begin{verbatim}
- $ lua -la.lua b.lua t1 t2
-\end{verbatim}
-the interpreter first runs the file \T{a.lua},
-then creates a table
-\begin{verbatim}
- arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua",
- [1] = "t1", [2] = "t2"; n = 2 }
-\end{verbatim}
-and finally runs the file \T{b.lua}.
-
-In interactive mode,
-if you write an incomplete statement,
-the interpreter waits for its completion.
-
-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 -e"_PROMPT='myprompt> '" -i
-\end{verbatim}
-(the first pair of quotes is for the shell,
-the second is for Lua),
-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\Nb{}\verb|#!| form,
-as in
-\begin{verbatim}
-#!/usr/local/bin/lua
-\end{verbatim}
-(Of course,
-the location of the Lua interpreter may be different in your machine.
-If \verb|lua| is in your \verb|PATH|,
-then
-\begin{verbatim}
-#!/usr/bin/env lua
-\end{verbatim}
-is a more portable solution.)
-
-\C{-------------------------------------------------------------------------}
-\section*{Acknowledgments}
-
-The Lua team is grateful to \tecgraf{} for its continued support to Lua.
-We thank everyone at \tecgraf{},
-specially the head of the group, Marcelo Gattass.
-At the risk of omitting several names,
-we also thank the following individuals for supporting,
-contributing to, and spreading the word about Lua:
-Alan Watson.
-André Clinio,
-André Costa,
-Antonio Scuri,
-Bret Mogilefsky,
-Cameron Laird,
-Carlos Cassino,
-Carlos Henrique Levy,
-Claudio Terra,
-David Jeske,
-Edgar Toernig,
-Erik Hougaard,
-Jim Mathies,
-John Belmonte,
-John Passaniti,
-John Roll,
-Jon Erickson,
-Jon Kleiser,
-Mark Ian Barlow,
-Nick Trout,
-Noemi Rodriguez,
-Norman Ramsey,
-Philippe Lhoste,
-Renata Ratton,
-Renato Borges,
-Renato Cerqueira,
-Reuben Thomas,
-Stephan Herrmann,
-Steve Dekorte,
-Thatcher Ulrich,
-Tomás Gorham,
-Vincent Penquerc'h,
-Thank you!
-
-
-\appendix
-
-\section*{Incompatibilities with Previous Versions}
-\addcontentsline{toc}{section}{Incompatibilities with Previous Versions}
-
-\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
-The precedence of \rwd{or} is smaller than the precedence of \rwd{and}.
-
-\item
-\rwd{in} is a reserved word.
-
-\item
-The old construction \verb|for k,v in t|, where \verb|t| is a table,
-is deprecated (although it is still supported).
-Use \verb|for k,v in pairs(t)| instead.
-
-\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
-Most library functions now are defined inside tables.
-There is a compatibility script (\verb|compat.lua|) that
-redefine most of them as global names.
-
-\item
-In the math library, angles are expressed in radians.
-With the compatibility script (\verb|compat.lua|),
-functions still work in degrees.
-
-\item
-The \verb|call| function is deprecated.
-Use \verb|f(unpack(tab))| instead of \verb|call(f, tab)|
-for unprotected calls,
-or the new \verb|pcall| function for protected calls.
-
-\item
-\verb|dofile| do not handle errors, but simply propagates them.
-
-\item
-The \verb|read| option \verb|*w| is obsolete.
-
-\item
-The \verb|format| option \verb|%n$| is obsolete.
-
-\end{itemize}
-
-
-\subsubsection*{Changes in the API}
-\begin{itemize}
-
-\item
-Userdata!!
-
-\end{itemize}
-
-
-
-\C{[===============================================================}
-\newpage
-\section*{The Complete Syntax of Lua} \label{BNF}
-\addcontentsline{toc}{section}{The Complete Syntax of Lua}
-
-The notation used here is the usual extended BNF,
-in which
-\rep{\emph{a}}\Nb{}means 0 or more \emph{a}'s, and
-\opt{\emph{a}}\Nb{}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.
-
-
-\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} \rep{\ter{,} \Nter{Name}} \rwd{in} explist1
- \rwd{do} block \rwd{end}
-\OrNL \rwd{function} funcname funcbody
-\OrNL \rwd{local} \rwd{function} \Nter{Name} funcbody
-\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}
- \rwd{false}
- \rwd{true}
-\Or \Nter{Number}
-\OrNL \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} funcbody}
-
-\produc{funcbody}{\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{..} \OrNL \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}
-
-\C{]===============================================================}
-
-\C{ Index}
-
-\newpage
-\addcontentsline{toc}{section}{Index}
-\input{manual.id}
-
-\end{document}
-%)]}
-
