From e0ff4e5d22bd2dbe74dd588f0710c18ae8a671ab Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Mon, 29 Mar 1999 11:21:37 -0300 Subject: [PATCH] first version about Lua debug library. --- manual.tex | 210 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 172 insertions(+), 38 deletions(-) diff --git a/manual.tex b/manual.tex index 3c550cd7..90fa12a2 100644 --- a/manual.tex +++ b/manual.tex @@ -1,4 +1,4 @@ -% $Id: manual.tex,v 1.26 1999/03/10 14:09:45 roberto Exp roberto $ +% $Id: manual.tex,v 1.27 1999/03/11 19:00:12 roberto Exp roberto $ \documentclass[11pt]{article} \usepackage{fullpage,bnf} @@ -41,7 +41,7 @@ Waldemar Celes \tecgraf\ --- Computer Science Department --- PUC-Rio } -%\date{\small \verb$Date: 1999/03/10 14:09:45 $} +%\date{\small \verb$Date: 1999/03/11 19:00:12 $} \maketitle @@ -2624,8 +2624,8 @@ When called with two arguments, \Math{l} and \Math{u}, \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. +All input and output operations in Lua are done, by default, +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 @@ -2638,20 +2638,45 @@ Initially, \verb|_INPUT=_STDIN| and \verb|_OUTPUT=_STDOUT|. A file handle is a userdata containing the file stream \verb|FILE*|, and with a distinctive tag created by the I/O library. - +Whenever a file handle is collected by the garbage collector, +its correspondent stream is automatically closed. Unless otherwise stated, all I/O functions return \nil\ on failure and some value different from \nil\ on success. -\subsubsection*{\ff \T{readfrom (filename [, mode])}}\Deffunc{readfrom} +\subsubsection*{\ff \T{openfile (filename, mode)}}\Deffunc{openfile} + +This function opens a file, +in the mode specified in the string \verb|mode|. +It returns a new file handle, +or, in case of errors, \nil\ plus a string describing the error. +This function does not modify neither \verb|_INPUT| nor \verb|_OUTPUT|. + +The string mode can be any of the following: +\begin{description} +\item["r"] read mode; +\item["w"] write mode; +\item["a"] append mode; +\item["r+"] update mode, all previous data is preserved; +\item["w+"] update mode, all previous data is erased; +\item["a+"] append update mode, previous data is preserved, + writing is only allowed at the end of file. +\end{description} +The string mode may also have a \verb|b| at the end, +which is needed in some systems to open the file in binary mode. + +\subsubsection*{\ff \T{closefile (handle)}}\Deffunc{closefile} + +This function closes the given file. +It does not modify neither \verb|_INPUT| nor \verb|_OUTPUT|. + +\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. -An optional \verb|mode| argument with the string \verb|"binary"| -opens file in binary mode (where this applies). It does not close the current input file. When called without parameters, it closes the \verb|_INPUT| file, @@ -2670,15 +2695,13 @@ 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 [, mode])}}\Deffunc{writeto} +\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. -An optional \verb|mode| argument with the string \verb|"binary"| -opens file in binary mode (where this applies). It does not close the current output file. Note that, if the file already exists, then it will be \emph{completely erased} with this operation. @@ -2700,20 +2723,15 @@ 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 [, mode])}}\Deffunc{appendto} +\subsubsection*{\ff \T{appendto (filename)}}\Deffunc{appendto} Opens a file named \verb|filename| and sets it as the value of \verb|_OUTPUT|. -An optional \verb|mode| argument with the string \verb|"binary"| -opens file in binary mode (where this applies). 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. -Note that function \verb|writeto| is -available to close an output file opened by \verb|appendto|. - \subsubsection*{\ff \T{remove (filename)}}\Deffunc{remove} Deletes the file with the given name. @@ -2741,9 +2759,9 @@ measured in bytes from the beginning of the file, to the position given by \verb|offset| plus a base specified by the string \verb|whence|, as follows: \begin{description} -\item[\tt "set"] base is position 0 (beginning of the file); -\item[\tt "cur"] base is current position; -\item[\tt "end"] base is end of file; +\item["set"] base is position 0 (beginning of the file); +\item["cur"] base is current position; +\item["end"] base is end of file; \end{description} In case of success, function \verb|seek| returns the final file position, measured in bytes from the beginning of the file. @@ -2765,18 +2783,17 @@ 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 ([filehandle] [readpattern])}}\Deffunc{read} +\subsubsection*{\ff \T{read ([filehandle] {readpattern})}}\Deffunc{read} Reads file \verb|_INPUT|, or \verb|filehandle| if this argument is given, -according to a read pattern, which specifies how much to read; -characters are read from the input file until -the read pattern fails or ends. -The function \verb|read| returns a string with the characters read, +according to read patterns, which specify how much to read. +For each pattern, +the function 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, +When called without patterns, it uses a default pattern that reads the next line (see below). @@ -2803,20 +2820,21 @@ 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 +There are some predefined patterns, as follows: +\begin{description} +\item["*n"] reads a number; +this is the only pattern that returns a number instead of a string. +\item["*l"] 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 +It is equivalent to the pattern \verb|"[^\n]*{\n}"|. +\item["*a"] reads the whole file. +It is equivalent to the pattern \verb|".*"|. +\item["*w"] 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} +skipping spaces if necessary, or \nil\ on end of file. +It is equivalent to the pattern \verb|"{%s*}%S%S*"|. +\end{description} \subsubsection*{\ff \T{write ([filehandle, ] value1, ...)}}\Deffunc{write} @@ -3010,7 +3028,7 @@ 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 +This second hook is called only if the active function has been compiled with debug information \see{pragma}. A hook is disabled when its value is \verb|NULL|, @@ -3020,6 +3038,122 @@ set their corresponding hooks and return their previous values. +\subsection{The Reflexive Debugger Interface} + +The library \verb|ldblib| provides +the functionallity of the debugger interface to Lua programs. +If you want to use this library, +your host application must open it first, +calling \verb|lua_dblibopen|. + +You should exert great care when using this library. +Functions provided here should be used exclusively for debugging +and similar tasks (e.g. profiling): +Please resist the temptation to use them as a +usual programming tool. +They are slow and violate some (otherwise) secure aspects of the +language (e.g. privacy of local variables). +As a general rule, if your program does not need this library, +do not open it. + + +\subsubsection*{\ff \T{funcinfo (function)}}\Deffunc{funcinfo} + +This function returns a table with information about the given function. +The table contains the following fields: +\begin{description} +\item[kind]: may be \verb|"C"|, if this is a C function, +\verb|"chunk"|, if this is the main part of a chunk, +or \verb|"Lua"| if this is a Lua function. + +\item[source] the source where the function was defined. +If the function was defined in a string, +\verb|source| is that string; +If the function was defined in a file, +\verb|source| starts with a \verb|@| followed by the file name. + +\item[def_line] the line where the function was defined in the source +(only valid if this is a Lua function). + +\item[where] can be \verb|"global"| if this function has a global name, +or \verb|"tag-method"| if this function is a tag method handler. + +\item[name] if \verb|where| = \verb|global|, +\verb|name| is the global name of the function; +if \verb|where| = \verb|tag-method|, +\verb|name| is the event name of the tag method. +\end{description} + +\subsubsection*{\ff \T{getstack (index)}}\Deffunc{getstack} + +This function returns a table with informations about the function +running at level \verb|index| of the stack. +Index 0 is the current function (\verb|getstack| itself). +If \verb|index| is bigger than the number of active functions, +the function returns \nil. +The table contains all the fields returned by \verb|funcinfo|, +plus the following: +\begin{description} +\item[func] the function at that level. +\item[current] the current line on the function execution; +this will be available only when the function is +precompiled with debug information. +\end{description} + +\subsubsection*{\ff \T{getlocal (index [, local])}}\Deffunc{getlocal} + +This function returns information about the local variables of the +function at level \verb|index| of the stack. +It can be called in three ways. +When called without a \verb|local| argument, +it returns a table, which associates variable names to their values. +When called with a name (a string) as \verb|local|, +it returns the value of the local variable with that name. +Finally, when called with an index (a number), +it returns the value and the name of the local variable +with that index. +(The first parameter has index 1, and so on, +until the last active local variable.) +In that case, the function returns \nil\ if there is no local +variable with the given index. +The specification by index is the only way to distinguish +homonym variables in a function. + +\subsubsection*{\ff \T{setlocal (index, local, newvalue)}}\Deffunc{setlocal} + +This function changes the values of the local variables of the +function at level \verb|index| of the stack. +The local variable can be specified by name or by index; +see function \verb|getlocal|. + +\subsubsection*{\ff \T{setcallhook (hook)}}\Deffunc{setcallhook} + +Sets the function \verb|hook| as the call hook; +this hook will be called every time the interpreter starts and +exits the execution of a function. +When Lua enters a function, +the hook is called with the function been called, +plus the source and the line where the function is defined. +When Lua exits a function, +the hook is called with no arguments. + +When called without arguments, +this function turns off call hooks. + +\subsubsection*{\ff \T{setlinehook (hook)}}\Deffunc{setlinehook} + +Sets the function \verb|hook| as the line hook; +this hook will be called every time the interpreter changes +the line of code it is executing. +The only argument to the hook is the line number the interpreter +is about to execut. +This hook is called only if the active function +has been compiled with debug information \see{pragma}. + +When called without arguments, +this function turns off line hooks. + + \section{\Index{Lua Stand-alone}} \label{lua-sa} Although Lua has been designed as an extension language,