summaryrefslogtreecommitdiff
path: root/manual.tex
diff options
context:
space:
mode:
authorRoberto Ierusalimschy <roberto@inf.puc-rio.br>2000-10-31 16:20:01 -0200
committerRoberto Ierusalimschy <roberto@inf.puc-rio.br>2000-10-31 16:20:01 -0200
commitdf416661cc394fb397341baee368c5894d7e3b1b (patch)
treef95f8642daa433163c2b8d48b29f63aab0171298 /manual.tex
parent67c1afff5917b118f3be818dd0df7448d19de877 (diff)
downloadlua-df416661cc394fb397341baee368c5894d7e3b1b.tar.gz
lua-df416661cc394fb397341baee368c5894d7e3b1b.tar.bz2
lua-df416661cc394fb397341baee368c5894d7e3b1b.zip
many changes
Diffstat (limited to 'manual.tex')
-rw-r--r--manual.tex132
1 files changed, 89 insertions, 43 deletions
diff --git a/manual.tex b/manual.tex
index 0b13babf..817f17ad 100644
--- a/manual.tex
+++ b/manual.tex
@@ -1,4 +1,4 @@
1% $Id: manual.tex,v 1.43 2000/09/18 19:41:16 roberto Exp roberto $ 1% $Id: manual.tex,v 1.44 2000/09/20 17:21:20 roberto Exp roberto $
2 2
3\documentclass[11pt]{article} 3\documentclass[11pt]{article}
4\usepackage{fullpage,bnf} 4\usepackage{fullpage,bnf}
@@ -21,8 +21,6 @@
21\newcommand{\Def}[1]{\emph{#1}\index{#1}} 21\newcommand{\Def}[1]{\emph{#1}\index{#1}}
22\newcommand{\Deffunc}[1]{\index{#1}} 22\newcommand{\Deffunc}[1]{\index{#1}}
23 23
24\newcommand{\Tochange}[1]{(#1 may change in the final 4.0 version.)}
25
26\newcommand{\ff}{$\bullet$\ } 24\newcommand{\ff}{$\bullet$\ }
27 25
28\newcommand{\Version}{4.0} 26\newcommand{\Version}{4.0}
@@ -131,7 +129,7 @@ Waldemar Celes
131\tecgraf\ --- Computer Science Department --- PUC-Rio 129\tecgraf\ --- Computer Science Department --- PUC-Rio
132} 130}
133 131
134\date{{\small \tt\$Date: 2000/09/18 19:41:16 $ $}} 132\date{{\small \tt\$Date: 2000/09/20 17:21:20 $ $}}
135 133
136\maketitle 134\maketitle
137 135
@@ -868,7 +866,7 @@ The second idiom is
868\begin{verbatim} 866\begin{verbatim}
869 x = a and b or c 867 x = a and b or c
870\end{verbatim} 868\end{verbatim}
871which should be read as \verb|x = a and (b or c)|. 869which should be read as \verb|x = (a and b) or c|.
872This idiom is equivalent to 870This idiom is equivalent to
873\begin{verbatim} 871\begin{verbatim}
874 if a then x = b else x = c end 872 if a then x = b else x = c end
@@ -1522,9 +1520,13 @@ Lua does the equivalent of the following function:
1522 end 1520 end
1523 end 1521 end
1524\end{verbatim} 1522\end{verbatim}
1525Moreover, at the end of a garbage collection cycle, 1523In a garbage-collection cicle,
1524the tag methods for userdata are called in reverse
1525order of tag creation:
1526That is, the first tag methods to be called are those associated
1527with the last tag created in the program.
1528Moreover, at the end of the cycle,
1526Lua does the equivalent of the call \verb|gc_event(nil)|. 1529Lua does the equivalent of the call \verb|gc_event(nil)|.
1527\Tochange{This}
1528 1530
1529\end{description} 1531\end{description}
1530 1532
@@ -1549,7 +1551,7 @@ and so do not generate hidden side-effects.
1549\subsection{States} \label{mangstate} 1551\subsection{States} \label{mangstate}
1550 1552
1551The Lua library is fully reentrant: 1553The Lua library is fully reentrant:
1552it does not have any global variable. 1554it does not have any global variables.
1553The whole state of the Lua interpreter 1555The whole state of the Lua interpreter
1554(global variables, stack, tag methods, etc.) 1556(global variables, stack, tag methods, etc.)
1555is stored in a dynamically allocated structure; \Deffunc{lua_State} 1557is stored in a dynamically allocated structure; \Deffunc{lua_State}
@@ -1818,18 +1820,43 @@ which accepts an explicit size.
1818 1820
1819\subsection{Garbage Collection}\label{GC} 1821\subsection{Garbage Collection}\label{GC}
1820 1822
1821A garbage collection cycle can be forced by: 1823Lua keeps two numbers to control its garbage collection.
1822\Deffunc{lua_collectgarbage} 1824One number counts how many bytes of dynamic memory Lua is using,
1825and the other keeps a threshold.
1826(This internal byte counter kept by Lua is not completely acurate:
1827Instead, it is a lower bound, usually within 10\% of the correct value.)
1828When the number of bytes crosses the threshold,
1829Lua runs a garbage-collection cycle,
1830that reclaims the memory of all ``dead'' objects
1831(that is, objects no longer accessible from Lua).
1832The byte counter is corrected,
1833and then the threshold is reset to twice the value of the byte counter.
1834
1835You can access the current values of these two numbers through the
1836following functions:
1837\Deffunc{lua_getgcthreshold} \Deffunc{lua_getgccount}
1823\begin{verbatim} 1838\begin{verbatim}
1824 long lua_collectgarbage (lua_State *L, long limit); 1839 int lua_getgccount (lua_State *L);
1840 int lua_getgcthreshold (lua_State *L);
1825\end{verbatim} 1841\end{verbatim}
1826This function returns the number of objects collected. 1842Both return their respective values in Kbytes.
1827The argument \verb|limit| makes the next cycle occur only 1843You can change the threshold value with
1828after that number of new objects have been created. 1844\Deffunc{lua_setgcthreshold}
1829If \verb|limit| is 0, 1845\begin{verbatim}
1830then Lua uses an adaptive heuristic to set this limit. 1846 void lua_setgcthreshold (lua_State *L, int newthreshold);
1847\end{verbatim}
1848Again, the \verb|newthreshold| value is given in Kbytes.
1849When you call this function,
1850Lua sets the new threshold and checks it against the byte counter;
1851if the new threshold is smaller than the byte counter,
1852Lua runs immediately the garbage collector
1853(and, after it, sets a new threshold according to the previous rule).
1854
1855If you want to change the adaptative behavior of the garbage collector,
1856you can use the garbage-collection tag method for the tag \nil
1857to set your own threshold
1858(the tag method is called after Lua resets the threshold).
1831 1859
1832\Tochange{This function}
1833 1860
1834\subsection{Userdata and Tags}\label{C-tags} 1861\subsection{Userdata and Tags}\label{C-tags}
1835 1862
@@ -1853,7 +1880,7 @@ Tags are created with the function
1853 int lua_newtag (lua_State *L); 1880 int lua_newtag (lua_State *L);
1854\end{verbatim} 1881\end{verbatim}
1855The function \verb|lua_settag| changes the tag of 1882The function \verb|lua_settag| changes the tag of
1856the object on top of the stack (and pops it): 1883the object on top of the stack (without popping it):
1857\Deffunc{lua_settag} 1884\Deffunc{lua_settag}
1858\begin{verbatim} 1885\begin{verbatim}
1859 void lua_settag (lua_State *L, int tag); 1886 void lua_settag (lua_State *L, int tag);
@@ -1875,15 +1902,18 @@ These functions return
18750 in case of success, or one of the following error codes if they fail 19020 in case of success, or one of the following error codes if they fail
1876(these constants are defined in \verb|lua.h|.): 1903(these constants are defined in \verb|lua.h|.):
1877\begin{itemize} 1904\begin{itemize}
1878\item \verb|LUA_ERRRUN| --- 1905\item \IndexVerb{LUA_ERRRUN} ---
1879error while running the chunk. 1906error while running the chunk.
1880\item \verb|LUA_ERRSYNTAX| --- 1907\item \IndexVerb{LUA_ERRSYNTAX} ---
1881syntax error during pre-compilation. 1908syntax error during pre-compilation.
1882\item \verb|LUA_ERRMEM| --- 1909\item \IndexVerb{LUA_ERRMEM} ---
1883memory allocation error. 1910memory allocation error.
1884For such errors, Lua does not call the \verb|_ERRORMESSAGE| function 1911For such errors, Lua does not call the \verb|_ERRORMESSAGE| function
1885\see{error}. 1912\see{error}.
1886\item \verb|LUA_ERRFILE| --- 1913\item \IndexVerb{LUA_ERRERR} ---
1914error while running the \verb|_ERRORMESSAGE| function.
1915For such errors, Lua does not call the function again, to avoid loops.
1916\item \IndexVerb{LUA_ERRFILE} ---
1887error opening the file (only for \verb|lua_dofile|). 1917error opening the file (only for \verb|lua_dofile|).
1888In this case, 1918In this case,
1889you may want to 1919you may want to
@@ -2021,7 +2051,7 @@ Finally, the function
2021\begin{verbatim} 2051\begin{verbatim}
2022 void lua_newtable (lua_State *L); 2052 void lua_newtable (lua_State *L);
2023\end{verbatim} 2053\end{verbatim}
2024creates a new, empty table and and pushes it onto the stack. 2054creates a new, empty table and pushes it onto the stack.
2025 2055
2026\subsection{Using Tables as Arrays} 2056\subsection{Using Tables as Arrays}
2027The API has functions that help to use Lua tables as arrays, 2057The API has functions that help to use Lua tables as arrays,
@@ -2120,8 +2150,7 @@ Tag methods can be changed with \Deffunc{lua_settagmethod}
2120\end{verbatim} 2150\end{verbatim}
2121The second parameter is the tag, 2151The second parameter is the tag,
2122and the third is the event name \see{tag-method}; 2152and the third is the event name \see{tag-method};
2123the new method is popped from the stack, 2153the new method is popped from the stack.
2124and the old one is pushed in its place.
2125To just get the current value of a tag method, 2154To just get the current value of a tag method,
2126use the function \Deffunc{lua_gettagmethod} 2155use the function \Deffunc{lua_gettagmethod}
2127\begin{verbatim} 2156\begin{verbatim}
@@ -2245,7 +2274,7 @@ these upvalues are inserted as the \emph{last} arguments to the function,
2245after the actual arguments provided in the call. 2274after the actual arguments provided in the call.
2246This makes it easy to get the upvalues without knowing how many arguments 2275This makes it easy to get the upvalues without knowing how many arguments
2247the function received (recall that functions in Lua can receive any number of 2276the function received (recall that functions in Lua can receive any number of
2248arguments): The \M{i}-th upvalue is in the stack at index \Math{i-n+1}, 2277arguments): The \M{i}-th upvalue is in the stack at index \Math{i-(n+1)},
2249where \M{n} is the number of upvalues. 2278where \M{n} is the number of upvalues.
2250 2279
2251For more examples of C~functions and closures, see files 2280For more examples of C~functions and closures, see files
@@ -2287,6 +2316,18 @@ When a reference is no longer needed,
2287it should be released with a call to \verb|lua_unref|. 2316it should be released with a call to \verb|lua_unref|.
2288 2317
2289 2318
2319\subsubsection*{Registry}
2320
2321When Lua starts, it registers a table at position
2322\IndexVerb{LUA_REFREGISTRY}.
2323It can be accessed through the macro\Deffunc{lua_getregistry}
2324\begin{verbatim}
2325 #define lua_getregistry(L) lua_getref(L, LUA_REFREGISTRY)
2326\end{verbatim}
2327This table can be used by C libraries as a general registry mechanism.
2328Any C library can store data into this table,
2329as long as it chooses a key different from other libraries.
2330
2290 2331
2291\section{Standard Libraries} 2332\section{Standard Libraries}
2292 2333
@@ -2368,17 +2409,17 @@ In particular, if \verb|errhandler| is \nil,
2368no error messages will be issued during the execution of the called function. 2409no error messages will be issued during the execution of the called function.
2369 2410
2370\subsubsection*{\ff \T{collectgarbage ([limit])}}\Deffunc{collectgarbage} 2411\subsubsection*{\ff \T{collectgarbage ([limit])}}\Deffunc{collectgarbage}
2371Forces a garbage collection cycle.
2372Returns the number of objects collected.
2373The optional argument \verb|limit| is a number that
2374makes the next cycle occur only after that number of new
2375objects have been created.
2376If \verb|limit| is absent or equal to 0,
2377then Lua uses an adaptive algorithm to set this limit.
2378\verb|collectgarbage| is equivalent to
2379the API function \verb|lua_collectgarbage|.
2380 2412
2381\Tochange{This function} 2413Sets the garbage-collection threshold for the given limit
2414(in Kbytes), and checks it against the byte counter;
2415if the new threshold is smaller than the byte counter,
2416Lua runs immediately the garbage collector \see{GC}.
2417
2418If \verb|limit| is absent, it defaults to zero
2419(thus forcing a garbage-collection cycle).
2420
2421\verb|collectgarbage| is equivalent to
2422the API function \verb|lua_setgcthreshold|.
2382 2423
2383\subsubsection*{\ff \T{copytagmethods (tagto, tagfrom)}} 2424\subsubsection*{\ff \T{copytagmethods (tagto, tagfrom)}}
2384\Deffunc{copytagmethods} 2425\Deffunc{copytagmethods}
@@ -2499,6 +2540,9 @@ This function could be defined in Lua:
2499Returns the current tag method 2540Returns the current tag method
2500for a given pair \M{(tag, event)}. 2541for a given pair \M{(tag, event)}.
2501 2542
2543This function cannot be used to get a tag method for the ``gc'' event.
2544(Such tag methods can only be manipulated by C code.)
2545
2502\subsubsection*{\ff \T{globals ([table])}}\Deffunc{globals} 2546\subsubsection*{\ff \T{globals ([table])}}\Deffunc{globals}
2503Returns the current table of globals. 2547Returns the current table of globals.
2504If the argument \verb|table| is given, 2548If the argument \verb|table| is given,
@@ -2595,6 +2639,9 @@ It returns the old method.
2595If \verb|newmethod| is \nil, 2639If \verb|newmethod| is \nil,
2596then \verb|settagmethod| restores the default behavior for the given event. 2640then \verb|settagmethod| restores the default behavior for the given event.
2597 2641
2642This function cannot be used to set a tag method for the ``gc'' event.
2643(Such tag methods can only be manipulated by C code.)
2644
2598\subsubsection*{\ff \T{sort (table [, comp])}}\Deffunc{sort} 2645\subsubsection*{\ff \T{sort (table [, comp])}}\Deffunc{sort}
2599Sorts table elements in a given order, \emph{in-place}, 2646Sorts table elements in a given order, \emph{in-place},
2600from \verb|table[1]| to \verb|table[n]|, 2647from \verb|table[1]| to \verb|table[n]|,
@@ -2710,7 +2757,6 @@ The possible results of this function are
2710\verb|"table"|, 2757\verb|"table"|,
2711\verb|"function"|, 2758\verb|"function"|,
2712and \verb|"userdata"|. 2759and \verb|"userdata"|.
2713\verb|type| is equivalent to the API function \verb|lua_type|.
2714 2760
2715 2761
2716\subsection{String Manipulation} 2762\subsection{String Manipulation}
@@ -3622,6 +3668,8 @@ is provided with the standard distribution.
3622 3668
3623This program can be called with any sequence of the following arguments: 3669This program can be called with any sequence of the following arguments:
3624\begin{description}\leftskip=20pt 3670\begin{description}\leftskip=20pt
3671\item[\T{-sNUM}] sets the stack size to \T{NUM}
3672(if present, this must be the first option);
3625\item[\T{-} ] executes \verb|stdin| as a file; 3673\item[\T{-} ] executes \verb|stdin| as a file;
3626\item[\T{-c}] calls \verb|lua_close| after running all arguments; 3674\item[\T{-c}] calls \verb|lua_close| after running all arguments;
3627\item[\T{-e} \rm\emph{stat}] executes string \verb|stat|; 3675\item[\T{-e} \rm\emph{stat}] executes string \verb|stat|;
@@ -3812,7 +3860,7 @@ The debug API has been completely rewritten.
3812%{=============================================================== 3860%{===============================================================
3813\section*{The Complete Syntax of Lua} \label{BNF} 3861\section*{The Complete Syntax of Lua} \label{BNF}
3814 3862
3815\addcontentsline{toc}{section}{The complete syntax of Lua} 3863\addcontentsline{toc}{section}{The Complete Syntax of Lua}
3816 3864
3817\renewenvironment{Produc}{\vspace{0.8ex}\par\noindent\hspace{3ex}\it\begin{tabular}{rrl}}{\end{tabular}\vspace{0.8ex}\par\noindent} 3865\renewenvironment{Produc}{\vspace{0.8ex}\par\noindent\hspace{3ex}\it\begin{tabular}{rrl}}{\end{tabular}\vspace{0.8ex}\par\noindent}
3818 3866
@@ -3927,13 +3975,11 @@ The debug API has been completely rewritten.
3927\end{Produc} 3975\end{Produc}
3928%}=============================================================== 3976%}===============================================================
3929 3977
3930% restore underscore to usual meaning 3978% Index
3931\catcode`\_=8
3932 3979
3933\newcommand{\indexentry}[2]{\item {#1} #2} 3980\newpage
3934\begin{theindex}
3935\addcontentsline{toc}{section}{Index} 3981\addcontentsline{toc}{section}{Index}
3936\input{manual.id} 3982\input{manual.id}
3937\end{theindex} 3983
3938 3984
3939\end{document} 3985\end{document}