| % $Id: manual.tex,v 1.24 1996/11/14 17:45:37 roberto Exp roberto $ |
| |
| \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: 1996/11/14 17:45:37 $} |
| |
| \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 \Version\ of the Lua programming language and |
| the API that allows interaction between Lua programs and their host C programs. |
| The document 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 \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. |
| 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 intended to be used as a configuration language for any |
| program that needs one. |
| Lua has been designed and implemented by |
| W.~Celes, 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 |
| 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 ends with a 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 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, 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. |
| |
| \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.}. |
| |
| \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. |
| 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. |
| |
| |
| |
| \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}. |
| The conventional commands include |
| assignment, control structures and procedure calls. |
| Non-conventional commands include table constructors |
| (Section~\ref{tableconstructor}), |
| and local variable declarations (Section~\ref{localvar}). |
| |
| \subsubsection{Blocks} |
| A \Index{block} is a list of statements, which is 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 can return any value. |
| All values different from \nil\ are considered true; |
| \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}% |
| Eventual returned values are thrown away. |
| Function calls are explained in Section \ref{functioncall}. |
| |
| \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 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'+', \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}, |
| then 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 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'=='). |
| |
| 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}). |
| |
| \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 indexes, |
| starting with 1. |
| For example: |
| \begin{verbatim} |
| a = {"v1", "v2", 34} |
| \end{verbatim} |
| is roughly 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 roughly 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. |
| 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. |
| 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'. |
| |
| 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 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 indexed 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. |
| 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. |
| \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. |
| |
| 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', 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. |
| For more information about an error, |
| the Lua program 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 also 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 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 references to Lua Objects. |
| \end{enumerate} |
| All API functions are declared in the header file \verb'lua.h'. |
| |
| \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' (0), |
| executes the {\tt 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}). |
| |
| \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 |
| \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 of no significance. |
| |
| 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. |
| 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 and 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, |
| \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 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_pushcfunction}\Deffunc{lua_pushusertag} |
| \Deffunc{lua_pushuserdata} |
| \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); |
| \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 the Lua stack, |
| where it can be assigned to a Lua variable, |
| passed as parameter to a Lua function, etc. \label{pushing} |
| |
| User data can have different tags, |
| whose semantics are defined by 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. |
| |
| 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 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 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 corresponding fallback is called. |
| |
| 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 corresponding fallback is called if needed. |
| |
| Finally, the function |
| \Deffunc{lua_createtable} |
| \begin{verbatim} |
| lua_Object lua_createtable (void); |
| \end{verbatim} |
| creates and returns a new table. |
| |
| {\em Please Notice:\/} |
| Most functions from the Lua library receive parameters through Lua's stack. |
| 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]'. |
| 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} |
| The functions \verb|lua_getnumber|, \verb|lua_getstring|, |
| \verb|lua_getuserdata|, and \verb|lua_getcfunction|, |
| plus the family \verb|lua_is*|, |
| are safe to be called without modifying the stack. |
| |
| \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 |
| \verb'LUA_NOOBJECT'\Deffunc{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{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}: |
| that 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'. |
| |
| |
| |
| \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. |
| 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 separated C modules. |
| Currently there are three standard libraries: |
| \begin{itemize} |
| \item string manipulation; |
| \item mathematical functions (sin, cos, 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. |
| |
| \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. |
| |
| \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 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*{\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. |
| See Section \ref{exnext} for an example of the use of this function. |
| |
| \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. |
| |
| \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. |
| |
| \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. |
| |
| \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. |
| |
| \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 has position 1. |
| See Page~\pageref{pm} for an explanation about patterns, |
| and Section~\ref{exstring} for some examples on string manipulation |
| in Lua. |
| |
| \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, it returns the indexes 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. |
| |
| \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, 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, this function is called every time a |
| match occurs, with all captured substrings as parameters. |
| If the value returned by this function is a string, |
| 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} |
| may return the string: |
| \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}. |
| \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 a single character class, |
| or a character class followed by \verb'*' or by \verb'?'. |
| A single character class matches any single character in the class. |
| A character class followed by \verb'*' matches 0 or more repetitions |
| of characters in the class. |
| A character class followed by \verb'?' matches 0 or one occurrence |
| of a character in the class. |
| A pattern item may also has the form \verb'%n', |
| for \verb-n- between 1 and 9; |
| such item matches a sub-string equal to the n-th captured string. |
| |
| \paragraph{Pattern:} |
| a \Def{pattern} is a sequence of pattern items. |
| Any repetition item (\verb'*') inside a pattern will always |
| match the longest possible sequence. |
| 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. |
| |
| 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 {\em captured} for future use. |
| Captures are numbered according to their left parentheses. |
| |
| \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} |
| \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 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 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 \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 *|). |
| 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. |
| |
| {\em System dependent:} if \verb'filename' starts with a \verb'|', |
| then a \Index{piped input} is open, via function \IndexVerb{popen}. |
| |
| \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 *|). |
| 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} |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| {\em System dependent:} if \verb'filename' starts with a \verb'|', |
| then a \Index{piped output} is open, via function \IndexVerb{popen}. |
| |
| \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 a 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 \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, |
| 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 this behaviour is different from regular pattern matching, |
| where a \verb'*' expands to the maximum length {\em such that\/} |
| the rest of the pattern does not fail.} |
| |
| 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. |
| 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. |
| |
| \subsubsection*{\ff{\tt exit ([code])}}\Deffunc{exit} |
| |
| This function calls the C function \verb-exit-, |
| with an optional \verb-code-, |
| to terminate the program. |
| |
| \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 implementation-defined. |
| |
| |
| \section{The Debugger Interface} \label{debugI} |
| |
| Lua has no built-in debugger 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, |
| a parameter \verb'lua_Function' 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 pre-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"', |
| while \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 pre-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} |
| The first one 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'. |
| |
| The function \verb'lua_setlocal' sets the local variable |
| \verb'local_number' to the value previously pushed on the stack |
| (\see{valuesCLua}). |
| If the function succeeds, then it returns 1. |
| If \verb'local_number' is greater than the number |
| of active local variables, |
| or if the activation record has no debug information, |
| then this function fails and returns 0. |
| |
| \subsection{Hooks} |
| |
| The Lua interpreter offers two hooks for debugging purposes: |
| \begin{verbatim} |
| typedef void (*lua_CHFunction) (lua_Function func, char *file, int line); |
| 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 pre-compiled with debug information (\see{pragma}). |
| |
| A hook is disabled when its value is NULL (0), |
| which is the initial value of both hooks. |
| |
| |
| \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{\Index{Data Structures}} |
| Tables are a strong unifying data constructor. |
| They directly implement a multitude of data types, |
| like ordinary arrays, records, sets, bags, and lists. |
| |
| Arrays need no explanations. |
| In Lua, it is conventional to start indices from 1, |
| but this is only a convention. |
| Arrays can be indexed by 0, negative numbers, or any other value (except \nil). |
| Records are also trivially implemented by the syntactic sugar |
| \verb'a.x'. |
| |
| The best way to implement a set is to store |
| its elements as indices of a table. |
| The statement \verb's = {}' creates an empty set \verb's'. |
| The statement \verb's[x] = 1' inserts the value of \verb'x' into |
| the set \verb's'. |
| The expression \verb's[x]' is true if and only if |
| \verb'x' belongs to \verb's'. |
| Finally, the statement \verb's[x] = nil' removes \verb'x' from \verb's'. |
| |
| Bags can be implemented similarly to sets, |
| but using the value associated to an element as its counter. |
| So, to insert an element, |
| the following code is enough: |
| \begin{verbatim} |
| if s[x] then s[x] = s[x]+1 else s[x] = 1 end |
| \end{verbatim} |
| and to remove an element: |
| \begin{verbatim} |
| if s[x] then s[x] = s[x]-1 end |
| if s[x] == 0 then s[x] = nil end |
| \end{verbatim} |
| |
| Lisp-like lists also have an easy implementation. |
| The ``cons'' of two elements \verb'x' and \verb'y' can be |
| created with the code \verb'l = {car=x, cdr=y}'. |
| The expression \verb'l.car' extracts the header, |
| while \verb'l.cdr' extracts the tail. |
| An alternative way is to create the list directly with \verb'l={x,y}', |
| and then to extract the header with \verb'l[1]' and |
| the tail with \verb'l[2]'. |
| |
| \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 \IndexVerb{clone} receives any table and returns a clone of it. |
| \begin{verbatim} |
| function clone (t) -- t is a table |
| local new_t = {} -- create 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 white-spaces at the beginning |
| and end of a string. |
| \begin{verbatim} |
| function trim(s) |
| local _, i = strfind(s, '^ *') |
| local f, __ = strfind(s, ' *$') |
| return strsub(s, i+1, f-1) |
| end |
| \end{verbatim} |
| |
| The second example shows a function that eliminates all spaces |
| of a string. |
| \begin{verbatim} |
| function remove_blanks (s) |
| return gsub(s, "%s%s*", "") |
| end |
| \end{verbatim} |
| |
| |
| \subsection{\Index{Variable number of arguments}} |
| Lua does not provide any explicit mechanism to deal with |
| variable number of arguments in function calls. |
| However, one can use table constructors to simulate this mechanism. |
| As an example, suppose a function to concatenate all its arguments. |
| It could be written like |
| \begin{verbatim} |
| function concat (o) |
| local i = 1 |
| local s = '' |
| while o[i] do |
| s = s .. o[i] |
| i = i+1 |
| end |
| return s |
| end |
| \end{verbatim} |
| To call it, one uses a table constructor to join all arguments: |
| \begin{verbatim} |
| x = concat{"hello ", "john", " and ", "mary"} |
| \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(format('\n%s =', 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, 'q') |
| 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 that all indices are identifiers |
| (that is, the tables are being used as records), |
| then 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, 'q') |
| 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} |
| #include "lua.h" |
| |
| int lockedParentName; /* lock index for the string "parent" */ |
| int lockedOldIndex; /* previous fallback function */ |
| |
| void callOldFallback (lua_Object table, lua_Object index) |
| { |
| lua_Object oldIndex = lua_getref(lockedOldIndex); |
| lua_pushobject(table); |
| lua_pushobject(index); |
| lua_callfunction(oldIndex); |
| if (lua_getresult(1) != LUA_NOOBJECT) |
| lua_pushobject(lua_getresult(1)); /* return result */ |
| } |
| |
| 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_pushref(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_pushstring("parent"); |
| lockedParentName = lua_ref(1); |
| lua_pushobject(lua_setfallback("index", Index)); |
| lockedOldIndex = lua_ref(1); |
| \end{verbatim} |
| Notice how the string \verb'"parent"' is kept |
| locked in Lua for optimal performance. |
| |
| \subsection{\Index{Programming with Classes}} |
| There are many different ways to do object-oriented programming in Lua. |
| This section presents one possible way to |
| implement classes, |
| using the inheritance mechanism presented above. |
| {\em Please notice: the following examples only work |
| with the index fallback redefined according to |
| Section~\ref{exfallback}}. |
| |
| As one could expect, a good way to represent a class is |
| with a table. |
| This table will contain all instance methods of the class, |
| plus optional default values for instance variables. |
| An instance of a class has its \verb'parent' field pointing to |
| the class, |
| and so it ``inherits'' all methods. |
| |
| For instance, a class \verb'Point' can be described as in |
| Figure~\ref{Point}. |
| Function \verb'create' helps the creation of new points, |
| adding the parent field. |
| Function \verb'move' is an example of an instance method. |
| \begin{figure} |
| \Line |
| \begin{verbatim} |
| Point = {x = 0, y = 0} |
| |
| function Point:create (o) |
| o.parent = self |
| return o |
| end |
| |
| function Point:move (p) |
| self.x = self.x + p.x |
| self.y = self.y + p.y |
| end |
| |
| ... |
| |
| -- |
| -- creating points |
| -- |
| p1 = Point:create{x = 10, y = 20} |
| p2 = Point:create{x = 10} -- y will be inherited until it is set |
| |
| -- |
| -- example of a method invocation |
| -- |
| p1:move(p2) |
| \end{verbatim} |
| \caption{A Class {\tt Point}.\label{Point}} |
| \Line |
| \end{figure} |
| Finally, a subclass can be created as a new table, |
| with the \verb'parent' field pointing to its superclass. |
| It is interesting to notice how the use of \verb'self' in |
| method \verb'create' allows this method to work properly even |
| when inherited by a subclass. |
| As usual, a subclass may overwrite any inherited method with |
| its own version. |
| |
| \subsection{\Index{Modules}} |
| Here we explain one possible way to simulate modules in Lua. |
| The main idea is to use a table to store the module functions. |
| |
| A module should be written as a separate chunk, starting with: |
| \begin{verbatim} |
| if modulename then return end -- avoid loading twice the same module |
| modulename = {} -- create a table to represent the module |
| \end{verbatim} |
| After that, functions can be directly defined with the syntax |
| \begin{verbatim} |
| function modulename.foo (...) |
| ... |
| end |
| \end{verbatim} |
| |
| Any code that needs this module has only to execute |
| \verb'dofile("filename")', where \verb'filename' is the file |
| where the module is written. |
| After this, any function can be called with |
| \begin{verbatim} |
| modulename.foo(...) |
| \end{verbatim} |
| |
| If a module function is going to be used many times, |
| the program can give a local name to it. |
| Because functions are values, it is enough to write |
| \begin{verbatim} |
| localname = modulename.foo |
| \end{verbatim} |
| Finally, a module may be {\em opened}, |
| giving direct access to all its functions, |
| as shown in the code in Figure~\ref{openmod}. |
| \begin{figure} |
| \Line |
| \begin{verbatim} |
| function open (mod) |
| local n, f = next(mod, nil) |
| while n do |
| setglobal(n, f) |
| n, f = next(mod, n) |
| end |
| end |
| \end{verbatim} |
| \caption{Opening a module.\label{openmod}} |
| \Line |
| \end{figure} |
| |
| \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{\Index{Lua Stand-alone}} |
| |
| 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 handle 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. |
| 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 addapt 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 characteres. |
| \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} |
| |
| \pagebreak |
| \tableofcontents |
| |
| \end{document} |