From 6ec4a0ef767f2a49983b4e2eb1d3fdb1fd331117 Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Mon, 18 Sep 2000 16:41:16 -0300 Subject: [PATCH] updates by lhf --- manual.tex | 2143 +++++++++++++++++++++++++++------------------------- 1 file changed, 1134 insertions(+), 1009 deletions(-) diff --git a/manual.tex b/manual.tex index 64f18c50..5d86a188 100644 --- a/manual.tex +++ b/manual.tex @@ -1,4 +1,4 @@ -% $Id: manual.tex,v 1.41 2000/08/14 19:18:14 roberto Exp roberto $ +% $Id: manual.tex,v 1.42 2000/08/30 18:58:46 roberto Exp roberto $ \documentclass[11pt]{article} \usepackage{fullpage,bnf} @@ -28,7 +28,7 @@ % LHF \renewcommand{\ter}[1]{{\rm`{\tt#1}'}} \newcommand{\Nter}[1]{{\rm{\tt#1}}} -\newcommand{\NOTE}{\par\noindent\emph{NOTE}: } +\newcommand{\NOTE}{\par\medskip\noindent\emph{NOTE}: } \makeindex @@ -70,28 +70,29 @@ Copyright \copyright\ 1994--2000 TeCGraf, PUC-Rio. All rights reserved. \noindent 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, including commercial applications, subject to +or royalty fees, to use, copy, modify, translate, and distribute +this software and its documentation (hereby called the "package") +for any purpose, including commercial applications, subject to the following conditions: \begin{itemize} \item The above copyright notice and this permission notice shall appear in all - copies or substantial portions of this software. + copies or substantial portions of this package. -\item The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software in a +\item The origin of this package must not be misrepresented; you must not + claim that you wrote the original package. If you use this package in a product, an acknowledgment in the product documentation would be greatly appreciated (but it is not required). \item Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. + misrepresented as being the original package. \end{itemize} 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 +purpose. The package 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 held liable to any party for direct, indirect, special, -incidental, or consequential damages arising out of the use of this software +incidental, or consequential damages arising out of the use of this package and its documentation. \noindent @@ -105,11 +106,16 @@ This implementation contains no third-party code. \noindent Copies of this manual can be obtained at \verb|http://www.tecgraf.puc-rio.br/lua/|. + +\bigskip +\noindent +The Lua logo was designed by A. Nakonechny. +Copyright \copyright\ 1998. All rights reserved. \end{quotation} %}=============================================================== \newpage -\title{Reference Manual of the Programming Language Lua \Version} +\title{\Large\bf Reference Manual of the Programming Language Lua \Version} \author{% Roberto Ierusalimschy\quad @@ -123,12 +129,15 @@ Waldemar Celes \tecgraf\ --- Computer Science Department --- PUC-Rio } -\date{{\small \tt\$Date: 2000/08/14 19:18:14 $ $}} +\date{{\small \tt\$Date: 2000/08/30 18:58:46 $ $}} \maketitle -\thispagestyle{empty} -\pagestyle{empty} +\pagestyle{plain} +\pagenumbering{roman} + +%\thispagestyle{empty} +%\pagestyle{empty} \begin{abstract} \noindent @@ -151,8 +160,8 @@ and rapid prototyping. This document describes version \Version\ of the Lua programming language -and the API that allows interaction between Lua programs and their -host C programs. +and the Application Program Interface (API) +that allows interaction between Lua programs and their host C~programs. \end{abstract} \def\abstractname{Resumo} @@ -160,7 +169,7 @@ host C programs. \noindent Lua \'e uma linguagem de programa\c{c}\~ao poderosa e leve, -projetada para extender aplica\c{c}\~oes. +projetada para estender aplica\c{c}\~oes. Lua tamb\'em \'e frequentemente usada como uma linguagem de prop\'osito geral. Lua combina programa\c{c}\~ao procedural (com sintaxe semelhante \`a de Pascal) @@ -178,7 +187,7 @@ e prototipagem r\'apida. 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. +a intera\c{c}\~ao entre programas Lua e programas C~hospedeiros. \end{abstract} \newpage @@ -188,6 +197,7 @@ a intera\c{c}\~ao entre programas Lua e programas C hospedeiros. \newpage \setcounter{page}{1} +\pagenumbering{arabic} \pagestyle{plain} @@ -211,13 +221,13 @@ 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, +and is provided as usual with no guarantees, as stated in its copyright notice. 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/ + http://www.tecgraf.puc-rio.br/lua/ + ftp://ftp.tecgraf.puc-rio.br/pub/lua/ \end{verbatim} Like any other reference manual, @@ -244,10 +254,11 @@ Lua: an extensible embedded language. All statements in Lua are executed in a \Def{global environment}. This environment is initialized with a call from the embedding program to -\verb|lua_newstate| and +\verb|lua_open| and persists until a call to \verb|lua_close|, or the end of the embedding program. -Optionally, a user can create multiple independent global +If necessary, +the host programmer can create multiple independent global environments, and freely switch between them \see{mangstate}. The global environment can be manipulated by Lua code or @@ -255,13 +266,13 @@ by the embedding program, which can read and write global variables using API functions from the library that implements Lua. -\Index{Global variables} do not need declaration. +\Index{Global variables} in Lua do not need to be declared. 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}. -A ``table of globals'' (called \emph{tog}) is used to keep all -global names and values. +A table is used to keep all global names and values +(tables are explained in \See{TypesSec}). The unit of execution of Lua is called a \Def{chunk}. A chunk is simply a sequence of statements, @@ -275,11 +286,12 @@ Statements are described in \See{stats}. in which \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.) +\oneormore{\emph{a}} means one or more \emph{a}'s. +The complete syntax of Lua is given on page~\pageref{BNF}.) -A chunk may be in a file or in a string inside the host program. -When a chunk is executed, first all its code is pre-compiled, -and then the statements are executed in sequential order. +A chunk may be stored in a file or in a string inside the host program. +When a chunk is executed, first it is pre-compiled into bytecodes for +a virtual machine, and then the statements are executed in sequential order. All modifications a chunk effects on the global environment persist after the chunk ends. @@ -305,7 +317,8 @@ There are six \Index{basic types} in Lua: \Def{nil}, \Def{number}, whose main property is to be different from any other value. \emph{Number} represents real (double-precision floating-point) numbers, while \emph{string} has the usual meaning. -Lua is \Index{eight-bit clean}, +\index{eight-bit clean} +Lua is 8-bit clean, and so strings may contain any 8-bit character, \emph{including} embedded zeros (\verb|'\0'|) \see{lexical}. The \verb|type| function returns a string describing the type @@ -325,8 +338,9 @@ of a given value \see{pdf-tag}. 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. +This type corresponds to a \verb|void*| +and has no pre-defined operations in Lua, +except for assignment and equality test. However, by using \emph{tag methods}, the programmer can define operations for \emph{userdata} values \see{tag-method}. @@ -345,31 +359,32 @@ 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}. +the table itself as the first parameter \see{func-def}. Note that tables are \emph{objects}, and not values. -Variables cannot contain tables, only \emph{references} to them. +Variables do not 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 \emph{tag methods} when -some events occur. -Tag methods are the main mechanism for extending the -semantics of Lua \see{tag-method}. Each of the types \M{nil}, \M{number}, and \M{string} has a different tag. All values of each of these types have the same pre-defined tag. Values of type \M{function} can have two different tags, depending on whether they are Lua functions or C~functions. Finally, -values of type \M{userdata} and \M{table} have -variable tags, assigned by the program \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}. +values of type \M{userdata} and \M{table} can have variable tags, +assigned by the programmer \see{tag-method}. +The function \verb|tag| returns the tag of a given value. +User tags are created with the function \verb|newtag|, +The function \verb|settag| \see{pdf-newtag} +is used to change the tag of a table. +The data of userdata can only be set from~C. +Tags are mainly used to select \emph{tag methods} when +some events occur. +Tag methods are the main mechanism for extending the +semantics of Lua \see{tag-method}. \section{The Language} @@ -389,12 +404,12 @@ can be used in an identifier. The following words are \emph{reserved}, and cannot be used as identifiers: \index{reserved words} \begin{verbatim} - and break do else - elseif end for function - if local nil not - or repeat return then - until while + and break do else elseif + end for function if in + 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 different, valid identifiers. @@ -404,34 +419,34 @@ are reserved for internal variables. The following strings denote other \Index{tokens}: \begin{verbatim} - ~= <= >= < > == = + - * / % - ( ) { } [ ] ; , . .. ... + ~= <= >= < > == = + - * / % + ( ) { } [ ] ; , . .. ... \end{verbatim} \IndexEmph{Literal strings} can be delimited by matching single or double quotes, and can contain the C-like escape sequences -\verb|'\a'| (bell), -\verb|'\b'| (backspace), -\verb|'\f'| (form feed), -\verb|'\n'| (newline), -\verb|'\r'| (carriage return), -\verb|'\t'| (horizontal tab), -\verb|'\v'| (vertical tab), -\verb|'\\'|, (backslash), -\verb|'\"'|, (double quote), -\verb|'\''| (single quote), -and \verb|'\|\emph{newline}\verb|'| (that is, a backslash followed by a real newline, +`\verb|\a|' (bell), +`\verb|\b|' (backspace), +`\verb|\f|' (form feed), +`\verb|\n|' (newline), +`\verb|\r|' (carriage return), +`\verb|\t|' (horizontal tab), +`\verb|\v|' (vertical tab), +`\verb|\\|' (backslash), +`\verb|\"|' (double quote), +`\verb|\'|' (single quote), +and `\verb|\|\emph{newline}' (that is, a backslash followed by a real newline, which results in a newline in the string). A character in a string may also be specified by its numerical value, -through the escape sequence \verb|'\ddd'|, -where \verb|ddd| is a sequence of up to three \emph{decimal} digits. +through the escape sequence `\verb|\|\emph{ddd}', +where \emph{ddd} is a sequence of up to three \emph{decimal} digits. Strings in Lua may contain any 8-bit value, including embedded zeros, -which can be specified as \verb|'\000'|. +which can be specified as `\verb|\000|'. Literal strings can also be delimited by matching \verb|[[| \dots\ \verb|]]|. Literals in this bracketed form may run for several lines, -may contain nested \verb|[[ ... ]]| pairs, +may contain nested \verb|[[| \dots\ \verb|]]| pairs, and do not interpret escape sequences. This form is specially convenient for writing strings that contain program pieces or @@ -439,25 +454,24 @@ other quoted strings. As an example, in a system using ASCII, the following three literals are equivalent: \begin{verbatim} -1) "alo\n123\"" -2) '\97lo\10\04923"' -3) [[alo - 123"]] + 1) "alo\n123\"" + 2) '\97lo\10\04923"' + 3) [[alo + 123"]] \end{verbatim} - -\Index{Comments} start anywhere outside a string with a +\IndexEmph{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 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, +\IndexEmph{Numerical constants} may be written with an optional decimal part and an optional decimal exponent. Examples of valid numerical constants are \begin{verbatim} - 3 3.0 3.1416 314.16e-2 0.31416E1 + 3 3.0 3.1416 314.16e-2 0.31416E1 \end{verbatim} \subsection{\Index{Coercion}} \label{coercion} @@ -490,7 +504,7 @@ then the excess values are thrown away. If there are less values than are needed, then the list is extended with as many \nil's as needed. This adjustment occurs in multiple assignments \see{assignment} -and function calls \see{functioncall}. +and in function calls \see{functioncall}. \subsection{Statements}\label{stats} @@ -505,7 +519,7 @@ and local variable declarations \see{localvar}. \subsubsection{Blocks} A \Index{block} is a list of statements; -syntatically, this is equal to a chunk: +syntactically, a block is equal to a chunk: \begin{Produc} \produc{block}{chunk} \end{Produc}% @@ -518,15 +532,15 @@ This is useful to control the scope of local variables \see{localvar}, and to add a \rwd{return} or \rwd{break} statement in the middle of another block; for instance, \begin{verbatim} - do return end -- return is the last statement in this block + do return end -- return is the last statement in this block \end{verbatim} \subsubsection{\Index{Assignment}} \label{assignment} -The language allows \Index{multiple assignment}. +Lua allows \Index{multiple assignment}. Therefore, the syntax for assignment defines a list of variables on the left side and a list of expressions on the right side. -Both lists have their elements separated by commas: +The elements in both lists are separated by commas: \begin{Produc} \produc{stat}{varlist1 \ter{=} explist1} \produc{varlist1}{var \rep{\ter{,} var}} @@ -536,14 +550,16 @@ and eventual indices on the left side, and then makes the assignments. So \begin{verbatim} - i = 3 - i, a[i] = 4, 20 + i = 3 + i, a[i] = 4, 20 \end{verbatim} -sets \verb|a[3]| to 20, but does not affect \verb|a[4]|. +sets \verb|a[3]| to 20, but does not affect \verb|a[4]| +because the \verb|i| in \verb|a[i]| is evaluated +before it is assigned \verb|4|. Multiple assignment can be used to exchange two values, as in \begin{verbatim} - x, y = y, x + x, y = y, x \end{verbatim} The two lists in a multiple assignment may have different lengths. @@ -578,11 +594,11 @@ 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 complete description of these functions. -(The function \verb|setglobal| is pre-defined in Lua. +(The function \verb|setglobal| is defined in the basic library. The function \T{settable\_event} is used only for explanatory purposes.) \subsubsection{Control Structures} -The control structures +The control structures \index{while-do}\index{repeat-until}\index{if-then-else}% \T{if}, \T{while}, and \T{repeat} have the usual meaning and familiar syntax: @@ -632,20 +648,20 @@ The numerical \rwd{for} loop has the following syntax: \end{Produc}% A \rwd{for} statement like \begin{verbatim} - for var=e1,e2,e3 do block end + for var = e1 ,e2, e3 do block end \end{verbatim} -is equivalent to the following code: +is equivalent to the code: \begin{verbatim} - do - local var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3) - if not (var and _limit and _step) then error() end - while (_step>0 and var<=_limit) or (_step<=0 and var>=_limit) do - block - var = var+_step - end - end + do + local var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3) + if not (var and _limit and _step) then error() end + while (_step>0 and var<=_limit) or (_step<=0 and var>=_limit) do + block + var = var+_step + end + end \end{verbatim} -Notice the following: +Note the following: \begin{itemize}\itemsep=0pt \item \verb|_limit| and \verb|_step| are invisible variables. The names are here for explanatory purposes only. @@ -662,7 +678,7 @@ assign it to another variable before breaking. \end{itemize} The table \rwd{for} statement traverses all pairs -index--value of a given table. +(index,value) of a given table. It has the following syntax: \begin{Produc} \produc{stat}{\rwd{for} name \ter{,} name \rwd{in} exp1 @@ -670,34 +686,33 @@ It has the following syntax: \end{Produc}% A \rwd{for} statement like \begin{verbatim} - for index, value in exp do block end + for index, value in exp do block end \end{verbatim} -is equivalent to the following code: +is equivalent to the code: \begin{verbatim} - do - local _t = exp - local index, value = next(t, nil) - while index do - block - index, value = next(t, index) - end - end + do + local _t = exp + local index, value = next(t, nil) + while index do + block + index, value = next(t, index) + end + end \end{verbatim} -Notice the following: +Note the following: \begin{itemize}\itemsep=0pt \item \verb|_t| is an invisible variable. The name is here for explanatory purposes only. -\item The behavior is undefined if you assign to \verb|index| inside +\item The behavior is \emph{undefined} if you assign to \verb|index| inside the block. -\item The behavior is undefined if you create -new indices in table \verb|_t| during the traversal. -However, it is safe to change the values associated with present indices. +\item The behavior is \emph{undefined} if you change +the table \verb|_t| during the traversal. \item The variables \verb|index| and \verb|value| are local to the statement; you cannot use their values after the \rwd{for} ends. \item You can use \rwd{break} to exit a \rwd{for}. If you need the value of \verb|index| or \verb|value|, assign them to other variables before breaking. -\item The order that table elements are traversed is completely undefined, +\item The order that table elements are traversed is undefined, \emph{even for numerical indices}. If you want to traverse indices in numerical order, use a numerical \rwd{for}. @@ -725,6 +740,9 @@ If present, an initial assignment has the same semantics of a multiple assignment. Otherwise, all variables are initialized with \nil. +A chunk is also a block, +so local variables can be declared outside any explicit block. + The scope of local variables begins \emph{after} the declaration and lasts until the end of the block. Thus, the code @@ -762,7 +780,7 @@ 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 \verb|getglobal| is defined in the basic library. Function \T{gettable\_event} is used only for explanatory purposes.) The non-terminal \M{exp1} is used to indicate that the values @@ -775,7 +793,7 @@ returned by an expression must be adjusted to one single value: Lua supports the usual \Index{arithmetic operators}: the binary \verb|+| (addition), \verb|-| (subtraction), \verb|*| (multiplication), -\verb|/| (division) and \verb|^| (exponentiation), +\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 \See{coercion}), @@ -787,13 +805,13 @@ giving the expected meaning to \Index{exponentiation} \see{mathlib}. \subsubsection{Relational Operators} -Lua provides the following \Index{relational operators}: +The \Index{relational operators} in Lua are \begin{verbatim} - == ~= < > <= >= + == ~= < > <= >= \end{verbatim} -All these return \nil\ as false and a value different from \nil\ as true. +These operators return \nil\ as false and a value different from \nil\ as true. -Equality first compares the tags of its operands. +Equality (\verb|==|) first compares the tags 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. @@ -807,6 +825,7 @@ The conversion rules of \See{coercion} Thus, \verb|"0"==0| evaluates to \emph{false}, and \verb|t[0]| and \verb|t["0"]| denote different entries in a table. +\medskip The order operators work as follows. If both arguments are numbers, then they are compared as such. @@ -815,13 +834,14 @@ then their values are compared using lexicographical order. Otherwise, the ``lt'' tag method is called \see{tag-method}. \subsubsection{Logical Operators} -The \Index{logical operators} are +The \Index{logical operators} in Lua are \index{and}\index{or}\index{not} \begin{verbatim} - and or not + and or not \end{verbatim} -Like control structures, all logical operators +Like the control structures, all logical operators consider \nil\ as false and anything else as true. + The conjunction operator \verb|and| returns \nil\ if its first argument is \nil; otherwise, it returns its second argument. The disjunction operator \verb|or| returns its first argument @@ -831,40 +851,46 @@ Both \verb|and| and \verb|or| use \Index{short-cut evaluation}, that is, the second operand is evaluated only when necessary. -There are two useful Lua idioms with logical operators. -The first idiom is \verb|x = x or v|, +There are two useful Lua idioms that use logical operators. +The first idiom is +\begin{verbatim} + x = x or v +\end{verbatim} which is equivalent to \begin{verbatim} - if x == nil then x = v end + if x == nil then x = v end \end{verbatim} -i.e., it sets \verb|x| to a default value \verb|v| when -\verb|x| is not set. -The other idiom is \verb|x = a and b or c|, -which should be read as \verb|x = a and (b or c)|, -is equivalent to +This idiom sets \verb|x| to a default value \verb|v| when \verb|x| is not set. + +The second idiom is \begin{verbatim} - if a then x = b else x = c end + x = a and b or c +\end{verbatim} +which should be read as \verb|x = a and (b or c)|. +This idiom is equivalent to +\begin{verbatim} + if a then x = b else x = c end \end{verbatim} provided that \verb|b| is not \nil. -\subsubsection{Concatenation} +\subsubsection{Concatenation} \label{concat} The string \Index{concatenation} operator in Lua is -denoted by ``\IndexVerb{..}''. -If both operands are strings or numbers, they are converted to +denoted by two dots (`\IndexVerb{..}'). +If both operands are strings or numbers, then they are converted to strings according to the rules in \See{coercion}. Otherwise, the ``concat'' tag method is called \see{tag-method}. \subsubsection{Precedence} -\Index{Operator precedence} follows the table below, +\Index{Operator precedence} in Lua follows the table below, from the lower to the higher priority: \begin{verbatim} - and or - < > <= >= ~= == - .. - + - - * / - not - (unary) - ^ + and or + < > <= >= ~= == + .. + + - + * / + not - (unary) + ^ \end{verbatim} All binary operators are left associative, except for \verb|^| (exponentiation), @@ -899,17 +925,17 @@ The expressions in the list are assigned to consecutive numerical indices, starting with 1. For example, \begin{verbatim} - a = {"v1", "v2", 34} + a = {"v1", "v2", 34} \end{verbatim} is equivalent to \begin{verbatim} - do - local temp = {} - temp[1] = "v1" - temp[2] = "v2" - temp[3] = 34 - a = temp - end + do + local temp = {} + temp[1] = "v1" + temp[2] = "v2" + temp[3] = 34 + a = temp + end \end{verbatim} The form \emph{ffieldlist1} initializes other fields in a table: @@ -919,18 +945,18 @@ The form \emph{ffieldlist1} initializes other fields in a table: \end{Produc}% For example, \begin{verbatim} - a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} + a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} \end{verbatim} is equivalent to \begin{verbatim} - do - local 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 + do + local 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 \end{verbatim} An expression like \verb|{x = 1, y = 4}| is in fact syntactic sugar for \verb|{["x"] = 1, ["y"] = 4}|. @@ -940,14 +966,14 @@ and can be used in the same constructor separated by a semi-colon. For example, all forms below are correct. \begin{verbatim} - x = {;} - x = {"a", "b",} - x = {type="list"; "a", "b"} - x = {f(0), f(1), f(2),; n=3,} + x = {;} + x = {"a", "b",} + x = {type="list"; "a", "b"} + x = {f(0), f(1), f(2),; n=3,} \end{verbatim} \subsubsection{Function Calls} \label{functioncall} -A \Index{function call} has the following syntax: +A \Index{function call} in Lua has the following syntax: \begin{Produc} \produc{functioncall}{varorfunc args} \end{Produc}% @@ -964,12 +990,9 @@ The form \produc{functioncall}{varorfunc \ter{:} name args} \end{Produc}% can be used to call ``methods''. -A call \verb|varorfunc:name(...)| -is syntactic sugar for -\begin{verbatim} - varorfunc.name(varorfunc, ...) -\end{verbatim} -except that \verb|varorfunc| is evaluated only once. +A call \verb|v:name(...)| +is syntactic sugar for \verb|v.name(v, ...)|, +except that \verb|v| is evaluated only once. Arguments have the following syntax: \begin{Produc} @@ -1003,16 +1026,16 @@ then no adjustment is made. The only places that can hold many values is the last (or the only) expression in an assignment, in an argument list, or in a return statement. -Here are some examples. +Here are some examples: \begin{verbatim} - f(); -- adjusted to 0 results - g(f(), x); -- f() is adjusted to 1 result - g(x, f()); -- g gets x plus all values returned by f() - a,b,c = f(), x; -- f() is adjusted to 1 result (and c gets nil) - a,b,c = x, f(); -- f() is adjusted to 2 - a,b,c = f(); -- f() is adjusted to 3 - return f(); -- returns all values returned by f() - return x,y,f(); -- returns a, b, and all values returned by f() + f(); -- adjusted to 0 results + g(f(), x); -- f() is adjusted to 1 result + g(x, f()); -- g gets x plus all values returned by f() + a,b,c = f(), x; -- f() is adjusted to 1 result (and c gets nil) + a,b,c = x, f(); -- f() is adjusted to 2 + a,b,c = f(); -- f() is adjusted to 3 + return f(); -- returns all values returned by f() + return x,y,f(); -- returns a, b, and all values returned by f() \end{verbatim} \subsubsection{\Index{Function Definitions}} \label{func-def} @@ -1027,33 +1050,25 @@ The syntax for function definition is \end{Produc}% The statement \begin{verbatim} - function f () - ... - end + function f () ... end \end{verbatim} is just syntactic sugar for \begin{verbatim} - f = function () - ... - end + f = function () ... end \end{verbatim} and the statement \begin{verbatim} - function o.f () - ... - end + function v.f () ... end \end{verbatim} is syntactic sugar for \begin{verbatim} - o.f = function () - ... - end + v.f = function () ... end \end{verbatim} A function definition is an executable expression, whose value has type \emph{function}. When Lua pre-compiles a chunk, -all its function bodies are pre-compiled, too. +all its function bodies are pre-compiled too. Then, whenever Lua executes the function definition, its upvalues are fixed \see{upvalue}, and the function is \emph{instantiated} (or \emph{closed}). @@ -1074,7 +1089,7 @@ 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, which is -indicated by the dots (\ldots) at the end of its parameter list. +indicated by three dots (`\verb|...|') at the end of its parameter list. A vararg function does not adjust its argument list; instead, it collects all extra arguments into an implicit parameter, called \IndexVerb{arg}. @@ -1084,24 +1099,24 @@ and the extra arguments at positions 1,~2,~\ldots,\M{n}. As an example, consider the following definitions: \begin{verbatim} - function f(a, b) end - function g(a, b, ...) end - function r() return 1,2,3 end + function f(a, b) end + function g(a, b, ...) end + function r() return 1,2,3 end \end{verbatim} Then, we have the following mapping from arguments to parameters: \begin{verbatim} - CALL PARAMETERS + CALL PARAMETERS - f(3) a=3, b=nil - f(3, 4) a=3, b=4 - f(3, 4, 5) a=3, b=4 - f(r(), 10) a=1, b=10 - f(r()) a=1, b=2 + f(3) a=3, b=nil + f(3, 4) a=3, b=4 + f(3, 4, 5) a=3, b=4 + f(r(), 10) a=1, b=10 + f(r()) a=1, b=2 - g(3) a=3, b=nil, arg={n=0} - g(3, 4) a=3, b=4, arg={n=0} - g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2} - g(5, r()) a=5, b=1, arg={2, 3; n=2} + g(3) a=3, b=nil, arg={n=0} + g(3, 4) a=3, b=4, arg={n=0} + g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2} + g(5, r()) a=5, b=1, arg={2, 3; n=2} \end{verbatim} Results are returned using the \rwd{return} statement \see{return}. @@ -1113,22 +1128,18 @@ The syntax \begin{Produc} \produc{funcname}{name \ter{:} name} \end{Produc}% -is used for defining \Index{methods}, +is used for defining \IndexEmph{methods}, that is, functions that have an implicit extra parameter \IndexVerb{self}: Thus, the statement \begin{verbatim} - function v:f (...) - ... - end + function v:f (...) ... end \end{verbatim} is equivalent to \begin{verbatim} - v.f = function (self, ...) - ... - end + v.f = function (self, ...) ... end \end{verbatim} -that is, the function gets an extra formal parameter called \verb|self|. -Note that the variable \verb|v| must have been +Note that the function gets an extra formal parameter called \verb|self|. +Note also that \verb|v| must have been previously initialized with a table value. @@ -1153,32 +1164,34 @@ but whose value is \emph{frozen} when the function wherein it appears is instantiated. The name used in an upvalue may be the name of any variable visible at the point where the function is defined, -that is +that is, global variables and local variables from the immediately enclosing function. -Notice that when the upvalue is a table, -only the reference to that table +Note that when the upvalue is a table, +only the \emph{reference} to that table (which is the value of the upvalue) is frozen; the table contents can be changed at will. +Using table values as upvalues is a technique for having +writable but private state attached to functions. Here are some examples: \begin{verbatim} - a,b,c = 1,2,3 -- global variables - local d - function f (x) - local b = {} -- x and b are local to f; b shadows the global b - local g = function (a) - local y -- a and y are local to g - p = a -- OK, access local 'a' - p = c -- OK, access global 'c' - p = b -- ERROR: cannot access a variable in outer scope - p = %b -- OK, access frozen value of 'b' (local to 'f') - %b = 3 -- ERROR: cannot change an upvalue - %b.x = 3 -- OK, change the table contents - p = %c -- OK, access frozen value of global 'c' - p = %y -- ERROR: 'y' is not visible where 'g' is defined - p = %d -- ERROR: 'd' is not visible where 'g' is defined - end -- g - end -- f + a,b,c = 1,2,3 -- global variables + local d + function f (x) + local b = {} -- x and b are local to f; b shadows the global b + local g = function (a) + local y -- a and y are local to g + p = a -- OK, access local `a' + p = c -- OK, access global `c' + p = b -- ERROR: cannot access a variable in outer scope + p = %b -- OK, access frozen value of `b' (local to `f') + %b = 3 -- ERROR: cannot change an upvalue + %b.x = 3 -- OK, change the table contents + p = %c -- OK, access frozen value of global `c' + p = %y -- ERROR: `y' is not visible where `g' is defined + p = %d -- ERROR: `d' is not visible where `g' is defined + end -- g + end -- f \end{verbatim} @@ -1195,27 +1208,28 @@ and then the corresponding function from the library \verb|lua_dobuffer|, or \verb|lua_callfunction|) is terminated, returning an error condition. -Memory allocation error is an exception to the previous rule. -When a \verb|malloc| fails, Lua may not be able to execute the +Memory allocation errors are an exception to the previous rule. +When memory allocation fails, Lua may not be able to execute the \verb|_ERRORMESSAGE| function. So, for this kind of error, Lua does not call the \verb|_ERRORMESSAGE| function; instead, the corresponding function from the library -returns immeditely with a special error code. +returns immediately with a special error code (\verb|LUA_ERRMEM|). +This and other error codes are defined in \verb|lua.h|. The only argument to \verb|_ERRORMESSAGE| is a string describing the error. The default definition for this function calls \verb|_ALERT|, \Deffunc{_ALERT} which prints the message to \verb|stderr| \see{alert}. -The standard I/O library redefines \verb|_ERRORMESSAGE|, +The standard I/O library redefines \verb|_ERRORMESSAGE| and uses the debug facilities \see{debugI} to print some extra information, such as a call stack traceback. -Lua code can explicitly generate an error by calling the built-in +Lua code can explicitly generate an error by calling the function \verb|error| \see{pdf-error}. -Lua code can ``catch'' an error using the built-in function +Lua code can ``catch'' an error using the function \verb|call| \see{pdf-call}. @@ -1238,7 +1252,7 @@ Its first parameter is the tag, the second parameter is the event name and the third parameter is the new method (a function), or \nil\ to restore the default behavior for the pair. The \verb|settagmethod| function returns the previous tag method for that pair. -Another function, \IndexVerb{gettagmethod}, +A companion function \IndexVerb{gettagmethod} receives a tag and an event name and returns the current method associated with the pair. @@ -1260,42 +1274,39 @@ are described in \See{predefined}. \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 +The function \verb|getbinmethod| below 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: +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 + function getbinmethod (op1, op2, event) + return gettagmethod(tag(op1), event) or + gettagmethod(tag(op2), event) or + gettagmethod(0, event) + end \end{verbatim} Using this function, -the tag method for the ``add' event is +the tag method for the ``add'' event is \begin{verbatim} - function add_event (op1, op2) - local o1, o2 = tonumber(op1), tonumber(op2) - if o1 and o2 then -- both operands are numeric - return o1+o2 -- '+' here is the primitive 'add' - else -- at least one of the operands is not numeric - local 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 + 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} -All global variables are kept in a table. -You can get this table calling the \verb|globals| function. - \item[``sub'':]\index{sub event} called when a \verb|-| operation is applied to non-numerical operands. Behavior similar to the ``add'' event. @@ -1309,41 +1320,42 @@ called when a \verb|/| operation is applied to non-numerical operands. Behavior similar to the ``add'' event. \item[``pow'':]\index{pow event} -called when a \verb|^| operation (exponentiation) is applied. +called when a \verb|^| operation (exponentiation) is applied, +even for numerical operands. \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 + 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 a 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 + 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} @@ -1351,51 +1363,51 @@ called when an order operation is applied to non-numerical or non-string operands. It corresponds to the \verb|<| operator. \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 + 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} The other order operators use this tag method according to the usual equivalences: \begin{verbatim} - a>b <=> b not (b=b <=> not (ab <=> b not (b=b <=> not (a