reference manual

1 files changed, 1741 insertions, 0 deletions

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