diff options
| author | Lua Team <team@lua.org> | 2000-11-06 12:00:00 +0000 |
|---|---|---|
| committer | repogen <> | 2000-11-06 12:00:00 +0000 |
| commit | 8cb71cb5548e3138e5d4e4744f52c79d9fafb116 (patch) | |
| tree | 25859eb162c67eafc46866e0ec3a9a7ebf93157a /doc | |
| parent | b7610da5fed99f59ac73ae452da8839a0f2c1bda (diff) | |
| download | lua-github-4.0.tar.gz | |
Lua 4.04.0
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/idx.html | 577 | ||||
| -rw-r--r-- | doc/index.html | 74 | ||||
| -rw-r--r-- | doc/logo.gif | bin | 0 -> 2750 bytes | |||
| -rw-r--r-- | doc/lua.1 | 143 | ||||
| -rw-r--r-- | doc/lua.html | 151 | ||||
| -rw-r--r-- | doc/luac.1 | 139 | ||||
| -rw-r--r-- | doc/luac.html | 149 | ||||
| -rw-r--r-- | doc/luac.man | 188 | ||||
| -rw-r--r-- | doc/manual.html | 4213 | ||||
| -rw-r--r-- | doc/readme.html | 23 |
10 files changed, 3274 insertions, 2383 deletions
diff --git a/doc/idx.html b/doc/idx.html index 65b0e78a..74693a56 100644 --- a/doc/idx.html +++ b/doc/idx.html @@ -1,282 +1,409 @@ <HTML> <HEAD> -<TITLE>Lua 3.2 Reference Manual - Word Index</TITLE> +<TITLE>Lua 4.0 Reference Manual - Word Index</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> -<H1>Index</H1> +<HR> +<H1> +<IMG SRC="logo.gif" ALT="Lua" ALIGN="bottom"> +<A HREF="index.html">Reference manual</A> +- word index +</H1> -<A HREF="manual.html#..">..</A><BR> -<A HREF="manual.html#Adjustment">Adjustment</A><BR> -<A HREF="manual.html#Assignment">Assignment</A><BR> -<A HREF="manual.html#Basic Expressions">Basic Expressions</A><BR> -<A HREF="manual.html#C pointers">C pointers</A><BR> -<A HREF="manual.html#C2lua">C2lua</A><BR> -<A HREF="manual.html#Coercion">Coercion</A><BR> -<A HREF="manual.html#Comments">Comments</A><BR> -<A HREF="manual.html#Expressions">Expressions</A><BR> -<A HREF="manual.html#Function Definitions">Function Definitions</A><BR> -<A HREF="manual.html#Global variables">Global variables</A><BR> -<A HREF="manual.html#Identifiers">Identifiers</A><BR> -<A HREF="manual.html#LUA_ANYTAG">LUA_ANYTAG</A><BR> -<A HREF="manual.html#LUA_NOOBJECT">LUA_NOOBJECT</A><BR> -<A HREF="manual.html#Literal strings">Literal strings</A><BR> -<A HREF="manual.html#Local variables">Local variables</A><BR> -<A HREF="manual.html#Lua Stand-alone">Lua Stand-alone</A><BR> -<A HREF="manual.html#Numerical constants">Numerical constants</A><BR> -<A HREF="manual.html#Operator precedence">Operator precedence</A><BR> -<A HREF="manual.html#PI">PI</A><BR> -<A HREF="manual.html#Pre-processor">Pre-processor</A><BR> -<A HREF="manual.html#Types and Tags">Types and Tags</A><BR> -<A HREF="manual.html#Upvalues">Upvalues</A><BR> -<A HREF="manual.html#Visibility">Visibility</A><BR> -<A HREF="manual.html#_ERRORMESSAGE">_ERRORMESSAGE</A><BR> -<A HREF="manual.html#_INPUT">_INPUT</A><BR> -<A HREF="manual.html#_OUTPUT">_OUTPUT</A><BR> -<A HREF="manual.html#_STDERR">_STDERR</A><BR> -<A HREF="manual.html#_STDIN">_STDIN</A><BR> -<A HREF="manual.html#_STDOUT">_STDOUT</A><BR> -<A HREF="manual.html#abs">abs</A><BR> -<A HREF="manual.html#acos">acos</A><BR> -<A HREF="manual.html#add event">add event</A><BR> -<A HREF="manual.html#alert">alert</A><BR> +<A HREF="manual.html#.."><TT>..</TT></A><BR> +<A HREF="manual.html#_ALERT"><TT>_ALERT</TT></A><BR> +<A HREF="manual.html#_ERRORMESSAGE"><TT>_ERRORMESSAGE</TT></A><BR> +<A HREF="manual.html#_INPUT"><TT>_INPUT</TT></A><BR> +<A HREF="manual.html#_OUTPUT"><TT>_OUTPUT</TT></A><BR> +<A HREF="manual.html#_PROMPT"><TT>_PROMPT</TT></A><BR> +<A HREF="manual.html#_STDERR"><TT>_STDERR</TT></A><BR> +<A HREF="manual.html#_STDIN"><TT>_STDIN</TT></A><BR> +<A HREF="manual.html#_STDOUT"><TT>_STDOUT</TT></A><BR> + + <P> + +<A HREF="manual.html#abs"><TT>abs</TT></A><BR> +<A HREF="manual.html#acceptable index">acceptable index</A><BR> +<A HREF="manual.html#acos"><TT>acos</TT></A><BR> +<A HREF="manual.html#add event">``add'' event</A><BR> +<A HREF="manual.html#Adjustment">adjustment</A><BR> +<A HREF="manual.html#alert"><TT>alert</TT></A><BR> <A HREF="manual.html#and">and</A><BR> -<A HREF="manual.html#appendto">appendto</A><BR> +<A HREF="manual.html#appendto"><TT>appendto</TT></A><BR> +<A HREF="manual.html#arg"><TT>arg</TT></A><BR> <A HREF="manual.html#arguments">arguments</A><BR> -<A HREF="manual.html#arg">arg</A><BR> <A HREF="manual.html#arithmetic operators">arithmetic operators</A><BR> <A HREF="manual.html#arrays">arrays</A><BR> -<A HREF="manual.html#asin">asin</A><BR> -<A HREF="manual.html#assert">assert</A><BR> +<A HREF="manual.html#asin"><TT>asin</TT></A><BR> +<A HREF="manual.html#assert"><TT>assert</TT></A><BR> +<A HREF="manual.html#Assignment">assignment</A><BR> <A HREF="manual.html#associative arrays">associative arrays</A><BR> -<A HREF="manual.html#atan2">atan2</A><BR> -<A HREF="manual.html#atan">atan</A><BR> +<A HREF="manual.html#atan"><TT>atan</TT></A><BR> +<A HREF="manual.html#atan2"><TT>atan2</TT></A><BR> + + <P> + +<A HREF="manual.html#Basic Expressions">basic expressions</A><BR> <A HREF="manual.html#basic types">basic types</A><BR> <A HREF="manual.html#block">block</A><BR> -<A HREF="manual.html#call">call</A><BR> +<A HREF="manual.html#break statement">break statement</A><BR> + + <P> + +<A HREF="manual.html#C API">C API</A><BR> +....... <A HREF="manual.html#LUA_ANYTAG"><TT>LUA_ANYTAG</TT></A><BR> +....... <A HREF="manual.html#lua_baselibopen"><TT>lua_baselibopen</TT></A><BR> +....... <A HREF="manual.html#lua_call"><TT>lua_call</TT></A><BR> +....... <A HREF="manual.html#lua_CFunction"><TT>lua_CFunction</TT></A><BR> +....... <A HREF="manual.html#lua_close"><TT>lua_close</TT></A><BR> +....... <A HREF="manual.html#lua_concat"><TT>lua_concat</TT></A><BR> +....... <A HREF="manual.html#lua_copytagmethods"><TT>lua_copytagmethods</TT></A><BR> +....... <A HREF="manual.html#lua_dblibopen"><TT>lua_dblibopen</TT></A><BR> +....... <A HREF="manual.html#lua_Debug"><TT>lua_Debug</TT></A><BR> +....... <A HREF="manual.html#lua_dobuffer"><TT>lua_dobuffer</TT></A><BR> +....... <A HREF="manual.html#lua_dofile"><TT>lua_dofile</TT></A><BR> +....... <A HREF="manual.html#lua_dostring"><TT>lua_dostring</TT></A><BR> +....... <A HREF="manual.html#lua_equal"><TT>lua_equal</TT></A><BR> +....... <A HREF="manual.html#LUA_ERRERR"><TT>LUA_ERRERR</TT></A><BR> +....... <A HREF="manual.html#LUA_ERRFILE"><TT>LUA_ERRFILE</TT></A><BR> +....... <A HREF="manual.html#LUA_ERRMEM"><TT>LUA_ERRMEM</TT></A><BR> +....... <A HREF="manual.html#lua_error"><TT>lua_error</TT></A><BR> +....... <A HREF="manual.html#LUA_ERRRUN"><TT>LUA_ERRRUN</TT></A><BR> +....... <A HREF="manual.html#LUA_ERRSYNTAX"><TT>LUA_ERRSYNTAX</TT></A><BR> +....... <A HREF="manual.html#lua_getgccount"><TT>lua_getgccount</TT></A><BR> +....... <A HREF="manual.html#lua_getgcthreshold"><TT>lua_getgcthreshold</TT></A><BR> +....... <A HREF="manual.html#lua_getglobal"><TT>lua_getglobal</TT></A><BR> +....... <A HREF="manual.html#lua_getglobals"><TT>lua_getglobals</TT></A><BR> +....... <A HREF="manual.html#lua_getinfo"><TT>lua_getinfo</TT></A><BR> +....... <A HREF="manual.html#lua_getlocal"><TT>lua_getlocal</TT></A><BR> +....... <A HREF="manual.html#lua_getn"><TT>lua_getn</TT></A><BR> +....... <A HREF="manual.html#lua_getref"><TT>lua_getref</TT></A><BR> +....... <A HREF="manual.html#lua_getregistry"><TT>lua_getregistry</TT></A><BR> +....... <A HREF="manual.html#lua_getstack"><TT>lua_getstack</TT></A><BR> +....... <A HREF="manual.html#lua_gettable"><TT>lua_gettable</TT></A><BR> +....... <A HREF="manual.html#lua_gettagmethod"><TT>lua_gettagmethod</TT></A><BR> +....... <A HREF="manual.html#lua_gettop"><TT>lua_gettop</TT></A><BR> +....... <A HREF="manual.html#lua_Hook"><TT>lua_Hook</TT></A><BR> +....... <A HREF="manual.html#lua_insert"><TT>lua_insert</TT></A><BR> +....... <A HREF="manual.html#lua_iolibopen"><TT>lua_iolibopen</TT></A><BR> +....... <A HREF="manual.html#lua_iscfunction"><TT>lua_iscfunction</TT></A><BR> +....... <A HREF="manual.html#lua_isfunction"><TT>lua_isfunction</TT></A><BR> +....... <A HREF="manual.html#lua_isnil"><TT>lua_isnil</TT></A><BR> +....... <A HREF="manual.html#lua_isnumber"><TT>lua_isnumber</TT></A><BR> +....... <A HREF="manual.html#lua_isstring"><TT>lua_isstring</TT></A><BR> +....... <A HREF="manual.html#lua_istable"><TT>lua_istable</TT></A><BR> +....... <A HREF="manual.html#lua_isuserdata"><TT>lua_isuserdata</TT></A><BR> +....... <A HREF="manual.html#lua_lessthan"><TT>lua_lessthan</TT></A><BR> +....... <A HREF="manual.html#lua_mathlibopen"><TT>lua_mathlibopen</TT></A><BR> +....... <A HREF="manual.html#LUA_MINSTACK"><TT>LUA_MINSTACK</TT></A><BR> +....... <A HREF="manual.html#LUA_MULTRET"><TT>LUA_MULTRET</TT></A><BR> +....... <A HREF="manual.html#lua_newtable"><TT>lua_newtable</TT></A><BR> +....... <A HREF="manual.html#lua_newtag"><TT>lua_newtag</TT></A><BR> +....... <A HREF="manual.html#lua_next"><TT>lua_next</TT></A><BR> +....... <A HREF="manual.html#LUA_NOREF"><TT>LUA_NOREF</TT></A><BR> +....... <A HREF="manual.html#lua_open"><TT>lua_open</TT></A><BR> +....... <A HREF="manual.html#lua_pushcclosure"><TT>lua_pushcclosure</TT></A><BR> +....... <A HREF="manual.html#lua_pushcfunction"><TT>lua_pushcfunction</TT></A><BR> +....... <A HREF="manual.html#lua_pushlstring"><TT>lua_pushlstring</TT></A><BR> +....... <A HREF="manual.html#lua_pushnil"><TT>lua_pushnil</TT></A><BR> +....... <A HREF="manual.html#lua_pushnumber"><TT>lua_pushnumber</TT></A><BR> +....... <A HREF="manual.html#lua_pushstring"><TT>lua_pushstring</TT></A><BR> +....... <A HREF="manual.html#lua_pushuserdata"><TT>lua_pushuserdata</TT></A><BR> +....... <A HREF="manual.html#lua_pushusertag"><TT>lua_pushusertag</TT></A><BR> +....... <A HREF="manual.html#lua_pushvalue"><TT>lua_pushvalue</TT></A><BR> +....... <A HREF="manual.html#lua_rawcall"><TT>lua_rawcall</TT></A><BR> +....... <A HREF="manual.html#lua_rawget"><TT>lua_rawget</TT></A><BR> +....... <A HREF="manual.html#lua_rawgeti"><TT>lua_rawgeti</TT></A><BR> +....... <A HREF="manual.html#lua_rawset"><TT>lua_rawset</TT></A><BR> +....... <A HREF="manual.html#lua_rawseti"><TT>lua_rawseti</TT></A><BR> +....... <A HREF="manual.html#lua_ref"><TT>lua_ref</TT></A><BR> +....... <A HREF="manual.html#LUA_REFNIL"><TT>LUA_REFNIL</TT></A><BR> +....... <A HREF="manual.html#LUA_REFREGISTRY"><TT>LUA_REFREGISTRY</TT></A><BR> +....... <A HREF="manual.html#lua_register"><TT>lua_register</TT></A><BR> +....... <A HREF="manual.html#lua_remove"><TT>lua_remove</TT></A><BR> +....... <A HREF="manual.html#lua_setcallhook"><TT>lua_setcallhook</TT></A><BR> +....... <A HREF="manual.html#lua_setgcthreshold"><TT>lua_setgcthreshold</TT></A><BR> +....... <A HREF="manual.html#lua_setglobal"><TT>lua_setglobal</TT></A><BR> +....... <A HREF="manual.html#lua_setglobals"><TT>lua_setglobals</TT></A><BR> +....... <A HREF="manual.html#lua_setlinehook"><TT>lua_setlinehook</TT></A><BR> +....... <A HREF="manual.html#lua_setlocal"><TT>lua_setlocal</TT></A><BR> +....... <A HREF="manual.html#lua_settable"><TT>lua_settable</TT></A><BR> +....... <A HREF="manual.html#lua_settag"><TT>lua_settag</TT></A><BR> +....... <A HREF="manual.html#lua_settagmethod"><TT>lua_settagmethod</TT></A><BR> +....... <A HREF="manual.html#lua_settop"><TT>lua_settop</TT></A><BR> +....... <A HREF="manual.html#lua_stackspace"><TT>lua_stackspace</TT></A><BR> +....... <A HREF="manual.html#lua_State"><TT>lua_State</TT></A><BR> +....... <A HREF="manual.html#lua_strlen"><TT>lua_strlen</TT></A><BR> +....... <A HREF="manual.html#lua_strlibopen"><TT>lua_strlibopen</TT></A><BR> +....... <A HREF="manual.html#lua_tag"><TT>lua_tag</TT></A><BR> +....... <A HREF="manual.html#lua_tocfunction"><TT>lua_tocfunction</TT></A><BR> +....... <A HREF="manual.html#lua_tonumber"><TT>lua_tonumber</TT></A><BR> +....... <A HREF="manual.html#lua_tostring"><TT>lua_tostring</TT></A><BR> +....... <A HREF="manual.html#lua_touserdata"><TT>lua_touserdata</TT></A><BR> +....... <A HREF="manual.html#lua_type"><TT>lua_type</TT></A><BR> +....... <A HREF="manual.html#lua_typename"><TT>lua_typename</TT></A><BR> +....... <A HREF="manual.html#lua_unref"><TT>lua_unref</TT></A><BR> +<A HREF="manual.html#C closure">C closure</A><BR> +<A HREF="manual.html#C pointers">C pointers</A><BR> +<A HREF="manual.html#call"><TT>call</TT></A><BR> <A HREF="manual.html#captures">captures</A><BR> -<A HREF="manual.html#ceil">ceil</A><BR> +<A HREF="manual.html#ceil"><TT>ceil</TT></A><BR> <A HREF="manual.html#character class">character class</A><BR> <A HREF="manual.html#chunk">chunk</A><BR> -<A HREF="manual.html#clock">clock</A><BR> -<A HREF="manual.html#closefile">closefile</A><BR> +<A HREF="manual.html#clock"><TT>clock</TT></A><BR> +<A HREF="manual.html#closefile"><TT>closefile</TT></A><BR> <A HREF="manual.html#closing a file">closing a file</A><BR> -<A HREF="manual.html#collectgarbage">collectgarbage</A><BR> -<A HREF="manual.html#concatenation event">concatenation event</A><BR> +<A HREF="manual.html#Coercion">coercion</A><BR> +<A HREF="manual.html#collectgarbage"><TT>collectgarbage</TT></A><BR> +<A HREF="manual.html#Comments">comments</A><BR> <A HREF="manual.html#concatenation">concatenation</A><BR> +<A HREF="manual.html#concatenation event">``concatenation'' event</A><BR> <A HREF="manual.html#condition expression">condition expression</A><BR> <A HREF="manual.html#constructors">constructors</A><BR> -<A HREF="manual.html#copytagmethods">copytagmethods</A><BR> -<A HREF="manual.html#cos">cos</A><BR> -<A HREF="manual.html#date">date</A><BR> -<A HREF="manual.html#debug pragma">debug pragma</A><BR> -<A HREF="manual.html#deg">deg</A><BR> -<A HREF="manual.html#div event">div event</A><BR> -<A HREF="manual.html#dofile">dofile</A><BR> -<A HREF="manual.html#dostring">dostring</A><BR> +<A HREF="manual.html#copytagmethods"><TT>copytagmethods</TT></A><BR> +<A HREF="manual.html#cos"><TT>cos</TT></A><BR> + + <P> + +<A HREF="manual.html#date"><TT>date</TT></A><BR> +<A HREF="manual.html#def"><TT>def</TT></A><BR> +<A HREF="manual.html#div event">``div'' event</A><BR> +<A HREF="manual.html#dofile"><TT>dofile</TT></A><BR> +<A HREF="manual.html#dostring"><TT>dostring</TT></A><BR> + + <P> + <A HREF="manual.html#eight-bit clean">eight-bit clean</A><BR> -<A HREF="manual.html#error">error</A><BR> +<A HREF="manual.html#error"><TT>error</TT></A><BR> <A HREF="manual.html#event">event</A><BR> -<A HREF="manual.html#execute">execute</A><BR> -<A HREF="manual.html#exit">exit</A><BR> +<A HREF="manual.html#execute"><TT>execute</TT></A><BR> +<A HREF="manual.html#exit"><TT>exit</TT></A><BR> +<A HREF="manual.html#exp"><TT>exp</TT></A><BR> <A HREF="manual.html#exponentiation">exponentiation</A><BR> +<A HREF="manual.html#Expressions">expressions</A><BR> + + <P> + <A HREF="manual.html#file handles">file handles</A><BR> -<A HREF="manual.html#floor">floor</A><BR> -<A HREF="manual.html#flush">flush</A><BR> -<A HREF="manual.html#foreachi">foreachi</A><BR> -<A HREF="manual.html#foreachvar">foreachvar</A><BR> -<A HREF="manual.html#foreach">foreach</A><BR> -<A HREF="manual.html#format">format</A><BR> -<A HREF="manual.html#frexp">frexp</A><BR> -<A HREF="manual.html#funcinfo">funcinfo</A><BR> -<A HREF="manual.html#function call">function call</A><BR> -<A HREF="manual.html#function event">function event</A><BR> +<A HREF="manual.html#floor"><TT>floor</TT></A><BR> +<A HREF="manual.html#flush"><TT>flush</TT></A><BR> +<A HREF="manual.html#for statement">for statement</A><BR> +<A HREF="manual.html#foreach"><TT>foreach</TT></A><BR> +<A HREF="manual.html#foreachi"><TT>foreachi</TT></A><BR> +<A HREF="manual.html#format"><TT>format</TT></A><BR> +<A HREF="manual.html#frexp"><TT>frexp</TT></A><BR> <A HREF="manual.html#function">function</A><BR> -<A HREF="manual.html#gc event">gc event</A><BR> -<A HREF="manual.html#ge event">ge event</A><BR> -<A HREF="manual.html#getenv">getenv</A><BR> -<A HREF="manual.html#getglobal event">getglobal event</A><BR> -<A HREF="manual.html#getglobal">getglobal</A><BR> -<A HREF="manual.html#getlocal">getlocal</A><BR> -<A HREF="manual.html#getn">getn</A><BR> -<A HREF="manual.html#getstack">getstack</A><BR> -<A HREF="manual.html#gettable event">gettable event</A><BR> -<A HREF="manual.html#gettagmethod">gettagmethod</A><BR> -<A HREF="manual.html#gettagmethod">gettagmethod</A><BR> +<A HREF="manual.html#function call">function call</A><BR> +<A HREF="manual.html#Function Definitions">function definitions</A><BR> +<A HREF="manual.html#function event">``function'' event</A><BR> + + <P> + +<A HREF="manual.html#gc event">``gc'' event</A><BR> +<A HREF="manual.html#getargs"><TT>getargs</TT></A><BR> +<A HREF="manual.html#getenv"><TT>getenv</TT></A><BR> +<A HREF="manual.html#getglobal"><TT>getglobal</TT></A><BR> +<A HREF="manual.html#getglobal event">``getglobal'' event</A><BR> +<A HREF="manual.html#getinfo"><TT>getinfo</TT></A><BR> +<A HREF="manual.html#getlocal"><TT>getlocal</TT></A><BR> +<A HREF="manual.html#getn"><TT>getn</TT></A><BR> +<A HREF="manual.html#gettable event">``gettable'' event</A><BR> +<A HREF="manual.html#gettagmethod"><TT>gettagmethod</TT></A><BR> <A HREF="manual.html#global environment">global environment</A><BR> -<A HREF="manual.html#gsub">gsub</A><BR> -<A HREF="manual.html#gt event">gt event</A><BR> -<A HREF="manual.html#if-then-else">if-then-else</A><BR> -<A HREF="manual.html#index event">index event</A><BR> -<A HREF="manual.html#ldexp">ldexp</A><BR> -<A HREF="manual.html#le event">le event</A><BR> -<A HREF="manual.html#log10">log10</A><BR> +<A HREF="manual.html#Global variables">global variables</A><BR> +<A HREF="manual.html#globals"><TT>globals</TT></A><BR> +<A HREF="manual.html#grammar">grammar</A><BR> +....... <A HREF="manual.html#args">args</A><BR> +....... <A HREF="manual.html#binop">binop</A><BR> +....... <A HREF="manual.html#block">block</A><BR> +....... <A HREF="manual.html#chunk">chunk</A><BR> +....... <A HREF="manual.html#declist">declist</A><BR> +....... <A HREF="manual.html#exp">exp</A><BR> +....... <A HREF="manual.html#exp1">exp1</A><BR> +....... <A HREF="manual.html#explist1">explist1</A><BR> +....... <A HREF="manual.html#ffield">ffield</A><BR> +....... <A HREF="manual.html#ffieldlist">ffieldlist</A><BR> +....... <A HREF="manual.html#ffieldlist1">ffieldlist1</A><BR> +....... <A HREF="manual.html#fieldlist">fieldlist</A><BR> +....... <A HREF="manual.html#funcname">funcname</A><BR> +....... <A HREF="manual.html#function">function</A><BR> +....... <A HREF="manual.html#functioncall">functioncall</A><BR> +....... <A HREF="manual.html#init">init</A><BR> +....... <A HREF="manual.html#lfieldlist">lfieldlist</A><BR> +....... <A HREF="manual.html#lfieldlist1">lfieldlist1</A><BR> +....... <A HREF="manual.html#parlist1">parlist1</A><BR> +....... <A HREF="manual.html#stat">stat</A><BR> +....... <A HREF="manual.html#tableconstructor">tableconstructor</A><BR> +....... <A HREF="manual.html#unop">unop</A><BR> +....... <A HREF="manual.html#upvalue">upvalue</A><BR> +....... <A HREF="manual.html#var">var</A><BR> +....... <A HREF="manual.html#varlist1">varlist1</A><BR> +....... <A HREF="manual.html#varorfunc">varorfunc</A><BR> +<A HREF="manual.html#gsub"><TT>gsub</TT></A><BR> + + <P> + +<A HREF="manual.html#Identifiers">identifiers</A><BR> +<A HREF="manual.html#if-then-else statement">if-then-else statement</A><BR> +<A HREF="manual.html#index event">``index'' event</A><BR> + + <P> + +<A HREF="manual.html#ldexp"><TT>ldexp</TT></A><BR> +<A HREF="manual.html#Literal strings">literal strings</A><BR> +<A HREF="manual.html#Local variables">local variables</A><BR> +<A HREF="manual.html#log"><TT>log</TT></A><BR> +<A HREF="manual.html#log10"><TT>log10</TT></A><BR> <A HREF="manual.html#logical operators">logical operators</A><BR> -<A HREF="manual.html#log">log</A><BR> -<A HREF="manual.html#lt event">lt event</A><BR> -<A HREF="manual.html#lua2C">lua2C</A><BR> -<A HREF="manual.html#lua_CFunction">lua_CFunction</A><BR> -<A HREF="manual.html#lua_Object">lua_Object</A><BR> -<A HREF="manual.html#lua_callfunction">lua_callfunction</A><BR> -<A HREF="manual.html#lua_close">lua_close</A><BR> -<A HREF="manual.html#lua_collectgarbage">lua_collectgarbage</A><BR> -<A HREF="manual.html#lua_copytagmethods">lua_copytagmethods</A><BR> -<A HREF="manual.html#lua_createtable">lua_createtable</A><BR> -<A HREF="manual.html#lua_dobuffer">lua_dobuffer</A><BR> -<A HREF="manual.html#lua_dofile">lua_dofile</A><BR> -<A HREF="manual.html#lua_dostring">lua_dostring</A><BR> -<A HREF="manual.html#lua_error">lua_error</A><BR> -<A HREF="manual.html#lua_getcfunction">lua_getcfunction</A><BR> -<A HREF="manual.html#lua_getglobal">lua_getglobal</A><BR> -<A HREF="manual.html#lua_getnumber">lua_getnumber</A><BR> -<A HREF="manual.html#lua_getparam">lua_getparam</A><BR> -<A HREF="manual.html#lua_getref">lua_getref</A><BR> -<A HREF="manual.html#lua_getresult">lua_getresult</A><BR> -<A HREF="manual.html#lua_getstring">lua_getstring</A><BR> -<A HREF="manual.html#lua_gettable">lua_gettable</A><BR> -<A HREF="manual.html#lua_gettagmethod">lua_gettagmethod</A><BR> -<A HREF="manual.html#lua_getuserdata">lua_getuserdata</A><BR> -<A HREF="manual.html#lua_iolibopen">lua_iolibopen</A><BR> -<A HREF="manual.html#lua_iscfunction">lua_iscfunction</A><BR> -<A HREF="manual.html#lua_isfunction">lua_isfunction</A><BR> -<A HREF="manual.html#lua_isnil">lua_isnil</A><BR> -<A HREF="manual.html#lua_isnumber">lua_isnumber</A><BR> -<A HREF="manual.html#lua_isstring">lua_isstring</A><BR> -<A HREF="manual.html#lua_istable">lua_istable</A><BR> -<A HREF="manual.html#lua_isuserdata">lua_isuserdata</A><BR> -<A HREF="manual.html#lua_lua2C">lua_lua2C</A><BR> -<A HREF="manual.html#lua_mathlibopen">lua_mathlibopen</A><BR> -<A HREF="manual.html#lua_newtag">lua_newtag</A><BR> -<A HREF="manual.html#lua_open">lua_open</A><BR> -<A HREF="manual.html#lua_pop">lua_pop</A><BR> -<A HREF="manual.html#lua_pushcclosure">lua_pushcclosure</A><BR> -<A HREF="manual.html#lua_pushcfunction">lua_pushcfunction</A><BR> -<A HREF="manual.html#lua_pushlstring">lua_pushlstring</A><BR> -<A HREF="manual.html#lua_pushnil">lua_pushnil</A><BR> -<A HREF="manual.html#lua_pushnumber">lua_pushnumber</A><BR> -<A HREF="manual.html#lua_pushobject">lua_pushobject</A><BR> -<A HREF="manual.html#lua_pushstring">lua_pushstring</A><BR> -<A HREF="manual.html#lua_pushuserdata">lua_pushuserdata</A><BR> -<A HREF="manual.html#lua_pushusertag">lua_pushusertag</A><BR> -<A HREF="manual.html#lua_rawgetglobal">lua_rawgetglobal</A><BR> -<A HREF="manual.html#lua_rawgetglobal">lua_rawgetglobal</A><BR> -<A HREF="manual.html#lua_rawgetglobal">lua_rawgetglobal</A><BR> -<A HREF="manual.html#lua_rawsettable">lua_rawsettable</A><BR> -<A HREF="manual.html#lua_ref">lua_ref</A><BR> -<A HREF="manual.html#lua_register">lua_register</A><BR> -<A HREF="manual.html#lua_setglobal">lua_setglobal</A><BR> -<A HREF="manual.html#lua_setstate">lua_setstate</A><BR> -<A HREF="manual.html#lua_settable">lua_settable</A><BR> -<A HREF="manual.html#lua_settagmethod">lua_settagmethod</A><BR> -<A HREF="manual.html#lua_settag">lua_settag</A><BR> -<A HREF="manual.html#lua_state">lua_state</A><BR> -<A HREF="manual.html#lua_strlen">lua_strlen</A><BR> -<A HREF="manual.html#lua_strlibopen">lua_strlibopen</A><BR> -<A HREF="manual.html#lua_tag">lua_tag</A><BR> -<A HREF="manual.html#lua_unref">lua_unref</A><BR> -<A HREF="manual.html#luac">luac</A><BR> -<A HREF="manual.html#luac">luac</A><BR> -<A HREF="manual.html#max">max</A><BR> +<A HREF="manual.html#lt event">``lt'' event</A><BR> +<A HREF="manual.html#Lua Stand-alone">Lua stand-alone</A><BR> +<A HREF="manual.html#luac"><TT>luac</TT></A><BR> + + <P> + +<A HREF="manual.html#max"><TT>max</TT></A><BR> <A HREF="manual.html#methods">methods</A><BR> -<A HREF="manual.html#min">min</A><BR> -<A HREF="manual.html#mod">mod</A><BR> -<A HREF="manual.html#mul event">mul event</A><BR> +<A HREF="manual.html#min"><TT>min</TT></A><BR> +<A HREF="manual.html#mod"><TT>mod</TT></A><BR> +<A HREF="manual.html#mul event">``mul'' event</A><BR> <A HREF="manual.html#multiple assignment">multiple assignment</A><BR> -<A HREF="manual.html#newtag">newtag</A><BR> -<A HREF="manual.html#nextvar">nextvar</A><BR> -<A HREF="manual.html#next">next</A><BR> + + <P> + +<A HREF="manual.html#newtag"><TT>newtag</TT></A><BR> +<A HREF="manual.html#next"><TT>next</TT></A><BR> <A HREF="manual.html#nil">nil</A><BR> <A HREF="manual.html#not">not</A><BR> <A HREF="manual.html#number">number</A><BR> -<A HREF="manual.html#openfile">openfile</A><BR> +<A HREF="manual.html#Numerical constants">numerical constants</A><BR> + + <P> + +<A HREF="manual.html#openfile"><TT>openfile</TT></A><BR> +<A HREF="manual.html#Operator precedence">operator precedence</A><BR> <A HREF="manual.html#or">or</A><BR> -<A HREF="manual.html#packed results">packed results</A><BR> -<A HREF="manual.html#pattern item">pattern item</A><BR> + + <P> + <A HREF="manual.html#pattern">pattern</A><BR> +<A HREF="manual.html#pattern item">pattern item</A><BR> +<A HREF="manual.html#PI"><TT>PI</TT></A><BR> <A HREF="manual.html#piped input">piped input</A><BR> -<A HREF="manual.html#piped output">piped output</A><BR> -<A HREF="manual.html#popen">popen</A><BR> -<A HREF="manual.html#popen">popen</A><BR> -<A HREF="manual.html#pow event">pow event</A><BR> +<A HREF="manual.html#popen"><TT>popen</TT></A><BR> +<A HREF="manual.html#pow event">``pow'' event</A><BR> <A HREF="manual.html#pre-compilation">pre-compilation</A><BR> -<A HREF="manual.html#predefined functions">predefined functions</A><BR> -<A HREF="manual.html#print">print</A><BR> +<A HREF="manual.html#print"><TT>print</TT></A><BR> <A HREF="manual.html#protected calls">protected calls</A><BR> -<A HREF="manual.html#rad">rad</A><BR> -<A HREF="manual.html#randomseed">randomseed</A><BR> -<A HREF="manual.html#random">random</A><BR> -<A HREF="manual.html#rawgetglobal">rawgetglobal</A><BR> -<A HREF="manual.html#rawgettable">rawgettable</A><BR> -<A HREF="manual.html#rawsetglobal">rawsetglobal</A><BR> -<A HREF="manual.html#rawsettable">rawsettable</A><BR> -<A HREF="manual.html#read pattern">read pattern</A><BR> -<A HREF="manual.html#readfrom">readfrom</A><BR> -<A HREF="manual.html#read">read</A><BR> + + <P> + +<A HREF="manual.html#rad"><TT>rad</TT></A><BR> +<A HREF="manual.html#random"><TT>random</TT></A><BR> +<A HREF="manual.html#randomseed"><TT>randomseed</TT></A><BR> +<A HREF="manual.html#rawget"><TT>rawget</TT></A><BR> +<A HREF="manual.html#rawset"><TT>rawset</TT></A><BR> +<A HREF="manual.html#read"><TT>read</TT></A><BR> +<A HREF="manual.html#readfrom"><TT>readfrom</TT></A><BR> <A HREF="manual.html#records">records</A><BR> <A HREF="manual.html#reference">reference</A><BR> -<A HREF="manual.html#reflexivity">reflexivity</A><BR> <A HREF="manual.html#relational operators">relational operators</A><BR> -<A HREF="manual.html#remove">remove</A><BR> -<A HREF="manual.html#rename">rename</A><BR> -<A HREF="manual.html#repeat-until">repeat-until</A><BR> +<A HREF="manual.html#remove"><TT>remove</TT></A><BR> +<A HREF="manual.html#rename"><TT>rename</TT></A><BR> +<A HREF="manual.html#repeat-until statement">repeat-until statement</A><BR> <A HREF="manual.html#reserved words">reserved words</A><BR> <A HREF="manual.html#return statement">return statement</A><BR> -<A HREF="manual.html#return">return</A><BR> -<A HREF="manual.html#seek">seek</A><BR> -<A HREF="manual.html#self">self</A><BR> -<A HREF="manual.html#setcallhook">setcallhook</A><BR> -<A HREF="manual.html#setglobal event">setglobal event</A><BR> -<A HREF="manual.html#setglobal">setglobal</A><BR> -<A HREF="manual.html#setlinehook">setlinehook</A><BR> -<A HREF="manual.html#setlocale">setlocale</A><BR> -<A HREF="manual.html#setlocal">setlocal</A><BR> -<A HREF="manual.html#settable event">settable event</A><BR> -<A HREF="manual.html#settagmethod">settagmethod</A><BR> -<A HREF="manual.html#settagmethod">settagmethod</A><BR> -<A HREF="manual.html#settag">settag</A><BR> + + <P> + +<A HREF="manual.html#seek"><TT>seek</TT></A><BR> +<A HREF="manual.html#self"><TT>self</TT></A><BR> +<A HREF="manual.html#setcallhook"><TT>setcallhook</TT></A><BR> +<A HREF="manual.html#setglobal"><TT>setglobal</TT></A><BR> +<A HREF="manual.html#setglobal event">``setglobal'' event</A><BR> +<A HREF="manual.html#setlinehook"><TT>setlinehook</TT></A><BR> +<A HREF="manual.html#setlocal"><TT>setlocal</TT></A><BR> +<A HREF="manual.html#setlocale"><TT>setlocale</TT></A><BR> +<A HREF="manual.html#settable event">``settable'' event</A><BR> +<A HREF="manual.html#settag"><TT>settag</TT></A><BR> +<A HREF="manual.html#settagmethod"><TT>settagmethod</TT></A><BR> <A HREF="manual.html#short-cut evaluation">short-cut evaluation</A><BR> -<A HREF="manual.html#sin">sin</A><BR> -<A HREF="manual.html#skips">skips</A><BR> -<A HREF="manual.html#sort">sort</A><BR> -<A HREF="manual.html#sqrt">sqrt</A><BR> +<A HREF="manual.html#sin"><TT>sin</TT></A><BR> +<A HREF="manual.html#sort"><TT>sort</TT></A><BR> +<A HREF="manual.html#sqrt"><TT>sqrt</TT></A><BR> +<A HREF="manual.html#stack index">stack index</A><BR> +<A HREF="manual.html#state">state</A><BR> <A HREF="manual.html#statements">statements</A><BR> -<A HREF="manual.html#stderr">stderr</A><BR> -<A HREF="manual.html#strbyte">strbyte</A><BR> -<A HREF="manual.html#strchar">strchar</A><BR> -<A HREF="manual.html#strfind">strfind</A><BR> +<A HREF="manual.html#stderr"><TT>stderr</TT></A><BR> +<A HREF="manual.html#strbyte"><TT>strbyte</TT></A><BR> +<A HREF="manual.html#strchar"><TT>strchar</TT></A><BR> +<A HREF="manual.html#strfind"><TT>strfind</TT></A><BR> <A HREF="manual.html#string">string</A><BR> -<A HREF="manual.html#strlen">strlen</A><BR> -<A HREF="manual.html#strlower">strlower</A><BR> -<A HREF="manual.html#strrep">strrep</A><BR> -<A HREF="manual.html#strsub">strsub</A><BR> -<A HREF="manual.html#strupper">strupper</A><BR> -<A HREF="manual.html#sub event">sub event</A><BR> +<A HREF="manual.html#strlen"><TT>strlen</TT></A><BR> +<A HREF="manual.html#strlower"><TT>strlower</TT></A><BR> +<A HREF="manual.html#strrep"><TT>strrep</TT></A><BR> +<A HREF="manual.html#strsub"><TT>strsub</TT></A><BR> +<A HREF="manual.html#strupper"><TT>strupper</TT></A><BR> +<A HREF="manual.html#sub event">``sub'' event</A><BR> + + <P> + <A HREF="manual.html#table">table</A><BR> -<A HREF="manual.html#tag methods">tag methods</A><BR> <A HREF="manual.html#tag">tag</A><BR> -<A HREF="manual.html#tag">tag</A><BR> -<A HREF="manual.html#tan">tan</A><BR> -<A HREF="manual.html#tinsert">tinsert</A><BR> -<A HREF="manual.html#tmpname">tmpname</A><BR> +<A HREF="manual.html#tag"><TT>tag</TT></A><BR> +<A HREF="manual.html#tag method">tag method</A><BR> +....... <A HREF="manual.html#add">add</A><BR> +....... <A HREF="manual.html#concatenation">concatenation</A><BR> +....... <A HREF="manual.html#div">div</A><BR> +....... <A HREF="manual.html#function">function</A><BR> +....... <A HREF="manual.html#gc">gc</A><BR> +....... <A HREF="manual.html#getglobal">getglobal</A><BR> +....... <A HREF="manual.html#gettable">gettable</A><BR> +....... <A HREF="manual.html#index">index</A><BR> +....... <A HREF="manual.html#lt">lt</A><BR> +....... <A HREF="manual.html#mul">mul</A><BR> +....... <A HREF="manual.html#pow">pow</A><BR> +....... <A HREF="manual.html#setglobal">setglobal</A><BR> +....... <A HREF="manual.html#settable">settable</A><BR> +....... <A HREF="manual.html#sub">sub</A><BR> +....... <A HREF="manual.html#unm">unm</A><BR> +<A HREF="manual.html#tan"><TT>tan</TT></A><BR> +<A HREF="manual.html#tinsert"><TT>tinsert</TT></A><BR> +<A HREF="manual.html#tmpname"><TT>tmpname</TT></A><BR> <A HREF="manual.html#tokens">tokens</A><BR> -<A HREF="manual.html#tonumber">tonumber</A><BR> -<A HREF="manual.html#tostring">tostring</A><BR> -<A HREF="manual.html#tremove">tremove</A><BR> -<A HREF="manual.html#type">type</A><BR> -<A HREF="manual.html#unm event">unm event</A><BR> +<A HREF="manual.html#tonumber"><TT>tonumber</TT></A><BR> +<A HREF="manual.html#tostring"><TT>tostring</TT></A><BR> +<A HREF="manual.html#tremove"><TT>tremove</TT></A><BR> +<A HREF="manual.html#type"><TT>type</TT></A><BR> +<A HREF="manual.html#Types and Tags">types and tags</A><BR> + + <P> + +<A HREF="manual.html#unm event">``unm'' event</A><BR> +<A HREF="manual.html#upvalues">upvalues</A><BR> <A HREF="manual.html#userdata">userdata</A><BR> -<A HREF="manual.html#vararg">vararg</A><BR> -<A HREF="manual.html#version 3.0">version 3.0</A><BR> -<A HREF="manual.html#version 3.1">version 3.1</A><BR> -<A HREF="manual.html#while-do">while-do</A><BR> -<A HREF="manual.html#writeto">writeto</A><BR> -<A HREF="manual.html#write">write</A><BR> + + <P> + +<A HREF="manual.html#valid index">valid index</A><BR> +<A HREF="manual.html#vararg function">vararg function</A><BR> +<A HREF="manual.html#version 3.2">version 3.2</A><BR> +<A HREF="manual.html#visibility">visibility</A><BR> + + <P> + +<A HREF="manual.html#while-do statement">while-do statement</A><BR> +<A HREF="manual.html#write"><TT>write</TT></A><BR> +<A HREF="manual.html#writeto"><TT>writeto</TT></A><BR> + + <P> + <HR> <SMALL> Last update: -Wed Jul 7 13:36:24 EST 1999 +Mon Nov 6 17:35:51 EDT 2000 by <A HREF="http://www.tecgraf.puc-rio.br/~lhf/">lhf</A>. </SMALL> diff --git a/doc/index.html b/doc/index.html index e6ff5faf..b7603a30 100644 --- a/doc/index.html +++ b/doc/index.html @@ -1,30 +1,23 @@ <HTML> <HEAD> -<TITLE>Lua 3.2 Reference Manual - Contents</TITLE> +<TITLE>Lua: reference manual - contents</TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <HR> -<H1>Reference Manual of the Programming Language -<A HREF="http://www.tecgraf.puc-rio.br/lua/">Lua</A> -3.2</H1> -<P> -<A HREF="http://www.inf.puc-rio.br/~roberto/">Roberto Ierusalimschy</A>, -<A HREF="http://www.tecgraf.puc-rio.br/~lhf/">Luiz Henrique de Figueiredo</A>, -<A HREF="http://www.tecgraf.puc-rio.br/~celes/">Waldemar Celes</A> -<BR> -<A HREF="mailto:lua@tecgraf.puc-rio.br">lua@tecgraf.puc-rio.br</A><BR> -<A HREF="http://www.tecgraf.puc-rio.br">TeCGraf</A>, -<A HREF="http://www.inf.puc-rio.br">Computer Science Department</A>, -<A HREF="http://www.puc-rio.br">PUC-Rio</A> -<P> +<H1> +<IMG SRC="logo.gif" ALT="Lua" ALIGN="bottom"> +Reference manual +</H1> +<A HREF="manual.html"> +Reference Manual of the Programming Language +<A HREF="http://www.tecgraf.puc-rio.br/lua/">Lua</A> +4.0</A> [ <A HREF="manual.html">top</A> | -<A HREF="#contents">contents</A> -| <A HREF="idx.html">index</A> | <A HREF="ftp://ftp.tecgraf.puc-rio.br/pub/lua/refman.ps.gz">ps</A> @@ -33,7 +26,7 @@ | <A HREF="old/">old versions</A> ] -<HR> +<P> <A NAME="contents"></A> <UL> <LI><A HREF="manual.html#1.">1 - Introduction</A> @@ -42,50 +35,57 @@ <LI><A HREF="manual.html#4.">4 - The Language</A> <UL> <LI><A HREF="manual.html#4.1">4.1 - Lexical Conventions</A> - <LI><A HREF="manual.html#4.2">4.2 - The Pre-processor</A> - <LI><A HREF="manual.html#4.3">4.3 - Coercion</A> - <LI><A HREF="manual.html#4.4">4.4 - Adjustment</A> - <LI><A HREF="manual.html#4.5">4.5 - Statements</A> - <LI><A HREF="manual.html#4.6">4.6 - Expressions</A> - <LI><A HREF="manual.html#4.7">4.7 - Visibility and Upvalues</A> + <LI><A HREF="manual.html#4.2">4.2 - Coercion</A> + <LI><A HREF="manual.html#4.3">4.3 - Adjustment</A> + <LI><A HREF="manual.html#4.4">4.4 - Statements</A> + <LI><A HREF="manual.html#4.5">4.5 - Expressions</A> + <LI><A HREF="manual.html#4.6">4.6 - Visibility and Upvalues</A> + <LI><A HREF="manual.html#4.7">4.7 - Error Handling</A> <LI><A HREF="manual.html#4.8">4.8 - Tag Methods</A> - <LI><A HREF="manual.html#4.9">4.9 - Error Handling</A> </UL> <LI><A HREF="manual.html#5.">5 - The Application Program Interface</A> <UL> - <LI><A HREF="manual.html#5.1">5.1 - Managing States</A> - <LI><A HREF="manual.html#5.2">5.2 - Exchanging Values between C and Lua</A> - <LI><A HREF="manual.html#5.3">5.3 - Garbage Collection</A> - <LI><A HREF="manual.html#5.4">5.4 - Executing Lua Code</A> - <LI><A HREF="manual.html#5.5">5.5 - Manipulating Lua Objects</A> - <LI><A HREF="manual.html#5.6">5.6 - Calling Lua Functions</A> - <LI><A HREF="manual.html#5.7">5.7 - C Functions</A> - <LI><A HREF="manual.html#5.8">5.8 - References to Lua Objects</A> + <LI><A HREF="manual.html#5.1">5.1 - States</A> + <LI><A HREF="manual.html#5.2">5.2 - The Stack and Indices</A> + <LI><A HREF="manual.html#5.3">5.3 - Stack Manipulation</A> + <LI><A HREF="manual.html#5.4">5.4 - Querying the Stack</A> + <LI><A HREF="manual.html#5.5">5.5 - Pushing values onto the Stack</A> + <LI><A HREF="manual.html#5.6">5.6 - Garbage Collection</A> + <LI><A HREF="manual.html#5.7">5.7 - Userdata and Tags</A> + <LI><A HREF="manual.html#5.8">5.8 - Executing Lua Code</A> + <LI><A HREF="manual.html#5.9">5.9 - Manipulating Global Variables in Lua</A> + <LI><A HREF="manual.html#5.10">5.10 - Manipulating Tables in Lua</A> + <LI><A HREF="manual.html#5.11">5.11 - Using Tables as Arrays</A> + <LI><A HREF="manual.html#5.12">5.12 - Calling Lua Functions</A> + <LI><A HREF="manual.html#5.13">5.13 - Defining C Functions</A> + <LI><A HREF="manual.html#5.14">5.14 - References to Lua Objects</A> </UL> -<LI><A HREF="manual.html#6.">6 - Predefined Functions and Libraries</A> +<LI><A HREF="manual.html#6.">6 - Standard Libraries</A> <UL> - <LI><A HREF="manual.html#6.1">6.1 - Predefined Functions</A> + <LI><A HREF="manual.html#6.1">6.1 - Basic Functions</A> <LI><A HREF="manual.html#6.2">6.2 - String Manipulation</A> <LI><A HREF="manual.html#6.3">6.3 - Mathematical Functions</A> <LI><A HREF="manual.html#6.4">6.4 - I/O Facilities</A> + <LI><A HREF="manual.html#6.5">6.5 - System Facilities</A> </UL> -<LI><A HREF="manual.html#7.">7 - The Debugger Interface</A> +<LI><A HREF="manual.html#7.">7 - The Debug Interface</A> <UL> <LI><A HREF="manual.html#7.1">7.1 - Stack and Function Information</A> <LI><A HREF="manual.html#7.2">7.2 - Manipulating Local Variables</A> <LI><A HREF="manual.html#7.3">7.3 - Hooks</A> - <LI><A HREF="manual.html#7.4">7.4 - The Reflexive Debugger Interface</A> + <LI><A HREF="manual.html#7.4">7.4 - The Reflexive Debug Interface</A> </UL> <LI><A HREF="manual.html#8.">8 - Lua Stand-alone</A> <LI><A HREF="manual.html#Acknowledgments">Acknowledgments</A> <LI><A HREF="manual.html#Incompatibilities">Incompatibilities with Previous Versions</A> +<LI><A HREF="manual.html#BNF">The Complete Syntax of Lua</A> <LI><A HREF="idx.html">Index</A> </UL> <HR> <SMALL> Last update: -Wed Jul 7 13:36:24 EST 1999 +Mon Nov 6 17:36:08 EDT 2000 by <A HREF="http://www.tecgraf.puc-rio.br/~lhf/">lhf</A>. </SMALL> diff --git a/doc/logo.gif b/doc/logo.gif Binary files differnew file mode 100644 index 00000000..f3e68936 --- /dev/null +++ b/doc/logo.gif diff --git a/doc/lua.1 b/doc/lua.1 new file mode 100644 index 00000000..b1561818 --- /dev/null +++ b/doc/lua.1 @@ -0,0 +1,143 @@ +.\" lua.man,v 1.3 2000/09/04 21:41:28 lhf Exp +.TH LUA 1 "2000/09/04 21:41:28" +.SH NAME +lua \- Lua interpreter +.SH SYNOPSIS +.B lua +[ +.I arguments +] +.SH DESCRIPTION +.B lua +is the stand-alone Lua interpreter. +It loads and executes Lua programs, +either in textual source form or +in precompiled binary form, +as output by +.BR luac , +the Lua compiler. +.B lua +can be used as a batch interpreter and also interactively. +.LP +The +.I arguments +can be options, assignments, or filenames, +and are processed in order, +from left to right. +.LP +Options start with +.B \- +and are described below. +.LP +An assignment is an argument of the form +.BR a=b , +which assigns the string +.RB ` b ' +to the global variable +.BR a . +Note that no quotes are needed around the string if it does not contain spaces +or other characters special to the shell. +This is for convenience only. +(In general, +you should be careful when using quotes and spaces on the command line +because they are usually handled by the shell.) +.LP +If the argument is neither an option nor an assignment, +then it is assumed to be a filename, +which is then loaded and executed. +.LP +If no arguments are given, +then +.B "\-v \-i" +is assumed when the standard input is a terminal; +otherwise, +.B \- +is assumed. +.SH OPTIONS +.TP +.B \- +load the standard input as a file, +that is, +not interactively, +even when the standard input is a terminal. +.TP +.B \-c +close Lua before exiting. +.TP +.BI \-e " stat" +execute statement +.IR stat . +You will need to quote +.I stat +if it contains spaces or quotes. +.TP +.BI \-f " file" +collect all remaining arguments as strings into a global table named +.B arg +and then execute +.IR file . +The arguments in +.B arg +start at 0, +which contains the string +.RI ` file '. +The index of the last argument is stored in +.BR "arg.n" . +.TP +.B \-i +enter interactive mode, +displaying a prompt. +In this mode, +.B lua +reads lines from the standard input and executes them as they are read. +Each line must contain a complete statement. +To span a statement across several lines, end each line with a backslash +.BR `\e' . +The prompt shown is the value of the global variable +.BR _PROMPT , +if this value is a string. +So, +to change the prompt, +set +.B _PROMPT +to a string of your choice. +You can do that after calling the interpreter +or on the command line with +.BR "_PROMPT=\'lua: \'" , +for example. +(Note the need for quotes, because the string contains a space.) +The default prompt is ``> ''. +.TP +.B \-q +enter interactive mode, +but without displaying a prompt. +.TP +.BI \-s n +set the stack size to +.IB n . +If present, +this must be the first option. +Note that +.I n +is in the same argument as +.BR -s . +For example, +to specify a stack size of 2000, +use +.BR -s2000 . +.TP +.B \-v +print version information. +.SH "SEE ALSO" +.BR luac (1) +.br +http://www.tecgraf.puc-rio.br/lua/ +.SH DIAGNOSTICS +Error messages should be self explanatory. +.SH AUTHORS +R. Ierusalimschy, +L. H. de Figueiredo, +and +W. Celes +(lua@tecgraf.puc-rio.br) +.\" EOF diff --git a/doc/lua.html b/doc/lua.html new file mode 100644 index 00000000..ef861bb5 --- /dev/null +++ b/doc/lua.html @@ -0,0 +1,151 @@ +<!-- lua.man,v 1.3 2000/09/04 21:41:28 lhf Exp --> +<HTML> +<HEAD> +<TITLE>LUA man page</TITLE> +</HEAD> + +<BODY BGCOLOR="#FFFFFF"> + +<H1>NAME</H1> +lua - Lua interpreter +<H1>SYNOPSIS</H1> +<B>lua</B> +[ +<I>arguments</I> +] +<H1>DESCRIPTION</H1> +<B>lua</B> +is the stand-alone Lua interpreter. +It loads and executes Lua programs, +either in textual source form or +in precompiled binary form, +as output by +<B>luac</B>, +the Lua compiler. +<B>lua</B> +can be used as a batch interpreter and also interactively. +<P> +The +<I>arguments</I> +can be options, assignments, or filenames, +and are processed in order, +from left to right. +<P> +Options start with +<B>-</B> +and are described below. +<P> +An assignment is an argument of the form +<B>a=b</B>, +which assigns the string +.RB ` b ' +to the global variable +<B>a</B>. +Note that no quotes are needed around the string if it does not contain spaces +or other characters special to the shell. +This is for convenience only. +(In general, +you should be careful when using quotes and spaces on the command line +because they are usually handled by the shell.) +<P> +If the argument is neither an option nor an assignment, +then it is assumed to be a filename, +which is then loaded and executed. +<P> +If no arguments are given, +then +<B>"-v -i"</B> +is assumed when the standard input is a terminal; +otherwise, +<B>-</B> +is assumed. +<H1>OPTIONS</H1> +<P> +<B>-</B> +load the standard input as a file, +that is, +not interactively, +even when the standard input is a terminal. +<P> +<B>-c</B> +close Lua before exiting. +<P> +<B>-e "</B><I>stat"</I> +execute statement +<I>stat</I>. +You will need to quote +<I>stat </I> +if it contains spaces or quotes. +<P> +<B>-f "</B><I>file"</I> +collect all remaining arguments as strings into a global table named +<B>arg</B> +and then execute +<I>file</I>. +The arguments in +<B>arg</B> +start at 0, +which contains the string +.RI ` file '. +The index of the last argument is stored in +<B>"arg.n"</B>. +<P> +<B>-i</B> +enter interactive mode, +displaying a prompt. +In this mode, +<B>lua</B> +reads lines from the standard input and executes them as they are read. +Each line must contain a complete statement. +To span a statement across several lines, end each line with a backslash +<B>`\e'</B>. +The prompt shown is the value of the global variable +<B>_PROMPT</B>, +if this value is a string. +So, +to change the prompt, +set +<B>_PROMPT</B> +to a string of your choice. +You can do that after calling the interpreter +or on the command line with +<B>"_PROMPT=\'lua: \'"</B>, +for example. +(Note the need for quotes, because the string contains a space.) +The default prompt is ``> ''. +<P> +<B>-q</B> +enter interactive mode, +but without displaying a prompt. +<P> +<B>-s</B><I>n</I> +set the stack size to +.IB n . +If present, +this must be the first option. +Note that +<I>n</I> +is in the same argument as +<B>-s</B>. +For example, +to specify a stack size of 2000, +use +<B>-s2000</B>. +<P> +<B>-v</B> +print version information. +<H1>SEE ALSO</H1> +<B>luac</B>(1) +<BR> +<A HREF="http://www.tecgraf.puc-rio.br/lua/">http://www.tecgraf.puc-rio.br/lua/</A> +<H1>DIAGNOSTICS</H1> +Error messages should be self explanatory. +<H1>AUTHORS</H1> +R. Ierusalimschy, +L. H. de Figueiredo, +and +W. Celes +(<A HREF="mailto:lua@tecgraf.puc-rio.br">lua@tecgraf.puc-rio.br</A>) +<!-- EOF --> +</BODY> +</HTML> diff --git a/doc/luac.1 b/doc/luac.1 new file mode 100644 index 00000000..212f9b61 --- /dev/null +++ b/doc/luac.1 @@ -0,0 +1,139 @@ +.\" luac.man,v 1.20 2000/10/06 15:11:21 lhf Exp +.TH LUAC 1 "2000/10/06 15:11:21" +.SH NAME +luac \- Lua compiler +.SH SYNOPSIS +.B luac +[ +.I options +] [ +.I filenames +] +.SH DESCRIPTION +.B luac +is the Lua compiler. +It translates programs written in the Lua programming language +into binary files that can be loaded and executed with +.B lua_dofile +in C or with +.B dofile +in Lua. +.LP +The main advantages of precompiling chunks are: +faster loading, +protecting source code from user changes, +and +off-line syntax error detection. +.LP +Pre-compiling does not imply faster execution +because in Lua chunks are always compiled into bytecodes before being executed. +.B luac +simply allows those bytecodes to be saved in a file for later execution. +.LP +.B luac +produces a single output file containing the bytecodes +for all source files given. +By default, +the output file is named +.BR luac.out , +but you can change this with the +.B \-o +option. +.LP +The binary files created by +.B luac +are portable to all architectures with the same word size. +This means that +binary files created on a 32-bit platform (such as Intel) +can be read without change in another 32-bit platform (such as Sparc), +even if the byte order (``endianess'') is different. +On the other hand, +binary files created on a 16-bit platform cannot be read in a 32-bit platform. +.LP +In the command line, +you can mix +text files containing Lua source and +binary files containing precompiled chunks. +This is useful to combine several precompiled chunks, +even from different (but compatible) platforms, +into a single precompiled chunk. +.LP +You can use +.B "\-" +to indicate +.I stdin +as a source file. +.LP +The internal format of the binary files produced by +.B luac +may change when a new version of Lua is released. +We try to maintain compatibility even for binary files, +but it is not always possible. +So, +save the source files of all Lua programs that you precompile. +.LP +.SH OPTIONS +Options must be separate. +.TP +.B \-l +produce a listing of the compiled bytecode for Lua's virtual machine. +Listing bytecodes is useful to learn about Lua's virtual machine. +If no files are given, then +.B luac +loads +.B luac.out +and lists its contents. +.TP +.BI \-o " file" +output to +.IR file , +instead of the default +.BR luac.out . +The output file can be a source file because +all files are loaded before the output file is written. +.TP +.B \-p +load files but do not generate any output file. +Used mainly for syntax checking or testing precompiled chunks: +corrupted files will probably generate errors when loaded. +For a thourough integrity test, +use +.BR \-t . +.TP +.B \-s +strip debug information before writing the output file. +This saves some space in very large chunks, +but if errors occur when running these chunks, +then the error messages might not contain the full information they usually do. +.TP +.B \-t +perform a thourough integrity test of precompiled chunks. +Code that passes this test is completely safe, +in the sense that it will not break the interpreter. +However, +there is no guarantee that such code does anything sensible. +(None can be given, because the halting problem is unsolvable.) +If no files are given, then +.B luac +loads +.B luac.out +and tests its contents. +.TP +.B \-v +print version information. +.SH FILES +.TP 15 +.B luac.out +default output file +.SH "SEE ALSO" +.BR lua (1) +.br +http://www.tecgraf.puc-rio.br/lua/ +.SH DIAGNOSTICS +Error messages should be self explanatory. +.SH AUTHORS +L. H. de Figueiredo, +R. Ierusalimschy and +W. Celes +(lua@tecgraf.puc-rio.br) +.\" EOF diff --git a/doc/luac.html b/doc/luac.html index 92d9ddf1..e083c2b3 100644 --- a/doc/luac.html +++ b/doc/luac.html @@ -1,4 +1,4 @@ -<!-- luac.man,v 1.17 1999/07/07 16:02:07 lhf Exp --> +<!-- luac.man,v 1.20 2000/10/06 15:11:21 lhf Exp --> <HTML> <HEAD> <TITLE>LUAC man page</TITLE> @@ -25,14 +25,11 @@ in C or with <B>dofile</B> in Lua. <P> -The main advantages of pre-compiling chunks are: +The main advantages of precompiling chunks are: faster loading, protecting source code from user changes, and off-line syntax error detection. -The binary files created by -<B>luac</B> -are portable to all architectures. <P> Pre-compiling does not imply faster execution because in Lua chunks are always compiled into bytecodes before being executed. @@ -49,126 +46,87 @@ but you can change this with the <B>-o</B> option. <P> +The binary files created by +<B>luac</B> +are portable to all architectures with the same word size. +This means that +binary files created on a 32-bit platform (such as Intel) +can be read without change in another 32-bit platform (such as Sparc), +even if the byte order (``endianess'') is different. +On the other hand, +binary files created on a 16-bit platform cannot be read in a 32-bit platform. +<P> +In the command line, +you can mix +text files containing Lua source and +binary files containing precompiled chunks. +This is useful to combine several precompiled chunks, +even from different (but compatible) platforms, +into a single precompiled chunk. +<P> You can use <B>"-"</B> to indicate <I>stdin</I> as a source file. <P> -<B>luac</B> -can also load and list binary files with the -<B>-u</B> -option. -<P> -Binary files produced by differents runs of -<B>luac</B> -(even in different machines) -can be combined into one large file, -using -<B>cat</B>(1). -The result is still a valid binary file -and can be loaded with a single call to -<B>lua_dofile</B> -or -<B>dofile</B>. -<P> The internal format of the binary files produced by <B>luac</B> may change when a new version of Lua is released. We try to maintain compatibility even for binary files, -but sometimes it cannot be done. +but it is not always possible. So, save the source files of all Lua programs that you precompile. <P> <H1>OPTIONS</H1> Options must be separate. <P> -<B>-c</B> -compile (this is the default). -<P> -<B>-u</B> -undump, i.e., load and list the given binary files. -If no files are given, then luac undumps -<B>luac.out</B>. -Listing a binary file is useful to learn Lua's virtual machine. -Listing is also useful to test the integrity of binary files: -corrupted files will probably generate errors when undumped. -To test without listing, use -<B>-q</B>. -For a thourough integrity test, -use -<B>-t</B>. -<P> -<B>-d</B> -turn debugging on. -Individual chunks may -still control the generation of debug information with -$debug and $nodebug. -If debugging is on, then listings show the names of the local variables. -<P> -<B>-D "</B><I>name"</I> -predefine symbol -<I>name</I> -for conditional compilation. -By default, -<B>luac</B> -does -<I>not</I> -predefine any symbols, -not even the built-in functions. -<P> <B>-l</B> produce a listing of the compiled bytecode for Lua's virtual machine. -This is the default when undumping. -<P> -<B>-n</B> -Save numbers in native format. -By default, -numbers are saved in text form, -for maximum portability. -Binary files with numbers in native format are slightly faster to load, -but are not completely portable. +Listing bytecodes is useful to learn about Lua's virtual machine. +If no files are given, then +<B>luac</B> +loads +<B>luac.out</B> +and lists its contents. <P> -<B>-o "</B><I>filename"</I> +<B>-o "</B><I>file"</I> output to -<I>filename</I>, +<I>file</I>, instead of the default <B>luac.out</B>. -The output file cannot be a source file. -<P> -<B>-O</B> -optimize. -Debug information is removed -and -duplicate constants are coalesced. +The output file can be a source file because +all files are loaded before the output file is written. <P> <B>-p</B> -parse sources files but do not generate any output file. -Used mainly for syntax checking. +load files but do not generate any output file. +Used mainly for syntax checking or testing precompiled chunks: +corrupted files will probably generate errors when loaded. +For a thourough integrity test, +use +<B>-t</B>. <P> -<B>-q</B> -quiet; produces no listing. -This is the default when compiling. +<B>-s</B> +strip debug information before writing the output file. +This saves some space in very large chunks, +but if errors occur when running these chunks, +then the error messages might not contain the full information they usually do. <P> <B>-t</B> -perform a thourough integrity test when undumping. +perform a thourough integrity test of precompiled chunks. Code that passes this test is completely safe, in the sense that it will not break the interpreter. However, there is no guarantee that such code does anything sensible. (None can be given, because the halting problem is unsolvable.) -<P> -<B>-U "</B><I>name"</I> -undefine symbol -<I>name</I> -for conditional compilation. +If no files are given, then +<B>luac</B> +loads +<B>luac.out</B> +and tests its contents. <P> <B>-v</B> print version information. -<P> -<B>-V</B> -verbose; -print the names of the source files as they are processed. <H1>FILES</H1> <P> <B>luac.out</B> @@ -176,19 +134,14 @@ default output file <H1>SEE ALSO</H1> <B>lua</B>(1) <BR> -<I>"Reference Manual of the Programming Language Lua"</I> -<BR> <A HREF="http://www.tecgraf.puc-rio.br/lua/">http://www.tecgraf.puc-rio.br/lua/</A> -<BR> -"Lua: an extensible extension language", -<I>Software: Practice & Experience</I> -<B>26</B> -#6 (1996) 635-652. <H1>DIAGNOSTICS</H1> Error messages should be self explanatory. <H1>AUTHORS</H1> L. H. de Figueiredo, R. Ierusalimschy and W. Celes -<I>(<A HREF="mailto:lua@tecgraf.puc-rio.br">lua@tecgraf.puc-rio.br</A>)</I> +(<A HREF="mailto:lua@tecgraf.puc-rio.br">lua@tecgraf.puc-rio.br</A>) <!-- EOF --> +</BODY> +</HTML> diff --git a/doc/luac.man b/doc/luac.man deleted file mode 100644 index 818448b8..00000000 --- a/doc/luac.man +++ /dev/null @@ -1,188 +0,0 @@ -.\" luac.man,v 1.17 1999/07/07 16:02:07 lhf Exp -.TH LUAC 1 "1999/07/07 16:02:07" -.SH NAME -luac \- Lua compiler -.SH SYNOPSIS -.B luac -[ -.I options -] [ -.I filenames -] -.SH DESCRIPTION -.B luac -is the Lua compiler. -It translates programs written in the Lua programming language -into binary files that can be loaded and executed with -.B lua_dofile -in C or with -.B dofile -in Lua. -.LP -The main advantages of pre-compiling chunks are: -faster loading, -protecting source code from user changes, -and -off-line syntax error detection. -The binary files created by -.B luac -are portable to all architectures. -.LP -Pre-compiling does not imply faster execution -because in Lua chunks are always compiled into bytecodes before being executed. -.B luac -simply allows those bytecodes to be saved in a file for later execution. -.LP -.B luac -produces a single output file containing the bytecodes -for all source files given. -By default, -the output file is named -.BR luac.out , -but you can change this with the -.B \-o -option. -.LP -You can use -.B "\-" -to indicate -.I stdin -as a source file. -.LP -.B luac -can also load and list binary files with the -.B \-u -option. -.LP -Binary files produced by differents runs of -.B luac -(even in different machines) -can be combined into one large file, -using -.BR cat (1). -The result is still a valid binary file -and can be loaded with a single call to -.B lua_dofile -or -.BR dofile . -.LP -The internal format of the binary files produced by -.B luac -may change when a new version of Lua is released. -We try to maintain compatibility even for binary files, -but sometimes it cannot be done. -So, -save the source files of all Lua programs that you precompile. -.LP -.SH OPTIONS -Options must be separate. -.TP -.B \-c -compile (this is the default). -.TP -.B \-u -undump, i.e., load and list the given binary files. -If no files are given, then luac undumps -.BR luac.out . -Listing a binary file is useful to learn Lua's virtual machine. -Listing is also useful to test the integrity of binary files: -corrupted files will probably generate errors when undumped. -To test without listing, use -.BR \-q . -For a thourough integrity test, -use -.BR \-t . -.TP -.B \-d -turn debugging on. -Individual chunks may -still control the generation of debug information with -$debug and $nodebug. -If debugging is on, then listings show the names of the local variables. -.TP -.BI \-D " name" -predefine symbol -.I name -for conditional compilation. -By default, -.B luac -does -.I not -predefine any symbols, -not even the built-in functions. -.TP -.B \-l -produce a listing of the compiled bytecode for Lua's virtual machine. -This is the default when undumping. -.TP -.B \-n -Save numbers in native format. -By default, -numbers are saved in text form, -for maximum portability. -Binary files with numbers in native format are slightly faster to load, -but are not completely portable. -.TP -.BI \-o " filename" -output to -.IR filename , -instead of the default -.BR luac.out . -The output file cannot be a source file. -.TP -.B \-O -optimize. -Debug information is removed -and -duplicate constants are coalesced. -.TP -.B \-p -parse sources files but do not generate any output file. -Used mainly for syntax checking. -.TP -.B \-q -quiet; produces no listing. -This is the default when compiling. -.TP -.B \-t -perform a thourough integrity test when undumping. -Code that passes this test is completely safe, -in the sense that it will not break the interpreter. -However, -there is no guarantee that such code does anything sensible. -(None can be given, because the halting problem is unsolvable.) -.TP -.BI \-U " name" -undefine symbol -.I name -for conditional compilation. -.TP -.B \-v -print version information. -.TP -.B \-V -verbose; -print the names of the source files as they are processed. -.SH FILES -.TP 15 -.B luac.out -default output file -.SH "SEE ALSO" -.BR lua (1) -.br -.I "Reference Manual of the Programming Language Lua" -.br -http://www.tecgraf.puc-rio.br/lua/ -.br -"Lua: an extensible extension language", -.I Software: Practice & Experience -.B 26 -#6 (1996) 635-652. -.SH DIAGNOSTICS -Error messages should be self explanatory. -.SH AUTHORS -L. H. de Figueiredo, -R. Ierusalimschy and -W. Celes -.I (lua@tecgraf.puc-rio.br) -.\" EOF diff --git a/doc/manual.html b/doc/manual.html index 8c157c2b..703bd165 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -1,10 +1,19 @@ +<HTML> <HEAD> -<TITLE>Lua 3.2 Reference Manual</TITLE> +<TITLE>Lua: reference manual 4.0</TITLE> </HEAD> + <BODY BGCOLOR="#FFFFFF"> -<h1>Lua 3.2 Reference Manual</h1> -<!-- $Id: manual.tex,v 1.33 1999/05/27 20:21:03 roberto Exp $ --> +<HR> +<H1> +<IMG SRC="logo.gif" ALT="Lua" ALIGN="bottom"> +Reference Manual of the Programming Language +<A HREF="http://www.tecgraf.puc-rio.br/lua/">Lua</A> +4.0 +</H1> + +<!-- $Id: manual.tex,v 1.45 2000/10/31 18:20:01 roberto Exp roberto $ --> <P> <P> <!-- ====================================================================== --> @@ -15,7 +24,7 @@ Lua is an extension programming language designed to support general procedural programming with data description facilities. -Lua is intended to be used as a light-weight, but powerful, +Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. <P> Lua is implemented as a library, written in C. @@ -24,21 +33,40 @@ it only works <EM>embedded</EM> in a host client, called the <EM>embedding</EM> program. This host program can invoke functions to execute a piece of code in Lua, can write and read Lua variables, -and can register C functions to be called by Lua code. -Through the use of C functions, Lua can be augmented to cope with +and can register C functions to be called by Lua code. +Through the use of C functions, Lua can be augmented to cope with a wide range of different domains, thus creating customized programming languages sharing a syntactical framework. <P> Lua is free-distribution software, -and provided as usual with no guarantees, -as stated in the copyright notice. +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: <PRE> - <A HREF="http://www.tecgraf.puc-rio.br/lua/">http://www.tecgraf.puc-rio.br/lua/</A> - <A HREF="ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz">ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz</A> + <A HREF="http://www.tecgraf.puc-rio.br/lua/">http://www.tecgraf.puc-rio.br/lua/</A> + <A HREF="ftp://ftp.tecgraf.puc-rio.br/pub/lua/">ftp://ftp.tecgraf.puc-rio.br/pub/lua/</A> </PRE> <P> +Like any other reference manual, +this document is dry in places. +For a discussion of the decisions behind the design of Lua, +see the papers below, +which are available at the web site above. +<UL> +<LI> +R. Ierusalimschy, L. H. de Figueiredo, and W. Celes. +Lua-an extensible extension language. +<EM>Software: Practice & Experience</EM> <B>26</B> #6 (1996) 635--652. +<LI> +L. H. de Figueiredo, R. Ierusalimschy, and W. Celes. +The design and implementation of a language for extending applications. +<EM>Proceedings of XXI Brazilian Seminar on Software and Hardware</EM> (1994) 273--283. +<LI> +L. H. de Figueiredo, R. Ierusalimschy, and W. Celes. +Lua: an extensible embedded language. +<EM>Dr. Dobb's Journal</EM> <B>21</B> #12 (Dec 1996) 26--33. +</UL> <P> <!-- ====================================================================== --> <HR> @@ -46,43 +74,50 @@ at the following URL's: <H1>2 - Environment and Chunks</H1> <P> All statements in Lua are executed in a <A NAME="global environment"><EM>global environment</EM></A>. -This environment, which keeps all global variables, -is initialized with a call from the embedding program to +This environment is initialized with a call from the embedding program to <CODE>lua_open</CODE> and persists until a call to <CODE>lua_close</CODE>, or the end of the embedding program. -Optionally, a user can create multiple independent global -environments (see Section <A HREF="#mangstate">5.1</A>). +If necessary, +the host programmer can create multiple independent global +environments, and freely switch between them (see Section <A HREF="#mangstate">5.1</A>). <P> The global environment can be manipulated by Lua code or by the embedding program, which can read and write global variables using API functions from the library that implements Lua. <P> -<A NAME="Global variables">Global variables</A> do not need declaration. +<A NAME="Global variables">Global variables</A> in Lua do not need to be declared. Any variable is assumed to be global unless explicitly declared local -(see Section <A HREF="#localvar">4.5.5</A>). -Before the first assignment, the value of a global variable is <B>nil</B>; -this default can be changed (see Section <A HREF="#tag-method">4.8</A>). +(see Section <A HREF="#localvar">4.4.6</A>). +Before the first assignment, the value of a global variable is <B>nil</B> +(this default can be changed; see Section <A HREF="#tag-method">4.8</A>). +A table is used to keep all global names and values +(tables are explained in Section <A HREF="#TypesSec">3</A>). <P> The unit of execution of Lua is called a <A NAME="chunk"><EM>chunk</EM></A>. -A chunk is simply a sequence of statements: -<PRE> -chunk ::= {stat} [ret] -</PRE> -Statements are described in Section <A HREF="#stats">4.5</A>. -(As usual, {<EM>a</EM>} means 0 or more <EM>a</EM>'s, -[<EM>a</EM>] means an optional <EM>a</EM> and ('<EM>a</EM>)+ means -one or more <EM>a</EM>'s.) -<P> -A chunk may be in a file or in a string inside the host program. -A chunk may optionally end with a <CODE>return</CODE> statement (see Section <A HREF="#return">4.5.3</A>). -When a chunk is executed, first all its code is pre-compiled, -then the statements are executed in sequential order. +A chunk is simply a sequence of statements, +which are executed sequentially. +Each statement can be optionally followed by a semicolon: +<PRE> + chunk ::= {stat [`<B>;</B>']} +</PRE> +Statements are described in Section <A HREF="#stats">4.4</A>. +(The notation above is the usual extended BNF, +in which +{<EM>a</EM>} means 0 or more <EM>a</EM>'s, +[<EM>a</EM>] means an optional <EM>a</EM>, and +(<EM>a</EM>)+ means one or more <EM>a</EM>'s. +The complete syntax of Lua is given in <A HREF="BNF">BNF</A>). +<P> +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, +by simulating the virtual machine. All modifications a chunk effects on the global environment persist -after the chunk end. +after the chunk ends. <P> -Chunks may also be pre-compiled into binary form; +Chunks may also be pre-compiled into binary form and stored in files; see program <A NAME="luac"><TT><A HREF="luac.html">luac</A></TT></A> for details. Text files with chunks and their binary pre-compiled forms are interchangeable. @@ -95,11 +130,12 @@ Lua automatically detects the file type and acts accordingly. <A NAME="3."></A> <H1>3 - Types and Tags</H1> <P> -Lua is a dynamically typed language. -Variables do not have types; only values do. +Lua is a <EM>dynamically typed language</EM>. +This means that +variables do not have types; only values do. Therefore, there are no type definitions in the language. All values carry their own type. -Besides a type, all values also have a <A NAME="tag">tag</A>. +Besides a type, all values also have a <A NAME="tag"><EM>tag</EM></A>. <P> There are six <A NAME="basic types">basic types</A> in Lua: <A NAME="nil"><EM>nil</EM></A>, <A NAME="number"><EM>number</EM></A>, <A NAME="string"><EM>string</EM></A>, <A NAME="function"><EM>function</EM></A>, <A NAME="userdata"><EM>userdata</EM></A>, and <A NAME="table"><EM>table</EM></A>. @@ -107,26 +143,30 @@ There are six <A NAME="basic types">basic types</A> in Lua: <A NAME="nil"><EM>ni whose main property is to be different from any other value. <EM>Number</EM> represents real (double-precision floating-point) numbers, while <EM>string</EM> has the usual meaning. -Lua is <A NAME="eight-bit clean">eight-bit clean</A>, +<A NAME="eight-bit clean"></A> +Lua is 8-bit clean, and so strings may contain any 8-bit character, -<EM>including</EM> embedded zeros (<CODE>'\0'</CODE>). -The function <CODE>type</CODE> returns a string describing the type +including embedded zeros (<CODE>'\0'</CODE>) (see Section <A HREF="#lexical">4.1</A>). +The <CODE>type</CODE> function returns a string describing the type of a given value (see Section <A HREF="#pdf-type">6.1</A>). <P> -Functions are considered first-class values in Lua. +Functions are considered <EM>first-class values</EM> in Lua. This means that functions can be stored in variables, passed as arguments to other functions, and returned as results. Lua can call (and manipulate) functions written in Lua and functions written in C. -They can be distinguished by their tags: +The two kinds of functions can be distinguished by their tags: all Lua functions have the same tag, -and all C functions have the same tag, +and all C functions have the same tag, which is different from the tag of Lua functions. +The <CODE>tag</CODE> function returns the tag +of a given value (see Section <A HREF="#pdf-tag">6.1</A>). <P> The type <EM>userdata</EM> is provided to allow -arbitrary <A NAME="C pointers">C pointers</A> to be stored in Lua variables. -It corresponds to a <CODE>void*</CODE> and has no pre-defined operations in Lua, -besides assignment and equality test. +arbitrary <A NAME="C pointers">C pointers</A> to be stored in Lua variables. +This type corresponds to a <CODE>void*</CODE> +and has no pre-defined operations in Lua, +except assignment and equality test. However, by using <EM>tag methods</EM>, the programmer can define operations for <EM>userdata</EM> values (see Section <A HREF="#tag-method">4.8</A>). @@ -135,100 +175,109 @@ The type <EM>table</EM> implements <A NAME="associative arrays">associative arra that is, <A NAME="arrays">arrays</A> that can be indexed not only with numbers, but with any value (except <B>nil</B>). Therefore, this type may be used not only to represent ordinary arrays, -but also symbol tables, sets, records, etc. +but also symbol tables, sets, records, graphs, trees, etc. Tables are the main data structuring mechanism in Lua. To represent <A NAME="records">records</A>, Lua uses the field name as an index. The language supports this representation by providing <CODE>a.name</CODE> as syntactic sugar for <CODE>a["name"]</CODE>. -Tables may also carry methods. +Tables may also carry <EM>methods</EM>: Because functions are first class values, table fields may contain functions. The form <CODE>t:f(x)</CODE> is syntactic sugar for <CODE>t.f(t,x)</CODE>, which calls the method <CODE>f</CODE> from the table <CODE>t</CODE> passing -itself as the first parameter (see Section <A HREF="#func-def">4.6.9</A>). +the table itself as the first parameter (see Section <A HREF="#func-def">4.5.9</A>). <P> Note that tables are <EM>objects</EM>, and not values. -Variables cannot contain tables, only <EM>references</EM> to them. +Variables do not contain tables, only <EM>references</EM> 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 Section <A HREF="#tableconstructor">4.6.7</A>). +(see Section <A HREF="#tableconstructor">4.5.7</A>). <P> -Tags are mainly used to select tag methods when +Each of the types <EM>nil</EM>, <EM>number</EM>, and <EM>string</EM> has a different tag. +All values of each of these types have the same pre-defined tag. +As explained above, +values of type <EM>function</EM> can have two different tags, +depending on whether they are Lua functions or C functions. +Finally, +values of type <EM>userdata</EM> and <EM>table</EM> can have variable tags, +assigned by the programmer (see Section <A HREF="#tag-method">4.8</A>). +The <CODE>tag</CODE> function returns the tag of a given value. +User tags are created with the function <CODE>newtag</CODE>. +The <CODE>settag</CODE> function +is used to change the tag of a table (see Section <A HREF="#pdf-newtag">6.1</A>). +The tag of userdata values can only be set from C (see Section <A HREF="#C-tags">5.7</A>). +Tags are mainly used to select <EM>tag methods</EM> when some events occur. Tag methods are the main mechanism for extending the semantics of Lua (see Section <A HREF="#tag-method">4.8</A>). -Each of the types <EM>nil</EM>, <EM>number</EM> and <EM>string</EM> has a different tag. -All values of each of these types have this same pre-defined tag. -Values of type <EM>function</EM> can have two different tags, -depending on whether they are Lua functions or C functions. -Finally, -values of type <EM>userdata</EM> and <EM>table</EM> can have -as many different tags as needed (see Section <A HREF="#tag-method">4.8</A>). -Tags are created with the function <CODE>newtag</CODE>, -and the function <CODE>tag</CODE> returns the tag of a given value. -To change the tag of a given table, -there is the function <CODE>settag</CODE> (see Section <A HREF="#pdf-newtag">6.1</A>). -<P> <P> <!-- ====================================================================== --> <HR> <A NAME="4."></A> <H1>4 - The Language</H1> <P> -This section describes the lexis, the syntax and the semantics of Lua. +This section describes the lexis, the syntax, and the semantics of Lua. <P> <P> <A NAME="lexical"></A> <A NAME="4.1"></A> <H2>4.1 - Lexical Conventions</H2> <P> -<A NAME="Identifiers">Identifiers</A> in Lua can be any string of letters, +<A NAME="Identifiers"><EM>Identifiers</EM></A> in Lua can be any string of letters, digits, and underscores, not beginning with a digit. -The definition of letter depends on the current locale: +This coincides with the definition of identifiers in most languages, +except that +the definition of letter depends on the current locale: Any character considered alphabetic by the current locale can be used in an identifier. -The following words are reserved, and cannot be used as identifiers: +The following words are <EM>reserved</EM>, and cannot be used as identifiers: <A NAME="reserved words"></A> <PRE> - and do else elseif - end 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 </PRE> +<P> Lua is a case-sensitive language: -<TT>and</TT> is a reserved word, but <TT>And</TT> and <TT>\'and</TT> -(if the locale permits) are two other different identifiers. +<TT>and</TT> is a reserved word, but <TT>And</TT> and <TT>ánd</TT> +(if the locale permits) are two different, valid identifiers. As a convention, identifiers starting with underscore followed by -uppercase letters are reserved for internal variables. +uppercase letters (such as <CODE>_INPUT</CODE>) +are reserved for internal variables. <P> The following strings denote other <A NAME="tokens">tokens</A>: <PRE> - ~= <= >= < > == = + - * / - ( ) { } [ ] ; , . .. ... + ~= <= >= < > == = + - * / + ( ) { } [ ] ; , . .. ... </PRE> <P> -<A NAME="Literal strings">Literal strings</A> can be delimited by matching single or double quotes, +<A NAME="Literal strings"><EM>Literal strings</EM></A> +can be delimited by matching single or double quotes, and can contain the C-like escape sequences -<CODE>'\a'</CODE> (bell), -<CODE>'\b'</CODE> (backspace), -<CODE>'\f'</CODE> (form feed), -<CODE>'\n'</CODE> (new line), -<CODE>'\r'</CODE> (carriage return), -<CODE>'\t'</CODE> (horizontal tab), -<CODE>'\v'</CODE> (vertical tab), -<CODE>'\\'</CODE>, (backslash), -<CODE>'\"'</CODE>, (double quote), -and <CODE>'\''</CODE> (single quote). +`<CODE>\a</CODE>' (bell), +`<CODE>\b</CODE>' (backspace), +`<CODE>\f</CODE>' (form feed), +`<CODE>\n</CODE>' (newline), +`<CODE>\r</CODE>' (carriage return), +`<CODE>\t</CODE>' (horizontal tab), +`<CODE>\v</CODE>' (vertical tab), +`<CODE>\\</CODE>' (backslash), +`<CODE>\"</CODE>' (double quote), +`<CODE>\'</CODE>' (single quote), +and `<CODE>\</CODE><EM>newline</EM>' (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 <CODE>'\ddd'</CODE>, -where <CODE>ddd</CODE> is a sequence of up to three <EM>decimal</EM> digits. -Strings in Lua may contain any 8-bit value, including embedded 0. +through the escape sequence `<CODE>\</CODE><EM>ddd</EM>', +where <EM>ddd</EM> is a sequence of up to three <EM>decimal</EM> digits. +Strings in Lua may contain any 8-bit value, including embedded zeros, +which can be specified as `<CODE>\000</CODE>'. <P> -Literal strings can also be delimited by matching <CODE>[[ ... ]]</CODE>. +Literal strings can also be delimited by matching <CODE>[[</CODE> ... <CODE>]]</CODE>. Literals in this bracketed form may run for several lines, -may contain nested <CODE>[[ ... ]]</CODE> pairs, +may contain nested <CODE>[[</CODE> ... <CODE>]]</CODE> pairs, and do not interpret escape sequences. This form is specially convenient for writing strings that contain program pieces or @@ -236,268 +285,363 @@ other quoted strings. As an example, in a system using ASCII, the following three literals are equivalent: <PRE> -1) "alo\n123\"" -2) '\97lo\10\04923"' -3) [[alo - 123"]] + 1) "alo\n123\"" + 2) '\97lo\10\04923"' + 3) [[alo + 123"]] </PRE> <P> -<P> -<A NAME="Comments">Comments</A> start anywhere outside a string with a +<A NAME="Comments"><EM>Comments</EM></A> start anywhere outside a string with a double hyphen (<CODE>--</CODE>) and run until the end of the line. Moreover, the first line of a chunk is skipped if it starts with <CODE>#</CODE>. This facility allows the use of Lua as a script interpreter in Unix systems (see Section <A HREF="#lua-sa">8</A>). <P> -<A NAME="Numerical constants">Numerical constants</A> may be written with an optional decimal part, +<A NAME="Numerical constants"><EM>Numerical constants</EM></A> may be written with an optional decimal part and an optional decimal exponent. Examples of valid numerical constants are <PRE> 3 3.0 3.1416 314.16e-2 0.31416E1 </PRE> <P> -<A NAME="pre-processor"></A> -<A NAME="4.2"></A> -<H2>4.2 - The Pre-processor</H2> -<P> -All lines that start with a <CODE>$</CODE> sign are handled by a pre-processor. -The <CODE>$</CODE> sign must be immediately -followed by one of the following directives: -<DL> -<DT><B><TT>debug</TT></B><DD> - turn on debugging facilities (see Section <A HREF="#pragma">4.9</A>). -<DT><B><TT>nodebug</TT></B><DD> - turn off debugging facilities (see Section <A HREF="#pragma">4.9</A>). -<DT><B><TT>if <EM>cond</TT></EM></B><DD> - starts a conditional part. -If <EM>cond</EM> is false, then this part is skipped by the lexical analyzer. -<DT><B><TT>ifnot <EM>cond</TT></EM></B><DD> - starts a conditional part. -If <EM>cond</EM> is true, then this part is skipped by the lexical analyzer. -<DT><B><TT>end</TT></B><DD> - ends a conditional part. -<DT><B><TT>else</TT></B><DD> - starts an ``else'' conditional part, -flipping the ``skip'' status. -<DT><B><TT>endinput</TT></B><DD> - ends the lexical parse of the file. -</DL> -<P> -Directives may be freely nested. -Particularly, a <CODE>$endinput</CODE> may occur inside a <CODE>$if</CODE>; -in that case, even the matching <CODE>$end</CODE> is not parsed. -<P> -A <EM>cond</EM> part may be -<DL> -<DT><B><TT>nil</TT></B><DD> - always false. -<DT><B><TT>1</TT></B><DD> - always true. -<DT><B><EM>name</EM></B><DD> - true if the value of the -global variable <EM>name</EM> is different from <B>nil</B>. -Note that <EM>name</EM> is evaluated <EM>before</EM> the chunk starts its execution. -Therefore, actions in a chunk do not affect its own conditional directives. -</DL> -<P> <A NAME="coercion"></A> -<A NAME="4.3"></A> -<H2>4.3 - Coercion</H2> +<A NAME="4.2"></A> +<H2>4.2 - Coercion</H2> <P> Lua provides some automatic conversions between values at run time. Any arithmetic operation applied to a string tries to convert that string to a number, following the usual rules. Conversely, whenever a number is used when a string is expected, that number is converted to a string, in a reasonable format. -For complete control on how numbers are converted to strings, +The format is chosen so that +a conversion from number to string then back to number +reproduces the original number <EM>exactly</EM>. +Thus, +the conversion does not necessarily produces nice-looking text for some numbers. +For complete control of how numbers are converted to strings, use the <CODE>format</CODE> function (see Section <A HREF="#format">6.2</A>). <P> <P> <A NAME="adjust"></A> -<A NAME="4.4"></A> -<H2>4.4 - Adjustment</H2> +<A NAME="4.3"></A> +<H2>4.3 - Adjustment</H2> <P> Functions in Lua can return many values. Because there are no type declarations, when a function is called -the system does not know how many values a function will return, +the system does not know how many values the function will return, or how many parameters it needs. Therefore, sometimes, a list of values must be <EM>adjusted</EM>, at run time, to a given length. If there are more values than are needed, then the excess values are thrown away. -If there are more needs than values, +If there are less values than are needed, then the list is extended with as many <B>nil</B>'s as needed. -Adjustment occurs in multiple assignment (see Section <A HREF="#assignment">4.5.2</A>) -and function calls (see Section <A HREF="#functioncall">4.6.8</A>). +This adjustment occurs in multiple assignments (see Section <A HREF="#assignment">4.4.2</A>) +and in function calls (see Section <A HREF="#functioncall">4.5.8</A>). <P> <P> <A NAME="stats"></A> -<A NAME="4.5"></A> -<H2>4.5 - Statements</H2> +<A NAME="4.4"></A> +<H2>4.4 - Statements</H2> <P> Lua supports an almost conventional set of <A NAME="statements">statements</A>, similar to those in Pascal or C. The conventional commands include -assignment, control structures and procedure calls. +assignment, control structures, and procedure calls. Non-conventional commands include table constructors -(see Section <A HREF="#tableconstructor">4.6.7</A>), -and local variable declarations (see Section <A HREF="#localvar">4.5.5</A>). +(see Section <A HREF="#tableconstructor">4.5.7</A>) +and local variable declarations (see Section <A HREF="#localvar">4.4.6</A>). <P> -<H3>4.5.1 - Blocks</H3> -A <A NAME="block">block</A> is a list of statements, which are executed sequentially. -A statement may be optionally followed by a semicolon: +<H3>4.4.1 - Blocks</H3> +A <A NAME="block">block</A> is a list of statements; +syntactically, a block is equal to a chunk: <PRE> -block ::= {stat sc} [ret] -sc ::= ['<B>;</B>'] + block ::= chunk </PRE> -For syntactic reasons, a <A NAME="return"><TT>return</TT></A> statement can only be written -as the last statement of a block. -This restriction also avoids some ``statement not reached'' conditions. <P> A block may be explicitly delimited: <PRE> -stat ::= <B>do</B> block <B>end</B> + stat ::= <B>do</B> block <B>end</B> </PRE> -This is useful to control the scope of local variables (see Section <A HREF="#localvar">4.5.5</A>). +Explicit blocks are useful +to control the scope of local variables (see Section <A HREF="#localvar">4.4.6</A>). +Explicit blocks are also sometimes used to +add a <B>return</B> or <B>break</B> statement in the middle +of another block (see Section <A HREF="#control">4.4.3</A>). <P> <A NAME="assignment"></A> -<H3>4.5.2 - <A NAME="Assignment</H3>">Assignment</H3></A> -The language allows <A NAME="multiple assignment">multiple assignment</A>. +<H3>4.4.2 - <A NAME="Assignment</H3>">Assignment</H3></A> +Lua allows <A NAME="multiple assignment">multiple assignment</A>. Therefore, the syntax for assignment -defines a list of variables on the left side, +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: <PRE> -stat ::= varlist1 '<B>=</B>' explist1 -varlist1 ::= var {'<B>,</B>' var} + stat ::= varlist1 `<B>=</B>' explist1 + varlist1 ::= var {`<B>,</B>' var} </PRE> This statement first evaluates all values on the right side and eventual indices on the left side, and then makes the assignments. -Therefore, it can be used to exchange two values, as in +So, the code +<PRE> + i = 3 + i, a[i] = 4, 20 +</PRE> +sets <CODE>a[3]</CODE> to 20, but does not affect <CODE>a[4]</CODE> +because the <CODE>i</CODE> in <CODE>a[i]</CODE> is evaluated +before it is assigned <CODE>4</CODE>. +<P> +Multiple assignment can be used to exchange two values, as in <PRE> - x, y = y, x + x, y = y, x </PRE> -The two lists may have different lengths. -Before the assignment, the list of values is <EM>adjusted</EM> to -the length of the list of variables (see Section <A HREF="#adjust">4.4</A>). +<P> +The two lists in a multiple assignment may have different lengths. +Before the assignment, the list of values is adjusted to +the length of the list of variables (see Section <A HREF="#adjust">4.3</A>). <P> A single name can denote a global variable, a local variable, or a formal parameter: <PRE> -var ::= name + var ::= name </PRE> +<P> Square brackets are used to index a table: <PRE> -var ::= simpleexp '<B>[</B>' exp1 '<B>]</B>' + var ::= varorfunc `<B>[</B>' exp1 `<B>]</B>' + varorfunc ::= var | functioncall </PRE> -The <EM>simpleexp</EM> should result in a table value, -from where the field indexed by the expression +The <EM>varorfunc</EM> should result in a table value, +from where the field indexed by the expression <EM>exp1</EM> value gets the assigned value. <P> The syntax <CODE>var.NAME</CODE> is just syntactic sugar for <CODE>var["NAME"]</CODE>: <PRE> -var ::= simpleexp '<B>.</B>' name + var ::= varorfunc `<B>.</B>' name </PRE> <P> The meaning of assignments and evaluations of global variables and indexed variables can be changed by tag methods (see Section <A HREF="#tag-method">4.8</A>). Actually, an assignment <CODE>x = val</CODE>, where <CODE>x</CODE> is a global variable, -is equivalent to a call <CODE>setglobal('x', val)</CODE>; +is equivalent to a call <CODE>setglobal("x", val)</CODE> and an assignment <CODE>t[i] = val</CODE> is equivalent to -<CODE>settable_event(t, i, val)</CODE>. -See Section <A HREF="#tag-method">4.8</A> for a complete description of these functions. -(Function <CODE>setglobal</CODE> is pre-defined in Lua. -Function <TT>settable_event</TT> is used only for explanatory purposes.) -<P> -<H3>4.5.3 - Control Structures</H3> -The <A NAME="condition expression">condition expression</A> of a control structure may return any value. +<CODE>settable_event(t,i,val)</CODE>. +See Section <A HREF="#tag-method">4.8</A> for a complete description of these functions +(<CODE>setglobal</CODE> is in the basic library; +<TT>settable_event</TT> is used for explanatory purposes only). +<P> +<A NAME="control"></A> +<H3>4.4.3 - Control Structures</H3> +The control structures +<B>if</B>, <B>while</B>, and <B>repeat</B> have the usual meaning and +familiar syntax +<A NAME="while-do statement"></A> +<A NAME="repeat-until statement"></A> +<A NAME="if-then-else statement"></A> +<PRE> + stat ::= <B>while</B> exp1 <B>do</B> block <B>end</B> + stat ::= <B>repeat</B> block <B>until</B> exp1 + stat ::= <B>if</B> exp1 <B>then</B> block {<B>elseif</B> exp1 <B>then</B> block} [<B>else</B> block] <B>end</B> +</PRE> +The <A NAME="condition expression">condition expression</A> <EM>exp1</EM> of a control structure may return any value. All values different from <B>nil</B> are considered true; only <B>nil</B> is considered false. -<TT>if</TT>'s, <TT>while</TT>'s and <TT>repeat</TT>'s have the usual meaning. -<P> -<A NAME="while-do"></A><A NAME="repeat-until"></A><A NAME="if-then-else"></A> -<PRE> -stat ::= <B>while</B> exp1 <B>do</B> block <B>end</B> <BR> | <B>repeat</B> block <B>until</B> exp1 <BR> | <B>if</B> exp1 <B>then</B> block {<B>elseif</B> exp1 <B>then</B> block} [<B>else</B> block] <B>end</B> -</PRE> <P> -A <TT>return</TT> is used to return values from a function or from a chunk. +The <B>return</B> statement is used to return values +from a function or from a chunk. <A NAME="return"></A> -Because they may return more than one value, -the syntax for a <A NAME="return statement">return statement</A> is -<PRE> -ret ::= <B>return</B> [explist1] [sc] -</PRE> +<A NAME="return statement"></A> +Because functions or chunks may return more than one value, +the syntax for the <B>return</B> statement is +<PRE> + stat ::= <B>return</B> [explist1] +</PRE> +<P> +The <B>break</B> statement can be used to terminate the execution of a loop, +skipping to the next statement after the loop: +<A NAME="break statement"></A> +<PRE> + stat ::= <B>break</B> +</PRE> +A <B>break</B> ends the innermost enclosing loop +(<B>while</B>, <B>repeat</B>, or <B>for</B>). +<P> +For syntactic reasons, <B>return</B> and <B>break</B> +statements can only be written as the <EM>last</EM> statements of a block. +If it is really necessary to <B>return</B> or <B>break</B> in the +middle of a block, +an explicit inner block can used, +as in the idiom `<CODE>do return end</CODE>', +because now <B>return</B> is last statement in the inner block. +<P> +<A NAME="for"></A> +<H3>4.4.4 - For Statement</H3> <A NAME="for statement"></A> +<P> +The <B>for</B> statement has two forms, +one for numbers and one for tables. +The numerical <B>for</B> loop has the following syntax: +<PRE> + stat ::= <B>for</B> name `<B>=</B>' exp1 `<B>,</B>' exp1 [`<B>,</B>' exp1] <B>do</B> block <B>end</B> +</PRE> +A <B>for</B> statement like +<PRE> + for var = e1 ,e2, e3 do block end +</PRE> +is equivalent to the code: +<PRE> + 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 +</PRE> +Note the following: +<UL><LI>sep=0pt +<LI><CODE>_limit</CODE> and <CODE>_step</CODE> are invisible variables. +The names are here for explanatory purposes only. +<LI>The behavior is <EM>undefined</EM> if you assign to <CODE>var</CODE> inside +the block. +<LI>If the third expression (the step) is absent, then a step of 1 is used. +<LI>Both the limit and the step are evaluated only once, +before the loop starts. +<LI>The variable <CODE>var</CODE> is local to the statement; +you cannot use its value after the <B>for</B> ends. +<LI>You can use <B>break</B> to exit a <B>for</B>. +If you need the value of the index, +assign it to another variable before breaking. +</UL> +<P> +The table <B>for</B> statement traverses all pairs +(index,value) of a given table. +It has the following syntax: +<PRE> + stat ::= <B>for</B> name `<B>,</B>' name <B>in</B> exp1 <B>do</B> block <B>end</B> +</PRE> +A <B>for</B> statement like +<PRE> + for index, value in exp do block end +</PRE> +is equivalent to the code: +<PRE> + do + local _t = exp + local index, value = next(t, nil) + while index do + block + index, value = next(t, index) + end + end +</PRE> +Note the following: +<UL><LI>sep=0pt +<LI><CODE>_t</CODE> is an invisible variable. +The name is here for explanatory purposes only. +<LI>The behavior is <EM>undefined</EM> if you assign to <CODE>index</CODE> inside +the block. +<LI>The behavior is <EM>undefined</EM> if you change +the table <CODE>_t</CODE> during the traversal. +<LI>The variables <CODE>index</CODE> and <CODE>value</CODE> are local to the statement; +you cannot use their values after the <B>for</B> ends. +<LI>You can use <B>break</B> to exit a <B>for</B>. +If you need the value of <CODE>index</CODE> or <CODE>value</CODE>, +assign them to other variables before breaking. +<LI>The order that table elements are traversed is undefined, +<EM>even for numerical indices</EM>. +If you want to traverse indices in numerical order, +use a numerical <B>for</B>. +</UL> +<P> <P> <A NAME="funcstat"></A> -<H3>4.5.4 - Function Calls as Statements</H3> +<H3>4.4.5 - Function Calls as Statements</H3> Because of possible side-effects, function calls can be executed as statements: <PRE> -stat ::= functioncall + stat ::= functioncall </PRE> In this case, all returned values are thrown away. -Function calls are explained in Section <A HREF="#functioncall">4.6.8</A>. +Function calls are explained in Section <A HREF="#functioncall">4.5.8</A>. <P> <A NAME="localvar"></A> -<H3>4.5.5 - Local Declarations</H3> +<H3>4.4.6 - Local Declarations</H3> <A NAME="Local variables">Local variables</A> may be declared anywhere inside a block. -Their scope begins after the declaration and lasts until the -end of the block. The declaration may include an initial assignment: <PRE> -stat ::= <B>local</B> declist [init] -declist ::= name {'<B>,</B>' name} -init ::= '<B>=</B>' explist1 + stat ::= <B>local</B> declist [init] + declist ::= name {`<B>,</B>' name} + init ::= `<B>=</B>' explist1 </PRE> If present, an initial assignment has the same semantics of a multiple assignment. Otherwise, all variables are initialized with <B>nil</B>. <P> +A chunk is also a block, +and so local variables can be declared outside any explicit block. <P> -<A NAME="4.6"></A> -<H2>4.6 - Expressions</H2> +The scope of local variables begins <EM>after</EM> +the declaration and lasts until the end of the block. +Thus, the code +<CODE>local print=print</CODE> +creates a local variable called <CODE>print</CODE> whose +initial value is that of the <EM>global</EM> variable of the same name. <P> -<H3>4.6.1 - <A NAME="Basic Expressions</H3>">Basic Expressions</H3></A> -Basic expressions are -<PRE> -exp ::= '<B>(</B>' exp '<B>)</B>' -exp ::= <B>nil</B> -exp ::= '<B>number</B>' -exp ::= '<B>literal</B>' -exp ::= function -exp ::= simpleexp -</PRE> +<P> +<A NAME="4.5"></A> +<H2>4.5 - Expressions</H2> +<P> +<H3>4.5.1 - <A NAME="Basic Expressions</H3>">Basic Expressions</H3></A> +The basic expressions in Lua are <PRE> -simpleexp ::= var -simpleexp ::= upvalue -simpleexp ::= functioncall + exp ::= `<B>(</B>' exp `<B>)</B>' + exp ::= <B>nil</B> + exp ::= number + exp ::= literal + exp ::= var + exp ::= upvalue + exp ::= function + exp ::= functioncall + exp ::= tableconstructor </PRE> <P> Numbers (numerical constants) and -string literals are explained in Section <A HREF="#lexical">4.1</A>; -variables are explained in Section <A HREF="#assignment">4.5.2</A>; -upvalues are explained in Section <A HREF="#upvalue">4.7</A>; -function definitions (<EM>function</EM>) are explained in Section <A HREF="#func-def">4.6.9</A>; -function calls are explained in Section <A HREF="#functioncall">4.6.8</A>. +literal strings are explained in Section <A HREF="#lexical">4.1</A>; +variables are explained in Section <A HREF="#assignment">4.4.2</A>; +upvalues are explained in Section <A HREF="#upvalue">4.6</A>; +function definitions are explained in Section <A HREF="#func-def">4.5.9</A>; +function calls are explained in Section <A HREF="#functioncall">4.5.8</A>. +Table constructors are explained in Section <A HREF="#tableconstructor">4.5.7</A>. <P> An access to a global variable <CODE>x</CODE> is equivalent to a -call <CODE>getglobal('x')</CODE>; +call <CODE>getglobal("x")</CODE> and an access to an indexed variable <CODE>t[i]</CODE> is equivalent to -a call <CODE>gettable_event(t, i)</CODE>. -See Section <A HREF="#tag-method">4.8</A> for a description of these functions. -(Function <CODE>getglobal</CODE> is pre-defined in Lua. -Function <TT>gettable_event</TT> is used only for explanatory purposes.) +a call <CODE>gettable_event(t,i)</CODE>. +See Section <A HREF="#tag-method">4.8</A> for a description of these functions +(<CODE>getglobal</CODE> is in the basic library; +<TT>gettable_event</TT> is used for explanatory purposes only). <P> The non-terminal <EM>exp1</EM> is used to indicate that the values returned by an expression must be adjusted to one single value: <PRE> -exp1 ::= exp + exp1 ::= exp </PRE> <P> -<H3>4.6.2 - Arithmetic Operators</H3> +<H3>4.5.2 - Arithmetic Operators</H3> Lua supports the usual <A NAME="arithmetic operators">arithmetic operators</A>: the binary <CODE>+</CODE> (addition), <CODE>-</CODE> (subtraction), <CODE>*</CODE> (multiplication), -<CODE>/</CODE> (division) and <CODE>^</CODE> (exponentiation), +<CODE>/</CODE> (division), and <CODE>^</CODE> (exponentiation); and unary <CODE>-</CODE> (negation). If the operands are numbers, or strings that can be converted to -numbers (according to the rules given in Section <A HREF="#coercion">4.3</A>), +numbers (according to the rules given in Section <A HREF="#coercion">4.2</A>), then all operations except exponentiation have the usual meaning. Otherwise, an appropriate tag method is called (see Section <A HREF="#tag-method">4.8</A>). An exponentiation always calls a tag method. @@ -505,196 +649,216 @@ The standard mathematical library redefines this method for numbers, giving the expected meaning to <A NAME="exponentiation">exponentiation</A> (see Section <A HREF="#mathlib">6.3</A>). <P> -<H3>4.6.3 - Relational Operators</H3> -Lua provides the following <A NAME="relational operators">relational operators</A>: +<H3>4.5.3 - Relational Operators</H3> +The <A NAME="relational operators">relational operators</A> in Lua are <PRE> - < > <= >= ~= == + == ~= < > <= >= </PRE> -All these return <B>nil</B> as false and a value different from <B>nil</B> as true. +These operators return <B>nil</B> as false and a value different from <B>nil</B> as true. <P> -Equality first compares the tags of its operands. +Equality (<CODE>==</CODE>) first compares the tags of its operands. If they are different, then the result is <B>nil</B>. Otherwise, their values are compared. Numbers and strings are compared in the usual way. -Tables, userdata and functions are compared by reference, -that is, two tables are considered equal only if they are the same table. +Tables, userdata, and functions are compared by reference, +that is, two tables are considered equal only if they are the <EM>same</EM> table. The operator <CODE>~=</CODE> is exactly the negation of equality (<CODE>==</CODE>). -Note that the conversion rules of Section <A HREF="#coercion">4.3</A> +<P> +The conversion rules of Section <A HREF="#coercion">4.2</A> <EM>do not</EM> apply to equality comparisons. -Thus, <CODE>"0"==0</CODE> evaluates to false, +Thus, <CODE>"0"==0</CODE> evaluates to <EM>false</EM>, and <CODE>t[0]</CODE> and <CODE>t["0"]</CODE> denote different entries in a table. <P> -The other operators work as follows. +The order operators work as follows. If both arguments are numbers, then they are compared as such. Otherwise, if both arguments are strings, then their values are compared using lexicographical order. -Otherwise, the ``order'' tag method is called (see Section <A HREF="#tag-method">4.8</A>). +Otherwise, the ``lt'' tag method is called (see Section <A HREF="#tag-method">4.8</A>). <P> -<H3>4.6.4 - Logical Operators</H3> -The <A NAME="logical operators">logical operators</A> are +<H3>4.5.4 - Logical Operators</H3> +The <A NAME="logical operators">logical operators</A> in Lua are <A NAME="and"></A><A NAME="or"></A><A NAME="not"></A> <PRE> - and or not + and or not </PRE> -Like control structures, all logical operators +Like the control structures, all logical operators consider <B>nil</B> as false and anything else as true. -The operator <CODE>and</CODE> returns <B>nil</B> if its first argument is <B>nil</B>; +<P> +The conjunction operator <CODE>and</CODE> returns <B>nil</B> if its first argument is <B>nil</B>; otherwise, it returns its second argument. -The operator <CODE>or</CODE> returns its first argument +The disjunction operator <CODE>or</CODE> returns its first argument if it is different from <B>nil</B>; otherwise, it returns its second argument. Both <CODE>and</CODE> and <CODE>or</CODE> use <A NAME="short-cut evaluation">short-cut evaluation</A>, that is, -the second operand is evaluated only when necessary. +the second operand is evaluated only if necessary. <P> -A useful Lua idiom is <CODE>x = x or v</CODE>, +There are two useful Lua idioms that use logical operators. +The first idiom is +<PRE> + x = x or v +</PRE> which is equivalent to <PRE> - if x == nil then x = v end + if x == nil then x = v end +</PRE> +This idiom sets <CODE>x</CODE> to a default value <CODE>v</CODE> when <CODE>x</CODE> is not set. +<P> +The second idiom is +<PRE> + x = a and b or c </PRE> -i.e., it sets <CODE>x</CODE> to a default value <CODE>v</CODE> when -<CODE>x</CODE> is not set. +which should be read as <CODE>x = (a and b) or c</CODE>. +This idiom is equivalent to +<PRE> + if a then x = b else x = c end +</PRE> +provided that <CODE>b</CODE> is not <B>nil</B>. <P> -<H3>4.6.5 - Concatenation</H3> +<A NAME="concat"></A> +<H3>4.5.5 - Concatenation</H3> The string <A NAME="concatenation">concatenation</A> operator in Lua is -denoted by ``<A NAME=".."><TT>..</TT></A>''. -If both operands are strings or numbers, they are converted to -strings according to the rules in Section <A HREF="#coercion">4.3</A>. +denoted by two dots (`<A NAME=".."><TT>..</TT></A>'). +If both operands are strings or numbers, then they are converted to +strings according to the rules in Section <A HREF="#coercion">4.2</A>. Otherwise, the ``concat'' tag method is called (see Section <A HREF="#tag-method">4.8</A>). <P> -<H3>4.6.6 - Precedence</H3> -<A NAME="Operator precedence">Operator precedence</A> follows the table below, +<H3>4.5.6 - Precedence</H3> +<A NAME="Operator precedence">Operator precedence</A> in Lua follows the table below, from the lower to the higher priority: <PRE> - and or - < > <= >= ~= == - .. - + - - * / - not - (unary) - ^ + and or + < > <= >= ~= == + .. + + - + * / + not - (unary) + ^ </PRE> All binary operators are left associative, except for <CODE>^</CODE> (exponentiation), which is right associative. +The pre-compiler may rearrange the order of evaluation of +associative operators (such as <CODE>..</CODE> or <CODE>+</CODE>), +as long as these optimizations do not change normal results. +However, these optimizations may change some results +if you define non-associative +tag methods for these operators. <P> <A NAME="tableconstructor"></A> -<H3>4.6.7 - Table Constructors</H3> +<H3>4.5.7 - Table Constructors</H3> Table <A NAME="constructors">constructors</A> are expressions that create tables; every time a constructor is evaluated, a new table is created. Constructors can be used to create empty tables, -or to create a table and initialize some fields. -<P> +or to create a table and initialize some of its fields. The general syntax for constructors is <PRE> -tableconstructor ::= '<B>{</B>' fieldlist '<B>}</B>' -fieldlist ::= lfieldlist | ffieldlist | lfieldlist '<B>;</B>' ffieldlist | ffieldlist '<B>;</B>' lfieldlist -lfieldlist ::= [lfieldlist1] -ffieldlist ::= [ffieldlist1] + tableconstructor ::= `<B>{</B>' fieldlist `<B>}</B>' + fieldlist ::= lfieldlist | ffieldlist | lfieldlist `<B>;</B>' ffieldlist | ffieldlist `<B>;</B>' lfieldlist + lfieldlist ::= [lfieldlist1] + ffieldlist ::= [ffieldlist1] </PRE> <P> The form <EM>lfieldlist1</EM> is used to initialize lists: <PRE> -lfieldlist1 ::= exp {'<B>,</B>' exp} ['<B>,</B>'] + lfieldlist1 ::= exp {`<B>,</B>' exp} [`<B>,</B>'] </PRE> The expressions in the list are assigned to consecutive numerical indices, -starting with 1. +starting with 1. For example, <PRE> - a = {"v1", "v2", 34} + a = {"v1", "v2", 34} </PRE> is equivalent to <PRE> - 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 </PRE> <P> The form <EM>ffieldlist1</EM> initializes other fields in a table: <PRE> -ffieldlist1 ::= ffield {'<B>,</B>' ffield} ['<B>,</B>'] -ffield ::= '<B>[</B>' exp '<B>]</B>' '<B>=</B>' exp | name '<B>=</B>' exp + ffieldlist1 ::= ffield {`<B>,</B>' ffield} [`<B>,</B>'] + ffield ::= `<B>[</B>' exp `<B>]</B>' `<B>=</B>' exp | name `<B>=</B>' exp </PRE> For example, <PRE> - a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} + a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} </PRE> is equivalent to <PRE> - 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 </PRE> An expression like <CODE>{x = 1, y = 4}</CODE> is in fact syntactic sugar for <CODE>{["x"] = 1, ["y"] = 4}</CODE>. <P> Both forms may have an optional trailing comma, and can be used in the same constructor separated by -a semi-collon. -For example, all forms below are correct: +a semi-colon. +For example, all forms below are correct. <PRE> - 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,} </PRE> <P> <A NAME="functioncall"></A> -<H3>4.6.8 - Function Calls</H3> -A <A NAME="function call">function call</A> has the following syntax: +<H3>4.5.8 - Function Calls</H3> +A <A NAME="function call">function call</A> in Lua has the following syntax: <PRE> -functioncall ::= simpleexp args + functioncall ::= varorfunc args </PRE> -First, <EM>simpleexp</EM> is evaluated. +First, <EM>varorfunc</EM> is evaluated. If its value has type <EM>function</EM>, then this function is called, with the given arguments. Otherwise, the ``function'' tag method is called, -having as first parameter the value of <EM>simpleexp</EM>, -and then the original call parameters. +having as first parameter the value of <EM>varorfunc</EM>, +and then the original call arguments +(see Section <A HREF="#tag-method">4.8</A>). <P> -The form: +The form <PRE> -functioncall ::= simpleexp '<B>:</B>' name args + functioncall ::= varorfunc `<B>:</B>' name args </PRE> can be used to call ``methods''. -A call <CODE>simpleexp:name(...)</CODE> -is syntactic sugar for -<PRE> - simpleexp.name(simpleexp, ...) -</PRE> -except that <CODE>simpleexp</CODE> is evaluated only once. +A call <CODE>v:name(...)</CODE> +is syntactic sugar for <CODE>v.name(v, ...)</CODE>, +except that <CODE>v</CODE> is evaluated only once. <P> Arguments have the following syntax: <PRE> -args ::= '<B>(</B>' [explist1] '<B>)</B>' -args ::= tableconstructor -args ::= '<B>literal</B>' -explist1 ::= exp1 {'<B>,</B>' exp1} + args ::= `<B>(</B>' [explist1] `<B>)</B>' + args ::= tableconstructor + args ::= literal + explist1 ::= {exp1 `<B>,</B>'} exp </PRE> All argument expressions are evaluated before the call. A call of the form <CODE>f{...}</CODE> is syntactic sugar for <CODE>f({...})</CODE>, that is, -the parameter list is a single new table. +the argument list is a single new table. A call of the form <CODE>f'...'</CODE> (or <CODE>f"..."</CODE> or <CODE>f[[...]]</CODE>) is syntactic sugar for <CODE>f('...')</CODE>, that is, -the parameter list is a single literal string. +the argument list is a single literal string. <P> Because a function can return any number of results -(see Section <A HREF="#return">4.5.3</A>), -the number of results must be adjusted before used. -If the function is called as a statement (see Section <A HREF="#funcstat">4.5.4</A>), +(see Section <A HREF="#return">4.4.3</A>), +the number of results must be adjusted before they are used (see Section <A HREF="#adjust">4.3</A>). +If the function is called as a statement (see Section <A HREF="#funcstat">4.4.5</A>), then its return list is adjusted to 0, thus discarding all returned values. If the function is called in a place that needs a single value @@ -704,166 +868,230 @@ thus discarding all returned values but the first one. If the function is called in a place that can hold many values (syntactically denoted by the non-terminal <EM>exp</EM>), then no adjustment is made. -Note that the only place that can hold many values -is the last (or the only) expression in an assignment -or in a return statement; see examples below. +The only places that can hold many values +is the last (or the only) expression in an assignment, +in an argument list, or in the <B>return</B> statement. +Here are some examples: <PRE> - f(); -- adjusted to 0 - g(x, f()); -- f() is adjusted to 1 - 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() + 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() </PRE> <P> <A NAME="func-def"></A> -<H3>4.6.9 - <A NAME="Function Definitions</H3>">Function Definitions</H3></A> +<H3>4.5.9 - <A NAME="Function Definitions</H3>">Function Definitions</H3></A> <P> The syntax for function definition is <PRE> -function ::= <B>function</B> '<B>(</B>' [parlist1] '<B>)</B>' block <B>end</B> -stat ::= <B>function</B> funcname '<B>(</B>' [parlist1] '<B>)</B>' block <B>end</B> -funcname ::= name | name '<B>.</B>' name + function ::= <B>function</B> `<B>(</B>' [parlist1] `<B>)</B>' block <B>end</B> + stat ::= <B>function</B> funcname `<B>(</B>' [parlist1] `<B>)</B>' block <B>end</B> + funcname ::= name | name `<B>.</B>' name | name `<B>:</B>' name </PRE> The statement <PRE> - function f (...) - ... - end + function f () ... end </PRE> is just syntactic sugar for <PRE> - f = function (...) - ... - end + f = function () ... end +</PRE> +and the statement +<PRE> + function v.f () ... end +</PRE> +is syntactic sugar for +<PRE> + v.f = function () ... end </PRE> <P> A function definition is an executable expression, whose value has type <EM>function</EM>. 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 Section <A HREF="#upvalue">4.7</A>), -and the function is <EM>instantiated</EM> (or ``closed''). -This function instance (or ``closure'') +its upvalues are fixed (see Section <A HREF="#upvalue">4.6</A>), +and the function is <EM>instantiated</EM> (or <EM>closed</EM>). +This function instance (or <EM>closure</EM>) is the final value of the expression. -Different instances of a same function +Different instances of the same function may have different upvalues. <P> Parameters act as local variables, initialized with the argument values: <PRE> -parlist1 ::= '<B>...</B>' -parlist1 ::= name {'<B>,</B>' name} ['<B>,</B>' '<B>...</B>'] + parlist1 ::= `<B>...</B>' + parlist1 ::= name {`<B>,</B>' name} [`<B>,</B>' `<B>...</B>'] </PRE> <A NAME="vararg"></A> When a function is called, the list of <A NAME="arguments">arguments</A> is adjusted to -the length of the list of parameters (see Section <A HREF="#adjust">4.4</A>), -unless the function is a <A NAME="vararg"><EM>vararg</EM></A> function, -indicated by the dots (...) at the end of its parameter list. +the length of the list of parameters (see Section <A HREF="#adjust">4.3</A>), +unless the function is a <A NAME="vararg function"><EM>vararg function</EM></A>, +which is +indicated by three dots (`<CODE>...</CODE>') at the end of its parameter list. A vararg function does not adjust its argument list; -instead, it collects any extra arguments into an implicit parameter, +instead, it collects all extra arguments into an implicit parameter, called <A NAME="arg"><TT>arg</TT></A>. -This parameter is always initialized as a table, -with a field <CODE>n</CODE> whose value is the number of extra arguments, -and the extra arguments at positions 1, 2, ... +The value of <CODE>arg</CODE> is a table, +with a field <CODE>n</CODE> whose value is the number of extra arguments, +and the extra arguments at positions 1, 2, ..., <CODE>n</CODE>. <P> -As an example, suppose definitions like: +As an example, consider the following definitions: <PRE> - function f(a, b) end - function g(a, b, ...) end + function f(a, b) end + function g(a, b, ...) end + function r() return 1,2,3 end </PRE> Then, we have the following mapping from arguments to parameters: <PRE> - CALL PARAMETERS + CALL PARAMETERS <P> - f(3) a=3, b=nil - f(3, 4) a=3, b=4 - f(3, 4, 5) a=3, b=4 + 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 <P> - 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(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} </PRE> <P> -Results are returned using the <CODE>return</CODE> statement (see Section <A HREF="#return">4.5.3</A>). -If control reaches the end of a function without a return instruction, +Results are returned using the <B>return</B> statement (see Section <A HREF="#return">4.4.3</A>). +If control reaches the end of a function +without encountering a <B>return</B> statement, then the function returns with no results. <P> -There is a special syntax for defining <A NAME="methods">methods</A>, -that is, functions that have an implicit extra parameter <A NAME="self"><TT>self</TT></A>: +The syntax <PRE> -function ::= <B>function</B> name '<B>:</B>' name '<B>(</B>' [parlist1] '<B>)</B>' block <B>end</B> + funcname ::= name `<B>:</B>' name </PRE> -Thus, a declaration like +is used for defining <A NAME="methods"><EM>methods</EM></A>, +that is, functions that have an implicit extra parameter <A NAME="self"><TT>self</TT></A>. +<P> +The statement <PRE> - function v:f (...) - ... - end + function v:f (...) ... end </PRE> -is equivalent to +is just syntactic sugar for <PRE> - v.f = function (self, ...) - ... - end + v.f = function (self, ...) ... end </PRE> -that is, the function gets an extra formal parameter called <CODE>self</CODE>. -Note that the variable <CODE>v</CODE> must have been -previously initialized with a table value. +Note that the function gets an extra formal parameter called <CODE>self</CODE>. <P> <P> <A NAME="upvalue"></A> -<A NAME="4.7"></A> -<H2>4.7 - Visibility and Upvalues</H2> -<A NAME="Visibility"></A> <A NAME="Upvalues"></A> +<A NAME="4.6"></A> +<H2>4.6 - Visibility and Upvalues</H2> +<A NAME="visibility"></A><A NAME="upvalues"></A> <P> A function body may refer to its own local variables -(which includes its parameters) and to global variables, -as long as they are not shadowed by local -variables from enclosing functions. +(which include its parameters) and to global variables, +as long as they are not <EM>shadowed</EM> by local +variables with the same name from enclosing functions. A function <EM>cannot</EM> access a local variable from an enclosing function, since such variables may no longer exist when the function is called. However, a function may access the <EM>value</EM> of a local variable -from an enclosing function, using <EM>upvalues</EM>. -<P> +from an enclosing function, using <EM>upvalues</EM>, +whose syntax is <PRE> -upvalue ::= '<B>%</B>' name + upvalue ::= `<B>%</B>' name </PRE> +<P> An upvalue is somewhat similar to a variable expression, -but whose value is frozen when the function wherein it +but whose value is <EM>frozen</EM> 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. +at the point where the function is defined, +that is, +global variables and local variables +from the <EM>immediately enclosing</EM> function. +Note that when the upvalue is a table, +only the <EM>reference</EM> 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. <P> Here are some examples: <PRE> - a,b,c = 1,2,3 -- global variables - function f (x) - local b -- x and b are local to f - 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') - p = %c -- OK, access frozen value of global 'c' - p = %y -- ERROR: 'y' 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 </PRE> <P> <P> +<A NAME="error"></A> +<A NAME="4.7"></A> +<H2>4.7 - Error Handling</H2> +<P> +Because Lua is an extension language, +all Lua actions start from C code in the host program +calling a function from the Lua library. +Whenever an error occurs during Lua compilation or execution, +the function <CODE>_ERRORMESSAGE</CODE> is called <A NAME="_ERRORMESSAGE"></A> +(provided it is different from <B>nil</B>), +and then the corresponding function from the library +(<CODE>lua_dofile</CODE>, <CODE>lua_dostring</CODE>, +<CODE>lua_dobuffer</CODE>, or <CODE>lua_call</CODE>) +is terminated, returning an error condition. +<P> +Memory allocation errors are an exception to the previous rule. +When memory allocation fails, Lua may not be able to execute the +<CODE>_ERRORMESSAGE</CODE> function. +So, for this kind of error, Lua does not call +the <CODE>_ERRORMESSAGE</CODE> function; +instead, the corresponding function from the library +returns immediately with a special error code (<CODE>LUA_ERRMEM</CODE>). +This and other error codes are defined in <CODE>lua.h</CODE>; +Section <A HREF="#luado">5.8</A>. +<P> +The only argument to <CODE>_ERRORMESSAGE</CODE> is a string +describing the error. +The default definition for +this function calls <CODE>_ALERT</CODE>, <A NAME="_ALERT"></A> +which prints the message to <CODE>stderr</CODE> (see Section <A HREF="#alert">6.1</A>). +The standard I/O library redefines <CODE>_ERRORMESSAGE</CODE> +and uses the debug facilities (see Section <A HREF="#debugI">7</A>) +to print some extra information, +such as a call stack traceback. +<P> +Lua code can explicitly generate an error by calling the +function <CODE>error</CODE> (see Section <A HREF="#pdf-error">6.1</A>). +Lua code can ``catch'' an error using the function +<CODE>call</CODE> (see Section <A HREF="#pdf-call">6.1</A>). +<P> +<P> <A NAME="tag-method"></A> <A NAME="4.8"></A> <H2>4.8 - Tag Methods</H2> <P> Lua provides a powerful mechanism to extend its semantics, -called <A NAME="tag methods"><EM>tag methods</EM></A>. +called <EM>tag methods</EM>. A tag method is a programmer-defined function -that is called at specific key points during the evaluation of a program, +that is called at specific key points during the execution of a Lua program, allowing the programmer to change the standard Lua behavior at these points. Each of these points is called an <A NAME="event"><EM>event</EM></A>. <P> @@ -876,8 +1104,8 @@ Its first parameter is the tag, the second parameter is the event name (a string; see below), and the third parameter is the new method (a function), or <B>nil</B> to restore the default behavior for the pair. -The function returns the previous tag method for that pair. -Another function, <A NAME="gettagmethod"><TT>gettagmethod</TT></A>, +The <CODE>settagmethod</CODE> function returns the previous tag method for that pair. +A companion function <A NAME="gettagmethod"><TT>gettagmethod</TT></A> receives a tag and an event name and returns the current method associated with the pair. <P> @@ -885,573 +1113,640 @@ Tag methods are called in the following events, identified by the given names. The semantics of tag methods is better explained by a Lua function describing the behavior of the interpreter at each event. -The function not only shows when a tag method is called, -but also its arguments, its results and the default behavior. -Please notice that the code shown here is only illustrative; +This function not only shows when a tag method is called, +but also its arguments, its results, and the default behavior. +The code shown here is only <EM>illustrative</EM>; the real behavior is hard coded in the interpreter, and it is much more efficient than this simulation. All functions used in these descriptions -(<CODE>rawgetglobal</CODE>, <CODE>tonumber</CODE>, <CODE>call</CODE>, etc.) +(<CODE>rawget</CODE>, <CODE>tonumber</CODE>, <CODE>call</CODE>, etc.) are described in Section <A HREF="#predefined">6.1</A>. <P> <DL> <P> <DT><B>``add'':</B><DD><A NAME="add event"></A> -called when a <CODE>+</CODE> operation is applied to non numerical operands. +called when a <CODE>+</CODE> operation is applied to non-numerical operands. <P> -The function <CODE>getbinmethod</CODE> defines how Lua chooses a tag method +The function <CODE>getbinmethod</CODE> 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: -<PRE> - function getbinmethod (op1, op2, event) - return gettagmethod(tag(op1), event) or - gettagmethod(tag(op2), event) or - gettagmethod(0, event) - end -</PRE> -<PRE> - 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 +If it also fails, then it gets a tag method from tag 0. +<PRE> + function getbinmethod (op1, op2, event) + return gettagmethod(tag(op1), event) or + gettagmethod(tag(op2), event) or + gettagmethod(0, event) + end +</PRE> +Using this function, +the tag method for the ``add'' event is +<PRE> + 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 </PRE> <P> <DT><B>``sub'':</B><DD><A NAME="sub event"></A> -called when a <CODE>-</CODE> operation is applied to non numerical operands. -Behavior similar to the <CODE>"add"</CODE> event. +called when a <CODE>-</CODE> operation is applied to non-numerical operands. +Behavior similar to the ``add'' event. <P> <DT><B>``mul'':</B><DD><A NAME="mul event"></A> -called when a <CODE>*</CODE> operation is applied to non numerical operands. -Behavior similar to the <CODE>"add"</CODE> event. +called when a <CODE>*</CODE> operation is applied to non-numerical operands. +Behavior similar to the ``add'' event. <P> <DT><B>``div'':</B><DD><A NAME="div event"></A> -called when a <CODE>/</CODE> operation is applied to non numerical operands. -Behavior similar to the <CODE>"add"</CODE> event. +called when a <CODE>/</CODE> operation is applied to non-numerical operands. +Behavior similar to the ``add'' event. <P> <DT><B>``pow'':</B><DD><A NAME="pow event"></A> -called when a <CODE>^</CODE> operation is applied. +called when a <CODE>^</CODE> operation (exponentiation) is applied, +even for numerical operands. <PRE> - 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 </PRE> <P> <DT><B>``unm'':</B><DD><A NAME="unm event"></A> -called when an unary <CODE>-</CODE> operation is applied to a non numerical operand. -<PRE> - 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 +called when a unary <CODE>-</CODE> operation is applied to a non-numerical operand. +<PRE> + 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 </PRE> <P> <DT><B>``lt'':</B><DD><A NAME="lt event"></A> -called when a <CODE><</CODE> operation is applied to non numerical -or non string operands. -<PRE> - 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 -</PRE> -<P> -<DT><B>``gt'':</B><DD><A NAME="gt event"></A> -called when a <CODE>></CODE> operation is applied to non numerical -or non string operands. -Behavior similar to the <CODE>"lt"</CODE> event. -<P> -<DT><B>``le'':</B><DD><A NAME="le event"></A> -called when a <CODE><=</CODE> operation is applied to non numerical -or non string operands. -Behavior similar to the <CODE>"lt"</CODE> event. -<P> -<DT><B>``ge'':</B><DD><A NAME="ge event"></A> -called when a <CODE>>=</CODE> operation is applied to non numerical -or non string operands. -Behavior similar to the <CODE>"lt"</CODE> event. +called when an order operation is applied to non-numerical +or non-string operands. +It corresponds to the <CODE><</CODE> operator. +<PRE> + 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 +</PRE> +The other order operators use this tag method according to the +usual equivalences: +<PRE> + a>b <=> b<a + a<=b <=> not (b<a) + a>=b <=> not (a<b) +</PRE> <P> <DT><B>``concat'':</B><DD><A NAME="concatenation event"></A> -called when a concatenation is applied to non string operands. -<PRE> - function concat_event (op1, op2) - if (type(op1) == "string" or type(op1) == "number") and - (type(op2) == "string" or type(op2) == "number") then - return op1..op2 -- primitive string concatenation - else - local tm = getbinmethod(op1, op2, "concat") - if tm then - return tm(op1, op2, "concat") - else - error("unexpected type for concatenation") - end - end - end +called when a concatenation is applied to non-string operands. +<PRE> + function concat_event (op1, op2) + if (type(op1) == "string" or type(op1) == "number") and + (type(op2) == "string" or type(op2) == "number") then + return op1..op2 -- primitive string concatenation + else + local tm = getbinmethod(op1, op2, "concat") + if tm then + return tm(op1, op2, "concat") + else + error("unexpected type for concatenation") + end + end + end </PRE> <P> <DT><B>``index'':</B><DD><A NAME="index event"></A> called when Lua tries to retrieve the value of an index not present in a table. -See event <CODE>"gettable"</CODE> for its semantics. +See the ``gettable'' event for its semantics. <P> <DT><B>``getglobal'':</B><DD><A NAME="getglobal event"></A> called whenever Lua needs the value of a global variable. This method can only be set for <B>nil</B> and for tags created by <CODE>newtag</CODE>. -<PRE> - function getglobal (varname) - local value = rawgetglobal(varname) - local tm = gettagmethod(tag(value), "getglobal") - if not tm then - return value - else - return tm(varname, value) - end - end -</PRE> -The function <CODE>getglobal</CODE> is pre-defined in Lua (see Section <A HREF="#predefined">6.1</A>). +Note that +the tag is that of the <EM>current value</EM> of the global variable. +<PRE> + function getglobal (varname) + -- access the table of globals + local value = rawget(globals(), varname) + local tm = gettagmethod(tag(value), "getglobal") + if not tm then + return value + else + return tm(varname, value) + end + end +</PRE> +The function <CODE>getglobal</CODE> is defined in the basic library (see Section <A HREF="#predefined">6.1</A>). <P> <DT><B>``setglobal'':</B><DD><A NAME="setglobal event"></A> called whenever Lua assigns to a global variable. This method cannot be set for numbers, strings, and tables and -userdata with default tags. +userdata with the default tag. <PRE> - function setglobal (varname, newvalue) - local oldvalue = rawgetglobal(varname) - local tm = gettagmethod(tag(oldvalue), "setglobal") - if not tm then - return rawsetglobal(varname, newvalue) - else - return tm(varname, oldvalue, newvalue) - end - end + function setglobal (varname, newvalue) + local oldvalue = rawget(globals(), varname) + local tm = gettagmethod(tag(oldvalue), "setglobal") + if not tm then + rawset(globals(), varname, newvalue) + else + tm(varname, oldvalue, newvalue) + end + end </PRE> -Notice: the function <CODE>setglobal</CODE> is pre-defined in Lua (see Section <A HREF="#predefined">6.1</A>). +The function <CODE>setglobal</CODE> is defined in the basic library (see Section <A HREF="#predefined">6.1</A>). <P> <DT><B>``gettable'':</B><DD><A NAME="gettable event"></A> called whenever Lua accesses an indexed variable. -This method cannot be set for tables with default tag. -<PRE> - function gettable_event (table, index) - local tm = gettagmethod(tag(table), "gettable") - if tm then - return tm(table, index) - elseif type(table) ~= "table" then - error("indexed expression not a table"); - else - local v = rawgettable(table, index) - tm = gettagmethod(tag(table), "index") - if v == nil and tm then - return tm(table, index) - else - return v - end - end - end +This method cannot be set for tables with the default tag. +<PRE> + function gettable_event (table, index) + local tm = gettagmethod(tag(table), "gettable") + if tm then + return tm(table, index) + elseif type(table) ~= "table" then + error("indexed expression not a table"); + else + local v = rawget(table, index) + tm = gettagmethod(tag(table), "index") + if v == nil and tm then + return tm(table, index) + else + return v + end + end + end </PRE> <P> <DT><B>``settable'':</B><DD><A NAME="settable event"></A> called when Lua assigns to an indexed variable. -This method cannot be set for tables with default tag. +This method cannot be set for tables with the default tag. <PRE> - function settable_event (table, index, value) - local tm = gettagmethod(tag(table), "settable") - if tm then - tm(table, index, value) - elseif type(table) ~= "table" then - error("indexed expression not a table") - else - rawsettable(table, index, value) - end - end + function settable_event (table, index, value) + local tm = gettagmethod(tag(table), "settable") + if tm then + tm(table, index, value) + elseif type(table) ~= "table" then + error("indexed expression not a table") + else + rawset(table, index, value) + end + end </PRE> <P> <DT><B>``function'':</B><DD><A NAME="function event"></A> -called when Lua tries to call a non function value. -<PRE> - function function_event (func, ...) - if type(func) == "function" then - return call(func, arg) - else - local tm = gettagmethod(tag(func), "function") - if tm then - local i = arg.n - while i > 0 do - arg[i+1] = arg[i] - i = i-1 - end - arg.n = arg.n+1 - arg[1] = func - return call(tm, arg) - else - error("call expression not a function") - end - end - end +called when Lua tries to call a non-function value. +<PRE> + function function_event (func, ...) + if type(func) == "function" then + return call(func, arg) + else + local tm = gettagmethod(tag(func), "function") + if tm then + for i=arg.n,1,-1 do + arg[i+1] = arg[i] + end + arg.n = arg.n+1 + arg[1] = func + return call(tm, arg) + else + error("call expression not a function") + end + end + end </PRE> <P> <DT><B>``gc'':</B><DD><A NAME="gc event"></A> -called when Lua is ``garbage collecting'' an object. -This method cannot be set for strings, numbers, functions, -and userdata with default tag. -For each object to be collected, +called when Lua is ``garbage collecting'' a userdata. +This tag method can be set only from C, +and cannot be set for a userdata with the default tag. +For each userdata to be collected, Lua does the equivalent of the following function: <PRE> - function gc_event (obj) - local tm = gettagmethod(tag(obj), "gc") - if tm then - tm(obj) - end - end -</PRE> -Moreover, at the end of a garbage collection cycle, + function gc_event (obj) + local tm = gettagmethod(tag(obj), "gc") + if tm then + tm(obj) + end + end +</PRE> +In a garbage-collection cycle, +the tag methods for userdata are called in <EM>reverse</EM> order of tag creation, +that is, the first tag methods to be called are those associated +with the last tag created in the program. +Moreover, at the end of the cycle, Lua does the equivalent of the call <CODE>gc_event(nil)</CODE>. <P> </DL> <P> <P> <P> -<A NAME="error"></A> -<A NAME="4.9"></A> -<H2>4.9 - Error Handling</H2> -<P> -Because Lua is an extension language, -all Lua actions start from C code in the host program -calling a function from the Lua library. -Whenever an error occurs during Lua compilation or execution, -function <CODE>_ERRORMESSAGE</CODE> is called <A NAME="_ERRORMESSAGE"></A> -(provided it is different from <B>nil</B>), -and then the corresponding function from the library -(<CODE>lua_dofile</CODE>, <CODE>lua_dostring</CODE>, -<CODE>lua_dobuffer</CODE>, or <CODE>lua_callfunction</CODE>) -is terminated, returning an error condition. -<P> -The only argument to <CODE>_ERRORMESSAGE</CODE> is a string -describing the error. -The default definition for this function calls <CODE>_ALERT</CODE>, -which prints the message to <CODE>stderr</CODE> (see Section <A HREF="#alert">6.1</A>). -The standard I/O library redefines <CODE>_ERRORMESSAGE</CODE>, -and uses the debug facilities (see Section <A HREF="#debugI">7</A>) -to print some extra information, -such as the call stack. -<P> -To provide more information about errors, -Lua programs should include the compilation pragma <CODE>$debug</CODE>. -<A NAME="pragma"></A> -<A NAME="debug pragma"></A> -When an error occurs in a chunk compiled with this option, -the I/O error routine is able to print the number of the -lines where the calls (and the error) were made. -<P> -Lua code can explicitly generate an error by calling the built-in -function <CODE>error</CODE> (see Section <A HREF="#pdf-error">6.1</A>). -Lua code can ``catch'' an error using the built-in function -<CODE>call</CODE> (see Section <A HREF="#pdf-call">6.1</A>). -<P> -<P> <P> <!-- ====================================================================== --> <HR> <A NAME="5."></A> <H1>5 - The Application Program Interface</H1> -<P> +<A NAME="C API"></A> This section describes the API for Lua, that is, -the set of C functions available to the host program to communicate -with the Lua library. -The API functions can be classified in the following categories: -<OL> -<LI>managing states; -<LI>exchanging values between C and Lua; -<LI>executing Lua code; -<LI>manipulating (reading and writing) Lua objects; -<LI>calling Lua functions; -<LI>C functions to be called by Lua; -<LI>manipulating references to Lua Objects. -</OL> +the set of C functions available to the host program to communicate +with Lua. All API functions and related types and constants are declared in the header file <CODE>lua.h</CODE>. <P> +Even when we use the term ``function'', +any facility in the API may be provided as a <EM>macro</EM> instead. +All such macros use each of its arguments exactly once, +and so do not generate hidden side-effects. +<P> +<P> <A NAME="mangstate"></A> <A NAME="5.1"></A> -<H2>5.1 - Managing States</H2> +<H2>5.1 - States</H2> +<P> +The Lua library is fully reentrant: +it does not have any global variables. +<A NAME="state"></A> The whole state of the Lua interpreter -(global variables, stack, tag methods, etc) -is stored in a dynamic structure pointed by<A NAME="lua_state"></A> -<PRE> -typedef struct lua_State lua_State; -extern lua_State *lua_state; -</PRE> -The variable <CODE>lua_state</CODE> is the only C global variable in -the Lua library. +(global variables, stack, tag methods, etc.) +is stored in a dynamically allocated structure of type <CODE>lua_State</CODE>; <A NAME="lua_State"></A> +this state must be passed as the first argument to +every function in the library (except <CODE>lua_open</CODE> below). <P> Before calling any API function, -this state must be initialized. -This is done by calling<A NAME="lua_open"></A> +you must create a state by calling +<A NAME="lua_open"></A> <PRE> -void lua_open (void); + lua_State *lua_open (int stacksize); </PRE> -This function allocates and initializes some internal structures, -and defines all pre-defined functions of Lua. -If <CODE>lua_state</CODE> is already different from <CODE>NULL</CODE>, -<CODE>lua_open</CODE> has no effect; -therefore, it is safe to call this function multiple times. -All standard libraries call <CODE>lua_open</CODE> when they are opened. +The sole argument to this function is the stack size for the interpreter. +(Each function call needs one stack position for each argument, local variable, +and temporary value, plus one position for book-keeping. +The stack must also have some 20 extra positions available. +For very small implementations, without recursive functions, +a stack size of 100 should be enough.) +If <CODE>stacksize</CODE> is zero, +then a default size of 1024 is used. <P> -Function <CODE>lua_setstate</CODE> is used to change the current state -of Lua:<A NAME="lua_setstate"></A> +To release a state created with <CODE>lua_open</CODE>, call +<A NAME="lua_close"></A> <PRE> -lua_State *lua_setstate (lua_State *st); + void lua_close (lua_State *L); </PRE> -It sets <CODE>lua_state</CODE> to <CODE>st</CODE> and returns the old state. +This function destroys all objects in the given Lua environment +(calling the corresponding garbage-collection tag methods, if any) +and frees all dynamic memory used by that state. +Usually, you do not need to call this function, +because all resources are naturally released when your program ends. +On the other hand, +long-running programs - +like a daemon or a web server - +might need to release states as soon as they are not needed, +to avoid growing too big. +<P> +With the exception of <CODE>lua_open</CODE>, +all functions in the Lua API need a state as their first argument. <P> -Multiple, independent states may be created. -For that, you must set <CODE>lua_state</CODE> back to <CODE>NULL</CODE> before -calling <CODE>lua_open</CODE>. -An easy way to do that is defining an auxiliary function: -<PRE> - lua_State *lua_newstate (void) { - lua_State *old = lua_setstate(NULL); - lua_open(); - return lua_setstate(old); - } -</PRE> -This function creates a new state without changing the current state -of the interpreter. -Note that any new state is created with all predefined functions, -but any additional library (such as the standard libraries) must be -explicitly open in the new state, if needed. -<P> -If necessary, a state may be released by calling<A NAME="lua_close"></A> -<PRE> -void lua_close (void); -</PRE> -This function destroys all objects in the current Lua environment -(calling the correspondent garbage collector tag methods), -frees all dynamic memory used by the state, -and then sets <CODE>lua_state</CODE> to <CODE>NULL</CODE>. -Usually, there is no need to call this function, -since these resources are naturally released when the program ends. -If <CODE>lua_state</CODE> is already <CODE>NULL</CODE>, -<CODE>lua_close</CODE> has no effect. -<P> -If you are using multiple states, -you may find useful to define the following function, -which releases a given state: -<PRE> - void lua_freestate (lua_State *st) { - lua_State *old = lua_setstate(st); - lua_close(); - if (old != st) lua_setstate(old); - } -</PRE> <P> -<A NAME="valuesCLua"></A> <A NAME="5.2"></A> -<H2>5.2 - Exchanging Values between C and Lua</H2> -Because Lua has no static type system, -all values passed between Lua and C have type -<CODE>lua_Object</CODE><A NAME="lua_Object"></A>, -which works like an abstract type in C that can hold any Lua value. -Values of type <CODE>lua_Object</CODE> have no meaning outside Lua; -for instance, -the comparison of two <CODE>lua_Object's</CODE> is undefined. -<P> -To check the type of a <CODE>lua_Object</CODE>, +<H2>5.2 - The Stack and Indices</H2> +<P> +Lua uses a <EM>stack</EM> to pass values to and from C. +Each element in this stack represents a Lua value +(nil, number, string, etc.). +<P> +For convenience, +most query operations in the API do not follow a strict stack discipline. +Instead, they can refer to any element in the stack by using an <EM>index</EM>: +A positive index represents an <EM>absolute</EM> stack position +(starting at 1, not 0 as in C); +a negative index represents an <EM>offset</EM> from the top of the stack. +More specifically, if the stack has <EM>n</EM> elements, +index 1 represents the first element +(that is, the first element pushed onto the stack), +and +index <EM>n</EM> represents the last element; +index <I>-1</I> also represents the last element +(that is, the element at the top), +and index <I>-n</I> represents the first element. +We say that an index is <EM>valid</EM> +if it lays between 1 and the stack top +(that is, if <CODE>1 <= abs(index) <= top</CODE>). +<A NAME="stack index"></A> <A NAME="valid index"></A> +<P> +At any time, you can get the index of the top element by calling +<A NAME="lua_gettop"></A> +<PRE> + int lua_gettop (lua_State *L); +</PRE> +Because indices start at 1, +the result of <CODE>lua_gettop</CODE> is equal to the number of elements in the stack +(and so 0 means an empty stack). +<P> +When you interact with Lua API, +<EM>you are responsible for controlling stack overflow</EM>. +The function <A NAME="lua_stackspace"></A> +<PRE> + int lua_stackspace (lua_State *L); +</PRE> +returns the number of stack positions still available. +Whenever Lua calls C, <A NAME="LUA_MINSTACK"></A> +it ensures that +at least <CODE>LUA_MINSTACK</CODE> positions are still available. +<CODE>LUA_MINSTACK</CODE> is defined in <CODE>lua.h</CODE> and is at least 16, +and so you have to worry about stack space only +when your code has loops pushing elements onto the stack. +<P> +Most query functions accept as indices any value inside the +available stack space. +Such indices are called <EM>acceptable indices</EM>. +More formally, we can define an <A NAME="acceptable index"><EM>acceptable index</EM></A> +as +<PRE> + (index < 0 && abs(index) <= top) || (index > 0 && index <= top + stackspace) +</PRE> +Note that 0 is not an acceptable index. +<P> +<A NAME="5.3"></A> +<H2>5.3 - Stack Manipulation</H2> +The API offers the following functions for basic stack manipulation: +<A NAME="lua_settop"></A><A NAME="lua_pushvalue"></A> +<A NAME="lua_remove"></A><A NAME="lua_insert"></A> +<PRE> + void lua_settop (lua_State *L, int index); + void lua_pushvalue (lua_State *L, int index); + void lua_remove (lua_State *L, int index); + void lua_insert (lua_State *L, int index); +</PRE> +<P> +<CODE>lua_settop</CODE> accepts any acceptable index, +or 0, +and sets the stack top to that index. +If the new top is larger than the old one, +then the new elements are filled with <B>nil</B>. +If <CODE>index</CODE> is 0, then all stack elements are removed. +A useful macro defined in the API is +<PRE> + #define lua_pop(L,n) lua_settop(L, -(n)-1) +</PRE> +which pops <CODE>n</CODE> elements from the stack. +<P> +<CODE>lua_pushvalue</CODE> pushes onto the stack a <EM>copy</EM> of the element +at the given index. +<CODE>lua_remove</CODE> removes the element at the given position, +shifting down the elements on top of that position to fill in the gap. +<CODE>lua_insert</CODE> moves the top element into the given position, +shifting up the elements on top of that position to open space. +These functions accept only valid indices. +As an example, if the stack starts as <CODE>10 20 30 40 50</CODE> +(from bottom to top), +then +<PRE> + lua_pushvalue(L, 3) --> 10 20 30 40 50 30 + lua_pushvalue(L, -1) --> 10 20 30 40 50 30 30 + lua_remove(L, -3) --> 10 20 30 40 30 30 + lua_remove(L, 6) --> 10 20 30 40 30 + lua_insert(L, 1) --> 30 10 20 30 40 + lua_insert(L, -1) --> 30 10 20 30 40 (no effect) + lua_settop(L, -3) --> 30 10 20 + lua_settop(L, 6) --> 30 10 20 nil nil nil +</PRE> +<P> +<P> +<A NAME="5.4"></A> +<H2>5.4 - Querying the Stack</H2> +<P> +To check the type of a stack element, the following functions are available: +<A NAME="lua_type"></A><A NAME="lua_tag"></A> <A NAME="lua_isnil"></A><A NAME="lua_isnumber"></A><A NAME="lua_isstring"></A> -<A NAME="lua_istable"></A><A NAME="lua_iscfunction"></A><A NAME="lua_isuserdata"></A> -<A NAME="lua_isfunction"></A> -<PRE> -int lua_isnil (lua_Object object); -int lua_isnumber (lua_Object object); -int lua_isstring (lua_Object object); -int lua_istable (lua_Object object); -int lua_isfunction (lua_Object object); -int lua_iscfunction (lua_Object object); -int lua_isuserdata (lua_Object object); -</PRE> -These functions return 1 if the object is compatible with the given type, -and 0 otherwise. -The function <CODE>lua_isnumber</CODE> accepts numbers and numerical strings, -whereas -<CODE>lua_isstring</CODE> accepts strings and numbers (see Section <A HREF="#coercion">4.3</A>), -and <CODE>lua_isfunction</CODE> accepts Lua functions and C functions. -<P> -To get the tag of a <CODE>lua_Object</CODE>, -the following function is available: -<A NAME="lua_tag"></A> -<PRE> -int lua_tag (lua_Object object); -</PRE> -<P> -To translate a value from type <CODE>lua_Object</CODE> to a specific C type, -the programmer can use: -<A NAME="lua_getnumber"></A><A NAME="lua_getstring"></A><A NAME="lua_strlen"></A> -<A NAME="lua_getcfunction"></A><A NAME="lua_getuserdata"></A> -<PRE> -double lua_getnumber (lua_Object object); -char *lua_getstring (lua_Object object); -long lua_strlen (lua_Object object); -lua_CFunction lua_getcfunction (lua_Object object); -void *lua_getuserdata (lua_Object object); -</PRE> -<P> -<CODE>lua_getnumber</CODE> converts a <CODE>lua_Object</CODE> to a floating-point number. -This <CODE>lua_Object</CODE> must be a number or a string convertible to number -(see Section <A HREF="#coercion">4.3</A>); otherwise, <CODE>lua_getnumber</CODE> returns 0. -<P> -<CODE>lua_getstring</CODE> converts a <CODE>lua_Object</CODE> to a string (<CODE>char*</CODE>). -This <CODE>lua_Object</CODE> must be a string or a number; -otherwise, the function returns 0 (the <CODE>NULL</CODE> pointer). -This function does not create a new string, -but returns a pointer to a string inside the Lua environment. -Those strings always have a 0 after their last character (like in C), +<A NAME="lua_istable"></A> +<A NAME="lua_isfunction"></A><A NAME="lua_iscfunction"></A><A NAME="lua_isuserdata"></A> +<PRE> + int lua_type (lua_State *L, int index); + int lua_tag (lua_State *L, int index); + int lua_isnil (lua_State *L, int index); + int lua_isnumber (lua_State *L, int index); + int lua_isstring (lua_State *L, int index); + int lua_istable (lua_State *L, int index); + int lua_isfunction (lua_State *L, int index); + int lua_iscfunction (lua_State *L, int index); + int lua_isuserdata (lua_State *L, int index); +</PRE> +These functions can be called with any acceptable index. +<P> +<CODE>lua_type</CODE> returns one of the following constants, +according to the type of the given object: +<CODE>LUA_TNIL</CODE>, +<CODE>LUA_TNUMBER</CODE>, +<CODE>LUA_TSTRING</CODE>, +<CODE>LUA_TTABLE</CODE>, +<CODE>LUA_TFUNCTION</CODE>, +<CODE>LUA_TUSERDATA</CODE>. +If the index is non-valid +(that is, if that stack position is ``empty''), +then <CODE>lua_type</CODE> returns <CODE>LUA_TNONE</CODE>. +These constants can be converted to strings with +<A NAME="lua_typename"></A> +<PRE> + const char *lua_typename (lua_State *L, int t); +</PRE> +where <CODE>t</CODE> is a type returned by <CODE>lua_type</CODE>. +The strings returned by <CODE>lua_typename</CODE> are +<CODE>"nil"</CODE>, <CODE>"number"</CODE>, <CODE>"string"</CODE>, <CODE>"table"</CODE>, +<CODE>"function"</CODE>, <CODE>"userdata"</CODE>, and <CODE>"no value"</CODE>, +<P> +<CODE>lua_tag</CODE> returns the tag of a value, +or <CODE>LUA_NOTAG</CODE> for a non-valid index. +<P> +The <CODE>lua_is*</CODE> functions return 1 if the object is compatible +with the given type, and 0 otherwise. +They always return 0 for a non-valid index. +<CODE>lua_isnumber</CODE> accepts numbers and numerical strings, +<CODE>lua_isstring</CODE> accepts strings and numbers (see Section <A HREF="#coercion">4.2</A>), +and <CODE>lua_isfunction</CODE> accepts both Lua functions and C functions. +To distinguish between Lua functions and C functions, +you should use <CODE>lua_iscfunction</CODE>. +To distinguish between numbers and numerical strings, +you can use <CODE>lua_type</CODE>. +<P> +The API also has functions to compare two values in the stack: +<A NAME="lua_equal"></A> +<A NAME="lua_lessthan"></A> +<PRE> + int lua_equal (lua_State *L, int index1, int index2); + int lua_lessthan (lua_State *L, int index1, int index2); +</PRE> +These functions are equivalent to their counterparts in Lua. +Specifically, <CODE>lua_lessthan</CODE> is equivalent to the <CODE>lt_event</CODE> +described in Section <A HREF="#tag-method">4.8</A>. +Both functions return 0 if any of the indices are non-valid. +<P> +To translate a value in the stack to a specific C type, +you can use the following conversion functions: +<A NAME="lua_tonumber"></A><A NAME="lua_tostring"></A><A NAME="lua_strlen"></A> +<A NAME="lua_tocfunction"></A><A NAME="lua_touserdata"></A> +<PRE> + double lua_tonumber (lua_State *L, int index); + const char *lua_tostring (lua_State *L, int index); + size_t lua_strlen (lua_State *L, int index); + lua_CFunction lua_tocfunction (lua_State *L, int index); + void *lua_touserdata (lua_State *L, int index); +</PRE> +These functions can be called with any acceptable index. +When called with a non-valid index, +they act as if the given value had an incorrect type. +<P> +<CODE>lua_tonumber</CODE> converts the value at the given index +to a floating-point number. +This value must be a number or a string convertible to number +(see Section <A HREF="#coercion">4.2</A>); otherwise, <CODE>lua_tonumber</CODE> returns 0. +<P> +<CODE>lua_tostring</CODE> converts a Lua value to a string +(<CODE>const char*</CODE>). +This value must be a string or a number; +otherwise, the function returns <CODE>NULL</CODE>. +This function returns a pointer to a string inside the Lua environment. +Those strings always have a zero (<CODE>'\0'</CODE>) after their last character (as in C), but may contain other zeros in their body. If you do not know whether a string may contain zeros, -you can use <CODE>lua_strlen</CODE> to get the actual length. +you should use <CODE>lua_strlen</CODE> to get its actual length. Because Lua has garbage collection, -there is no guarantee that the pointer returned by <CODE>lua_getstring</CODE> -will be valid after the block ends -(see Section <A HREF="#GC">5.3</A>). +there is no guarantee that the pointer returned by <CODE>lua_tostring</CODE> +will be valid after the respective value is removed from the stack. <P> -<CODE>lua_getcfunction</CODE> converts a <CODE>lua_Object</CODE> to a C function. -This <CODE>lua_Object</CODE> must have type <EM>CFunction</EM>; -otherwise, <CODE>lua_getcfunction</CODE> returns 0 (the <CODE>NULL</CODE> pointer). -The type <CODE>lua_CFunction</CODE> is explained in Section <A HREF="#LuacallC">5.7</A>. +<CODE>lua_tocfunction</CODE> converts a value in the stack to a C function. +This value must be a C function; +otherwise, <CODE>lua_tocfunction</CODE> returns <CODE>NULL</CODE>. +The type <CODE>lua_CFunction</CODE> is explained in Section <A HREF="#LuacallC">5.13</A>. <P> -<CODE>lua_getuserdata</CODE> converts a <CODE>lua_Object</CODE> to <CODE>void*</CODE>. -This <CODE>lua_Object</CODE> must have type <EM>userdata</EM>; -otherwise, <CODE>lua_getuserdata</CODE> returns 0 (the <CODE>NULL</CODE> pointer). +<CODE>lua_touserdata</CODE> converts a value to <CODE>void*</CODE>. +This value must have type <EM>userdata</EM>; +otherwise, <CODE>lua_touserdata</CODE> returns <CODE>NULL</CODE>. <P> -<A NAME="GC"></A> -<A NAME="5.3"></A> -<H2>5.3 - Garbage Collection</H2> -Because Lua has automatic memory management and garbage collection, -a <CODE>lua_Object</CODE> has a limited scope, -and is only valid inside the <EM>block</EM> where it has been created. -A C function called from Lua is a block, -and its parameters are valid only until its end. -It is good programming practice to convert Lua objects to C values -as soon as they are available, -and never to store <CODE>lua_Object</CODE>s in C global variables. -<P> -A garbage collection cycle can be forced by: -<A NAME="lua_collectgarbage"></A> -<PRE> -long lua_collectgarbage (long limit); -</PRE> -This function returns the number of objects collected. -The argument <CODE>limit</CODE> makes the next cycle occur only -after that number of new objects have been created. -If <CODE>limit</CODE>=0, then Lua uses an adaptive heuristics to set this limit. -<P> -<P> -All communication between Lua and C is done through two -abstract data types, called <A NAME="lua2C"><EM>lua2C</EM></A> and <A NAME="C2lua"><EM>C2lua</EM></A>. -The first one, as the name implies, is used to pass values -from Lua to C: -parameters when Lua calls C and results when C calls Lua. -The structure C2lua is used in the reverse direction: -parameters when C calls Lua and results when Lua calls C. -<P> -The structure lua2C is an abstract array, -which can be indexed with the function: -<A NAME="lua_lua2C"></A> -<PRE> -lua_Object lua_lua2C (int number); -</PRE> -where <CODE>number</CODE> starts with 1. -When called with a number larger than the array size, -this function returns <CODE>LUA_NOOBJECT</CODE><A NAME="LUA_NOOBJECT"></A>. -In this way, it is possible to write C functions that receive -a variable number of parameters, -and to call Lua functions that return a variable number of results. -Note that the structure lua2C cannot be directly modified by C code. -<P> -The second structure, C2lua, is an abstract stack. -Pushing elements into this stack -is done with the following functions: +<P> +<P> +<A NAME="5.5"></A> +<H2>5.5 - Pushing values onto the Stack</H2> +<P> +The API has the following functions to +push C values onto the stack: <A NAME="lua_pushnumber"></A><A NAME="lua_pushlstring"></A><A NAME="lua_pushstring"></A> <A NAME="lua_pushcfunction"></A><A NAME="lua_pushusertag"></A> -<A NAME="lua_pushnil"></A><A NAME="lua_pushobject"></A> <A NAME="pushing"></A> -<A NAME="lua_pushuserdata"></A> -<PRE> -void lua_pushnumber (double n); -void lua_pushlstring (char *s, long len); -void lua_pushstring (char *s); -void lua_pushusertag (void *u, int tag); -void lua_pushnil (void); -void lua_pushobject (lua_Object object); -void lua_pushcfunction (lua_CFunction f); /* macro */ -</PRE> -All of them receive a C value, -convert it to a corresponding <CODE>lua_Object</CODE>, -and leave the result on the top of C2lua. -In particular, functions <CODE>lua_pushlstring</CODE> and <CODE>lua_pushstring</CODE> -make an internal copy of the given string. -Function <CODE>lua_pushstring</CODE> can only be used to push proper C strings -(that is, strings that do not contain zeros and end with a zero); -otherwise you should use the more generic <CODE>lua_pushlstring</CODE>. -The function -<A NAME="lua_pop"></A> -<PRE> -lua_Object lua_pop (void); -</PRE> -returns a reference to the object at the top of the C2lua stack, -and pops it. -<P> -As a general rule, all API functions pop from the stack -all elements they use. +<A NAME="lua_pushnil"></A><A NAME="lua_pushuserdata"></A> +<PRE> + void lua_pushnumber (lua_State *L, double n); + void lua_pushlstring (lua_State *L, const char *s, size_t len); + void lua_pushstring (lua_State *L, const char *s); + void lua_pushusertag (lua_State *L, void *u, int tag); + void lua_pushnil (lua_State *L); + void lua_pushcfunction (lua_State *L, lua_CFunction f); +</PRE> +These functions receive a C value, +convert it to a corresponding Lua value, +and push the result onto the stack. +In particular, <CODE>lua_pushlstring</CODE> and <CODE>lua_pushstring</CODE> +make an <EM>internal copy</EM> of the given string. +<CODE>lua_pushstring</CODE> can only be used to push proper C strings +(that is, strings that end with a zero and do not contain embedded zeros); +otherwise you should use the more general <CODE>lua_pushlstring</CODE>, +which accepts an explicit size. +<P> +<P> +<A NAME="GC"></A> +<A NAME="5.6"></A> +<H2>5.6 - Garbage Collection</H2> +<P> +Lua uses two numbers to control its garbage collection. +One number counts how many bytes of dynamic memory Lua is using, +and the other is a threshold. +(This internal byte counter kept by Lua is not completely acurate; +it is just a lower bound, usually within 10% of the correct value.) +When the number of bytes crosses the threshold, +Lua runs a garbage-collection cycle, +which reclaims the memory of all ``dead'' objects +(that is, objects no longer accessible from Lua). +The byte counter is corrected, +and then the threshold is reset to twice the value of the byte counter. +<P> +You can access the current values of these two numbers through the +following functions: +<A NAME="lua_getgcthreshold"></A> <A NAME="lua_getgccount"></A> +<PRE> + int lua_getgccount (lua_State *L); + int lua_getgcthreshold (lua_State *L); +</PRE> +Both return their respective values in Kbytes. +You can change the threshold value with +<A NAME="lua_setgcthreshold"></A> +<PRE> + void lua_setgcthreshold (lua_State *L, int newthreshold); +</PRE> +Again, the <CODE>newthreshold</CODE> value is given in Kbytes. +When you call this function, +Lua sets the new threshold and checks it against the byte counter. +If the new threshold is smaller than the byte counter, +then Lua immediately runs the garbage collector; +after the collection, +a new threshold is set according to the previous rule. +<P> +If you want to change the adaptative behavior of the garbage collector, +you can use the garbage-collection tag method for <B>nil</B> +to set your own threshold +(the tag method is called after Lua resets the threshold). +<P> +<P> +<A NAME="C-tags"></A> +<A NAME="5.7"></A> +<H2>5.7 - Userdata and Tags</H2> <P> Because userdata are objects, the function <CODE>lua_pushusertag</CODE> may create a new userdata. If Lua has a userdata with the given value (<CODE>void*</CODE>) and tag, -that userdata is pushed. +then that userdata is pushed. Otherwise, a new userdata is created, with the given value and tag. If this function is called with <CODE>tag</CODE> equal to <CODE>LUA_ANYTAG</CODE><A NAME="LUA_ANYTAG"></A>, @@ -1462,230 +1757,361 @@ with tag equal to 0. <P> Userdata can have different tags, whose semantics are only known to the host program. -Tags are created with the function: +Tags are created with the function <A NAME="lua_newtag"></A> <PRE> -int lua_newtag (void); + int lua_newtag (lua_State *L); </PRE> The function <CODE>lua_settag</CODE> changes the tag of -the object on the top of C2lua (and pops it); -the object must be a userdata or a table. +the object on top of the stack (without popping it): <A NAME="lua_settag"></A> <PRE> -void lua_settag (int tag); + void lua_settag (lua_State *L, int tag); </PRE> -<CODE>tag</CODE> must be a value created with <CODE>lua_newtag</CODE>. +The object must be a userdata or a table; +the given <CODE>tag</CODE> must be a value created with <CODE>lua_newtag</CODE>. <P> -When C code calls Lua repeatedly, as in a loop, -objects returned by these calls can accumulate, -and may cause a stack overflow. -To avoid this, -nested blocks can be defined with the functions: -<PRE> -void lua_beginblock (void); -void lua_endblock (void); -</PRE> -After the end of the block, -all <CODE>lua_Object</CODE>'s created inside it are released. -The use of explicit nested blocks is good programming practice -and is strongly encouraged. -<P> -<A NAME="5.4"></A> -<H2>5.4 - Executing Lua Code</H2> +<A NAME="luado"></A> +<A NAME="5.8"></A> +<H2>5.8 - Executing Lua Code</H2> A host program can execute Lua chunks written in a file or in a string -using the following functions: +by using the following functions: <A NAME="lua_dofile"></A><A NAME="lua_dostring"></A><A NAME="lua_dobuffer"></A> <PRE> -int lua_dofile (char *filename); -int lua_dostring (char *string); -int lua_dobuffer (char *buff, int size, char *name); + 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); </PRE> -All these functions return an error code: -0, in case of success; non zero, in case of errors. -More specifically, <CODE>lua_dofile</CODE> returns 2 if for any reason -it could not open the file. +These functions return +0 in case of success, or one of the following error codes if they fail: +<UL> +<LI><A NAME="LUA_ERRRUN"><TT>LUA_ERRRUN</TT></A> - +error while running the chunk. +<LI><A NAME="LUA_ERRSYNTAX"><TT>LUA_ERRSYNTAX</TT></A> - +syntax error during pre-compilation. +<LI><A NAME="LUA_ERRMEM"><TT>LUA_ERRMEM</TT></A> - +memory allocation error. +For such errors, Lua does not call <CODE>_ERRORMESSAGE</CODE> (see Section <A HREF="#error">4.7</A>). +<LI><A NAME="LUA_ERRERR"><TT>LUA_ERRERR</TT></A> - +error while running <CODE>_ERRORMESSAGE</CODE>. +For such errors, Lua does not call <CODE>_ERRORMESSAGE</CODE> again, to avoid loops. +<LI><A NAME="LUA_ERRFILE"><TT>LUA_ERRFILE</TT></A> - +error opening the file (only for <CODE>lua_dofile</CODE>). +In this case, +you may want to +check <CODE>errno</CODE>, +call <CODE>strerror</CODE>, +or call <CODE>perror</CODE> to tell the user what went wrong. +</UL> +These constants are defined in <CODE>lua.h</CODE>. +<P> When called with argument <CODE>NULL</CODE>, <CODE>lua_dofile</CODE> executes the <CODE>stdin</CODE> stream. -Functions <CODE>lua_dofile</CODE> and <CODE>lua_dobuffer</CODE> +<CODE>lua_dofile</CODE> and <CODE>lua_dobuffer</CODE> are both able to execute pre-compiled chunks. They automatically detect whether the chunk is text or binary, and load it accordingly (see program <A NAME="luac"><TT><A HREF="luac.html">luac</A></TT></A>). -Function <CODE>lua_dostring</CODE> executes only source code. +<CODE>lua_dostring</CODE> executes only source code, +given in textual form. <P> -The third parameter to <CODE>lua_dobuffer</CODE> (<CODE>name</CODE>) +The third parameter to <CODE>lua_dobuffer</CODE> is the ``name of the chunk'', -used in error messages and debug information. +which is used in error messages and debug information. If <CODE>name</CODE> is <CODE>NULL</CODE>, -Lua gives a default name to the chunk. +then Lua gives a default name to the chunk. +<P> +These functions push onto the stack +any values eventually returned by the chunk. +A chunk may return any number of values; +Lua takes care that these values fit into the stack space, +but after the call the responsibility is back to you. +If you need to push other elements after calling any of these functions, +and you want to ``play safe'', +you must either check the stack space +with <CODE>lua_stackspace</CODE> +or remove the returned elements +from the stack (if you do not need them). +For instance, the following code +loads a chunk in a file and discards all results returned by this chunk, +leaving the stack as it was before the call: +<PRE> + { + int oldtop = lua_gettop(L); + lua_dofile(L, filename); + lua_settop(L, oldtop); + } +</PRE> <P> -These functions return, in structure lua2C, -any values eventually returned by the chunks. -They also empty the stack C2lua. <P> +<A NAME="5.9"></A> +<H2>5.9 - Manipulating Global Variables in Lua</H2> <P> -<A NAME="5.5"></A> -<H2>5.5 - Manipulating Lua Objects</H2> -To read the value of any global Lua variable, -one uses the function: +To read the value of a global Lua variable, +you call <A NAME="lua_getglobal"></A> <PRE> -lua_Object lua_getglobal (char *varname); + void lua_getglobal (lua_State *L, const char *varname); </PRE> -As in Lua, this function may trigger a tag method. -To read the real value of any global variable, +which pushes onto the stack the value of the given variable. +As in Lua, this function may trigger a tag method +for the ``getglobal'' event (see Section <A HREF="#tag-method">4.8</A>). +To read the real value of a global variable, without invoking any tag method, -use the <EM>raw</EM> version: -<A NAME="lua_rawgetglobal"></A> -<PRE> -lua_Object lua_rawgetglobal (char *varname); -</PRE> +use <CODE>lua_rawget</CODE> over the table of globals +(see below). <P> -To store a value previously pushed onto C2lua in a global variable, -there is the function: +To store a value in a global variable, +you call <A NAME="lua_setglobal"></A> <PRE> -void lua_setglobal (char *varname); + void lua_setglobal (lua_State *L, const char *varname); </PRE> -As in Lua, this function may trigger a tag method. -To set the real value of any global variable, +which pops from the stack the value to be stored in the given variable. +As in Lua, this function may trigger a tag method +for the ``setglobal'' event (see Section <A HREF="#tag-method">4.8</A>). +To set the real value of a global variable, without invoking any tag method, -use the <EM>raw</EM> version: -<A NAME="lua_rawgetglobal"></A> +use <CODE>lua_rawset</CODE> over the table of globals +(see below). +<P> +All global variables are kept in an ordinary Lua table. +You can get this table calling +<A NAME="lua_getglobals"></A> <PRE> -void lua_rawsetglobal (char *varname); + void lua_getglobals (lua_State *L); </PRE> +which pushes the current table of globals onto the stack. +To set another table as the table of globals, +you call +<A NAME="lua_setglobals"></A> +<PRE> + void lua_setglobals (lua_State *L); +</PRE> +The table to be used is popped from the stack. +<P> +<A NAME="5.10"></A> +<H2>5.10 - Manipulating Tables in Lua</H2> +Lua tables can also be manipulated through the API. <P> -Tables can also be manipulated via the API. -The function +To read the value of in a table, +the table must reside somewhere in the stack. +With this set, +you call <A NAME="lua_gettable"></A> <PRE> -lua_Object lua_gettable (void); + void lua_gettable (lua_State *L, int index); </PRE> -pops a table and an index from the stack C2lua, -and returns the contents of the table at that index. -As in Lua, this operation may trigger a tag method. -To get the real value of any table index, +where <CODE>index</CODE> refers to the table. +<CODE>lua_gettable</CODE> pops a key from the stack, +and returns (on the stack) the contents of the table at that key. +As in Lua, this operation may trigger a tag method +for the ``gettable'' event. +To get the real value of any table key, without invoking any tag method, use the <EM>raw</EM> version: -<A NAME="lua_rawgetglobal"></A> +<A NAME="lua_rawget"></A> <PRE> -lua_Object lua_rawgettable (void); + void lua_rawget (lua_State *L, int index); </PRE> <P> -To store a value in an index, -the program must push the table, the index, -and the value onto C2lua, -and then call the function +To store a value into a table that resides somewhere in the stack, +you push the key and the value onto the stack +(in this order), +and then call <A NAME="lua_settable"></A> <PRE> -void lua_settable (void); + void lua_settable (lua_State *L, int index); </PRE> -Again, the tag method for ``settable'' may be called. +where <CODE>index</CODE> refers to the table. +<CODE>lua_settable</CODE> pops from the stack both the key and the value. +As in Lua, this operation may trigger a tag method +for the ``settable'' event. To set the real value of any table index, without invoking any tag method, use the <EM>raw</EM> version: -<A NAME="lua_rawsettable"></A> +<A NAME="lua_rawset"></A> <PRE> -void lua_rawsettable (void); + void lua_rawset (lua_State *L, int index); </PRE> <P> Finally, the function -<A NAME="lua_createtable"></A> +<A NAME="lua_newtable"></A> <PRE> -lua_Object lua_createtable (void); + void lua_newtable (lua_State *L); </PRE> -creates and returns a new, empty table. +creates a new, empty table and pushes it onto the stack. <P> +<A NAME="5.11"></A> +<H2>5.11 - Using Tables as Arrays</H2> +The API has functions that help to use Lua tables as arrays, +that is, +tables indexed by numbers only: +<A NAME="lua_rawgeti"></A> +<A NAME="lua_rawseti"></A> +<A NAME="lua_getn"></A> +<PRE> + void lua_rawgeti (lua_State *L, int index, int n); + void lua_rawseti (lua_State *L, int index, int n); + int lua_getn (lua_State *L, int index); +</PRE> <P> -<A NAME="5.6"></A> -<H2>5.6 - Calling Lua Functions</H2> -Functions defined in Lua by a chunk +<CODE>lua_rawgeti</CODE> gets the value of the <EM>n</EM>-th element of the table +at stack position <CODE>index</CODE>. +<P> +<CODE>lua_rawseti</CODE> sets the value of the <EM>n</EM>-th element of the table +at stack position <CODE>index</CODE> to the value at the top of the stack. +<P> +<CODE>lua_getn</CODE> returns the number of elements in the table +at stack position <CODE>index</CODE>. +This number is the value of the table field <CODE>n</CODE>, +if it has a numeric value, +or +the largest numerical index with a non-nil value in the table. +<P> +<A NAME="5.12"></A> +<H2>5.12 - Calling Lua Functions</H2> +<P> +Functions defined in Lua +(and C functions registered in Lua) can be called from the host program. This is done using the following protocol: -first, the arguments to the function are pushed onto C2lua -(see Section <A HREF="#pushing">5.3</A>), in direct order, i.e., the first argument is pushed first. -Then, the function is called using -<A NAME="lua_callfunction"></A> -<PRE> -int lua_callfunction (lua_Object function); -</PRE> -This function returns an error code: -0, in case of success; non zero, in case of errors. -Finally, the results (a Lua function may return many values) -are returned in structure lua2C, -and can be retrieved with the macro <CODE>lua_getresult</CODE>, -<A NAME="lua_getresult"></A> -which is just another name to function <CODE>lua_lua2C</CODE>. -Note that function <CODE>lua_callfunction</CODE> -pops all elements from the C2lua stack. -<P> -The following example shows how a C program may do the +First, the function to be called is pushed onto the stack; +then, the arguments to the function are pushed +(see Section <A HREF="#pushing">5.5</A>) in <EM>direct order</EM>, that is, the first argument is pushed first. +Finally, the function is called using +<A NAME="lua_call"></A> +<PRE> + int lua_call (lua_State *L, int nargs, int nresults); +</PRE> +This function returns the same error codes as <CODE>lua_dostring</CODE> and +friends (see Section <A HREF="#luado">5.8</A>). +If you want to propagate the error, +instead of returning an error code, +use +<A NAME="lua_rawcall"></A> +<PRE> + void lua_rawcall (lua_State *L, int nargs, int nresults); +</PRE> +<P> +In both functions, +<CODE>nargs</CODE> is the number of arguments that you pushed onto the stack. +All arguments and the function value are popped from the stack, +and the function results are pushed. +The number of results are adjusted (see Section <A HREF="#adjust">4.3</A>) to <CODE>nresults</CODE>, +unless <CODE>nresults</CODE> is <A NAME="LUA_MULTRET"><TT>LUA_MULTRET</TT></A>. +In that case, <EM>all</EM> results from the function are pushed. +The function results are pushed in direct order +(the first result is pushed first), +so that after the call the last result is on the top. +<P> +The following example shows how the host program may do the equivalent to the Lua code: <PRE> - a,b = f("how", t.x, 4) + a,b = f("how", t.x, 4) </PRE> +Here it is in C: <PRE> - lua_pushstring("how"); /* 1st argument */ - lua_pushobject(lua_getglobal("t")); /* push value of global 't' */ - lua_pushstring("x"); /* push the string 'x' */ - lua_pushobject(lua_gettable()); /* push result of t.x (2nd arg) */ - lua_pushnumber(4); /* 3rd argument */ - lua_callfunction(lua_getglobal("f")); /* call Lua function */ - lua_pushobject(lua_getresult(1)); /* push first result of the call */ - lua_setglobal("a"); /* set global variable 'a' */ - lua_pushobject(lua_getresult(2)); /* push second result of the call */ - lua_setglobal("b"); /* set global variable 'b' */ + lua_getglobal(L, "t"); /* global `t' (for later use) */ + lua_getglobal(L, "f"); /* function to be called */ + lua_pushstring(L, "how"); /* 1st argument */ + lua_pushstring(L, "x"); /* push the string `x' */ + lua_gettable(L, -4); /* push result of t.x (2nd arg) */ + lua_pushnumber(L, 4); /* 3rd argument */ + lua_call(L, 3, 2); /* call function with 3 arguments and 2 results */ + lua_setglobal(L, "b"); /* set global variable `b' */ + lua_setglobal(L, "a"); /* set global variable `a' */ + lua_pop(L, 1); /* remove `t' from the stack */ </PRE> +Notice that the code above is ``balanced'': +at its end ,the stack is back to its original configuration. +This is considered good programming practice. +<P> +<P> <P> -Some special Lua functions have exclusive interfaces. -A C function can generate a Lua error calling the function +Some special Lua functions have their own C interfaces. +The host program can generate a Lua error calling the function <A NAME="lua_error"></A> <PRE> -void lua_error (char *message); + void lua_error (lua_State *L, const char *message); </PRE> This function never returns. -If the C function has been called from Lua, +If <CODE>lua_error</CODE> is called from a C function that has been called from Lua, then the corresponding Lua execution terminates, as if an error had occurred inside Lua code. -Otherwise, the whole host program terminates with a call to <CODE>exit(1)</CODE>. -The <CODE>message</CODE> is passed to the error handler function, -<CODE>_ERRORMESSAGE</CODE>. +Otherwise, the whole host program terminates with a call to +<CODE>exit(EXIT_FAILURE)</CODE>. +Before terminating execution, +the <CODE>message</CODE> is passed to the error handler function, +<CODE>_ERRORMESSAGE</CODE> (see Section <A HREF="#error">4.7</A>). If <CODE>message</CODE> is <CODE>NULL</CODE>, then <CODE>_ERRORMESSAGE</CODE> is not called. <P> -Tag methods can be changed with: <A NAME="lua_settagmethod"></A> +<P> +Tag methods can be changed with <A NAME="lua_settagmethod"></A> <PRE> -lua_Object lua_settagmethod (int tag, char *event); + void lua_settagmethod (lua_State *L, int tag, const char *event); </PRE> -The first parameter is the tag, -and the second is the event name (see Section <A HREF="#tag-method">4.8</A>); -the new method is pushed from C2lua. -This function returns a <CODE>lua_Object</CODE>, -which is the old tag method value. -To get just the current value of a tag method, +The second parameter is the tag, +and the third is the event name (see Section <A HREF="#tag-method">4.8</A>); +the new method is popped from the stack. +To get the current value of a tag method, use the function <A NAME="lua_gettagmethod"></A> <PRE> -lua_Object lua_gettagmethod (int tag, char *event); + void lua_gettagmethod (lua_State *L, int tag, const char *event); </PRE> <P> It is also possible to copy all tag methods from one tag to another: <A NAME="lua_copytagmethods"></A> <PRE> -int lua_copytagmethods (int tagto, int tagfrom); + int lua_copytagmethods (lua_State *L, int tagto, int tagfrom); </PRE> This function returns <CODE>tagto</CODE>. <P> <P> +You can traverse a table with the function <A NAME="lua_next"></A> +<PRE> + int lua_next (lua_State *L, int index); +</PRE> +where <CODE>index</CODE> refers to the table to be traversed. +The function pops a key from the stack, +and pushes a key-value pair from the table +(the ``next'' pair after the given key). +If there are no more elements, then the function returns 0 +(and pushes nothing). +A typical traversal looks like this: +<PRE> + /* table is in the stack at index `t' */ + lua_pushnil(L); /* first key */ + while (lua_next(L, t) != 0) { + /* `key' is at index -2 and `value' at index -1 */ + printf("%s - %s\n", + lua_typename(L, lua_type(L, -2)), lua_typename(L, lua_type(L, -1))); + lua_pop(L, 1); /* removes `value'; keeps `index' for next iteration */ + } +</PRE> +<P> +The function <A NAME="lua_concat"></A> +<PRE> + void lua_concat (lua_State *L, int n); +</PRE> +concatenates the <CODE>n</CODE> values at the top of the stack, +pops them, and leaves the result at the top; +<CODE>n</CODE> must be at least 2. +Concatenation is done following the usual semantics of Lua +(see Section <A HREF="#concat">4.5.5</A>). +<P> +<P> <A NAME="LuacallC"></A> -<A NAME="5.7"></A> -<H2>5.7 - C Functions</H2> -To register a C function to Lua, -there is the following macro: +<A NAME="5.13"></A> +<H2>5.13 - Defining C Functions</H2> +To register a C function to Lua, +there is the following convenience macro: <A NAME="lua_register"></A> <PRE> -#define lua_register(n,f) (lua_pushcfunction(f), lua_setglobal(n)) -/* char *n; */ -/* lua_CFunction f; */ + #define lua_register(L, n, f) (lua_pushcfunction(L, f), lua_setglobal(L, n)) + /* const char *n; */ + /* lua_CFunction f; */ </PRE> which receives the name the function will have in Lua, and a pointer to the function. @@ -1693,110 +2119,185 @@ This pointer must have type <CODE>lua_CFunction</CODE>, which is defined as <A NAME="lua_CFunction"></A> <PRE> -typedef void (*lua_CFunction) (void); + typedef int (*lua_CFunction) (lua_State *L); </PRE> -that is, a pointer to a function with no parameters and no results. +that is, a pointer to a function with integer result and a single argument, +a Lua environment. <P> In order to communicate properly with Lua, -a C function must follow a protocol, -which defines the way parameters and results are passed. -<P> -A C function receives its arguments in structure lua2C; -to access them, it uses the macro <CODE>lua_getparam</CODE>, <A NAME="lua_getparam"></A> -again just another name for <CODE>lua_lua2C</CODE>. -To return values, a C function just pushes them onto the stack C2lua, -in direct order (see Section <A HREF="#valuesCLua">5.2</A>). -Like a Lua function, a C function called by Lua can also return +a C function must follow the following protocol, +which defines the way parameters and results are passed: +A C function receives its arguments from Lua in the stack, +in direct order (the first argument is pushed first). +To return values to Lua, a C function just pushes them onto the stack, +in direct order (the first result is pushed first), +and returns the number of results. +Like a Lua function, a C function called by Lua can also return many results. <P> -When a C function is created, -it is possible to associate some <EM>upvalues</EM> to it, -thus creating a C closure; -then these values are passed to the function whenever it is called, -as common arguments. -To associate upvalues to a function, -first these values must be pushed on C2lua. -Then the function -<A NAME="lua_pushcclosure"></A> -<PRE> -void lua_pushcclosure (lua_CFunction fn, int n); -</PRE> -is used to put the C function on C2lua, -with the argument <CODE>n</CODE> telling how many upvalues must be -associated with the function; +As an example, the following function receives a variable number +of numerical arguments and returns their average and sum: +<PRE> + static int foo (lua_State *L) { + int n = lua_gettop(L); /* number of arguments */ + double sum = 0; + int i; + for (i = 1; i <= n; i++) { + if (!lua_isnumber(L, i)) + lua_error(L, "incorrect argument to function `average'"); + sum += lua_tonumber(L, i); + } + lua_pushnumber(L, sum/n); /* first result */ + lua_pushnumber(L, sum); /* second result */ + return 2; /* number of results */ + } +</PRE> +This function may be registered in Lua as `<CODE>average</CODE>' by calling +<PRE> + lua_register(L, "average", foo); +</PRE> +<P> +<P> +When a C function is created, +it is possible to associate some <EM>upvalues</EM> to it +(see Section <A HREF="#upvalue">4.6</A>), +thus creating a <A NAME="C closure"><EM>C closure</EM></A>; +these values are passed to the function whenever it is called, +as ordinary arguments. +To associate upvalues to a C function, +first these values should be pushed onto the stack. +Then the function <A NAME="lua_pushcclosure"></A> +<PRE> + void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); +</PRE> +is used to push the C function onto the stack, +with the argument <CODE>n</CODE> telling how many upvalues should be +associated with the function +(these upvalues are popped from the stack); in fact, the macro <CODE>lua_pushcfunction</CODE> is defined as <CODE>lua_pushcclosure</CODE> with <CODE>n</CODE> set to 0. -Then, any time the function is called, -these upvalues are inserted as the first arguments to the function, -before the actual arguments provided in the call. -<P> -For some examples of C functions, see files <CODE>lstrlib.c</CODE>, -<CODE>liolib.c</CODE> and <CODE>lmathlib.c</CODE> in the official Lua distribution. -<P> -<A NAME="5.8"></A> -<H2>5.8 - References to Lua Objects</H2> -<P> -As noted in Section <A HREF="#GC">5.3</A>, <CODE>lua_Object</CODE>s are volatile. -If the C code needs to keep a <CODE>lua_Object</CODE> -outside block boundaries, -then it must create a <A NAME="reference"><EM>reference</EM></A> to the object. -The routines to manipulate references are the following: +Then, whenever the C function is called, +these upvalues are inserted as the <EM>last</EM> arguments to the function, +after the actual arguments provided in the call. +This makes it easy to get the upvalues without knowing how many arguments +the function received (recall that functions in Lua can receive any number of +arguments): The <EM>i</EM>-th upvalue is in the stack at index <I>i-(n+1)</I>, +where <EM>n</EM> is the number of upvalues. +<P> +For more examples of C functions and closures, see files +<CODE>lbaselib.c</CODE>, <CODE>liolib.c</CODE>, <CODE>lmathlib.c</CODE>, and <CODE>lstrlib.c</CODE> +in the official Lua distribution. +<P> +<A NAME="5.14"></A> +<H2>5.14 - References to Lua Objects</H2> +<P> +If the C code needs to keep a Lua value +outside the life span of a C function, +then it must create a <A NAME="reference"><EM>reference</EM></A> to the value. +The functions to manipulate references are the following: <A NAME="lua_ref"></A><A NAME="lua_getref"></A> <A NAME="lua_unref"></A> <PRE> -int lua_ref (int lock); -lua_Object lua_getref (int ref); -void lua_unref (int ref); + int lua_ref (lua_State *L, int lock); + int lua_getref (lua_State *L, int ref); + void lua_unref (lua_State *L, int ref); </PRE> -The function <CODE>lua_ref</CODE> creates a reference -to the object that is on the top of the stack, +<P> +<CODE>lua_ref</CODE> pops a value from +the stack, creates a reference to it, and returns this reference. -If <CODE>lock</CODE> is true, the object is <EM>locked</EM>: +For a <B>nil</B> value, +the reference is always <CODE>LUA_REFNIL</CODE>.<A NAME="LUA_REFNIL"></A> +(<CODE>lua.h</CODE> also defines a constant <CODE>LUA_NOREF</CODE> <A NAME="LUA_NOREF"></A> +that +is different from any valid reference.) +If <CODE>lock</CODE> is not zero, then the object is <EM>locked</EM>: this means the object will not be garbage collected. -Note that an unlocked reference may be garbage collected. -Whenever the referenced object is needed, +<EM>Unlocked references may be garbage collected</EM>. +<P> +Whenever the referenced object is needed in C, a call to <CODE>lua_getref</CODE> -returns a handle to it; +pushes that object onto the stack; if the object has been collected, -<CODE>lua_getref</CODE> returns <CODE>LUA_NOOBJECT</CODE>. +<CODE>lua_getref</CODE> returns 0 (and does not push anything). <P> When a reference is no longer needed, -it can be released with a call to <CODE>lua_unref</CODE>. +it should be released with a call to <CODE>lua_unref</CODE>. +<P> +<P> +<h3>Registry</h3> <P> +When Lua starts, it registers a table at position +<A NAME="LUA_REFREGISTRY"><TT>LUA_REFREGISTRY</TT></A>. +It can be accessed through the macro<A NAME="lua_getregistry"></A> +<PRE> + #define lua_getregistry(L) lua_getref(L, LUA_REFREGISTRY) +</PRE> +This table can be used by C libraries as a general registry mechanism. +Any C library can store data into this table, +as long as it chooses a key different from other libraries. <P> <P> <!-- ====================================================================== --> <HR> <A NAME="6."></A> -<H1>6 - Predefined Functions and Libraries</H1> +<H1>6 - Standard Libraries</H1> <P> -The set of <A NAME="predefined functions">predefined functions</A> in Lua is small but powerful. -Most of them provide features that allow some degree of -<A NAME="reflexivity">reflexivity</A> in the language. -Some of these features cannot be simulated with the rest of the -language nor with the standard Lua API. -Others are just convenient interfaces to common API functions. -<P> -The libraries, on the other hand, provide useful routines +The standard libraries provide useful functions that are implemented directly through the standard API. Therefore, they are not necessary to the language, -and are provided as separate C modules. -Currently, there are three standard libraries: +and are provided as separate C modules. +Currently, Lua has the following standard libraries: <UL> +<LI>basic library; <LI>string manipulation; <LI>mathematical functions (sin, log, etc); <LI>input and output (plus some system facilities). </UL> To have access to these libraries, -the C host program must call the functions +the C host program must call the functions +<CODE>lua_baselibopen</CODE>, <CODE>lua_strlibopen</CODE>, <CODE>lua_mathlibopen</CODE>, -and <CODE>lua_iolibopen</CODE>, declared in <CODE>lualib.h</CODE>. -<A NAME="lua_strlibopen"></A><A NAME="lua_mathlibopen"></A><A NAME="lua_iolibopen"></A> -<P> +and <CODE>lua_iolibopen</CODE>, which are declared in <CODE>lualib.h</CODE>. +<A NAME="lua_baselibopen"></A> +<A NAME="lua_strlibopen"></A> +<A NAME="lua_mathlibopen"></A> +<A NAME="lua_iolibopen"></A> <P> <A NAME="predefined"></A> <A NAME="6.1"></A> -<H2>6.1 - Predefined Functions</H2> +<H2>6.1 - Basic Functions</H2> +<P> +The basic library provides some core functions to Lua. +Therefore, if you do not include this library in your application, +you should check carefully whether you need to provide some alternative +implementation for some facilities. +(For instance, +without function <CODE>_ERRORMESSAGE</CODE>, +Lua is unable to show error messages.) +<P> +<A NAME="alert"></A> +<h3> <TT>_ALERT (message)</TT></h3><A NAME="alert"></A> +Prints its only string argument to <A NAME="stderr"><TT>stderr</TT></A>. +All error messages in Lua are printed through the function stored +in the <CODE>_ALERT</CODE> global variable +(see Section <A HREF="#error">4.7</A>). +Therefore, a program may assign another function to this variable +to change the way such messages are shown +(for instance, for systems without <CODE>stderr</CODE>). +<P> +<h3> <TT>assert (v [, message])</TT></h3><A NAME="assert"></A> +Issues an <EM>``assertion failed!''</EM> error +when its argument <CODE>v</CODE> is <B>nil</B>. +This function is equivalent to the following Lua function: +<PRE> + function assert (v, m) + if not v then + m = m or "" + error("assertion failed! " .. m) + end + end +</PRE> <P> <h3> <TT>call (func, arg [, mode [, errhandler]])</TT></h3><A NAME="call"></A> <A NAME="pdf-call"></A> @@ -1805,29 +2306,13 @@ Calls function <CODE>func</CODE> with the arguments given by the table <CODE>arg</CODE>. The call is equivalent to <PRE> - func(arg[1], arg[2], ..., arg[n]) + func(arg[1], arg[2], ..., arg[n]) </PRE> where <CODE>n</CODE> is the result of <CODE>getn(arg)</CODE> (see Section <A HREF="#getn">6.1</A>). +All results from <CODE>func</CODE> are simply returned by <CODE>call</CODE>. <P> By default, -all results from <CODE>func</CODE> are just returned by the call. -If the string <CODE>mode</CODE> contains <CODE>"p"</CODE>, -the results are <EM>packed</EM> in a single table.<A NAME="packed results"></A> -That is, <CODE>call</CODE> returns just one table; -at index <CODE>n</CODE>, the table has the total number of results -from the call; -the first result is at index 1, etc. -For instance, the following calls produce the following results: -<PRE> -a = call(sin, {5}) --> a = 0.0871557 = sin(5) -a = call(max, {1,4,5; n=2}) --> a = 4 (only 1 and 4 are arguments) -a = call(max, {1,4,5; n=2}, "p") --> a = {4; n=1} -t = {x=1} -a = call(next, {t,nil;n=2}, "p") --> a={"x", 1; n=2} -</PRE> -<P> -By default, -if an error occurs during the function call, +if an error occurs during the call to <CODE>func</CODE>, the error is propagated. If the string <CODE>mode</CODE> contains <CODE>"x"</CODE>, then the call is <EM>protected</EM>.<A NAME="protected calls"></A> @@ -1836,96 +2321,168 @@ regardless of what happens during the call. Instead, it returns <B>nil</B> to signal the error (besides calling the appropriated error handler). <P> -If provided, -<CODE>errhandler</CODE> is temporarily set as the error function -<CODE>_ERRORMESSAGE</CODE>, while <CODE>func</CODE> runs. +If <CODE>errhandler</CODE> is provided, +the error function <CODE>_ERRORMESSAGE</CODE> is temporarily set to <CODE>errhandler</CODE>, +while <CODE>func</CODE> runs. In particular, if <CODE>errhandler</CODE> is <B>nil</B>, no error messages will be issued during the execution of the called function. <P> <h3> <TT>collectgarbage ([limit])</TT></h3><A NAME="collectgarbage"></A> -Forces a garbage collection cycle. -Returns the number of objects collected. -An optional argument, <CODE>limit</CODE>, is a number that -makes the next cycle occur only after that number of new -objects have been created. -If <CODE>limit</CODE> is absent or equal to 0, -Lua uses an adaptive algorithm to set this limit. -<CODE>collectgarbage</CODE> is equivalent to -the API function <CODE>lua_collectgarbage</CODE>. +<P> +Sets the garbage-collection threshold for the given limit +(in Kbytes), and checks it against the byte counter. +If the new threshold is smaller than the byte counter, +then Lua immediately runs the garbage collector (see Section <A HREF="#GC">5.6</A>). +If <CODE>limit</CODE> is absent, it defaults to zero +(thus forcing a garbage-collection cycle). +<P> +<h3> <TT>copytagmethods (tagto, tagfrom)</TT></h3> +<A NAME="copytagmethods"></A> +Copies all tag methods from one tag to another; +returns <CODE>tagto</CODE>. <P> <h3> <TT>dofile (filename)</TT></h3><A NAME="dofile"></A> Receives a file name, -opens the file, and executes the file contents as a Lua chunk, +opens the named file, and executes its contents as a Lua chunk, or as pre-compiled chunks. When called without arguments, <CODE>dofile</CODE> executes the contents of the standard input (<CODE>stdin</CODE>). If there is any error executing the file, then <CODE>dofile</CODE> returns <B>nil</B>. Otherwise, it returns the values returned by the chunk, -or a non <B>nil</B> value if the chunk returns no values. -It issues an error when called with a non string argument. -<CODE>dofile</CODE> is equivalent to the API function <CODE>lua_dofile</CODE>. +or a non-<B>nil</B> value if the chunk returns no values. +It issues an error when called with a non-string argument. <P> <h3> <TT>dostring (string [, chunkname])</TT></h3><A NAME="dostring"></A> Executes a given string as a Lua chunk. If there is any error executing the string, -<CODE>dostring</CODE> returns <B>nil</B>. +then <CODE>dostring</CODE> returns <B>nil</B>. Otherwise, it returns the values returned by the chunk, -or a non <B>nil</B> value if the chunk returns no values. -An optional second parameter (<CODE>chunkname</CODE>) +or a non-<B>nil</B> value if the chunk returns no values. +The optional parameter <CODE>chunkname</CODE> is the ``name of the chunk'', used in error messages and debug information. -<CODE>dostring</CODE> is equivalent to the API function <CODE>lua_dostring</CODE>. +<P> +<A NAME="pdf-error"></A> +<h3> <TT>error (message)</TT></h3><A NAME="error"></A> +Calls the error handler (see Section <A HREF="#error">4.7</A>) and then terminates +the last protected function called +(in C: <CODE>lua_dofile</CODE>, <CODE>lua_dostring</CODE>, +<CODE>lua_dobuffer</CODE>, or <CODE>lua_callfunction</CODE>; +in Lua: <CODE>dofile</CODE>, <CODE>dostring</CODE>, or <CODE>call</CODE> in protected mode). +If <CODE>message</CODE> is <B>nil</B>, then the error handler is not called. +Function <CODE>error</CODE> never returns. +<P> +<h3> <TT>foreach (table, func)</TT></h3><A NAME="foreach"></A> +Executes the given <CODE>func</CODE> over all elements of <CODE>table</CODE>. +For each element, the function is called with the index and +respective value as arguments. +If the function returns any non-<B>nil</B> value, +then the loop is broken, and this value is returned +as the final value of <CODE>foreach</CODE>. +This function could be defined in Lua: +<PRE> + function foreach (t, f) + for i, v in t do + local res = f(i, v) + if res then return res end + end + end +</PRE> +<P> +The behavior of <CODE>foreach</CODE> is <EM>undefined</EM> if you change +the table <CODE>t</CODE> during the traversal. +<P> +<P> +<h3> <TT>foreachi (table, func)</TT></h3><A NAME="foreachi"></A> +Executes the given <CODE>func</CODE> over the +numerical indices of <CODE>table</CODE>. +For each index, the function is called with the index and +respective value as arguments. +Indices are visited in sequential order, +from 1 to <CODE>n</CODE>, +where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>). +If the function returns any non-<B>nil</B> value, +then the loop is broken, and this value is returned +as the final value of <CODE>foreachi</CODE>. +This function could be defined in Lua: +<PRE> + function foreachi (t, f) + for i=1,getn(t) do + local res = f(i, t[i]) + if res then return res end + end + end +</PRE> +<P> +<P> +<h3> <TT>getglobal (name)</TT></h3><A NAME="getglobal"></A> +Gets the value of a global variable, +or calls a tag method for ``getglobal''. +Its full semantics is explained in Section <A HREF="#tag-method">4.8</A>. +The string <CODE>name</CODE> does not need to be a +syntactically valid variable name. +<P> +<A NAME="getn"></A> +<h3> <TT>getn (table)</TT></h3><A NAME="getn"></A> +Returns the ``size'' of a table, when seen as a list. +If the table has an <CODE>n</CODE> field with a numeric value, +this value is the ``size'' of the table. +Otherwise, the ``size'' is the largest numerical index with a non-nil +value in the table. +This function could be defined in Lua: +<PRE> + function getn (t) + if type(t.n) == "number" then return t.n end + local max = 0 + for i, _ in t do + if type(i) == "number" and i>max then max=i end + end + return max + end +</PRE> +<P> +<h3> <TT>gettagmethod (tag, event)</TT></h3> +<A NAME="gettagmethod"></A> +Returns the current tag method +for a given pair <EM>(tag, event)</EM>. +This function cannot be used to get a tag method for the ``gc'' event. +(Such tag methods can only be manipulated by C code.) +<P> +<h3> <TT>globals ([table])</TT></h3><A NAME="globals"></A> +Returns the current table of globals. +If the argument <CODE>table</CODE> is given, +then it also sets this table as the table of globals. <P> <A NAME="pdf-newtag"></A> <h3> <TT>newtag ()</TT></h3><A NAME="newtag"></A> Returns a new tag. -<CODE>newtag</CODE> is equivalent to the API function <CODE>lua_newtag</CODE>. <P> -<h3> <TT>next (table, index)</TT></h3><A NAME="next"></A> +<h3> <TT>next (table, [index])</TT></h3><A NAME="next"></A> Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. -It returns the next index of the table and the +<CODE>next</CODE> returns the next index of the table and the value associated with the index. When called with <B>nil</B> as its second argument, -the function returns the first index -of the table (and its associated value). +<CODE>next</CODE> returns the first index +of the table and its associated value. When called with the last index, or with <B>nil</B> in an empty table, -it returns <B>nil</B>. +<CODE>next</CODE> returns <B>nil</B>. +If the second argument is absent, then it is interpreted as <B>nil</B>. <P> Lua has no declaration of fields; semantically, there is no difference between a field not present in a table or a field with value <B>nil</B>. -Therefore, the function only considers fields with non <B>nil</B> values. +Therefore, <CODE>next</CODE> only considers fields with non-<B>nil</B> values. The order in which the indices are enumerated is not specified, <EM>even for numeric indices</EM> (to traverse a table in numeric order, -use a counter or the function <CODE>foreachi</CODE>). -If the table indices are modified in any way during a traversal, -the semantics of <CODE>next</CODE> is undefined. -<P> -This function cannot be written with the standard API. -<P> -<h3> <TT>nextvar (name)</TT></h3><A NAME="nextvar"></A> -This function is similar to the function <CODE>next</CODE>, -but iterates instead over the global variables. -Its single argument is the name of a global variable, -or <B>nil</B> to get a first name. -Similarly to <CODE>next</CODE>, it returns the name of another variable -and its value, -or <B>nil</B> if there are no more variables. -There can be no creation of new global variables during the traversal; -otherwise the semantics of <CODE>nextvar</CODE> is undefined. -<P> -This function cannot be written with the standard API. +use a numerical <B>for</B> or the function <CODE>foreachi</CODE>). <P> -<h3> <TT>tostring (e)</TT></h3><A NAME="tostring"></A> -Receives an argument of any type and -converts it to a string in a reasonable format. -For complete control on how numbers are converted, -use function <CODE>format</CODE>. +The behavior of <CODE>next</CODE> is <EM>undefined</EM> if you change +the table during the traversal. <P> <h3> <TT>print (e1, e2, ...)</TT></h3><A NAME="print"></A> Receives any number of arguments, @@ -1935,342 +2492,225 @@ but only as a quick way to show a value, for instance for debugging. See Section <A HREF="#libio">6.4</A> for functions for formatted output. <P> -<A NAME="alert"></A> -<h3> <TT>_ALERT (message)</TT></h3><A NAME="alert"></A> -Prints its only string argument to <A NAME="stderr"><TT>stderr</TT></A>. -All error messages in Lua are printed through this function. -Therefore, a program may redefine it -to change the way such messages are shown -(for instance, for systems without <CODE>stderr</CODE>). -<P> -<h3> <TT>tonumber (e [, base])</TT></h3><A NAME="tonumber"></A> -Receives one argument, -and tries to convert it to a number. -If the argument is already a number or a string convertible -to a number, then <CODE>tonumber</CODE> returns that number; -otherwise, it returns <B>nil</B>. -<P> -An optional argument specifies the base to interpret the numeral. -The base may be any integer between 2 and 36 inclusive. -In bases above 10, the letter `A' (either upper or lower case) -represents 10, `B' represents 11, and so forth, with `Z' representing 35. -<P> -In base 10 (the default), the number may have a decimal part, -as well as an optional exponent part (see Section <A HREF="#coercion">4.3</A>). -In other bases, only integers are accepted. -<P> -<A NAME="pdf-type"></A> -<h3> <TT>type (v)</TT></h3><A NAME="type"></A> -Allows Lua to test the type of a value. -It receives one argument, and returns its type, coded as a string. -The possible results of this function are -<CODE>"nil"</CODE> (a string, not the value <B>nil</B>), -<CODE>"number"</CODE>, -<CODE>"string"</CODE>, -<CODE>"table"</CODE>, -<CODE>"function"</CODE>, -and <CODE>"userdata"</CODE>. -<P> -<h3> <TT>tag (v)</TT></h3><A NAME="tag"></A> -Allows Lua to test the tag of a value (see Section <A HREF="#TypesSec">3</A>). -It receives one argument, and returns its tag (a number). -<CODE>tag</CODE> is equivalent to the API function <CODE>lua_tag</CODE>. -<P> -<h3> <TT>settag (t, tag)</TT></h3><A NAME="settag"></A> -Sets the tag of a given table (see Section <A HREF="#TypesSec">3</A>). -<CODE>tag</CODE> must be a value created with <CODE>newtag</CODE> -(see Section <A HREF="#pdf-newtag">6.1</A>). -It returns the value of its first argument (the table). -For security reasons, -it is impossible to change the tag of a userdata from Lua. -<P> -<P> -<h3> <TT>assert (v [, message])</TT></h3><A NAME="assert"></A> -Issues an <EM>``assertion failed!''</EM> error -when its argument is <B>nil</B>. -This function is equivalent to the following Lua function: -<PRE> - function assert (v, m) - if not v then - m = m or "" - error("assertion failed! " .. m) - end - end -</PRE> -<P> -<A NAME="pdf-error"></A> -<h3> <TT>error (message)</TT></h3><A NAME="error"></A> -Calls the error handler and then terminates -the last protected function called -(in C: <CODE>lua_dofile</CODE>, <CODE>lua_dostring</CODE>, -<CODE>lua_dobuffer</CODE>, or <CODE>lua_callfunction</CODE>; -in Lua: <CODE>dofile</CODE>, <CODE>dostring</CODE>, or <CODE>call</CODE> in protected mode). -If <CODE>message</CODE> is <B>nil</B>, the error handler is not called. -Function <CODE>error</CODE> never returns. -<CODE>error</CODE> is equivalent to the API function <CODE>lua_error</CODE>. -<P> -<h3> <TT>rawgettable (table, index)</TT></h3><A NAME="rawgettable"></A> +<h3> <TT>rawget (table, index)</TT></h3><A NAME="rawget"></A> Gets the real value of <CODE>table[index]</CODE>, without invoking any tag method. <CODE>table</CODE> must be a table, and <CODE>index</CODE> is any value different from <B>nil</B>. <P> -<h3> <TT>rawsettable (table, index, value)</TT></h3><A NAME="rawsettable"></A> +<h3> <TT>rawset (table, index, value)</TT></h3><A NAME="rawset"></A> Sets the real value of <CODE>table[index]</CODE> to <CODE>value</CODE>, without invoking any tag method. <CODE>table</CODE> must be a table, <CODE>index</CODE> is any value different from <B>nil</B>, and <CODE>value</CODE> is any Lua value. <P> -<h3> <TT>rawsetglobal (name, value)</TT></h3><A NAME="rawsetglobal"></A> -Assigns the given value to a global variable. -The string <CODE>name</CODE> does not need to be a -syntactically valid variable name. -Therefore, -this function can set global variables with strange names like -<CODE>"m v 1"</CODE> or <CODE>34</CODE>. -Function <CODE>rawsetglobal</CODE> returns the value of its second argument. -<P> <h3> <TT>setglobal (name, value)</TT></h3><A NAME="setglobal"></A> -Assigns the given value to a global variable, -or calls a tag method. +Sets the named global variable to the given value, +or calls a tag method for ``setglobal''. Its full semantics is explained in Section <A HREF="#tag-method">4.8</A>. The string <CODE>name</CODE> does not need to be a syntactically valid variable name. -Function <CODE>setglobal</CODE> returns the value of its second argument. <P> -<h3> <TT>rawgetglobal (name)</TT></h3><A NAME="rawgetglobal"></A> -Retrieves the value of a global variable. -The string <CODE>name</CODE> does not need to be a -syntactically valid variable name. -<P> -<h3> <TT>getglobal (name)</TT></h3><A NAME="getglobal"></A> -Retrieves the value of a global variable, -or calls a tag method. -Its full semantics is explained in Section <A HREF="#tag-method">4.8</A>. -The string <CODE>name</CODE> does not need to be a -syntactically valid variable name. +<h3> <TT>settag (t, tag)</TT></h3><A NAME="settag"></A> +Sets the tag of a given table (see Section <A HREF="#TypesSec">3</A>). +<CODE>tag</CODE> must be a value created with <CODE>newtag</CODE> +(see Section <A HREF="#pdf-newtag">6.1</A>). +<CODE>settag</CODE> returns the value of its first argument (the table). +For the safety of host programs, +it is impossible to change the tag of a userdata from Lua. <P> <h3> <TT>settagmethod (tag, event, newmethod)</TT></h3> <A NAME="settagmethod"></A> -Sets a new tag method to the given pair <EM>(tag, event)</EM>. -It returns the old method. +Sets a new tag method to the given pair <EM>(tag, event)</EM> and +returns the old method. If <CODE>newmethod</CODE> is <B>nil</B>, -<CODE>settagmethod</CODE> restores the default behavior for the given event. -<P> -<h3> <TT>gettagmethod (tag, event)</TT></h3> -<A NAME="gettagmethod"></A> -Returns the current tag method -for a given pair <EM>(tag, event)</EM>. -<P> -<h3> <TT>copytagmethods (tagto, tagfrom)</TT></h3> -<A NAME="copytagmethods"></A> -Copies all tag methods from one tag to another; -it returns <CODE>tagto</CODE>. -<P> -<A NAME="getn"></A> -<h3> <TT>getn (table)</TT></h3><A NAME="getn"></A> -Returns the ``size'' of a table, when seen as a list. -If the table has an <CODE>n</CODE> field with a numeric value, -this is its ``size''. -Otherwise, the size is the largest numerical index with a non-nil -value in the table. -This function could be defined in Lua: -<PRE> - function getn (t) - if type(t.n) == 'number' then return t.n end - local max = 0 - local i = next(t, nil) - while i do - if type(i) == 'number' and i>max then max=i end - i = next(t, i) - end - return max - end -</PRE> +then <CODE>settagmethod</CODE> restores the default behavior for the given event. +This function cannot be used to set a tag method for the ``gc'' event. +(Such tag methods can only be manipulated by C code.) <P> +<h3> <TT>sort (table [, comp])</TT></h3><A NAME="sort"></A> +Sorts table elements in a given order, <EM>in-place</EM>, +from <CODE>table[1]</CODE> to <CODE>table[n]</CODE>, +where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>). +If <CODE>comp</CODE> is given, +then it must be a function that receives two table elements, +and returns true (that is, a value different from <B>nil</B>) +when the first is less than the second +(so that <CODE>not comp(a[i+1], a[i])</CODE> will be true after the sort). +If <CODE>comp</CODE> is not given, +then the standard Lua operator <CODE><</CODE> is used instead. <P> -<h3> <TT>foreach (table, function)</TT></h3><A NAME="foreach"></A> -Executes the given <CODE>function</CODE> over all elements of <CODE>table</CODE>. -For each element, the function is called with the index and -respective value as arguments. -If the function returns any non-<B>nil</B> value, -the loop is broken, and the value is returned -as the final value of <CODE>foreach</CODE>. +The sort algorithm is <EM>not</EM> stable +(that is, elements considered equal by the given order +may have their relative positions changed by the sort). <P> -This function could be defined in Lua: -<PRE> - function foreach (t, f) - local i, v = next(t, nil) - while i do - local res = f(i, v) - if res then return res end - i, v = next(t, i) - end - end -</PRE> +<A NAME="pdf-tag"></A> +<h3> <TT>tag (v)</TT></h3><A NAME="tag"></A> +Allows Lua programs to test the tag of a value (see Section <A HREF="#TypesSec">3</A>). +It receives one argument, and returns its tag (a number). <P> +<h3> <TT>tonumber (e [, base])</TT></h3><A NAME="tonumber"></A> +Tries to convert its argument to a number. +If the argument is already a number or a string convertible +to a number, then <CODE>tonumber</CODE> returns that number; +otherwise, it returns <B>nil</B>. <P> -<h3> <TT>foreachi (table, function)</TT></h3><A NAME="foreachi"></A> -Executes the given <CODE>function</CODE> over the -numerical indices of <CODE>table</CODE>. -For each index, the function is called with the index and -respective value as arguments. -Indices are visited in sequential order, -from 1 to <CODE>n</CODE>, -where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>). -If the function returns any non-<B>nil</B> value, -the loop is broken, and the value is returned -as the final value of <CODE>foreachi</CODE>. +An optional argument specifies the base to interpret the numeral. +The base may be any integer between 2 and 36, inclusive. +In bases above 10, the letter `A' (either upper or lower case) +represents 10, `B' represents 11, and so forth, with `Z' representing 35. +In base 10 (the default), the number may have a decimal part, +as well as an optional exponent part (see Section <A HREF="#coercion">4.2</A>). +In other bases, only unsigned integers are accepted. <P> -This function could be defined in Lua: -<PRE> - function foreachi (t, f) - local i, n = 1, getn(t) - while i <= n do - local res = f(i, t[i]) - if res then return res end - i = i+1 - end - end -</PRE> +<h3> <TT>tostring (e)</TT></h3><A NAME="tostring"></A> +Receives an argument of any type and +converts it to a string in a reasonable format. +For complete control of how numbers are converted, +use function <CODE>format</CODE>. <P> -<h3> <TT>foreachvar (function)</TT></h3><A NAME="foreachvar"></A> -Executes <CODE>function</CODE> over all global variables. -For each variable, -the function is called with its name and its value as arguments. -If the function returns any non-nil value, -the loop is broken, and the value is returned -as the final value of <CODE>foreachvar</CODE>. <P> -This function could be defined in Lua: -<PRE> - function foreachvar (f) - local n, v = nextvar(nil) - while n do - local res = f(n, v) - if res then return res end - n, v = nextvar(n) - end - end -</PRE> <P> <h3> <TT>tinsert (table [, pos] , value)</TT></h3><A NAME="tinsert"></A> <P> Inserts element <CODE>value</CODE> at table position <CODE>pos</CODE>, -shifting other elements to open space. -The default value for <CODE>pos</CODE> is <CODE>n+1</CODE> -(where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>)) +shifting other elements to open space, if necessary. +The default value for <CODE>pos</CODE> is <CODE>n+1</CODE>, +where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>), so that a call <CODE>tinsert(t,x)</CODE> inserts <CODE>x</CODE> at the end of table <CODE>t</CODE>. -<P> -This function also sets or increments the field <CODE>n</CODE> of the table, +This function also sets or increments the field <CODE>n</CODE> of the table to <CODE>n+1</CODE>. -<P> This function is equivalent to the following Lua function, -except that the table accesses are all raw (that is, without tag methods): -<PRE> - function tinsert (t, ...) - local pos, value - local n = getn(t) - if arg.n == 1 then - pos = n+1; value = arg[1] - else - pos = arg[1]; value = arg[2] - end - t.n = n+1; - while n >= pos do - t[n+1] = t[n] - n = n-1 - end - t[pos] = value - end +except that the table accesses are all <EM>raw</EM> +(that is, without tag methods): +<PRE> + function tinsert (t, ...) + local pos, value + local n = getn(t) + if arg.n == 1 then + pos, value = n+1, arg[1] + else + pos, value = arg[1], arg[2] + end + t.n = n+1; + for i=n,pos,-1 do + t[i+1] = t[i] + end + t[pos] = value + end </PRE> <P> <h3> <TT>tremove (table [, pos])</TT></h3><A NAME="tremove"></A> <P> Removes from <CODE>table</CODE> the element at position <CODE>pos</CODE>, -shifting other elements to close the space. +shifting other elements to close the space, if necessary. Returns the value of the removed element. -The default value for <CODE>pos</CODE> is <CODE>n</CODE> -(where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>)), +The default value for <CODE>pos</CODE> is <CODE>n</CODE>, +where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>), so that a call <CODE>tremove(t)</CODE> removes the last element of table <CODE>t</CODE>. -<P> -This function also sets or decrements the field <CODE>n</CODE> of the table, +This function also sets or decrements the field <CODE>n</CODE> of the table to <CODE>n-1</CODE>. <P> This function is equivalent to the following Lua function, -except that the table accesses are all raw (that is, without tag methods): -<PRE> - function tremove (t, pos) - local n = getn(t) - pos = pos or n - local value = t[pos] - if n<=0 then return end - while pos < n do - t[pos] = t[pos+1] - pos = pos+1 - end - t[n] = nil - t.n = n-1 - return value - end +except that the table accesses are all <EM>raw</EM> +(that is, without tag methods): +<PRE> + function tremove (t, pos) + local n = getn(t) + if n<=0 then return end + pos = pos or n + local value = t[pos] + for i=pos,n-1 do + t[i] = t[i+1] + end + t[n] = nil + t.n = n-1 + return value + end </PRE> <P> -<h3> <TT>sort (table [, comp])</TT></h3><A NAME="sort"></A> -Sorts table elements in a given order, <EM>in-place</EM>, -from <CODE>table[1]</CODE> to <CODE>table[n]</CODE>, -where <CODE>n</CODE> is the result of <CODE>getn(table)</CODE> (see Section <A HREF="#getn">6.1</A>). -If <CODE>comp</CODE> is given, -it must be a function that receives two table elements, -and returns true when the first is less than the second -(so that <CODE>not comp(a[i+1], a[i])</CODE> will be true after the sort). -If <CODE>comp</CODE> is not given, -the standard <CODE><</CODE> Lua operator is used instead. -<P> -Function <CODE>sort</CODE> returns the (sorted) table. +<A NAME="pdf-type"></A> +<h3> <TT>type (v)</TT></h3><A NAME="type"></A> +Allows Lua programs to test the type of a value. +It receives one argument, and returns its type, coded as a string. +The possible results of this function are +<CODE>"nil"</CODE> (a string, not the value <B>nil</B>), +<CODE>"number"</CODE>, +<CODE>"string"</CODE>, +<CODE>"table"</CODE>, +<CODE>"function"</CODE>, +and <CODE>"userdata"</CODE>. <P> <P> <A NAME="6.2"></A> <H2>6.2 - String Manipulation</H2> This library provides generic functions for string manipulation, such as finding and extracting substrings and pattern matching. -When indexing a string, the first character is at position 1 +When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). +Also, +indices are allowed to be negative and are intepreted as indexing backwards, +from the end of the string. Thus, the last character is at position <I>-1</I>, +and so on. <P> -<h3> <TT>strfind (str, pattern [, init [, plain]])</TT></h3> +<h3> <TT>strbyte (s [, i])</TT></h3><A NAME="strbyte"></A> +Returns the internal numerical code of the <EM>i</EM>-th character of <CODE>s</CODE>. +If <CODE>i</CODE> is absent, then it is assumed to be 1. +<CODE>i</CODE> may be negative. +<P> +Numerical codes are not necessarily portable across platforms. +<P> +<h3> <TT>strchar (i1, i2, ...)</TT></h3><A NAME="strchar"></A> +Receives 0 or more integers. +Returns a string with length equal to the number of arguments, +wherein each character has the internal numerical code equal +to its correspondent argument. +<P> +Numerical codes are not necessarily portable across platforms. +<P> +<h3> <TT>strfind (s, pattern [, init [, plain]])</TT></h3> <A NAME="strfind"></A> Looks for the first <EM>match</EM> of -<CODE>pattern</CODE> in <CODE>str</CODE>. -If it finds one, then it returns the indices on <CODE>str</CODE> +<CODE>pattern</CODE> in <CODE>s</CODE>. +If it finds one, then <CODE>strfind</CODE> returns the indices of <CODE>s</CODE> where this occurrence starts and ends; otherwise, it returns <B>nil</B>. -If the pattern specifies captures, +If the pattern specifies captures (see <CODE>gsub</CODE> below), the captured strings are returned as extra results. -A third optional numerical argument specifies where to start the search; -its default value is 1. -If <CODE>init</CODE> is negative, -it is replaced by the length of the string minus its -absolute value plus 1. -Therefore, <I>-1</I> points to the last character of <CODE>str</CODE>. -A value of 1 as a fourth optional argument +A third, optional numerical argument <CODE>init</CODE> specifies +where to start the search; +its default value is 1, and may be negative. +A value of 1 as a fourth, optional argument <CODE>plain</CODE> turns off the pattern matching facilities, so the function does a plain ``find substring'' operation, with no characters in <CODE>pattern</CODE> being considered ``magic''. +Note that if <CODE>plain</CODE> is given, then <CODE>init</CODE> must be given too. <P> <h3> <TT>strlen (s)</TT></h3><A NAME="strlen"></A> Receives a string and returns its length. +The empty string <CODE>""</CODE> has length 0. +Embedded zeros are counted, +and so <CODE>"a\000b\000c"</CODE> has length 5. +<P> +<h3> <TT>strlower (s)</TT></h3><A NAME="strlower"></A> +Receives a string and returns a copy of that string with all +upper case letters changed to lower case. +All other characters are left unchanged. +The definition of what is an upper-case +letter depends on the current locale. +<P> +<h3> <TT>strrep (s, n)</TT></h3><A NAME="strrep"></A> +Returns a string that is the concatenation of <CODE>n</CODE> copies of +the string <CODE>s</CODE>. <P> <h3> <TT>strsub (s, i [, j])</TT></h3><A NAME="strsub"></A> Returns another string, which is a substring of <CODE>s</CODE>, -starting at <CODE>i</CODE> and running until <CODE>j</CODE>. -If <CODE>i</CODE> or <CODE>j</CODE> are negative, -they are replaced by the length of the string minus their -absolute value plus 1. -Therefore, <I>-1</I> points to the last character of <CODE>s</CODE> -and <I>-2</I> to the previous one. -If <CODE>j</CODE> is absent, it is assumed to be equal to <I>-1</I> +starting at <CODE>i</CODE> and running until <CODE>j</CODE>; +<CODE>i</CODE> and <CODE>j</CODE> may be negative, +If <CODE>j</CODE> is absent, then it is assumed to be equal to <I>-1</I> (which is the same as the string length). In particular, the call <CODE>strsub(s,1,j)</CODE> returns a prefix of <CODE>s</CODE> @@ -2278,13 +2718,6 @@ with length <CODE>j</CODE>, and the call <CODE>strsub(s, -i)</CODE> returns a suffix of <CODE>s</CODE> with length <CODE>i</CODE>. <P> -<h3> <TT>strlower (s)</TT></h3><A NAME="strlower"></A> -Receives a string and returns a copy of that string with all -upper case letters changed to lower case. -All other characters are left unchanged. -The definition of what is an upper case -letter depends on the current locale. -<P> <h3> <TT>strupper (s)</TT></h3><A NAME="strupper"></A> Receives a string and returns a copy of that string with all lower case letters changed to upper case. @@ -2292,47 +2725,25 @@ All other characters are left unchanged. The definition of what is a lower case letter depends on the current locale. <P> -<h3> <TT>strrep (s, n)</TT></h3><A NAME="strrep"></A> -Returns a string that is the concatenation of <CODE>n</CODE> copies of -the string <CODE>s</CODE>. -<P> -<h3> <TT>strbyte (s [, i])</TT></h3><A NAME="strbyte"></A> -Returns the internal numerical code of the character <CODE>s[i]</CODE>. -If <CODE>i</CODE> is absent, then it is assumed to be 1. -If <CODE>i</CODE> is negative, -it is replaced by the length of the string minus its -absolute value plus 1. -Therefore, <I>-1</I> points to the last character of <CODE>s</CODE>. -<P> -Note that numerical codes are not necessarily portable across platforms. -<P> -<h3> <TT>strchar (i1, i2, ...)</TT></h3><A NAME="strchar"></A> -Receives 0 or more integers. -Returns a string with length equal to the number of arguments, -wherein each character has the internal numerical code equal -to its correspondent argument. -<P> -Note that numerical codes are not necessarily portable across platforms. -<P> <h3> <TT>format (formatstring, e1, e2, ...)</TT></h3><A NAME="format"></A> <A NAME="format"></A> Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the <CODE>printf</CODE> family of -standard C functions. +standard C functions. The only differences are that the options/modifiers <CODE>*</CODE>, <CODE>l</CODE>, <CODE>L</CODE>, <CODE>n</CODE>, <CODE>p</CODE>, and <CODE>h</CODE> are not supported, and there is an extra option, <CODE>q</CODE>. -This option formats a string in a form suitable to be safely read +The <CODE>q</CODE> option formats a string in a form suitable to be safely read back by the Lua interpreter: The string is written between double quotes, -and all double quotes, returns and backslashes in the string +and all double quotes, returns, and backslashes in the string are correctly escaped when written. For instance, the call <PRE> -format('%q', 'a string with "quotes" and \n new line') + format('%q', 'a string with "quotes" and \n new line') </PRE> will produce the string: <PRE> @@ -2340,7 +2751,7 @@ will produce the string: new line" </PRE> <P> -Conversions can be applied to the n-th argument in the argument list, +Conversions can be applied to the <EM>n</EM>-th argument in the argument list, rather than the next unused argument. In this case, the conversion character <CODE>%</CODE> is replaced by the sequence <CODE>%d$</CODE>, where <CODE>d</CODE> is a @@ -2359,20 +2770,22 @@ the appropriate format string. For example, <CODE>"%*g"</CODE> can be simulated with <CODE>"%"..width.."g"</CODE>. <P> -<EM>Note: function <TT>format</TT> can only be used with strings that do not contain zeros.</EM> +Neither the format string nor the string values to be formatted with +<CODE>%s</CODE> can contain embedded zeros. +<CODE>%q</CODE> handles string values with embedded zeros. <P> <h3> <TT>gsub (s, pat, repl [, n])</TT></h3> <A NAME="gsub"></A> -Returns a copy of <CODE>s</CODE>, -where all occurrences of the pattern <CODE>pat</CODE> have been +Returns a copy of <CODE>s</CODE> +in which all occurrences of the pattern <CODE>pat</CODE> have been replaced by a replacement string specified by <CODE>repl</CODE>. -This function also returns, as a second value, +<CODE>gsub</CODE> also returns, as a second value, the total number of substitutions made. <P> If <CODE>repl</CODE> is a string, then its value is used for replacement. Any sequence in <CODE>repl</CODE> of the form <CODE>%n</CODE> with <CODE>n</CODE> between 1 and 9 -stands for the value of the n-th captured substring. +stands for the value of the <EM>n</EM>-th captured substring. <P> If <CODE>repl</CODE> is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, @@ -2381,35 +2794,35 @@ If the value returned by this function is a string, then it is used as the replacement string; otherwise, the replacement string is the empty string. <P> -A last optional parameter <CODE>n</CODE> limits +The last, optional parameter <CODE>n</CODE> limits the maximum number of substitutions to occur. For instance, when <CODE>n</CODE> is 1 only the first occurrence of <CODE>pat</CODE> is replaced. <P> Here are some examples: <PRE> - x = gsub("hello world", "(%w+)", "%1 %1") - --> x="hello hello world world" + x = gsub("hello world", "(%w+)", "%1 %1") + --> x="hello hello world world" <P> - x = gsub("hello world", "(%w+)", "%1 %1", 1) - --> x="hello hello world" + x = gsub("hello world", "(%w+)", "%1 %1", 1) + --> x="hello hello world" <P> - x = gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") - --> x="world hello Lua from" + x = gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") + --> x="world hello Lua from" <P> - x = gsub("home = $HOME, user = $USER", "%$(%w+)", getenv) - --> x="home = /home/roberto, user = roberto" (for instance) + x = gsub("home = $HOME, user = $USER", "%$(%w+)", getenv) + --> x="home = /home/roberto, user = roberto" (for instance) <P> - x = gsub("4+5 = $return 4+5$", "%$(.-)%$", dostring) - --> x="4+5 = 9" + x = gsub("4+5 = $return 4+5$", "%$(.-)%$", dostring) + --> x="4+5 = 9" <P> - local t = {name="lua", version="3.2"} - x = gsub("$name - $version", "%$(%w+)", function (v) return %t[v] end) - --> x="lua - 3.2" + local t = {name="lua", version="4.0"} + x = gsub("$name - $version", "%$(%w+)", function (v) return %t[v] end) + --> x="lua - 4.0" <P> - t = {n=0} - gsub("first second word", "(%w+)", function (w) tinsert(%t, w) end) - --> t={"first", "second", "word"; n=3} + t = {n=0} + gsub("first second word", "(%w+)", function (w) tinsert(%t, w) end) + --> t={"first", "second", "word"; n=3} </PRE> <P> <P> @@ -2420,7 +2833,7 @@ Here are some examples: a <A NAME="character class"><EM>character class</EM></A> is used to represent a set of characters. The following combinations are allowed in describing a character class: <DL> -<DT><B><EM>x</EM></B><DD> (where <EM>x</EM> is any character not in the list +<DT><B><EM>x</EM></B><DD> (where <EM>x</EM> is any magic characters <CODE>^$()%.[]*+-?</CODE>) - represents the character <EM>x</EM> itself. <DT><B><TT>.</TT></B><DD> - (a dot) represents all characters. @@ -2432,37 +2845,44 @@ The following combinations are allowed in describing a character class: <DT><B><TT>%s</TT></B><DD> - represents all space characters. <DT><B><TT>%u</TT></B><DD> - represents all upper case letters. <DT><B><TT>%w</TT></B><DD> - represents all alphanumeric characters. -<DT><B><TT>%x</TT></B><DD> - represents all hexa-decimal digits. +<DT><B><TT>%x</TT></B><DD> - represents all hexadecimal digits. <DT><B><TT>%z</TT></B><DD> - represents the character with representation 0. -<DT><B><TT>%<EM>x</TT></EM></B><DD> (where <EM>x</EM> is any non alphanumeric character) - +<DT><B><TT>%<EM>x</TT></EM></B><DD> (where <EM>x</EM> is any non-alphanumeric character) - represents the character <EM>x</EM>. -This is the standard way to escape the magic characters <CODE>()%.[]*-?</CODE>. -It is strongly recommended that any control character (even the non magic), -when used to represent itself in a pattern, should be preceded by a <CODE>%</CODE>. +This is the standard way to escape the magic characters. +We recommend that any punctuation character (even the non magic) +should be preceded by a <CODE>%</CODE> +when used to represent itself in a pattern. +<P> <DT><B><TT>[char-set</TT></B>]<DD> - -Represents the class which is the union of all -characters in char-set. -To include a <CODE>]</CODE> in char-set, it must be the first character. +represents the class which is the union of all +characters in <CODE>char-set</CODE>. A range of characters may be specified by separating the end characters of the range with a <CODE>-</CODE>. -If <CODE>-</CODE> appears as the first or last character of char-set, -then it represents itself. -All classes <CODE>%</CODE><EM>x</EM> described above can also be used as +All classes <CODE>%</CODE><EM>x</EM> described above may also be used as components in a char-set. All other characters in char-set represent themselves. -E.g., assuming an <EM>ascii</EM> character set, -<CODE>[%dA-Fa-f]</CODE> specifies the hexa-decimal digits. +For example, <CODE>[%w_]</CODE> (or <CODE>[_%w]</CODE>) +represents all alphanumeric characters plus the underscore, +<CODE>[0-7]</CODE> represents the octal digits, +and <CODE>[0-7%l%-]</CODE> represents the octal digits plus +the lower case letters plus the <CODE>-</CODE> character. +<P> +The interaction between ranges and classes is not defined. +Therefore, patterns like <CODE>[%a-z]</CODE> or <CODE>[a-%%]</CODE> +have no meaning. +<P> <DT><B><TT>[^char-set</TT></B>]<DD> - -represents the complement of char-set, -where char-set is interpreted as above. +represents the complement of <CODE>char-set</CODE>, +where <CODE>char-set</CODE> is interpreted as above. </DL> For all classes represented by single letters (<CODE>%a</CODE>, <CODE>%c</CODE>, ...), -the correspondent upper-case letter represents the complement of the class. +the corresponding upper-case letter represents the complement of the class. For instance, <CODE>%S</CODE> represents all non-space characters. <P> The definitions of letter, space, etc. depend on the current locale. In particular, the class <CODE>[a-z]</CODE> may not be equivalent to <CODE>%l</CODE>. -The second form should be preferred for more portable programs. +The second form should be preferred for portability. <P> <H4>Pattern Item:</H4> a <A NAME="pattern item"><EM>pattern item</EM></A> may be @@ -2488,15 +2908,15 @@ a single character class followed by <CODE>?</CODE>, which matches 0 or 1 occurrence of a character in the class; <LI> <TT>%<EM>n</TT></EM>, for <EM>n</EM> between 1 and 9; -such item matches a sub-string equal to the n-th captured string +such item matches a sub-string equal to the <EM>n</EM>-th captured string (see below); <LI> <TT>%b<EM>xy</TT></EM>, where <EM>x</EM> and <EM>y</EM> are two distinct characters; -such item matches strings that start with <EM>x</EM>, end with <EM>y</EM>, +such item matches strings that start with <EM>x</EM>, end with <EM>y</EM>, and where the <EM>x</EM> and <EM>y</EM> are <EM>balanced</EM>. -That means that, if one reads the string from left to write, -counting plus 1 for an <EM>x</EM> and minus 1 for a <EM>y</EM>, -the ending <EM>y</EM> is the first where the count reaches 0. +This means that, if one reads the string from left to right, +counting <I>+1</I> for an <EM>x</EM> and <I>-1</I> for a <EM>y</EM>, +the ending <EM>y</EM> is the first <EM>y</EM> where the count reaches 0. For instance, the item <CODE>%b()</CODE> matches expressions with balanced parentheses. </UL> @@ -2507,10 +2927,12 @@ A <CODE>^</CODE> at the beginning of a pattern anchors the match at the beginning of the subject string. A <CODE>$</CODE> at the end of a pattern anchors the match at the end of the subject string. +At other positions, +<CODE>^</CODE> and <CODE>$</CODE> have no special meaning and represent themselves. <P> <H4>Captures:</H4> -a pattern may contain sub-patterns enclosed in parentheses, -that describe <A NAME="captures"><EM>captures</EM></A>. +A pattern may contain sub-patterns enclosed in parentheses, +they describe <A NAME="captures"><EM>captures</EM></A>. When a match succeeds, the sub-strings of the subject string that match captures are stored (<EM>captured</EM>) for future use. Captures are numbered according to their left parentheses. @@ -2520,43 +2942,44 @@ stored as the first capture (and therefore has number 1); the character matching <CODE>.</CODE> is captured with number 2, and the part matching <CODE>%s*</CODE> has number 3. <P> +A pattern cannot contain embedded zeros. Use <CODE>%z</CODE> instead. +<P> <P> <A NAME="mathlib"></A> <A NAME="6.3"></A> <H2>6.3 - Mathematical Functions</H2> <P> -This library is an interface to some functions of the standard C math library. +This library is an interface to some functions of the standard C math library. In addition, it registers a tag method for the binary operator <CODE>^</CODE> that returns <I>x^y</I> when applied to numbers <CODE>x^y</CODE>. <P> The library provides the following functions: <A NAME="abs"></A><A NAME="acos"></A><A NAME="asin"></A><A NAME="atan"></A> -<A NAME="atan2"></A><A NAME="ceil"></A><A NAME="cos"></A><A NAME="floor"></A> -<A NAME="log"></A><A NAME="log10"></A><A NAME="max"></A><A NAME="min"></A> -<A NAME="mod"></A><A NAME="sin"></A><A NAME="sqrt"></A><A NAME="tan"></A> -<A NAME="frexp"></A><A NAME="ldexp"></A> -<A NAME="random"></A><A NAME="randomseed"></A> +<A NAME="atan2"></A><A NAME="ceil"></A><A NAME="cos"></A><A NAME="def"></A><A NAME="exp"></A> +<A NAME="floor"></A><A NAME="log"></A><A NAME="log10"></A><A NAME="max"></A><A NAME="min"></A> +<A NAME="mod"></A><A NAME="rad"></A><A NAME="sin"></A><A NAME="sqrt"></A><A NAME="tan"></A> +<A NAME="frexp"></A><A NAME="ldexp"></A><A NAME="random"></A><A NAME="randomseed"></A> <PRE> -abs acos asin atan atan2 ceil cos deg floor log log10 -max min mod rad sin sqrt tan frexp ldexp -random randomseed + abs acos asin atan atan2 ceil cos deg exp floor log log10 + max min mod rad sin sqrt tan frexp ldexp random randomseed </PRE> plus a global variable <A NAME="PI"><TT>PI</TT></A>. Most of them -are only interfaces to the homonymous functions in the C library, +are only interfaces to the homonymous functions in the C library, except that, for the trigonometric functions, all angles are expressed in <EM>degrees</EM>, not radians. -Functions <A NAME="deg"><TT>deg</TT></A> and <A NAME="rad"><TT>rad</TT></A> can be used to convert +The functions <CODE>deg</CODE> and <CODE>rad</CODE> can be used to convert between radians and degrees. <P> The function <CODE>max</CODE> returns the maximum value of its numeric arguments. Similarly, <CODE>min</CODE> computes the minimum. -Both can be used with 1, 2 or more arguments. +Both can be used with 1, 2, or more arguments. <P> The functions <CODE>random</CODE> and <CODE>randomseed</CODE> are interfaces to the simple random generator functions <CODE>rand</CODE> and <CODE>srand</CODE>, provided by ANSI C. +(No guarantees can be given for their statistical properties.) The function <CODE>random</CODE>, when called without arguments, returns a pseudo-random real number in the range <I>[0,1)</I>. When called with a number <I>n</I>, @@ -2574,17 +2997,15 @@ over two <A NAME="file handles"><EM>file handles</EM></A>, one for reading and o These handles are stored in two Lua global variables, called <CODE>_INPUT</CODE> and <CODE>_OUTPUT</CODE>. The global variables -<CODE>_STDIN</CODE>, <CODE>_STDOUT</CODE> and <CODE>_STDERR</CODE> +<CODE>_STDIN</CODE>, <CODE>_STDOUT</CODE>, and <CODE>_STDERR</CODE> are initialized with file descriptors for -<CODE>stdin</CODE>, <CODE>stdout</CODE> and <CODE>stderr</CODE>. +<CODE>stdin</CODE>, <CODE>stdout</CODE>, and <CODE>stderr</CODE>. Initially, <CODE>_INPUT=_STDIN</CODE> and <CODE>_OUTPUT=_STDOUT</CODE>. <A NAME="_INPUT"></A><A NAME="_OUTPUT"></A> <A NAME="_STDIN"></A><A NAME="_STDOUT"></A><A NAME="_STDERR"></A> <P> -A file handle is a userdata containing the file stream <CODE>FILE*</CODE>, +A file handle is a userdata containing the file stream (<CODE>FILE*</CODE>), 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. <P> Unless otherwise stated, all I/O functions return <B>nil</B> on failure and @@ -2598,18 +3019,19 @@ It returns a new file handle, or, in case of errors, <B>nil</B> plus a string describing the error. This function does not modify either <CODE>_INPUT</CODE> or <CODE>_OUTPUT</CODE>. <P> -The string mode can be any of the following: +The <CODE>mode</CODE> string can be any of the following: <DL> -<DT><B>"r"</B><DD> read mode; -<DT><B>"w"</B><DD> write mode; -<DT><B>"a"</B><DD> append mode; -<DT><B>"r+"</B><DD> update mode, all previous data is preserved; -<DT><B>"w+"</B><DD> update mode, all previous data is erased; -<DT><B>"a+"</B><DD> append update mode, previous data is preserved, +<DT><B>``r''</B><DD> read mode; +<DT><B>``w''</B><DD> write mode; +<DT><B>``a''</B><DD> append mode; +<DT><B>``r+''</B><DD> update mode, all previous data is preserved; +<DT><B>``w+''</B><DD> update mode, all previous data is erased; +<DT><B>``a+''</B><DD> append update mode, previous data is preserved, writing is only allowed at the end of file. </DL> -The string mode may also have a <CODE>b</CODE> at the end, +The <CODE>mode</CODE> string may also have a <CODE>b</CODE> at the end, which is needed in some systems to open the file in binary mode. +This string is exactlty what is used in the standard C function <CODE>fopen</CODE>. <P> <h3> <TT>closefile (handle)</TT></h3><A NAME="closefile"></A> <P> @@ -2626,18 +3048,15 @@ It does not close the current input file. When called without parameters, it closes the <CODE>_INPUT</CODE> file, and restores <CODE>stdin</CODE> as the value of <CODE>_INPUT</CODE>. -<P> If this function fails, it returns <B>nil</B>, plus a string describing the error. <P> -<CITE> -<EM>System dependent</EM>: if <CODE>filename</CODE> starts with a <CODE>|</CODE>, +If <CODE>filename</CODE> starts with a <CODE>|</CODE>, then a <A NAME="piped input">piped input</A> is opened, via function <A NAME="popen"><TT>popen</TT></A>. Not all systems implement pipes. Moreover, the number of files that can be open at the same time is usually limited and depends on the system. -</CITE> <P> <h3> <TT>writeto (filename)</TT></h3><A NAME="writeto"></A> <P> @@ -2653,25 +3072,23 @@ When called without parameters, this function closes the <CODE>_OUTPUT</CODE> file, and restores <CODE>stdout</CODE> as the value of <CODE>_OUTPUT</CODE>. <A NAME="closing a file"></A> -<P> If this function fails, it returns <B>nil</B>, plus a string describing the error. <P> -<CITE> -<EM>System dependent</EM>: if <CODE>filename</CODE> starts with a <CODE>|</CODE>, -then a <A NAME="piped output">piped output</A> is opened, via function <A NAME="popen"><TT>popen</TT></A>. +If <CODE>filename</CODE> starts with a <CODE>|</CODE>, +then a <A NAME="piped input">piped input</A> is opened, via function <A NAME="popen"><TT>popen</TT></A>. Not all systems implement pipes. Moreover, the number of files that can be open at the same time is usually limited and depends on the system. -</CITE> <P> <h3> <TT>appendto (filename)</TT></h3><A NAME="appendto"></A> <P> Opens a file named <CODE>filename</CODE> and sets it as the value of <CODE>_OUTPUT</CODE>. Unlike the <CODE>writeto</CODE> operation, -this function does not erase any previous content of the file. +this function does not erase any previous contents of the file; +instead, anything written to the file is appended to its end. If this function fails, it returns <B>nil</B>, plus a string describing the error. <P> @@ -2691,7 +3108,7 @@ plus a string describing the error. <P> Saves any written data to the given file. If <CODE>filehandle</CODE> is not specified, -flushes all open files. +then <CODE>flush</CODE> flushes all open files. If this function fails, it returns <B>nil</B>, plus a string describing the error. <P> @@ -2702,9 +3119,9 @@ measured in bytes from the beginning of the file, to the position given by <CODE>offset</CODE> plus a base specified by the string <CODE>whence</CODE>, as follows: <DL> -<DT><B>"set"</B><DD> base is position 0 (beginning of the file); -<DT><B>"cur"</B><DD> base is current position; -<DT><B>"end"</B><DD> base is end of file; +<DT><B>``set''</B><DD> base is position 0 (beginning of the file); +<DT><B>``cur''</B><DD> base is current position; +<DT><B>``end''</B><DD> base is end of file; </DL> In case of success, function <CODE>seek</CODE> returns the final file position, measured in bytes from the beginning of the file. @@ -2724,62 +3141,35 @@ end of the file, and returns its size. <P> 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. +The file must be explicitly opened before its use +and removed when no longer needed. <P> -<h3> <TT>read ([filehandle,] readpattern1, ...)</TT></h3><A NAME="read"></A> +<h3> <TT>read ([filehandle,] format1, ...)</TT></h3><A NAME="read"></A> <P> Reads file <CODE>_INPUT</CODE>, or <CODE>filehandle</CODE> if this argument is given, -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 <B>nil</B> if the read pattern fails <EM>and</EM> -the result string would be empty. -When called without patterns, -it uses a default pattern that reads the next line +according to the given formats, which specify what to read. +For each format, +the function returns a string (or a number) with the characters read, +or <B>nil</B> if it cannot read data with the specified format. +When called without formats, +it uses a default format that reads the next line (see below). <P> -A <A NAME="read pattern"><EM>read pattern</EM></A> is a sequence of read pattern items. -An item may be a single character class -or a character class followed by <CODE>?</CODE>, by <CODE>*</CODE>, or by <CODE>+</CODE>. -A single character class reads the next character from the input -if it belongs to the class, otherwise it fails. -A character class followed by <CODE>?</CODE> reads the next character -from the input if it belongs to the class; -it never fails. -A character class followed by <CODE>*</CODE> reads until a character that -does not belong to the class, or end of file; -since it can match a sequence of zero characters, it never fails. -A character class followed by <CODE>+</CODE> reads until a character that -does not belong to the class, or end of file; -it fails if it cannot read at least one character. -Note that the behavior of read patterns is slightly different from -the regular pattern matching behavior, -where a <CODE>*</CODE> expands to the maximum length <EM>such that</EM> -the rest of the pattern does not fail. -With the read pattern behavior -there is no need for backtracking the reading. -<P> -A pattern item may contain sub-patterns enclosed in curly brackets, -that describe <A NAME="skips"><EM>skips</EM></A>. -Characters matching a skip are read, -but are not included in the resulting string. -<P> -There are some predefined patterns, as follows: +The available formats are <DL> <DT><B>``*n''</B><DD> reads a number; -this is the only pattern that returns a number instead of a string. -<DT><B>``*l''</B><DD> returns the next line +this is the only format that returns a number instead of a string. +<DT><B>``*l''</B><DD> reads the next line (skipping the end of line), or <B>nil</B> on end of file. -This is the default pattern. -It is equivalent to the pattern <CODE>"[^\n]*{\n}"</CODE>. -<DT><B>``*a''</B><DD> reads the whole file. -It is equivalent to the pattern <CODE>".*"</CODE>. -<DT><B>``*w''</B><DD> returns the next word -(maximal sequence of non white-space characters), +This is the default format. +<DT><B>``*a''</B><DD> reads the whole file, starting at the current position. +On end of file, it returns the empty string. +<DT><B>``*w''</B><DD> reads the next word +(maximal sequence of non--white-space characters), skipping spaces if necessary, or <B>nil</B> on end of file. -It is equivalent to the pattern <CODE>"{%s*}%S+"</CODE>. +<DT><B><EM>number</EM></B><DD> reads a string with up to that number of characters, +or <B>nil</B> on end of file. </DL> <P> <h3> <TT>write ([filehandle, ] value1, ...)</TT></h3><A NAME="write"></A> @@ -2793,41 +3183,45 @@ use <CODE>tostring</CODE> or <CODE>format</CODE> before <CODE>write</CODE>. If this function fails, it returns <B>nil</B>, plus a string describing the error. <P> +<A NAME="libiosys"></A> +<A NAME="6.5"></A> +<H2>6.5 - System Facilities</H2> +<P> +<h3> <TT>clock ()</TT></h3><A NAME="clock"></A> +<P> +Returns an approximation of the amount of CPU time +used by the program, in seconds. +<P> <h3> <TT>date ([format])</TT></h3><A NAME="date"></A> <P> Returns a string containing date and time formatted according to the given string <CODE>format</CODE>, -following the same rules of the ANSI C function <CODE>strftime</CODE>. +following the same rules of the ANSI C function <CODE>strftime</CODE>. When called without arguments, it returns a reasonable date and time representation that depends on -the host system and on the locale. +the host system and on the current locale. <P> -<h3> <TT>clock ()</TT></h3><A NAME="clock"></A> +<h3> <TT>execute (command)</TT></h3><A NAME="execute"></A> <P> -Returns an approximation of the amount of CPU time -used by the program, in seconds. +This function is equivalent to the C function <CODE>system</CODE>. +It passes <CODE>command</CODE> to be executed by an operating system shell. +It returns a status code, which is system-dependent. <P> <h3> <TT>exit ([code])</TT></h3><A NAME="exit"></A> <P> -Calls the C function <CODE>exit</CODE>, +Calls the C function <CODE>exit</CODE>, with an optional <CODE>code</CODE>, to terminate the program. -The default value for <CODE>code</CODE> is 1. +The default value for <CODE>code</CODE> is the success code. <P> <h3> <TT>getenv (varname)</TT></h3><A NAME="getenv"></A> <P> Returns the value of the process environment variable <CODE>varname</CODE>, or <B>nil</B> if the variable is not defined. <P> -<h3> <TT>execute (command)</TT></h3><A NAME="execute"></A> -<P> -This function is equivalent to the C function <CODE>system</CODE>. -It passes <CODE>command</CODE> to be executed by an operating system shell. -It returns an error code, which is system-dependent. -<P> <h3> <TT>setlocale (locale [, category])</TT></h3><A NAME="setlocale"></A> <P> -This function is an interface to the ANSI C function <CODE>setlocale</CODE>. +This function is an interface to the ANSI C function <CODE>setlocale</CODE>. <CODE>locale</CODE> is a string specifying a locale; <CODE>category</CODE> is an optional string describing which category to change: <CODE>"all"</CODE>, <CODE>"collate"</CODE>, <CODE>"ctype"</CODE>, @@ -2841,7 +3235,7 @@ or <B>nil</B> if the request cannot be honored. <!-- ====================================================================== --> <HR> <A NAME="7."></A> -<H1>7 - The Debugger Interface</H1> +<H1>7 - The Debug Interface</H1> <P> Lua has no built-in debugging facilities. Instead, it offers a special interface, @@ -2849,264 +3243,302 @@ by means of functions and <EM>hooks</EM>, 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 the header file <CODE>luadebug.h</CODE>. +This interface is declared in <CODE>luadebug.h</CODE>. <P> <A NAME="7.1"></A> <H2>7.1 - Stack and Function Information</H2> <P> -The main function to get information about the interpreter stack -is +<A NAME="lua_getstack"></A> +The main function to get information about the interpreter stack is <PRE> -lua_Function lua_stackedfunction (int level); + int lua_getstack (lua_State *L, int level, lua_Debug *ar); </PRE> -It returns a handle (<CODE>lua_Function</CODE>) to the <EM>activation record</EM> +It fills parts of a <CODE>lua_Debug</CODE> structure with +an identification of the <EM>activation record</EM> of the function executing at a given level. Level 0 is the current running function, -while level <I>n+1</I> is the function that has called level <I>n</I>. -When called with a level greater than the stack depth, -<CODE>lua_stackedfunction</CODE> returns <CODE>LUA_NOOBJECT</CODE>. -<P> -The type <CODE>lua_Function</CODE> is just another name -to <CODE>lua_Object</CODE>. -Although, in this library, -a <CODE>lua_Function</CODE> can be used wherever a <CODE>lua_Object</CODE> is required, -when a parameter has type <CODE>lua_Function</CODE> -it accepts only a handle returned by -<CODE>lua_stackedfunction</CODE>. -<P> -Three other functions produce extra information about a function: -<PRE> -void lua_funcinfo (lua_Object func, char **source, int *linedefined); -int lua_currentline (lua_Function func); -char *lua_getobjname (lua_Object o, char **name); -</PRE> -<CODE>lua_funcinfo</CODE> gives the source and the line where the -given function has been defined: +whereas level <I>n+1</I> is the function that has called level <I>n</I>. +Usually, <CODE>lua_getstack</CODE> returns 1; +when called with a level greater than the stack depth, +it returns 0. +<P> +<A NAME="lua_Debug"></A> +The structure <CODE>lua_Debug</CODE> is used to carry different pieces of +information about an active function: +<PRE> + typedef struct lua_Debug { + const char *event; /* "call", "return" */ + int currentline; /* (l) */ + const char *name; /* (n) */ + const char *namewhat; /* (n) global, tag method, local, field */ + int nups; /* (u) number of upvalues */ + int linedefined; /* (S) */ + const char *what; /* (S) "Lua" function, "C" function, Lua "main" */ + const char *source; /* (S) */ + char short_src[LUA_IDSIZE]; /* (S) */ +<P> + /* private part */ + ... + } lua_Debug; +</PRE> +<CODE>lua_getstack</CODE> fills only the private part +of this structure, for future use. +To fill in the other fields of <CODE>lua_Debug</CODE> with useful information, +call <A NAME="lua_getinfo"></A> +<PRE> + int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); +</PRE> +This function returns 0 on error +(e.g., an invalid option in <CODE>what</CODE>). +Each character in the string <CODE>what</CODE> +selects some fields of <CODE>ar</CODE> to be filled, +as indicated by the letter in parentheses in the definition of <CODE>lua_Debug</CODE>: +`<CODE>S</CODE>' fills in the fields <CODE>source</CODE>, <CODE>linedefined</CODE>, +and <CODE>what</CODE>; +`<CODE>l</CODE>' fills in the field <CODE>currentline</CODE>, etc. +Moreover, `<CODE>f</CODE>' pushes onto the stack the function that is +running at the given level. +<P> +To get information about a function that is not active (that is, +it is not in the stack), +you push the function onto the stack, +and start the <CODE>what</CODE> string with the character <CODE>></CODE>. +For instance, to know in which line a function <CODE>f</CODE> was defined, +you can write +<PRE> + lua_Debug ar; + lua_getglobal(L, "f"); + lua_getinfo(L, ">S", &ar); + printf("%d\n", ar.linedefined); +</PRE> +The fields of <CODE>lua_Debug</CODE> have the following meaning: +<DL> +<P> +<DT><B>source</B><DD> If the function was defined in a string, <CODE>source</CODE> is that string; -If the function was defined in a file, +if the function was defined in a file, <CODE>source</CODE> starts with a <CODE>@</CODE> followed by the file name. -If the ``function'' is in fact the main code of a chunk, -then <CODE>linedefined</CODE> is 0. -If the function is a C function, -then <CODE>linedefined</CODE> is <I>-1</I>, and <CODE>filename</CODE> is <CODE>"(C)"</CODE>. -<P> -The function <CODE>lua_currentline</CODE> gives the current line where -a given function is executing. -It only works if the function has been compiled with debug -information. -When no line information is available, -<CODE>lua_currentline</CODE> returns <I>-1</I>. <P> -The generation of debug information is controled by an internal flag, -which can be switched with -<PRE> -int lua_setdebug (int debug); -</PRE> -This function sets the flag and returns its previous value. -This flag can also be set from Lua (see Section <A HREF="#pragma">4.9</A>). +<DT><B>short_src</B><DD> +A ``printable'' version of <CODE>source</CODE>, to be used in error messages. +<P> +<DT><B>linedefined</B><DD> +the line number where the definition of the function starts. +<P> +<DT><B>what</B><DD> the string <CODE>"Lua"</CODE> if this is a Lua function, +<CODE>"C"</CODE> if this is a C function, +or <CODE>"main"</CODE> if this is the main part of a chunk. +<P> +<DT><B>currentline</B><DD> +the current line where the given function is executing. +When no line information is available, +<CODE>currentline</CODE> is set to <I>-1</I>. <P> -Function <CODE>lua_getobjname</CODE> tries to find a reasonable name for -a given function. +<DT><B>name</B><DD> +a reasonable name for the given function. 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. -Function <CODE>lua_getobjname</CODE> checks whether the given +The <CODE>lua_getinfo</CODE> 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 <CODE>lua_getobjname</CODE> -returns the string <CODE>"tag-method"</CODE>, -and <CODE>name</CODE> is set to point to the event name. +If the given function is a tag method, +then <CODE>name</CODE> points to the event name. If the given function is the value of a global variable, -then <CODE>lua_getobjname</CODE> returns the string <CODE>"global"</CODE>, -and <CODE>name</CODE> points to the variable name. +then <CODE>name</CODE> points to the variable name. If the given function is neither a tag method nor a global variable, -then <CODE>lua_getobjname</CODE> returns the empty string, -and <CODE>name</CODE> is set to <CODE>NULL</CODE>. +then <CODE>name</CODE> is set to <CODE>NULL</CODE>. +<P> +<DT><B>namewhat</B><DD> +Explains the previous field. +If the function is a global variable, +<CODE>namewhat</CODE> is <CODE>"global"</CODE>; +if the function is a tag method, +<CODE>namewhat</CODE> is <CODE>"tag-method"</CODE>; +otherwise <CODE>namewhat</CODE> is <CODE>""</CODE> (the empty string). +<P> +<DT><B>nups</B><DD> +Number of upvalues of a function. +<P> +</DL> +<P> <P> <A NAME="7.2"></A> <H2>7.2 - Manipulating Local Variables</H2> <P> +For the manipulation of local variables, +<CODE>luadebug.h</CODE> uses indices: +The first parameter or local variable has index 1, and so on, +until the last active local variable. +<P> +<A NAME="lua_getlocal"></A><A NAME="lua_setlocal"></A> The following functions allow the manipulation of the local variables of a given activation record. -They only work if the function has been compiled with debug -information (see Section <A HREF="#pragma">4.9</A>). -Moreover, for these functions, a local variable becomes -visible in the line after its definition. -<PRE> -lua_Object lua_getlocal (lua_Function func, int local_number, char **name); -int lua_setlocal (lua_Function func, int local_number); -</PRE> -<CODE>lua_getlocal</CODE> returns the value of a local variable, -and sets <CODE>name</CODE> to point to the variable name. -<CODE>local_number</CODE> is an index for local variables. -The first parameter has index 1, and so on, until the -last active local variable. -When called with a <CODE>local_number</CODE> greater than the -number of active local variables, -or if the activation record has no debug information, -<CODE>lua_getlocal</CODE> returns <CODE>LUA_NOOBJECT</CODE>. -Formal parameters are the first local variables. -<P> -The function <CODE>lua_setlocal</CODE> sets the local variable -<CODE>local_number</CODE> to the value previously pushed on the stack -(see Section <A HREF="#valuesCLua">5.2</A>). -If the function succeeds, then it returns 1. -If <CODE>local_number</CODE> is greater than the number -of active local variables, -or if the activation record has no debug information, -then this function fails and returns 0. -<P> +<PRE> + const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); + const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); +</PRE> +The parameter <CODE>ar</CODE> must be a valid activation record, +filled by a previous call to <CODE>lua_getstack</CODE> or +given as argument to a hook (see Section <A HREF="#sub-hooks">7.3</A>). +Function <CODE>lua_getlocal</CODE> gets the index of a local variable +(<CODE>n</CODE>), pushes its value onto the stack, +and returns its name. +For <CODE>lua_setlocal</CODE>, +you push the new value onto the stack, +and the function assigns that value to the variable and returns its name. +Both functions return <CODE>NULL</CODE> on failure; +that happens if the index is greater than +the number of active local variables. +<P> +As an example, the following function lists the names of all +local variables for a function at a given level of the stack: +<PRE> + int listvars (lua_State *L, int level) { + lua_Debug ar; + int i = 1; + const char *name; + if (lua_getstack(L, level, &ar) == 0) + return 0; /* failure: no such level in the stack */ + while ((name = lua_getlocal(L, &ar, i++)) != NULL) { + printf("%s\n", name); + lua_pop(L, 1); /* remove variable value */ + } + return 1; + } +</PRE> +<P> +<P> +<A NAME="sub-hooks"></A> <A NAME="7.3"></A> <H2>7.3 - Hooks</H2> <P> The Lua interpreter offers two hooks for debugging purposes: +a <EM>call</EM> hook and a <EM>line</EM> hook. +Both have the same type, +<A NAME="lua_Hook"></A> <PRE> -typedef void (*lua_CHFunction) (lua_Function func, char *file, int line); -lua_CHFunction lua_setcallhook (lua_CHFunction func); -<P> -typedef void (*lua_LHFunction) (int line); -lua_LHFunction lua_setlinehook (lua_LHFunction func); + typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); +</PRE> +and you can set them with the following functions: +<A NAME="lua_setcallhook"></A><A NAME="lua_setlinehook"></A> +<PRE> + lua_Hook lua_setcallhook (lua_State *L, lua_Hook func); + lua_Hook lua_setlinehook (lua_State *L, lua_Hook func); </PRE> -The first hook is called whenever the interpreter enters or leaves a -function. -When entering a function, -its parameters are a handle to the function activation record, -plus the file and the line where the function is defined -(the same information which is provided by <CODE>lua_funcinfo</CODE>); -when leaving a function, <CODE>func</CODE> is <CODE>LUA_NOOBJECT</CODE>, -<CODE>file</CODE> is <CODE>"(return)"</CODE>, and <CODE>line</CODE> is 0. -<P> -The other hook is called every time the interpreter changes -the line of code it is executing. -Its only parameter is the line number -(the same information which is provided by the call -<CODE>lua_currentline(lua_stackedfunction(0))</CODE>). -This second hook is called only if the active function -has been compiled with debug information (see Section <A HREF="#pragma">4.9</A>). -<P> A hook is disabled when its value is <CODE>NULL</CODE>, which is the initial value of both hooks. -Both <CODE>lua_setcallhook</CODE> and <CODE>lua_setlinehook</CODE> +The functions <CODE>lua_setcallhook</CODE> and <CODE>lua_setlinehook</CODE> set their corresponding hooks and return their previous values. <P> +The call hook is called whenever the +interpreter enters or leaves a function. +The <CODE>event</CODE> field of <CODE>ar</CODE> has the strings <CODE>"call"</CODE> +or <CODE>"return"</CODE>. +This <CODE>ar</CODE> can then be used in calls to <CODE>lua_getinfo</CODE>, +<CODE>lua_getlocal</CODE>, and <CODE>lua_setlocal</CODE> +to get more information about the function and to manipulate its +local variables. +<P> +The line hook is called every time the interpreter changes +the line of code it is executing. +The <CODE>event</CODE> field of <CODE>ar</CODE> has the string <CODE>"line"</CODE>, +and the <CODE>currentline</CODE> field has the line number. +Again, you can use this <CODE>ar</CODE> in other calls to the debug API. +<P> +While Lua is running a hook, it disables other calls to hooks. +Therefore, if a hook calls Lua to execute a function or a chunk, +this execution ocurrs without any calls to hooks. <P> <P> <A NAME="7.4"></A> -<H2>7.4 - The Reflexive Debugger Interface</H2> +<H2>7.4 - The Reflexive Debug Interface</H2> <P> The library <CODE>ldblib</CODE> provides -the functionallity of the debugger interface to Lua programs. +the functionality of the debug interface to Lua programs. If you want to use this library, your host application must open it, -calling <CODE>lua_dblibopen</CODE>. +by calling <CODE>lua_dblibopen</CODE>. +<A NAME="lua_dblibopen"></A> <P> You should exert great care when using this library. The functions provided here should be used exclusively for debugging -and similar tasks (e.g. profiling). +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). +language (e.g., privacy of local variables). As a general rule, if your program does not need this library, do not open it. <P> <P> -<h3> <TT>funcinfo (function)</TT></h3><A NAME="funcinfo"></A> +<h3> <TT>getinfo (function, [what])</TT></h3><A NAME="getinfo"></A> <P> -This function returns a table with information about the given function. -The table contains the following fields: -<DL> -<DT><B>kind</B><DD>: may be <CODE>"C"</CODE>, if this is a C function, -<CODE>"chunk"</CODE>, if this is the main part of a chunk, -or <CODE>"Lua"</CODE> if this is a Lua function. +This function returns a table with information about a function. +You can give the function directly, +or you can give a number as the value of <CODE>function</CODE>, +which means the function running at level <CODE>function</CODE> of the stack: +Level 0 is the current function (<CODE>getinfo</CODE> itself); +level 1 is the function that called <CODE>getinfo</CODE>; +and so on. +If <CODE>function</CODE> is a number larger than the number of active functions, +then <CODE>getinfo</CODE> returns <B>nil</B>. <P> -<DT><B>source</B><DD> the source where the function was defined. -If the function was defined in a string, -<CODE>source</CODE> is that string; -If the function was defined in a file, -<CODE>source</CODE> starts with a <CODE>@</CODE> followed by the file name. +The returned table contains all the fields returned by <CODE>lua_getinfo</CODE>, +with the string <CODE>what</CODE> describing what to get. +The default for <CODE>what</CODE> is to get all information available. <P> -<DT><B>def_line</B><DD> the line where the function was defined in the source -(only valid if this is a Lua function). +For instance, the expression <CODE>getinfo(1,"n").name</CODE> returns +the name of the current function, if a reasonable name can be found, +and <CODE>getinfo(print)</CODE> returns a table with all available information +about the <CODE>print</CODE> function. <P> -<DT><B>where</B><DD> can be <CODE>"global"</CODE> if this function has a global name, -or <CODE>"tag-method"</CODE> if this function is a tag method handler. -<P> -<DT><B>name</B><DD> if <CODE>where</CODE> = <CODE>global</CODE>, -<CODE>name</CODE> is the global name of the function; -if <CODE>where</CODE> = <CODE>tag-method</CODE>, -<CODE>name</CODE> is the event name of the tag method. -</DL> <P> -<h3> <TT>getstack (index)</TT></h3><A NAME="getstack"></A> +<h3> <TT>getlocal (level, local)</TT></h3><A NAME="getlocal"></A> <P> -This function returns a table with informations about the function -running at level <CODE>index</CODE> of the stack. -Index 0 is the current function (<CODE>getstack</CODE> itself). -If <CODE>index</CODE> is bigger than the number of active functions, -the function returns <B>nil</B>. -The table contains all the fields returned by <CODE>funcinfo</CODE>, -plus the following: -<DL> -<DT><B>func</B><DD> the function at that level. -<DT><B>current</B><DD> the current line on the function execution; -this will be available only when the function is -precompiled with debug information. -</DL> -<P> -<h3> <TT>getlocal (index [, local])</TT></h3><A NAME="getlocal"></A> -<P> -This function returns information about the local variables of the -function at level <CODE>index</CODE> of the stack. -It can be called in three ways. -When called without a <CODE>local</CODE> argument, -it returns a table, which associates variable names to their values. -When called with a name (a string) as <CODE>local</CODE>, -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, +This function returns the name and the value of the local variable +with index <CODE>local</CODE> of the function at level <CODE>level</CODE> of the stack. +(The first parameter or local variable has index 1, and so on, until the last active local variable.) -In that case, the function returns <B>nil</B> 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. +The function returns <B>nil</B> if there is no local +variable with the given index, +and raises an error when called with a <CODE>level</CODE> out of range. +(You can call <CODE>getinfo</CODE> to check whether the level is valid.) <P> -<h3> <TT>setlocal (index, local, newvalue)</TT></h3><A NAME="setlocal"></A> +<h3> <TT>setlocal (level, local, value)</TT></h3><A NAME="setlocal"></A> <P> -This function changes the values of the local variables of the -function at level <CODE>index</CODE> of the stack. -The local variable can be specified by name or by index; -see function <CODE>getlocal</CODE>. +This function assigns the value <CODE>value</CODE> to the local variable +with index <CODE>local</CODE> of the function at level <CODE>level</CODE> of the stack. +The function returns <B>nil</B> if there is no local +variable with the given index, +and raises an error when called with a <CODE>level</CODE> out of range. <P> <h3> <TT>setcallhook (hook)</TT></h3><A NAME="setcallhook"></A> <P> Sets the function <CODE>hook</CODE> 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. -<P> +The only argument to the call hook is the event name (<CODE>"call"</CODE> or +<CODE>"return"</CODE>). +You can call <CODE>getinfo</CODE> with level 2 to get more information about +the function being called or returning +(level 0 is the <CODE>getinfo</CODE> function, +and level 1 is the hook function). When called without arguments, this function turns off call hooks. +<CODE>setcallhook</CODE> returns the old hook. <P> <h3> <TT>setlinehook (hook)</TT></h3><A NAME="setlinehook"></A> <P> Sets the function <CODE>hook</CODE> 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 Section <A HREF="#pragma">4.9</A>). -<P> +The only argument to the line hook is the line number the interpreter +is about to execute. When called without arguments, this function turns off line hooks. +<CODE>setlinehook</CODE> returns the old hook. <P> <P> <A NAME="lua-sa"></A> @@ -3116,60 +3548,96 @@ this function turns off line hooks. <H1>8 - Lua Stand-alone</H1> <P> Although Lua has been designed as an extension language, -the language can also be used as a stand-alone interpreter. -An implementation of such an interpreter, +to be embedded in a host C program, +it is frequently used as a stand-alone language. +An interpreter for Lua as a stand-alone language, called simply <CODE>lua</CODE>, is provided with the standard distribution. This program can be called with any sequence of the following arguments: <DL> -<DT><B><TT>-v</TT></B><DD> prints version information. -<DT><B><TT>-d</TT></B><DD> turns on debug information. -<DT><B><TT>-e stat</TT></B><DD> executes <CODE>stat</CODE> as a Lua chunk. -<DT><B><TT>-i</TT></B><DD> runs interactively, -accepting commands from standard input until an <CODE>EOF</CODE>. -Each line entered is immediately executed. -<DT><B><TT>-q</TT></B><DD> same as <TT>-i</TT>, but without a prompt (quiet mode). -<DT><B><TT>-</TT></B><DD> executes <CODE>stdin</CODE> as a file. -<DT><B><TT>var=value</TT></B><DD> sets global <CODE>var</CODE> with string <CODE>"value"</CODE>. -<DT><B><TT>filename</TT></B><DD> executes file <CODE>filename</CODE> as a Lua chunk. +<DT><B><TT>-sNUM</TT></B><DD> sets the stack size to <TT>NUM</TT> +(if present, this must be the first option); +<DT><B><TT>-</TT> </B><DD> executes <CODE>stdin</CODE> as a file; +<DT><B><TT>-c</TT></B><DD> calls <CODE>lua_close</CODE> after running all arguments; +<DT><B><TT>-e</TT> \rm<EM>stat</EM></B><DD> executes string <CODE>stat</CODE>; +<DT><B><TT>-f filename</TT></B><DD> executes file <CODE>filename</CODE> with the +remaining arguments in table <CODE>arg</CODE>; +<DT><B><TT>-i</TT></B><DD> enters interactive mode with prompt; +<DT><B><TT>-q</TT></B><DD> enters interactive mode without prompt; +<DT><B><TT>-v</TT></B><DD> prints version information; +<DT><B><TT>var=value</TT></B><DD> sets global <CODE>var</CODE> to string <CODE>"value"</CODE>; +<DT><B><TT>filename</TT></B><DD> executes file <CODE>filename</CODE>. </DL> When called without arguments, -Lua behaves as <CODE>lua -v -i</CODE> when <CODE>stdin</CODE> is a terminal, +<CODE>lua</CODE> behaves as <CODE>lua -v -i</CODE> when <CODE>stdin</CODE> is a terminal, and as <CODE>lua -</CODE> otherwise. <P> -All arguments are handled in order. +All arguments are handled in order, except <CODE>-c</CODE>. For instance, an invocation like <PRE> -$ lua -i a=test prog.lua + $ lua -i a=test prog.lua </PRE> -will first interact with the user until an <CODE>EOF</CODE>, +will first interact with the user until an <CODE>EOF</CODE> in <CODE>stdin</CODE>, then will set <CODE>a</CODE> to <CODE>"test"</CODE>, and finally will run the file <CODE>prog.lua</CODE>. +(Here, +<CODE>$</CODE> is the shell prompt. Your prompt may be different.) <P> -When in interactive mode, +When the option <TT>-f filename</TT> is used, +all remaining arguments in the command line +are passed to the Lua program <CODE>filename</CODE> in a table called <CODE>arg</CODE>. +In this table, +the field <CODE>n</CODE> gets the index of the last argument, +and the field 0 gets <CODE>"filename"</CODE>. +For instance, in the call +<PRE> + $ lua a.lua -f b.lua t1 t3 +</PRE> +the interpreter first runs the file <TT>a.lua</TT>, +then creates a table +<PRE> + arg = {"t1", "t3"; n = 2, [0] = "b.lua"} +</PRE> +and finally runs the file <TT>b.lua</TT>. +<A NAME="getargs"></A> +The stand-alone interpreter also provides a <CODE>getargs</CODE> function that +can be used to access <EM>all</EM> command line arguments. +For instance, if you call Lua with the line +<PRE> + $ lua -c a b +</PRE> +then a call to <CODE>getargs</CODE> in <CODE>a</CODE> or <CODE>b</CODE> will return the table +<PRE> + {[0] = "lua", [1] = "-c", [2] = "a", [3] = "b", n = 3} +</PRE> +<P> +In interactive mode, a multi-line statement can be written finishing intermediate -lines with a backslash (<CODE>\</CODE>). -The prompt presented is the value of the global variable <CODE>_PROMPT</CODE>. -Therefore, the prompt can be changed like below: +lines with a backslash (`<CODE>\</CODE>'). +If the global variable <A NAME="_PROMPT"><TT>_PROMPT</TT></A> is defined as a string, +then its value is used as the prompt. +Therefore, the prompt can be changed directly on the command line: <PRE> -$ lua _PROMPT='myprompt> ' -i + $ lua _PROMPT='myprompt> ' -i </PRE> +or in any Lua programs by assigning to <CODE>_PROMPT</CODE>. <P> In Unix systems, Lua scripts can be made into executable programs -by using the <CODE>#!</CODE> form, -as in <CODE>#!/usr/local/bin/lua</CODE>. +by using <CODE>chmod +x</CODE> and the <CODE>#!</CODE> form, +as in <CODE>#!/usr/local/bin/lua</CODE>, +or <CODE>#!/usr/local/bin/lua -f</CODE> to get other arguments. +<P> <P> <HR> <A NAME="Acknowledgments"></A> <h1>Acknowledgments</h1> <P> The authors would like to thank CENPES/PETROBRAS which, -jointly with TeCGraf, used extensively early versions of -this system and gave valuable comments. +jointly with TeCGraf, used early versions of +this system extensively and gave valuable comments. The authors would also like to thank Carlos Henrique Levy, who found the name of the game. -Lua means <EM>moon</EM> in Portuguese. -<P> +Lua means ``moon'' in Portuguese. <P> <P> <P> @@ -3177,60 +3645,153 @@ Lua means <EM>moon</EM> in Portuguese. <A NAME="Incompatibilities"></A> <h1>Incompatibilities with Previous Versions</h1> <P> -Although great care has been taken to avoid incompatibilities with +Lua 4.0 is a major revision of the language. +We took a great care to avoid incompatibilities with the previous public versions of Lua, -some differences had to be introduced. +but some differences had to be introduced. Here is a list of all these incompatibilities. <P> -<h2>Incompatibilities with <A NAME="version 3.1</h2>">version 3.1</h2></A> +<P> +<h2>Incompatibilities with <A NAME="version 3.2</h2>">version 3.2</h2></A> +<P> +<h3>Changes in the Language</h3> <UL> +<P> <LI> -In the debug API, the old variables <CODE>lua_debug</CODE>, -<CODE>lua_callhook</CODE> and <CODE>lua_linehook</CODE> now live inside <CODE>lua_state</CODE>. -Therefore, they are no longer directly accessible, and must be -manipulated only through the new functions <CODE>lua_setdebug</CODE>, -<CODE>lua_setcallhook</CODE> and <CODE>lua_setlinehook</CODE>. +All pragmas (<CODE>$debug</CODE>, <CODE>$if</CODE>, ...) have been removed. +<P> +<LI> +<B>for</B>, <B>break</B>, and <B>in</B> are now reserved words. +<P> +<LI> +Garbage-collection tag methods for tables is now obsolete. +<P> +<LI> +There is now only one tag method for order operators. +<P> +<LI> +In nested function calls like <CODE>f(g(x))</CODE>, +<EM>all</EM> return values from <CODE>g</CODE> are passed as arguments to <CODE>f</CODE>. +This only happens when <CODE>g</CODE> is the last +or the only argument to <CODE>f</CODE>. +<P> +<LI> +The pre-compiler may assume that some operators are associative, +for optimizations. +This may cause problems if these operators +have non-associative tag methods. <P> <LI>Old pre-compiled code is obsolete, and must be re-compiled. +<P> </UL> <P> -<h2>Incompatibilities with <A NAME="version 3.0</h2>">version 3.0</h2></A> +<P> +<h3>Changes in the Libraries</h3> <UL> <P> -<LI>To support multiple contexts, -Lua 3.1 must be explicitly opened before used, -with function <CODE>lua_open</CODE>. -However, all standard libraries check whether Lua is already opened, -so any existing program that opens at least one standard -library before calling Lua does not need to be modified. +<LI> +When traversing a table with <CODE>next</CODE> or <CODE>foreach</CODE>, +the table cannot be modified in any way. <P> -<LI>Function <CODE>dostring</CODE> no longer accepts an optional second argument, -with a temporary error handler. -This facility is now provided by function <CODE>call</CODE>. +<LI> +General read patterns are now obsolete. <P> -<LI>Function <CODE>gsub</CODE> no longer accepts an optional fourth argument -(a callback data, a table). -Closures replace this feature with advantage. +<LI> +The functions <CODE>rawgettable</CODE> and <CODE>rawsettable</CODE> +have been renamed to <CODE>rawget</CODE> and <CODE>rawset</CODE>. <P> -<LI>The syntax for function declaration is now more restricted; -for instance, the old syntax <CODE>function f[exp] (x) ... end</CODE> is not -accepted in Lua 3.1. -In these cases, -programs should use an explicit assignment instead, such as -<CODE>f[exp] = function (x) ... end</CODE>. +<LI> +The functions <CODE>foreachvar</CODE>, <CODE>nextvar</CODE>, +<CODE>rawsetglobal</CODE>, and <CODE>rawgetglobal</CODE> are obsolete. +You can get their functionality using table operations +over the table of globals, +which is returned by <CODE>globals</CODE>. <P> -<LI>Old pre-compiled code is obsolete, and must be re-compiled. +<LI> +<CODE>setglobal</CODE> and <CODE>sort</CODE> no longer return a value; +<CODE>type</CODE> no longer returns a second value. <P> -<LI>The option <CODE>a=b</CODE> in Lua stand-alone now sets <CODE>a</CODE> to the -<EM>string</EM> <CODE>b</CODE>, and not to the value of <CODE>b</CODE>. +<LI> +The <CODE>p</CODE> option in function <CODE>call</CODE> is now obsolete. <P> </UL> <P> +<P> +<h3>Changes in the API</h3> +<UL> +<P> +<LI> +The API has been completely rewritten: +It is now fully reentrant and much clearer. +<P> +<LI> +The debug API has been completely rewritten. +<P> +</UL> +<P> +<A NAME="BNF"></A> +<A NAME="grammar"></A> +<HR> +<h1>The Complete Syntax of Lua</h1> +<P> +<A NAME="grammar"></A> +<P> +<PRE> +<P> + chunk ::= {stat [`<B>;</B>']} +<P> + block ::= chunk +<P> + stat ::= varlist1 `<B>=</B>' explist1 <BR> | functioncall <BR> | <B>do</B> block <B>end</B> <BR> | <B>while</B> exp1 <B>do</B> block <B>end</B> <BR> | <B>repeat</B> block <B>until</B> exp1 <BR> | <B>if</B> exp1 <B>then</B> block {<B>elseif</B> exp1 <B>then</B> block} [<B>else</B> block] <B>end</B> <BR> | <B>return</B> [explist1] <BR> | <B>break</B> <BR> | <B>for</B> `<B>name</B>' `<B>=</B>' exp1 `<B>,</B>' exp1 [`<B>,</B>' exp1] <B>do</B> block <B>end</B> <BR> | <B>for</B> `<B>name</B>' `<B>,</B>' `<B>name</B>' <B>in</B> exp1 <B>do</B> block <B>end</B> <BR> | <B>function</B> funcname `<B>(</B>' [parlist1] `<B>)</B>' block <B>end</B> <BR> | <B>local</B> declist [init] +<P> + funcname ::= `<B>name</B>' | `<B>name</B>' `<B>.</B>' `<B>name</B>' | `<B>name</B>' `<B>:</B>' `<B>name</B>' +<P> + varlist1 ::= var {`<B>,</B>' var} +<P> + var ::= `<B>name</B>' | varorfunc `<B>[</B>' exp1 `<B>]</B>' | varorfunc `<B>.</B>' `<B>name</B>' +<P> + varorfunc ::= var | functioncall +<P> + declist ::= `<B>name</B>' {`<B>,</B>' `<B>name</B>'} +<P> + init ::= `<B>=</B>' explist1 +<P> + explist1 ::= {exp1 `<B>,</B>'} exp +<P> + exp1 ::= exp +<P> + exp ::= <B>nil</B> | `<B>number</B>' | `<B>literal</B>' | var | function | upvalue <BR> | functioncall | tableconstructor | `<B>(</B>' exp `<B>)</B>' | exp binop exp | unop exp +<P> +<P> + functioncall ::= varorfunc args | varorfunc `<B>:</B>' `<B>name</B>' args +<P> + args ::= `<B>(</B>' [explist1] `<B>)</B>' | tableconstructor | `<B>literal</B>' +<P> + function ::= <B>function</B> `<B>(</B>' [parlist1] `<B>)</B>' block <B>end</B> +<P> + parlist1 ::= `<B>...</B>' | `<B>name</B>' {`<B>,</B>' `<B>name</B>'} [`<B>,</B>' `<B>...</B>'] +<P> + upvalue ::= `<B>%</B>' `<B>name</B>' +<P> + tableconstructor ::= `<B>{</B>' fieldlist `<B>}</B>' + fieldlist ::= lfieldlist | ffieldlist | lfieldlist `<B>;</B>' ffieldlist | ffieldlist `<B>;</B>' lfieldlist + lfieldlist ::= [lfieldlist1] + ffieldlist ::= [ffieldlist1] + lfieldlist1 ::= exp {`<B>,</B>' exp} [`<B>,</B>'] + ffieldlist1 ::= ffield {`<B>,</B>' ffield} [`<B>,</B>'] + ffield ::= `<B>[</B>' exp `<B>]</B>' `<B>=</B>' exp | `<B>name</B>' `<B>=</B>' exp +<P> + binop ::= `<B>+</B>' | `<B>-</B>' | `<B>*</B>' | `<B>/</B>' | `<B>\^{ </B>' | `<B>..</B>' <BR> | `<B><</B>' | `<B><=</B>' | `<B>></B>' | `<B>>=</B>' | `<B>==</B>' | `<B>\ { </B>'=} <BR> | <B>and</B> | <B>or</B>} +<P> + unop ::= `<B>-</B>' | <B>not</B> +<P> +</PRE> +<P> <HR> <SMALL> Last update: -Wed Jul 7 13:36:24 EST 1999 +Mon Nov 6 17:37:03 EDT 2000 by <A HREF="http://www.tecgraf.puc-rio.br/~lhf/">lhf</A>. </SMALL> diff --git a/doc/readme.html b/doc/readme.html index dd75b1d1..a574eccd 100644 --- a/doc/readme.html +++ b/doc/readme.html @@ -6,24 +6,29 @@ <BODY BGCOLOR="#FFFFFF"> <HR> -<H1><A HREF="http://www.tecgraf.puc-rio.br/lua/">Lua</A> documentation</H1> +<H1> +<IMG SRC="logo.gif" ALT="Lua" ALIGN="bottom"> +Documentation +</H1> <UL> +<LI><A HREF="http://www.tecgraf.puc-rio.br/lua/">Official web site</A> <LI><A HREF="index.html">Reference manual</A> +<LI><A HREF="lua.html">lua man page</A> <LI><A HREF="luac.html">luac man page</A> -<LI><A HREF="../README">README</A> -<LI><A HREF="../src/lib/README">src/lib/README</A> -<LI><A HREF="../src/lua/README">src/lua/README</A> -<LI><A HREF="../src/luac/README">src/luac/README</A> -<LI><A HREF="../etc/README">etc/README</A> -<LI><A HREF="../test/README">test/README</A> -<LI><A HREF="../test/examples/www/README">test/examples/www/README</A> +<LI><A HREF="../README">lua/README</A> +<LI><A HREF="../src/lib/README">lua/src/lib/README</A> +<LI><A HREF="../src/lua/README">lua/src/lua/README</A> +<LI><A HREF="../src/luac/README">lua/src/luac/README</A> +<LI><A HREF="../etc/README">lua/etc/README</A> +<LI><A HREF="../test/README">lua/test/README</A> +<LI><A HREF="../test/examples/www/README">lua/test/examples/www/README</A> </UL> <HR> <SMALL> Last update: -Wed Jul 7 13:24:17 EST 1999 +Mon Nov 6 19:13:31 EDT 2000 by <A HREF="http://www.tecgraf.puc-rio.br/~lhf/">lhf</A>. </SMALL> |
