towards 5.0 alpha...

manual.tex

@@ -1,4 +1,4 @@
-% $Id: manual.tex,v 1.56 2002/06/06 12:49:28 roberto Exp roberto $
+% $Id: manual.tex,v 1.57 2002/08/06 19:10:44 roberto Exp roberto $
 
 \documentclass[11pt,twoside,draft]{article}
 \usepackage{fullpage}
@@ -133,7 +133,7 @@ Waldemar Celes
 \tecgraf\ --- Computer Science Department --- PUC-Rio
 }
 
-%\date{{\small \tt\$Date: 2002/06/06 12:49:28 $ $}}
+%\date{{\small \tt\$Date: 2002/08/06 19:10:44 $ $}}
 
 \maketitle
 
@@ -251,6 +251,8 @@ The evolution of an extension language: a history of Lua,
 \emph{Proceedings of V Brazilian Symposium on Programming Languages} (2001) B-14--B-28.
 \end{itemize}
 
+Lua means ``moon'' in Portuguese.
+
 %------------------------------------------------------------------------------
 \section{Lua Concepts}\label{concepts}
 
@@ -293,6 +295,10 @@ Lua automatically detects the file type and acts accordingly.
 \index{pre-compilation}
 
 
+\subsection{Table of Globals} \label{global-table}
+
+????
+
 \subsection{\Index{Values and Types}} \label{TypesSec}
 
 Lua is a \emph{dynamically typed language}.
@@ -331,7 +337,7 @@ and has no pre-defined operations in Lua,
 except assignment and identity test.
 However, by using \emph{metatables},
 the programmer can define operations for userdata values
-\see{metatables}.
+\see{metatable}.
 Userdata values cannot be created or modified in Lua,
 only through the C~API.
 This guarantees the integrity of data owned by the host program.
@@ -966,7 +972,7 @@ Tables, userdata, and functions are compared \emph{by reference},
 that is,
 two tables are considered equal only if they are the \emph{same} table.
 
-??eq metamethod??
+%% TODO eq metamethod
 
 Every time you create a new table (or userdata, or function),
 this new value is different from any previously existing value.
@@ -1358,43 +1364,18 @@ while all of them share the same \verb|x|.
 
 \subsection{Error Handling} \label{error}
 
-%% TODO Must be rewritten!!!
-
 Because Lua is an extension language,
 all Lua actions start from C~code in the host program
-calling a function from the Lua library.
+calling a function from the Lua library \see{pcall}.
 Whenever an error occurs during Lua compilation or execution,
-the function \verb|_ERRORMESSAGE| is called \DefLIB{_ERRORMESSAGE}
-(provided it is different from \nil),
-and then the corresponding function from the library
-(\verb|lua_dofile|, \verb|lua_dostring|,
-\verb|lua_dobuffer|, or \verb|lua_call|)
-is terminated, returning an error condition.
-
-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 immediately with a special error code (\verb|LUA_ERRMEM|).
-This and other error codes are defined in \verb|lua.h|
-\see{luado}.
-
-The only argument to \verb|_ERRORMESSAGE| is a string
-describing the error.
-The default definition for
-this function calls \verb|_ALERT|, \DefLIB{_ALERT}
-which prints the message to \verb|stderr| \see{alert}.
-The standard I/O library redefines \verb|_ERRORMESSAGE|
-and uses the debug interface \see{debugI}
-to print some extra information,
-such as a call-stack traceback.
+control returns to C,
+which can take appropriate measures
+(such as to print an error message).
 
 Lua code can explicitly generate an error by calling the
 function \verb|error| \see{pdf-error}.
-Lua code can ``catch'' an error using the function
-\verb|call| \see{pdf-call}.
+If you need to catch errors in Lua,
+you can use the \verb|pcall| function \see{pdf-pcall}.
 
 
 \subsection{Metatables} \label{metatable}
@@ -2161,14 +2142,32 @@ when applied on a non-userdata value, it returns \verb|NULL|.
 
 When Lua collects a full userdata,
 it calls its \verb|gc| metamethod, if any,
-and then it automatically frees its corresponding memory.
+and then it frees its corresponding memory.
 
 
 \subsection{Metatables}
 
-%% TODO
+The following functions allow you do manipulate the metatables
+of an object:
+\begin{verbatim}
+       int lua_getmetatable (lua_State *L, int objindex);
+       int lua_setmetatable (lua_State *L, int objindex);
+\end{verbatim}
+\DefAPI{lua_getmetatable}\DefAPI{lua_setmetatable}
+Both get at \verb|objindex| a valid index for an object.
+\verb|lua_getmetatable| pushes on the stack the metatable of that object;
+\verb|lua_setmetatable| sets the table on the top of the stack as the
+new metatable for that object (and pops the table).
+
+If the object does not have a metatable,
+\verb|lua_getmetatable| returns 0, and pushes nothing on the stack.
+\verb|lua_setmetatable| returns 0 when it cannot
+set the metatable of the given object
+(that is, when the object is not a userdata nor a table);
+even then it pops the table from the stack.
 
 \subsection{Loading Lua Chunks}
+
 You can load a Lua chunk with
 \begin{verbatim}
        typedef const char * (*lua_Chunkreader)
@@ -2183,9 +2182,10 @@ Everytime it needs another piece of the chunk,
 it calls the reader,
 passing along its \verb|data| parameter.
 The reader must return a pointer to a block of memory
-with the part of the chunk,
+with a new part of the chunk,
 and set \verb|size| to the block size.
 To signal the end of the chunk, the reader must return \verb|NULL|.
+The reader function may return pieces of any size greater than zero.
 
 In the current implementation,
 the reader function cannot call any Lua function;
@@ -2214,43 +2214,6 @@ for examples of how to use \verb|lua_load|,
 and for some ready-to-use functions to load chunks
 from files and from strings.
 
-
-\subsection{Executing Lua Chunks}\label{luado}
->>>>
-A host program can execute Lua chunks written in a file or in a string
-by using the following functions:
-\begin{verbatim}
-       int lua_dofile   (lua_State *L, const char *filename);
-       int lua_dostring (lua_State *L, const char *string);
-       int lua_dobuffer (lua_State *L, const char *buff,
-                         size_t size, const char *name);
-\end{verbatim}
-\DefAPI{lua_dofile}\DefAPI{lua_dostring}\DefAPI{lua_dobuffer}%
-These functions return
-0 in case of success, or one of the following error codes
-(defined in \verb|lua.h|)
-if they fail:
-\begin{itemize}
-\item \IndexAPI{LUA_ERRRUN} ---
-error while running the chunk.
-\item \IndexAPI{LUA_ERRSYNTAX} ---
-syntax error during pre-compilation.
-\item \IndexAPI{LUA_ERRMEM} ---
-memory allocation error.
-For such errors, Lua does not call \verb|_ERRORMESSAGE| \see{error}.
-\item \IndexAPI{LUA_ERRERR} ---
-error while running \verb|_ERRORMESSAGE|.
-For such errors, Lua does not call \verb|_ERRORMESSAGE| again, to avoid loops.
-\item \IndexAPI{LUA_ERRFILE} ---
-error opening the file (only for \verb|lua_dofile|).
-In this case,
-you may want to
-check \verb|errno|,
-call \verb|strerror|,
-or call \verb|perror| to tell the user what went wrong.
-\end{itemize}
-
-
 \subsection{Manipulating Tables}
 
 Tables are created by calling
@@ -2426,7 +2389,54 @@ to show all the details.
 Usually programmers use several macros and auxiliar functions that
 provide higher level access to Lua.)
 
-%% TODO: pcall
+
+\subsection{Protected Calls}\label{pcall}
+
+When you call a function with \verb|lua_call|,
+any error inside the called function is propagated upwards
+(with a \verb|longjmp|).
+If you need to handle errors,
+then you should use \verb|lua_pcall|:
+\begin{verbatim}
+       int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
+\end{verbatim}
+Both \verb|nargs| and \verb|nresults| have the same meaning as
+in \verb|lua_call|.
+If there are no errors during the call,
+\verb|lua_pcall| behaves exactly like \verb|lua_call|.
+Like \verb|lua_call|,
+\verb|lua_pcall| always removes the function
+and its arguments from the stack.
+However, if there is any error,
+\verb|lua_pcall| catches it,
+pushes a single value at the stack (the error message),
+and returns an error code.
+
+If \verb|errfunc| is 0,
+then the error message returned is exactly the original error message.
+Otherwise, \verb|errfunc| gives the stack index for an
+\emph{error handler function}.
+(In the current implementation, that index cannot be a pseudo-index.)
+In case of runtime errors,
+that function will be called with the error message,
+and its return value will be the message returned by \verb|lua_pcall|.
+
+Typically, the error handler function is used to add more debug
+information to the error message, such as a stack traceback.
+Such information cannot be gathered after the return of \verb|lua_pcall|,
+since by then the stack has unwound.
+
+The \verb|lua_pcall| function returns 0 in case of success,
+or one of the following error codes
+(defined in \verb|lua.h|):
+\begin{itemize}
+\item \IndexAPI{LUA_ERRRUN} --- a runtime error.
+\item \IndexAPI{LUA_ERRMEM} --- memory allocation error.
+For such errors, Lua does not call the error handler function.
+\item \IndexAPI{LUA_ERRERR} ---
+error while running the error handler function.
+\end{itemize}
+
 
 \medskip
 
@@ -2494,8 +2504,10 @@ of numerical arguments and returns their average and sum:
          lua_Number sum = 0;
          int i;
          for (i = 1; i <= n; i++) {
-           if (!lua_isnumber(L, i))
-             lua_error(L, "incorrect argument to function `average'");
+           if (!lua_isnumber(L, i)) {
+             lua_pushstring(L, "incorrect argument to function `average'");
+             lua_error(L);
+           }
            sum += lua_tonumber(L, i);
          }
          lua_pushnumber(L, sum/n);        /* first result */
@@ -2565,8 +2577,8 @@ outside the life span of a C~function.
 This table is always located at pseudo-index
 \IndexAPI{LUA_REGISTRYINDEX}.
 Any C~library can store data into this table,
-as long as it chooses a key different from other libraries.
-Typically, you can use as key a string containing the library name,
+as long as it chooses keys different from other libraries.
+Typically, you should use as key a string containing your library name,
 or a light userdata with the address of a C object in your code.
 
 The integer keys in the registry are used by the reference mechanism,
@@ -2583,7 +2595,6 @@ 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 \verb|luadebug.h|.
 
 \subsection{Stack and Function Information}
 
@@ -2683,15 +2694,10 @@ 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.
-The \verb|lua_getinfo| function checks whether the given
-function is a tag method or the value of a global variable.
-If the given function is a tag method,
-then \verb|name| points to the event name.
-%% TODO: mas qual o tag? Agora que temos tipos com nome, seria util saber
-%% o tipo de TM. Em particular para mensagens de erro.
-If the given function is the value of a global variable,
-then \verb|name| points to the variable name.
-If the given function is neither a tag method nor a global variable,
+The \verb|lua_getinfo| function checks how the function was
+called or whether it is the value of a global variable to
+find a suitable name.
+If it cannot find a name,
 then \verb|name| is set to \verb|NULL|.
 
 \item[namewhat]
@@ -2727,7 +2733,6 @@ given as argument to a hook \see{sub-hooks}.
 \verb|lua_getlocal| gets the index \verb|n| of a local variable,
 pushes its value onto the stack,
 and returns its name.
-%% TODO: why return name?
 \verb|lua_setlocal| assigns the value at the top of the stack
 to the variable and returns its name.
 Both functions return \verb|NULL| on failure,
@@ -2860,33 +2865,6 @@ This function is equivalent to the following Lua function:
        end
 \end{verbatim}
 
-??\subsubsection*{\ff \T{call (func, arg [, mode [, errhandler]])}}\DefLIB{call}
-\label{pdf-call}
-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[n])
-\end{verbatim}
-where \verb|n| is the result of \verb|getn(arg)| \see{getn}.
-All results from \verb|func| are simply returned by \verb|call|.
-
-By default,
-if an error occurs during the call to \verb|func|,
-the error is propagated.
-If the string \verb|mode| contains \verb|"x"|,
-then the call is \emph{protected}.\index{protected calls}
-In this mode, function \verb|call| does not propagate an error,
-regardless of what happens during the call.
-Instead, it returns \nil{} to signal the error
-(besides calling the appropriated error handler).
-
-If \verb|errhandler| is provided,
-the error function \verb|_ERRORMESSAGE| is temporarily set to \verb|errhandler|,
-while \verb|func| runs.
-In particular, if \verb|errhandler| is \nil,
-no error messages will be issued during the execution of the called function.
-
 \subsubsection*{\ff \T{collectgarbage ([limit])}}\DefLIB{collectgarbage}
 
 Sets the garbage-collection threshold for the given limit
@@ -2935,6 +2913,16 @@ Returns the number of Kbytes of dynamic memory Lua is using,
 and (as a second result) the
 current garbage collector threshold (also in Kbytes).
 
+\subsubsection*{\ff \T{ipairs (t)}}\DefLIB{ipairs}
+
+Returns the table \verb|t| and a generator function
+so that the construction
+\begin{verbatim}
+       for i,v in ipairs(t) do ... end
+\end{verbatim}
+will iterate over the pairs \verb|1, t[1]|, \verb|2, t[2]|, \ldots,
+up to the first nil value of the table.
+
 \subsubsection*{\ff \T{loadfile (filename)}}\DefLIB{loadfile}
 Loads a file as a Lua chunk.
 If there is no errors, 
@@ -2982,6 +2970,24 @@ use a numerical \rwd{for} or the function \verb|ipairs|).
 The behavior of \verb|next| is \emph{undefined} if you change
 the table during the traversal.
 
+\subsubsection*{\ff \T{pairs (t)}}\DefLIB{pairs}
+
+Returns the table \verb|t| and the function \verb|next|,
+so that the construction
+\begin{verbatim}
+       for k,v in pairs(t) do ... end
+\end{verbatim}
+will iterate over all pairs of key--value of table \verb|t|.
+
+\subsubsection*{\ff \T{pcall (func, arg1, arg2, ...)}}\DefLIB{pcall}
+\label{pdf-pcall}
+Calls function \verb|func| with
+the given arguments in protected mode.
+Its first result is a boolean, true if the call succeeds without errors.
+In such case, \verb|pcall| also returns all results from the call,
+after this first result.
+In case of any error, \verb|pcall| returns false plus the error message.
+
 \subsubsection*{\ff \T{print (e1, e2, ...)}}\DefLIB{print}
 Receives any number of arguments,
 and prints their values in \verb|stdout|,
@@ -3225,6 +3231,10 @@ For example, \verb|"%*g"| can be simulated with
 String values to be formatted with
 \verb|%s| cannot contain embedded zeros.
 
+\subsubsection*{\ff \T{string.gfind (s, pat)}}
+
+% TODO
+
 \subsubsection*{\ff \T{string.gsub (s, pat, repl [, n])}}
 \DefLIB{string.gsub}
 Returns a copy of \verb|s|
@@ -3410,7 +3420,8 @@ that value is assumed as its size.
 You can call the \verb|table.setn| function to explicitly set
 the size of a table.
 \item implicit size ---
-%% TODO
+Otherwise, the size of the object is one less the first integer index
+with a \nil{} value.
 \end{itemize}
 For more details, see the descriptions of the \verb|table.getn| and
 \verb|table.setn| functions.
@@ -3977,9 +3988,9 @@ The program name is stored in index 0,
 the first argument after the program goes to index 1,
 and so on.
 The field \verb|n| gets the number of arguments after the program name.
-Any argument before the program name
-(that is, the options plus the interpreter name)
-goes to negative indices.
+Any arguments before the program name
+(that is, the interpreter name plus the options)
+go to negative indices.
 For instance, in the call
 \begin{verbatim}
        $ lua -la.lua b.lua t1 t2
@@ -4020,14 +4031,44 @@ then a more portable solution is \verb|#!/usr/bin/env lua|.)
 %------------------------------------------------------------------------------
 \section*{Acknowledgments}
 
-%% TODO rever isso?
-
-The authors thank CENPES/PETROBRAS which,
-jointly with \tecgraf, used early versions of
-this system extensively and gave valuable comments.
-The authors also thank Carlos Henrique Levy,
-who found the name of the game.
-Lua means ``moon'' in Portuguese.
+The Lua team is grateful to \tecgraf{} for its continued support to Lua.
+We thank everyone at \tecgraf{},
+specially the head of the group, Marcelo Gattass.
+At the risk of omitting several names,
+we also thank the following individuals for supporting,
+contributing to, and spreading the word about Lua:
+Alan Watson,
+Andr\'e Clinio,
+Andr\'e Costa,
+Bret Mogilefsky,
+Cameron Laird,
+Carlos Cassino,
+Carlos Henrique Levy,
+Claudio Terra,
+David Jeske,
+Edgar Toernig,
+Erik Hougaard,
+Jim Mathies,
+John Belmonte,
+John Passaniti,
+John Roll,
+Jon Erickson,
+Jon Kleiser,
+Mark Ian Barlow,
+Nick Trout,
+Noemi Rodriguez,
+Norman Ramsey,
+Philippe Lhost,
+Renata Ratton,
+Renato Borges,
+Renato Cerqueira,
+Reuben Thomas,
+Stephan Herrmann,
+Steve Dekorte,
+Thatcher Ulrich,
+Tom\'as Gorham,
+Vincent Penquerc'h.
+Thank you!
 
 
 \appendix
@@ -4035,12 +4076,6 @@ Lua means ``moon'' in Portuguese.
 \section*{Incompatibilities with Previous Versions}
 \addcontentsline{toc}{section}{Incompatibilities with Previous Versions}
 
-We took a great care to avoid incompatibilities with
-the previous public versions of Lua,
-but some differences had to be introduced.
-Here is a list of all these incompatibilities.
-
-
 \subsection*{Incompatibilities with \Index{version 4.0}}
 
 \subsubsection*{Changes in the Language}
@@ -4068,6 +4103,14 @@ this newline is ignored.
 \subsubsection*{Changes in the Libraries}
 \begin{itemize}
 
+\item
+Most library functions now are defined inside tables.
+There is a compatibility script (\verb|compat.lua|) that
+redefine most of them as global names.
+
+\item
+\verb|dofile| do not handle errors, but simply propagate them.
+
 \item
 The \verb|read| option \verb|*w| is obsolete.