diff options
author | Roberto Ierusalimschy <roberto@inf.puc-rio.br> | 2000-10-31 16:20:01 -0200 |
---|---|---|
committer | Roberto Ierusalimschy <roberto@inf.puc-rio.br> | 2000-10-31 16:20:01 -0200 |
commit | df416661cc394fb397341baee368c5894d7e3b1b (patch) | |
tree | f95f8642daa433163c2b8d48b29f63aab0171298 /manual.tex | |
parent | 67c1afff5917b118f3be818dd0df7448d19de877 (diff) | |
download | lua-df416661cc394fb397341baee368c5894d7e3b1b.tar.gz lua-df416661cc394fb397341baee368c5894d7e3b1b.tar.bz2 lua-df416661cc394fb397341baee368c5894d7e3b1b.zip |
many changes
Diffstat (limited to 'manual.tex')
-rw-r--r-- | manual.tex | 132 |
1 files changed, 89 insertions, 43 deletions
@@ -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} |
871 | which should be read as \verb|x = a and (b or c)|. | 869 | which should be read as \verb|x = (a and b) or c|. |
872 | This idiom is equivalent to | 870 | This 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} |
1525 | Moreover, at the end of a garbage collection cycle, | 1523 | In a garbage-collection cicle, |
1524 | the tag methods for userdata are called in reverse | ||
1525 | order of tag creation: | ||
1526 | That is, the first tag methods to be called are those associated | ||
1527 | with the last tag created in the program. | ||
1528 | Moreover, at the end of the cycle, | ||
1526 | Lua does the equivalent of the call \verb|gc_event(nil)|. | 1529 | Lua 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 | ||
1551 | The Lua library is fully reentrant: | 1553 | The Lua library is fully reentrant: |
1552 | it does not have any global variable. | 1554 | it does not have any global variables. |
1553 | The whole state of the Lua interpreter | 1555 | The whole state of the Lua interpreter |
1554 | (global variables, stack, tag methods, etc.) | 1556 | (global variables, stack, tag methods, etc.) |
1555 | is stored in a dynamically allocated structure; \Deffunc{lua_State} | 1557 | is 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 | ||
1821 | A garbage collection cycle can be forced by: | 1823 | Lua keeps two numbers to control its garbage collection. |
1822 | \Deffunc{lua_collectgarbage} | 1824 | One number counts how many bytes of dynamic memory Lua is using, |
1825 | and the other keeps a threshold. | ||
1826 | (This internal byte counter kept by Lua is not completely acurate: | ||
1827 | Instead, it is a lower bound, usually within 10\% of the correct value.) | ||
1828 | When the number of bytes crosses the threshold, | ||
1829 | Lua runs a garbage-collection cycle, | ||
1830 | that reclaims the memory of all ``dead'' objects | ||
1831 | (that is, objects no longer accessible from Lua). | ||
1832 | The byte counter is corrected, | ||
1833 | and then the threshold is reset to twice the value of the byte counter. | ||
1834 | |||
1835 | You can access the current values of these two numbers through the | ||
1836 | following 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} |
1826 | This function returns the number of objects collected. | 1842 | Both return their respective values in Kbytes. |
1827 | The argument \verb|limit| makes the next cycle occur only | 1843 | You can change the threshold value with |
1828 | after that number of new objects have been created. | 1844 | \Deffunc{lua_setgcthreshold} |
1829 | If \verb|limit| is 0, | 1845 | \begin{verbatim} |
1830 | then Lua uses an adaptive heuristic to set this limit. | 1846 | void lua_setgcthreshold (lua_State *L, int newthreshold); |
1847 | \end{verbatim} | ||
1848 | Again, the \verb|newthreshold| value is given in Kbytes. | ||
1849 | When you call this function, | ||
1850 | Lua sets the new threshold and checks it against the byte counter; | ||
1851 | if the new threshold is smaller than the byte counter, | ||
1852 | Lua runs immediately the garbage collector | ||
1853 | (and, after it, sets a new threshold according to the previous rule). | ||
1854 | |||
1855 | If you want to change the adaptative behavior of the garbage collector, | ||
1856 | you can use the garbage-collection tag method for the tag \nil | ||
1857 | to 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} |
1855 | The function \verb|lua_settag| changes the tag of | 1882 | The function \verb|lua_settag| changes the tag of |
1856 | the object on top of the stack (and pops it): | 1883 | the 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 | |||
1875 | 0 in case of success, or one of the following error codes if they fail | 1902 | 0 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} --- |
1879 | error while running the chunk. | 1906 | error while running the chunk. |
1880 | \item \verb|LUA_ERRSYNTAX| --- | 1907 | \item \IndexVerb{LUA_ERRSYNTAX} --- |
1881 | syntax error during pre-compilation. | 1908 | syntax error during pre-compilation. |
1882 | \item \verb|LUA_ERRMEM| --- | 1909 | \item \IndexVerb{LUA_ERRMEM} --- |
1883 | memory allocation error. | 1910 | memory allocation error. |
1884 | For such errors, Lua does not call the \verb|_ERRORMESSAGE| function | 1911 | For 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} --- |
1914 | error while running the \verb|_ERRORMESSAGE| function. | ||
1915 | For such errors, Lua does not call the function again, to avoid loops. | ||
1916 | \item \IndexVerb{LUA_ERRFILE} --- | ||
1887 | error opening the file (only for \verb|lua_dofile|). | 1917 | error opening the file (only for \verb|lua_dofile|). |
1888 | In this case, | 1918 | In this case, |
1889 | you may want to | 1919 | you 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} |
2024 | creates a new, empty table and and pushes it onto the stack. | 2054 | creates a new, empty table and pushes it onto the stack. |
2025 | 2055 | ||
2026 | \subsection{Using Tables as Arrays} | 2056 | \subsection{Using Tables as Arrays} |
2027 | The API has functions that help to use Lua tables as arrays, | 2057 | The 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} |
2121 | The second parameter is the tag, | 2151 | The second parameter is the tag, |
2122 | and the third is the event name \see{tag-method}; | 2152 | and the third is the event name \see{tag-method}; |
2123 | the new method is popped from the stack, | 2153 | the new method is popped from the stack. |
2124 | and the old one is pushed in its place. | ||
2125 | To just get the current value of a tag method, | 2154 | To just get the current value of a tag method, |
2126 | use the function \Deffunc{lua_gettagmethod} | 2155 | use 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, | |||
2245 | after the actual arguments provided in the call. | 2274 | after the actual arguments provided in the call. |
2246 | This makes it easy to get the upvalues without knowing how many arguments | 2275 | This makes it easy to get the upvalues without knowing how many arguments |
2247 | the function received (recall that functions in Lua can receive any number of | 2276 | the function received (recall that functions in Lua can receive any number of |
2248 | arguments): The \M{i}-th upvalue is in the stack at index \Math{i-n+1}, | 2277 | arguments): The \M{i}-th upvalue is in the stack at index \Math{i-(n+1)}, |
2249 | where \M{n} is the number of upvalues. | 2278 | where \M{n} is the number of upvalues. |
2250 | 2279 | ||
2251 | For more examples of C~functions and closures, see files | 2280 | For more examples of C~functions and closures, see files |
@@ -2287,6 +2316,18 @@ When a reference is no longer needed, | |||
2287 | it should be released with a call to \verb|lua_unref|. | 2316 | it should be released with a call to \verb|lua_unref|. |
2288 | 2317 | ||
2289 | 2318 | ||
2319 | \subsubsection*{Registry} | ||
2320 | |||
2321 | When Lua starts, it registers a table at position | ||
2322 | \IndexVerb{LUA_REFREGISTRY}. | ||
2323 | It 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} | ||
2327 | This table can be used by C libraries as a general registry mechanism. | ||
2328 | Any C library can store data into this table, | ||
2329 | as 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, | |||
2368 | no error messages will be issued during the execution of the called function. | 2409 | no 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} |
2371 | Forces a garbage collection cycle. | ||
2372 | Returns the number of objects collected. | ||
2373 | The optional argument \verb|limit| is a number that | ||
2374 | makes the next cycle occur only after that number of new | ||
2375 | objects have been created. | ||
2376 | If \verb|limit| is absent or equal to 0, | ||
2377 | then Lua uses an adaptive algorithm to set this limit. | ||
2378 | \verb|collectgarbage| is equivalent to | ||
2379 | the API function \verb|lua_collectgarbage|. | ||
2380 | 2412 | ||
2381 | \Tochange{This function} | 2413 | Sets the garbage-collection threshold for the given limit |
2414 | (in Kbytes), and checks it against the byte counter; | ||
2415 | if the new threshold is smaller than the byte counter, | ||
2416 | Lua runs immediately the garbage collector \see{GC}. | ||
2417 | |||
2418 | If \verb|limit| is absent, it defaults to zero | ||
2419 | (thus forcing a garbage-collection cycle). | ||
2420 | |||
2421 | \verb|collectgarbage| is equivalent to | ||
2422 | the 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: | |||
2499 | Returns the current tag method | 2540 | Returns the current tag method |
2500 | for a given pair \M{(tag, event)}. | 2541 | for a given pair \M{(tag, event)}. |
2501 | 2542 | ||
2543 | This 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} |
2503 | Returns the current table of globals. | 2547 | Returns the current table of globals. |
2504 | If the argument \verb|table| is given, | 2548 | If the argument \verb|table| is given, |
@@ -2595,6 +2639,9 @@ It returns the old method. | |||
2595 | If \verb|newmethod| is \nil, | 2639 | If \verb|newmethod| is \nil, |
2596 | then \verb|settagmethod| restores the default behavior for the given event. | 2640 | then \verb|settagmethod| restores the default behavior for the given event. |
2597 | 2641 | ||
2642 | This 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} |
2599 | Sorts table elements in a given order, \emph{in-place}, | 2646 | Sorts table elements in a given order, \emph{in-place}, |
2600 | from \verb|table[1]| to \verb|table[n]|, | 2647 | from \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"|, |
2712 | and \verb|"userdata"|. | 2759 | and \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 | ||
3623 | This program can be called with any sequence of the following arguments: | 3669 | This 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} |