| % $Id: manual.tex,v 2.11 1997/07/04 22:35:38 roberto Exp roberto $ |
| |
| \documentstyle[fullpage,11pt,bnf]{article} |
| |
| \newcommand{\See}[1]{Section~\ref{#1}} |
| \newcommand{\see}[1]{(see \See{#1})} |
| \newcommand{\M}[1]{\emph{#1}} |
| \newcommand{\T}[1]{{\tt #1}} |
| \newcommand{\Math}[1]{$#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]{\T{#1}\index{#1}} |
| \newcommand{\Def}[1]{\emph{#1}\index{#1}} |
| \newcommand{\Deffunc}[1]{\index{#1}} |
| |
| \newcommand{\ff}{$\bullet$\ } |
| |
| \newcommand{\Version}{3.0} |
| |
| \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@tecgraf.puc-rio.br |
| \vspace{2.0ex}\\ |
| %MCC 08/95 --- |
| \tecgraf\ --- Computer Science Department --- PUC-Rio |
| } |
| |
| \date{\small \verb$Date: 1997/07/04 22:35:38 $} |
| |
| \maketitle |
| |
| \thispagestyle{empty} |
| \pagestyle{empty} |
| |
| \begin{abstract} |
| \noindent |
| Lua is an extension programming language designed to be used |
| as a configuration language for any program that needs one. |
| This document describes version \Version\ of the Lua programming language and |
| the API that allows interaction between Lua programs and their host C programs. |
| \end{abstract} |
| |
| \vspace{4ex} |
| \begin{quotation} |
| \small |
| \begin{center}{\bf Sum\'ario}\end{center} |
| \vspace{1ex} |
| \noindent |
| Lua \'e uma linguagem de extens\~ao projetada para ser usada como |
| linguagem de configura\c{c}\~ao em qualquer programa que precise de |
| uma. |
| Este documento descreve a vers\~ao \Version\ da linguagem de |
| programa\c{c}\~ao Lua e a Interface de Programa\c{c}\~ao (API) que permite |
| a intera\c{c}\~ao entre programas Lua e programas C hospedeiros. |
| \end{quotation} |
| |
| |
| \vfill |
| \begin{quotation} |
| \noindent |
| \footnotesize |
| Copyright \copyright\ 1994--1997 TeCGraf, PUC-Rio. |
| Written by Waldemar Celes Filho, |
| Roberto Ierusalimschy, Luiz Henrique de Figueiredo. |
| All rights reserved. |
| % |
| Permission is hereby granted, without written agreement and without license or |
| royalty fees, to use, copy, modify, and distribute this software and its |
| documentation for any purpose, subject to the following conditions: |
| % |
| The above copyright notice and this permission notice shall appear in all |
| copies or substantial portions of this software. |
| % |
| The name ``Lua'' cannot be used for any modified form |
| of this software that does not originate from the authors. |
| Nevertheless, the name ``Lua'' may and should be |
| used to designate the language implemented and described in this package, |
| even if embedded in any other system, as long as its syntax and semantics |
| remain unchanged. |
| % |
| The authors specifically disclaim any warranties, including, |
| but not limited to, the implied warranties of merchantability |
| and fitness for a particular purpose. |
| The software provided hereunder is on an ``as is'' basis, and the |
| authors have no obligation to provide maintenance, support, updates, |
| enhancements, or modifications. |
| In no event shall TeCGraf, PUC-Rio, or the |
| authors be liable to any party for direct, indirect, special, incidental, or |
| consequential damages arising out of the use of this software and its |
| documentation. |
| \end{quotation} |
| \vfill |
| |
| \newpage |
| |
| \tableofcontents |
| |
| \newpage |
| \setcounter{page}{1} |
| \pagestyle{plain} |
| |
| |
| \section{Introduction} |
| |
| Lua is an extension programming language designed to support |
| general procedural programming with data description |
| facilities. |
| It is intended to be used as a light-weight, but powerful, |
| configuration language for any program that needs one. |
| Lua has been designed and implemented by |
| W.~Celes, |
| R.~Ierusalimschy and |
| L.~H.~de Figueiredo. |
| |
| Lua is implemented as a library, written in C. |
| Being an extension language, Lua has no notion of a ``main'' program: |
| it only works \emph{embedded} in a host client, |
| called the \emph{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 |
| a wide range of different domains, |
| thus creating customized programming languages sharing a syntactical framework. |
| |
| Lua is free-distribution software, |
| and provided as usual with no guarantees, |
| as stated in the copyright notice in the front page of this manual. |
| The implementation described in this manual is available |
| at the following URL's: |
| \begin{verbatim} |
| http://www.tecgraf.puc-rio.br/lua/ |
| ftp://ftp.tecgraf.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; |
| this default can be changed \see{tag-method}. |
| |
| The unit of execution of Lua is called a \Def{chunk}. |
| The syntax for chunks is: |
| \begin{Produc} |
| \produc{chunk}{\rep{stat \Or function} \opt{ret}} |
| \end{Produc}% |
| (As usual, \rep{\emph{a}} means 0 or more \emph{a}'s, |
| \opt{\emph{a}} means an optional \emph{a} and \oneormore{\emph{a}} means |
| one or more \emph{a}'s.) |
| |
| A chunk may contain statements and function definitions, |
| and may be in a file or in a string inside the host program. |
| A chunk may optionally end with a \verb|return| statement \see{return}. |
| When a chunk is executed, first all its functions and statements are compiled, |
| then the statements are executed in sequential order. |
| All modifications a chunk effects on the global environment persist |
| after its end. |
| Those include modifications to global variables |
| and definitions of new functions |
| (actually, a function definition is an |
| assignment to a global variable \see{TypesSec}). |
| |
| Chunks may be pre-compiled into binary form; |
| 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 and Tags}} \label{TypesSec} |
| |
| Lua is a dynamically typed language. |
| Variables do not have types; only values do. |
| Therefore, there are no type definitions in the language. |
| All values carry their own type. |
| Besides a type, all values also have a \Index{tag}. |
| |
| There are six \Index{basic types} in Lua: \Def{nil}, \Def{number}, |
| \Def{string}, \Def{function}, \Def{userdata}, and \Def{table}. |
| \emph{Nil} is the type of the value \nil, |
| whose main property is to be different from any other value. |
| \emph{Number} represents real (floating-point) numbers, |
| while \emph{string} has the usual meaning; |
| notice that Lua is \Index{eight-bit clean}, |
| so strings can have ISO characters. |
| The function \verb|type| returns a string describing the type |
| of a given value \see{pdf-type}. |
| |
| 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. |
| They can be distinguished by their tags: |
| all Lua functions have the same tag, |
| and all C functions have the same tag, |
| which is different from the tag of a Lua function. |
| |
| The type \emph{userdata} is provided to allow |
| arbitrary \Index{C pointers} to be stored in Lua variables. |
| It corresponds to a \verb|void*| and has no pre-defined operations in Lua, |
| besides assignment and equality test. |
| However, by using \emph{tag methods}, |
| the programmer may define operations for \emph{userdata} values |
| \see{tag-method}. |
| |
| The type \emph{table} implements \Index{associative arrays}, |
| that is, \Index{arrays} that can be indexed not only with numbers, |
| but with any value (except \nil). |
| 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 \see{func-def}. |
| |
| It is important to notice that tables are \emph{objects}, and not values. |
| Variables cannot contain tables, only \emph{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}. |
| |
| Tags are mainly used to select tag methods when |
| some events occur \see{tag-method}. |
| Each of the types nil, number and string has a different tag. |
| All values of each of these types have this same pre-defined tag. |
| Values of type function can have two different tags, |
| depending on whether they are Lua or C functions. |
| Finally, |
| values of type userdata and table can have |
| as many different tags as needed \see{tag-method}. |
| Tags are created with the function \verb|newtag|, |
| and the function \verb|tag| returns the tag of a given value. |
| To change the tag of a given table, |
| there is the function \verb|settag| \see{pdf-newtag}. |
| |
| |
| \section{The Language} |
| |
| This section describes the lexis, the syntax and the semantics of Lua. |
| |
| |
| \subsection{Lexical Conventions} \label{lexical} |
| |
| \Index{Identifiers} can be any string of letters, digits, and underscores, |
| not beginning with a digit. |
| The definition of letter depends on the current locale: |
| Any character considered alphabetic by the current locale |
| can be used in an identifier. |
| The following 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} |
| Lua is a case-sensitive language: |
| \T{and} is a reserved word, but \T{And} and \T{\'and} |
| (if the locale permits) are two other different identifiers. |
| |
| The following strings denote other \Index{tokens}: |
| \begin{verbatim} |
| ~= <= >= < > == = .. + - * / |
| % ( ) { } [ ] ; , . ... |
| \end{verbatim} |
| |
| \Index{Literal strings} can be delimited by matching single or double quotes, |
| and can contain the C-like escape sequences |
| \verb|'\n'|, \verb|'\t'| and \verb|'\r'|. |
| Literal strings can also be delimited by matching \verb|[[ ... ]]|. |
| Literals in this bracketed form may run for several lines, |
| may contain nested \verb|[[ ... ]]| pairs, |
| and do not interpret escape sequences. |
| This form is specially convenient for |
| handling strings that contain program pieces or |
| other quoted strings. |
| |
| \Index{Comments} start anywhere outside a string with a |
| double hyphen (\verb|--|) and run until the end of the line. |
| Moreover, |
| the first line of a chunk file is skipped if it starts with \verb|#|. |
| This facility allows the use of Lua as a script interpreter |
| in Unix systems \see{lua-sa}. |
| |
| \Index{Numerical constants} may be written with an optional decimal part, |
| and an optional decimal exponent. |
| Examples of valid numerical constants are: |
| \begin{verbatim} |
| 4 4.0 0.4 4.57e-3 0.3e12 |
| \end{verbatim} |
| |
| \subsection{The \Index{Pre-processor}} \label{pre-processor} |
| |
| All lines that start with a \verb|$| are handled by a pre-processor. |
| The \verb|$| can be followed by any of the following directives: |
| \begin{description} |
| \item[\T{debug}] --- turn on some debugging facilities \see{pragma}. |
| \item[\T{nodebug}] --- turn off some debugging facilities \see{pragma}. |
| \item[\T{if \M{cond}}] --- starts a conditional part. |
| If \M{cond} is false, then this part is skipped by the lexical analyzer. |
| \item[\T{ifnot \M{cond}}] --- starts a conditional part. |
| If \M{cond} is true, then this part is skipped by the lexical analyzer. |
| \item[\T{end}] --- ends a conditional part. |
| \item[\T{else}] --- starts an ``else'' conditional part, |
| switching the ``skip'' status. |
| \item[\T{endinput}] --- ends the lexical parse of the file. |
| \end{description} |
| |
| Directives can be freely nested. |
| Particularly, a \verb|$endinput| may occur inside a \verb|$if|; |
| in that case, even the matching \verb|$end| is not parsed. |
| |
| A \M{cond} part may be: |
| \begin{description} |
| \item[\T{nil}] --- always false. |
| \item[\T{1}] --- always true. |
| \item[\M{name}] --- true if the value of the |
| global variable \M{name} is different from \nil. |
| Notice that \M{name} is evaluated before the chunk starts its execution. |
| Therefore, actions in a chunk do not affect its own conditional directives. |
| \end{description} |
| |
| \subsection{\Index{Coercion}} \label{coercion} |
| |
| Lua provides some automatic conversions between values. |
| Any arithmetic operation applied to a string tries to convert |
| that string to a number, following the usual rules. |
| Conversely, whenever a number is used when a string is expected, |
| that number is converted to a string, according to the following rule: |
| if the number is an integer, it is written without exponent or decimal point; |
| otherwise, it is formatted following the \verb|%g| |
| conversion specification of the \verb|printf| function in the |
| standard C library. |
| For complete control on how numbers are converted to strings, |
| use the \verb|format| function \see{format}. |
| |
| |
| \subsection{\Index{Adjustment}} \label{adjust} |
| |
| Functions in Lua can return many values. |
| Because there are no type declarations, |
| the system does not know how many values a function will return, |
| or how many parameters it needs. |
| Therefore, sometimes, a list of values must be \emph{adjusted}, at run time, |
| to a given length. |
| If there are more values than are needed, then the last values are thrown away. |
| If there are more needs than values, then the list is extended with as |
| many \nil's as needed. |
| Adjustment occurs in multiple assignment and function calls. |
| |
| |
| \subsection{Statements} |
| |
| Lua supports an almost conventional set of \Index{statements}, |
| similar to those in Pascal or C. |
| The conventional commands include |
| assignment, control structures and procedure calls. |
| Non-conventional commands include table constructors |
| \see{tableconstructor}, |
| and local variable declarations \see{localvar}. |
| |
| \subsubsection{Blocks} |
| A \Index{block} is a list of statements, which are executed sequentially. |
| Any statement can be optionally followed by a semicolon: |
| \begin{Produc} |
| \produc{block}{\rep{stat sc} \opt{ret}} |
| \produc{sc}{\opt{\ter{;}}} |
| \end{Produc}% |
| For syntactic reasons, a \IndexVerb{return} statement can only be written |
| as the last statement of a block. |
| This restriction also avoids some ``statement not reached'' conditions. |
| |
| \subsubsection{\Index{Assignment}} \label{assignment} |
| The language allows \Index{multiple assignment}. |
| Therefore, the syntax for assignment |
| defines a list of variables on the left side, |
| and a list of expressions on the right side. |
| 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} |
| The two lists may have different lengths. |
| Before the assignment, the list of values is \emph{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}% |
| The \verb|var| should result in a table value, |
| where the field indexed by the expression value gets the assigned value. |
| |
| The meaning of assignments and evaluations of global variables and |
| indexed variables can be changed by tag methods \see{tag-method}. |
| Actually, |
| an assignment \verb|x = val|, where \verb|x| is a global variable, |
| is equivalent to a call \verb|setglobal('x', val)|; |
| an assignment \verb|t[i] = val| is equivalent to |
| \verb|settable_event(t, i, val)|. |
| See \See{tag-method} for a description of these functions. |
| (Function \verb|setglobal| is pre-defined in Lua. |
| Function \T{settable\_event} is used only for explanatory purposes.) |
| |
| The syntax \verb|var.NAME| is just syntactic sugar for |
| \verb|var["NAME"]|: |
| \begin{Produc} |
| \produc{var}{var \ter{.} name} |
| \end{Produc}% |
| |
| \subsubsection{Control Structures} |
| The \Index{condition expression} of a control structure may return any value. |
| All values different from \nil\ are considered true; |
| only \nil\ is considered false. |
| \T{if}'s, \T{while}'s and \T{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 \T{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} \opt{explist1} \opt{sc}} |
| \end{Produc} |
| |
| \subsubsection{Function Calls as Statements} \label{funcstat} |
| Because of possible side-effects, |
| function calls can be executed as statements: |
| \begin{Produc} |
| \produc{stat}{functioncall} |
| \end{Produc}% |
| In this case, returned values are thrown away. |
| Function calls are explained in Section~\ref{functioncall}. |
| |
| \subsubsection{Local Declarations} \label{localvar} |
| \Index{Local variables} may be declared anywhere inside a block. |
| Their scope begins after the declaration and lasts until the |
| end of the block. |
| The declaration may include an initial assignment: |
| \begin{Produc} |
| \produc{stat}{\rwd{local} declist \opt{init}} |
| \produc{declist}{name \rep{\ter{,} name}} |
| \produc{init}{\ter{=} explist1} |
| \end{Produc}% |
| If present, an initial assignment has the same semantics |
| of a multiple assignment. |
| Otherwise, all variables are initialized with \nil. |
| |
| |
| \subsection{\Index{Expressions}} |
| |
| \subsubsection{\Index{Simple Expressions}} |
| Simple expressions are: |
| \begin{Produc} |
| \produc{exp}{\ter{(} exp \ter{)}} |
| \produc{exp}{\rwd{nil}} |
| \produc{exp}{\ter{number}} |
| \produc{exp}{\ter{literal}} |
| \produc{exp}{var} |
| \end{Produc}% |
| Numbers (numerical constants) and |
| string literals are explained in Section~\ref{lexical}. |
| Variables are explained in Section~\ref{assignment}. |
| |
| An access to a global variable \verb|x| is equivalent to a |
| call \verb|getglobal('x')|; |
| an access to an indexed variable \verb|t[i]| is equivalent to |
| a call \verb|gettable_event(t, i)|. |
| See \See{tag-method} for a description of these functions. |
| (Function \verb|getglobal| is pre-defined in Lua. |
| Function \T{gettable\_event} is used only for explanatory purposes.) |
| |
| The non-terminal \M{exp1} is used to indicate that the values |
| returned by an expression must be adjusted to one single value: |
| \begin{Produc} |
| \produc{exp1}{exp} |
| \end{Produc} |
| |
| \subsubsection{Arithmetic Operators} |
| Lua supports the usual \Index{arithmetic operators}: |
| the binary \verb|+| (addition), |
| \verb|-| (subtraction), \verb|*| (multiplication), |
| \verb|/| (division) and \verb|^| (exponentiation), |
| and unary \verb|-| (negation). |
| If the operands are numbers, or strings that can be converted to |
| numbers, according to the rules given in Section~\ref{coercion}, |
| then all operations except exponentiation have the usual meaning. |
| Otherwise, an appropriate tag method is called \see{tag-method}. |
| An exponentiation always calls a tag method. |
| The standard mathematical library redefines this method for numbers, |
| 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\ 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, userdata and functions are compared by reference, |
| that is, two tables are considered equal only if they are the same table. |
| The operator \verb|~=| is exactly the negation of equality (\verb|==|). |
| Note that the conversion rules of Section~\ref{coercion} |
| \emph{do not} apply to equality comparisons. |
| Thus, \verb|"0"==0| evaluates to false. |
| |
| The other operators work as follows. |
| If both arguments are numbers, then they are compared as such. |
| Otherwise, if both arguments are strings, |
| their values are compared using lexicographical order. |
| Otherwise, the ``order'' tag method is called \see{tag-method}. |
| |
| \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 when 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 ``concat'' tag method is called \see{tag-method}. |
| |
| \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 \emph{lfieldlist1} is used to initialize lists. |
| \begin{Produc} |
| \produc{lfieldlist1}{exp \rep{\ter{,} exp} \opt{\ter{,}}} |
| \end{Produc}% |
| The expressions in the list are assigned to consecutive numerical indices, |
| starting with 1. |
| For example: |
| \begin{verbatim} |
| a = {"v1", "v2", 34} |
| \end{verbatim} |
| is essentially equivalent to: |
| \begin{verbatim} |
| temp = {} |
| temp[1] = "v1" |
| temp[2] = "v2" |
| temp[3] = 34 |
| a = temp |
| \end{verbatim} |
| |
| The form \emph{ffieldlist1} initializes other fields in a table: |
| \begin{Produc} |
| \produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}} |
| \produc{ffield}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp} |
| \end{Produc}% |
| For example: |
| \begin{verbatim} |
| a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} |
| \end{verbatim} |
| is essentially equivalent to: |
| \begin{verbatim} |
| temp = {} |
| temp[f(k)] = g(y) |
| temp.x = 1 -- or temp["x"] = 1 |
| temp.y = 3 -- or temp["y"] = 3 |
| temp[0] = b+c |
| a = temp |
| \end{verbatim} |
| An expression like \verb|{x = 1, y = 4}| is |
| in fact syntactic sugar for \verb|{["x"] = 1, ["y"] = 4}|. |
| |
| \subsubsection{Function Calls} \label{functioncall} |
| A \Index{function call} has the following syntax: |
| \begin{Produc} |
| \produc{functioncall}{var realParams} |
| \end{Produc}% |
| Here, \M{var} can be any variable (global, local, indexed, etc). |
| If its value has type \emph{function}, |
| then this function is called. |
| Otherwise, the ``function'' tag method is called, |
| having as first parameter the value of \M{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. |
| 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}, |
| then its return list is adjusted to~0, |
| thus discarding all returned values. |
| If the function is called in a place that needs a single value |
| (syntactically denoted by the non-terminal \M{exp1}), |
| then its return list is adjusted to~1, |
| thus discarding all returned values but the first one. |
| If the function is called in a place that can hold many values |
| (syntactically denoted by the non-terminal \M{exp}), |
| then no adjustment is made. |
| |
| |
| \subsection{\Index{Function Definitions}} \label{func-def} |
| |
| 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 \emph{function}, |
| into the variable \verb|var|. |
| It is in this sense that |
| a function definition is an assignment to a global variable. |
| |
| Parameters act as local variables, |
| initialized with the argument values. |
| \begin{Produc} |
| \produc{parlist1}{\ter{\ldots}} |
| \produc{parlist1}{name \rep{\ter{,} name} \opt{\ter{,} \ter{\ldots}}} |
| \end{Produc} |
| \label{vararg} |
| When a function is called, |
| the list of \Index{arguments} is adjusted to |
| the length of the list of parameters \see{adjust}, |
| unless the function is a \Def{vararg} function, |
| indicated by the dots (\ldots) at the end of its parameter list. |
| A vararg function does not adjust its argument list; |
| instead, it collects any extra arguments in an implicit parameter, |
| called \Def{arg}. |
| This parameter is always initialized as a table, |
| with a field \verb|n| with the number of extra arguments, |
| and the extra arguments at positions 1, 2, \ldots |
| |
| As an example, suppose definitions like: |
| \begin{verbatim} |
| function f(a, b) end |
| function g(a, b, ...) end |
| \end{verbatim} |
| Then, we have the following mapping from arguments to parameters: |
| \begin{verbatim} |
| CALL PARAMETERS |
| |
| f(3) a=3, b=nil |
| f(3, 4) a=3, b=4 |
| f(3, 4, 5) a=3, b=4 |
| |
| g(3) a=3, b=nil, arg={n=0} |
| g(3, 4) a=3, b=4, arg={n=0} |
| g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2} |
| \end{verbatim} |
| |
| 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{Tag Methods} \label{tag-method} |
| |
| Lua provides a powerful mechanism to extend its semantics, |
| called \Def{Tag Methods}. |
| A tag method (TM) is a programmer-defined function |
| that can be called at many key points of the evaluation of a program, |
| allowing a programmer to change the standard Lua behavior at these points. |
| Each of these points is called an \Def{event}. |
| |
| The tag method called for any specific event is selected |
| according to the tag of the values involved |
| in the event \see{TypesSec}. |
| The function \IndexVerb{settagmethod} changes the tag method |
| associated with a given pair \M{<tag, event>}. |
| Its first parameter is the tag, the second the event name |
| (a string, see below), |
| and the third parameter is the new method (a function), |
| or \nil\ to restore the default behavior. |
| The function returns the previous tag method. |
| Another function, \IndexVerb{gettagmethod}, |
| receives a tag and an event name and returns the |
| current method associated with the pair. |
| |
| Tag methods are called in the following events, |
| identified by the given names. |
| The semantics of tag methods is better explained by a Lua function |
| describing the behavior of the interpreter at each event. |
| The function not only shows when a tag method is called, |
| but also its arguments, its results and the default behavior. |
| Please notice that the code shown here is only illustrative; |
| the real behavior is hard coded in the interpreter, |
| and it is much more efficient than this simulation. |
| All functions used in these descriptions |
| (\verb|rawgetglobal|, \verb|tonumber|, \verb|call|, etc) |
| are described in \See{predefined}. |
| |
| \begin{description} |
| |
| \item[``add'':]\index{add event} |
| called when a \verb|+| operation is applied to non numerical operands. |
| |
| The function \verb|getbinmethod| defines how Lua chooses a tag method |
| for a binary operation. |
| First Lua tries the first operand. |
| If its tag does not define a tag method for the operation, |
| then Lua tries the second operand. |
| If it also fails, then it gets a tag method from tag~0: |
| \begin{verbatim} |
| function getbinmethod (op1, op2, event) |
| return gettagmethod(tag(op1), event) or |
| gettagmethod(tag(op2), event) or |
| gettagmethod(0, event) |
| end |
| \end{verbatim} |
| \begin{verbatim} |
| function add_event (op1, op2) |
| local o1, o2 = tonumber(op1), tonumber(op2) |
| if o1 and o2 then -- both operands are numeric |
| return o1+o2 -- '+' here is the primitive 'add' |
| else -- at least one of the operands is not numeric. |
| local tm = getbinmethod(op1, op2, "add") |
| if tm then |
| -- call the method with both operands and an extra |
| -- argument with the event name |
| return tm(op1, op2, "add") |
| else -- no tag method available: Default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``sub'':]\index{sub event} |
| called when a \verb|-| operation is applied to non numerical operands. |
| Behavior similar to \verb|"add"| event. |
| |
| \item[``mul'':]\index{mul event} |
| called when a \verb|*| operation is applied to non numerical operands. |
| Behavior similar to \verb|"add"| event. |
| |
| \item[``div'':]\index{div event} |
| called when a \verb|/| operation is applied to non numerical operands. |
| Behavior similar to \verb|"add"| event. |
| |
| \item[``pow'':]\index{pow event} |
| called when a \verb|^| operation is applied. |
| \begin{verbatim} |
| function pow_event (op1, op2) |
| local tm = getbinmethod(op1, op2, "pow") |
| if tm then |
| -- call the method with both operands and an extra |
| -- argument with the event name |
| return tm(op1, op2, "pow") |
| else -- no tag method available: Default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| \end{verbatim} |
| |
| \item[``unm'':]\index{unm event} |
| called when an unary \verb|-| operation is applied to a non numerical operand. |
| \begin{verbatim} |
| function unm_event (op) |
| local o = tonumber(op) |
| if o then -- operand is numeric |
| return -o -- '-' here is the primitive 'unm' |
| else -- the operand is not numeric. |
| -- Try to get a tag method from the operand; |
| -- if it does not have one, try a "global" one (tag 0) |
| local tm = gettagmethod(tag(op), "unm") or |
| gettagmethod(0, "unm") |
| if tm then |
| -- call the method with the operand, nil, and an extra |
| -- argument with the event name |
| return tm(op, nil, "unm") |
| else -- no tag method available: Default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``lt'':]\index{lt event} |
| called when a \verb|<| operation is applied to non numerical |
| or non string operands. |
| \begin{verbatim} |
| function lt_event (op1, op2) |
| if type(op1) == "number" and type(op2) == "number" then |
| return op1 < op2 -- numeric comparison |
| elseif type(op1) == "string" and type(op2) == "string" then |
| return op1 < op2 -- lexicographic comparison |
| else |
| local tm = getbinmethod(op1, op2, "lt") |
| if tm then |
| return tm(op1, op2, "lt") |
| else |
| error("unexpected type at comparison"); |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``gt'':]\index{gt event} |
| called when a \verb|>| operation is applied to non numerical |
| or non string operands. |
| Behavior similar to \verb|"lt"| event. |
| |
| \item[``le'':]\index{le event} |
| called when a \verb|<=| operation is applied to non numerical |
| or non string operands. |
| Behavior similar to \verb|"lt"| event. |
| |
| \item[``ge'':]\index{ge event} |
| called when a \verb|>=| operation is applied to non numerical |
| or non string operands. |
| Behavior similar to \verb|"lt"| event. |
| |
| \item[``concat'':]\index{concatenation event} |
| called when a concatenation is applied to non string operands. |
| \begin{verbatim} |
| function concat_event (op1, op2) |
| if (type(op1) == "string" or type(op1) == "number") and |
| (type(op2) == "string" or type(op2) == "number") then |
| return op1..op2 -- primitive string concatenation |
| else |
| local tm = getbinmethod(op1, op2, "concat") |
| if tm then |
| return tm(op1, op2, "concat") |
| else |
| error("unexpected type for concatenation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``index'':]\index{index event} |
| called when Lua tries to retrieve the value of an index |
| not present in a table. |
| See event \verb|"gettable"| for its semantics. |
| |
| \item[``getglobal'':]\index{getglobal event} |
| called whenever Lua accesses a global variable. |
| This method can only be set for \nil\ and for tags |
| created by \verb|newtag|. |
| \begin{verbatim} |
| function getglobal (varname) |
| local value = rawgetglobal(varname) |
| local tm = gettagmethod(tag(value), "getglobal") |
| if not tm then |
| return value |
| else |
| return tm(varname, value) |
| end |
| end |
| \end{verbatim} |
| Notice: the function \verb|getglobal| is pre-defined in Lua \see{predefined}. |
| |
| \item[``setglobal'':]\index{setglobal event} |
| called whenever Lua assigns to a global variable. |
| This method cannot be set for numbers, strings, and tables and |
| userdata with default tags. |
| \begin{verbatim} |
| function setglobal (varname, newvalue) |
| local oldvalue = rawgetglobal(varname) |
| local tm = gettagmethod(tag(oldvalue), "setglobal") |
| if not tm then |
| return rawsetglobal(varname, newvalue) |
| else |
| return tm(varname, oldvalue, newvalue) |
| end |
| end |
| \end{verbatim} |
| Notice: the function \verb|setglobal| is pre-defined in Lua \see{predefined}. |
| |
| \item[``gettable'':]\index{gettable event} |
| called whenever Lua accesses an indexed variable. |
| This method cannot be set for tables with default tag. |
| \begin{verbatim} |
| function gettable_event (table, index) |
| local tm = gettagmethod(tag(table), "gettable") |
| if tm then |
| return tm(table, index) |
| elseif type(table) ~= "table" then |
| error("indexed expression not a table"); |
| else |
| local v = rawgettable(table, index) |
| tm = gettagmethod(tag(table), "index") |
| if (v == nil) and tm then |
| return tm(table, index) |
| else |
| return v |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``settable'':]\index{settable event} |
| called when Lua assigns to an indexed variable. |
| This method cannot be set for tables with default tag. |
| \begin{verbatim} |
| function settable_event (table, index, value) |
| local tm = gettagmethod(tag(table), "settable") |
| if tm then |
| tm(table, index, value) |
| elseif type(table) ~= "table" then |
| error("indexed expression not a table") |
| else |
| rawsettable(table, index, value) |
| end |
| end |
| \end{verbatim} |
| |
| \item[``function'':]\index{function event} |
| called when Lua tries to call a non function value. |
| \begin{verbatim} |
| function function_event (func, ...) |
| if type(func) == "function" then |
| return call(func, arg) |
| else |
| local tm = gettagmethod(tag(func), "function") |
| if tm then |
| local i = arg.n |
| while i > 0 do |
| arg[i+1] = arg[i] |
| i = i-1 |
| end |
| arg.n = arg.n+1 |
| arg[1] = func |
| return call(tm, arg) |
| else |
| error("call expression not a function") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``gc'':]\index{gc event} |
| called when Lua is garbage collecting an object. |
| This method cannot be set for strings, numbers, functions, |
| and userdata with default tag. |
| For each object to be collected, |
| Lua does the equivalent of the following function: |
| \begin{verbatim} |
| function gc_event (obj) |
| local tm = gettagmethod(tag(obj), "gc") |
| if tm then |
| tm(obj) |
| end |
| end |
| \end{verbatim} |
| Moreover, at the end of a garbage collection cycle, |
| Lua does the equivalent of the call \verb|gc_event(nil)|. |
| |
| \end{description} |
| |
| |
| |
| \subsection{Error Handling} \label{error} |
| |
| Because Lua is an extension language, |
| all Lua actions start from C code calling a function from the Lua library. |
| Whenever an error occurs during Lua compilation or execution, |
| the \Def{error method} is called, |
| and then the corresponding function from the library |
| (\verb|lua_dofile|, \verb|lua_dostring|, or \verb|lua_callfunction|) |
| is terminated returning an error condition. |
| |
| The only argument to the error method is a string |
| describing the error. |
| The default method prints this message in \verb|stderr|. |
| If needed, it is possible to change the error method with the |
| function \verb|seterrormethod|, |
| which gets the new error handler as its only parameter |
| \see{pdf-seterrormethod}. |
| The standard I/O library uses this facility to redefine the error method, |
| using the debug facilities \see{debugI}, |
| in order to print some extra information, |
| like the call stack. |
| |
| To provide more information about errors, |
| Lua programs should include the compilation pragma \verb|$debug|. |
| \index{debug pragma}\label{pragma} |
| When an error occurs in a program compiled with this option, |
| the I/O error routine is able to print the number of the |
| lines where the calls (and the error) were made. |
| |
| 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 Lua library. |
| The API functions can be classified in the following categories: |
| \begin{enumerate} |
| \item exchanging values between C and Lua; |
| \item executing Lua code; |
| \item manipulating (reading and writing) Lua objects; |
| \item calling Lua functions; |
| \item C functions to be called by Lua; |
| \item manipulating references to Lua Objects. |
| \end{enumerate} |
| All API functions and related types and constants |
| are declared in the header file \verb|lua.h|. |
| |
| \subsection{Exchanging Values between C and Lua} \label{valuesCLua} |
| Because Lua has no static type system, |
| all values passed between Lua and C have type |
| \verb|lua_Object|\Deffunc{lua_Object}, |
| which works like an abstract type in C that can hold any Lua value. |
| Values of type \verb|lua_Object| have no meaning outside Lua; |
| for instance, |
| the comparison of two \verb|lua_Object's| is undefined. |
| |
| To check the type of a \verb|lua_Object|, |
| the following functions are available: |
| \Deffunc{lua_isnil}\Deffunc{lua_isnumber}\Deffunc{lua_isstring} |
| \Deffunc{lua_istable}\Deffunc{lua_iscfunction}\Deffunc{lua_isuserdata} |
| \Deffunc{lua_isfunction} |
| \begin{verbatim} |
| int lua_isnil (lua_Object object); |
| int lua_isnumber (lua_Object object); |
| int lua_isstring (lua_Object object); |
| int lua_istable (lua_Object object); |
| int lua_isfunction (lua_Object object); |
| int lua_iscfunction (lua_Object object); |
| int lua_isuserdata (lua_Object object); |
| \end{verbatim} |
| All macros return 1 if the object is compatible with the given type, |
| and 0 otherwise. |
| The function \verb|lua_isnumber| accepts numbers and numerical strings, |
| whereas |
| \verb|lua_isstring| accepts strings and numbers \see{coercion}, |
| and \verb|lua_isfunction| accepts Lua and C functions. |
| |
| To check the tag of a \verb|lua_Object|, |
| the following function is available: |
| \Deffunc{lua_tag} |
| \begin{verbatim} |
| int lua_tag (lua_Object object); |
| \end{verbatim} |
| |
| 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} |
| float lua_getnumber (lua_Object object); |
| char *lua_getstring (lua_Object object); |
| lua_CFunction lua_getcfunction (lua_Object object); |
| void *lua_getuserdata (lua_Object object); |
| \end{verbatim} |
| |
| \verb|lua_getnumber| converts a \verb|lua_Object| to a floating-point number. |
| This \verb|lua_Object| must be a number or a string convertible to number |
| \see{coercion}; otherwise, the function returns~0. |
| |
| \verb|lua_getstring| converts a \verb|lua_Object| to a string (\verb|char*|). |
| This \verb|lua_Object| must be a string or a number; |
| otherwise, the function returns~0 (the \verb|NULL| pointer). |
| This function does not create a new string, |
| but returns a pointer to a string inside the Lua environment. |
| Because Lua has garbage collection, |
| there is no guarantee that such pointer will be valid after the block ends |
| (see below). |
| |
| \verb|lua_getcfunction| converts a \verb|lua_Object| to a C function. |
| This \verb|lua_Object| must have type \emph{CFunction}; |
| otherwise, the function returns 0 (the \verb|NULL| pointer). |
| The type \verb|lua_CFunction| is explained in Section~\ref{LuacallC}. |
| |
| \verb|lua_getuserdata| converts a \verb|lua_Object| to \verb|void*|. |
| This \verb|lua_Object| must have type \emph{userdata}; |
| otherwise, the function returns 0 (the \verb|NULL| pointer). |
| |
| Because Lua has automatic memory management and garbage collection, |
| a \verb|lua_Object| has a limited scope, |
| and is only valid inside the \emph{block} where it was created. |
| A C function called from Lua is a block, |
| and its parameters are valid only until its end. |
| It is good programming practice to convert Lua objects to C values |
| as soon as they are available, |
| and never to store \verb|lua_Object|s in C global variables. |
| |
| A garbage collection cycle can be forced by: |
| \Deffunc{lua_collectgarbage} |
| \begin{verbatim} |
| long lua_collectgarbage (long limit); |
| \end{verbatim} |
| This function returns the number of objects collected. |
| The argument \verb|limit| makes the next cycle occur only |
| when that number of new objects have been created. |
| If \verb|limit|=0, then Lua uses an adaptable heuristics to set this limit. |
| |
| |
| All communication between Lua and C is done through two |
| abstract data types, called \Def{lua2C} and \Def{C2lua}. |
| The first one, as the name implies, is used to pass values |
| from Lua to C: parameters when Lua calls C and results when C calls Lua. |
| The structure C2lua is used in the reverse direction: |
| parameters when C calls Lua and results when Lua calls C. |
| |
| The structure lua2C is an abstract array, |
| which can be indexed with the function: |
| \Deffunc{lua_lua2C} |
| \begin{verbatim} |
| lua_Object lua_lua2C (int number); |
| \end{verbatim} |
| where \verb|number| starts with 1. |
| When called with a number larger than the array size, |
| this function returns \verb|LUA_NOOBJECT|\Deffunc{LUA_NOOBJECT}. |
| In this way, it is possible to write C functions that receive |
| a variable number of parameters, |
| and to call Lua functions that return a variable number of results. |
| Notice that the structure lua2C cannot be directly modified by C code. |
| |
| The second structure, C2lua, is a stack. |
| Pushing elements into this stack |
| is done with the following functions: |
| \Deffunc{lua_pushnumber}\Deffunc{lua_pushstring} |
| \Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag} |
| \Deffunc{lua_pushnil}\Deffunc{lua_pushobject} |
| \Deffunc{lua_pushuserdata}\label{pushing} |
| \begin{verbatim} |
| void lua_pushnumber (double n); |
| void lua_pushstring (char *s); |
| void lua_pushcfunction (lua_CFunction f); |
| void lua_pushusertag (void *u, int tag); |
| void lua_pushnil (void); |
| void lua_pushobject (lua_Object object); |
| \end{verbatim} |
| All of them receive a C value, |
| convert it to a corresponding \verb|lua_Object|, |
| and leave the result on the top of C2lua. |
| The function |
| \Deffunc{lua_pop} |
| \begin{verbatim} |
| lua_Object lua_pop (void); |
| \end{verbatim} |
| returns a reference to the object at the top of the C2lua stack, |
| and pops it. |
| |
| As a general rule, all API functions pop from the stack |
| all elements that they use. |
| |
| Because userdata are objects, |
| the function \verb|lua_pushusertag| may create a new userdata. |
| If Lua has a userdata with the given value (\verb|void*|) and tag, |
| that userdata is pushed. |
| Otherwise, a new userdata is created, with the given value and tag. |
| If this function is called with |
| \verb|tag|=\verb|LUA_ANYTAG|\Deffunc{LUA_ANYTAG}, |
| then Lua will try to find any userdata with the given value, |
| no matter its tag. |
| If there is no userdata with that value, then a new one is created, |
| with tag=0. |
| |
| Userdata can have different tags, |
| whose semantics are only known to the host program. |
| Tags are created with the function: |
| \Deffunc{lua_newtag} |
| \begin{verbatim} |
| int lua_newtag (void); |
| \end{verbatim} |
| The function \verb|lua_settag| changes the tag of |
| the object on the top of C2lua (and pops it); |
| the object must be a userdata or a table. |
| \Deffunc{lua_settag} |
| \begin{verbatim} |
| void lua_settag (int tag); |
| \end{verbatim} |
| \verb|tag| must be a value created with \verb|lua_newtag|. |
| |
| When C code calls Lua repeatedly, as in a loop, |
| objects returned by these calls can accumulate, |
| and may cause a stack overflow. |
| To avoid this, |
| nested blocks can be defined with the functions: |
| \begin{verbatim} |
| void lua_beginblock (void); |
| void lua_endblock (void); |
| \end{verbatim} |
| After the end of the block, |
| all \verb|lua_Object|'s created inside it are released. |
| The use of explicit nested blocks is strongly encouraged. |
| |
| \subsection{Executing Lua Code} |
| A host program can execute Lua chunks written in a file or in a string |
| using the following functions: |
| \Deffunc{lua_dofile}\Deffunc{lua_dostring} |
| \begin{verbatim} |
| int lua_dofile (char *filename); |
| int lua_dostring (char *string); |
| \end{verbatim} |
| Both functions return an error code: |
| 0, in case of success; non zero, in case of errors. |
| More specifically, \verb|lua_dofile| returns 2 if for any reason |
| it could not open the file. |
| The function \verb|lua_dofile|, if called with argument \verb|NULL|, |
| executes the \verb|stdin| stream. |
| Function \verb|lua_dofile| is also able to execute pre-compiled chunks. |
| It automatically detects whether the file is text or binary, |
| and loads it accordingly (see program \IndexVerb{luac}). |
| |
| These functions return, in structure lua2C, |
| any values eventually returned by the chunks. |
| They also empty the stack C2lua. |
| |
| |
| \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, this function may trigger a tag method. |
| To read the real value of any global variable, |
| without invoking any tag method, |
| this function has a \emph{raw} version: |
| \Deffunc{lua_rawgetglobal} |
| \begin{verbatim} |
| lua_Object lua_rawgetglobal (char *varname); |
| \end{verbatim} |
| |
| To store a value previously pushed onto C2lua in a global variable, |
| there is the function: |
| \Deffunc{lua_setglobal} |
| \begin{verbatim} |
| void lua_setglobal (char *varname); |
| \end{verbatim} |
| As in Lua, this function may trigger a tag method. |
| To set the real value of any global variable, |
| without invoking any tag method, |
| this function has a \emph{raw} version: |
| \Deffunc{lua_rawgetglobal} |
| \begin{verbatim} |
| void lua_rawsetglobal (char *varname); |
| \end{verbatim} |
| |
| Tables can also be manipulated via the API. |
| The function |
| \Deffunc{lua_gettable} |
| \begin{verbatim} |
| lua_Object lua_gettable (void); |
| \end{verbatim} |
| pops from the stack C2lua a table and an index, |
| and returns the contents of the table at that index. |
| As in Lua, this operation may trigger a tag method. |
| To get the real value of any table index, |
| without invoking any tag method, |
| this function has a \emph{raw} version: |
| \Deffunc{lua_rawgetglobal} |
| \begin{verbatim} |
| lua_Object lua_rawgettable (void); |
| \end{verbatim} |
| |
| To store a value in an index, |
| the program must push the table, the index, |
| and the value onto C2lua, |
| and then call the function: |
| \Deffunc{lua_settable} |
| \begin{verbatim} |
| void lua_settable (void); |
| \end{verbatim} |
| Again, the tag method for ``settable'' may be called. |
| To set the real value of any table index, |
| without invoking any tag method, |
| this function has a \emph{raw} version: |
| \Deffunc{lua_rawsettable} |
| \begin{verbatim} |
| void lua_rawsettable (void); |
| \end{verbatim} |
| |
| Finally, the function |
| \Deffunc{lua_createtable} |
| \begin{verbatim} |
| lua_Object lua_createtable (void); |
| \end{verbatim} |
| creates and returns a new, empty table. |
| |
| |
| \subsection{Calling Lua Functions} |
| Functions defined in Lua by a chunk executed with |
| \verb|dofile| or \verb|dostring| can be called from the host program. |
| This is done using the following protocol: |
| first, the arguments to the function are pushed onto C2lua |
| \see{pushing}, in direct order, i.e., the first argument is pushed first. |
| |
| Then, the function is called using |
| \Deffunc{lua_callfunction} |
| \begin{verbatim} |
| int lua_callfunction (lua_Object function); |
| \end{verbatim} |
| This function returns an error code: |
| 0, in case of success; non zero, in case of errors. |
| Finally, the results (a Lua function may return many values) |
| are returned in structure lua2C, |
| and can be retrieved with the macro \verb|lua_getresult|, |
| \Deffunc{lua_getresult} |
| which is just another name to the function \verb|lua_lua2C|. |
| Notice that the function \verb|lua_callfunction| |
| pops all elements from the C2lua stack. |
| |
| The following example shows how a C program may do the |
| equivalent to the Lua code: |
| \begin{verbatim} |
| a = f("how", t.x, 4) |
| \end{verbatim} |
| \begin{verbatim} |
| lua_pushstring("how"); /* 1st argument */ |
| lua_pushobject(lua_getglobal("t")); /* push value of global 't' */ |
| lua_pushstring("x"); /* push the string 'x' */ |
| lua_pushobject(lua_gettable()); /* push result of t.x (= t['x']) */ |
| lua_pushnumber(4); /* 3th argument */ |
| lua_callfunction(lua_getglobal("f")); /* call Lua function */ |
| lua_pushobject(lua_getresult(1)); /* push first result of the call */ |
| lua_setglobal("a"); /* sets global variable 'a' */ |
| \end{verbatim} |
| |
| Some special Lua functions have exclusive interfaces. |
| A C function can generate a Lua error calling the function |
| \Deffunc{lua_error} |
| \begin{verbatim} |
| void lua_error (char *message); |
| \end{verbatim} |
| This function never returns. |
| If the C function has been called from Lua, |
| then the corresponding Lua execution terminates, |
| as if an error had occurred inside Lua code. |
| Otherwise, the whole program terminates with a call to \verb|exit(1)|. |
| |
| The error handler method \see{error} can be changed with: |
| \Deffunc{lua_seterrormethod} |
| \begin{verbatim} |
| lua_Object lua_seterrormethod (void); |
| \end{verbatim} |
| This function sets the object at the top of C2lua |
| as the new error method, |
| and returns the old error method value. |
| |
| Tag methods can be changed with: |
| \Deffunc{lua_settagmethod} |
| \begin{verbatim} |
| lua_Object lua_settagmethod (int tag, char *event); |
| \end{verbatim} |
| The first parameter is the tag, |
| the second is the event name \see{tag-method}; |
| the new method is pushed from C2lua. |
| This function returns a \verb|lua_Object|, |
| which is the old tag method value. |
| To get just the current value of a tag method, |
| there is the function |
| \Deffunc{lua_gettagmethod} |
| \begin{verbatim} |
| lua_Object lua_gettagmethod (int tag, char *event); |
| \end{verbatim} |
| |
| |
| \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_setglobal(n)) |
| /* char *n; */ |
| /* lua_CFunction f; */ |
| \end{verbatim} |
| which receives the name the function will have in Lua, |
| and a pointer to the function. |
| This pointer must have type \verb|lua_CFunction|, |
| which is defined as |
| \Deffunc{lua_CFunction} |
| \begin{verbatim} |
| typedef void (*lua_CFunction) (void); |
| \end{verbatim} |
| that is, a pointer to a function with no parameters and no results. |
| |
| In order to communicate properly with Lua, |
| a C function must follow a protocol, |
| which defines the way parameters and results are passed. |
| |
| A C function receives its arguments in structure lua2C; |
| to access them, it uses the macro \verb|lua_getparam|, \Deffunc{lua_getparam} |
| again just another name to \verb|lua_lua2C|. |
| To return values, a C function just pushes them onto the stack C2lua, |
| in direct order \see{valuesCLua}. |
| Like a Lua function, a C function called by Lua can also return |
| many results. |
| |
| For some examples, see files \verb|strlib.c|, |
| \verb|iolib.c| and \verb|mathlib.c| in Lua distribution. |
| |
| \subsection{References to Lua Objects} |
| |
| As noted in Section~\ref{LuacallC}, \verb|lua_Object|s are volatile. |
| If the C code needs to keep a \verb|lua_Object| |
| outside block boundaries, |
| then 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_unref} |
| \begin{verbatim} |
| int lua_ref (int lock); |
| lua_Object lua_getref (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 \emph{locked}: |
| this means the object will not be garbage collected. |
| Notice that an unlocked reference may be garbage collected. |
| Whenever the referenced object is needed, |
| a call to \verb|lua_getref| |
| returns a handle to it; |
| if the object has been collected, |
| \verb|lua_getref| returns \verb|LUA_NOOBJECT|. |
| |
| 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 allow some degree of |
| \Index{reflexivity} in the language. |
| Some of these features cannot be simulated with the rest of the |
| language nor with the standard Lua API. |
| Others are just convenient interfaces to common API functions. |
| |
| The libraries, on the other hand, provide useful routines |
| that are implemented directly through the standard API. |
| Therefore, they are not necessary to the language, |
| and are provided as separate C modules. |
| Currently there are three standard libraries: |
| \begin{itemize} |
| \item string manipulation; |
| \item mathematical functions (sin, log, etc); |
| \item input and output (plus some system facilities). |
| \end{itemize} |
| In order to have access to these libraries, |
| the host program must call the functions |
| \verb|strlib_open|, \verb|mathlib_open|, and \verb|iolib_open|, |
| declared in \verb|lualib.h|. |
| |
| |
| \subsection{Predefined Functions} \label{predefined} |
| |
| \subsubsection*{\ff \T{call (func, arg, [retmode])}}\Deffunc{call} |
| This function calls function \verb|func| with |
| the arguments given by the table \verb|arg|. |
| The call is equivalent to |
| \begin{verbatim} |
| func(arg[1], arg[2], ..., arg[arg.n]) |
| \end{verbatim} |
| If \verb|arg.n| is not defined, |
| then Lua stops getting arguments at the first nil value. |
| |
| If \verb|retmode| is absent, |
| all results from \verb|func| are just returned by the call. |
| If \verb|retmode| is equal to \verb|"pack"|, |
| the results are \emph{packed} in a single table.\index{packed results} |
| That is, \verb|call| returns just one table; |
| at index \verb|n|, the table has the total number of results |
| from the call; |
| the first result is at index 1, etc. |
| For instance, the following calls produce the following results: |
| \begin{verbatim} |
| a = call(sin, {5}) --> a = 0.0871557 = sin(5) |
| a = call(max, {1,4,5; n=2}) --> a = 4 (only 1 and 4 are arguments) |
| t = {x=1} |
| a = call(next, {t,nil;n=2}, "pack") --> a={"x", 1; n=2} |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{collectgarbage ([limit])}}\Deffunc{collectgarbage} |
| Forces a garbage collection cycle. |
| Returns the number of objects collected. |
| An optional argument, \verb|limit|, is a number that |
| makes the next cycle occur when that number of new |
| objects have been created. |
| If absent, Lua uses an adaptable algorithm to set |
| this limit. |
| \verb|collectgarbage| is equivalent to |
| the API function \verb|lua_collectgarbage|. |
| |
| \subsubsection*{\ff \T{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, |
| then \verb|dofile| returns \nil. |
| Otherwise, it returns the values returned by the chunk, |
| or a non \nil\ value if the chunk returns no values. |
| It issues an error when called with a non string argument. |
| \verb|dofile| is equivalent to the API function \verb|lua_dofile|. |
| |
| \subsubsection*{\ff \T{dostring (string [, errmethod])}}\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. |
| If provided, \verb|errmethod| is temporarily set as the error method, |
| while \verb|string| runs. |
| As a particular case, if \verb|errmethod| is \nil, |
| no error messages will be issued during the execution of the string. |
| |
| \subsubsection*{\ff \T{newtag ()}}\Deffunc{newtag}\label{pdf-newtag} |
| Returns a new tag. |
| \verb|newtag| is equivalent to the API function \verb|lua_newtag|. |
| |
| \subsubsection*{\ff \T{next (table, index)}}\Deffunc{next} |
| This function allows a program to traverse all fields of a table. |
| Its first argument is a table and its second argument |
| is an index in this table. |
| It returns the next index of the table and the |
| value associated with the index. |
| When called with \nil\ as its second argument, |
| the function returns the first index |
| of the table (and its associated value). |
| When called with the last index, or with \nil\ in an empty table, |
| it returns \nil. |
| |
| In Lua there is no declaration of fields; |
| semantically, there is no difference between a |
| field not present in a table or a field with value \nil. |
| Therefore, the function only considers fields with non \nil\ values. |
| The order in which the indices are enumerated is not specified, |
| \emph{not even for numeric indices} |
| (to traverse a table in numeric order, |
| use a counter). |
| If the table is modified in any way during a traversal, |
| the semantics of \verb|next| is undefined. |
| |
| This function cannot be written with the standard API. |
| |
| \subsubsection*{\ff \T{nextvar (name)}}\Deffunc{nextvar} |
| This function is similar to the function \verb|next|, |
| but iterates over the global variables. |
| Its single argument is the name of a global variable, |
| or \nil\ to get a first name. |
| Similarly to \verb|next|, it returns the name of another variable |
| and its value, |
| or \nil\ if there are no more variables. |
| There can be no assignments to global variables during the traversal; |
| otherwise the semantics of \verb|nextvar| is undefined. |
| |
| This function cannot be written with the standard API. |
| |
| \subsubsection*{\ff \T{tostring (e)}}\Deffunc{tostring} |
| This function receives an argument of any type and |
| converts it to a string in a reasonable format. |
| |
| \subsubsection*{\ff \T{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 \T{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 \T{type (v)}}\Deffunc{type}\label{pdf-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"|, |
| and \verb|"userdata"|. |
| \verb|type| is equivalent to the API function \verb|lua_type|. |
| |
| \subsubsection*{\ff \T{tag (v)}}\Deffunc{tag} |
| This function allows Lua to test the tag of a value \see{TypesSec}. |
| It receives one argument, and returns its tag (a number). |
| \verb|tag| is equivalent to the API function \verb|lua_tag|. |
| |
| \subsubsection*{\ff \T{settag (t, tag)}}\Deffunc{settag} |
| This function sets the tag of a given table \see{TypesSec}. |
| \verb|tag| must be a value created with \verb|newtag| |
| \see{pdf-newtag}. |
| For security reasons, |
| it is impossible to change the tag of a userdata from Lua. |
| |
| \subsubsection*{\ff \T{assert (v)}}\Deffunc{assert} |
| This function issues an \emph{``assertion failed!''} error |
| when its argument is \nil. |
| |
| \subsubsection*{\ff \T{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|, or \verb|lua_callfunction|). |
| It never returns. |
| \verb|error| is equivalent to the API function \verb|lua_error|. |
| |
| \subsubsection*{\ff \T{rawgettable (table, index)}}\Deffunc{rawgettable} |
| Gets the real value of \verb|table[index]|, |
| without invoking any tag method. |
| \verb|table| must be a table, |
| and \verb|index| is any value different from \nil. |
| |
| \subsubsection*{\ff \T{rawsettable (table, index, value)}}\Deffunc{rawsettable} |
| Sets the real value \verb|table[index]=value|, |
| without invoking any tag method. |
| \verb|table| must be a table, |
| \verb|index| is any value different from \nil, |
| and \verb|value| is any Lua value. |
| |
| \subsubsection*{\ff \T{rawsetglobal (name, value)}}\Deffunc{rawsetglobal} |
| 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 \T{setglobal (name, value)}}\Deffunc{setglobal} |
| This function assigns the given value to a global variable, |
| or calls a tag method. |
| Its full semantics is explained in \See{tag-method}. |
| |
| \subsubsection*{\ff \T{rawgetglobal (name)}}\Deffunc{rawgetglobal} |
| 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 \T{getglobal (name)}}\Deffunc{getglobal} |
| This function retrieves the value of a global variable, |
| or calls a tag method. |
| Its full semantics is explained in \See{tag-method}. |
| |
| \subsubsection*{\ff \T{seterrormethod (newmethod)}} |
| \label{pdf-seterrormethod} |
| Sets the error handler \see{error}. |
| \verb|newmethod| must be a function or \nil, |
| in which case the error handler does nothing. |
| Returns the old error handler. |
| |
| \subsubsection*{\ff \T{settagmethod (tag, event, newmethod)}} |
| \Deffunc{settagmethod} |
| This function sets a new tag method to the given pair \M{<tag, event>}. |
| It returns the old method. |
| If \verb|newmethod| is \nil, |
| it restores the default behavior for the given event. |
| |
| \subsubsection*{\ff \T{gettagmethod (tag, event)}} |
| \Deffunc{gettagmethod} |
| This function returns the current tag method |
| for a given pair \M{<tag, event>}. |
| |
| |
| \subsection{String Manipulation} |
| This library provides generic functions for string manipulation, |
| such as finding and extracting substrings and pattern matching. |
| When indexing a string, the first character is at position~1, |
| not~0, as in C. |
| |
| \subsubsection*{\ff \T{strfind (str, pattern [, init [, plain]])}} |
| \Deffunc{strfind} |
| This function looks for the first \emph{match} of |
| \verb|pattern| in \verb|str|. |
| If it finds one, then it returns the indices on \verb|str| |
| where this occurrence 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 fourth optional argument |
| turns off the pattern matching facilities, |
| so the function does a plain ``find substring'' operation, |
| with no characters in \verb|pattern| being considered ``magic''. |
| |
| \subsubsection*{\ff \T{strlen (s)}}\Deffunc{strlen} |
| Receives a string and returns its length. |
| |
| \subsubsection*{\ff \T{strsub (s, i [, j])}}\Deffunc{strsub} |
| Returns another string, which is a substring of \verb|s|, |
| starting at \verb|i| and running until \verb|j|. |
| If \verb|i| or \verb|j| are negative, |
| they are replaced by the length of the string minus their |
| absolute value plus 1. |
| Therefore, -1 points to the last character of \verb|s| |
| and -2 to the previous one. |
| If \verb|j| is absent, it is assumed to be equal to -1 |
| (which is the same as the string length). |
| In particular, |
| the call \verb|strsub(s,1,j)| returns a prefix of \verb|s| |
| with length \verb|j|, |
| and the call \verb|strsub(s, -i)| returns a suffix of \verb|s| |
| with length \verb|i|. |
| |
| \subsubsection*{\ff \T{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 \T{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 \T{strrep (s, n)}}\Deffunc{strrep} |
| Returns a string which is the concatenation of \verb|n| copies of |
| the string \verb|s|. |
| |
| \subsubsection*{\ff \T{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 \T{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} |
| |
| Conversions can be applied to the n-th argument in the argument list, |
| rather than the next unused argument. |
| In this case, the conversion character \verb|%| is replaced |
| by the sequence \verb|%d$|, where \verb|d| is a |
| decimal digit in the range [1,9], |
| giving the position of the argument in the argument list. |
| For instance, the call \verb|format("%2$d -> %1$03d", 1, 34)| will |
| result in \verb|"34 -> 001"|. |
| |
| The options \verb|c|, \verb|d|, \verb|E|, \verb|e|, \verb|f|, |
| \verb|g| \verb|i|, \verb|o|, \verb|u|, \verb|X|, and \verb|x| all |
| expect a number as argument, |
| whereas \verb|q| and \verb|s| expect a string. |
| Note that the \verb|*| modifier can be simulated by building |
| the appropriate format string. |
| For example, \verb|"%*g"| can be simulated with |
| \verb|"%"..width.."g"|. |
| |
| \subsubsection*{\ff \T{gsub (s, pat, repl [, table] [, n])}} |
| \Deffunc{gsub} |
| Returns a copy of \verb|s|, |
| where all occurrences of the pattern \verb|pat| have been |
| replaced by a replacement string specified by \verb|repl|. |
| This function also returns, as a second value, |
| the total number of substitutions made. |
| |
| If \verb|repl| is a string, then its value is used for replacement. |
| Any sequence in \verb|repl| of the form \verb|%n| |
| with \verb|n| between 1 and 9 |
| stands for the value of the n-th captured substring. |
| |
| If \verb|repl| is a function, then this function is called every time a |
| match occurs, with the following arguments: |
| If \verb|table| is present, then the first argument is this table |
| and the second one is a match counter (1 for the first call). |
| Independently of these two optional arguments, |
| all captured substrings are passed as arguments, |
| in order (see below); |
| If the value returned by this function is a string, |
| then it is used as the replacement string; |
| otherwise, the replacement string is the empty string. |
| |
| A last optional parameter \verb|n| limits |
| the maximum number of substitutions to occur. |
| For instance, when \verb|n| is 1 only the first occurrence of |
| \verb|pat| is replaced. |
| |
| See some examples below: |
| \begin{verbatim} |
| x = gsub("hello world", "(%w%w*)", "%1 %1", 1) |
| --> x="hello hello world" |
| |
| x = gsub("home = $HOME, user = $USER", "$(%w%w*)", getenv) |
| --> x="home = /home/roberto, user = roberto" (for instance) |
| |
| x = gsub("4+5 = $return 4+5$", "$(.-)%$", dostring) |
| --> x="4+5 = 9" |
| |
| function f(t, i, v) return t[v] end |
| t = {name="lua", version="3.0"} |
| x = gsub("$name - $version", "$(%w%w*)", f, t) |
| --> x="lua - 3.0" |
| |
| t = {"apple", "orange", "lime"} |
| x = gsub("x and x and x", "x", rawgettable, t) |
| --> x="apple and orange and lime" |
| |
| t = {} |
| dummy, t.n = gsub("first second word", "(%w%w*)", rawsettable, t) |
| --> t={"first", "second", "word"; n=3} |
| \end{verbatim} |
| |
| |
| \subsubsection*{Patterns} \label{pm} |
| |
| \paragraph{Character Class:} |
| a \Def{character class} is used to represent a set of characters. |
| The following combinations are allowed in describing a character class: |
| \begin{description} |
| \item[\emph{x}] (where \emph{x} is any character not in the list \verb|()%.[*-?|) |
| --- represents the character \emph{x} itself. |
| \item[\T{.}] --- represents all characters. |
| \item[\T{\%a}] --- represents all letters. |
| \item[\T{\%A}] --- represents all non letter characters. |
| \item[\T{\%d}] --- represents all digits. |
| \item[\T{\%D}] --- represents all non digits. |
| \item[\T{\%l}] --- represents all lower case letters. |
| \item[\T{\%L}] --- represents all non lower case letter characters. |
| \item[\T{\%s}] --- represents all space characters. |
| \item[\T{\%S}] --- represents all non space characters. |
| \item[\T{\%u}] --- represents all upper case letters. |
| \item[\T{\%U}] --- represents all non upper case letter characters. |
| \item[\T{\%w}] --- represents all alphanumeric characters. |
| \item[\T{\%W}] --- represents all non alphanumeric characters. |
| \item[\T{\%\M{x}}] (where \M{x} is any non alphanumeric character) --- |
| represents the character \M{x}. |
| This is the standard way to escape the magic characters \verb|()%.[*-?|. |
| \item[\T{[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 English upper case characters. |
| If \verb|-| appears as the first or last character of char-set, |
| then it represents itself. |
| All classes \verb|%|\emph{x} described above can also be used as |
| components in a char-set. |
| All other characters in char-set represent themselves. |
| \item[\T{[\^{ }char-set]}] --- |
| represents the complement of char-set, |
| where char-set is interpreted as above. |
| \end{description} |
| |
| The definitions of letter, space, etc depend on the current locale. |
| In particular, the class \verb|[a-z]| may not be equivalent to \verb|%l|. |
| The second form should be preferred for more portable programs. |
| |
| \paragraph{Pattern Item:} |
| a \Def{pattern item} may be: |
| \begin{itemize} |
| \item |
| a single character class, |
| which matches any single character in the class; |
| \item |
| a single character class followed by \verb|*|, |
| which matches 0 or more repetitions of characters in the class. |
| These repetition items will always match the longest possible sequence. |
| \item |
| a single character class followed by \verb|-|, |
| which also matches 0 or more repetitions of characters in the class. |
| Unlike \verb|*|, |
| these repetition items will always match the shortest possible sequence. |
| \item |
| a single character class followed by \verb|?|, |
| which matches 0 or 1 occurrence of a character in the class; |
| \item |
| \T{\%\M{n}}, for \M{n} between 1 and 9; |
| such item matches a sub-string equal to the n-th captured string |
| (see below); |
| \item |
| \T{\%b\M{xy}}, where \M{x} and \M{y} are two distinct characters; |
| such item matches strings that start with \M{x}, end with \M{y}, |
| and where the \M{x} and \M{y} are \emph{balanced}. |
| That means that, if one reads the string from left to write, |
| counting plus 1 for an \M{x} and minus 1 for a \M{y}, |
| the ending \M{y} is the first where the count reaches 0. |
| For instance, the item \verb|%b()| matches expressions with |
| balanced parentheses. |
| \end{itemize} |
| |
| \paragraph{Pattern:} |
| a \Def{pattern} is a sequence of pattern items. |
| A \verb|^| at the beginning of a pattern anchors the match at the |
| beginning of the subject string. |
| A \verb|$| at the end of a pattern anchors the match at the |
| end of the subject string. |
| |
| \paragraph{Captures:} |
| a pattern may contain sub-patterns enclosed in parentheses, |
| that describe \Def{captures}. |
| When a match succeeds, the sub-strings of the subject string |
| that match captures are stored (\emph{captured}) for future use. |
| Captures are numbered according to their left parentheses. |
| For instance, in the pattern \verb|"(a*(.)%w(%s*))"|, |
| the part of the string matching \verb|"a*(.)%w(%s*)"| is |
| stored as the first capture (and therefore has number 1); |
| the character matching \verb|.| is captured with number 2, |
| and the part matching \verb|%s*| has number 3. |
| |
| |
| \subsection{Mathematical Functions} \label{mathlib} |
| |
| This library is an interface to some functions of the standard C math library. |
| In addition, it registers a tag method for the binary operator \verb|^| that |
| returns \Math{x^y} when applied to numbers \verb|x^y|. |
| |
| The library provides the following functions: |
| \Deffunc{abs}\Deffunc{acos}\Deffunc{asin}\Deffunc{atan} |
| \Deffunc{atan2}\Deffunc{ceil}\Deffunc{cos}\Deffunc{floor} |
| \Deffunc{log}\Deffunc{log10}\Deffunc{max}\Deffunc{min} |
| \Deffunc{mod}\Deffunc{sin}\Deffunc{sqrt}\Deffunc{tan} |
| \Deffunc{random}\Deffunc{randomseed} |
| \begin{verbatim} |
| abs acos asin atan atan2 ceil cos floor log log10 |
| max min mod sin sqrt tan random randomseed |
| \end{verbatim} |
| Most of them |
| are only interfaces to the homonymous functions in the C library, |
| except that, for the trigonometric functions, |
| all angles are expressed in \emph{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|, when called without arguments, |
| returns a pseudo-random real number in the range \Math{[0,1)}. |
| When called with a number \Math{n}, |
| returns a pseudo-random integer in the range \Math{[1,n]}. |
| |
| |
| \subsection{I/O Facilities} \label{libio} |
| |
| All input and output operations in Lua are done over two |
| \Def{file handles}, one for reading and one for writing. |
| These handles are stored in two Lua global variables, |
| called \verb|_INPUT| and \verb|_OUTPUT|. |
| The global variables |
| \verb|_STDIN|, \verb|_STDOUT| and \verb|_STDERR| |
| are initialized with file descriptors for |
| \verb|stdin|, \verb|stdout| and \verb|stderr|. |
| Initially, \verb|_INPUT=_STDIN| and \verb|_OUTPUT=_STDOUT|. |
| \Deffunc{_INPUT}\Deffunc{_OUTPUT} |
| \Deffunc{_STDIN}\Deffunc{_STDOUT}\Deffunc{_STDERR} |
| |
| A file handle is a userdata containing the file stream \verb|FILE*|, |
| and with a distinctive tag created by the I/O library. |
| |
| |
| Unless otherwise stated, |
| all I/O functions return \nil\ on failure and |
| some value different from \nil\ on success. |
| |
| \subsubsection*{\ff \T{readfrom (filename)}}\Deffunc{readfrom} |
| |
| This function may be called in two ways. |
| When called with a file name, it opens the named file, |
| sets its handle as the value of \verb|_INPUT|, |
| and returns this value. |
| It does not close the current input file. |
| When called without parameters, |
| it closes the \verb|_INPUT| file, |
| and restores \verb|stdin| as the value of \verb|_INPUT|. |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \begin{quotation} |
| \noindent |
| \emph{System dependent}: if \verb|filename| starts with a \verb-|-, |
| then a \Index{piped input} is open, via function \IndexVerb{popen}. |
| Not all systems implement pipes. |
| Moreover, |
| the number of files that can be open at the same time is |
| usually limited and depends on the system. |
| \end{quotation} |
| |
| \subsubsection*{\ff \T{writeto (filename)}}\Deffunc{writeto} |
| |
| This function may be called in two ways. |
| When called with a file name, |
| it opens the named file, |
| sets its handle as the value of \verb|_OUTPUT|, |
| and returns this value. |
| It does not close the current output file. |
| Notice that, if the file already exists, |
| then it will be \emph{completely erased} with this operation. |
| When called without parameters, |
| this function closes the \verb|_OUTPUT| file, |
| and restores \verb|stdout| as the value of \verb|_OUTPUT|. |
| \index{closing a file} |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \begin{quotation} |
| \noindent |
| \emph{System dependent}: if \verb|filename| starts with a \verb-|-, |
| then a \Index{piped output} is open, via function \IndexVerb{popen}. |
| Not all systems implement pipes. |
| Moreover, |
| the number of files that can be open at the same time is |
| usually limited and depends on the system. |
| \end{quotation} |
| |
| \subsubsection*{\ff \T{appendto (filename)}}\Deffunc{appendto} |
| |
| This function opens a file named \verb|filename| and sets it as the |
| value of \verb|_OUTPUT|. |
| Unlike the \verb|writeto| operation, |
| this function does not erase any previous content of the file. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| Notice that function \verb|writeto| is available to close an output file. |
| |
| \subsubsection*{\ff \T{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 \T{rename (name1, name2)}}\Deffunc{rename} |
| |
| This function renames file named \verb|name1| to \verb|name2|. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{tmpname ()}}\Deffunc{tmpname} |
| |
| This function returns a string with a file name that can safely |
| be used for a temporary file. |
| The file must be explicitly removed when no longer needed. |
| |
| \subsubsection*{\ff \T{read ([readpattern])}}\Deffunc{read} |
| |
| This function reads the file \verb|_INPUT| |
| according to a read pattern, that specifies how much to read; |
| characters are read from the current input file until |
| the read pattern fails or ends. |
| The function \verb|read| returns a string with the characters read, |
| even if the pattern succeeds only partially, |
| or \nil\ if the read pattern fails \emph{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 characters, it never fails. |
| Notice that the behavior of read patterns is different from |
| the regular pattern matching behavior, |
| where a \verb|*| expands to the maximum length \emph{such that} |
| the rest of the pattern does not fail. |
| With the read pattern behavior |
| there is no need for backtracking the reading. |
| |
| A pattern item may contain sub-patterns enclosed in curly brackets, |
| that describe \Def{skips}. |
| Characters matching a skip are read, |
| but are not included in the resulting string. |
| |
| Following are some examples of read patterns and their meanings: |
| \begin{itemize} |
| \item \verb|"."| returns the next character, or \nil\ on end of file. |
| \item \verb|".*"| reads the whole file. |
| \item \verb|"[^\n]*{\n}"| returns the next line |
| (skipping the end of line), or \nil\ on end of file. |
| This is the default pattern. |
| \item \verb|"{%s*}%S%S*"| returns the next word |
| (maximal sequence of non white-space characters), |
| skipping spaces if necessary, |
| 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 \T{write (value1, ...)}}\Deffunc{write} |
| |
| This function writes the value of each of its arguments to the |
| file \verb|_OUTPUT|. |
| The arguments must be strings or numbers. |
| To write other values, |
| use \verb|tostring| or \verb|format| before \verb|write|. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{date ([format])}}\Deffunc{date} |
| |
| This function returns a string containing date and time |
| formatted according to the given string \verb|format|, |
| following the same rules of the ANSI C function \verb|strftime|. |
| When called without arguments, |
| it returns a reasonable date and time representation that depends on |
| the host system. |
| |
| \subsubsection*{\ff \T{exit ([code])}}\Deffunc{exit} |
| |
| This function calls the C function \verb|exit|, |
| with an optional \verb|code|, |
| to terminate the program. |
| The default value for \verb|code| is 1. |
| |
| \subsubsection*{\ff \T{getenv (varname)}}\Deffunc{getenv} |
| |
| Returns the value of the environment variable \verb|varname|, |
| or \nil\ if the variable is not defined. |
| |
| \subsubsection*{\ff \T{execute (command)}}\Deffunc{execute} |
| |
| This function is equivalent to the C function \verb|system|. |
| It passes \verb|command| to be executed by an operating system shell. |
| It returns an error code, which is system-dependent. |
| |
| \subsubsection*{\ff \T{setlocale (locale [, category])}}\Deffunc{setlocale} |
| |
| This function is an interface to the ANSI C function \verb|setlocale|. |
| \verb|locale| is a string specifing a locale; |
| \verb|category| is a number describing which category to change: |
| 0 is \verb|LC_ALL|, 1 is \verb|LC_COLLATE|, 2 is \verb|LC_CTYPE|, |
| 3 is \verb|LC_MONETARY|, 4 is \verb|LC_NUMERIC|, and 5 is \verb|LC_TIME|; |
| the default category is \verb|LC_ALL|. |
| The function returns the name of the new locale, |
| or \nil\ if the request cannot be honored. |
| |
| |
| \section{The Debugger Interface} \label{debugI} |
| |
| Lua has no built-in debugging facilities. |
| Instead, it offers a special interface, |
| by means of functions and \emph{hooks}, |
| which allows the construction of different |
| kinds of debuggers, profilers, and other tools |
| that need ``inside information'' from the interpreter. |
| This interface is declared in 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 \emph{activation record} |
| of the function executing at a given level. |
| Level~0 is the current running function, |
| while level \Math{n+1} is the function that has called level \Math{n}. |
| When called with a level greater than the stack depth, |
| \verb|lua_stackedfunction| returns \verb|LUA_NOOBJECT|. |
| |
| The type \verb|lua_Function| is just another name |
| to \verb|lua_Object|. |
| Although, in this library, |
| a \verb|lua_Function| can be used wherever a \verb|lua_Object| is required, |
| when a parameter has type \verb|lua_Function| |
| it accepts only a handle returned by |
| \verb|lua_stackedfunction|. |
| |
| Three other functions produce extra information about a function: |
| \begin{verbatim} |
| void lua_funcinfo (lua_Object func, char **filename, int *linedefined); |
| int lua_currentline (lua_Function func); |
| char *lua_getobjname (lua_Object o, char **name); |
| \end{verbatim} |
| \verb|lua_funcinfo| gives the file name and the line where the |
| given function has been defined. |
| If the ``function'' is in fact the main code of a chunk, |
| then \verb|linedefined| is 0. |
| If the function is a C function, |
| then \verb|linedefined| is -1, and \verb|filename| is \verb|"(C)"|. |
| |
| The function \verb|lua_currentline| gives the current line where |
| a given function is executing. |
| It only works if the function has been compiled with debug |
| information \see{pragma}. |
| When no line information is available, it returns -1. |
| |
| Function \verb|lua_getobjname| tries to find a reasonable name for |
| a given function. |
| Because functions in Lua are first class values, |
| they do not have a fixed name: |
| Some functions may be the value of many global variables, |
| while others may be stored only in a table field. |
| Function \verb|lua_getobjname| first checks whether the given |
| function is a tag method. |
| If so, it returns the string \verb|"tag-method"|, |
| and \verb|name| is set to point to the event name. |
| Otherwise, if the given function is the value of a global variable, |
| then \verb|lua_getobjname| returns the string \verb|"global"|, |
| and \verb|name| points to the variable name. |
| If the given function is neither a tag method nor a global variable, |
| then \verb|lua_getobjname| returns the empty string, |
| and \verb|name| is set to \verb|NULL|. |
| |
| \subsection{Manipulating Local Variables} |
| |
| The following functions allow the manipulation of the |
| local variables of a given activation record. |
| They only work if the function has been compiled with debug |
| information \see{pragma}. |
| \begin{verbatim} |
| lua_Object lua_getlocal (lua_Function func, int local_number, char **name); |
| int lua_setlocal (lua_Function func, int local_number); |
| \end{verbatim} |
| \verb|lua_getlocal| returns the value of a local variable, |
| and sets \verb|name| to point to the variable name. |
| \verb|local_number| is an index for local variables. |
| The first parameter has index 1, and so on, until the |
| last active local variable. |
| When called with a \verb|local_number| greater than the |
| number of active local variables, |
| or if the activation record has no debug information, |
| \verb|lua_getlocal| returns \verb|LUA_NOOBJECT|. |
| Formal parameters are the first local variables. |
| |
| The function \verb|lua_setlocal| sets the local variable |
| \verb|local_number| to the value previously pushed on the stack |
| \see{valuesCLua}. |
| If the function succeeds, then it returns 1. |
| If \verb|local_number| is greater than the number |
| of active local variables, |
| or if the activation record has no debug information, |
| then this function fails and returns 0. |
| |
| \subsection{Hooks} |
| |
| The Lua interpreter offers two hooks for debugging purposes: |
| \begin{verbatim} |
| typedef void (*lua_CHFunction) (lua_Function func, char *file, int line); |
| extern lua_CHFunction lua_callhook; |
| |
| typedef void (*lua_LHFunction) (int line); |
| extern lua_LHFunction lua_linehook; |
| \end{verbatim} |
| The first one is called whenever the interpreter enters or leaves a |
| function. |
| When entering a function, |
| its parameters are a handle to the function activation record, |
| plus the file and the line where the function is defined (the same |
| information which is provided by \verb|lua_funcinfo|); |
| when leaving a function, \verb|func| is \verb|LUA_NOOBJECT|, |
| \verb|file| is \verb|"(return)"|, and \verb|line| is 0. |
| |
| The other hook is called every time the interpreter changes |
| the line of code it is executing. |
| Its only parameter is the line number |
| (the same information which is provided by the call |
| \verb|lua_currentline(lua_stackedfunction(0))|). |
| This second hook is only called if the active function |
| has been compiled with debug information \see{pragma}. |
| |
| A hook is disabled when its value is \verb|NULL|, |
| which is the initial value of both hooks. |
| |
| |
| |
| \section{\Index{Lua Stand-alone}} \label{lua-sa} |
| |
| Although Lua has been designed as an extension language, |
| the language can also be used as a stand-alone interpreter. |
| An implementation of such an interpreter, |
| called simply \verb|lua|, |
| is provided with the standard distribution. |
| This program can be called with any sequence of the following arguments: |
| \begin{description} |
| \item[\T{-v}] prints version information. |
| \item[\T{-}] runs interactively, accepting commands from standard input |
| until an \verb|EOF|. |
| \item[\T{-e stat}] executes \verb|stat| as a Lua chunk. |
| \item[\T{var=exp}] executes \verb|var=exp| as a Lua chunk. |
| \item[\T{filename}] executes file \verb|filename| as a Lua chunk. |
| \end{description} |
| All arguments are handled in order. |
| For instance, an invocation like |
| \begin{verbatim} |
| $ lua - a=1 prog.lua |
| \end{verbatim} |
| will first interact with the user until an \verb|EOF|, |
| then will set \verb|a| to 1, |
| and finally will run file \verb|prog.lua|. |
| |
| Please notice that the interaction with the shell may lead to |
| unintended results. |
| For instance, a call like |
| \begin{verbatim} |
| $ lua a="name" prog.lua |
| \end{verbatim} |
| will \emph{not} set \verb|a| to the string \verb|"name"|. |
| Instead, the quotes will be handled by the shell, |
| lua will get only \verb|a=name| to run, |
| and \verb|a| will finish with \nil, |
| because the global variable \verb|name| has not been initialized. |
| Instead, one should write |
| \begin{verbatim} |
| $ lua 'a="name"' prog.lua |
| \end{verbatim} |
| |
| \section*{Acknowledgments} |
| |
| The authors would like to thank CENPES/PETROBRAS 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 \emph{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.5}} |
| \begin{itemize} |
| \item |
| The whole fallback mechanism has been replaced by tag methods. |
| Nevertheless, the function \verb|setfallback| has been rewritten in |
| a way that uses tag methods to fully emulate the old behavior |
| of fallbacks. |
| \item |
| Tags now must be created with the function \verb|newtag|. |
| Nevertheless, old user defined tags are still accepted |
| (user defined tags must be positive; |
| \verb|newtag| uses negative numbers). |
| Tag methods cannot be set for such user defined tags, |
| and fallbacks do not affect tags created by \verb|newtag|. |
| \item |
| Lua 2.5 accepts mixed comparisons of strings and numbers, |
| like \verb|2<"12"|, giving weird results. |
| Now this is an error. |
| \item |
| Character \verb|"-"| (hyphen) now is ``magic'' in pattern matching. |
| \item |
| Some API functions have been rewritten as macros. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 2.4}} |
| The whole I/O facilities have been rewritten. |
| We strongly encourage programmers to adapt their code |
| to this new version. |
| 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 \emph{read patterns} to specify |
| what to read; |
| this is incompatible with the old format options. |
| \item Function \verb|strfind| now accepts patterns, |
| so it may have a different behavior when the pattern includes |
| special characters. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 2.2}} |
| \begin{itemize} |
| \item |
| Functions \verb|date| and \verb|time| (from \verb|iolib|) |
| have been superseded by the new, more powerful version of function \verb|date|. |
| \item |
| Function \verb|append| (from \verb|iolib|) now returns 1 whenever it succeeds, |
| whether the file is new or not. |
| \item |
| Function \verb|int2str| (from \verb|strlib|) has been superseded by new |
| function \verb|format|, with parameter \verb|"%c"|. |
| \item |
| The API lock mechanism has been superseded by the reference mechanism. |
| However, \verb|lua.h| provides compatibility macros, |
| so there is no need to change programs. |
| \item |
| The API function \verb|lua_pushliteral| now is just a macro to |
| \verb|lua_pushstring|. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 2.1}} |
| \begin{itemize} |
| \item |
| The function \verb|type| now returns the string \verb|"function"| |
| both for C and Lua functions. |
| Because Lua functions and C functions are compatible, |
| this behavior is usually more useful. |
| When needed, the second result of function \T{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, \emph{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 \emph{fallback} mechanism \see{error}. |
| \item |
| When calling a function from the Lua library, |
| parameters passed through the stack |
| must be pushed just before the corresponding call, |
| with no intermediate calls to Lua. |
| Special care should be taken with macros like |
| \verb|lua_getindexed| and \verb|lua_getfield|. |
| \end{itemize} |
| |
| \newcommand{\indexentry}[2]{\item {#1} #2} |
| %\catcode`\_=12 |
| \begin{theindex} |
| \input{manual.id} |
| \end{theindex} |
| |
| |
| \end{document} |
| |
| |