| % $Id: manual.tex,v 1.29 1997/03/06 21:13:34 roberto Exp $ |
| |
| \documentstyle[fullpage,11pt,bnf]{article} |
| |
| \newcommand{\rw}[1]{{\bf #1}} |
| \newcommand{\see}[1]{(see Section~\ref{#1})} |
| \newcommand{\nil}{{\bf nil}} |
| \newcommand{\Line}{\rule{\linewidth}{.5mm}} |
| \def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}} |
| |
| \newcommand{\Index}[1]{#1\index{#1}} |
| \newcommand{\IndexVerb}[1]{{\tt #1}\index{#1}} |
| \newcommand{\Def}[1]{{\em #1}\index{#1}} |
| \newcommand{\Deffunc}[1]{\index{#1}} |
| |
| \newcommand{\ff}{$\bullet$\ } |
| |
| \newcommand{\Version}{2.5} |
| |
| \makeindex |
| |
| \begin{document} |
| |
| \title{Reference Manual of the Programming Language Lua \Version} |
| |
| \author{% |
| Roberto Ierusalimschy\quad |
| Luiz Henrique de Figueiredo\quad |
| Waldemar Celes |
| \vspace{1.0ex}\\ |
| \smallskip |
| \small\tt lua@icad.puc-rio.br |
| \vspace{2.0ex}\\ |
| %MCC 08/95 --- |
| \tecgraf\ --- Departamento de Inform\'atica --- PUC-Rio |
| } |
| |
| \date{\small \verb$Date: 1997/03/06 21:13:34 $} |
| |
| \maketitle |
| |
| \thispagestyle{empty} |
| \pagestyle{empty} |
| |
| \begin{abstract} |
| \noindent |
| Lua is an extension programming language designed to be used |
| as a configuration language for any program that needs one. |
| This document describes version \Version\ of the Lua programming language and |
| the API that allows interaction between Lua programs and their host C programs. |
| \end{abstract} |
| |
| \vspace{4ex} |
| \begin{quotation} |
| \small |
| \begin{center}{\bf Sum\'ario}\end{center} |
| \vspace{1ex} |
| \noindent |
| Lua \'e uma linguagem de extens\~ao projetada para ser usada como |
| linguagem de configura\c{c}\~ao em qualquer programa que precise de |
| uma. |
| Este documento descreve a vers\~ao \Version\ da linguagem de |
| programa\c{c}\~ao Lua e a Interface de Programa\c{c}\~ao (API) que permite |
| a intera\c{c}\~ao entre programas Lua e programas C hospedeiros. |
| \end{quotation} |
| |
| |
| \vfill |
| \begin{quotation} |
| \noindent |
| \footnotesize |
| Copyright (c) 1994--1996 TeCGraf, PUC-Rio. Written by Waldemar Celes Filho, |
| Roberto Ierusalimschy, Luiz Henrique de Figueiredo. All rights reserved. |
| % |
| Permission is hereby granted, without written agreement and without license or |
| royalty fees, to use, copy, modify, and distribute this software and its |
| documentation for any purpose, subject to the following conditions: |
| % |
| The above copyright notice and this permission notice shall appear in all |
| copies or substantial portions of this software. |
| % |
| The name "Lua" cannot be used for any modified form of this software that does |
| not originate from the authors. Nevertheless, the name "Lua" may and should be |
| used to designate the language implemented and described in this package, |
| even if embedded in any other system, as long as its syntax and semantics |
| remain unchanged. |
| % |
| The authors specifically disclaim any warranties, including, but not limited |
| to, the implied warranties of merchantability and fitness for a particular |
| purpose. The software provided hereunder is on an "as is" basis, and the |
| authors have no obligation to provide maintenance, support, updates, |
| enhancements, or modifications. In no event shall TeCGraf, PUC-Rio, or the |
| authors be liable to any party for direct, indirect, special, incidental, or |
| consequential damages arising out of the use of this software and its |
| documentation. |
| \end{quotation} |
| \vfill |
| |
| \newpage |
| |
| \tableofcontents |
| |
| \newpage |
| \setcounter{page}{1} |
| \pagestyle{plain} |
| |
| |
| \section{Introduction} |
| |
| Lua is an extension programming language designed to support |
| general procedural programming features with data description |
| facilities. |
| It is intended to be used as a |
| light-weight, but powerful, configuration language for any |
| program that needs one. |
| Lua has been designed and implemented by |
| W.~Celes, |
| R.~Ierusalimschy and |
| L.~H.~de Figueiredo. |
| |
| 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 |
| many, completely different domains, |
| thus creating customized programming languages sharing a syntactical framework. |
| |
| Lua is free-distribution software, |
| and provided as usual with no guarantees. |
| The implementation described in this manual is available |
| at the following URL's: |
| \begin{verbatim} |
| http://www.inf.puc-rio.br/~roberto/lua.html |
| ftp://ftp.icad.puc-rio.br/pub/lua/lua.tar.gz |
| \end{verbatim} |
| |
| |
| \section{Environment and Chunks} |
| |
| All statements in Lua are executed in a \Def{global environment}. |
| This environment, which keeps all global variables and functions, |
| is initialized at the beginning of the embedding program and |
| persists until its end. |
| |
| The global environment can be manipulated by Lua code or |
| by the embedding program, |
| which can read and write global variables |
| using functions in the library that implements Lua. |
| |
| \Index{Global variables} do not need declaration. |
| Any variable is assumed to be global unless explicitly declared local |
| \see{localvar}. |
| Before the first assignment, the value of a global variable is \nil. |
| |
| The unit of execution of Lua is called a \Def{chunk}. |
| The syntax% |
| \footnote{As usual, \rep{{\em a}} means 0 or more {\em a\/}'s, |
| \opt{{\em a}} means an optional {\em a} and \oneormore{{\em a}} means |
| one or more {\em a\/}'s.} |
| for chunks is: |
| \begin{Produc} |
| \produc{chunk}{\rep{statement \Or function} \opt{ret}} |
| \end{Produc}% |
| A chunk may contain statements and function definitions, |
| and may be in a file or in a string inside the host program. |
| A chunk may optionally end with a \verb|return| statement \see{return}. |
| When a chunk is executed, first all its functions and statements are compiled, |
| then the statements are executed in sequential order. |
| All modifications a chunk effects on the global environment persist |
| after its end. |
| Those include modifications to global variables and definitions |
| of new functions% |
| \footnote{Actually, a function definition is an |
| assignment to a global variable \see{TypesSec}.}. |
| |
| Chunks may be pre-compiled; see program \IndexVerb{luac} for details. |
| Text files with chunks and their binary pre-compiled forms |
| are interchangeable. |
| Lua automatically detects the file type and acts accordingly. |
| \index{pre-compilation} |
| |
| \section{\Index{Types}} \label{TypesSec} |
| |
| Lua is a dynamically typed language. |
| Variables do not have types; only values do. |
| All values carry their own type. |
| Therefore, there are no type definitions in the language. |
| |
| There are seven \Index{basic types} in Lua: \Def{nil}, \Def{number}, |
| \Def{string}, \Def{function}, \Def{CFunction}, \Def{userdata}, |
| and \Def{table}. |
| {\em Nil\/} is the type of the value \nil, |
| whose main property is to be different from any other value. |
| {\em Number\/} represents real (floating point) numbers, |
| while {\em string\/} has the usual meaning. |
| |
| Functions are considered first-class values in Lua. |
| This means that functions can be stored in variables, |
| passed as arguments to other functions and returned as results. |
| When a function is defined in Lua, its body is compiled and stored |
| in a given variable. |
| Lua can call (and manipulate) functions written in Lua and |
| functions written in C; the latter have type {\em CFunction}. |
| |
| The type {\em userdata\/} is provided to allow |
| arbitrary \Index{C pointers} to be stored in Lua variables. |
| It corresponds to \verb'void*' and has no pre-defined operations in Lua, |
| besides assignment and equality test. |
| However, by using fallbacks, the programmer may define operations |
| for {\em userdata\/} values; \see{fallback}. |
| |
| The type {\em table\/} implements \Index{associative arrays}, |
| that is, \Index{arrays} that can be indexed not only with numbers, |
| but with any value (except \nil). |
| Therefore, this type may be used not only to represent ordinary arrays, |
| but also symbol tables, sets, records, etc. |
| To represent \Index{records}, Lua uses the field name as an index. |
| The language supports this representation by |
| providing \verb'a.name' as syntactic sugar for \verb'a["name"]'. |
| Tables may also carry methods. |
| Because functions are first class values, |
| table fields may contain functions. |
| The form \verb't:f(x)' is syntactic sugar for \verb't.f(t,x)', |
| which calls the method \verb'f' from the table \verb't' passing |
| itself as the first parameter. |
| |
| It is important to notice that tables are {\em objects}, and not values. |
| Variables cannot contain tables, only {\em references\/} to them. |
| Assignment, parameter passing and returns always manipulate references |
| to tables, and do not imply any kind of copy. |
| Moreover, tables must be explicitly created before used |
| \see{tableconstructor}. |
| |
| |
| |
| \section{The Language} |
| |
| This section describes the lexis, the syntax and the semantics of Lua. |
| |
| |
| \subsection{Lexical Conventions} \label{lexical} |
| |
| Lua is a case sensitive language. |
| \Index{Identifiers} can be any string of letters, digits, and underscores, |
| not beginning with a digit. |
| The following words are reserved, and cannot be used as identifiers: |
| \index{reserved words} |
| \begin{verbatim} |
| and do else elseif |
| end function if local |
| nil not or repeat |
| return then until while |
| \end{verbatim} |
| |
| The following strings denote other \Index{tokens}: |
| \begin{verbatim} |
| ~= <= >= < > == = .. + - * / |
| % ( ) { } [ ] ; , . |
| \end{verbatim} |
| |
| \Index{Literal strings} can be delimited by matching single or double quotes, |
| and can contain the C-like escape sequences |
| \verb-'\n'-, \verb-'\t'- and \verb-'\r'-. |
| Literal strings can also be delimited by matching \verb'[[ ... ]]'. |
| Literals in this bracketed form may run for several lines, |
| may contain nested \verb'[[ ... ]]' pairs, |
| and do not interpret escape sequences. |
| This form is specially convenient for |
| handling text that has quoted strings in it. |
| |
| \Index{Comments} start anywhere outside a string with a |
| double hyphen (\verb'--') and run until the end of the line. |
| Moreover, if the first line of a chunk file starts with \verb'#', |
| this line is skipped% |
| \footnote{This facility allows the use of Lua as a script interpreter |
| in Unix systems \see{lua-sa}.}. |
| |
| \Index{Numerical constants} may be written with an optional decimal part, |
| and an optional decimal exponent. |
| Examples of valid numerical constants are: |
| \begin{verbatim} |
| 4 4.0 0.4 4.57e-3 0.3e12 |
| \end{verbatim} |
| |
| |
| \subsection{\Index{Coercion}} \label{coercion} |
| |
| Lua provides some automatic conversions between values. |
| Any arithmetic operation applied to a string tries to convert |
| that string to a number, following the usual rules. |
| Conversely, whenever a number is used when a string is expected, |
| that number is converted to a string, according to the following rule: |
| if the number is an integer, it is written without exponent or decimal point; |
| otherwise, it is formatted following the \verb'%g' |
| conversion specification of the \verb'printf' function in the |
| standard C library. |
| For complete control on how numbers are converted to strings, |
| use the \verb|format| function \see{format}. |
| |
| |
| \subsection{\Index{Adjustment}} \label{adjust} |
| |
| Functions in Lua can return many values. |
| Because there are no type declarations, |
| the system does not know how many values a function will return, |
| or how many parameters it needs. |
| Therefore, sometimes, a list of values must be {\em adjusted\/}, at run time, |
| to a given length. |
| If there are more values than are needed, then the last values are thrown away. |
| If there are more needs than values, then the list is extended with as |
| many \nil's as needed. |
| Adjustment occurs in multiple assignment and function calls. |
| |
| |
| \subsection{Statements} |
| |
| Lua supports an almost conventional set of \Index{statements}, |
| similar to those in Pascal or C. |
| The conventional commands include |
| assignment, control structures and procedure calls. |
| Non-conventional commands include table constructors |
| \see{tableconstructor}, |
| and local variable declarations \see{localvar}. |
| |
| \subsubsection{Blocks} |
| A \Index{block} is a list of statements, which are executed sequentially. |
| Any statement can be optionally followed by a semicolon: |
| \begin{Produc} |
| \produc{block}{\rep{stat sc} \opt{ret}} |
| \produc{sc}{\opt{\ter{;}}} |
| \end{Produc}% |
| For syntactic reasons, a \IndexVerb{return} statement can only be written |
| as the last statement of a block. |
| This restriction also avoids some ``statement not reached'' errors. |
| |
| \subsubsection{\Index{Assignment}} \label{assignment} |
| The language allows \Index{multiple assignment}. |
| Therefore, the syntax defines a list of variables on the left side, |
| and a list of expressions on the right side. |
| Both lists have their elements separated by commas: |
| \begin{Produc} |
| \produc{stat}{varlist1 \ter{=} explist1} |
| \produc{varlist1}{var \rep{\ter{,} var}} |
| \end{Produc}% |
| This statement first evaluates all values on the right side |
| and eventual indices on the left side, |
| and then makes the assignments. |
| Therefore, it can be used to exchange two values, as in |
| \begin{verbatim} |
| x, y = y, x |
| \end{verbatim} |
| Before the assignment, the list of values is {\em adjusted\/} to |
| the length of the list of variables \see{adjust}. |
| |
| A single name can denote a global or a local variable, |
| or a formal parameter: |
| \begin{Produc} |
| \produc{var}{name} |
| \end{Produc}% |
| Square brackets are used to index a table: |
| \begin{Produc} |
| \produc{var}{var \ter{[} exp1 \ter{]}} |
| \end{Produc}% |
| If \verb'var' results in a table value, |
| the field indexed by the expression value gets the assigned value. |
| Otherwise, the fallback {\em settable\/} is called, |
| with three parameters: the value of \verb'var', |
| the value of expression, and the value being assigned to it; |
| \see{fallback}. |
| |
| The syntax \verb'var.NAME' is just syntactic sugar for |
| \verb'var["NAME"]': |
| \begin{Produc} |
| \produc{var}{var \ter{.} name} |
| \end{Produc}% |
| |
| \subsubsection{Control Structures} |
| The \Index{condition expression} of a control structure may return any value. |
| All values different from \nil\ are considered true; |
| only \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 or a chunk. |
| \label{return} |
| Because they may return more than one value, |
| the syntax for a \Index{return statement} is: |
| \begin{Produc} |
| \produc{ret}{\rwd{return} explist \opt{sc}} |
| \end{Produc} |
| |
| \subsubsection{Function Calls as Statements} \label{funcstat} |
| Because of possible side-effects, |
| function calls can be executed as statements: |
| \begin{Produc} |
| \produc{stat}{functioncall} |
| \end{Produc}% |
| In this case, returned values are thrown away. |
| Function calls are explained in Section~\ref{functioncall}. |
| |
| \subsubsection{Local Declarations} \label{localvar} |
| \Index{Local variables} may be declared anywhere inside a block. |
| Their scope begins after the declaration and lasts until the |
| end of the block. |
| The declaration may include an initial assignment: |
| \begin{Produc} |
| \produc{stat}{\rwd{local} declist \opt{init}} |
| \produc{declist}{name \rep{\ter{,} name}} |
| \produc{init}{\ter{=} explist1} |
| \end{Produc}% |
| If present, an initial assignment has the same semantics |
| of a multiple assignment. |
| Otherwise, all variables are initialized with \nil. |
| |
| |
| \subsection{\Index{Expressions}} |
| |
| \subsubsection{\Index{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'+' (addition), |
| \verb'-' (subtraction), |
| \verb'*' (multiplication), |
| \verb'/' (division) and \verb'^' (exponentiation), |
| and the unary \verb'-' (negation). |
| If the operands are numbers, or strings that can be converted to |
| numbers, according to the rules given in Section~\ref{coercion}, |
| then all operations except exponentiation have the usual meaning. |
| Otherwise, the fallback ``arith'' is called \see{fallback}. |
| An exponentiation always calls this fallback. |
| The standard mathematical library redefines this fallback, |
| giving the expected meaning to \Index{exponentiation} |
| \see{mathlib}. |
| |
| \subsubsection{Relational Operators} |
| Lua provides the following \Index{relational operators}: |
| \begin{verbatim} |
| < > <= >= ~= == |
| \end{verbatim} |
| All these return \nil\ as false and a value different from \nil\ |
| (actually the number 1) as true. |
| |
| Equality first compares the types of its operands. |
| If they are different, then the result is \nil. |
| Otherwise, their values are compared. |
| Numbers and strings are compared in the usual way. |
| Tables, CFunctions, and functions are compared by reference, |
| that is, two tables are considered equal only if they are the same table. |
| The operator \verb'~=' is exactly the negation of equality (\verb'=='). |
| Note that the conversion rules of Section~\ref{coercion} |
| do not apply to equality comparisons. |
| Thus, \verb|"0"==0| evaluates to false. |
| |
| The other operators work as follows. |
| If both arguments are numbers, then they are compared as such. |
| Otherwise, if both arguments can be converted to strings, |
| their values are compared using lexicographical order. |
| Otherwise, the ``order'' fallback is called \see{fallback}. |
| %Note that the conversion rules of Section~\ref{coercion} |
| %do apply to order operators. |
| %Thus, \verb|"2">"12"| evaluates to true. |
| |
| \subsubsection{Logical Operators} |
| Like control structures, all logical operators |
| consider \nil\ as false and anything else as true. |
| The \Index{logical operators} are: |
| \index{and}\index{or}\index{not} |
| \begin{verbatim} |
| and or not |
| \end{verbatim} |
| The operator \verb'and' returns \nil\ if its first argument is \nil; |
| otherwise it returns its second argument. |
| The operator \verb'or' returns its first argument |
| if it is different from \nil; |
| otherwise it returns its second argument. |
| Both \verb'and' and \verb'or' use \Index{short-cut evaluation}, |
| that is, |
| the second operand is evaluated only if necessary. |
| |
| \subsubsection{Concatenation} |
| Lua offers a string \Index{concatenation} operator, |
| denoted by ``\IndexVerb{..}''. |
| If operands are strings or numbers, then they are converted to |
| strings according to the rules in Section~\ref{coercion}. |
| Otherwise, the fallback ``concat'' is called \see{fallback}. |
| |
| \subsubsection{Precedence} |
| \Index{Operator precedence} follows the table below, |
| from the lower to the higher priority: |
| \begin{verbatim} |
| and or |
| < > <= >= ~= == |
| .. |
| + - |
| * / |
| not - (unary) |
| ^ |
| \end{verbatim} |
| All binary operators are left associative, |
| except for \verb'^' (exponentiation), |
| which is right associative. |
| |
| \subsubsection{Table Constructors} \label{tableconstructor} |
| Table \Index{constructors} are expressions that create tables; |
| every time a constructor is evaluated, a new table is created. |
| Constructors can be used to create empty tables, |
| or to create a table and initialize some fields. |
| |
| The general syntax for constructors is: |
| \begin{Produc} |
| \produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}} |
| \produc{fieldlist}{lfieldlist \Or ffieldlist \Or lfieldlist \ter{;} ffieldlist} |
| \produc{lfieldlist}{\opt{lfieldlist1}} |
| \produc{ffieldlist}{\opt{ffieldlist1}} |
| \end{Produc} |
| |
| The form {\em lfieldlist1\/} is used to initialize lists. |
| \begin{Produc} |
| \produc{lfieldlist1}{exp \rep{\ter{,} exp} \opt{\ter{,}}} |
| \end{Produc}% |
| The expressions in the list are assigned to consecutive numerical indices, |
| starting with 1. |
| For example: |
| \begin{verbatim} |
| a = {"v1", "v2", 34} |
| \end{verbatim} |
| is essentialy equivalent to: |
| \begin{verbatim} |
| temp = {} |
| temp[1] = "v1" |
| temp[2] = "v2" |
| temp[3] = 34 |
| a = temp |
| \end{verbatim} |
| |
| The next form initializes named fields in a table: |
| \begin{Produc} |
| \produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}} |
| \produc{ffield}{name \ter{=} exp} |
| \end{Produc}% |
| For example: |
| \begin{verbatim} |
| a = {x = 1, y = 3} |
| \end{verbatim} |
| is essentialy equivalent to: |
| \begin{verbatim} |
| temp = {} |
| temp.x = 1 -- or temp["x"] = 1 |
| temp.y = 3 -- or 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 value has type {\em function\/} or {\em CFunction}, |
| then this function is called. |
| Otherwise, the ``function'' fallback is called, |
| having as first parameter the value of \verb'var', |
| and then the original call parameters. |
| |
| The form: |
| \begin{Produc} |
| \produc{functioncall}{var \ter{:} name realParams} |
| \end{Produc}% |
| can be used to call ``methods''. |
| A call \verb'var:name(...)' |
| is syntactic sugar for |
| \begin{verbatim} |
| var.name(var, ...) |
| \end{verbatim} |
| except that \verb'var' is evaluated only once. |
| |
| \begin{Produc} |
| \produc{realParams}{\ter{(} \opt{explist1} \ter{)}} |
| \produc{realParams}{tableconstructor} |
| \produc{explist1}{exp1 \rep{\ter{,} exp1}} |
| \end{Produc}% |
| All argument expressions are evaluated before the call; |
| then the list of \Index{arguments} is adjusted to |
| the length of the list of parameters \see{adjust}; |
| finally, this list is assigned to the formal parameters. |
| A call of the form \verb'f{...}' is syntactic sugar for |
| \verb'f({...})', that is, |
| the parameter list is a single new table. |
| |
| Because a function can return any number of results |
| \see{return}, |
| the number of results must be adjusted before used. |
| If the function is called as a statement \see{funcstat}, |
| its return list is adjusted to 0, |
| thus discarding all returned values. |
| If the function is called in a place that needs a single value |
| (syntactically denoted by the non-terminal \verb'exp1'), |
| then its return list is adjusted to 1, |
| thus discarding all returned values, |
| except the first one. |
| If the function is called in a place that can hold many values |
| (syntactically denoted by the non-terminal \verb'exp'), |
| then no adjustment is made. |
| |
| |
| \subsection{\Index{Function Definitions}} |
| |
| Functions in Lua can be defined anywhere in the global level of a chunk. |
| The syntax for function definition is: |
| \begin{Produc} |
| \produc{function}{\rwd{function} var \ter{(} \opt{parlist1} \ter{)} |
| block \rwd{end}} |
| \end{Produc} |
| |
| When Lua pre-compiles a chunk, |
| all its function bodies are pre-compiled, too. |
| Then, when Lua ``executes'' the function definition, |
| its body is stored, with type {\em function}, |
| into the variable \verb'var'. |
| It is in this sense that |
| a function definition is an assignment to a global variable. |
| |
| Parameters act as local variables, |
| initialized with the argument values. |
| \begin{Produc} |
| \produc{parlist1}{name \rep{\ter{,} name}} |
| \end{Produc} |
| |
| Results are returned using the \verb'return' statement \see{return}. |
| If control reaches the end of a function without a return instruction, |
| then the function returns with no results. |
| |
| There is a special syntax for defining \Index{methods}, |
| that is, functions that have an extra parameter \Def{self}. |
| \begin{Produc} |
| \produc{function}{\rwd{function} var \ter{:} name \ter{(} \opt{parlist1} |
| \ter{)} block \rwd{end}} |
| \end{Produc}% |
| Thus, a declaration like |
| \begin{verbatim} |
| function v:f (...) |
| ... |
| end |
| \end{verbatim} |
| is equivalent to |
| \begin{verbatim} |
| function v.f (self, ...) |
| ... |
| end |
| \end{verbatim} |
| that is, the function gets an extra formal parameter called \verb'self'. |
| Notice that |
| the variable \verb'v' must have been previously initialized with a table value. |
| |
| |
| \subsection{Fallbacks} \label{fallback} |
| |
| Lua provides a powerful mechanism to extend its semantics, |
| called \Def{fallbacks}. |
| A fallback is a programmer defined function |
| that is called whenever Lua does not know how to proceed. |
| |
| Lua supports the following fallbacks, |
| identified by the given strings: |
| \begin{description} |
| \item[``arith'':]\index{arithmetic fallback} |
| called when an arithmetic operation is applied to non numerical operands, |
| or when the binary \verb'^' operation (exponentiation) 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 handler 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 handler 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 handler 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 handler returns \nil. |
| \item[``getglobal'':]\index{index getglobal} |
| called when Lua tries to retrieve the value of a global variable |
| which has a \nil\ value (or which has not been initialized). |
| It receives as argument the name of the variable. |
| Its return value is the final result of the expression. |
| The default handler 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 handler issues an error. |
| \item[``settable'':]\index{settable fallback} |
| called when Lua tries to assign to an index in a non table value. |
| It receives as arguments the non table value, |
| the index, and the assigned value. |
| The default handler issues an error. |
| \item[``function'':]\index{function fallback} |
| 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 handler 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, |
| to signal the completion of the garbage collection. |
| 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 handler does nothing. |
| \item[``error'':]\index{error fallback} |
| called when an error occurs. |
| It receives as argument a string describing the error. |
| The default handler prints the message on the standard error output |
| (\verb|stderr|). |
| \end{description} |
| |
| The function \IndexVerb{setfallback} is used to change a fallback handler. |
| Its first argument is the name of a fallback condition, |
| and the second argument is the new function to be called. |
| It returns the old handler function for the given fallback. |
| |
| |
| \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, |
| the ``error'' fallback function is called, |
| and then the corresponding function from the library |
| (\verb'lua_dofile', \verb'lua_dostring', |
| \verb'lua_call', or \verb'lua_callfunction') |
| is terminated returning an error condition. |
| |
| The only argument to the ``error'' fallback function is a string |
| describing the error. |
| The standard I/O library redefines this fallback, |
| using the debug facilities \see{debugI}, |
| in order to print some extra information, |
| like the call stack. |
| To provide more information about errors, |
| Lua programs can include the compilation pragma \verb'$debug'. |
| \index{debug pragma}\label{pragma} |
| This pragma must be written in a line by itself. |
| When an error occurs in a program compiled with this option, |
| the error routine is able to print the number of the lines where the calls |
| (and the error) were made. |
| If needed, it is possible to change the ``error'' fallback handler |
| \see{fallback}. |
| |
| Lua code can explicitly generate an error by calling the built-in |
| function \verb'error' \see{pdf-error}. |
| |
| |
| \section{The Application Program Interface} |
| |
| This section describes the API for Lua, that is, |
| the set of C functions available to the host program to communicate |
| with the library. |
| The API functions can be classified in the following categories: |
| \begin{enumerate} |
| \item exchanging values between C and Lua; |
| \item executing Lua code; |
| \item manipulating (reading and writing) Lua objects; |
| \item calling Lua functions; |
| \item C functions to be called by Lua; |
| \item manipulating references to Lua Objects. |
| \end{enumerate} |
| All API functions and related types and constants |
| are declared in the header file \verb'lua.h'. |
| |
| \subsection{Exchanging Values between C and Lua} \label{valuesCLua} |
| Because Lua has no static type system, |
| all values passed between Lua and C have type |
| \verb'lua_Object'\Deffunc{lua_Object}, |
| which works like an abstract type in C that can hold any Lua value. |
| Values of type \verb'lua_Object' have no meaning outside Lua; |
| for instance, |
| the comparisson of two \verb"lua_Object's" is undefined. |
| |
| 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 functions: |
| \Deffunc{lua_isnil}\Deffunc{lua_isnumber}\Deffunc{lua_isstring} |
| \Deffunc{lua_istable}\Deffunc{lua_iscfunction}\Deffunc{lua_isuserdata} |
| \Deffunc{lua_isfunction} |
| \begin{verbatim} |
| int lua_isnil (lua_Object object); |
| int lua_isnumber (lua_Object object); |
| int lua_isstring (lua_Object object); |
| int lua_istable (lua_Object object); |
| int lua_isfunction (lua_Object object); |
| int lua_iscfunction (lua_Object object); |
| int lua_isuserdata (lua_Object object); |
| \end{verbatim} |
| All macros return 1 if the object is compatible with the given type, |
| and 0 otherwise. |
| The function \verb'lua_isnumber' accepts numbers and numerical strings, |
| whereas |
| \verb'lua_isstring' accepts strings and numbers \see{coercion}, |
| and \verb'lua_isfunction' accepts Lua and C functions. |
| The function \verb'lua_type' can be used to distinguish between |
| different kinds of user data. |
| |
| To translate a value from type \verb'lua_Object' to a specific C type, |
| the programmer can use: |
| \Deffunc{lua_getnumber}\Deffunc{lua_getstring} |
| \Deffunc{lua_getcfunction}\Deffunc{lua_getuserdata} |
| \begin{verbatim} |
| double lua_getnumber (lua_Object object); |
| char *lua_getstring (lua_Object object); |
| lua_CFunction lua_getcfunction (lua_Object object); |
| void *lua_getuserdata (lua_Object object); |
| \end{verbatim} |
| \verb'lua_getnumber' converts a \verb'lua_Object' to a floating-point number. |
| 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 \verb|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 \verb|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 \verb|NULL| pointer). |
| |
| Because Lua has automatic memory management and garbage collection, |
| a \verb'lua_Object' has a limited scope, |
| and is only valid inside the {\em block\/} where it was created. |
| A C function called from Lua is a block, |
| and its parameters are valid only until its end. |
| It is good programming practice to convert Lua objects to C values |
| as soon as they are available, |
| and never to store \verb'lua_Object's in C global variables. |
| |
| |
| All comunication between Lua and C is done through two |
| abstract data types, called \Def{lua2C} and \Def{C2lua}. |
| The first one, as the name implies, is used to pass values |
| from Lua to C: parameters when Lua calls C and results when C calls Lua. |
| The structure C2lua is used in the reverse direction: |
| parameters when C calls Lua and results when Lua calls C. |
| Notice that the structure lua2C cannot be directly modified by C code, |
| while the structure C2lua cannot be ``read'' by C code. |
| |
| The structure lua2C is an abstract array, |
| which can be indexed with the function: |
| \Deffunc{lua_lua2C} |
| \begin{verbatim} |
| lua_Object lua_lua2C (int number); |
| \end{verbatim} |
| where \verb'number' starts with 1. |
| When called with a number larger than the array size, |
| this function returns |
| \verb'LUA_NOOBJECT'\Deffunc{LUA_NOOBJECT}. |
| In this way, it is possible to write C functions that receive |
| a variable number of parameters, |
| and to call Lua functions that return a variable number of results. |
| |
| The second structure, C2lua, is a stack. |
| Pushing elements into this stack |
| is done by using the following functions: |
| \Deffunc{lua_pushnumber}\Deffunc{lua_pushstring} |
| \Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag} |
| \Deffunc{lua_pushnil}\Deffunc{lua_pushobject} |
| \Deffunc{lua_pushuserdata}\label{pushing} |
| \begin{verbatim} |
| void lua_pushnumber (double n); |
| void lua_pushstring (char *s); |
| void lua_pushcfunction (lua_CFunction f); |
| void lua_pushusertag (void *u, int tag); |
| void lua_pushnil (void); |
| void lua_pushobject (lua_Object object); |
| \end{verbatim} |
| plus the macro: |
| \begin{verbatim} |
| void lua_pushuserdata (void *u); |
| \end{verbatim} |
| All of them receive a C value, |
| convert it to a corresponding \verb'lua_Object', |
| and leave the result on the top of C2lua. |
| |
| User data can have different tags, |
| whose semantics are only known to the host program. |
| Any positive integer can be used to tag a user datum. |
| When a user datum is retrieved, |
| the function \verb'lua_type' can be used to get its tag. |
| |
| {\em Please note:} most functions in the Lua API |
| use the structures lua2C and C2lua, |
| and therefore change their contents. |
| Great care must be taken, |
| specially when pushing a sequence of objects into C2lua, |
| to avoid using those functions. |
| The family of functions \verb|lua_get*|, \verb|lua_is*|, |
| plus the function \verb|lua_lua2C|, |
| are safe to be called without modifying these structures; |
| the family \verb|lua_push*| does not modify lua2C. |
| All other functions may change lua2C and C2lua, |
| unless noticed otherwise. |
| |
| 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. |
| The use of explicit nested blocks is strongly encouraged. |
| |
| \subsection{Executing Lua Code} |
| A host program can execute Lua chunks written in a file or in a string |
| using the following functions: |
| \Deffunc{lua_dofile}\Deffunc{lua_dostring} |
| \begin{verbatim} |
| int lua_dofile (char *filename); |
| int lua_dostring (char *string); |
| \end{verbatim} |
| Both functions return an error code: |
| 0, in case of success; non zero, in case of errors. |
| More specifically, \verb'lua_dofile' returns 2 if for any reason |
| it could not open the file. |
| The function \verb'lua_dofile', if called with argument \verb'NULL', |
| executes the \verb|stdin| stream. |
| Function \verb'lua_dofile' is also able to execute pre-compiled chunks. |
| It automatically detects whether the file is text or binary, |
| and loads it accordingly (see program \IndexVerb{luac}). |
| These functions also return, in structure lua2C, |
| any values eventually returned by the chunks. |
| |
| |
| \subsection{Manipulating Lua Objects} |
| To read the value of any global Lua variable, |
| one uses the function: |
| \Deffunc{lua_getglobal} |
| \begin{verbatim} |
| lua_Object lua_getglobal (char *varname); |
| \end{verbatim} |
| As in Lua, if the value of the global is \nil, |
| then the ``getglobal'' fallback is called. |
| |
| To store a value previously pushed onto C2lua 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 C2lua a table and an index, |
| and returns the contents of the table at that index. |
| As in Lua, if the first object is not a table, |
| or the index is not present in the table, |
| the corresponding fallback is called. |
| |
| To store a value in an index, |
| the program must push the table, the index, |
| and the value onto C2lua, |
| and then call the function: |
| \Deffunc{lua_storesubscript} |
| \begin{verbatim} |
| void lua_storesubscript (void); |
| \end{verbatim} |
| Again, the ``settable'' fallback is called if a non-table value is used. |
| |
| Finally, the function |
| \Deffunc{lua_createtable} |
| \begin{verbatim} |
| lua_Object lua_createtable (void); |
| \end{verbatim} |
| creates and returns a new, empty table. |
| |
| As already noted, |
| most functions from the Lua library receive parameters through C2lua. |
| Because other functions also use this stack, |
| it is important that these |
| parameters be pushed just before the corresponding call, |
| without intermediate calls to the Lua library. |
| For instance, suppose the user wants the value of \verb'a[i]', |
| where \verb'a' and \verb'i' are global Lua variables. |
| 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} |
| This code is incorrect because |
| 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 C2lua |
| \see{pushing}, in direct order, i.e., the first argument is pushed first. |
| Again, it is important to emphasize that, during this phase, |
| most other Lua functions cannot 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 results (a Lua function may return many values) |
| are returned in structure lua2C, |
| and can be retrieved with the macro \verb|lua_getresult|, |
| \Deffunc{lua_getresult} |
| which is just another name to the function \verb|lua_lua2C|. |
| |
| The following example shows how a C program may call the |
| \verb|strsub| function in Lua to extract a piece of a string: |
| \begin{verbatim} |
| /* assume that 's' and 'r' are strings (char *), 'i' and 'j' integers */ |
| lua_pushstring(s); /* 1st argument */ |
| lua_pushnumber(i); /* 2nd argument */ |
| lua_pushnumber(j); /* 3rd argument */ |
| lua_call("strsub"); /* call Lua function */ |
| r = lua_getstring(lua_getresult(1)); /* r = strsub(s, i, j) */ |
| \end{verbatim} |
| |
| 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, |
| then the corresponding Lua execution terminates, |
| as if an error had occurred inside Lua code. |
| Otherwise, the whole program terminates with a call to \verb|exit(1)|. |
| %%LHF: proponho lua_error(char* m, int rc), gerando exit(rc) |
| |
| 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 \see{fallback}, |
| and the second is 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 failure (invalid fallback name). |
| This old value can be used for chaining fallbacks. |
| |
| |
| \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. |
| |
| A C function receives its arguments in structure lua2C; |
| to access them, it uses the macro \verb|lua_getparam|, \Deffunc{lua_getparam} |
| again just another name to \verb|lua_lua2C|. |
| To return values, a C function just pushes them onto the stack C2lua, |
| in direct order \see{valuesCLua}. |
| Like a Lua function, a C function called by Lua can also return |
| many results. |
| |
| As an example, |
| the code below shows a CFunction to compute the maximum of |
| a variable number of arguments: |
| \begin{verbatim} |
| void math_max (void) |
| { |
| int i=1; /* argument count */ |
| 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} |
| To be available in Lua, this function must be registered: |
| \begin{verbatim} |
| lua_register ("max", math_max); |
| \end{verbatim} |
| |
| For more examples, see files \verb|strlib.c|, |
| \verb|iolib.c| and \verb|mathlib.c| in Lua distribution. |
| |
| \subsection{References to Lua Objects} |
| |
| As noted in Section~\ref{LuacallC}, \verb'lua_Object's are volatile. |
| If the C code needs to keep a \verb'lua_Object' |
| outside block boundaries, |
| it must create a \Def{reference} to the object. |
| The routines to manipulate references are the following: |
| \Deffunc{lua_ref}\Deffunc{lua_getref} |
| \Deffunc{lua_pushref}\Deffunc{lua_unref} |
| \begin{verbatim} |
| int lua_ref (int lock); |
| lua_Object lua_getref (int ref); |
| void lua_pushref (int ref); |
| void lua_unref (int ref); |
| \end{verbatim} |
| The function \verb'lua_ref' creates a reference |
| to the object that is on the top of the stack, |
| and returns this reference. |
| If \verb'lock' is true, the object is {\em locked\/}: |
| this means the object will not be garbage collected. |
| Notice that an unlocked reference may be garbage collected. |
| Whenever the referenced object is needed, |
| a call to \verb'lua_getref' |
| returns a handle to it, |
| whereas \verb'lua_pushref' pushes the object on the stack. |
| If the object has been collected, |
| then \verb'lua_getref' returns \verb'LUA_NOOBJECT', |
| and \verb'lua_pushobject' issues an error. |
| |
| When a reference is no longer needed, |
| it can be freed with a call to \verb'lua_unref'. |
| |
| The function \verb|lua_pushref| does not corrupt the |
| structures lua2C and C2lua, and therefore is safe to |
| be called when pushing parameters onto C2lua. |
| |
| |
| |
| \section{Predefined Functions and Libraries} |
| |
| The set of \Index{predefined functions} in Lua is small but powerful. |
| Most of them provide features that allow some degree of |
| \Index{reflexivity} in the language. |
| Some of these features cannot be simulated with the rest of the |
| Language nor with the standard Lua API. |
| Others are just convenient interfaces to common API functions. |
| |
| The libraries, on the other hand, provide useful routines |
| that are implemented directly through the standard API. |
| Therefore, they are not necessary to the language, |
| and are provided as separate C modules. |
| Currently there are three standard libraries: |
| \begin{itemize} |
| \item string manipulation; |
| \item mathematical functions (sin, log, etc); |
| \item input and output (plus some system facilities). |
| \end{itemize} |
| 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*{\ff{\tt dofile (filename)}}\Deffunc{dofile} |
| This function receives a file name, |
| opens it, and executes its contents as a Lua chunk, |
| or as pre-compiled chunks. |
| When called without arguments, |
| it executes the contents of the standard input (\verb'stdin'). |
| If there is any error executing the file, it returns \nil. |
| Otherwise, it returns the values returned by the chunk, |
| or a non \nil\ value if the chunk returns no values. |
| It issues an error when called with a non string argument. |
| \verb|dofile| is simply an interface to \verb|lua_dofile|. |
| |
| \subsubsection*{\ff{\tt dostring (string)}}\Deffunc{dostring} |
| This function executes a given string as a Lua chunk. |
| If there is any error executing the string, it returns \nil. |
| Otherwise, it returns the values returned by the chunk, |
| or a non \nil\ value if the chunk returns no values. |
| \verb|dostring| is simply an interface to \verb|lua_dostring|. |
| |
| \subsubsection*{\ff{\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 in which the indices are enumerated is not specified, |
| {\em even for numeric indices}. |
| If the table is modified in any way during a traversal, |
| the semantics of \verb|next| is undefined. |
| |
| This function cannot be written with the standard API. |
| |
| \subsubsection*{\ff{\tt nextvar (name)}}\Deffunc{nextvar} |
| This function is similar to the function \verb'next', |
| but iterates over the global variables. |
| Its single argument is the name of a global variable, |
| or \nil\ to get a first name. |
| Similarly to \verb'next', it returns the name of another variable |
| and its value, |
| or \nil\ if there are no more variables. |
| There can be no assignments to global variables during the traversal; |
| otherwise the semantics of \verb|nextvar| is undefined. |
| |
| This function cannot be written with the standard API. |
| |
| \subsubsection*{\ff{\tt tostring (e)}}\Deffunc{tostring} |
| This function receives an argument of any type and |
| converts it to a string in a reasonable format. |
| |
| \subsubsection*{\ff{\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*{\ff{\tt tonumber (e)}}\Deffunc{tonumber} |
| This function receives one argument, |
| and tries to convert it to a number. |
| If the argument is already a number or a string convertible |
| to a number \see{coercion}, then it returns that number; |
| otherwise, it returns \nil. |
| |
| \subsubsection*{\ff{\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. |
| |
| \verb|type| is simply an interface to \verb|lua_type|. |
| |
| \subsubsection*{\ff{\tt assert (v)}}\Deffunc{assert} |
| This function issues an {\em ``assertion failed!''} error |
| when its argument is \nil. |
| |
| \subsubsection*{\ff{\tt error (message)}}\Deffunc{error}\label{pdf-error} |
| This function issues an error message and terminates |
| the last called function from the library |
| (\verb'lua_dofile', \verb'lua_dostring', \ldots). |
| It never returns. |
| \verb|error| is simply an interface to \verb|lua_error|. |
| |
| \subsubsection*{\ff{\tt setglobal (name, value)}}\Deffunc{setglobal} |
| This function assigns the given value to a global variable. |
| The string \verb'name' does not need to be a syntactically valid variable name. |
| Therefore, this function can set global variables with strange names like |
| \verb|`m v 1'| or \verb'34'. |
| It returns the value of its second argument. |
| \verb|setglobal| is simply an interface to \verb|lua_storeglobal|. |
| |
| \subsubsection*{\ff{\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*{\ff{\tt setfallback (fallbackname, newfallback)}} |
| \Deffunc{setfallback} |
| This function sets a new fallback function to the given fallback. |
| It returns the old fallback function. |
| \verb|setfallback| is simply an interface to \verb|lua_setfallback|. |
| |
| \subsection{String Manipulation} |
| This library provides generic functions for string manipulation, |
| such as finding and extracting substrings and pattern matching. |
| When indexing a string, the first character is at position 1, |
| not 0, as in C. |
| |
| \subsubsection*{\ff{\tt strfind (str, pattern [, init [, plain]])}} |
| \Deffunc{strfind} |
| This function looks for the first {\em match\/} of |
| \verb-pattern- in \verb-str-. |
| If it finds one, then it returns the indices on \verb-str- |
| where this occurence starts and ends; |
| otherwise, it returns \nil. |
| If the pattern specifies captures, |
| the captured strings are returned as extra results. |
| A third optional numerical argument specifies where to start the search; |
| its default value is 1. |
| A value of 1 as a forth optional argument |
| turns off the pattern matching facilities, |
| so the function does a plain ``find substring'' operation. |
| |
| \subsubsection*{\ff{\tt strlen (s)}}\Deffunc{strlen} |
| Receives a string and returns its length. |
| |
| \subsubsection*{\ff{\tt strsub (s, i [, j])}}\Deffunc{strsub} |
| Returns another string, which is a substring of \verb's', |
| starting at \verb'i' and runing until \verb'j'. |
| If \verb'j' is absent, |
| it is assumed to be equal to the length of \verb's'. |
| In particular, the call \verb'strsub(s,1,j)' returns a prefix of \verb's' |
| with length \verb'j', |
| whereas the call \verb'strsub(s,i)' returns a suffix of \verb's', |
| starting at \verb'i'. |
| |
| \subsubsection*{\ff{\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*{\ff{\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*{\ff{\tt strrep (s, n)}}\Deffunc{strrep} |
| Returns a string which is the concatenation of \verb-n- copies of |
| the string \verb-s-. |
| |
| \subsubsection*{\ff{\tt ascii (s [, i])}}\Deffunc{ascii} |
| Returns the ASCII code of the character \verb's[i]'. |
| If \verb'i' is absent, then it is assumed to be 1. |
| |
| \subsubsection*{\ff{\tt format (formatstring, e1, e2, \ldots)}}\Deffunc{format} |
| \label{format} |
| This function returns a formated version of its variable number of arguments |
| following the description given in its first argument (which must be a string). |
| The format string follows the same rules as the \verb'printf' family of |
| standard C functions. |
| The only differences are that the options/modifiers |
| \verb'*', \verb'l', \verb'L', \verb'n', \verb'p', |
| and \verb'h' are not supported, |
| and there is an extra option, \verb'q'. |
| This option formats a string in a form suitable to be safely read |
| back by the Lua interpreter; |
| that is, |
| the string is written between double quotes, |
| and all double quotes, returns and backslashes in the string |
| are correctly escaped when written. |
| For instance, the call |
| \begin{verbatim} |
| format('%q', 'a string with "quotes" and \n new line') |
| \end{verbatim} |
| will produce the string: |
| \begin{verbatim} |
| "a string with \"quotes\" and \ |
| new line" |
| \end{verbatim} |
| |
| The options \verb'c', \verb'd', \verb'E', \verb'e', \verb'f', |
| \verb'g' \verb'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. |
| Note that the \verb'*' modifier can be simulated by building |
| the appropriate format string. |
| For example, \verb|"%*g"| can be simulated with |
| \verb|"%"..width.."g"|. |
| |
| \subsubsection*{\ff{\tt gsub (s, pat, repl [, n])}}\Deffunc{gsub} |
| Returns a copy of \verb-s-, |
| where all occurrences of the pattern \verb-pat- have been |
| replaced by a replacement string specified by \verb-repl-. |
| This function also returns, as a second value, |
| the total number of substitutions made. |
| |
| If \verb-repl- is a string, then its value is used for replacement. |
| Any sequence in \verb-repl- of the form \verb-%n- |
| with \verb-n- between 1 and 9 |
| stands for the value of the n-th captured substring. |
| |
| If \verb-repl- is a function, then this function is called every time a |
| match occurs, with all captured substrings as parameters |
| (see below). |
| If the value returned by this function is a string, |
| then it is used as the replacement string; |
| otherwise, the replacement string is the empty string. |
| |
| An 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. |
| |
| As an example, in the following expression each occurrence of the form |
| \verb-$name- calls the function \verb|getenv|, |
| passing \verb|name| as argument |
| (because only this part of the pattern is captured). |
| The value returned by \verb|getenv| will replace the pattern. |
| Therefore, the whole expression: |
| \begin{verbatim} |
| gsub("home = $HOME, user = $USER", "$(%w%w*)", getenv) |
| \end{verbatim} |
| returns a string like: |
| \begin{verbatim} |
| home = /home/roberto, user = roberto |
| \end{verbatim} |
| |
| \subsubsection*{Patterns} \label{pm} |
| |
| \paragraph{Character Class:} |
| a \Def{character class} is used to represent a set of characters. |
| The following combinations are allowed in describing a character class: |
| \begin{description} |
| \item[{\em x}] (where {\em x} is any character not in the list \verb'()%.[*?') |
| --- represents the character {\em x} itself. |
| \item[{\tt .}] --- represents all characters. |
| \item[{\tt \%a}] --- represents all letters. |
| \item[{\tt \%A}] --- represents all non letter characters. |
| \item[{\tt \%d}] --- represents all digits. |
| \item[{\tt \%D}] --- represents all non digits. |
| \item[{\tt \%l}] --- represents all lower case letters. |
| \item[{\tt \%L}] --- represents all non lower case letter characters. |
| \item[{\tt \%s}] --- represents all space characters. |
| \item[{\tt \%S}] --- represents all non space characters. |
| \item[{\tt \%u}] --- represents all upper case letters. |
| \item[{\tt \%U}] --- represents all non upper case letter characters. |
| \item[{\tt \%w}] --- represents all alphanumeric characters. |
| \item[{\tt \%W}] --- represents all non alphanumeric characters. |
| \item[{\tt \%\em x}] (where {\em x} is any non alphanumeric character) --- |
| represents the character {\em x}. |
| This is the standard way to escape the magic characters \verb'()%.[*?'. |
| \item[{\tt [char-set]}] --- |
| Represents the class which is the union of all |
| characters in char-set. |
| To include a \verb']' in char-set, it must be the first character. |
| A range of characters may be specified by |
| separating the end characters of the range with a \verb'-'; |
| e.g., \verb'A-Z' specifies the upper case characters. |
| If \verb'-' appears as the first or last character of char-set, |
| then it represents itself. |
| All classes \verb'%'{\em x} described above can also be used as |
| components in a char-set. |
| All other characters in char-set represent themselves. |
| \item[{\tt [\^{ }char-set]}] --- |
| represents the complement of char-set, |
| where char-set is interpreted as above. |
| \end{description} |
| |
| \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 itens 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 itens will always match the shortest possible sequence. |
| \item |
| a single character class followed by \verb'?', |
| which matches 0 or 1 occurrence of a character in the class; |
| \item |
| {\tt \%$n$}, for $n$ between 1 and 9; |
| such item matches a sub-string equal to the n-th captured string |
| (see below); |
| \item |
| {\tt \%b$xy$}, where $x$ and $y$ are two distinct characters; |
| such item mathes strings that start with $x$, end with $y$, |
| and where the $x$ and $y$ are {\em balanced}. |
| That means that, if one reads the string from left to write, |
| counting plus 1 for an $x$ and minus 1 for a $y$, |
| the ending $y$ is the first where the count reaches 0. |
| For instance, the item \verb|%()| matches expressions with |
| balanced parentheses. |
| \end{itemize} |
| |
| \paragraph{Pattern:} |
| a \Def{pattern} is a sequence of pattern items. |
| A \verb'^' at the beginning of a pattern anchors the match at the |
| beginning of the subject string. |
| A \verb'$' at the end of a pattern anchors the match at the |
| end of the subject string. |
| |
| \paragraph{Captures:} |
| a pattern may contain sub-patterns enclosed in parentheses, |
| that describe \Def{captures}. |
| When a match succeeds, the sub-strings of the subject string |
| that match captures are stored ({\em captured\/}) for future use. |
| Captures are numbered according to their left parentheses. |
| For instance, in the pattern \verb|"(a*(.)%w(%s*))"|, |
| the part of the string matching \verb|"a*(.)%w(%s*)"| is |
| stored as the first capture (and therefore has number 1); |
| the character matching \verb|.| is captured with number 2, |
| and the part matching \verb|%s*| has number 3. |
| |
| \subsection{Mathematical Functions} \label{mathlib} |
| |
| This library is an interface to some functions of the standard C math library. |
| In addition, it registers a fallback for the binary operator \verb'^' that, |
| returns $x^y$ when applied to numbers \verb'x^y'. |
| |
| The library provides the following functions: |
| \Deffunc{abs}\Deffunc{acos}\Deffunc{asin}\Deffunc{atan} |
| \Deffunc{atan2}\Deffunc{ceil}\Deffunc{cos}\Deffunc{floor} |
| \Deffunc{log}\Deffunc{log10}\Deffunc{max}\Deffunc{min} |
| \Deffunc{mod}\Deffunc{sin}\Deffunc{sqrt}\Deffunc{tan} |
| \Deffunc{random}\Deffunc{randomseed} |
| \begin{verbatim} |
| abs acos asin atan atan2 ceil cos floor log log10 |
| max min mod sin sqrt tan random randomseed |
| \end{verbatim} |
| Most of them |
| are only interfaces to the homonymous functions in the C library, |
| except that, for the trigonometric functions, |
| all angles are expressed in {\em degrees}, not radians. |
| |
| The function \verb'max' returns the maximum |
| value of its numeric arguments. |
| Similarly, \verb'min' computes the minimum. |
| Both can be used with an unlimited number of arguments. |
| |
| The functions \verb'random' and \verb'randomseed' are interfaces to |
| the simple random generator functions \verb'rand' and \verb'srand', |
| provided by ANSI C. |
| The function \verb'random' returns pseudo-random numbers in the range |
| $[0,1)$. |
| |
| |
| \subsection{I/O Facilities} \label{libio} |
| |
| All input and outpu 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 \nil\ on failure and |
| some value different from \nil\ on success. |
| |
| \subsubsection*{\ff{\tt readfrom (filename)}}\Deffunc{readfrom} |
| |
| This function may be called in three ways. |
| When called with a file name, |
| it opens the named file, |
| sets it as the {\em current\/} input file, |
| and returns a {\em handle\/} to the file |
| (this handle is a user data containing the file stream \verb|FILE*|). |
| It does not close the current input file. |
| When called with a file handle, returned by a previous call, |
| it restores the file as the current input. |
| When called without parameters, |
| it closes the current input file, |
| and restores \verb'stdin' as the current input file. |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \begin{quotation} |
| \noindent |
| {\em System dependent\/}: if \verb'filename' starts with a \verb'|', |
| then a \Index{piped input} is open, via function \IndexVerb{popen}. |
| Not all systems implement pipes. |
| Moreover, |
| the number of files that can be open at the same time is usually limited and |
| depends on the system. |
| \end{quotation} |
| |
| \subsubsection*{\ff{\tt writeto (filename)}}\Deffunc{writeto} |
| |
| This function may be called in three ways. |
| When called with a file name, |
| it opens the named file, |
| sets it as the {\em current\/} output file, |
| and returns a {\em handle\/} to the file |
| (this handle is a user data containing the file stream \verb|FILE*|). |
| It does not close the current output file. |
| Notice that, if the file already exists, |
| it will be {\em completely erased\/} with this operation. |
| When called with a file handle, returned by a previous call, |
| it restores the file as the current output. |
| When called without parameters, |
| this function closes the current output file, |
| and restores \verb'stdout' as the current output file. |
| \index{closing a file} |
| %%LHF: nao tem como escrever em stderr, tem? |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \begin{quotation} |
| \noindent |
| {\em System dependent\/}: if \verb'filename' starts with a \verb'|', |
| then a \Index{piped output} is open, via function \IndexVerb{popen}. |
| Not all systems implement pipes. |
| Moreover, |
| the number of files that can be open at the same time is usually limited and |
| depends on the system. |
| \end{quotation} |
| |
| \subsubsection*{\ff{\tt appendto (filename)}}\Deffunc{appendto} |
| |
| This function opens a file named \verb'filename' and sets it as the |
| {\em current\/} output file. |
| It returns the file handle, |
| or \nil\ in case of error. |
| Unlike the \verb'writeto' operation, |
| this function does not erase any previous content of the file. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| Notice that function \verb|writeto| is available to close an output file. |
| |
| \subsubsection*{\ff{\tt remove (filename)}}\Deffunc{remove} |
| |
| This function deletes the file with the given name. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff{\tt rename (name1, name2)}}\Deffunc{rename} |
| |
| This function renames file named \verb'name1' to \verb'name2'. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff{\tt tmpname ()}}\Deffunc{tmpname} |
| |
| This function returns a string with a file name that can safely |
| be used for a temporary file. |
| |
| \subsubsection*{\ff{\tt read ([readpattern])}}\Deffunc{read} |
| |
| This function reads the current input |
| according to a read pattern, that specifies how much to read; |
| characters are read from the current input file until |
| the read pattern fails or ends. |
| The function \verb|read| returns a string with the characters read, |
| even if the pattern succeeds only partially, |
| or \nil\ if the read pattern fails {\em and\/} |
| the result string would be empty. |
| When called without parameters, |
| it uses a default pattern that reads the next line |
| (see below). |
| |
| A \Def{read pattern} is a sequence of read pattern items. |
| An item may be a single character class |
| or a character class followed by \verb'?' or by \verb'*'. |
| A single character class reads the next character from the input |
| if it belongs to the class, otherwise it fails. |
| A character class followed by \verb'?' reads the next character |
| from the input if it belongs to the class; |
| it never fails. |
| A character class followed by \verb'*' reads until a character that |
| does not belong to the class, or end of file; |
| since it can match a sequence of zero characteres, it never fails.% |
| \footnote{ |
| Notice that the behavior of read patterns is different from |
| the regular pattern matching behavior, |
| where a \verb'*' expands to the maximum length {\em such that\/} |
| the rest of the pattern does not fail. |
| With the read pattern behavior |
| there is no need for backtracking the reading. |
| } |
| |
| A pattern item may contain sub-patterns enclosed in curly brackets, |
| that describe \Def{skips}. |
| Characters matching a skip are read, |
| but are not included in the resulting string. |
| |
| Following are some examples of read patterns and their meanings: |
| \begin{itemize} |
| \item \verb|"."| returns the next character, or \nil\ on end of file. |
| \item \verb|".*"| reads the whole file. |
| \item \verb|"[^\n]*{\n}"| returns the next line |
| (skipping the end of line), or \nil\ on end of file. |
| This is the default pattern. |
| \item \verb|"{%s*}%S%S*"| returns the next word |
| (maximal sequence of non white-space characters), |
| or \nil\ on end of file. |
| \item \verb|"{%s*}[+-]?%d%d*"| returns the next integer |
| or \nil\ if the next characters do not conform to an integer format. |
| \end{itemize} |
| |
| \subsubsection*{\ff{\tt write (value1, ...)}}\Deffunc{write} |
| |
| This function writes the value of each of its arguments to the |
| current output file. |
| The arguments must be strings or numbers. |
| To write other values, |
| use \verb|tostring| before \verb|write|. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff{\tt date ([format])}}\Deffunc{date} |
| |
| This function returns a string containing date and time |
| formatted according to the given string \verb'format', |
| following the same rules of the ANSI C function \verb'strftime'. |
| When called without arguments, |
| it returns a reasonable date and time representation that depends on |
| the host system. |
| |
| \subsubsection*{\ff{\tt exit ([code])}}\Deffunc{exit} |
| |
| This function calls the C function \verb-exit-, |
| with an optional \verb-code-, |
| to terminate the program. |
| The default value for \verb-code- is 1. |
| |
| \subsubsection*{\ff{\tt getenv (varname)}}\Deffunc{getenv} |
| |
| Returns the value of the environment variable \verb|varname|, |
| or \nil\ if the variable is not defined. |
| |
| \subsubsection*{\ff{\tt execute (command)}}\Deffunc{execute} |
| |
| This function is equivalent to the C function \verb|system|. |
| It passes \verb|command| to be executed by an operating system shell. |
| It returns an error code, which is system-dependent. |
| |
| |
| \section{The Debugger Interface} \label{debugI} |
| |
| Lua has no built-in debugging facilities. |
| Instead, it offers a special interface, |
| by means of functions and {\em hooks}, |
| which allows the construction of different |
| kinds of debuggers, profilers, and other tools |
| that need ``inside information'' from the interpreter. |
| This interface is declared in the header file \verb'luadebug.h'. |
| |
| \subsection{Stack and Function Information} |
| |
| The main function to get information about the interpreter stack |
| is |
| \begin{verbatim} |
| lua_Function lua_stackedfunction (int level); |
| \end{verbatim} |
| It returns a handle (\verb'lua_Function') to the {\em activation record\/} |
| of the function executing at a given level. |
| Level 0 is the current running function, |
| while level $n+1$ is the function that has called level $n$. |
| When called with a level greater than the stack depth, |
| \verb'lua_stackedfunction' returns \verb'LUA_NOOBJECT'. |
| |
| The type \verb'lua_Function' is just another name |
| to \verb'lua_Object'. |
| Although, in this library, |
| a \verb'lua_Function' can be used wherever a \verb'lua_Object' is required, |
| when a parameter has type \verb'lua_Function' |
| it accepts only a handle returned by |
| \verb'lua_stackedfunction'. |
| |
| Three other functions produce extra information about a function: |
| \begin{verbatim} |
| void lua_funcinfo (lua_Object func, char **filename, int *linedefined); |
| int lua_currentline (lua_Function func); |
| char *lua_getobjname (lua_Object o, char **name); |
| \end{verbatim} |
| \verb'lua_funcinfo' gives the file name and the line where the |
| given function has been defined. |
| If the ``function'' is in fact the main code of a chunk, |
| then \verb'linedefined' is 0. |
| If the function is a C function, |
| then \verb'linedefined' is -1, and \verb'filename' is \verb'"(C)"'. |
| |
| The function \verb'lua_currentline' gives the current line where |
| a given function is executing. |
| It only works if the function has been compiled with debug |
| information \see{pragma}. |
| When no line information is available, it returns -1. |
| |
| Function \verb'lua_getobjname' tries to find a reasonable name for |
| a given function. |
| Because functions in Lua are first class values, |
| they do not have a fixed name: |
| Some functions may be the value of many global variables, |
| while others may be stored only in a table field. |
| Function \verb'lua_getobjname' first checks whether the given |
| function is a fallback. |
| If so, it returns the string \verb'"fallback"', |
| and \verb'name' is set to point to the fallback name. |
| Otherwise, if the given function is the value of a global variable, |
| then \verb'lua_getobjname' returns the string \verb'"global"', |
| and \verb'name' points to the variable name. |
| If the given function is neither a fallback nor a global variable, |
| then \verb'lua_getobjname' returns the empty string, |
| and \verb'name' is set to \verb'NULL'. |
| |
| \subsection{Manipulating Local Variables} |
| |
| The following functions allow the manipulation of the |
| local variables of a given activation record. |
| They only work if the function has been compiled with debug |
| information \see{pragma}. |
| \begin{verbatim} |
| lua_Object lua_getlocal (lua_Function func, int local_number, char **name); |
| int lua_setlocal (lua_Function func, int local_number); |
| \end{verbatim} |
| \verb|lua_getlocal| returns the value of a local variable, |
| and sets \verb'name' to point to the variable name. |
| \verb'local_number' is an index for local variables. |
| The first parameter has index 1, and so on, until the |
| last active local variable. |
| When called with a \verb'local_number' greater than the |
| number of active local variables, |
| or if the activation record has no debug information, |
| \verb'lua_getlocal' returns \verb'LUA_NOOBJECT'. |
| Formal parameters are the first local variables. |
| |
| The function \verb'lua_setlocal' sets the local variable |
| %%LHF: please, lua_setglobal! |
| \verb'local_number' to the value previously pushed on the stack |
| \see{valuesCLua}. |
| If the function succeeds, then it returns 1. |
| If \verb'local_number' is greater than the number |
| of active local variables, |
| or if the activation record has no debug information, |
| then this function fails and returns 0. |
| |
| \subsection{Hooks} |
| |
| The Lua interpreter offers two hooks for debugging purposes: |
| \begin{verbatim} |
| typedef void (*lua_CHFunction) (lua_Function func, char *file, int line); |
| extern lua_CHFunction lua_callhook; |
| |
| typedef void (*lua_LHFunction) (int line); |
| extern lua_LHFunction lua_linehook; |
| \end{verbatim} |
| The first one is called whenever the interpreter enters or leaves a |
| function. |
| When entering a function, |
| its parameters are a handle to the function activation record, |
| plus the file and the line where the function is defined (the same |
| information which is provided by \verb'lua_funcinfo'); |
| when leaving a function, \verb'func' is \verb'LUA_NOOBJECT', |
| \verb'file' is \verb'"(return)"', and \verb'line' is 0. |
| |
| The other hook is called every time the interpreter changes |
| the line of code it is executing. |
| Its only parameter is the line number |
| (the same information which is provided by the call |
| \verb'lua_currentline(lua_stackedfunction(0))'). |
| This second hook is only called if the active function |
| has been compiled with debug information \see{pragma}. |
| |
| A hook is disabled when its value is \verb|NULL|, |
| which is the initial value of both hooks. |
| |
| |
| |
| \section{\Index{Lua Stand-alone}} \label{lua-sa} |
| |
| Although Lua has been designed as an extension language, |
| the language can also be used as a stand-alone interpreter. |
| An implementation of such an interpreter, |
| called simply \verb|lua|, |
| is provided with the standard distribution. |
| This program can be called with any sequence of the following arguments: |
| \begin{description} |
| \item[{\tt -v}] prints version information. |
| \item[{\tt -}] runs interactively, accepting commands from standard input |
| until an \verb|EOF|. |
| \item[{\tt -e stat}] executes \verb|stat| as a Lua chunk. |
| \item[{\tt var=exp}] executes \verb|var=exp| as a Lua chunk. |
| \item[{\tt filename}] executes file \verb|filename| as a Lua chunk. |
| \end{description} |
| All arguments are handled in order. |
| For instance, an invocation like |
| \begin{verbatim} |
| $ lua - a=1 prog.lua |
| \end{verbatim} |
| will first interact with the user until an \verb|EOF|, |
| then will set \verb'a' to 1, |
| and finally will run file \verb'prog.lua'. |
| |
| Please notice that the interaction with the shell may lead to |
| unintended results. |
| For instance, a call like |
| \begin{verbatim} |
| $ lua a="name" prog.lua |
| \end{verbatim} |
| will {\em not\/} set \verb|a| to the string \verb|"name"|. |
| Instead, the quotes will be handled by the shell, |
| lua will get only \verb'a=name' to run, |
| and \verb'a' will finish with \nil, |
| because the global variable \verb|name| has not been initialized. |
| Instead, one should write |
| \begin{verbatim} |
| $ lua 'a="name"' prog.lua |
| \end{verbatim} |
| |
| \section*{Acknowledgments} |
| |
| The authors would like to thank CENPES/PETROBR\'AS which, |
| jointly with \tecgraf, used extensively early versions of |
| this system and gave valuable comments. |
| The authors would also like to thank Carlos Henrique Levy, |
| who found the name of the game. |
| Lua means {\em moon\/} in Portuguese. |
| |
| |
| |
| \appendix |
| |
| \section*{Incompatibilities with Previous Versions} |
| |
| Although great care has been taken to avoid incompatibilities with |
| the previous public versions of Lua, |
| some differences had to be introduced. |
| Here is a list of all these incompatibilities. |
| |
| \subsection*{Incompatibilities with \Index{version 2.4}} |
| The whole I/O facilities have been rewritten. |
| We strongly encourage programmers to adapt their code |
| to this new version. |
| However, we are keeping the old version of the libraries |
| in the distribution, |
| to allow a smooth transition. |
| The incompatibilities between the new and the old libraries are: |
| \begin{itemize} |
| \item The format facility of function \verb'write' has been supersed by |
| function \verb'format'; |
| therefore this facility has been dropped. |
| \item Function \verb'read' now uses {\em read patterns\/} to specify |
| what to read; |
| this is incompatible with the old format options. |
| \item Function \verb'strfind' now accepts patterns, |
| so it may have a different behavior when the pattern includes |
| special characters. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 2.2}} |
| \begin{itemize} |
| \item |
| Functions \verb'date' and \verb'time' (from \verb'iolib') |
| have been superseded by the new, more powerful version of function \verb'date'. |
| \item |
| Function \verb'append' (from \verb'iolib') now returns 1 whenever it succeeds, |
| whether the file is new or not. |
| \item |
| Function \verb'int2str' (from \verb'strlib') has been superseded by new |
| function \verb'format', with parameter \verb'"%c"'. |
| \item |
| The API lock mechanism has been superseded by the reference mechanism. |
| However, \verb-lua.h- provides compatibility macros, |
| so there is no need to change programs. |
| \item |
| The API function \verb'lua_pushliteral' now is just a macro to |
| \verb'lua_pushstring'. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 2.1}} |
| \begin{itemize} |
| \item |
| The function \verb'type' now returns the string \verb'"function"' |
| both for C and Lua functions. |
| Because Lua functions and C functions are compatible, |
| this behavior is usually more useful. |
| When needed, the second result of function {\tt type} may be used |
| to distinguish between Lua and C functions. |
| \item |
| A function definition only assigns the function value to the |
| given variable at execution time. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 1.1}} |
| \begin{itemize} |
| \item |
| The equality test operator now is denoted by \verb'==', |
| instead of \verb'='. |
| \item |
| The syntax for table construction has been greatly simplified. |
| The old \verb'@(size)' has been substituted by \verb'{}'. |
| The list constructor (formerly \verb'@[...]') and the record |
| constructor (formerly \verb'@{...}') now are both coded like |
| \verb'{...}'. |
| When the construction involves a function call, |
| like in \verb'@func{...}', |
| the new syntax does not use the \verb'@'. |
| More important, {\em a construction function must now |
| explicitly return the constructed table}. |
| \item |
| The function \verb'lua_call' no longer has the parameter \verb'nparam'. |
| \item |
| The function \verb'lua_pop' is no longer available, |
| since it could lead to strange behavior. |
| In particular, |
| to access results returned from a Lua function, |
| the new macro \verb|lua_getresult| should be used. |
| \item |
| The old functions \verb'lua_storefield' and \verb'lua_storeindexed' |
| have been replaced by |
| \begin{verbatim} |
| int lua_storesubscript (void); |
| \end{verbatim} |
| with the parameters explicitly pushed on the stack. |
| \item |
| The functionality of the function \verb'lua_errorfunction' has been |
| replaced by the {\em fallback\/} mechanism \see{error}. |
| \item |
| When calling a function from the Lua library, |
| parameters passed through the stack |
| must be pushed just before the corresponding call, |
| with no intermediate calls to Lua. |
| Special care should be taken with macros like |
| \verb'lua_getindexed' and \verb'lua_getfield'. |
| \end{itemize} |
| |
| \newcommand{\indexentry}[2]{\item {#1} #2} |
| %\catcode`\_=12 |
| \begin{theindex} |
| \input{manual.id} |
| \end{theindex} |
| |
| |
| \end{document} |