diff options
| author | Lua Team <team@lua.org> | 2006-01-12 12:00:00 +0000 |
|---|---|---|
| committer | repogen <> | 2006-01-12 12:00:00 +0000 |
| commit | 4f266285f998d0d14c4e83cc29772f0de1a7fbba (patch) | |
| tree | a122a829730d9f96e3a4e2bf65347490a8759800 | |
| parent | b3196343ba1a5dfe10e68eb9c61dc0ad5bb961a8 (diff) | |
| download | lua-github-4f266285f998d0d14c4e83cc29772f0de1a7fbba.tar.gz | |
Lua 5.1-rc15.1-rc1
| -rw-r--r-- | COPYRIGHT | 2 | ||||
| -rw-r--r-- | HISTORY | 2 | ||||
| -rw-r--r-- | INSTALL | 57 | ||||
| -rw-r--r-- | MANIFEST | 214 | ||||
| -rw-r--r-- | Makefile | 34 | ||||
| -rw-r--r-- | README | 2 | ||||
| -rw-r--r-- | doc/contents.html | 271 | ||||
| -rw-r--r-- | doc/lua.1 | 37 | ||||
| -rw-r--r-- | doc/lua.html | 51 | ||||
| -rw-r--r-- | doc/luac.1 | 34 | ||||
| -rw-r--r-- | doc/luac.html | 50 | ||||
| -rw-r--r-- | doc/manual.html | 1822 | ||||
| -rw-r--r-- | src/Makefile | 51 | ||||
| -rw-r--r-- | src/lapi.c | 27 | ||||
| -rw-r--r-- | src/lauxlib.c | 18 | ||||
| -rw-r--r-- | src/lauxlib.h | 4 | ||||
| -rw-r--r-- | src/lbaselib.c | 6 | ||||
| -rw-r--r-- | src/lcode.c | 12 | ||||
| -rw-r--r-- | src/ldblib.c | 6 | ||||
| -rw-r--r-- | src/ldebug.c | 8 | ||||
| -rw-r--r-- | src/ldo.c | 17 | ||||
| -rw-r--r-- | src/lfunc.c | 6 | ||||
| -rw-r--r-- | src/lgc.c | 17 | ||||
| -rw-r--r-- | src/linit.c | 4 | ||||
| -rw-r--r-- | src/liolib.c | 8 | ||||
| -rw-r--r-- | src/llex.c | 52 | ||||
| -rw-r--r-- | src/llex.h | 6 | ||||
| -rw-r--r-- | src/llimits.h | 23 | ||||
| -rw-r--r-- | src/lmem.c | 18 | ||||
| -rw-r--r-- | src/loadlib.c | 65 | ||||
| -rw-r--r-- | src/lobject.c | 12 | ||||
| -rw-r--r-- | src/lobject.h | 14 | ||||
| -rw-r--r-- | src/lopcodes.h | 4 | ||||
| -rw-r--r-- | src/loslib.c | 48 | ||||
| -rw-r--r-- | src/lparser.c | 80 | ||||
| -rw-r--r-- | src/lstring.c | 4 | ||||
| -rw-r--r-- | src/lstrlib.c | 59 | ||||
| -rw-r--r-- | src/ltable.c | 92 | ||||
| -rw-r--r-- | src/ltable.h | 15 | ||||
| -rw-r--r-- | src/ltm.c | 6 | ||||
| -rw-r--r-- | src/lua.c | 14 | ||||
| -rw-r--r-- | src/lua.h | 8 | ||||
| -rw-r--r-- | src/luaconf.h | 44 | ||||
| -rw-r--r-- | src/lualib.h | 8 | ||||
| -rw-r--r-- | src/lvm.c | 14 | ||||
| -rw-r--r-- | src/print.c | 7 |
46 files changed, 1822 insertions, 1531 deletions
@@ -9,7 +9,7 @@ For details and rationale, see http://www.lua.org/license.html . =============================================================================== -Copyright (C) 1994-2005 Lua.org, PUC-Rio. +Copyright (C) 1994-2006 Lua.org, PUC-Rio. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -1,4 +1,4 @@ -This is Lua 5.1 (beta). +This is Lua 5.1. * Changes from version 5.0 to 5.1 ------------------------------- @@ -1,17 +1,27 @@ -This is Lua 5.1 (beta). +This is Lua 5.1. -* Installation +* Building Lua ------------ - Building Lua on a Unix system should be very easy: simply doing "make" - should work. This will build Lua in the src directory. + Lua is built in the src directory, but the build process can be + controlled from the top-level Makefile. - There are also special make targets for ansi, linux, bsd, mingw. + Building Lua on Unix systems should be very easy. First do "make" and + see if your platform is listed. If so, just do "make xxx", where xxx + is your platform name. The platforms currently supported are: + ansi bsd generic linux macosx mingw posix - See below for customization instructions. + See below for customization instructions and for instructions on how + to build with other Windows compilers. - If you want to install Lua in an official place in your system, then - do "make install". The official place and the way to install files are - defined in Makefile. You must have the right permissions to install files. + If you want to check that Lua has been built correctly, do "make test" + after building Lua. Also, have a look at the example programs in test. + +* Installing Lua + -------------- + Once you have built Lua, you may want to install it in an official + place in your system. In this case, do "make install". The official + place and the way to install files are defined in Makefile. You must + have the right permissions to install files. If you want to install Lua locally, then do "make local". This will create directories bin, include, lib, man, and install Lua there as @@ -25,8 +35,11 @@ This is Lua 5.1 (beta). These are the only directories you need for development. There are man pages for lua and luac, in both nroff and html, and a - reference manual in html in ./doc, some sample code in ./test, and some - useful stuff in ./etc. You don't need these directories for development. + reference manual in html in doc, some sample code in test, and some + useful stuff in etc. You don't need these directories for development. + + If you want to install Lua locally, but in some other directory, do + "make install INSTALL_TOP=xxx", where xxx is your chosen directory. See below for instructions for Windows and other systems. @@ -44,14 +57,16 @@ This is Lua 5.1 (beta). to edit src/luaconf.h. The edited file will be the one installed, and it will be used by any Lua clients that you build, to ensure consistency. - We strongly recommend that you enable dynamic loading. See src/luaconf.h - and also src/Makefile. + We strongly recommend that you enable dynamic loading. This is done + automatically for all platforms listed above that have this feature + (and also Windows). See src/luaconf.h and also src/Makefile. -* Installation on Windows and other systems +* Building Lua on Windows and other systems ----------------------------------------- - The instructions for building Lua on other systems depend on the compiler - you use. You'll need to create projects (or whatever your compiler uses) - for building the library, the interpreter, and the compiler, as follows: + If you're not using the usual Unix tools, then the instructions for + building Lua depend on the compiler you use. You'll need to create + projects (or whatever your compiler uses) for building the library, + the interpreter, and the compiler, as follows: library: lapi.c lcode.c ldebug.c ldo.c ldump.c lfunc.c lgc.c llex.c lmem.c lobject.c lopcodes.c lparser.c lstate.c lstring.c @@ -63,8 +78,11 @@ This is Lua 5.1 (beta). compiler: library, luac.c print.c + If you use Visual Studio .NET, you can use etc/luavs.bat + in its "Command Prompt". + If all you want is to build the Lua interpreter, you may put all .c files - in a single project, except for luac.c and print.c. Or use etc/all.c. + in a single project, except for luac.c and print.c. Or just use etc/all.c. To use Lua as a library in your own programs, you'll need to know how to create and use libraries with your compiler. @@ -72,7 +90,4 @@ This is Lua 5.1 (beta). As mentioned above, you may edit luaconf.h to select some features before building Lua. - If you use Visual Studio .NET, you can use etc/luavs.bat - in its "Command Prompt". - (end of INSTALL) @@ -1,108 +1,108 @@ -MANIFEST contents of Lua 5.1 (beta) distribution on Fri Nov 18 07:42:23 BRST 2005 -lua-5.1-beta -lua-5.1-beta/COPYRIGHT -lua-5.1-beta/HISTORY -lua-5.1-beta/INSTALL -lua-5.1-beta/MANIFEST -lua-5.1-beta/Makefile -lua-5.1-beta/README -lua-5.1-beta/doc -lua-5.1-beta/doc/contents.html -lua-5.1-beta/doc/logo.gif -lua-5.1-beta/doc/lua.1 -lua-5.1-beta/doc/lua.css -lua-5.1-beta/doc/lua.html -lua-5.1-beta/doc/luac.1 -lua-5.1-beta/doc/luac.html -lua-5.1-beta/doc/manual.html -lua-5.1-beta/doc/readme.html -lua-5.1-beta/etc -lua-5.1-beta/etc/Makefile -lua-5.1-beta/etc/README -lua-5.1-beta/etc/all.c -lua-5.1-beta/etc/lua.hpp -lua-5.1-beta/etc/lua.ico -lua-5.1-beta/etc/lua.pc -lua-5.1-beta/etc/luavs.bat -lua-5.1-beta/etc/min.c -lua-5.1-beta/etc/noparser.c -lua-5.1-beta/etc/strict.lua -lua-5.1-beta/src -lua-5.1-beta/src/Makefile -lua-5.1-beta/src/lapi.c -lua-5.1-beta/src/lapi.h -lua-5.1-beta/src/lauxlib.c -lua-5.1-beta/src/lauxlib.h -lua-5.1-beta/src/lbaselib.c -lua-5.1-beta/src/lcode.c -lua-5.1-beta/src/lcode.h -lua-5.1-beta/src/ldblib.c -lua-5.1-beta/src/ldebug.c -lua-5.1-beta/src/ldebug.h -lua-5.1-beta/src/ldo.c -lua-5.1-beta/src/ldo.h -lua-5.1-beta/src/ldump.c -lua-5.1-beta/src/lfunc.c -lua-5.1-beta/src/lfunc.h -lua-5.1-beta/src/lgc.c -lua-5.1-beta/src/lgc.h -lua-5.1-beta/src/linit.c -lua-5.1-beta/src/liolib.c -lua-5.1-beta/src/llex.c -lua-5.1-beta/src/llex.h -lua-5.1-beta/src/llimits.h -lua-5.1-beta/src/lmathlib.c -lua-5.1-beta/src/lmem.c -lua-5.1-beta/src/lmem.h -lua-5.1-beta/src/loadlib.c -lua-5.1-beta/src/lobject.c -lua-5.1-beta/src/lobject.h -lua-5.1-beta/src/lopcodes.c -lua-5.1-beta/src/lopcodes.h -lua-5.1-beta/src/loslib.c -lua-5.1-beta/src/lparser.c -lua-5.1-beta/src/lparser.h -lua-5.1-beta/src/lstate.c -lua-5.1-beta/src/lstate.h -lua-5.1-beta/src/lstring.c -lua-5.1-beta/src/lstring.h -lua-5.1-beta/src/lstrlib.c -lua-5.1-beta/src/ltable.c -lua-5.1-beta/src/ltable.h -lua-5.1-beta/src/ltablib.c -lua-5.1-beta/src/ltm.c -lua-5.1-beta/src/ltm.h -lua-5.1-beta/src/lua.c -lua-5.1-beta/src/lua.h -lua-5.1-beta/src/luac.c -lua-5.1-beta/src/luaconf.h -lua-5.1-beta/src/lualib.h -lua-5.1-beta/src/lundump.c -lua-5.1-beta/src/lundump.h -lua-5.1-beta/src/lvm.c -lua-5.1-beta/src/lvm.h -lua-5.1-beta/src/lzio.c -lua-5.1-beta/src/lzio.h -lua-5.1-beta/src/print.c -lua-5.1-beta/test -lua-5.1-beta/test/README -lua-5.1-beta/test/bisect.lua -lua-5.1-beta/test/cf.lua -lua-5.1-beta/test/echo.lua -lua-5.1-beta/test/env.lua -lua-5.1-beta/test/factorial.lua -lua-5.1-beta/test/fib.lua -lua-5.1-beta/test/fibfor.lua -lua-5.1-beta/test/globals.lua -lua-5.1-beta/test/hello.lua -lua-5.1-beta/test/life.lua -lua-5.1-beta/test/luac.lua -lua-5.1-beta/test/printf.lua -lua-5.1-beta/test/readonly.lua -lua-5.1-beta/test/sieve.lua -lua-5.1-beta/test/sort.lua -lua-5.1-beta/test/table.lua -lua-5.1-beta/test/trace-calls.lua -lua-5.1-beta/test/trace-globals.lua -lua-5.1-beta/test/xd.lua +MANIFEST contents of Lua 5.1 distribution on Wed Jan 11 22:50:45 BRST 2006 +lua-5.1 +lua-5.1/COPYRIGHT +lua-5.1/doc +lua-5.1/doc/contents.html +lua-5.1/doc/logo.gif +lua-5.1/doc/lua.1 +lua-5.1/doc/luac.1 +lua-5.1/doc/luac.html +lua-5.1/doc/lua.css +lua-5.1/doc/lua.html +lua-5.1/doc/manual.html +lua-5.1/doc/readme.html +lua-5.1/etc +lua-5.1/etc/all.c +lua-5.1/etc/lua.hpp +lua-5.1/etc/lua.ico +lua-5.1/etc/lua.pc +lua-5.1/etc/luavs.bat +lua-5.1/etc/Makefile +lua-5.1/etc/min.c +lua-5.1/etc/noparser.c +lua-5.1/etc/README +lua-5.1/etc/strict.lua +lua-5.1/HISTORY +lua-5.1/INSTALL +lua-5.1/Makefile +lua-5.1/MANIFEST +lua-5.1/README +lua-5.1/src +lua-5.1/src/lapi.c +lua-5.1/src/lapi.h +lua-5.1/src/lauxlib.c +lua-5.1/src/lauxlib.h +lua-5.1/src/lbaselib.c +lua-5.1/src/lcode.c +lua-5.1/src/lcode.h +lua-5.1/src/ldblib.c +lua-5.1/src/ldebug.c +lua-5.1/src/ldebug.h +lua-5.1/src/ldo.c +lua-5.1/src/ldo.h +lua-5.1/src/ldump.c +lua-5.1/src/lfunc.c +lua-5.1/src/lfunc.h +lua-5.1/src/lgc.c +lua-5.1/src/lgc.h +lua-5.1/src/linit.c +lua-5.1/src/liolib.c +lua-5.1/src/llex.c +lua-5.1/src/llex.h +lua-5.1/src/llimits.h +lua-5.1/src/lmathlib.c +lua-5.1/src/lmem.c +lua-5.1/src/lmem.h +lua-5.1/src/loadlib.c +lua-5.1/src/lobject.c +lua-5.1/src/lobject.h +lua-5.1/src/lopcodes.c +lua-5.1/src/lopcodes.h +lua-5.1/src/loslib.c +lua-5.1/src/lparser.c +lua-5.1/src/lparser.h +lua-5.1/src/lstate.c +lua-5.1/src/lstate.h +lua-5.1/src/lstring.c +lua-5.1/src/lstring.h +lua-5.1/src/lstrlib.c +lua-5.1/src/ltable.c +lua-5.1/src/ltable.h +lua-5.1/src/ltablib.c +lua-5.1/src/ltm.c +lua-5.1/src/ltm.h +lua-5.1/src/lua.c +lua-5.1/src/luac.c +lua-5.1/src/luaconf.h +lua-5.1/src/lua.h +lua-5.1/src/lualib.h +lua-5.1/src/lundump.c +lua-5.1/src/lundump.h +lua-5.1/src/lvm.c +lua-5.1/src/lvm.h +lua-5.1/src/lzio.c +lua-5.1/src/lzio.h +lua-5.1/src/Makefile +lua-5.1/src/print.c +lua-5.1/test +lua-5.1/test/bisect.lua +lua-5.1/test/cf.lua +lua-5.1/test/echo.lua +lua-5.1/test/env.lua +lua-5.1/test/factorial.lua +lua-5.1/test/fibfor.lua +lua-5.1/test/fib.lua +lua-5.1/test/globals.lua +lua-5.1/test/hello.lua +lua-5.1/test/life.lua +lua-5.1/test/luac.lua +lua-5.1/test/printf.lua +lua-5.1/test/README +lua-5.1/test/readonly.lua +lua-5.1/test/sieve.lua +lua-5.1/test/sort.lua +lua-5.1/test/table.lua +lua-5.1/test/trace-calls.lua +lua-5.1/test/trace-globals.lua +lua-5.1/test/xd.lua END OF MANIFEST @@ -4,6 +4,9 @@ # == CHANGE THE SETTINGS BELOW TO SUIT YOUR ENVIRONMENT ======================= +# Your platform. See PLATS for possible values. +PLAT= none + # Where to install. The installation starts in the src directory, so take care # if INSTALL_TOP is not an absolute path. (Man pages are installed from the # doc directory.) @@ -24,6 +27,9 @@ INSTALL_DATA= cp # == END OF USER SETTINGS. NO NEED TO CHANGE ANYTHING BELOW THIS LINE ========= +# Convenience platforms targets. +PLATS= ansi bsd generic linux macosx mingw posix + # What to install. TO_BIN= lua luac TO_INC= lua.h luaconf.h lualib.h lauxlib.h ../etc/lua.hpp @@ -33,7 +39,9 @@ TO_MAN= lua.1 luac.1 # Lua version. Currently used only for messages. V= 5.1 -all clean: +all: $(PLAT) + +$(PLATS) clean: cd src; $(MAKE) $@ test: all @@ -49,27 +57,8 @@ install: all local: $(MAKE) install INSTALL_TOP=.. INSTALL_EXEC="cp -p" INSTALL_DATA="cp -p" -# convenience targets for usual platforms - -ansi: - cd src; $(MAKE) MYCFLAGS=-DLUA_ANSI - -linux: - cd src; $(MAKE) MYCFLAGS=-DLUA_USE_LINUX MYLIBS="-Wl,-E -ldl -lreadline -lhistory -lncurses" - -macosx: - cd src; $(MAKE) MYCFLAGS=-DLUA_USE_MACOSX - -posix: - cd src; $(MAKE) MYCFLAGS=-DLUA_USE_POSIX - -bsd: - cd src; $(MAKE) MYCFLAGS="-DLUA_USE_POSIX -DLUA_USE_DLOPEN" MYLIBS="-Wl,-E" - -mingw: - cd src; $(MAKE) "LUA_A=lua51.dll" "LUA_T=lua.exe" \ - "AR=gcc -shared -o" "RANLIB=strip --strip-unneeded" \ - "MYCFLAGS=-DLUA_BUILD_AS_DLL" "MYLIBS=" "MYLDFLAGS=-s" lua.exe +none: + @echo "Please choose a platform: $(PLATS)" # echo config parameters echo: @@ -80,6 +69,7 @@ echo: @echo "" @echo "These are the parameters currently set in Makefile to install Lua $V:" @echo "" + @echo "PLAT = $(PLAT)" @echo "INSTALL_TOP = $(INSTALL_TOP)" @echo "INSTALL_BIN = $(INSTALL_BIN)" @echo "INSTALL_INC = $(INSTALL_INC)" @@ -1,4 +1,4 @@ -This is Lua 5.1 (beta). +This is Lua 5.1. See HISTORY for a summary of changes since the last released version. * What is Lua? diff --git a/doc/contents.html b/doc/contents.html index 25dd0c5a..7b890342 100644 --- a/doc/contents.html +++ b/doc/contents.html @@ -14,12 +14,14 @@ Lua 5.1 Reference Manual <SMALL> <A HREF="http://www.lua.org/copyright.html">Copyright</A> -© 2005 Lua.org, PUC-Rio. All rights reserved. +© 2006 Lua.org, PUC-Rio. All rights reserved. </SMALL> <HR> +<H2>Contents</H2> <UL> -<LI><A HREF="#words">Word index</A> +<LI><A HREF="#quick">Quick index</A> +<P> <LI><A HREF="manual.html">Top</A> <LI><A HREF="manual.html#1">1 - Introduction</A> <LI><A HREF="manual.html#2">2 - The Language</A> @@ -82,20 +84,23 @@ Lua 5.1 Reference Manual <UL> <LI><A HREF="manual.html#5.1">5.1 - Basic Functions</A> <LI><A HREF="manual.html#5.2">5.2 - Coroutine Manipulation</A> -<LI><A HREF="manual.html#5.3">5.3 - Packages and Modules</A> +<LI><A HREF="manual.html#5.3">5.3 - Modules</A> <LI><A HREF="manual.html#5.4">5.4 - String Manipulation</A> <LI><A HREF="manual.html#5.5">5.5 - Table Manipulation</A> <LI><A HREF="manual.html#5.6">5.6 - Mathematical Functions</A> <LI><A HREF="manual.html#5.7">5.7 - Input and Output Facilities</A> <LI><A HREF="manual.html#5.8">5.8 - Operating System Facilities</A> -<LI><A HREF="manual.html#5.9">5.9 - The Reflexive Debug Interface</A> +<LI><A HREF="manual.html#5.9">5.9 - The Debug Library</A> </UL> <LI><A HREF="manual.html#6">6 - Lua Stand-alone</A> <LI><A HREF="manual.html#BNF">The Complete Syntax of Lua</A> </UL> -<H3><A NAME="words">Word index</A></H3> - +<H2><A NAME="quick">Quick index</A></H2> +<TABLE> +<TR VALIGN="top"> +<TD WIDTH="35%"> +<H3><A NAME="functions">Functions</A></H3> <A HREF="manual.html#pdf-_G">_G</A><BR> <A HREF="manual.html#pdf-_VERSION">_VERSION</A><BR> <A HREF="manual.html#pdf-assert">assert</A><BR> @@ -146,52 +151,83 @@ Lua 5.1 Reference Manual <A HREF="manual.html#pdf-load">load</A><BR> <A HREF="manual.html#pdf-loadfile">loadfile</A><BR> <A HREF="manual.html#pdf-loadstring">loadstring</A><BR> - -<A HREF="manual.html#luaL_Buffer">luaL_Buffer</A><BR> -<A HREF="manual.html#luaL_Reg">luaL_Reg</A><BR> -<A HREF="manual.html#luaL_addchar">luaL_addchar</A><BR> -<A HREF="manual.html#luaL_addlstring">luaL_addlstring</A><BR> -<A HREF="manual.html#luaL_addsize">luaL_addsize</A><BR> -<A HREF="manual.html#luaL_addstring">luaL_addstring</A><BR> -<A HREF="manual.html#luaL_addvalue">luaL_addvalue</A><BR> -<A HREF="manual.html#luaL_argcheck">luaL_argcheck</A><BR> -<A HREF="manual.html#luaL_argerror">luaL_argerror</A><BR> -<A HREF="manual.html#luaL_buffinit">luaL_buffinit</A><BR> -<A HREF="manual.html#luaL_callmeta">luaL_callmeta</A><BR> -<A HREF="manual.html#luaL_checkany">luaL_checkany</A><BR> -<A HREF="manual.html#luaL_checkint">luaL_checkint</A><BR> -<A HREF="manual.html#luaL_checkinteger">luaL_checkinteger</A><BR> -<A HREF="manual.html#luaL_checklong">luaL_checklong</A><BR> -<A HREF="manual.html#luaL_checklstring">luaL_checklstring</A><BR> -<A HREF="manual.html#luaL_checknumber">luaL_checknumber</A><BR> -<A HREF="manual.html#luaL_checkoption">luaL_checkoption</A><BR> -<A HREF="manual.html#luaL_checkstack">luaL_checkstack</A><BR> -<A HREF="manual.html#luaL_checkstring">luaL_checkstring</A><BR> -<A HREF="manual.html#luaL_checktype">luaL_checktype</A><BR> -<A HREF="manual.html#luaL_checkudata">luaL_checkudata</A><BR> -<A HREF="manual.html#luaL_error">luaL_error</A><BR> -<A HREF="manual.html#luaL_getmetafield">luaL_getmetafield</A><BR> -<A HREF="manual.html#luaL_getmetatable">luaL_getmetatable</A><BR> -<A HREF="manual.html#luaL_gsub">luaL_gsub</A><BR> -<A HREF="manual.html#luaL_loadbuffer">luaL_loadbuffer</A><BR> -<A HREF="manual.html#luaL_loadfile">luaL_loadfile</A><BR> -<A HREF="manual.html#luaL_loadstring">luaL_loadstring</A><BR> -<A HREF="manual.html#luaL_newmetatable">luaL_newmetatable</A><BR> -<A HREF="manual.html#luaL_newstate">luaL_newstate</A><BR> -<A HREF="manual.html#luaL_optint">luaL_optint</A><BR> -<A HREF="manual.html#luaL_optinteger">luaL_optinteger</A><BR> -<A HREF="manual.html#luaL_optlong">luaL_optlong</A><BR> -<A HREF="manual.html#luaL_optlstring">luaL_optlstring</A><BR> -<A HREF="manual.html#luaL_optnumber">luaL_optnumber</A><BR> -<A HREF="manual.html#luaL_optstring">luaL_optstring</A><BR> -<A HREF="manual.html#luaL_prepbuffer">luaL_prepbuffer</A><BR> -<A HREF="manual.html#luaL_pushresult">luaL_pushresult</A><BR> -<A HREF="manual.html#luaL_ref">luaL_ref</A><BR> -<A HREF="manual.html#luaL_register">luaL_register</A><BR> -<A HREF="manual.html#luaL_typename">luaL_typename</A><BR> -<A HREF="manual.html#luaL_typerror">luaL_typerror</A><BR> -<A HREF="manual.html#luaL_unref">luaL_unref</A><BR> -<A HREF="manual.html#luaL_where">luaL_where</A><BR> +<A HREF="manual.html#pdf-math.abs">math.abs</A><BR> +<A HREF="manual.html#pdf-math.acos">math.acos</A><BR> +<A HREF="manual.html#pdf-math.asin">math.asin</A><BR> +<A HREF="manual.html#pdf-math.atan">math.atan</A><BR> +<A HREF="manual.html#pdf-math.atan2">math.atan2</A><BR> +<A HREF="manual.html#pdf-math.ceil">math.ceil</A><BR> +<A HREF="manual.html#pdf-math.cos">math.cos</A><BR> +<A HREF="manual.html#pdf-math.cosh">math.cosh</A><BR> +<A HREF="manual.html#pdf-math.def">math.def</A><BR> +<A HREF="manual.html#pdf-math.exp">math.exp</A><BR> +<A HREF="manual.html#pdf-math.floor">math.floor</A><BR> +<A HREF="manual.html#pdf-math.fmod">math.fmod</A><BR> +<A HREF="manual.html#pdf-math.ldexp">math.ldexp</A><BR> +<A HREF="manual.html#pdf-math.log">math.log</A><BR> +<A HREF="manual.html#pdf-math.log10">math.log10</A><BR> +<A HREF="manual.html#pdf-math.pow">math.pow</A><BR> +<A HREF="manual.html#pdf-math.sin">math.sin</A><BR> +<A HREF="manual.html#pdf-math.sinh">math.sinh</A><BR> +<A HREF="manual.html#pdf-math.sqrt">math.sqrt</A><BR> +<A HREF="manual.html#pdf-math.tan">math.tan</A><BR> +<A HREF="manual.html#pdf-math.tanh">math.tanh</A><BR> +<A HREF="manual.html#pdf-module">module</A><BR> +<A HREF="manual.html#pdf-next">next</A><BR> +<A HREF="manual.html#pdf-os.clock">os.clock</A><BR> +<A HREF="manual.html#pdf-os.date">os.date</A><BR> +<A HREF="manual.html#pdf-os.difftime">os.difftime</A><BR> +<A HREF="manual.html#pdf-os.execute">os.execute</A><BR> +<A HREF="manual.html#pdf-os.exit">os.exit</A><BR> +<A HREF="manual.html#pdf-os.getenv">os.getenv</A><BR> +<A HREF="manual.html#pdf-os.remove">os.remove</A><BR> +<A HREF="manual.html#pdf-os.rename">os.rename</A><BR> +<A HREF="manual.html#pdf-os.setlocale">os.setlocale</A><BR> +<A HREF="manual.html#pdf-os.time">os.time</A><BR> +<A HREF="manual.html#pdf-os.tmpname">os.tmpname</A><BR> +<A HREF="manual.html#pdf-package.cpath">package.cpath</A><BR> +<A HREF="manual.html#pdf-package.loaded">package.loaded</A><BR> +<A HREF="manual.html#pdf-package.loadlib">package.loadlib</A><BR> +<A HREF="manual.html#pdf-package.path">package.path</A><BR> +<A HREF="manual.html#pdf-package.preload">package.preload</A><BR> +<A HREF="manual.html#pdf-package.seeall">package.seeall</A><BR> +<A HREF="manual.html#pdf-pairs">pairs</A><BR> +<A HREF="manual.html#pdf-pcall">pcall</A><BR> +<A HREF="manual.html#pdf-print">print</A><BR> +<A HREF="manual.html#pdf-rawequal">rawequal</A><BR> +<A HREF="manual.html#pdf-rawget">rawget</A><BR> +<A HREF="manual.html#pdf-rawset">rawset</A><BR> +<A HREF="manual.html#pdf-require">require</A><BR> +<A HREF="manual.html#pdf-select">select</A><BR> +<A HREF="manual.html#pdf-setfenv">setfenv</A><BR> +<A HREF="manual.html#pdf-setmetatable">setmetatable</A><BR> +<A HREF="manual.html#pdf-string.byte">string.byte</A><BR> +<A HREF="manual.html#pdf-string.char">string.char</A><BR> +<A HREF="manual.html#pdf-string.dump">string.dump</A><BR> +<A HREF="manual.html#pdf-string.find">string.find</A><BR> +<A HREF="manual.html#pdf-string.format">string.format</A><BR> +<A HREF="manual.html#pdf-string.gmatch">string.gmatch</A><BR> +<A HREF="manual.html#pdf-string.gsub">string.gsub</A><BR> +<A HREF="manual.html#pdf-string.len">string.len</A><BR> +<A HREF="manual.html#pdf-string.lower">string.lower</A><BR> +<A HREF="manual.html#pdf-string.match">string.match</A><BR> +<A HREF="manual.html#pdf-string.rep">string.rep</A><BR> +<A HREF="manual.html#pdf-string.reverse">string.reverse</A><BR> +<A HREF="manual.html#pdf-string.sub">string.sub</A><BR> +<A HREF="manual.html#pdf-string.upper">string.upper</A><BR> +<A HREF="manual.html#pdf-table.concat">table.concat</A><BR> +<A HREF="manual.html#pdf-table.insert">table.insert</A><BR> +<A HREF="manual.html#pdf-table.maxn">table.maxn</A><BR> +<A HREF="manual.html#pdf-table.remove">table.remove</A><BR> +<A HREF="manual.html#pdf-table.sort">table.sort</A><BR> +<A HREF="manual.html#pdf-tonumber">tonumber</A><BR> +<A HREF="manual.html#pdf-tostring">tostring</A><BR> +<A HREF="manual.html#pdf-type">type</A><BR> +<A HREF="manual.html#pdf-unpack">unpack</A><BR> +<A HREF="manual.html#pdf-xpcall">xpcall</A><BR> +</TD> +<TD> +<H3>API</H3> <A HREF="manual.html#lua_Alloc">lua_Alloc</A><BR> <A HREF="manual.html#lua_CFunction">lua_CFunction</A><BR> <A HREF="manual.html#lua_Debug">lua_Debug</A><BR> @@ -256,6 +292,7 @@ Lua 5.1 Reference Manual <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_pushstring">lua_pushstring</A><BR> +<A HREF="manual.html#lua_pushthread">lua_pushthread</A><BR> <A HREF="manual.html#lua_pushvalue">lua_pushvalue</A><BR> <A HREF="manual.html#lua_pushvfstring">lua_pushvfstring</A><BR> <A HREF="manual.html#lua_rawequal">lua_rawequal</A><BR> @@ -275,6 +312,7 @@ Lua 5.1 Reference Manual <A HREF="manual.html#lua_settable">lua_settable</A><BR> <A HREF="manual.html#lua_settop">lua_settop</A><BR> <A HREF="manual.html#lua_setupvalue">lua_setupvalue</A><BR> +<A HREF="manual.html#lua_status">lua_status</A><BR> <A HREF="manual.html#lua_toboolean">lua_toboolean</A><BR> <A HREF="manual.html#lua_tocfunction">lua_tocfunction</A><BR> <A HREF="manual.html#lua_tointeger">lua_tointeger</A><BR> @@ -285,89 +323,66 @@ Lua 5.1 Reference Manual <A HREF="manual.html#lua_tothread">lua_tothread</A><BR> <A HREF="manual.html#lua_touserdata">lua_touserdata</A><BR> <A HREF="manual.html#lua_type">lua_type</A><BR> +<A HREF="manual.html#lua_typename">lua_typename</A><BR> <A HREF="manual.html#lua_xmove">lua_xmove</A><BR> <A HREF="manual.html#lua_yield">lua_yield</A><BR> - -<A HREF="manual.html#pdf-math.abs">math.abs</A><BR> -<A HREF="manual.html#pdf-math.acos">math.acos</A><BR> -<A HREF="manual.html#pdf-math.asin">math.asin</A><BR> -<A HREF="manual.html#pdf-math.atan">math.atan</A><BR> -<A HREF="manual.html#pdf-math.atan2">math.atan2</A><BR> -<A HREF="manual.html#pdf-math.ceil">math.ceil</A><BR> -<A HREF="manual.html#pdf-math.cos">math.cos</A><BR> -<A HREF="manual.html#pdf-math.cosh">math.cosh</A><BR> -<A HREF="manual.html#pdf-math.def">math.def</A><BR> -<A HREF="manual.html#pdf-math.exp">math.exp</A><BR> -<A HREF="manual.html#pdf-math.floor">math.floor</A><BR> -<A HREF="manual.html#pdf-math.fmod">math.fmod</A><BR> -<A HREF="manual.html#pdf-math.ldexp">math.ldexp</A><BR> -<A HREF="manual.html#pdf-math.log">math.log</A><BR> -<A HREF="manual.html#pdf-math.log10">math.log10</A><BR> -<A HREF="manual.html#pdf-math.pow">math.pow</A><BR> -<A HREF="manual.html#pdf-math.sin">math.sin</A><BR> -<A HREF="manual.html#pdf-math.sinh">math.sinh</A><BR> -<A HREF="manual.html#pdf-math.sqrt">math.sqrt</A><BR> -<A HREF="manual.html#pdf-math.tan">math.tan</A><BR> -<A HREF="manual.html#pdf-math.tanh">math.tanh</A><BR> -<A HREF="manual.html#pdf-module">module</A><BR> -<A HREF="manual.html#pdf-next">next</A><BR> -<A HREF="manual.html#pdf-os.clock">os.clock</A><BR> -<A HREF="manual.html#pdf-os.date">os.date</A><BR> -<A HREF="manual.html#pdf-os.difftime">os.difftime</A><BR> -<A HREF="manual.html#pdf-os.execute">os.execute</A><BR> -<A HREF="manual.html#pdf-os.exit">os.exit</A><BR> -<A HREF="manual.html#pdf-os.getenv">os.getenv</A><BR> -<A HREF="manual.html#pdf-os.remove">os.remove</A><BR> -<A HREF="manual.html#pdf-os.rename">os.rename</A><BR> -<A HREF="manual.html#pdf-os.setlocale">os.setlocale</A><BR> -<A HREF="manual.html#pdf-os.time">os.time</A><BR> -<A HREF="manual.html#pdf-os.tmpname">os.tmpname</A><BR> -<A HREF="manual.html#pdf-package.cpath">package.cpath</A><BR> -<A HREF="manual.html#pdf-package.loaded">package.loaded</A><BR> -<A HREF="manual.html#pdf-package.loadlib">package.loadlib</A><BR> -<A HREF="manual.html#pdf-package.path">package.path</A><BR> -<A HREF="manual.html#pdf-package.preload">package.preload</A><BR> -<A HREF="manual.html#pdf-package.seeall">package.seeall</A><BR> -<A HREF="manual.html#pdf-pairs">pairs</A><BR> -<A HREF="manual.html#pdf-pcall">pcall</A><BR> -<A HREF="manual.html#pdf-print">print</A><BR> -<A HREF="manual.html#pdf-rawequal">rawequal</A><BR> -<A HREF="manual.html#pdf-rawget">rawget</A><BR> -<A HREF="manual.html#pdf-rawset">rawset</A><BR> -<A HREF="manual.html#pdf-require">require</A><BR> -<A HREF="manual.html#pdf-select">select</A><BR> -<A HREF="manual.html#pdf-setfenv">setfenv</A><BR> -<A HREF="manual.html#pdf-setmetatable">setmetatable</A><BR> -<A HREF="manual.html#pdf-string.byte">string.byte</A><BR> -<A HREF="manual.html#pdf-string.char">string.char</A><BR> -<A HREF="manual.html#pdf-string.dump">string.dump</A><BR> -<A HREF="manual.html#pdf-string.find">string.find</A><BR> -<A HREF="manual.html#pdf-string.format">string.format</A><BR> -<A HREF="manual.html#pdf-string.gmatch">string.gmatch</A><BR> -<A HREF="manual.html#pdf-string.gsub">string.gsub</A><BR> -<A HREF="manual.html#pdf-string.len">string.len</A><BR> -<A HREF="manual.html#pdf-string.lower">string.lower</A><BR> -<A HREF="manual.html#pdf-string.match">string.match</A><BR> -<A HREF="manual.html#pdf-string.rep">string.rep</A><BR> -<A HREF="manual.html#pdf-string.reverse">string.reverse</A><BR> -<A HREF="manual.html#pdf-string.sub">string.sub</A><BR> -<A HREF="manual.html#pdf-string.upper">string.upper</A><BR> -<A HREF="manual.html#pdf-table.concat">table.concat</A><BR> -<A HREF="manual.html#pdf-table.insert">table.insert</A><BR> -<A HREF="manual.html#pdf-table.maxn(table)">table.maxn(table)</A><BR> -<A HREF="manual.html#pdf-table.remove">table.remove</A><BR> -<A HREF="manual.html#pdf-table.sort">table.sort</A><BR> -<A HREF="manual.html#pdf-tonumber">tonumber</A><BR> -<A HREF="manual.html#pdf-tostring">tostring</A><BR> -<A HREF="manual.html#pdf-type">type</A><BR> -<A HREF="manual.html#pdf-unpack">unpack</A><BR> -<A HREF="manual.html#pdf-xpcall">xpcall</A><BR> +</TD> +<TD> +<H3>Auxiliary library</H3> +<A HREF="manual.html#luaL_Buffer">luaL_Buffer</A><BR> +<A HREF="manual.html#luaL_Reg">luaL_Reg</A><BR> +<A HREF="manual.html#luaL_addchar">luaL_addchar</A><BR> +<A HREF="manual.html#luaL_addlstring">luaL_addlstring</A><BR> +<A HREF="manual.html#luaL_addsize">luaL_addsize</A><BR> +<A HREF="manual.html#luaL_addstring">luaL_addstring</A><BR> +<A HREF="manual.html#luaL_addvalue">luaL_addvalue</A><BR> +<A HREF="manual.html#luaL_argcheck">luaL_argcheck</A><BR> +<A HREF="manual.html#luaL_argerror">luaL_argerror</A><BR> +<A HREF="manual.html#luaL_buffinit">luaL_buffinit</A><BR> +<A HREF="manual.html#luaL_callmeta">luaL_callmeta</A><BR> +<A HREF="manual.html#luaL_checkany">luaL_checkany</A><BR> +<A HREF="manual.html#luaL_checkint">luaL_checkint</A><BR> +<A HREF="manual.html#luaL_checkinteger">luaL_checkinteger</A><BR> +<A HREF="manual.html#luaL_checklong">luaL_checklong</A><BR> +<A HREF="manual.html#luaL_checklstring">luaL_checklstring</A><BR> +<A HREF="manual.html#luaL_checknumber">luaL_checknumber</A><BR> +<A HREF="manual.html#luaL_checkoption">luaL_checkoption</A><BR> +<A HREF="manual.html#luaL_checkstack">luaL_checkstack</A><BR> +<A HREF="manual.html#luaL_checkstring">luaL_checkstring</A><BR> +<A HREF="manual.html#luaL_checktype">luaL_checktype</A><BR> +<A HREF="manual.html#luaL_checkudata">luaL_checkudata</A><BR> +<A HREF="manual.html#luaL_error">luaL_error</A><BR> +<A HREF="manual.html#luaL_getmetafield">luaL_getmetafield</A><BR> +<A HREF="manual.html#luaL_getmetatable">luaL_getmetatable</A><BR> +<A HREF="manual.html#luaL_gsub">luaL_gsub</A><BR> +<A HREF="manual.html#luaL_loadbuffer">luaL_loadbuffer</A><BR> +<A HREF="manual.html#luaL_loadfile">luaL_loadfile</A><BR> +<A HREF="manual.html#luaL_loadstring">luaL_loadstring</A><BR> +<A HREF="manual.html#luaL_newmetatable">luaL_newmetatable</A><BR> +<A HREF="manual.html#luaL_newstate">luaL_newstate</A><BR> +<A HREF="manual.html#luaL_optint">luaL_optint</A><BR> +<A HREF="manual.html#luaL_optinteger">luaL_optinteger</A><BR> +<A HREF="manual.html#luaL_optlong">luaL_optlong</A><BR> +<A HREF="manual.html#luaL_optlstring">luaL_optlstring</A><BR> +<A HREF="manual.html#luaL_optnumber">luaL_optnumber</A><BR> +<A HREF="manual.html#luaL_optstring">luaL_optstring</A><BR> +<A HREF="manual.html#luaL_prepbuffer">luaL_prepbuffer</A><BR> +<A HREF="manual.html#luaL_pushresult">luaL_pushresult</A><BR> +<A HREF="manual.html#luaL_ref">luaL_ref</A><BR> +<A HREF="manual.html#luaL_register">luaL_register</A><BR> +<A HREF="manual.html#luaL_typename">luaL_typename</A><BR> +<A HREF="manual.html#luaL_typerror">luaL_typerror</A><BR> +<A HREF="manual.html#luaL_unref">luaL_unref</A><BR> +<A HREF="manual.html#luaL_where">luaL_where</A><BR> +</TD> +</TR> +</TABLE> <P> <HR> <SMALL> Last update: -Tue Nov 1 15:40:46 BRST 2005 +Tue Jan 10 10:10:22 BRST 2006 </SMALL> </BODY> @@ -1,5 +1,5 @@ -.\" $Id: lua.man,v 1.9 2005/09/02 16:29:34 lhf Exp $ -.TH LUA 1 "$Date: 2005/09/02 16:29:34 $" +.\" $Id: lua.man,v 1.11 2006/01/06 16:03:34 lhf Exp $ +.TH LUA 1 "$Date: 2006/01/06 16:03:34 $" .SH NAME lua \- Lua interpreter .SH SYNOPSIS @@ -45,9 +45,9 @@ The arguments in .B arg start at 0, which contains the string -.RI ` script '. +.RI ' script '. The index of the last argument is stored in -.BR "arg.n" . +.BR arg.n . The arguments given in the command line before .IR script , including the name of the interpreter, @@ -63,17 +63,17 @@ if it is defined. If the value of .B LUA_INIT is of the form -.RI `@ filename ', +.RI '@ filename ', then .I filename is executed. Otherwise, the string is assumed to be a Lua statement and is executed. .LP Options start with -.B \- +.B '\-' and are described below. You can use -.B "\--" +.B "'\--'" to signal the end of options. .LP If no arguments are given, @@ -96,11 +96,11 @@ a syntax error is found. So, one way to interrupt the reading of an incomplete statement is to force a syntax error: adding a -.B `;' +.B ';' in the middle of a statement is a sure way of forcing a syntax error (except inside multiline strings and comments; these must be closed explicitly). If a line starts with -.BR `=' , +.BR '=' , then .B lua displays the values of all the expressions in the remainder of the @@ -115,11 +115,10 @@ So, to change the prompts, set the corresponding variable 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 prompts are ``> '' and ``>> ''. +or on the command line +(but in this case you have to be careful with quotes +if the prompt string contains a space; otherwise you may confuse the shell.) +The default prompts are "> " and ">> ". .SH OPTIONS .TP .B \- @@ -141,14 +140,12 @@ enter interactive mode after .I script is executed. .TP -.BI \-l " module" +.BI \-l " name" call -.BI require( module ) +.BI require(' name ') before executing -.IR script. -Typically used to load libraries -(hence the letter -.IR l ). +.IR script . +Typically used to load libraries. .TP .B \-v show version information. diff --git a/doc/lua.html b/doc/lua.html index 3bc0d8ae..5900321f 100644 --- a/doc/lua.html +++ b/doc/lua.html @@ -1,4 +1,4 @@ -<!-- $Id: lua.man,v 1.9 2005/09/02 16:29:34 lhf Exp $ --> +<!-- $Id: lua.man,v 1.11 2006/01/06 16:03:34 lhf Exp $ --> <HTML> <HEAD> <TITLE>LUA man page</TITLE> @@ -7,9 +7,9 @@ <BODY BGCOLOR="#FFFFFF"> -<H1>NAME</H1> +<H2>NAME</H2> lua - Lua interpreter -<H1>SYNOPSIS</H1> +<H2>SYNOPSIS</H2> <B>lua</B> [ <I>options</I> @@ -20,7 +20,7 @@ lua - Lua interpreter <I>args</I> ] ] -<H1>DESCRIPTION</H1> +<H2>DESCRIPTION</H2> <B>lua</B> is the stand-alone Lua interpreter. It loads and executes Lua programs, @@ -52,9 +52,9 @@ The arguments in <B>arg</B> start at 0, which contains the string -`<I>script</I>'. +'<I>script</I>'. The index of the last argument is stored in -<B>"arg.n"</B>. +<B>arg.n</B>. The arguments given in the command line before <I>script</I>, including the name of the interpreter, @@ -70,17 +70,17 @@ if it is defined. If the value of <B>LUA_INIT</B> is of the form -`@<I>filename</I>', +'@<I>filename</I>', then <I>filename</I> is executed. Otherwise, the string is assumed to be a Lua statement and is executed. <P> Options start with -<B>-</B> +<B>'-'</B> and are described below. You can use -<B>"--"</B> +<B>'--'</B> to signal the end of options. <P> If no arguments are given, @@ -103,11 +103,11 @@ a syntax error is found. So, one way to interrupt the reading of an incomplete statement is to force a syntax error: adding a -<B>`;' </B> +<B>';'</B> in the middle of a statement is a sure way of forcing a syntax error (except inside multiline strings and comments; these must be closed explicitly). If a line starts with -<B>`='</B>, +<B>'='</B>, then <B>lua</B> displays the values of all the expressions in the remainder of the @@ -122,12 +122,11 @@ So, to change the prompts, set the corresponding variable 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 prompts are ``> '' and ``>> ''. -<H1>OPTIONS</H1> +or on the command line +(but in this case you have to be careful with quotes +if the prompt string contains a space; otherwise you may confuse the shell.) +The default prompts are "> " and ">> ". +<H2>OPTIONS</H2> <P> <B>-</B> load and execute the standard input as a file, @@ -135,7 +134,7 @@ that is, not interactively, even when the standard input is a terminal. <P> -<B>-e "</B><I>stat"</I> +<B>-e </B><I>stat</I> execute statement <I>stat</I>. You need to quote @@ -148,24 +147,22 @@ enter interactive mode after <I>script</I> is executed. <P> -<B>-l "</B><I>module"</I> +<B>-l </B><I>name</I> call -<B>require( module</B><I>)</I> +<B>require(' name</B><I>')</I> before executing -<I></I>script. -Typically used to load libraries -(hence the letter -<I>l</I>). +<I>script</I>. +Typically used to load libraries. <P> <B>-v</B> show version information. -<H1>SEE ALSO</H1> +<H2>SEE ALSO</H2> <B>luac</B>(1) <BR> <A HREF="http://www.lua.org/">http://www.lua.org/</A> -<H1>DIAGNOSTICS</H1> +<H2>DIAGNOSTICS</H2> Error messages should be self explanatory. -<H1>AUTHORS</H1> +<H2>AUTHORS</H2> R. Ierusalimschy, L. H. de Figueiredo, and @@ -1,5 +1,5 @@ -.\" $Id: luac.man,v 1.26 2005/09/02 16:29:34 lhf Exp $ -.TH LUAC 1 "$Date: 2005/09/02 16:29:34 $" +.\" $Id: luac.man,v 1.28 2006/01/06 16:03:34 lhf Exp $ +.TH LUAC 1 "$Date: 2006/01/06 16:03:34 $" .SH NAME luac \- Lua compiler .SH SYNOPSIS @@ -17,7 +17,7 @@ into binary files that can be latter loaded and executed. .LP The main advantages of precompiling chunks are: faster loading, -protecting source code from user changes, +protecting source code from accidental user changes, and off-line syntax checking. .LP @@ -26,6 +26,13 @@ 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 +Pre-compiled chunks are not necessarily smaller than the corresponding source. +The main goal in pre-compiling is faster loading. +.LP +The binary files created by +.B luac +are portable only among architectures with the same word size and byte order. +.LP .B luac produces a single output file containing the bytecodes for all source files given. @@ -36,10 +43,6 @@ but you can change this with the .B \-o option. .LP -The binary files created by -.B luac -are portable only among architectures with the same word size and byte order. -.LP In the command line, you can mix text files containing Lua source and @@ -49,14 +52,14 @@ even from different (but compatible) platforms, into a single precompiled chunk. .LP You can use -.B "\-" +.B "'\-'" to indicate the standard input as a source file and -.B "\--" +.B "'\--'" to signal the end of options (that is, all remaining arguments will be treated as files even if they start with -.BR "\-" ). +.BR "'\-'" ). .LP The internal format of the binary files produced by .B luac @@ -81,6 +84,10 @@ output to .IR file , instead of the default .BR luac.out . +(You can use +.B "'\-'" +for standard output, +but not on platforms that open standard output in text mode.) The output file may be a source file because all files are loaded before the output file is written. Be careful not to overwrite precious files. @@ -105,9 +112,10 @@ No messages are displayed if the file passes the integrity test. .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 may not contain the full information they usually do -(line numbers and names of locals are lost). +but if errors occur when running a stripped chunk, +then the error messages may not contain the full information they usually do. +For instance, +line numbers and names of local variables are lost. .TP .B \-v show version information. diff --git a/doc/luac.html b/doc/luac.html index 586b38e8..3ecdfdf0 100644 --- a/doc/luac.html +++ b/doc/luac.html @@ -1,4 +1,4 @@ -<!-- $Id: luac.man,v 1.26 2005/09/02 16:29:34 lhf Exp $ --> +<!-- $Id: luac.man,v 1.28 2006/01/06 16:03:34 lhf Exp $ --> <HTML> <HEAD> <TITLE>LUAC man page</TITLE> @@ -7,16 +7,16 @@ <BODY BGCOLOR="#FFFFFF"> -<H1>NAME</H1> +<H2>NAME</H2> luac - Lua compiler -<H1>SYNOPSIS</H1> +<H2>SYNOPSIS</H2> <B>luac</B> [ <I>options</I> ] [ <I>filenames</I> ] -<H1>DESCRIPTION</H1> +<H2>DESCRIPTION</H2> <B>luac</B> is the Lua compiler. It translates programs written in the Lua programming language @@ -24,7 +24,7 @@ into binary files that can be latter loaded and executed. <P> The main advantages of precompiling chunks are: faster loading, -protecting source code from user changes, +protecting source code from accidental user changes, and off-line syntax checking. <P> @@ -33,6 +33,13 @@ because in Lua chunks are always compiled into bytecodes before being executed. <B>luac</B> simply allows those bytecodes to be saved in a file for later execution. <P> +Pre-compiled chunks are not necessarily smaller than the corresponding source. +The main goal in pre-compiling is faster loading. +<P> +The binary files created by +<B>luac</B> +are portable only among architectures with the same word size and byte order. +<P> <B>luac</B> produces a single output file containing the bytecodes for all source files given. @@ -43,10 +50,6 @@ but you can change this with the <B>-o</B> option. <P> -The binary files created by -<B>luac</B> -are portable only among architectures with the same word size and byte order. -<P> In the command line, you can mix text files containing Lua source and @@ -56,14 +59,14 @@ even from different (but compatible) platforms, into a single precompiled chunk. <P> You can use -<B>"-"</B> +<B>'-'</B> to indicate the standard input as a source file and -<B>"--"</B> +<B>'--'</B> to signal the end of options (that is, all remaining arguments will be treated as files even if they start with -<B>"-"</B>). +<B>'-'</B>). <P> The internal format of the binary files produced by <B>luac</B> @@ -71,7 +74,7 @@ is likely to change when a new version of Lua is released. So, save the source files of all Lua programs that you precompile. <P> -<H1>OPTIONS</H1> +<H2>OPTIONS</H2> Options must be separate. <P> <B>-l</B> @@ -83,11 +86,15 @@ loads <B>luac.out</B> and lists its contents. <P> -<B>-o "</B><I>file"</I> +<B>-o </B><I>file</I> output to <I>file</I>, instead of the default <B>luac.out</B>. +(You can use +<B>'-'</B> +for standard output, +but not on platforms that open standard output in text mode.) The output file may be a source file because all files are loaded before the output file is written. Be careful not to overwrite precious files. @@ -112,23 +119,24 @@ No messages are displayed if the file passes the integrity test. <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 may not contain the full information they usually do -(line numbers and names of locals are lost). +but if errors occur when running a stripped chunk, +then the error messages may not contain the full information they usually do. +For instance, +line numbers and names of local variables are lost. <P> <B>-v</B> show version information. -<H1>FILES</H1> +<H2>FILES</H2> <P> <B>luac.out</B> default output file -<H1>SEE ALSO</H1> +<H2>SEE ALSO</H2> <B>lua</B>(1) <BR> <A HREF="http://www.lua.org/">http://www.lua.org/</A> -<H1>DIAGNOSTICS</H1> +<H2>DIAGNOSTICS</H2> Error messages should be self explanatory. -<H1>AUTHORS</H1> +<H2>AUTHORS</H2> L. H. de Figueiredo, R. Ierusalimschy and W. Celes diff --git a/doc/manual.html b/doc/manual.html index 293532f1..df42a932 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -8,9 +8,9 @@ <body bgcolor="#FFFFFF"> -<hr/> +<hr /> <h1> -<a href="http://www.lua.org/home.html"><img src="logo.gif" alt="[Lua logo]" border="0"/></a> +<a href="http://www.lua.org/home.html"><img src="logo.gif" alt="[Lua logo]" border="0" /></a> Lua 5.1 Reference Manual </h1> @@ -18,16 +18,15 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes <p> <small> <a href="http://www.lua.org/copyright.html">Copyright</a> -© 2005 Lua.org, PUC-Rio. All rights reserved. +© 2006 Lua.org, PUC-Rio. All rights reserved. </small> -<hr/> +<hr /> <p> <p> <!-- ====================================================================== --> - <a name="1"></a><h1>1 - Introduction</h1> <p>Lua is an extension programming language designed to support @@ -36,7 +35,7 @@ facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight -configuration language for any program that needs one. +scripting language for any program that needs one. Lua is implemented as a library, written in <em>clean</em> C (that is, in the common subset of ANSI C and C++). @@ -49,42 +48,21 @@ 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>The Lua distribution includes a stand-alone embedding program, -<code>lua</code>, that uses the Lua library to offer a complete Lua interpreter. +The Lua distribution includes a sample host program called <code>lua</code>, +which uses the Lua library to offer a complete, stand-alone Lua interpreter. <p>Lua is free software, and is provided as usual with no guarantees, -as stated in its copyright notice. +as stated in its license. The implementation described in this manual is available at Lua's official web site, <code>www.lua.org</code>. <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 Lua's web site. -<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. -<li> -R. Ierusalimschy, L. H. de Figueiredo, and W. Celes. -The evolution of an extension language: a history of Lua, -<em>Proceedings of V Brazilian Symposium on Programming Languages</em> (2001) B-14--B-28. -</ul> - -<p>Lua means "moon" in Portuguese and is pronounced LOO-ah. +see the technical papers available at Lua's web site. +For a detailed introduction to programming in Lua, +see Roberto's book, <em>Programming in Lua</em>. <p> <a name="language"></a><a name="2"></a><h1>2 - The Language</h1> @@ -96,7 +74,7 @@ which tokens are valid, how they can be combined, and what their combinations mean. -<p>The language constructs will be explained using the usual extended BNF, +<p>The language constructs will be explained using the usual extended BNF notation, in which {<em>a</em>} means 0 or more <em>a</em>'s, and [<em>a</em>] means an optional <em>a</em>. @@ -104,16 +82,20 @@ Non-terminals are shown in <em>italics</em>, keywords are shown in <b>bold</b>, and other terminal symbols are shown in <code>typewriter</code> font, enclosed in single quotes. +The complete syntax of Lua can be found at the end of this manual. <p><a name="lexical"></a><a name="2.1"></a><h2>2.1 - Lexical Conventions</h2> -<p><em>Names</em> in Lua can be any string of letters, +<p><em>Names</em> +(also called <em>identifiers</em>) +in Lua can be any string of letters, digits, and underscores, not beginning with a digit. This coincides with the definition of names in most languages. (The definition of letter depends on the current locale: any character considered alphabetic by the current locale can be used in an identifier.) +Identifiers are used to name variables and table fields. <p>The following <em>keywords</em> are reserved and cannot be used as names: @@ -130,7 +112,7 @@ and cannot be used as names: are two different, valid names. As a convention, names starting with an underscore followed by uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>) -are reserved for internal variables used by Lua. +are reserved for internal global variables used by Lua. <p>The following strings denote other tokens: <pre> @@ -152,8 +134,8 @@ and can contain the following C-like escape sequences: <li><b><code>\t</code></b> --- horizontal tab <li><b><code>\v</code></b> --- vertical tab <li><b><code>\\</code></b> --- backslash -<li><b><code>\"</code></b> --- quotation mark -<li><b><code>\'</code></b> --- apostrophe +<li><b><code>\"</code></b> --- quotation mark (double quote) +<li><b><code>\'</code></b> --- apostrophe (single quote) </ul> Moreover, a `<code>\</code><em>newline</em>´ (that is, a backslash followed by a real newline) @@ -161,38 +143,51 @@ results in a newline in the string. A character in a string may also be specified by its numerical value using the escape sequence `<code>\</code><em>ddd</em>´, where <em>ddd</em> is a sequence of up to three decimal digits. +(Note that if a numerical escape is to be followed by a digit, +it must be expressed using exactly three digits.) Strings in Lua may contain any 8-bit value, including embedded zeros, which can be specified as `<code>\0</code>´. +<p>To put a double (single) quote, a newline, a backslash, +or an embedded zero +inside a literal string enclosed by double (single) quotes +you must use an escape sequence. +Any other character may be directly inserted into the literal. +(Some control characters may cause problems for the file system, +but Lua has no problem with them.) + <p>Literal strings can also be defined using a long format -enclosed by <em>l-brackets</em> (long brackets). -We define an <em>opening l-bracket of level <em>n</em></em> as an opening +enclosed by <em>long brackets</em>. +We define an <em>opening long bracket of level <em>n</em></em> as an opening square bracket followed by <em>n</em> equal signs followed by another opening square bracket. -So, an opening l-bracket of level 0 is written as <code>[[</code>, -an opening l-bracket of level 1 is written as <code>[=[</code>, +So, an opening long bracket of level 0 is written as <code>[[</code>, +an opening long bracket of level 1 is written as <code>[=[</code>, and so on. -A <em>closing l-bracket</em> is defined similarly; -for instance, a closing l-bracket of level 4 is written as <code>]====]</code>. -A long string starts with an opening l-bracket of any level and -ends at the first closing l-bracket of the same level. +A <em>closing long bracket</em> is defined similarly; +for instance, a closing long bracket of level 4 is written as <code>]====]</code>. +A long string starts with an opening long bracket of any level and +ends at the first closing long bracket of the same level. Literals in this bracketed form may run for several lines, do not interpret any escape sequences, -and ignore l-brackets of any other level. +and ignore long brackets of any other level. +They may contain anything except a closing bracket of the proper level +or embedded zeros. <p>For convenience, -when the opening l-bracket is immediately followed by a newline, +when the opening long bracket is immediately followed by a newline, the newline is not included in the string. As an example, in a system using ASCII (in which `<code>a</code>´ is coded as 97, newline is coded as 10, and `<code>1</code>´ is coded as 49), the four literals below denote the same string: <pre> - (1) "alo\n123\"" - (2) '\97lo\10\04923"' - (3) [[alo + (1) 'alo\n123"' + (2) "alo\n123\"" + (3) '\97lo\10\04923"' + (4) [[alo 123"]] - (4) [==[ + (5) [==[ alo 123"]==] </pre> @@ -204,13 +199,14 @@ Examples of valid numerical constants are 3 3.0 3.1416 314.16e-2 0.31416E1 </pre> -<p><em>Comments</em> start anywhere outside a string with a -double hyphen (<code>--</code>). -If the text immediately after <code>--</code> is not an opening l-bracket, +<p><em>Comments</em> start with a double hyphen (<code>--</code>) +anywhere outside a string. +If the text immediately after <code>--</code> is not an opening long bracket, the comment is a <em>short comment</em>, which runs until the end of the line. Otherwise, it is a <em>long comment</em>, -which runs until the corresponding closing l-bracket. +which runs until the corresponding closing long bracket. +Long comments are frequently used to disable code temporarily. <p><a name="TypesSec"></a><a name="2.2"></a><h2>2.2 - Values and Types</h2> @@ -220,15 +216,19 @@ variables do not have types; only values do. There are no type definitions in the language. All values carry their own type. +<p>All values in Lua are <em>first-class values</em>. +That means that all values can be stored in variables, +passed as arguments to other functions, and returned as results. + <p>There are eight basic types in Lua: <em>nil</em>, <em>boolean</em>, <em>number</em>, <em>string</em>, <em>function</em>, <em>userdata</em>, <em>thread</em>, and <em>table</em>. <em>Nil</em> is the type of the value <b>nil</b>, whose main property is to be different from any other value; -usually it represents the absence of a useful value. +it usually represents the absence of a useful value. <em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>. -In Lua, both <b>nil</b> and <b>false</b> make a condition false; +Both <b>nil</b> and <b>false</b> make a condition false; any other value makes it true. <em>Number</em> represents real (double-precision floating-point) numbers. (It is easy to build Lua interpreters that use other @@ -239,12 +239,9 @@ See file <code>luaconf.h</code>.) Lua is 8-bit clean: Strings may contain any 8-bit character, -including embedded zeros (<code>'\0'</code>) (see <a href="#lexical">2.1</a>). +including embedded zeros (`<code>\0</code>´) (see <a href="#lexical">2.1</a>). -<p>Functions are <em>first-class values</em> in Lua. -That 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 +<p>Lua can call (and manipulate) functions written in Lua and functions written in C (see <a href="#functioncall">2.5.8</a>). @@ -262,12 +259,14 @@ This guarantees the integrity of data owned by the host program. <p>The type <em>thread</em> represents independent threads of execution and it is used to implement coroutines (see <a href="#coroutine">2.11</a>). +Do not confuse Lua threads with operating-system threads. +Lua supports coroutines on all systems, +even those that do not support threads. <p>The type <em>table</em> implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value (except <b>nil</b>). -Moreover, -tables can be <em>heterogeneous</em>, +Tables can be <em>heterogeneous</em>; that is, they can contain values of all types (except <b>nil</b>). Tables are the sole data structuring mechanism in Lua; they may be used to represent ordinary arrays, @@ -281,11 +280,11 @@ There are several convenient ways to create tables in Lua <p>Like indices, the value of a table field can be of any type (except <b>nil</b>). In particular, -because functions are first class values, +because functions are first-class values, table fields may contain functions. Thus tables may also carry <em>methods</em> (see <a href="#func-def">2.5.9</a>). -<p>Tables, functions, and userdata values are <em>objects</em>: +<p>Strings, tables, functions, and userdata values are <em>objects</em>: variables do not actually <em>contain</em> these values, only <em>references</em> to them. Assignment, parameter passing, and function returns @@ -300,7 +299,7 @@ of a given value. <p>Lua provides automatic conversion between string and number values at run time. Any arithmetic operation applied to a string tries to convert -that string to a number, following the usual rules. +that string to a number, following the usual conversion rules. Conversely, whenever a number is used where a string is expected, the number is converted to a string, in a reasonable format. For complete control of how numbers are converted to strings, @@ -315,12 +314,14 @@ There are three kinds of variables in Lua: global variables, local variables, and table fields. <p>A single name can denote a global variable or a local variable -(or a formal parameter of a function, -which is a particular form of local variable): +(or a function formal parameter, +which is a particular kind of local variable): <pre> var ::= Name </pre> -Variables are assumed to be global unless explicitly declared local +Name denotes identifiers, as defined in (see <a href="#lexical">2.1</a>). + +<p>Variables are assumed to be global unless explicitly declared local (see <a href="#localvar">2.4.7</a>). Local variables are <em>lexically scoped</em>: Local variables can be freely accessed by functions @@ -334,12 +335,12 @@ defined inside their scope (see <a href="#visibility">2.6</a>). </pre> The first expression (<em>prefixexp</em>) should result in a table value; the second expression (<em>exp</em>) -identifies a specific entry inside that table. +identifies a specific entry in that table. The expression denoting the table to be indexed has a restricted syntax; see <a href="#expressions">2.5</a> for details. -<p>The syntax <code>var.NAME</code> is just syntactic sugar for -<code>var["NAME"]</code>: +<p>The syntax <code>var.Name</code> is just syntactic sugar for +<code>var["Name"]</code> and is used to denote table fields: <pre> var ::= prefixexp `<b>.</b>´ Name </pre> @@ -361,8 +362,10 @@ so that all global variables in that function will refer to that environment table. When a function is created, it inherits the environment from the function that created it. -To replace or get the environment table of a Lua function, -you call <a href="#pdf-setfenv"><code>setfenv</code></a> or <a href="#pdf-getfenv"><code>getfenv</code></a>. +To get the environment table of a Lua function, +you call <a href="#pdf-setfenv"><code>setfenv</code></a>. +To replace it, +you call <a href="#pdf-setfenv"><code>setfenv</code></a>. (You can only manipulate the environment of C functions through the debug library; (see <a href="#libdebug">5.9</a>).) @@ -384,7 +387,7 @@ We use them here only for explanatory purposes.) <p>Lua supports an almost conventional set of statements, similar to those in Pascal or C. This set includes -assignment, control structures, procedure calls, +assignment, control structures, function calls, table constructors, and variable declarations. <p><a name="chunks"></a><a name="2.4.1"></a><h3>2.4.1 - Chunks</h3> @@ -396,6 +399,7 @@ Each statement can be optionally followed by a semicolon: <pre> chunk ::= {stat [`<b>;</b>´]} </pre> +There are no empty statements and thus `<code>;;</code>´ is not legal. <p>Lua handles a chunk as the body of an anonymous function with a variable number of arguments @@ -404,7 +408,7 @@ As such, chunks can define local variables, receive arguments, and return values. <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 opcodes for +When a chunk is executed, first it is pre-compiled into instructions for a virtual machine, and then the compiled code is executed by an interpreter for the virtual machine. @@ -417,7 +421,7 @@ Lua automatically detects the file type and acts accordingly. <p><a name="2.4.2"></a><h3>2.4.2 - Blocks</h3> A block is a list of statements; -syntactically, a block is equal to a chunk: +syntactically, a block is the same as a chunk: <pre> block ::= chunk </pre> @@ -455,7 +459,7 @@ the excess values are thrown away. If there are fewer values than needed, the list is extended with as many <b>nil</b>'s as needed. If the list of expressions ends with a function call, -then all values returned by that function call enter in the list of values, +then all values returned by that call enter in the list of values, before the adjustment (except when the call is enclosed in parentheses; see <a href="#expressions">2.5</a>). @@ -509,7 +513,7 @@ familiar syntax: </pre> Lua also has a <b>for</b> statement, in two flavors (see <a href="#for">2.4.5</a>). -<p>The condition expression <em>exp</em> of a +<p>The condition expression of a control structure may return any value. Both <b>false</b> and <b>nil</b> are considered false. All values different from <b>nil</b> and <b>false</b> are considered true @@ -518,11 +522,11 @@ All values different from <b>nil</b> and <b>false</b> are considered true <p>In the <b>repeat</b>--<b>until</b> loop, the inner block does not end at the <b>until</b> keyword, but only after the condition. -That means the condition can refer to local variables -declared inside the loop. +So, the condition can refer to local variables +declared inside the loop block. <p>The <b>return</b> statement is used to return values -from a function or from a chunk. +from a function or a chunk (which is just a function). Functions and chunks may return more than one value, so the syntax for the <b>return</b> statement is @@ -530,7 +534,7 @@ so the syntax for the <b>return</b> statement is stat ::= <b>return</b> [explist1] </pre> -<p>The <b>break</b> statement can be used to terminate the execution of a +<p>The <b>break</b> statement is used to terminate the execution of a <b>while</b>, <b>repeat</b>, or <b>for</b> loop, skipping to the next statement after the loop: @@ -539,7 +543,7 @@ skipping to the next statement after the loop: </pre> A <b>break</b> ends the innermost enclosing loop. -<p>For syntactic reasons, <b>return</b> and <b>break</b> +<p>The <b>return</b> and <b>break</b> statements can only be written as the <em>last</em> statement of a block. If it is really necessary to <b>return</b> or <b>break</b> in the middle of a block, @@ -599,11 +603,12 @@ then assign it to another variable before breaking or exiting the loop. <p>The generic <b>for</b> statement works over functions, called <em>iterators</em>. -For each iteration, it calls its iterator function to produce a new value, -stopping when the new value is <b>nil</b>. +On each iteration, the iterator function is called to produce a new value, +stopping when this new value is <b>nil</b>. The generic <b>for</b> loop has the following syntax: <pre> - stat ::= <b>for</b> Name {`<b>,</b>´ Name} <b>in</b> explist1 <b>do</b> block <b>end</b> + stat ::= <b>for</b> namelist <b>in</b> explist1 <b>do</b> block <b>end</b> + namelist ::= Name {`<b>,</b>´ Name} </pre> A <b>for</b> statement like <pre> @@ -649,14 +654,13 @@ Local variables may be declared anywhere inside a block. The declaration may include an initial assignment: <pre> stat ::= <b>local</b> namelist [`<b>=</b>´ explist1] - namelist ::= Name {`<b>,</b>´ Name} </pre> If present, an initial assignment has the same semantics of a multiple assignment (see <a href="#assignment">2.4.3</a>). Otherwise, all variables are initialized with <b>nil</b>. <p>A chunk is also a block (see <a href="#chunks">2.4.1</a>), -so local variables can be declared in a chunk outside any explicit block. +and so local variables can be declared in a chunk outside any explicit block. The scope of such local variables extends until the end of the chunk. <p>The visibility rules for local variables are explained in <a href="#visibility">2.6</a>. @@ -669,7 +673,7 @@ The basic expressions in Lua are the following: exp ::= prefixexp exp ::= <b>nil</b> | <b>false</b> | <b>true</b> exp ::= Number - exp ::= Literal + exp ::= String exp ::= function exp ::= tableconstructor exp ::= `<b>...</b>´ @@ -684,7 +688,7 @@ function definitions are explained in <a href="#func-def">2.5.9</a>; function calls are explained in <a href="#functioncall">2.5.8</a>; table constructors are explained in <a href="#tableconstructor">2.5.7</a>. Vararg expressions, -denoted by three dots (...), can only be used inside +denoted by three dots (`<code>...</code>´), can only be used inside vararg functions; they are explained in <a href="#func-def">2.5.9</a>. @@ -738,18 +742,18 @@ or <b>nil</b> if <code>f</code> does not return any values.) Lua supports the usual arithmetic operators: the binary <code>+</code> (addition), <code>-</code> (subtraction), <code>*</code> (multiplication), -<code>/</code> (division), <code>%</code> (modulus), and <code>^</code> (exponentiation); +<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation); and unary <code>-</code> (negation). If the operands are numbers, or strings that can be converted to numbers (see <a href="#coercion">2.2.1</a>), then all operations have the usual meaning. Exponentiation works for any exponent. -For instance, <code>x^-0.5</code> computes the inverse of the square root of <code>x</code>. +For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>. Modulus is defined as <pre> - a % b == a - math.floor(a/b)*b + a % b == a - math.floor(a/b)*b </pre> -That is, it is the remaining of a division that rounds +That is, it is the remainder of a division that rounds the quotient towards minus infinity. <p><a name="rel-ops"></a><a name="2.5.2"></a><h3>2.5.2 - Relational Operators</h3> @@ -766,11 +770,12 @@ Numbers and strings are compared in the usual way. Objects (tables, userdata, threads, and functions) are compared by <em>reference</em>: Two objects are considered equal only if they are the <em>same</em> object. -Every time you create a new object (a table, userdata, or function), +Every time you create a new object +(a table, userdata, thread, or function), this new object is different from any previously existing object. <p>You can change the way that Lua compares tables and userdata -using the "eq" metamethod (see <a href="#metatable">2.8</a>). +by using the "eq" metamethod (see <a href="#metatable">2.8</a>). <p>The conversion rules of <a href="#coercion">2.2.1</a> <em>do not</em> apply to equality comparisons. @@ -799,27 +804,29 @@ all logical operators consider both <b>false</b> and <b>nil</b> as false and anything else as true. -<p>The operator <b>not</b> always returns <b>false</b> or <b>true</b>. - -<p>The conjunction operator <b>and</b> returns its first argument +<p>The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. +The conjunction operator <b>and</b> returns its first argument if this value is <b>false</b> or <b>nil</b>; otherwise, <b>and</b> returns its second argument. The disjunction operator <b>or</b> returns its first argument if this value is different from <b>nil</b> and <b>false</b>; otherwise, <b>or</b> returns its second argument. -Both <b>and</b> and <b>or</b> use short-cut evaluation, +Both <b>and</b> and <b>or</b> use short-cut evaluation; that is, the second operand is evaluated only if necessary. -For example, +Here are some examples: <pre> - 10 or error() -> 10 - nil or "a" -> "a" - nil and 10 -> nil - false and error() -> false - false and nil -> false - false or nil -> nil - 10 and 20 -> 20 + 10 or 20 --> 10 + 10 or error() --> 10 + nil or "a" --> "a" + nil and 10 --> nil + false and error() --> false + false and nil --> false + false or nil --> nil + 10 and 20 --> 20 </pre> +(Here and in the sequel, +`<code>--></code>´ indicates the result of the preceding expression.) <p><a name="concat"></a><a name="2.5.4"></a><h3>2.5.4 - Concatenation</h3> The string concatenation operator in Lua is @@ -830,21 +837,22 @@ Otherwise, the "concat" metamethod is called (see <a href="#metatable">2.8</a>). <p><a name="len-op"></a><a name="2.5.5"></a><h3>2.5.5 - The Length Operator</h3> -<p>The length operator is denoted by the prefix <code>#</code>. +<p>The length operator is denoted by the unary operator <code>#</code>. The length of a string is its number of bytes (that is, the usual meaning of string length when each character is one byte). -The length of a table <code>t</code> is defined to be any + +<p>The length of a table <code>t</code> is defined to be any integer index <code>n</code> such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>; moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> may be zero. - -<p>For a regular array, with non-nil values from 1 to a given <code>n</code>, +For a regular array, with non-nil values from 1 to a given <code>n</code>, its length is exactly that <code>n</code>, the index of its last value. If the array has "holes" (that is, <b>nil</b> values between other non-nil values), -then <code>#t</code> may be any of the indices that precede a <b>nil</b> value +then <code>#t</code> may be any of the indices that +directly precedes a <b>nil</b> value (that is, it may consider any such <b>nil</b> value as the end of the array). @@ -861,7 +869,8 @@ from lower to higher priority: not # - (unary) ^ </pre> -You can use parentheses to change the precedences of an expression. +As usual, +you can use parentheses to change the precedences of an expression. The concatenation (`<code>..</code>´) and exponentiation (`<code>^</code>´) operators are right associative. All other binary operators are left associative. @@ -889,20 +898,20 @@ starting with 1. Fields in the other formats do not affect this counting. For example, <pre> - a = {[f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45} + a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } </pre> is equivalent to <pre> do - local temp = {} - temp[f(1)] = g - temp[1] = "x" -- 1st exp - temp[2] = "y" -- 2nd exp - temp.x = 1 -- temp["x"] = 1 - temp[3] = f(x) -- 3rd exp - temp[30] = 23 - temp[4] = 45 -- 4th exp - a = temp + local t = {} + t[f(1)] = g + t[1] = "x" -- 1st exp + t[2] = "y" -- 2nd exp + t.x = 1 -- t["x"] = 1 + t[3] = f(x) -- 3rd exp + t[30] = 23 + t[4] = 45 -- 4th exp + a = t end </pre> @@ -927,7 +936,7 @@ first <em>prefixexp</em> and <em>args</em> are evaluated. If the value of <em>prefixexp</em> has type <em>function</em>, then that function is called with the given arguments. -Otherwise, its "call" metamethod is called, +Otherwise, the <em>prefixexp</em> "call" metamethod is called, having as first parameter the value of <em>prefixexp</em>, followed by the original call arguments (see <a href="#metatable">2.8</a>). @@ -945,16 +954,14 @@ except that <code>v</code> is evaluated only once. <pre> args ::= `<b>(</b>´ [explist1] `<b>)</b>´ args ::= tableconstructor - args ::= Literal + args ::= String </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 argument list is a single new table. +A call of the form <code>f{...}</code> is syntactic sugar for <code>f({...})</code>; +that is, 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 argument list is a single literal string. +(or <code>f"..."</code> or <code>f[[...]]</code>) is syntactic sugar for <code>f('...')</code>; +that is, the argument list is a single literal string. <p>As an exception to the free-format syntax of Lua, you cannot put a line break before the `<code>(</code>´ in a function call. @@ -964,7 +971,7 @@ If you write a = f (g).x(a) </pre> -Lua would read that as <code>a = f(g).x(a)</code>. +Lua would see that as a single statement, <code>a = f(g).x(a)</code>. So, if you want two statements, you must add a semi-colon between them. If you actually want to call <code>f</code>, you must remove the line break before <code>(g)</code>. @@ -981,15 +988,15 @@ However, a tail call erases any debug information about the calling function. Note that a tail call only happens with a particular syntax, where the <b>return</b> has one single function call as argument; -this syntax makes the calling function returns exactly +this syntax makes the calling function return exactly the returns of the called function. -So, all the following examples are not tail calls: +So, none of the following examples are tail calls: <pre> - return (f(x)) -- results adjusted to 1 - return 2 * f(x) - return x, f(x) -- additional results - f(x); return -- results discarded - return x or f(x) -- results adjusted to 1 + return (f(x)) -- results adjusted to 1 + return 2 * f(x) + return x, f(x) -- additional results + f(x); return -- results discarded + return x or f(x) -- results adjusted to 1 </pre> <p><a name="func-def"></a><a name="2.5.9"></a><h3>2.5.9 - Function Definitions</h3> @@ -1030,6 +1037,12 @@ translates to <pre> local f; f = function () ... end </pre> +<em>not</em> this: +<pre> + local f = function () ... end +</pre> +(This only makes a difference when the body of the function +contains references to <code>f</code>.) <p>A function definition is an executable expression, whose value has type <em>function</em>. @@ -1084,10 +1097,10 @@ to the vararg expression: f(r(), 10) a=1, b=10 f(r()) a=1, b=2 - g(3) a=3, b=nil, ... -> (nothing) - g(3, 4) a=3, b=4, ... -> (nothing) - g(3, 4, 5, 8) a=3, b=4, ... -> 5 8 - g(5, r()) a=5, b=1, ... -> 2 3 + g(3) a=3, b=nil, ... --> (nothing) + g(3, 4) a=3, b=4, ... --> (nothing) + g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 + g(5, r()) a=5, b=1, ... --> 2 3 </pre> <p>Results are returned using the <b>return</b> statement (see <a href="#control">2.4.4</a>). @@ -1114,36 +1127,29 @@ is syntactic sugar for The scope of variables begins at the first statement <em>after</em> their declaration and lasts until the end of the innermost block that includes the declaration. -For instance: -<pre> - x = 10 -- global variable - do -- new block - local x = x -- new `x', with value 10 - print(x) --> 10 - x = x+1 - do -- another block - local x = x+1 -- another `x' - print(x) --> 12 - end - print(x) --> 11 - end - print(x) --> 10 (the global one) +Consider the following example: +<pre> + x = 10 -- global variable + do -- new block + local x = x -- new `x', with value 10 + print(x) --> 10 + x = x+1 + do -- another block + local x = x+1 -- another `x' + print(x) --> 12 + end + print(x) --> 11 + end + print(x) --> 10 (the global one) </pre> -Notice that, in a declaration like <code>local x = x</code>, + +<p>Notice that, in a declaration like <code>local x = x</code>, the new <code>x</code> being declared is not in scope yet, and so the second <code>x</code> refers to the outside variable. <p>Because of the lexical scoping rules, local variables can be freely accessed by functions defined inside their scope. -For instance: -<pre> - local counter = 0 - function inc (x) - counter = counter + x - return counter - end -</pre> A local variable used by an inner function is called an <em>upvalue</em>, or <em>external local variable</em>, inside the inner function. @@ -1152,12 +1158,12 @@ inside the inner function. defines new local variables. Consider the following example: <pre> - a = {} - local x = 20 - for i=1,10 do - local y = 0 - a[i] = function () y=y+1; return x+y end - end + a = {} + local x = 20 + for i=1,10 do + local y = 0 + a[i] = function () y=y+1; return x+y end + end </pre> The loop creates ten closures (that is, ten instances of the anonymous function). @@ -1166,13 +1172,13 @@ while all of them share the same <code>x</code>. <p><a name="error"></a><a name="2.7"></a><h2>2.7 - Error Handling</h2> -<p>Because Lua is an extension language, +<p>Because Lua is an embedded extension language, all Lua actions start from C code in the host program calling a function from the Lua library (see <a href="#lua_pcall"></a>). Whenever an error occurs during Lua compilation or execution, control returns to C, which can take appropriate measures -(such as print an error message). +(such as printing an error message). <p>Lua code can explicitly generate an error by calling the <a href="#pdf-error"><code>error</code></a> function. @@ -1215,7 +1221,7 @@ So, there is one single metatable for all numbers, and for all strings, etc. <p>A metatable may control how an object behaves in arithmetic operations, -order comparisons, concatenation, and indexing. +order comparisons, concatenation, length operation, and indexing. A metatable can also define a function to be called when a userdata is garbage collected. For each of those operations Lua associates a specific key @@ -1228,7 +1234,7 @@ controls how Lua will perform the operation. <p>Metatables control the operations listed next. Each operation is identified by its corresponding name. The key for each operation is a string with its name prefixed by -two underscores; +two underscores, `<code>__</code>´; for instance, the key for operation "add" is the string <code>"__add"</code>. The semantics of these operations is better explained by a Lua function @@ -1243,11 +1249,11 @@ are described in <a href="#predefined">5.1</a>. In particular, to retrieve the metamethod of a given object, we use the expression <pre> - metatable(obj)[event] + metatable(obj)[event] </pre> This should be read as <pre> - rawget(metatable(obj) or {}, event) + rawget(getmetatable(obj) or {}, event) </pre> That is, the access to a metamethod does not invoke other metamethods, and the access to objects with no metatables does not fail @@ -1522,11 +1528,11 @@ called when Lua calls a value. <p>Besides metatables, objects of types thread, function, and userdata have another table associated with them, -called <em>environment</em>. +called their <em>environment</em>. Like metatables, environments are regular tables and multiple objects can share the same environment. -<p>Environments associated with userdata has no meaning for Lua. +<p>Environments associated with userdata have no meaning for Lua. It is only a feature for programmers to associate a table to a userdata. @@ -1557,10 +1563,10 @@ use the C API. <p><a name="GC"></a><a name="2.10"></a><h2>2.10 - Garbage Collection</h2> -<p>Lua does automatic memory management. +<p>Lua performs automatic memory management. That means that you do not have to worry about allocating memory for new objects -and freeing it when the objects are no longer needed. +not about freeing it when the objects are no longer needed. Lua manages memory automatically by running a <em>garbage collector</em> from time to time to collect all <em>dead objects</em> @@ -1568,9 +1574,12 @@ to collect all <em>dead objects</em> All objects in Lua are subject to automatic management: tables, userdata, functions, threads, and strings. -<p>Lua 5.1 implements an incremental mark-and-sweep collector. -It uses two numbers to control its garbage-collection cycles. -One number, the <em>garbage-collector pause</em>, +<p>Lua implements an incremental mark-and-sweep collector. +It uses two numbers to control its garbage-collection cycles: +the <em>garbage-collector pause</em> and +the <em>garbage-collector multiplier</em>. + +<p>The garbage-collector pause controls how long the collector waits before starting a new cycle. Larger values make the collector less aggressive. Values smaller than 1 mean the collector will not wait to @@ -1578,7 +1587,7 @@ start a new cycle. A value of 2 means that the collector waits more or less to double the total memory in use before starting a new cycle. -<p>The other number, the <em>garbage-collector multiplier</em>, +<p>The garbage-collector multiplier controls the relative speed of the collector relative to memory allocation. Larger values make the collector more aggressive but also increases @@ -1605,7 +1614,7 @@ with external resource management (such as closing files, network or database connections, or freeing your own memory). -<p>Free userdata with a field <code>__gc</code> in their metatables are not +<p>Garbage userdata with a field <code>__gc</code> in their metatables are not collected immediately by the garbage collector. Instead, Lua puts them in a list. After the collection, @@ -1676,8 +1685,8 @@ passing as its first argument the thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, the coroutine starts its execution, at the first line of its main function. -Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are given as -parameters for the coroutine main function. +Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on +to the coroutine main function. After the coroutine starts running, it runs until it terminates or <em>yields</em>. @@ -1703,43 +1712,39 @@ it continues its execution from the point where it yielded, with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. -<p>The <code>coroutine.wrap</code> function creates a coroutine -like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, +<p>The <code>coroutine.wrap</code> function creates a coroutine, +just like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, but instead of returning the coroutine itself, it returns a function that, when called, resumes the coroutine. Any arguments passed to that function -go as extra arguments to resume. -The function returns all the values returned by resume, +go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. +<code>coroutine.wrap</code> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, except the first one (the boolean error code). Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, -this function does not catch errors; +<code>coroutine.wrap</code> does not catch errors; any error is propagated to the caller. <p>As an example, consider the next code: <pre> -function foo1 (a) +function foo (a) print("foo", a) return coroutine.yield(2*a) end co = coroutine.create(function (a,b) print("co-body", a, b) - local r = foo1(a+1) + local r = foo(a+1) print("co-body", r) local r, s = coroutine.yield(a+b, a-b) print("co-body", r, s) return b, "end" end) -a, b = coroutine.resume(co, 1, 10) -print("main", a, b) -a, b, c = coroutine.resume(co, "r") -print("main", a, b, c) -a, b, c = coroutine.resume(co, "x", "y") -print("main", a, b, c) -a, b = coroutine.resume(co, "x", "y") -print("main", a, b) +print("main", coroutine.resume(co, 1, 10)) +print("main", coroutine.resume(co, "r")) +print("main", coroutine.resume(co, "x", "y")) +print("main", coroutine.resume(co, "x", "y")) </pre> When you run it, it produces the following output: <pre> @@ -1767,10 +1772,10 @@ are declared in the header file <code>lua.h</code>. any facility in the API may be provided as a macro instead. All such macros use each of its arguments exactly once (except for the first argument, which is always a Lua state), -and so do not generate hidden side-effects. +and so do not generate any hidden side-effects. -<p>Like in most C libraries, -the Lua API functions do not check their arguments. +<p>As in most C libraries, +the Lua API functions do not check their arguments for validity or consistency. However, you can change this behavior by compiling Lua with a proper definition for the macro <code>luai_apicheck</code>, in file <code>luaconf.h</code>. @@ -1784,7 +1789,7 @@ Each element in this stack represents a Lua value <p>Whenever Lua calls C, the called function gets a new stack, which is independent of previous stacks and of stacks of C functions that are still active. -That stack initially contains any arguments to the C function, +That stack initially contains any arguments to the C function and it is where the C function pushes its results to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). @@ -1794,7 +1799,7 @@ 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); -a negative index represents an <em>offset</em> from the top of the stack. +a negative index represents an <em>offset</em> relative to the top of the stack. More specifically, if the stack has <em>n</em> elements, then index 1 represents the first element (that is, the element that was pushed onto the stack first) @@ -1811,6 +1816,8 @@ if it lies between 1 and the stack top <p><a name="3.2"></a><h2>3.2 - Stack Size</h2> <p>When you interact with Lua API, +you are responsible for ensuring consistency. +In particular, <em>you are responsible for controlling stack overflow</em>. You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> to grow the stack size. @@ -1828,7 +1835,7 @@ Such indices are called <em>acceptable indices</em>. More formally, we define an <em>acceptable index</em> as follows: <pre> - (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) + (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) </pre> Note that 0 is never an acceptable index. @@ -1837,8 +1844,8 @@ Note that 0 is never an acceptable index. <p>Unless otherwise noted, any function that accepts valid indices can also be called with <em>pseudo-indices</em>, -which represent some Lua values that are accessible to the C code -but are not in the stack. +which represent some Lua values that are accessible to C code +but which are not in the stack. Pseudo-indices are used to access the thread environment, the function environment, the registry, @@ -1861,11 +1868,12 @@ For instance, to access the value of a global variable, do <p>When a C function is created, it is possible to associate some values with it, thus creating a <em>C closure</em>; -these values are then accessible to the function whenever it is called +these values are called <em>upvalues</em> and are +accessible to the function whenever it is called (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>). <p>Whenever a C function is called, -its associated values are located at specific pseudo-indices. +its upvalues are located at specific pseudo-indices. Those pseudo-indices are produced by the macro <code>lua_upvalueindex</code>. The first value associated with a function is at position @@ -1877,13 +1885,14 @@ produces an acceptable (but invalid) index. <p><a name="registry"></a><a name="3.5"></a><h2>3.5 - Registry</h2> -<p>Lua provides a registry, +<p>Lua provides a <em>registry</em>, a pre-defined table that can be used by any C code to store whatever Lua value it needs to store. This table is always located at pseudo-index <code>LUA_REGISTRYINDEX</code>. Any C library can store data into this table, -as long as it chooses keys different from other libraries. +but it should take care to choose keys different from those used +by other libraries, to avoid collisions. Typically, you should use as key a string containing your library name or a light userdata with the address of a C object in your code. @@ -1894,9 +1903,13 @@ and therefore should not be used by other purposes. <p><a name="3.6"></a><h2>3.6 - Error Handling in C</h2> <p>Internally, Lua uses the C <code>longjmp</code> facility to handle errors. +(You can also choose to use exceptions if you use C++; +See file <code>luaconf.h</code>.) When Lua faces any error -(such as memory allocation errors, type errors, syntax errors) -it <em>raises</em> an error, that is, it does a long jump. +(such as memory allocation errors, type errors, syntax errors, +and runtime errors) +it <em>raises</em> an error; +that is, it does a long jump. A <em>protected environment</em> uses <code>setjmp</code> to set a recover point; any error jumps to the most recent active recover point. @@ -1909,7 +1922,7 @@ so they never raise an error: <a href="#lua_newstate"><code>lua_newstate</code></a>, <a href="#lua_close"><code>lua_close</code></a>, <a href="#lua_load"><code>lua_load</code></a>, <a href="#lua_pcall"><code>lua_pcall</code></a>, and <a href="#lua_cpcall"><code>lua_cpcall</code></a>. -<p>Inside a C function you can raise an error calling <a href="#lua_error"><code>lua_error</code></a>. +<p>Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. <p><a name="3.7"></a><h2>3.7 - Functions and Types</h2> @@ -1917,7 +1930,7 @@ so they never raise an error: alphabetical order. <p><a name="lua_Alloc"></a> -<hr/><h3><code>lua_Alloc</code></h3> +<hr /><h3><code>lua_Alloc</code></h3> <pre> typedef void * (*lua_Alloc) (void *ud, void *ptr, @@ -1927,12 +1940,12 @@ alphabetical order. </pre> -<p>The allocator function used by Lua states. +<p>The type of the memory allocation function used by Lua states. The allocator function must provide a functionality similar to <code>realloc</code>, but not exactly the same. -Its arguments are <code>ud</code>, -the opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; +Its arguments are +<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; <code>ptr</code>, a pointer to the block being allocated/reallocated/freed; <code>osize</code>, the original size of the block; <code>nsize</code>, the new size of the block. @@ -1943,30 +1956,30 @@ it should free the block pointed by <code>ptr</code>. When <code>nsize</code> is not zero, the allocator returns <code>NULL</code> if and only if it cannot fill the request. When <code>nsize</code> is not zero and <code>osize</code> is zero, -the allocator behaves like <code>malloc</code>. +the allocator should behave like <code>malloc</code>. When <code>nsize</code> and <code>osize</code> are not zero, the allocator behaves like <code>realloc</code>. Lua assumes that the allocator never fails when <code>osize >= nsize</code>. -<p>A simple implementation for the allocator function -could be like this: +<p>Here is a simple implementation for the allocator function. +It is used in the auxiliary library by <a href="#lua_newstate"><code>lua_newstate</code></a>. <pre> static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { (void)ud; /* not used */ (void)osize; /* not used */ if (nsize == 0) { - free(ptr); /* ANSI ensures that free(NULL) has no effect */ + free(ptr); /* ANSI requires that free(NULL) has no effect */ return NULL; } else - /* ANSI ensures that realloc(NULL, size) == malloc(size) */ + /* ANSI requires that realloc(NULL, size) == malloc(size) */ return realloc(ptr, nsize); } </pre> <p><a name="lua_atpanic"></a> -<hr/><h3><code>lua_atpanic</code></h3> +<hr /><h3><code>lua_atpanic</code></h3> <pre> lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); </pre> @@ -1976,14 +1989,15 @@ static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { <p>If an error happens outside any protected environment, Lua calls a <em>panic function</em> -and then calls <code>exit(EXIT_FAILURE)</code>. -Your new panic function may avoid the application exit by +and then calls <code>exit(EXIT_FAILURE)</code>, +thus exiting the host application. +Your panic function may avoid this exit by never returning (e.g., doing a long jump). <p>The panic function can access the error message at the top of the stack. <p><a name="lua_call"></a> -<hr/><h3><code>lua_call</code></h3> +<hr /><h3><code>lua_call</code></h3> <pre> void lua_call (lua_State *L, int nargs, int nresults); </pre> @@ -1994,18 +2008,20 @@ never returning (e.g., doing a long jump). <p>To call a function you must use the following protocol: First, the function to be called is pushed onto the stack; then, the arguments to the function are pushed -in direct order, that is, the first argument is pushed first. +in direct order; +that is, the first argument is pushed first. Finally you call <a href="#lua_call"><code>lua_call</code></a>; <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 to <code>nresults</code>, +All arguments and the function value are popped from the stack +when the function is called. +The function results are pushed onto the stack when the function returns. +The number of results is adjusted to <code>nresults</code>, unless <code>nresults</code> is <code>LUA_MULTRET</code>. In that case, <em>all</em> results from the function are pushed. Lua takes care that the returned values fit into the stack space. The function results are pushed onto the stack in direct order (the first result is pushed first), -so that after the call the last result is on the top. +so that after the call the last result is on the top of the stack. <p>Any error inside the called function is propagated upwards (with a <code>longjmp</code>). @@ -2017,21 +2033,21 @@ equivalent to this Lua code: </pre> Here it is in C: <pre> - lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* global `t' (for later use) */ lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */ lua_pushstring(L, "how"); /* 1st argument */ - lua_getfield(L, -3, "x"); /* push result of t.x (2nd arg) */ + lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */ + lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ + lua_remove(L, -2); /* remove `t' from the stack */ lua_pushinteger(L, 14); /* 3rd argument */ lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */ lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global variable `a' */ - lua_pop(L, 1); /* remove `t' from the stack */ </pre> Note that the code above is "balanced": at its end, the stack is back to its original configuration. This is considered good programming practice. <p><a name="lua_CFunction"></a> -<hr/><h3><code>lua_CFunction</code></h3> +<hr /><h3><code>lua_CFunction</code></h3> <pre> typedef int (*lua_CFunction) (lua_State *L); </pre> @@ -2040,17 +2056,19 @@ This is considered good programming practice. <p>Type for C functions. <p>In order to communicate properly with Lua, -a C function must follow the following protocol, +a C function must use the following protocol, which defines the way parameters and results are passed: A C function receives its arguments from Lua in its stack in direct order (the first argument is pushed first). So, when the function starts, -its first argument (if any) is at index 1. +<a href="#lua_gettop(L)"><code>lua_gettop(L)</code></a> returns the number of arguments received by the function. +The first argument (if any) is at index 1 +and its last argument is at index <a href="#lua_gettop(L)"><code>lua_gettop(L)</code></a>. 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. Any other value in the stack below the results will be properly -discharged by Lua. +discarded by Lua. Like a Lua function, a C function called by Lua can also return many results. @@ -2075,20 +2093,20 @@ of numerical arguments and returns their average and sum: </pre> <p><a name="lua_checkstack"></a> -<hr/><h3><code>lua_checkstack</code></h3> +<hr /><h3><code>lua_checkstack</code></h3> <pre> int lua_checkstack (lua_State *L, int extra); </pre> -<p>Grows the stack size to <code>top + extra</code> elements; +<p>Ensures that there are at least <code>extra</code> free stack slots in the stack. it returns false if it cannot grow the stack to that size. This function never shrinks the stack; if the stack is already larger than the new size, it is left unchanged. <p><a name="lua_close"></a> -<hr/><h3><code>lua_close</code></h3> +<hr /><h3><code>lua_close</code></h3> <pre> void lua_close (lua_State *L); </pre> @@ -2105,7 +2123,7 @@ might need to release states as soon as they are not needed, to avoid growing too large. <p><a name="lua_concat"></a> -<hr/><h3><code>lua_concat</code></h3> +<hr /><h3><code>lua_concat</code></h3> <pre> void lua_concat (lua_State *L, int n); </pre> @@ -2120,7 +2138,7 @@ Concatenation is done following the usual semantics of Lua (see <a href="#concat">2.5.4</a>). <p><a name="lua_cpcall"></a> -<hr/><h3><code>lua_cpcall</code></h3> +<hr /><h3><code>lua_cpcall</code></h3> <pre> int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); </pre> @@ -2133,10 +2151,10 @@ In case of errors, <a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>, plus the error object on the top of the stack; otherwise, it returns zero, and does not change the stack. -Any value returned by <code>func</code> is discarded. +All values returned by <code>func</code> are discarded. <p><a name="lua_createtable"></a> -<hr/><h3><code>lua_createtable</code></h3> +<hr /><h3><code>lua_createtable</code></h3> <pre> void lua_createtable (lua_State *L, int narr, int nrec); </pre> @@ -2144,25 +2162,26 @@ Any value returned by <code>func</code> is discarded. <p>Creates a new empty table and pushes it onto the stack. The new table has space pre-allocated -for <code>narr</code> array elements plus <code>nrec</code> non-array elements. +for <code>narr</code> array elements and <code>nrec</code> non-array elements. This pre-allocation is useful when you know exactly how many elements the table will have. Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. <p><a name="lua_dump"></a> -<hr/><h3><code>lua_dump</code></h3> +<hr /><h3><code>lua_dump</code></h3> <pre> int lua_dump (lua_State *L, lua_Writer writer, void *data); </pre> <p>Dumps a function as a binary chunk. -This function receives a Lua function on the top of the stack +Receives a Lua function on the top of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped. As it produces parts of the chunk, <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) +with the given <code>data</code> to write them. <p>The value returned is the error code returned by the last @@ -2172,7 +2191,7 @@ call to the writer; <p>This function does not pop the function from the stack. <p><a name="lua_equal"></a> -<hr/><h3><code>lua_equal</code></h3> +<hr /><h3><code>lua_equal</code></h3> <pre> int lua_equal (lua_State *L, int index1, int index2); </pre> @@ -2183,23 +2202,24 @@ call to the writer; following the semantics of the Lua <code>==</code> operator (that is, may call metamethods). Otherwise returns 0. -Also returns 0 if any of the indices are non valid. +Also returns 0 if any of the indices is non valid. <p><a name="lua_error"></a> -<hr/><h3><code>lua_error</code></h3> +<hr /><h3><code>lua_error</code></h3> <pre> int lua_error (lua_State *L); </pre> <p>Generates a Lua error. -The error message (which actually can be any type of object) +The error message (which can actually be a Lua value of any type) must be on the stack top. This function does a long jump, and therefore never returns. +(see <a href="#pdf-luaL_error"><code>luaL_error</code></a>). <p><a name="lua_gc"></a> -<hr/><h3><code>lua_gc</code></h3> +<hr /><h3><code>lua_gc</code></h3> <pre> int lua_gc (lua_State *L, int what, int data); </pre> @@ -2227,28 +2247,28 @@ you must tune experimentally the value of <code>data</code>. The function returns 1 if that step finished a garbage-collection cycle. <li> <code>LUA_GCSETPAUSE</code>--- -sets <em><code>data</code>/100</em> as the new value +sets <code>data</code>/100 as the new value for the <em>pause</em> of the collector (see <a href="#GC">2.10</a>). The function returns the previous value of the pause. <li> <code>LUA_GCSETSTEPMUL</code>--- -sets <em><code>arg</code>/100</em> as the new value for the <em>step multiplier</em> of +sets <code>arg</code>/100 as the new value for the <em>step multiplier</em> of the collector (see <a href="#GC">2.10</a>). The function returns the previous value of the step multiplier. </ul> <p><a name="lua_getallocf"></a> -<hr/><h3><code>lua_getallocf</code></h3> +<hr /><h3><code>lua_getallocf</code></h3> <pre> lua_Alloc lua_getallocf (lua_State *L, void **ud); </pre> -<p>Returns the allocator function of a given state. -If <code>ud</code> is not <code>NULL</code> Lua stores in <code>*ud</code> the +<p>Returns the memory allocator function of a given state. +If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. <p><a name="lua_getfenv"></a> -<hr/><h3><code>lua_getfenv</code></h3> +<hr /><h3><code>lua_getfenv</code></h3> <pre> void lua_getfenv (lua_State *L, int index); </pre> @@ -2258,7 +2278,7 @@ opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>. the value at the given index. <p><a name="lua_getfield"></a> -<hr/><h3><code>lua_getfield</code></h3> +<hr /><h3><code>lua_getfield</code></h3> <pre> void lua_getfield (lua_State *L, int index, const char *k); </pre> @@ -2270,7 +2290,7 @@ As in Lua, this function may trigger a metamethod for the "index" event (see <a href="#metatable">2.8</a>). <p><a name="lua_getmetatable"></a> -<hr/><h3><code>lua_getmetatable</code></h3> +<hr /><h3><code>lua_getmetatable</code></h3> <pre> int lua_getmetatable (lua_State *L, int index); </pre> @@ -2283,7 +2303,7 @@ or if the value does not have a metatable, returns 0 and pushes nothing on the stack. <p><a name="lua_gettable"></a> -<hr/><h3><code>lua_gettable</code></h3> +<hr /><h3><code>lua_gettable</code></h3> <pre> void lua_gettable (lua_State *L, int index); </pre> @@ -2299,7 +2319,7 @@ As in Lua, this function may trigger a metamethod for the "index" event (see <a href="#metatable">2.8</a>). <p><a name="lua_gettop"></a> -<hr/><h3><code>lua_gettop</code></h3> +<hr /><h3><code>lua_gettop</code></h3> <pre> int lua_gettop (lua_State *L); </pre> @@ -2311,7 +2331,7 @@ that result is equal to the number of elements in the stack (and so 0 means an empty stack). <p><a name="lua_insert"></a> -<hr/><h3><code>lua_insert</code></h3> +<hr /><h3><code>lua_insert</code></h3> <pre> void lua_insert (lua_State *L, int index); </pre> @@ -2323,7 +2343,7 @@ Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position. <p><a name="lua_Integer"></a> -<hr/><h3><code>lua_Integer</code></h3> +<hr /><h3><code>lua_Integer</code></h3> <pre> typedef ptrdiff_t lua_Integer; </pre> @@ -2332,11 +2352,11 @@ because a pseudo-index is not an actual stack position. <p>The type used by the Lua API to represent integral values. <p>By default it is a <code>ptrdiff_t</code>, -which is usually the largest type the machine handles +which is usually the largest integral type the machine handles "comfortably". <p><a name="lua_isboolean"></a> -<hr/><h3><code>lua_isboolean</code></h3> +<hr /><h3><code>lua_isboolean</code></h3> <pre> int lua_isboolean (lua_State *L, int index); </pre> @@ -2346,7 +2366,7 @@ which is usually the largest type the machine handles and 0 otherwise. <p><a name="lua_iscfunction"></a> -<hr/><h3><code>lua_iscfunction</code></h3> +<hr /><h3><code>lua_iscfunction</code></h3> <pre> int lua_iscfunction (lua_State *L, int index); </pre> @@ -2356,7 +2376,7 @@ and 0 otherwise. and 0 otherwise. <p><a name="lua_isfunction"></a> -<hr/><h3><code>lua_isfunction</code></h3> +<hr /><h3><code>lua_isfunction</code></h3> <pre> int lua_isfunction (lua_State *L, int index); </pre> @@ -2366,7 +2386,7 @@ and 0 otherwise. (either C or Lua), and 0 otherwise. <p><a name="lua_islightuserdata"></a> -<hr/><h3><code>lua_islightuserdata</code></h3> +<hr /><h3><code>lua_islightuserdata</code></h3> <pre> int lua_islightuserdata (lua_State *L, int index); </pre> @@ -2376,7 +2396,7 @@ and 0 otherwise. and 0 otherwise. <p><a name="lua_isnil"></a> -<hr/><h3><code>lua_isnil</code></h3> +<hr /><h3><code>lua_isnil</code></h3> <pre> int lua_isnil (lua_State *L, int index); </pre> @@ -2386,7 +2406,7 @@ and 0 otherwise. and 0 otherwise. <p><a name="lua_isnumber"></a> -<hr/><h3><code>lua_isnumber</code></h3> +<hr /><h3><code>lua_isnumber</code></h3> <pre> int lua_isnumber (lua_State *L, int index); </pre> @@ -2397,7 +2417,7 @@ or a string convertible to a number, and 0 otherwise. <p><a name="lua_isstring"></a> -<hr/><h3><code>lua_isstring</code></h3> +<hr /><h3><code>lua_isstring</code></h3> <pre> int lua_isstring (lua_State *L, int index); </pre> @@ -2408,7 +2428,7 @@ or a number (which is always convertible to a string), and 0 otherwise. <p><a name="lua_istable"></a> -<hr/><h3><code>lua_istable</code></h3> +<hr /><h3><code>lua_istable</code></h3> <pre> int lua_istable (lua_State *L, int index); </pre> @@ -2418,7 +2438,7 @@ and 0 otherwise. and 0 otherwise. <p><a name="lua_isthread"></a> -<hr/><h3><code>lua_isthread</code></h3> +<hr /><h3><code>lua_isthread</code></h3> <pre> int lua_isthread (lua_State *L, int index); </pre> @@ -2428,7 +2448,7 @@ and 0 otherwise. and 0 otherwise. <p><a name="lua_isuserdata"></a> -<hr/><h3><code>lua_isuserdata</code></h3> +<hr /><h3><code>lua_isuserdata</code></h3> <pre> int lua_isuserdata (lua_State *L, int index); </pre> @@ -2438,21 +2458,21 @@ and 0 otherwise. (either full or light), and 0 otherwise. <p><a name="lua_lessthan"></a> -<hr/><h3><code>lua_lessthan</code></h3> +<hr /><h3><code>lua_lessthan</code></h3> <pre> int lua_lessthan (lua_State *L, int index1, int index2); </pre> -<p>Returns 1 if the value in acceptable index <code>index1</code> is smaller -than the value in acceptable index <code>index2</code>, +<p>Returns 1 if the value at acceptable index <code>index1</code> is smaller +than the value at acceptable index <code>index2</code>, following the semantics of the Lua <code><</code> operator (that is, may call metamethods). Otherwise returns 0. -Also returns 0 if any of the indices are non valid. +Also returns 0 if any of the indices is non valid. <p><a name="lua_load"></a> -<hr/><h3><code>lua_load</code></h3> +<hr /><h3><code>lua_load</code></h3> <pre> int lua_load (lua_State *L, lua_Reader reader, void *data, const char *chunkname); @@ -2481,11 +2501,11 @@ and loads it accordingly (see program <code>luac</code>). (see <a href="#lua_Reader"><code>lua_Reader</code></a>). The <code>data</code> argument is an opaque value passed to the reader function. -<p>The <code>chunkname</code> argument gives the chunk name. -It is used for error messages and debug information (see <a href="#debugI">3.8</a>). +<p>The <code>chunkname</code> argument gives a name to the chunk, +which is used for error messages and in debug information (see <a href="#debugI">3.8</a>). <p><a name="lua_newstate"></a> -<hr/><h3><code>lua_newstate</code></h3> +<hr /><h3><code>lua_newstate</code></h3> <pre> lua_State *lua_newstate (lua_Alloc f, void *ud); </pre> @@ -2493,14 +2513,14 @@ It is used for error messages and debug information (see <a href="#debugI">3.8</ <p>Creates a new, independent state. Returns <code>NULL</code> if cannot create the state -(not enough memory). +(due to lack of memory). The argument <code>f</code> is the allocator function; Lua does all memory allocation for that state through that function. The second argument, <code>ud</code>, is an opaque pointer that Lua simply passes to the allocator in every call. <p><a name="lua_newtable"></a> -<hr/><h3><code>lua_newtable</code></h3> +<hr /><h3><code>lua_newtable</code></h3> <pre> void lua_newtable (lua_State *L); </pre> @@ -2510,7 +2530,7 @@ simply passes to the allocator in every call. Equivalent to <code>lua_createtable(L, 0, 0)</code>. <p><a name="lua_newthread"></a> -<hr/><h3><code>lua_newthread</code></h3> +<hr /><h3><code>lua_newthread</code></h3> <pre> lua_State *lua_newthread (lua_State *L); </pre> @@ -2520,14 +2540,14 @@ Equivalent to <code>lua_createtable(L, 0, 0)</code>. and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. The new state returned by this function shares with the original state all global objects (such as tables), -but has an independent run-time stack. +but has an independent execution stack. <p>There is no explicit function to close or to destroy a thread. Threads are subject to garbage collection, like any Lua object. <p><a name="lua_newuserdata"></a> -<hr/><h3><code>lua_newuserdata</code></h3> +<hr /><h3><code>lua_newuserdata</code></h3> <pre> void *lua_newuserdata (lua_State *L, size_t size); </pre> @@ -2544,21 +2564,22 @@ You must create it, it can have its own metatable, and you can detect when it is being collected. A full userdata is only equal to itself (under raw equality). -<p>When Lua collects a full userdata, -it calls the userdata's <code>gc</code> metamethod, if any, -and then it frees the userdata's corresponding memory. +<p>When Lua collects a full userdata with a <code>gc</code> metamethod, +Lua calls the metamethod and marks the userdata as finalized. +When that userdata is collected again then +Lua frees its corresponding memory. <p><a name="lua_next"></a> -<hr/><h3><code>lua_next</code></h3> +<hr /><h3><code>lua_next</code></h3> <pre> int lua_next (lua_State *L, int index); </pre> <p>Pops a key from the stack, -and pushes a key-value pair from the table +and pushes a key-value pair from the table at the given index (the "next" pair after the given key). -If there are no more elements, +If there are no more elements in the table, then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). <p>A typical traversal looks like this: @@ -2581,33 +2602,34 @@ the value at the given index; this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. <p><a name="lua_Number"></a> -<hr/><h3><code>lua_Number</code></h3> +<hr /><h3><code>lua_Number</code></h3> <pre> typedef double lua_Number; </pre> <p>The type of numbers in Lua. +By default, it is double, but that can be changed in <code>luaconf.h</code>. <p>Through the configuration file you can change Lua to operate with other type for numbers (e.g., float or long). <p><a name="lua_objlen"></a> -<hr/><h3><code>lua_objlen</code></h3> +<hr /><h3><code>lua_objlen</code></h3> <pre> size_t lua_objlen (lua_State *L, int index); </pre> <p>Returns the "length" of the value at the given acceptable index: -For strings, this is the string length; -for tables, this is the result of the length operator (`<code>#</code>´). +for strings, this is the string length; +for tables, this is the result of the length operator (`<code>#</code>´); for userdata, this is the size of the block of memory allocated -for the userdatum. -For other values, returns 0. +for the userdata; +for other values, it is 0. <p><a name="lua_pcall"></a> -<hr/><h3><code>lua_pcall</code></h3> +<hr /><h3><code>lua_pcall</code></h3> <pre> lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); </pre> @@ -2628,13 +2650,14 @@ Like <a href="#lua_call"><code>lua_call</code></a>, and its arguments from the stack. <p>If <code>errfunc</code> is 0, -then the error message returned is exactly the original error message. +then the error message returned on the stack +is exactly the original error message. Otherwise, <code>errfunc</code> is the stack index of an <em>error handler function</em>. (In the current implementation, that index cannot be a pseudo-index.) In case of runtime errors, that function will be called with the error message -and its return value will be the message returned by <a href="#lua_pcall"><code>lua_pcall</code></a>. +and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. <p>Typically, the error handler function is used to add more debug information to the error message, such as a stack traceback. @@ -2653,7 +2676,7 @@ error while running the error handler function. </ul> <p><a name="lua_pop"></a> -<hr/><h3><code>lua_pop</code></h3> +<hr /><h3><code>lua_pop</code></h3> <pre> void lua_pop (lua_State *L, int n); </pre> @@ -2662,7 +2685,7 @@ error while running the error handler function. <p>Pops <code>n</code> elements from the stack. <p><a name="lua_pushboolean"></a> -<hr/><h3><code>lua_pushboolean</code></h3> +<hr /><h3><code>lua_pushboolean</code></h3> <pre> void lua_pushboolean (lua_State *L, int b); </pre> @@ -2671,7 +2694,7 @@ error while running the error handler function. <p>Pushes a boolean value with value <code>b</code> onto the stack. <p><a name="lua_pushcclosure"></a> -<hr/><h3><code>lua_pushcclosure</code></h3> +<hr /><h3><code>lua_pushcclosure</code></h3> <pre> void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); </pre> @@ -2686,14 +2709,14 @@ these values are then accessible to the function whenever it is called. To associate values with a C function, first these values should be pushed onto the stack (when there are multiple values, the first value is pushed first). -Then the function <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> -is used to create and push the C function onto the stack, +Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> +is called to create and push the C function onto the stack, with the argument <code>n</code> telling how many values should be associated with the function. <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. <p><a name="lua_pushcfunction"></a> -<hr/><h3><code>lua_pushcfunction</code></h3> +<hr /><h3><code>lua_pushcfunction</code></h3> <pre> void lua_pushcfunction (lua_State *L, lua_CFunction f); </pre> @@ -2703,7 +2726,7 @@ associated with the function. This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. <p><a name="lua_pushfstring"></a> -<hr/><h3><code>lua_pushfstring</code></h3> +<hr /><h3><code>lua_pushfstring</code></h3> <pre> const char *lua_pushfstring (lua_State *L, const char *fmt, ...); </pre> @@ -2711,15 +2734,15 @@ This function is equivalent to <code>lua_pushcclosure(L, f, 0);</code>. <p>Pushes onto the stack a formatted string and returns a pointer to that string. -It is similar to the C function <code>sprintf</code> -but with some important differences: +It is similar to the C function <code>sprintf</code>, +but has some important differences: <ul> <li> You do not have to allocate the space for the result: The result is a Lua string and Lua takes care of memory allocation (and deallocation, through garbage collection). <li> The conversion specifiers are quite restricted. There are no flags, widths, or precisions. -The conversion specifiers can be simply +The conversion specifiers can only be `<code>%%</code>´ (inserts a `<code>%</code>´ in the string), `<code>%s</code>´ (inserts a zero-terminated string, with no size restrictions), `<code>%f</code>´ (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), @@ -2729,7 +2752,7 @@ The conversion specifiers can be simply </ul> <p><a name="lua_pushinteger"></a> -<hr/><h3><code>lua_pushinteger</code></h3> +<hr /><h3><code>lua_pushinteger</code></h3> <pre> void lua_pushinteger (lua_State *L, lua_Integer n); </pre> @@ -2738,7 +2761,7 @@ The conversion specifiers can be simply <p>Pushes a number with value <code>n</code> onto the stack. <p><a name="lua_pushlightuserdata"></a> -<hr/><h3><code>lua_pushlightuserdata</code></h3> +<hr /><h3><code>lua_pushlightuserdata</code></h3> <pre> void lua_pushlightuserdata (lua_State *L, void *p); </pre> @@ -2755,7 +2778,7 @@ A light userdata is equal to "any" light userdata with the same C address. <p><a name="lua_pushlstring"></a> -<hr/><h3><code>lua_pushlstring</code></h3> +<hr /><h3><code>lua_pushlstring</code></h3> <pre> void lua_pushlstring (lua_State *L, const char *s, size_t len); </pre> @@ -2766,9 +2789,10 @@ onto the stack. Lua makes (or reuses) an internal copy of the given string, so the memory at <code>s</code> can be freed or reused immediately after the function returns. +The string can contain embedded zeros. <p><a name="lua_pushnil"></a> -<hr/><h3><code>lua_pushnil</code></h3> +<hr /><h3><code>lua_pushnil</code></h3> <pre> void lua_pushnil (lua_State *L); </pre> @@ -2777,7 +2801,7 @@ the function returns. <p>Pushes a nil value onto the stack. <p><a name="lua_pushnumber"></a> -<hr/><h3><code>lua_pushnumber</code></h3> +<hr /><h3><code>lua_pushnumber</code></h3> <pre> void lua_pushnumber (lua_State *L, lua_Number n); </pre> @@ -2786,7 +2810,7 @@ the function returns. <p>Pushes a number with value <code>n</code> onto the stack. <p><a name="lua_pushstring"></a> -<hr/><h3><code>lua_pushstring</code></h3> +<hr /><h3><code>lua_pushstring</code></h3> <pre> void lua_pushstring (lua_State *L, const char *s); </pre> @@ -2797,9 +2821,20 @@ onto the stack. Lua makes (or reuses) an internal copy of the given string, so the memory at <code>s</code> can be freed or reused immediately after the function returns. +The string cannot embedded zeros; +it is assumed to end at the first zero. + +<p><a name="lua_pushthread"></a> +<hr /><h3><code>lua_pushthread</code></h3> +<pre> + void lua_pushthread (lua_State *L); +</pre> + + +<p>Pushes the thread represented by <code>L</code> onto the stack. <p><a name="lua_pushvalue"></a> -<hr/><h3><code>lua_pushvalue</code></h3> +<hr /><h3><code>lua_pushvalue</code></h3> <pre> void lua_pushvalue (lua_State *L, int index); </pre> @@ -2809,7 +2844,7 @@ the function returns. onto the stack. <p><a name="lua_pushvfstring"></a> -<hr/><h3><code>lua_pushvfstring</code></h3> +<hr /><h3><code>lua_pushvfstring</code></h3> <pre> const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp); </pre> @@ -2819,7 +2854,7 @@ onto the stack. instead of a variable number of arguments. <p><a name="lua_rawequal"></a> -<hr/><h3><code>lua_rawequal</code></h3> +<hr /><h3><code>lua_rawequal</code></h3> <pre> int lua_rawequal (lua_State *L, int index1, int index2); </pre> @@ -2832,17 +2867,17 @@ Otherwise returns 0. Also returns 0 if any of the indices are non valid. <p><a name="lua_rawget"></a> -<hr/><h3><code>lua_rawget</code></h3> +<hr /><h3><code>lua_rawget</code></h3> <pre> void lua_rawget (lua_State *L, int index); </pre> -<p>Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but doing a raw indexing +<p>Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access (i.e., without metamethods). <p><a name="lua_rawgeti"></a> -<hr/><h3><code>lua_rawgeti</code></h3> +<hr /><h3><code>lua_rawgeti</code></h3> <pre> void lua_rawgeti (lua_State *L, int index, int n); </pre> @@ -2850,36 +2885,36 @@ Also returns 0 if any of the indices are non valid. <p>Pushes onto the stack the value <code>t[n]</code>, where <code>t</code> is the value at the given valid index <code>index</code>. -The access is raw, +The access is raw; that is, it does not invoke metamethods. <p><a name="lua_rawset"></a> -<hr/><h3><code>lua_rawset</code></h3> +<hr /><h3><code>lua_rawset</code></h3> <pre> void lua_rawset (lua_State *L, int index); </pre> -<p>Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but doing a raw assignment +<p>Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment (i.e., without metamethods). <p><a name="lua_rawseti"></a> -<hr/><h3><code>lua_rawseti</code></h3> +<hr /><h3><code>lua_rawseti</code></h3> <pre> void lua_rawseti (lua_State *L, int index, int n); </pre> -<p>Does the equivalent to <code>t[n] = v</code>, +<p>Does the equivalent of <code>t[n] = v</code>, where <code>t</code> is the value at the given valid index <code>index</code> and <code>v</code> is the value at the top of the stack, <p>This function pops the value from the stack. -The assignment is raw, +The assignment is raw; that is, it does not invoke metamethods. <p><a name="lua_Reader"></a> -<hr/><h3><code>lua_Reader</code></h3> +<hr /><h3><code>lua_Reader</code></h3> <pre> typedef const char * (*lua_Reader) (lua_State *L, void *data, size_t *size); @@ -2894,11 +2929,12 @@ passing along its <code>data</code> parameter. The reader must return a pointer to a block of memory with a new piece of the chunk and set <code>size</code> to the block size. -To signal the end of the chunk, the reader returns <code>NULL</code>. +The block must exist until the reader function is called again. +To signal the end of the chunk, the reader must return <code>NULL</code>. The reader function may return pieces of any size greater than zero. <p><a name="lua_remove"></a> -<hr/><h3><code>lua_remove</code></h3> +<hr /><h3><code>lua_remove</code></h3> <pre> void lua_remove (lua_State *L, int index); </pre> @@ -2910,7 +2946,7 @@ Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position. <p><a name="lua_replace"></a> -<hr/><h3><code>lua_replace</code></h3> +<hr /><h3><code>lua_replace</code></h3> <pre> void lua_replace (lua_State *L, int index); </pre> @@ -2921,7 +2957,7 @@ without shifting any element (therefore replacing the value at the given position). <p><a name="lua_resume"></a> -<hr/><h3><code>lua_resume</code></h3> +<hr /><h3><code>lua_resume</code></h3> <pre> int lua_resume (lua_State *L, int narg); </pre> @@ -2931,7 +2967,7 @@ without shifting any element <p>To start a coroutine, you first create a new thread (see <a href="#lua_newthread"><code>lua_newthread</code></a>); -then you push on its stack the body function plus any eventual arguments; +then you push on its stack the main function plus any eventual arguments; then you call <a href="#lua_resume"><code>lua_resume</code></a>, with <code>narg</code> being the number of arguments. This call returns when the coroutine suspends or finishes its execution. @@ -2944,14 +2980,14 @@ without errors, or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). In case of errors, the stack is not unwound, -so you can use the debug API over it; +so you can use the debug API over it. The error message is on the top of the stack. To restart a coroutine, you put on its stack only the values to be passed as results from <code>yield</code>, and then call <a href="#lua_resume"><code>lua_resume</code></a>. <p><a name="lua_setallocf"></a> -<hr/><h3><code>lua_setallocf</code></h3> +<hr /><h3><code>lua_setallocf</code></h3> <pre> void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); </pre> @@ -2961,7 +2997,7 @@ and then call <a href="#lua_resume"><code>lua_resume</code></a>. with user data <code>ud</code>. <p><a name="lua_setfenv"></a> -<hr/><h3><code>lua_setfenv</code></h3> +<hr /><h3><code>lua_setfenv</code></h3> <pre> int lua_setfenv (lua_State *L, int index); </pre> @@ -2971,10 +3007,11 @@ with user data <code>ud</code>. the new environment for the value at the given index. If the value at the given index is neither a function nor a thread nor a userdata, -<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0 (false). +<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0. +Otherwise it returns 1. <p><a name="lua_setfield"></a> -<hr/><h3><code>lua_setfield</code></h3> +<hr /><h3><code>lua_setfield</code></h3> <pre> void lua_setfield (lua_State *L, int index, const char *k); </pre> @@ -2989,7 +3026,7 @@ As in Lua, this function may trigger a metamethod for the "newindex" event (see <a href="#metatable">2.8</a>). <p><a name="lua_setmetatable"></a> -<hr/><h3><code>lua_setmetatable</code></h3> +<hr /><h3><code>lua_setmetatable</code></h3> <pre> int lua_setmetatable (lua_State *L, int index); </pre> @@ -3000,7 +3037,7 @@ sets it as the new metatable for the value at the given acceptable index. <p><a name="lua_settable"></a> -<hr/><h3><code>lua_settable</code></h3> +<hr /><h3><code>lua_settable</code></h3> <pre> void lua_settable (lua_State *L, int index); </pre> @@ -3016,7 +3053,7 @@ As in Lua, this function may trigger a metamethod for the "newindex" event (see <a href="#metatable">2.8</a>). <p><a name="lua_settop"></a> -<hr/><h3><code>lua_settop</code></h3> +<hr /><h3><code>lua_settop</code></h3> <pre> void lua_settop (lua_State *L, int index); </pre> @@ -3029,7 +3066,7 @@ then the new elements are filled with <b>nil</b>. If <code>index</code> is 0, then all stack elements are removed. <p><a name="lua_State"></a> -<hr/><h3><code>lua_State</code></h3> +<hr /><h3><code>lua_State</code></h3> <pre> typedef struct lua_State lua_State; </pre> @@ -3044,8 +3081,21 @@ All information about a state is kept in this structure. every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, which creates a Lua state from scratch. +<p><a name="lua_status"></a> +<hr /><h3><code>lua_status</code></h3> +<pre> + int lua_status (lua_State *L); +</pre> + + +<p>Returns the status of the thread <code>L</code>. + +<p>The status can by 0 for a normal thread, +an error code if the thread finished its execution with an error, +or <code>LUA_YIELD</code> if the thread is suspended. + <p><a name="lua_toboolean"></a> -<hr/><h3><code>lua_toboolean</code></h3> +<hr /><h3><code>lua_toboolean</code></h3> <pre> int lua_toboolean (lua_State *L, int index); </pre> @@ -3058,11 +3108,11 @@ Like all tests in Lua, different from <b>false</b> and <b>nil</b>; otherwise it returns 0. It also returns 0 when called with a non-valid index. -(If you want to accept only real boolean values, +(If you want to accept only actual boolean values, use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) <p><a name="lua_tocfunction"></a> -<hr/><h3><code>lua_tocfunction</code></h3> +<hr /><h3><code>lua_tocfunction</code></h3> <pre> lua_CFunction lua_tocfunction (lua_State *L, int index); </pre> @@ -3073,7 +3123,7 @@ That value must be a C function; otherwise, returns <code>NULL</code>. <p><a name="lua_tointeger"></a> -<hr/><h3><code>lua_tointeger</code></h3> +<hr /><h3><code>lua_tointeger</code></h3> <pre> lua_Integer lua_tointeger (lua_State *L, int idx); </pre> @@ -3089,7 +3139,7 @@ otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0. it is truncated in some non-specified way. <p><a name="lua_tolstring"></a> -<hr/><h3><code>lua_tolstring</code></h3> +<hr /><h3><code>lua_tolstring</code></h3> <pre> const char *lua_tolstring (lua_State *L, int index, size_t *len); </pre> @@ -3105,11 +3155,11 @@ If the value is a number, then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also <em>changes the actual value in the stack to a string</em>. (This change confuses <a href="#lua_next"><code>lua_next</code></a> -when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys.) +when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.) <p><a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer to a string inside the Lua state. -This string always has a zero (<code>'\0'</code>) +This string always has a zero (`<code>\0</code>´) after its last character (as in C), but may contain other zeros in its body. Because Lua has garbage collection, @@ -3117,7 +3167,7 @@ there is no guarantee that the pointer returned by <a href="#lua_tolstring"><cod will be valid after the corresponding value is removed from the stack. <p><a name="lua_tonumber"></a> -<hr/><h3><code>lua_tonumber</code></h3> +<hr /><h3><code>lua_tonumber</code></h3> <pre> lua_Number lua_tonumber (lua_State *L, int index); </pre> @@ -3130,23 +3180,23 @@ The Lua value must be a number or a string convertible to number otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0. <p><a name="lua_topointer"></a> -<hr/><h3><code>lua_topointer</code></h3> +<hr /><h3><code>lua_topointer</code></h3> <pre> const void *lua_topointer (lua_State *L, int index); </pre> <p>Converts the value at the given acceptable index to a generic -C pointer (<code>void *</code>). +C pointer (<code>void*</code>). The value may be a userdata, a table, a thread, or a function; otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>. Lua ensures that different objects return different pointers. There is no direct way to convert the pointer back to its original value. -<p>Typically this function is used for debug information. +<p>Typically this function is used only for debug information. <p><a name="lua_tostring"></a> -<hr/><h3><code>lua_tostring</code></h3> +<hr /><h3><code>lua_tostring</code></h3> <pre> const char *lua_tostring (lua_State *L, int index); </pre> @@ -3155,19 +3205,19 @@ There is no direct way to convert the pointer back to its original value. <p>Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. <p><a name="lua_tothread"></a> -<hr/><h3><code>lua_tothread</code></h3> +<hr /><h3><code>lua_tothread</code></h3> <pre> lua_State *lua_tothread (lua_State *L, int index); </pre> <p>Converts the value at the given acceptable index to a Lua thread -(represented as <code>lua_State *</code>). +(represented as <code>lua_State*</code>). This value must be a thread; otherwise, the function returns <code>NULL</code>. <p><a name="lua_touserdata"></a> -<hr/><h3><code>lua_touserdata</code></h3> +<hr /><h3><code>lua_touserdata</code></h3> <pre> void *lua_touserdata (lua_State *L, int index); </pre> @@ -3180,7 +3230,7 @@ returns its pointer. Otherwise, returns <code>NULL</code>. <p><a name="lua_type"></a> -<hr/><h3><code>lua_type</code></h3> +<hr /><h3><code>lua_type</code></h3> <pre> int lua_type (lua_State *L, int index); </pre> @@ -3199,10 +3249,21 @@ defined in <code>lua.h</code>: <code>LUA_TFUNCTION</code>, <code>LUA_TUSERDATA</code>, <code>LUA_TTHREAD</code>, +and <code>LUA_TLIGHTUSERDATA</code>. +<p><a name="lua_typename"></a> +<hr /><h3><code>lua_typename</code></h3> +<pre> + const char *lua_typename (lua_State *L, int tp); +</pre> + + +<p>Returns the name of the type encoded by the value <code>tp</code>, +which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. + <p><a name="lua_Writer"></a> -<hr/><h3><code>lua_Writer</code></h3> +<hr /><h3><code>lua_Writer</code></h3> <pre> typedef int (*lua_Writer) (lua_State *L, const void* p, size_t sz, void* ud); @@ -3223,19 +3284,19 @@ any other value means an error and stops <a href="#lua_dump"><code>lua_dump</cod calling the writer again. <p><a name="lua_xmove"></a> -<hr/><h3><code>lua_xmove</code></h3> +<hr /><h3><code>lua_xmove</code></h3> <pre> void lua_xmove (lua_State *from, lua_State *to, int n); </pre> -<p>Exchange values between different threads of the same global state. +<p>Exchange values between different threads of the <em>same</em> global state. <p>This function pops <code>n</code> values from the stack <code>from</code>, and pushes them into the stack <code>to</code>. <p><a name="lua_yield"></a> -<hr/><h3><code>lua_yield</code></h3> +<hr /><h3><code>lua_yield</code></h3> <pre> int lua_yield (lua_State *L, int nresults); </pre> @@ -3243,7 +3304,7 @@ and pushes them into the stack <code>to</code>. <p>Yields a coroutine. -<p>This function can only be called as the +<p>This function should only be called as the return expression of a C function, as follows: <pre> return lua_yield (L, nresults); @@ -3265,20 +3326,19 @@ kinds of debuggers, profilers, and other tools that need "inside information" from the interpreter. <p><a name="lua_Debug"></a> -<hr/><h3><code>lua_Debug</code></h3> +<hr /><h3><code>lua_Debug</code></h3> <pre> typedef struct lua_Debug { int event; - const char *name; /* (n) */ - const char *namewhat; /* (n) */ - const char *what; /* (S) */ - const char *source; /* (S) */ - int currentline; /* (l) */ - int nups; /* (u) number of upvalues */ - int linedefined; /* (S) */ - int lastlinedefined; /* (S) */ + const char *name; /* (n) */ + const char *namewhat; /* (n) */ + const char *what; /* (S) */ + const char *source; /* (S) */ + int currentline; /* (l) */ + int nups; /* (u) number of upvalues */ + int linedefined; /* (S) */ + int lastlinedefined; /* (S) */ char short_src[LUA_IDSIZE]; /* (S) */ - /* private part */ ... } lua_Debug; @@ -3295,36 +3355,37 @@ call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. <p>The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: <ul> -<li><b><code>source</code></b> +<li><b><code>source</code></b> --- If the function was defined in a string, then <code>source</code> is that string. If the function was defined in a file, then <code>source</code> starts with a `<code>@</code>´ followed by the file name. -<p><li><b><code>short_src</code></b> -A "printable" version of <code>source</code>, to be used in error messages. +<p><li><b><code>short_src</code></b> --- +a "printable" version of <code>source</code>, to be used in error messages. -<p><li><b><code>linedefined</code></b> +<p><li><b><code>linedefined</code></b> --- the line number where the definition of the function starts. -<p><li><b><code>lastlinedefined</code></b> +<p><li><b><code>lastlinedefined</code></b> --- the line number where the definition of the function ends. -<p><li><b><code>what</code></b> the string <code>"Lua"</code> if this is a Lua function, -<code>"C"</code> if this is a C function, -<code>"main"</code> if this is the main part of a chunk, -and <code>"tail"</code> if this was a function that did a tail call. +<p><li><b><code>what</code></b> --- +the string <code>"Lua"</code> if the function is a Lua function, +<code>"C"</code> if it is a C function, +<code>"main"</code> if it is the main part of a chunk, +and <code>"tail"</code> if it was a function that did a tail call. In the latter case, -Lua has no other information about this function. +Lua has no other information about the function. -<p><li><b><code>currentline</code></b> +<p><li><b><code>currentline</code></b> --- the current line where the given function is executing. When no line information is available, <code>currentline</code> is set to <em>-1</em>. -<p><li><b><code>name</code></b> +<p><li><b><code>name</code></b> --- a reasonable name for the given function. -Because functions in Lua are first class values, +Because functions in Lua are first-class values, they do not have a fixed name: Some functions may be the value of multiple global variables, while others may be stored only in a table field. @@ -3333,21 +3394,21 @@ called to find a suitable name. If it cannot find a name, then <code>name</code> is set to <code>NULL</code>. -<p><li><b><code>namewhat</code></b> -Explains the <code>name</code> field. +<p><li><b><code>namewhat</code></b> --- +explains the <code>name</code> field. The value of <code>namewhat</code> can be <code>"global"</code>, <code>"local"</code>, <code>"method"</code>, <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), according to how the function was called. (Lua uses the empty string when no other option seems to apply.) -<p><li><b><code>nups</code></b> -The number of upvalues of the function. +<p><li><b><code>nups</code></b> --- +the number of upvalues of the function. <p></ul> <p><a name="lua_gethook"></a> -<hr/><h3><code>lua_gethook</code></h3> +<hr /><h3><code>lua_gethook</code></h3> <pre> lua_Hook lua_gethook (lua_State *L); </pre> @@ -3356,7 +3417,7 @@ The number of upvalues of the function. <p>Returns the current hook function. <p><a name="lua_gethookcount"></a> -<hr/><h3><code>lua_gethookcount</code></h3> +<hr /><h3><code>lua_gethookcount</code></h3> <pre> int lua_gethookcount (lua_State *L); </pre> @@ -3365,7 +3426,7 @@ The number of upvalues of the function. <p>Returns the current hook count. <p><a name="lua_gethookmask"></a> -<hr/><h3><code>lua_gethookmask</code></h3> +<hr /><h3><code>lua_gethookmask</code></h3> <pre> int lua_gethookmask (lua_State *L); </pre> @@ -3374,7 +3435,7 @@ The number of upvalues of the function. <p>Returns the current hook mask. <p><a name="lua_getinfo"></a> -<hr/><h3><code>lua_getinfo</code></h3> +<hr /><h3><code>lua_getinfo</code></h3> <pre> int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); </pre> @@ -3408,7 +3469,7 @@ you can write the following code: </pre> <p><a name="lua_getlocal"></a> -<hr/><h3><code>lua_getlocal</code></h3> +<hr /><h3><code>lua_getlocal</code></h3> <pre> const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); </pre> @@ -3421,7 +3482,7 @@ given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). The index <code>n</code> selects which local variable to inspect (1 is the first parameter or active local variable, and so on, until the last active local variable). -<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack, +<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack and returns its name. <p>Variable names starting with `<code>(</code>´ (open parentheses) @@ -3433,7 +3494,7 @@ when the index is greater than the number of active local variables. <p><a name="lua_getstack"></a> -<hr/><h3><code>lua_getstack</code></h3> +<hr /><h3><code>lua_getstack</code></h3> <pre> int lua_getstack (lua_State *L, int level, lua_Debug *ar); </pre> @@ -3451,7 +3512,7 @@ when called with a level greater than the stack depth, it returns 0. <p><a name="lua_getupvalue"></a> -<hr/><h3><code>lua_getupvalue</code></h3> +<hr /><h3><code>lua_getupvalue</code></h3> <pre> const char *lua_getupvalue (lua_State *L, int funcindex, int n); </pre> @@ -3466,7 +3527,8 @@ pushes the upvalue's value onto the stack, and returns its name. <code>funcindex</code> points to the closure in the stack. (Upvalues have no particular order, -as they are active through the whole function.) +as they are active through the whole function. +So, they are numbered in an arbitrary order.) <p>Returns <code>NULL</code> (and pushes nothing) when the index is greater than the number of upvalues. @@ -3474,7 +3536,7 @@ For C functions, this function uses the empty string <code>""</code> as a name for all upvalues. <p><a name="lua_Hook"></a> -<hr/><h3><code>lua_Hook</code></h3> +<hr /><h3><code>lua_Hook</code></h3> <pre> typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); </pre> @@ -3502,7 +3564,7 @@ Therefore, if a hook calls back Lua to execute a function or a chunk, that execution occurs without any calls to hooks. <p><a name="lua_sethook"></a> -<hr/><h3><code>lua_sethook</code></h3> +<hr /><h3><code>lua_sethook</code></h3> <pre> int lua_sethook (lua_State *L, lua_Hook func, int mask, int count); </pre> @@ -3512,7 +3574,7 @@ that execution occurs without any calls to hooks. <p><code>func</code> is the hook function. <code>mask</code> specifies on which events the hook will be called: -It is formed by a disjunction of the constants +It is formed by a bitwise or of the constants <code>LUA_MASKCALL</code>, <code>LUA_MASKRET</code>, <code>LUA_MASKLINE</code>, @@ -3522,9 +3584,11 @@ includes <code>LUA_MASKCOUNT</code>. For each event, the hook is called as explained below: <ul> <li><b>The call hook</b> is called when the interpreter calls a function. -The hook is called just after Lua enters the new function. +The hook is called just after Lua enters the new function, +before the function gets its arguments. <li><b>The return hook</b> is called when the interpreter returns from a function. The hook is called just before Lua leaves the function. +You have no access to the values to be returned by the function. <li><b>The line hook</b> is called when the interpreter is about to start the execution of a new line of code, or when it jumps back in the code (even to the same line). @@ -3537,14 +3601,14 @@ or when it jumps back in the code (even to the same line). <p>A hook is disabled by setting <code>mask</code> to zero. <p><a name="lua_setlocal"></a> -<hr/><h3><code>lua_setlocal</code></h3> +<hr /><h3><code>lua_setlocal</code></h3> <pre> const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); </pre> <p>Sets the value of a local variable of a given activation record. -Parameters <code>ar</code> and <code>n</code> are like in <a href="#lua_getlocal"><code>lua_getlocal</code></a> +Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a> (see <a href="#lua_getlocal"></a>). <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack to the variable and returns its name. @@ -3555,14 +3619,14 @@ when the index is greater than the number of active local variables. <p><a name="lua_setupvalue"></a> -<hr/><h3><code>lua_setupvalue</code></h3> +<hr /><h3><code>lua_setupvalue</code></h3> <pre> const char *lua_setupvalue (lua_State *L, int funcindex, int n); </pre> <p>Sets the value of a closure's upvalue. -Parameters <code>funcindex</code> and <code>n</code> are like in <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> +Parameters <code>funcindex</code> and <code>n</code> are as in <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> (see <a href="#lua_getupvalue"></a>). It assigns the value at the top of the stack to the upvalue and returns its name. @@ -3586,17 +3650,17 @@ common tasks. are defined in header file <code>lauxlib.h</code> and have a prefix <code>luaL_</code>. -<p>All functions in the auxiliary library are build on -top of the basic API, so they provide nothing that cannot -be done with that API. +<p>All functions in the auxiliary library are built on +top of the basic API, +and so they provide nothing that cannot be done with that API. <p>Several functions in the auxiliary library are used to check C function arguments. Their names are always <code>luaL_check*</code> or <code>luaL_opt*</code>. -All those functions raise an error if the check is not satisfied. +All of these functions raise an error if the check is not satisfied. Because the error message is formatted for arguments (e.g., <code>"bad argument #1"</code>), -you should not use those functions for other stack values. +you should not use these functions for other stack values. <p><a name="4.1"></a><h2>4.1 - Functions and Types</h2> @@ -3604,7 +3668,7 @@ you should not use those functions for other stack values. in alphabetical order. <p><a name="luaL_addchar"></a> -<hr/><h3><code>luaL_addchar</code></h3> +<hr /><h3><code>luaL_addchar</code></h3> <pre> void luaL_addchar (luaL_Buffer B, char c); </pre> @@ -3614,7 +3678,7 @@ in alphabetical order. (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). <p><a name="luaL_addlstring"></a> -<hr/><h3><code>luaL_addlstring</code></h3> +<hr /><h3><code>luaL_addlstring</code></h3> <pre> void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); </pre> @@ -3623,9 +3687,10 @@ in alphabetical order. <p>Adds the string pointed by <code>s</code> with length <code>l</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). +The string may contain embedded zeros. <p><a name="luaL_addsize"></a> -<hr/><h3><code>luaL_addsize</code></h3> +<hr /><h3><code>luaL_addsize</code></h3> <pre> void luaL_addsize (luaL_Buffer B, size_t n); </pre> @@ -3636,7 +3701,7 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>) to (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). <p><a name="luaL_addstring"></a> -<hr/><h3><code>luaL_addstring</code></h3> +<hr /><h3><code>luaL_addstring</code></h3> <pre> void luaL_addstring (luaL_Buffer *B, const char *s); </pre> @@ -3645,9 +3710,10 @@ buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>) to <p>Adds the zero-terminated string pointed by <code>s</code> to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). +The string may not contain embedded zeros. <p><a name="luaL_addvalue"></a> -<hr/><h3><code>luaL_addvalue</code></h3> +<hr /><h3><code>luaL_addvalue</code></h3> <pre> void luaL_addvalue (luaL_Buffer *B); </pre> @@ -3663,7 +3729,7 @@ be called with an extra element on the stack, which is the value to be added to the buffer. <p><a name="luaL_argcheck"></a> -<hr/><h3><code>luaL_argcheck</code></h3> +<hr /><h3><code>luaL_argcheck</code></h3> <pre> void luaL_argcheck (lua_State *L, int cond, int numarg, const char *extramsg); @@ -3671,12 +3737,12 @@ which is the value to be added to the buffer. <p>Checks whether <code>cond</code> is true. -If not, raise an error with message +If not, raises an error with message <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, where <code>func</code> is retrieved from the call stack. <p><a name="luaL_argerror"></a> -<hr/><h3><code>luaL_argerror</code></h3> +<hr /><h3><code>luaL_argerror</code></h3> <pre> int luaL_argerror (lua_State *L, int numarg, const char *extramsg); </pre> @@ -3686,10 +3752,12 @@ where <code>func</code> is retrieved from the call stack. <code>"bad argument #<numarg> to <func> (<extramsg>)"</code>, where <code>func</code> is retrieved from the call stack. -<p>This function never returns. +<p>This function never returns, +but it is an idiom to use it as <code>return luaL_argerror ...</code> +in C functions. <p><a name="luaL_Buffer"></a> -<hr/><h3><code>luaL_Buffer</code></h3> +<hr /><h3><code>luaL_Buffer</code></h3> <pre> typedef struct luaL_Buffer luaL_Buffer; </pre> @@ -3700,21 +3768,23 @@ where <code>func</code> is retrieved from the call stack. <p>A string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows: <ul> -<li> Fist you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>. -<li> Then you initialize it with a call <code>luaL_buffinit(L, &b);</code>. +<li> First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>. +<li> Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>. <li> Then you add string pieces to the buffer calling any of the <code>luaL_add*</code> functions. <li> You finish calling <code>luaL_pushresult(&b)</code>. That call leaves the final string on the top of the stack. </ul> -<p>During its normal operation a string buffer uses a -variable number of stack slots. +<p>During its normal operation, +a string buffer uses a variable number of stack slots. So, while using a buffer, you cannot assume that you know where -is the top of the stack. -You can use the stack between successive calls to buffer operations, -as long as that use is balanced, that is, -when you call a buffer operation the stack is at the same level +the top of the stack is. +You can use the stack between successive calls to buffer operations +as long as that use is balanced; +that is, +when you call a buffer operation, +the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its @@ -3722,7 +3792,7 @@ level when the buffer was initialized, plus the final string on its top. <p><a name="luaL_buffinit"></a> -<hr/><h3><code>luaL_buffinit</code></h3> +<hr /><h3><code>luaL_buffinit</code></h3> <pre> void luaL_buffinit (lua_State *L, luaL_Buffer *B); </pre> @@ -3734,7 +3804,7 @@ the buffer must be declared as a variable (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). <p><a name="luaL_callmeta"></a> -<hr/><h3><code>luaL_callmeta</code></h3> +<hr /><h3><code>luaL_callmeta</code></h3> <pre> int luaL_callmeta (lua_State *L, int obj, const char *e); </pre> @@ -3744,53 +3814,54 @@ the buffer must be declared as a variable <p>If the object at index <code>obj</code> has a metatable and that metatable has a field <code>e</code>, -calls that field passing the object as argument. -In that case the function returns 1 and pushes on the +this function calls that field and passes the object as its only argument. +In that case this function returns 1 and pushes on the stack the value returned by the call. -If there is no metatable or no metamethod returns 0 -(without pushing any value on the stack). +If there is no metatable or no metamethod, +this function returns 0 (without pushing any value on the stack). <p><a name="luaL_checkany"></a> -<hr/><h3><code>luaL_checkany</code></h3> +<hr /><h3><code>luaL_checkany</code></h3> <pre> void luaL_checkany (lua_State *L, int narg); </pre> -<p>Checks whether the function has an argument <code>narg</code>. +<p>Checks whether the function has an argument +of any type (including <b>nil</b>) at position <code>narg</code>. <p><a name="luaL_checkint"></a> -<hr/><h3><code>luaL_checkint</code></h3> +<hr /><h3><code>luaL_checkint</code></h3> <pre> int luaL_checkint (lua_State *L, int narg); </pre> <p>Checks whether the function argument <code>narg</code> is a number -and returns that number casted to an <code>int</code>. +and returns that number cast to an <code>int</code>. <p><a name="luaL_checkinteger"></a> -<hr/><h3><code>luaL_checkinteger</code></h3> +<hr /><h3><code>luaL_checkinteger</code></h3> <pre> - lua_Integer luaL_checkinteger (lua_State *L, int numArg); + lua_Integer luaL_checkinteger (lua_State *L, int narg); </pre> <p>Checks whether the function argument <code>narg</code> is a number -and returns that number casted to a <a href="#lua_Integer"><code>lua_Integer</code></a>. +and returns that number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. <p><a name="luaL_checklong"></a> -<hr/><h3><code>luaL_checklong</code></h3> +<hr /><h3><code>luaL_checklong</code></h3> <pre> long luaL_checklong (lua_State *L, int narg); </pre> <p>Checks whether the function argument <code>narg</code> is a number -and returns that number casted to a <code>long</code>. +and returns that number cast to a <code>long</code>. <p><a name="luaL_checklstring"></a> -<hr/><h3><code>luaL_checklstring</code></h3> +<hr /><h3><code>luaL_checklstring</code></h3> <pre> const char *luaL_checklstring (lua_State *L, int numArg, size_t *l); </pre> @@ -3798,11 +3869,11 @@ and returns that number casted to a <code>long</code>. <p>Checks whether the function argument <code>narg</code> is a string and returns that string; -if <code>l</code> is not <code>NULL</code> fills the position <code>*l</code> +if <code>l</code> is not <code>NULL</code> fills <code>*l</code> with the string's length. <p><a name="luaL_checknumber"></a> -<hr/><h3><code>luaL_checknumber</code></h3> +<hr /><h3><code>luaL_checknumber</code></h3> <pre> lua_Number luaL_checknumber (lua_State *L, int numArg); </pre> @@ -3812,7 +3883,7 @@ with the string's length. and returns that number. <p><a name="luaL_checkoption"></a> -<hr/><h3><code>luaL_checkoption</code></h3> +<hr /><h3><code>luaL_checkoption</code></h3> <pre> int luaL_checkoption (lua_State *L, int narg, const char *def, const char *const lst[]); @@ -3830,8 +3901,12 @@ the function has no argument <code>narg</code> or if that argument is <b>nil</b> Raises an error if the argument is not a string or if the string cannot be found. +<p>This is a useful function for mapping strings to C enums. +The usual interfaces in Lua libraries is to use strings instead of numbers +to select options. + <p><a name="luaL_checkstack"></a> -<hr/><h3><code>luaL_checkstack</code></h3> +<hr /><h3><code>luaL_checkstack</code></h3> <pre> void luaL_checkstack (lua_State *L, int sz, const char *msg); </pre> @@ -3842,7 +3917,7 @@ raising an error if the stack cannot grow to that size. <code>msg</code> is an additional text to go into the error message. <p><a name="luaL_checkstring"></a> -<hr/><h3><code>luaL_checkstring</code></h3> +<hr /><h3><code>luaL_checkstring</code></h3> <pre> const char *luaL_checkstring (lua_State *L, int narg); </pre> @@ -3852,7 +3927,7 @@ raising an error if the stack cannot grow to that size. and returns that string. <p><a name="luaL_checktype"></a> -<hr/><h3><code>luaL_checktype</code></h3> +<hr /><h3><code>luaL_checktype</code></h3> <pre> void luaL_checktype (lua_State *L, int narg, int t); </pre> @@ -3861,7 +3936,7 @@ and returns that string. <p>Checks whether the function argument <code>narg</code> has type <code>t</code>. <p><a name="luaL_checkudata"></a> -<hr/><h3><code>luaL_checkudata</code></h3> +<hr /><h3><code>luaL_checkudata</code></h3> <pre> void *luaL_checkudata (lua_State *L, int ud, const char *tname); </pre> @@ -3871,7 +3946,7 @@ and returns that string. of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). <p><a name="luaL_error"></a> -<hr/><h3><code>luaL_error</code></h3> +<hr /><h3><code>luaL_error</code></h3> <pre> int luaL_error (lua_State *L, const char *fmt, ...); </pre> @@ -3885,10 +3960,12 @@ It also adds at the beginning of the message the file name and the line number where the error occurred, if that information is available. -<p>This function never returns. +<p>This function never returns, +but it is an idiom to use it as <code>return luaL_error ...</code> +in C functions. <p><a name="luaL_getmetafield"></a> -<hr/><h3><code>luaL_getmetafield</code></h3> +<hr /><h3><code>luaL_getmetafield</code></h3> <pre> int luaL_getmetafield (lua_State *L, int obj, const char *e); </pre> @@ -3898,10 +3975,10 @@ if that information is available. of the object at index <code>obj</code>. If the object does not have a metatable, or if the metatable does not have that field, -returns 0 (false) and pushes nothing. +returns 0 and pushes nothing. <p><a name="luaL_getmetatable"></a> -<hr/><h3><code>luaL_getmetatable</code></h3> +<hr /><h3><code>luaL_getmetatable</code></h3> <pre> void luaL_getmetatable (lua_State *L, const char *tname); </pre> @@ -3911,19 +3988,20 @@ returns 0 (false) and pushes nothing. in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). <p><a name="luaL_gsub"></a> -<hr/><h3><code>luaL_gsub</code></h3> +<hr /><h3><code>luaL_gsub</code></h3> <pre> const char *luaL_gsub (lua_State *L, const char *s, const char *p, const char *r); </pre> -<p>Creates a copy of string <code>s</code> changing any occurrence of <code>p</code> -by the string <code>r</code>. +<p>Creates a copy of string <code>s</code> by replacing any occurrence +any occurrence of the string <code>p</code> +wth the string <code>r</code>. Pushes the resulting string on the stack and returns it. <p><a name="luaL_loadbuffer"></a> -<hr/><h3><code>luaL_loadbuffer</code></h3> +<hr /><h3><code>luaL_loadbuffer</code></h3> <pre> int luaL_loadbuffer (lua_State *L, const char *buff, size_t sz, const char *name); @@ -3939,7 +4017,7 @@ buffer pointed by <code>buff</code> with size <code>sz</code>. used for debug information and error messages. <p><a name="luaL_loadfile"></a> -<hr/><h3><code>luaL_loadfile</code></h3> +<hr /><h3><code>luaL_loadfile</code></h3> <pre> int luaL_loadfile (lua_State *L, const char *filename); </pre> @@ -3948,14 +4026,16 @@ used for debug information and error messages. <p>Loads a file as a Lua chunk. This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file named <code>filename</code>. -If the file's first line starts with a <code>#</code> it is ignored. +If <code>filename</code> is <code>NULL</code>, +then it loads from the standard input. +The first line in the file is ignored if it starts with a <code>#</code>. <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, but it has an extra error code <code>LUA_ERRFILE</code> -if it cannot open the file. +if it cannot open/read the file. <p><a name="luaL_loadstring"></a> -<hr/><h3><code>luaL_loadstring</code></h3> +<hr /><h3><code>luaL_loadstring</code></h3> <pre> int luaL_loadstring (lua_State *L, const char *s); </pre> @@ -3968,24 +4048,24 @@ the zero-terminated string <code>s</code>. <p>This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. <p><a name="luaL_newmetatable"></a> -<hr/><h3><code>luaL_newmetatable</code></h3> +<hr /><h3><code>luaL_newmetatable</code></h3> <pre> int luaL_newmetatable (lua_State *L, const char *tname); </pre> -<p>If the register already has the key <code>"tname"</code>, +<p>If the registry already has the key <code>"tname"</code>, returns 0. Otherwise, -creates a new table to be used as metatables for userdata, -adds it to the register with key <code>"tname"</code>, +creates a new table to be used as a metatable for userdata, +adds it to the registry with key <code>"tname"</code>, and returns 1. <p>In both cases pushes on the stack the final value associated with <code>"tname"</code> in the registry. <p><a name="luaL_newstate"></a> -<hr/><h3><code>luaL_newstate</code></h3> +<hr /><h3><code>luaL_newstate</code></h3> <pre> lua_State *luaL_newstate (void); </pre> @@ -3993,7 +4073,7 @@ with <code>"tname"</code> in the registry. <p>Creates a new Lua state, calling <a href="#lua_newstate"><code>lua_newstate</code></a> with an allocation function based on the standard C <code>realloc</code> function -and setting a panic function ((see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)) that prints +and setting a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints an error message to the standard error output in case of fatal errors. @@ -4001,46 +4081,46 @@ errors. or <code>NULL</code> if there is a memory allocation error. <p><a name="luaL_optint"></a> -<hr/><h3><code>luaL_optint</code></h3> +<hr /><h3><code>luaL_optint</code></h3> <pre> int luaL_optint (lua_State *L, int narg, int d); </pre> <p>If the function argument <code>narg</code> is a number, -returns that number casted to an <code>int</code>. +returns that number cast to an <code>int</code>. If that argument is absent or is <b>nil</b>, returns <code>d</code>. -Otherwise, raise an error. +Otherwise, raises an error. <p><a name="luaL_optinteger"></a> -<hr/><h3><code>luaL_optinteger</code></h3> +<hr /><h3><code>luaL_optinteger</code></h3> <pre> lua_Integer luaL_optinteger (lua_State *L, int nArg, lua_Integer d); </pre> <p>If the function argument <code>narg</code> is a number, -returns that number casted to a <a href="#lua_Integer"><code>lua_Integer</code></a>. +returns that number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. If that argument is absent or is <b>nil</b>, returns <code>d</code>. -Otherwise, raise an error. +Otherwise, raises an error. <p><a name="luaL_optlong"></a> -<hr/><h3><code>luaL_optlong</code></h3> +<hr /><h3><code>luaL_optlong</code></h3> <pre> long luaL_optlong (lua_State *L, int narg, long d); </pre> <p>If the function argument <code>narg</code> is a number, -returns that number casted to a <code>long</code>. +returns that number cast to a <code>long</code>. If that argument is absent or is <b>nil</b>, returns <code>d</code>. -Otherwise, raise an error. +Otherwise, raises an error. <p><a name="luaL_optlstring"></a> -<hr/><h3><code>luaL_optlstring</code></h3> +<hr /><h3><code>luaL_optlstring</code></h3> <pre> const char *luaL_optlstring (lua_State *L, int numArg, const char *d, size_t *l); @@ -4051,13 +4131,13 @@ Otherwise, raise an error. returns that string. If that argument is absent or is <b>nil</b>, returns <code>d</code>. -Otherwise, raise an error. +Otherwise, raises an error. -<p>If <code>l</code> is not <code>NULL</code> fills the position <code>*l</code> -with the results's length. +<p>If <code>l</code> is not <code>NULL</code>, +fills the position <code>*l</code> with the results's length. <p><a name="luaL_optnumber"></a> -<hr/><h3><code>luaL_optnumber</code></h3> +<hr /><h3><code>luaL_optnumber</code></h3> <pre> lua_Number luaL_optnumber (lua_State *L, int nArg, lua_Number d); </pre> @@ -4067,10 +4147,10 @@ with the results's length. returns that number. If that argument is absent or is <b>nil</b>, returns <code>d</code>. -Otherwise, raise an error. +Otherwise, raises an error. <p><a name="luaL_optstring"></a> -<hr/><h3><code>luaL_optstring</code></h3> +<hr /><h3><code>luaL_optstring</code></h3> <pre> const char *luaL_optstring (lua_State *L, int narg, const char *d); </pre> @@ -4080,24 +4160,24 @@ Otherwise, raise an error. returns that string. If that argument is absent or is <b>nil</b>, returns <code>d</code>. -Otherwise, raise an error. +Otherwise, raises an error. <p><a name="luaL_prepbuffer"></a> -<hr/><h3><code>luaL_prepbuffer</code></h3> +<hr /><h3><code>luaL_prepbuffer</code></h3> <pre> char *luaL_prepbuffer (luaL_Buffer *B); </pre> <p>Returns an address to a space of size <code>LUAL_BUFFERSIZE</code> -wherein you can copy a string to be added to buffer <code>B</code> +where you can copy a string to be added to buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). After copying the string into that space you must call <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add it to the buffer. <p><a name="luaL_pushresult"></a> -<hr/><h3><code>luaL_pushresult</code></h3> +<hr /><h3><code>luaL_pushresult</code></h3> <pre> void luaL_pushresult (luaL_Buffer *B); </pre> @@ -4107,7 +4187,7 @@ it to the buffer. the top of the stack. <p><a name="luaL_ref"></a> -<hr/><h3><code>luaL_ref</code></h3> +<hr /><h3><code>luaL_ref</code></h3> <pre> int luaL_ref (lua_State *L, int t); </pre> @@ -4118,19 +4198,19 @@ in the table at index <code>t</code>, for the object at the top of the stack (and pops the object). <p>A reference is a unique integer key. -As long as you do not add integer keys into table <code>t</code>, +As long as you do not manually add integer keys into table <code>t</code>, <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. You can retrieve an object referred by reference <code>r</code> -calling <code>lua_rawgeti(L, t, r)</code>. +by calling <code>lua_rawgeti(L, t, r)</code>. Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. -<p>Whenever the object at the top of the stack is <b>nil</b>, +<p>If the object at the top of the stack is <b>nil</b>, <a href="#luaL_ref"><code>luaL_ref</code></a> returns the same reference <code>LUA_REFNIL</code>. -The constant <code>LUA_NOREF</code> is garanteed to be different +The constant <code>LUA_NOREF</code> is guaranteed to be different from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. <p><a name="luaL_Reg"></a> -<hr/><h3><code>luaL_Reg</code></h3> +<hr /><h3><code>luaL_Reg</code></h3> <pre> typedef struct luaL_Reg { const char *name; @@ -4140,15 +4220,15 @@ from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. </pre> -<p>Format for arrays of functions to be registered by +<p>Type for arrays of functions to be registered by <a href="#luaL_register"><code>luaL_register</code></a>. <code>name</code> is the function name and <code>func</code> is a pointer to the function. Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry -wherein both <code>name</code> and <code>func</code> are <code>NULL</code>. +in which both <code>name</code> and <code>func</code> are <code>NULL</code>. <p><a name="luaL_register"></a> -<hr/><h3><code>luaL_register</code></h3> +<hr /><h3><code>luaL_register</code></h3> <pre> void luaL_register (lua_State *L, const char *libname, const luaL_Reg *l); @@ -4163,7 +4243,7 @@ simply registers all functions in the list <code>l</code> <p>When called with a non-null <code>libname</code>, creates a new table <code>t</code>, -sets it as the value of the variable <code>libname</code>, +sets it as the value of the global variable <code>libname</code>, sets it as the value of <code>package.loaded[libname]</code>, and registers on it all functions in the list <code>l</code>. If there is a table in <code>package.loaded[libname]</code> or in @@ -4174,7 +4254,7 @@ reuses that table instead of creating a new one. on the top of the stack. <p><a name="luaL_typename"></a> -<hr/><h3><code>luaL_typename</code></h3> +<hr /><h3><code>luaL_typename</code></h3> <pre> const char *luaL_typename (lua_State *L, int idx); </pre> @@ -4183,7 +4263,7 @@ on the top of the stack. <p>Returns the name of the type of the value at index <code>idx</code>. <p><a name="luaL_typerror"></a> -<hr/><h3><code>luaL_typerror</code></h3> +<hr /><h3><code>luaL_typerror</code></h3> <pre> int luaL_typerror (lua_State *L, int narg, const char *tname); </pre> @@ -4198,7 +4278,7 @@ where <code><location></code> is produced by <a href="#luaL_where"><code>lu and <code><realt></code> is the type name of the actual argument. <p><a name="luaL_unref"></a> -<hr/><h3><code>luaL_unref</code></h3> +<hr /><h3><code>luaL_unref</code></h3> <pre> void luaL_unref (lua_State *L, int t, int ref); </pre> @@ -4214,7 +4294,7 @@ The reference <code>ref</code> is also freed to be used again. <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. <p><a name="luaL_where"></a> -<hr/><h3><code>luaL_where</code></h3> +<hr /><h3><code>luaL_where</code></h3> <pre> void luaL_where (lua_State *L, int lvl); </pre> @@ -4224,20 +4304,21 @@ The reference <code>ref</code> is also freed to be used again. of the control at level <code>lvl</code> in the call stack. Typically this string has the format <code><chunkname>:<currentline>:</code>. Level 0 is the running function, -level 1 is the function that called the running function. +level 1 is the function that called the running function, +etc. <p>This function is used to build a prefix for error messages. <p> <a name="libraries"></a><a name="5"></a><h1>5 - Standard Libraries</h1> -<p>The standard libraries provide useful functions +<p>The standard Lua libraries provide useful functions that are implemented directly through the C API. Some of these functions provide essential services to the language (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); others provide access to "outside" services (e.g., I/O); and others could be implemented in Lua itself, -but are quite useful or have critical performance to +but are quite useful or have critical performance requirements that deserve an implementation in C (e.g., <code>sort</code>). <p>All libraries are implemented through the official C API @@ -4258,9 +4339,11 @@ each library provides all its functions as fields of a global table or as methods of its objects. <p>To have access to these libraries, -the C host program must first call the function -<code>luaL_openlibs</code>; -or else it can open them individually calling +the C host program must call +<code>luaL_openlibs</code>, +which open all standard libraries. +Alternatively, +it can open them individually by calling <code>luaopen_base</code> (for the basic library), <code>luaopen_package</code> (for the package library), <code>luaopen_string</code> (for the string library), @@ -4268,86 +4351,90 @@ or else it can open them individually calling <code>luaopen_math</code> (for the mathematical library), <code>luaopen_io</code> (for the I/O and the Operating System libraries), and <code>luaopen_debug</code> (for the debug library). -These functions are declared in <code>lualib.h</code>. +These functions are declared in <code>lualib.h</code> +and should not be called directly: +you must call them like any other Lua C function, +e.g., by using <code>lua_call</code>. <p><a name="predefined"></a><a name="5.1"></a><h2>5.1 - Basic Functions</h2> <p>The basic library provides some core functions to Lua. If you do not include this library in your application, -you should check carefully whether you need to provide some alternative -implementation for some of its facilities. +you should check carefully whether you need to provide +implementations for some of its facilities. -<p><a name="pdf-assert"></a><hr/><h3><code>assert (v [, message])</code></h3> +<p><a name="pdf-assert"></a><hr /><h3><code>assert (v [, message])</code></h3> Issues an error when -the value of its argument <code>v</code> is <b>nil</b> or <b>false</b>; +the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); otherwise, returns all its arguments. <code>message</code> is an error message; when absent, it defaults to "assertion failed!" -<p><a name="pdf-collectgarbage"></a><hr/><h3><code>collectgarbage (opt [, arg])</code></h3> +<p><a name="pdf-collectgarbage"></a><hr /><h3><code>collectgarbage (opt [, arg])</code></h3> <p>This function is a generic interface to the garbage collector. It performs different functions according to its first argument, <code>opt</code>: <ul> -<li><b>"stop"</b> stops the garbage collector. -<li><b>"restart"</b> restarts the garbage collector. -<li><b>"collect"</b> performs a full garbage-collection cycle. -<li><b>"count"</b> returns the total memory in use by Lua (in Kbytes). -<li><b>"step"</b> performs a garbage-collection step. +<li><b>"stop"</b> --- stops the garbage collector. +<li><b>"restart"</b> --- restarts the garbage collector. +<li><b>"collect"</b> --- performs a full garbage-collection cycle. +<li><b>"count"</b> --- returns the total memory in use by Lua (in Kbytes). +<li><b>"step"</b> --- performs a garbage-collection step. The step "size" is controlled by <code>arg</code> (larger values mean more steps) in a non-specified way. If you want to control the step size you must tune experimentally the value of <code>arg</code>. Returns <b>true</b> if that step finished a collection cycle. -<li><b>"steppause"</b> -sets <em><code>arg</code>/100</em> as the new value for the <em>pause</em> of +<li><b>"steppause"</b> --- +sets <code>arg</code>/100 as the new value for the <em>pause</em> of the collector (see <a href="#GC">2.10</a>). -<li><b>"setstepmul"</b> -sets <em><code>arg</code>/100</em> as the new value for the <em>step multiplier</em> of +<li><b>"setstepmul"</b> --- +sets <code>arg</code>/100 as the new value for the <em>step multiplier</em> of the collector (see <a href="#GC">2.10</a>). </ul> -<p><a name="pdf-dofile"></a><hr/><h3><code>dofile (filename)</code></h3> +<p><a name="pdf-dofile"></a><hr /><h3><code>dofile (filename)</code></h3> Opens the named file and executes its contents as a Lua chunk. When called without arguments, -<a href="#pdf-dofile"><code>dofile</code></a> executes the contents of the standard input (<code>stdin</code>). -Returns any value returned by the chunk. -In case of errors, <a href="#pdf-dofile"><code>dofile</code></a> propagates the error -to its caller (that is, it does not run in protected mode). +<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). +Returns all values returned by the chunk. +In case of errors, <code>dofile</code> propagates the error +to its caller (that is, <code>dofile</code> does not run in protected mode). -<p><a name="pdf-error"></a><hr/><h3><code>error (message [, level])</code></h3> +<p><a name="pdf-error"></a><hr /><h3><code>error (message [, level])</code></h3> Terminates the last protected function called and returns <code>message</code> as the error message. -Function <a href="#pdf-error"><code>error</code></a> never returns. +Function <code>error</code> never returns. -<p>Usually, <a href="#pdf-error"><code>error</code></a> adds some information about the error position +<p>Usually, <code>error</code> adds some information about the error position at the beginning of the message. The <code>level</code> argument specifies how to get the error position. With level 1 (the default), the error position is where the -<a href="#pdf-error"><code>error</code></a> function was called. +<code>error</code> function was called. Level 2 points the error to where the function -that called <a href="#pdf-error"><code>error</code></a> was called; and so on. +that called <code>error</code> was called; and so on. Passing a level 0 avoids the addition of error position information to the message. -<p><a name="pdf-_G"></a><hr/><h3><code>_G</code></h3> +<p><a name="pdf-_G"></a><hr /><h3><code>_G</code></h3> A global variable (not a function) that holds the global environment (that is, <code>_G._G = _G</code>). Lua itself does not use this variable; -changing its value does not affect any environment. +changing its value does not affect any environment, +nor vice-versa. (Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.) -<p><a name="pdf-getfenv"></a><hr/><h3><code>getfenv (f)</code></h3> +<p><a name="pdf-getfenv"></a><hr /><h3><code>getfenv (f)</code></h3> Returns the current environment in use by the function. -<code>f</code> can be a Lua function or a number, -which specifies the function at that stack level: -Level 1 is the function calling <a href="#pdf-getfenv"><code>getfenv</code></a>. +<code>f</code> can be a Lua function or a number +that specifies the function at that stack level: +Level 1 is the function calling <code>getfenv</code>. If the given function is not a Lua function, or if <code>f</code> is 0, -<a href="#pdf-getfenv"><code>getfenv</code></a> returns the global environment. +<code>getfenv</code> returns the global environment. The default for <code>f</code> is 1. -<p><a name="pdf-getmetatable"></a><hr/><h3><code>getmetatable (object)</code></h3> +<p><a name="pdf-getmetatable"></a><hr /><h3><code>getmetatable (object)</code></h3> <p>If <code>object</code> does not have a metatable, returns <b>nil</b>. Otherwise, @@ -4355,9 +4442,9 @@ if the object's metatable has a <code>"__metatable"</code> field, returns the associated value. Otherwise, returns the metatable of the given object. -<p><a name="pdf-ipairs"></a><hr/><h3><code>ipairs (t)</code></h3> +<p><a name="pdf-ipairs"></a><hr /><h3><code>ipairs (t)</code></h3> -<p>Returns an iterator function, the table <code>t</code>, and 0, +<p>Returns three values: an iterator function, the table <code>t</code>, and 0, so that the construction <pre> for i,v in ipairs(t) do ... end @@ -4365,7 +4452,9 @@ so that the construction will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., up to the first integer key with a nil value in the table. -<p><a name="pdf-load"></a><hr/><h3><code>load (func [, chunkname])</code></h3> +<p>See <a href="#pdf-next"><code>next</code></a> for the caveats of modifying the table during its traversal. + +<p><a name="pdf-load"></a><hr /><h3><code>load (func [, chunkname])</code></h3> <p>Loads a chunk using function <code>func</code> to get its pieces. Each call to <code>func</code> must return a string that concatenates @@ -4380,12 +4469,14 @@ The environment of the returned function is the global environment. <p><code>chunkname</code> is used as the chunk name for error messages and debug information. -<p><a name="pdf-loadfile"></a><hr/><h3><code>loadfile (filename)</code></h3> +<p><a name="pdf-loadfile"></a><hr /><h3><code>loadfile ([filename])</code></h3> <p>Similar to <a href="#pdf-load"><code>load</code></a>, -but gets the chunk from file <code>filename</code>. +but gets the chunk from file <code>filename</code> +or from the standard input, +if no file name given. -<p><a name="pdf-loadstring"></a><hr/><h3><code>loadstring (string [, chunkname])</code></h3> +<p><a name="pdf-loadstring"></a><hr /><h3><code>loadstring (string [, chunkname])</code></h3> <p>Similar to <a href="#pdf-load"><code>load</code></a>, but gets the chunk from the given string. @@ -4395,106 +4486,112 @@ but gets the chunk from the given string. assert(loadstring(s))() </pre> -<p><a name="pdf-next"></a><hr/><h3><code>next (table [, index])</code></h3> +<p><a name="pdf-next"></a><hr /><h3><code>next (table [, index])</code></h3> <p>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. -<a href="#pdf-next"><code>next</code></a> returns the next index of the table and the -value associated with the index. +<code>next</code> returns the next index of the table +and its associated value. When called with <b>nil</b> as its second argument, -<a href="#pdf-next"><code>next</code></a> returns the first index -of the table and its associated value. +<code>next</code> returns an initial index +and its associated value. When called with the last index, or with <b>nil</b> in an empty table, -<a href="#pdf-next"><code>next</code></a> 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>. +In particular, +you can use <code>next(t)</code> to check whether a table is empty. -<p>Lua has no declaration of fields; +<p>Lua has no declaration of fields. There is no difference between a field not present in a table or a field with value <b>nil</b>. -Therefore, <a href="#pdf-next"><code>next</code></a> 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 numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.) -<p>The behavior of <a href="#pdf-next"><code>next</code></a> is <em>undefined</em> if, +<p>The behavior of <code>next</code> is <em>undefined</em> if, during the traversal, you assign any value to a non-existent field in the table. +You may however modify existing fields. +In particular, you may clear existing fields. -<p><a name="pdf-pairs"></a><hr/><h3><code>pairs (t)</code></h3> +<p><a name="pdf-pairs"></a><hr /><h3><code>pairs (t)</code></h3> -<p>Returns the <a href="#pdf-next"><code>next</code></a> function and the table <code>t</code> (plus a <b>nil</b>), +<p>Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, so that the construction <pre> for k,v in pairs(t) do ... end </pre> will iterate over all key--value pairs of table <code>t</code>. -<p><a name="pdf-pcall"></a><hr/><h3><code>pcall (f, arg1, arg2, ...)</code></h3> +<p>See <a href="#pdf-next"><code>next</code></a> for the caveats of modifying the table during its traversal. + +<p><a name="pdf-pcall"></a><hr /><h3><code>pcall (f, arg1, arg2, ...)</code></h3> <p>Calls function <code>f</code> with the given arguments in protected mode. That means that any error inside <code>f</code> is not propagated; -instead, <a href="#pdf-pcall"><code>pcall</code></a> catches the error +instead, <code>pcall</code> catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. -In such case, <a href="#pdf-pcall"><code>pcall</code></a> also returns all results from the call, +In such case, <code>pcall</code> also returns all results from the call, after this first result. -In case of any error, <a href="#pdf-pcall"><code>pcall</code></a> returns <b>false</b> plus the error message. +In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. -<p><a name="pdf-print"></a><hr/><h3><code>print (e1, e2, ...)</code></h3> +<p><a name="pdf-print"></a><hr /><h3><code>print (e1, e2, ...)</code></h3> Receives any number of arguments, and prints their values in <code>stdout</code>, using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings. -This function is not intended for formatted output, +<code>print</code> is not intended for formatted output, but only as a quick way to show a value, typically for debugging. -For formatted output, use <code>format</code> (see <a href="#format">5.4</a>). +For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>. -<p><a name="pdf-rawequal"></a><hr/><h3><code>rawequal (v1, v2)</code></h3> +<p><a name="pdf-rawequal"></a><hr /><h3><code>rawequal (v1, v2)</code></h3> Checks whether <code>v1</code> is equal to <code>v2</code>, without invoking any metamethod. Returns a boolean. -<p><a name="pdf-rawget"></a><hr/><h3><code>rawget (table, index)</code></h3> +<p><a name="pdf-rawget"></a><hr /><h3><code>rawget (table, index)</code></h3> Gets the real value of <code>table[index]</code>, without invoking any metamethod. -<code>table</code> must be a table; -<code>index</code> is any value different from <b>nil</b>. +<code>table</code> must be a table and +<code>index</code> any value different from <b>nil</b>. -<p><a name="pdf-rawset"></a><hr/><h3><code>rawset (table, index, value)</code></h3> +<p><a name="pdf-rawset"></a><hr /><h3><code>rawset (table, index, value)</code></h3> Sets the real value of <code>table[index]</code> to <code>value</code>, without invoking any metamethod. <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. +<code>index</code> any value different from <b>nil</b>, +and <code>value</code> any Lua value. -<p><a name="pdf-select"></a><hr/><h3><code>select (index, ...)</code></h3> +<p><a name="pdf-select"></a><hr /><h3><code>select (index, ...)</code></h3> <p>If <code>index</code> is a number, -returns all argument after argument number <code>index</code>. +returns all arguments after argument number <code>index</code>. Otherwise, <code>index</code> must be the string <code>"#"</code>, and <code>select</code> returns the total number of extra arguments it received. -<p><a name="setfenv"></a><a name="pdf-setfenv"></a><hr/><h3><code>setfenv (f, table)</code></h3> +<p><a name="setfenv"></a><a name="pdf-setfenv"></a><hr /><h3><code>setfenv (f, table)</code></h3> <p>Sets the environment to be used by the given function. -<code>f</code> can be a Lua function or a number, -which specifies the function at that stack level: -Level 1 is the function calling <a href="#pdf-setfenv"><code>setfenv</code></a>. -<a href="#pdf-setfenv"><code>setfenv</code></a> returns the given function. +<code>f</code> can be a Lua function or a number +that specifies the function at that stack level: +Level 1 is the function calling <code>setfenv</code>. +<code>setfenv</code> returns the given function. -<p>As a special case, when <code>f</code> is 0 <a href="#pdf-setfenv"><code>setfenv</code></a> changes +<p>As a special case, when <code>f</code> is 0 <code>setfenv</code> changes the environment of the running thread. -In this case, <a href="#pdf-setfenv"><code>setfenv</code></a> returns no values. +In this case, <code>setfenv</code> returns no values. -<p><a name="pdf-setmetatable"></a><hr/><h3><code>setmetatable (table, metatable)</code></h3> +<p><a name="pdf-setmetatable"></a><hr /><h3><code>setmetatable (table, metatable)</code></h3> <p>Sets the metatable for the given table. -(You cannot change the metatable of other types from Lua.) +(You cannot change the metatable of other types from Lua, only from C.) If <code>metatable</code> is <b>nil</b>, removes the metatable of the given table. If the original metatable has a <code>"__metatable"</code> field, @@ -4502,10 +4599,10 @@ raises an error. <p>This function returns <code>table</code>. -<p><a name="pdf-tonumber"></a><hr/><h3><code>tonumber (e [, base])</code></h3> +<p><a name="pdf-tonumber"></a><hr /><h3><code>tonumber (e [, base])</code></h3> Tries to convert its argument to a number. If the argument is already a number or a string convertible -to a number, then <a href="#pdf-tonumber"><code>tonumber</code></a> returns that number; +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. @@ -4514,21 +4611,21 @@ In bases above 10, the letter `<code>A</code>´ (in either upper or lower c represents 10, `<code>B</code>´ represents 11, and so forth, with `<code>Z</code>´ representing 35. In base 10 (the default), the number may have a decimal part, -as well as an optional exponent part (see <a href="#coercion">2.2.1</a>). +as well as an optional exponent part (see <a href="#lexical">2.1</a>). In other bases, only unsigned integers are accepted. -<p><a name="pdf-tostring"></a><hr/><h3><code>tostring (e)</code></h3> +<p><a name="pdf-tostring"></a><hr /><h3><code>tostring (e)</code></h3> 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 <a href="#pdf-string.format"><code>string.format</code></a> (see <a href="#format">5.4</a>). +use <a href="#pdf-string.format"><code>string.format</code></a>. <p>If the metatable of <code>e</code> has a <code>"__tostring"</code> field, -<a href="#pdf-tostring"><code>tostring</code></a> calls the corresponding value +then <code>tostring</code> calls the corresponding value with <code>e</code> as argument, and uses the result of the call as its result. -<p><a name="pdf-type"></a><hr/><h3><code>type (v)</code></h3> +<p><a name="pdf-type"></a><hr /><h3><code>type (v)</code></h3> Returns the type of its only argument, coded as a string. The possible results of this function are <code>"nil"</code> (a string, not the value <b>nil</b>), @@ -4540,8 +4637,8 @@ The possible results of this function are <code>"thread"</code>, and <code>"userdata"</code>. -<p><a name="pdf-unpack"></a><hr/><h3><code>unpack (list [, i [, j]])</code></h3> -Returns the elements from the given list. +<p><a name="pdf-unpack"></a><hr /><h3><code>unpack (list [, i [, j]])</code></h3> +Returns the elements from the given table. This function is equivalent to <pre> return list[i], list[i+1], ..., list[j] @@ -4549,30 +4646,30 @@ This function is equivalent to except that the above code can be written only for a fixed number of elements. By default, <code>i</code> is 1 and <code>j</code> is the length of the list, -as defined by the length operator. +as defined by the length operator (see <a href="#len-op">2.5.5</a>). -<p><a name="pdf-_VERSION"></a><hr/><h3><code>_VERSION</code></h3> +<p><a name="pdf-_VERSION"></a><hr /><h3><code>_VERSION</code></h3> A global variable (not a function) that holds a string containing the current interpreter version. The current contents of this variable is <code>"Lua 5.1"</code>. -<p><a name="pdf-xpcall"></a><hr/><h3><code>xpcall (f, err)</code></h3> +<p><a name="pdf-xpcall"></a><hr /><h3><code>xpcall (f, err)</code></h3> -<p>This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, +<p>This function is similar to <code>pcall</code>, except that you can set a new error handler. -<p><a href="#pdf-xpcall"><code>xpcall</code></a> calls function <code>f</code> in protected mode, +<p><code>xpcall</code> calls function <code>f</code> in protected mode, using <code>err</code> as the error handler. Any error inside <code>f</code> is not propagated; -instead, <a href="#pdf-xpcall"><code>xpcall</code></a> catches the error, +instead, <code>xpcall</code> catches the error, calls the <code>err</code> function with the original error object, and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. -In such case, <a href="#pdf-xpcall"><code>xpcall</code></a> also returns all results from the call, +In this case, <code>xpcall</code> also returns all results from the call, after this first result. In case of any error, -<a href="#pdf-xpcall"><code>xpcall</code></a> returns false plus the result from <code>err</code>. +<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. <p><a name="5.2"></a><h2>5.2 - Coroutine Manipulation</h2> @@ -4580,22 +4677,24 @@ In case of any error, the basic library and come inside the table <code>coroutine</code>. See <a href="#coroutine">2.11</a> for a general description of coroutines. -<p><a name="pdf-coroutine.create"></a><hr/><h3><code>coroutine.create (f)</code></h3> +<p><a name="pdf-coroutine.create"></a><hr /><h3><code>coroutine.create (f)</code></h3> <p>Creates a new coroutine, with body <code>f</code>. <code>f</code> must be a Lua function. Returns this new coroutine, an object with type <code>"thread"</code>. -<p><a name="pdf-coroutine.resume"></a><hr/><h3><code>coroutine.resume (co, val1, ...)</code></h3> +<p><a name="pdf-coroutine.resume"></a><hr /><h3><code>coroutine.resume (co [, val1, ..., valn])</code></h3> <p>Starts or continues the execution of coroutine <code>co</code>. The first time you resume a coroutine, it starts running its body. -The arguments <code>val1</code>, ... go as the arguments to the body function. +The values <code>val1</code>, ..., <code>valn</code> are passed +as the arguments to the body function. If the coroutine has yielded, <code>resume</code> restarts it; -the arguments <code>val1</code>, ... go as the results from the yield. +the values <code>val1</code>, ..., <code>valn</code> are passed +as the results from the yield. <p>If the coroutine runs without any errors, <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> @@ -4604,12 +4703,12 @@ the arguments <code>val1</code>, ... go as the results from the yield. If there is any error, <code>resume</code> returns <b>false</b> plus the error message. -<p><a name="pdf-coroutine.running"></a><hr/><h3><code>coroutine.running ()</code></h3> +<p><a name="pdf-coroutine.running"></a><hr /><h3><code>coroutine.running ()</code></h3> <p>Returns the running coroutine, or <b>nil</b> when called by the main thread. -<p><a name="pdf-coroutine.status"></a><hr/><h3><code>coroutine.status (co)</code></h3> +<p><a name="pdf-coroutine.status"></a><hr /><h3><code>coroutine.status (co)</code></h3> <p>Returns the status of coroutine <code>co</code>, as a string: <code>"running"</code>, @@ -4621,7 +4720,7 @@ or if it has not started running yet; and <code>"dead"</code> if the coroutine has finished its body function, or if it has stopped with an error. -<p><a name="pdf-coroutine.wrap"></a><hr/><h3><code>coroutine.wrap (f)</code></h3> +<p><a name="pdf-coroutine.wrap"></a><hr /><h3><code>coroutine.wrap (f)</code></h3> <p>Creates a new coroutine, with body <code>f</code>. <code>f</code> must be a Lua function. @@ -4632,22 +4731,22 @@ Returns the same values returned by <code>resume</code>, except the first boolean. In case of error, propagates the error. -<p><a name="pdf-coroutine.yield"></a><hr/><h3><code>coroutine.yield (val1, ...)</code></h3> +<p><a name="pdf-coroutine.yield"></a><hr /><h3><code>coroutine.yield ([val1, ..., valn])</code></h3> <p>Suspends the execution of the calling coroutine. -The coroutine cannot be running neither a C function, +The coroutine can be running neither a C function, nor a metamethod, nor an iterator. -Any arguments to <code>yield</code> go as extra results to <code>resume</code>. +Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. -<p><a name="5.3"></a><h2>5.3 - Packages and Modules</h2> +<p><a name="5.3"></a><h2>5.3 - Modules</h2> <p>The package library provides basic -facilities for packages and modules in Lua. +facilities for loading and building modules in Lua. It exports two of its functions directly in the global environment: <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>. Everything else is exported in a table <code>package</code>. -<p><a name="pdf-module"></a><hr/><h3><code>module (name [, ...])</code></h3> +<p><a name="pdf-module"></a><hr /><h3><code>module (name [, ...])</code></h3> <p>Creates a module. If there is a table in <code>package.loaded[name]</code>, @@ -4666,51 +4765,51 @@ of the current function and the new value of <code>package.loaded[name]</code>, so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>. <p>If <code>name</code> is a compound name -(that is, one with components separated by dots) -<code>module</code> creates (or reuses, if they already exists) +(that is, one with components separated by dots), +<code>module</code> creates (or reuses, if they already exist) tables for each component. For instance, if <code>name</code> is <code>a.b.c</code>, -<code>module</code> stores the module table in field <code>c</code> of +then <code>module</code> stores the module table in field <code>c</code> of field <code>b</code> of global <code>a</code>. <p>This function may receive optional <em>options</em> after the module name, where each option is a function to be applied over the module. -<p><a name="pdf-require"></a><hr/><h3><code>require (modname)</code></h3> +<p><a name="pdf-require"></a><hr /><h3><code>require (modname)</code></h3> <p>Loads the given module. The function starts by looking into the table <code>package.loaded</code> to determine whether <code>modname</code> is already loaded. -If it is, then <a href="#pdf-require"><code>require</code></a> returns the value stored +If it is, then <code>require</code> returns the value stored at <code>package.loaded[modname]</code>. -Otherwise, it tries to find a loader for that module. +Otherwise, it tries to find a <em>loader</em> for that module. <p>To find a loader, -first <a href="#pdf-require"><code>require</code></a> queries <code>package.preload[modname]</code>. -If it is a true value, +first <code>require</code> queries <code>package.preload[modname]</code>. +If it has a value, that value (which should be a function) is the loader. -Otherwise <a href="#pdf-require"><code>require</code></a> searches for a Lua loader using the +Otherwise <code>require</code> searches for a Lua loader using the path stored in <code>package.path</code>. -if that also fails, it searches for a C loader using the +If that also fails, it searches for a C loader using the path stored in <code>package.cpath</code>. If that also fails, -it tries an <em>all-in-one</em> loader. +it tries an <em>all-in-one</em> loader (see below). <p>When loading a C library, -<a href="#pdf-require"><code>require</code></a> first uses a dynamic link facility to link the +<code>require</code> first uses a dynamic link facility to link the application with the library. Then it tries to find a C function inside that library to be used as the loader. The name of that C function is the string <code>"luaopen_"</code> -concatenated with a copy of the module name wherein each dot +concatenated with a copy of the module name where each dot is replaced by an underscore. Moreover, if the module name has a hyphen, its prefix up to (and including) the first hyphen is removed. For instance, if the module name is <code>a.v1-b.c</code>, the function name will be <code>luaopen_b_c</code>. -<p>If <a href="#pdf-require"><code>require</code></a> finds neither a Lua library nor a +<p>If <code>require</code> finds neither a Lua library nor a C library for a module, it calls the <em>all-in-one loader</em>. That loader searches the C path for a library for @@ -4725,29 +4824,29 @@ into one single library, with each submodule keeping its original open function. <p>Once a loader is found, -<a href="#pdf-require"><code>require</code></a> calls the loader with a sinle argument, <code>modname</code>. +<code>require</code> calls the loader with a single argument, <code>modname</code>. If the loader returns any value, -<a href="#pdf-require"><code>require</code></a> assigns it to <code>package.loaded[modname]</code>. +<code>require</code> assigns it to <code>package.loaded[modname]</code>. If the loader returns no value and has not assigned any value to <code>package.loaded[modname]</code>, -<a href="#pdf-require"><code>require</code></a> assigns <b>true</b> to that entry. +then <code>require</code> assigns <b>true</b> to that entry. In any case, require returns the final value of <code>package.loaded[modname]</code>. <p>If there is any error loading or running the module, or if it cannot find any loader for that module, -then <a href="#pdf-require"><code>require</code></a> signals an error. +then <code>require</code> signals an error. -<p><a name="pdf-package.cpath"></a><hr/><h3><code>package.cpath</code></h3> +<p><a name="pdf-package.cpath"></a><hr /><h3><code>package.cpath</code></h3> <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. <p>Lua initializes the C path <code>package.cpath</code> in the same way it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, using the environment variable <code>LUA_CPATH</code> -(plus another compiled-defined default path). +(plus another default path defined in <code>luaconf.h</code>). -<p><a name="pdf-package.loaded"></a><hr/><h3><code>package.loaded</code></h3> +<p><a name="pdf-package.loaded"></a><hr /><h3><code>package.loaded</code></h3> <p>A table used by <a href="#pdf-require"><code>require</code></a> to control which modules are already loaded. @@ -4755,27 +4854,34 @@ When you require a module <code>modname</code> and <code>package.loaded[modname]</code> is not false, <a href="#pdf-require"><code>require</code></a> simply returns the value stored there. -<p><a name="pdf-package.loadlib"></a><hr/><h3><code>package.loadlib (libname, funcname)</code></h3> +<p><a name="pdf-package.loadlib"></a><hr /><h3><code>package.loadlib (libname, funcname)</code></h3> -<p>Links the program with the dynamic C library <code>libname</code>. +<p>Dynamically links the host program with the C library <code>libname</code>. Inside this library, looks for a function <code>funcname</code> and returns this function as a C function. +(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)). -<p><code>libname</code> must be the complete file name of the C library, -including any eventual path and extension. +<p>This is a low-level function. +It completely bypasses the package and module system. +Unlike <a href="#pdf-require"><code>require</code></a>, +it does not perform any path searching or automatically adds extensions. +<code>libname</code> must be the complete file name of the C library, +including if necessary a path and extension. +<code>funcname</code> must be the exact name exported by the C library +(which may depend on the C compiler and linker used). <p>This function is not supported by ANSI C. As such, it is only available on some platforms -(Windows, Linux, Solaris, BSD, plus other Unix systems that -support the <code>dlfcn</code> standard). +(Windows, Linux, Mac OS X, Solaris, BSD, +plus other Unix systems that support the <code>dlfcn</code> standard). -<p><a name="pdf-package.path"></a><hr/><h3><code>package.path</code></h3> +<p><a name="pdf-package.path"></a><hr /><h3><code>package.path</code></h3> <p>The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. <p>At start-up, Lua initializes this variable with the value of the environment variable <code>LUA_PATH</code> or -with a compiled-defined default path, +with a default path defined in <code>luaconf.h</code>, if the environment variable is not defined. Any <code>";;"</code> in the value of the environment variable is replaced by the default path. @@ -4790,21 +4896,21 @@ So, for instance, if the Lua path is <pre> "./?.lua;./?.lc;/usr/local/?/init.lua" </pre> -the search for a Lua loader for module <code>mod</code> +the search for a Lua loader for module <code>foo</code> will try to load the files -<code>./mod.lua</code>, <code>./mod.lc</code>, and -<code>/usr/local/mod/init.lua</code>, in that order. +<code>./foo.lua</code>, <code>./foo.lc</code>, and +<code>/usr/local/foo/init.lua</code>, in that order. -<p><a name="pdf-package.preload"></a><hr/><h3><code>package.preload</code></h3> +<p><a name="pdf-package.preload"></a><hr /><h3><code>package.preload</code></h3> <p>A table to store loaders for specific modules (see <a href="#pdf-require"><code>require</code></a>). -<p><a name="pdf-package.seeall"></a><hr/><h3><code>package.seeall (module)</code></h3> +<p><a name="pdf-package.seeall"></a><hr /><h3><code>package.seeall (module)</code></h3> <p>Sets a metatable for <code>module</code> with -its <code>__index</code> field refering to the global environment, -so that this module inherits undefined values +its <code>__index</code> field referring to the global environment, +so that this module inherits values from the global environment. To be used as an option to function <a href="#pdf-module"><code>module</code></a>. @@ -4821,12 +4927,12 @@ Thus, the last character is at position <em>-1</em>, and so on. <p>The string library provides all its functions inside the table <code>string</code>. It also sets a metatable for strings -wherein <code>__index</code> points to itself. -Therefore, you can use the string function is object-oriented style. +where the <code>__index</code> field points to the metatable itself. +Therefore, you can use the string functions in object-oriented style. For instance, <code>string.byte(s, i)</code> can be written as <code>s:byte(i)</code>. -<p><a name="pdf-string.byte"></a><hr/><h3><code>string.byte (s [, i [, j]])</code></h3> +<p><a name="pdf-string.byte"></a><hr /><h3><code>string.byte (s [, i [, j]])</code></h3> Returns the internal numerical codes of the characters <code>s[i]</code>, <code>s[i+1]</code>, ..., <code>s[j]</code>. The default value for <code>i</code> is 1; @@ -4834,25 +4940,25 @@ the default value for <code>j</code> is <code>i</code>. <p>Note that numerical codes are not necessarily portable across platforms. -<p><a name="pdf-string.char"></a><hr/><h3><code>string.char (i1, i2, ...)</code></h3> +<p><a name="pdf-string.char"></a><hr /><h3><code>string.char (i1, i2, ...)</code></h3> Receives 0 or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal -to its correspondent argument. +to its corresponding argument. <p>Note that numerical codes are not necessarily portable across platforms. -<p><a name="pdf-string.dump"></a><hr/><h3><code>string.dump (function)</code></h3> +<p><a name="pdf-string.dump"></a><hr /><h3><code>string.dump (function)</code></h3> -<p>Returns a binary representation of the given function, +<p>Returns a string containing a binary representation of the given function, so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on that string returns a copy of the function. -<code>function</code> must be a Lua function. +<code>function</code> must be a Lua function without upvalues. -<p><a name="pdf-string.find"></a><hr/><h3><code>string.find (s, pattern [, init [, plain]])</code></h3> -Looks for the first <em>match</em> of +<p><a name="pdf-string.find"></a><hr /><h3><code>string.find (s, pattern [, init [, plain]])</code></h3> +Looks for the first match of <code>pattern</code> in the string <code>s</code>. -If it finds one, then <code>find</code> returns the indices of <code>s</code> +If it finds a match, then <code>find</code> returns the indices of <code>s</code> where this occurrence starts and ends; otherwise, it returns <b>nil</b>. A third, optional numerical argument <code>init</code> specifies @@ -4862,26 +4968,27 @@ A value of <b>true</b> 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. +Note that if <code>plain</code> is given, then <code>init</code> must be given as well. <p>If the pattern has captures, then in a successful match the captured values are also returned, after the two indices. -<p><a name="format"></a><a name="pdf-string.format"></a><hr/><h3><code>string.format (formatstring, e1, e2, ...)</code></h3> +<p><a name="format"></a><a name="pdf-string.format"></a><hr /><h3><code>string.format (formatstring, e1, e2, ...)</code></h3> 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. 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>. +and <code>h</code> are not supported +and that there is an extra option, <code>q</code>. 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, newlines, and backslashes in the string +and all double quotes, newlines, embedded zeros, +and backslashes in the string are correctly escaped when written. For instance, the call <pre> @@ -4901,12 +5008,12 @@ whereas <code>q</code> and <code>s</code> expect a string. <p>This function does not accept string values containing embedded zeros. -<p><a name="pdf-string.gmatch"></a><hr/><h3><code>string.gmatch (s, pat)</code></h3> +<p><a name="pdf-string.gmatch"></a><hr /><h3><code>string.gmatch (s, pattern)</code></h3> Returns an iterator function that, each time it is called, -returns the next captures from pattern <code>pat</code> over string <code>s</code>. +returns the next captures from <code>pattern</code> over string <code>s</code>. -<p>If <code>pat</code> specifies no captures, +<p>If <code>pattern</code> specifies no captures, then the whole match is produced in each call. <p>As an example, the following loop @@ -4928,11 +5035,12 @@ given string into a table: end </pre> -<p><a name="pdf-string.gsub"></a><hr/><h3><code>string.gsub (s, pat, repl [, n])</code></h3> +<p><a name="pdf-string.gsub"></a><hr /><h3><code>string.gsub (s, pattern, repl [, n])</code></h3> 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>. -<code>gsub</code> also returns, as a second value, +in which all occurrences of the <code>pattern</code> have been +replaced by a replacement string specified by <code>repl</code>, +which may be a string, a table, or a function. +<code>gsub</code> also returns, as its second value, the total number of substitutions made. <p>If <code>repl</code> is a string, then its value is used for replacement. @@ -4943,6 +5051,11 @@ stands for the value of the <em>n</em>-th captured substring (see below). The sequence <code>%0</code> stands for the whole match. The sequence <code>%%</code> stands for a single <code>%</code>. +<p>If <code>repl</code> is a table, then the table is queried for every match, +using the first capture as the key; +if the pattern specifies no captures, +then the whole match is used as the key. + <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, in order; @@ -4951,9 +5064,10 @@ then the whole match is passed as a sole argument. If <code>repl</code> is a table, then this table is queried with the value of the first capture or of the whole match, if the pattern specifies no captures. -In both cases, -if the value returned by the function or resulted by the query -is a string, + +<p>In both cases, +if the value returned by the function or by the table query +is a string or a number, then it is used as the replacement string; otherwise, if it is <b>false</b> or <b>nil</b>, then there is no replacement @@ -4962,7 +5076,7 @@ then there is no replacement <p>The optional last 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. +<code>pattern</code> is replaced. <p>Here are some examples: <pre> @@ -4983,24 +5097,24 @@ For instance, when <code>n</code> is 1 only the first occurrence of end) --> x="4+5 = 9" - local t = {name="lua", version="5.0"} - x = string.gsub("$name_$version.tar.gz", "%$(%w+)", t) - --> x="lua_5.0.tar.gz" + local t = {name="lua", version="5.1"} + x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) + --> x="lua-5.1.tar.gz" </pre> -<p><a name="pdf-string.len"></a><hr/><h3><code>string.len (s)</code></h3> +<p><a name="pdf-string.len"></a><hr /><h3><code>string.len (s)</code></h3> Receives a string and returns its length. The empty string <code>""</code> has length 0. Embedded zeros are counted, so <code>"a\000bc\000"</code> has length 5. -<p><a name="pdf-string.lower"></a><hr/><h3><code>string.lower (s)</code></h3> +<p><a name="pdf-string.lower"></a><hr /><h3><code>string.lower (s)</code></h3> Receives a string and returns a copy of that string with all uppercase letters changed to lowercase. All other characters are left unchanged. -The definition of what is an uppercase letter depends on the current locale. +The definition of what an uppercase letter is depends on the current locale. -<p><a name="pdf-string.match"></a><hr/><h3><code>string.match (s, pattern [, init])</code></h3> +<p><a name="pdf-string.match"></a><hr /><h3><code>string.match (s, pattern [, init])</code></h3> Looks for the first <em>match</em> of <code>pattern</code> in the string <code>s</code>. If it finds one, then <code>match</code> returns @@ -5012,14 +5126,14 @@ A third, optional numerical argument <code>init</code> specifies where to start the search; its default value is 1 and may be negative. -<p><a name="pdf-string.rep"></a><hr/><h3><code>string.rep (s, n)</code></h3> +<p><a name="pdf-string.rep"></a><hr /><h3><code>string.rep (s, n)</code></h3> Returns a string that is the concatenation of <code>n</code> copies of the string <code>s</code>. -<p><a name="pdf-string.reverse"></a><hr/><h3><code>string.reverse (s)</code></h3> +<p><a name="pdf-string.reverse"></a><hr /><h3><code>string.reverse (s)</code></h3> Returns a string that is the string <code>s</code> reversed. -<p><a name="pdf-string.sub"></a><hr/><h3><code>string.sub (s, i [, j])</code></h3> +<p><a name="pdf-string.sub"></a><hr /><h3><code>string.sub (s, i [, j])</code></h3> Returns the substring of <code>s</code> that starts at <code>i</code> and continues until <code>j</code>; <code>i</code> and <code>j</code> may be negative. @@ -5031,11 +5145,11 @@ with length <code>j</code>, and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> with length <code>i</code>. -<p><a name="pdf-string.upper"></a><hr/><h3><code>string.upper (s)</code></h3> +<p><a name="pdf-string.upper"></a><hr /><h3><code>string.upper (s)</code></h3> Receives a string and returns a copy of that string with all lowercase letters changed to uppercase. All other characters are left unchanged. -The definition of what is a lowercase letter depends on the current locale. +The definition of what a lowercase letter is depends on the current locale. <p><a name="pm"></a><h3>Patterns</h3> @@ -5043,7 +5157,7 @@ The definition of what is a lowercase letter depends on the current locale. A <em>character class</em> is used to represent a set of characters. The following combinations are allowed in describing a character class: <ul> -<li><b><em>x</em></b> (where <em>x</em> is not one of the magic characters +<li><b><em>x</em></b> (where <em>x</em> is not one of the <em>magic characters</em> <code>^$()%.[]*+-?</code>) --- represents the character <em>x</em> itself. <li><b><code>.</code></b> --- (a dot) represents all characters. @@ -5117,11 +5231,11 @@ these repetition items will always match the <em>shortest</em> possible sequence a single character class followed by `<code>?</code>´, which matches 0 or 1 occurrence of a character in the class; <li> -<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; +<code>%</code><em>n</em>, for <em>n</em> between 1 and 9; such item matches a substring equal to the <em>n</em>-th captured string (see below); <li> -<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; +<code>%b</code><em>xy</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>, and where the <em>x</em> and <em>y</em> are <em>balanced</em>. This means that, if one reads the string from left to right, @@ -5149,8 +5263,8 @@ Captures are numbered according to their left parentheses. For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, the part of the string matching <code>"a*(.)%w(%s*)"</code> is 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. +the character matching <code>"."</code> is captured with number 2, +and the part matching <code>"%s*"</code> has number 3. <p>As a special case, the empty capture <code>()</code> captures the current string position (a number). @@ -5168,14 +5282,14 @@ represents an array or a list. For those functions, when we talk about "the length" of a table we mean the result of the length operator. -<p><a name="pdf-table.concat"></a><hr/><h3><code>table.concat (table [, sep [, i [, j]]])</code></h3> +<p><a name="pdf-table.concat"></a><hr /><h3><code>table.concat (table [, sep [, i [, j]]])</code></h3> Returns <code>table[i]..sep..table[i+1] ... sep..table[j]</code>. The default value for <code>sep</code> is the empty string, the default for <code>i</code> is 1, and the default for <code>j</code> is the length of the table. If <code>i</code> is greater than <code>j</code>, returns the empty string. -<p><a name="pdf-table.insert"></a><hr/><h3><code>table.insert (table, [pos,] value)</code></h3> +<p><a name="pdf-table.insert"></a><hr /><h3><code>table.insert (table, [pos,] value)</code></h3> <p>Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, shifting up other elements to open space, if necessary. @@ -5184,12 +5298,12 @@ where <code>n</code> is the length of the table (see <a href="#len-op">2.5.5</a> so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end of table <code>t</code>. -<p><a name="pdf-table.maxn(table)"></a><hr/><h3><code>table.maxn(table)</code></h3> +<p><a name="pdf-table.maxn"></a><hr /><h3><code>table.maxn (table)</code></h3> <p>Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. -<p><a name="pdf-table.remove"></a><hr/><h3><code>table.remove (table [, pos])</code></h3> +<p><a name="pdf-table.remove"></a><hr /><h3><code>table.remove (table [, pos])</code></h3> <p>Removes from <code>table</code> the element at position <code>pos</code>, shifting down other elements to close the space, if necessary. @@ -5199,7 +5313,7 @@ where <code>n</code> is the length of the table, so that a call <code>table.remove(t)</code> removes the last element of table <code>t</code>. -<p><a name="pdf-table.sort"></a><hr/><h3><code>table.sort (table [, comp])</code></h3> +<p><a name="pdf-table.sort"></a><hr /><h3><code>table.sort (table [, comp])</code></h3> 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 length of the table. @@ -5211,7 +5325,7 @@ when the first is less than the second If <code>comp</code> is not given, then the standard Lua operator <code><</code> is used instead. -<p>The sort algorithm is not stable, +<p>The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort. @@ -5276,7 +5390,7 @@ Equal seeds produce equal sequences of numbers. <p><a name="libio"></a><a name="5.7"></a><h2>5.7 - Input and Output Facilities</h2> <p>The I/O library provides two different styles for file manipulation. -The first one uses implicit file descriptors, +The first one uses implicit file descriptors; that is, there are operations to set a default input file and a default output file, and all input/output operations are over those default files. @@ -5297,16 +5411,16 @@ all I/O functions return <b>nil</b> on failure (plus an error message as a second result) and some value different from <b>nil</b> on success. -<p><a name="pdf-io.close"></a><hr/><h3><code>io.close ([file])</code></h3> +<p><a name="pdf-io.close"></a><hr /><h3><code>io.close ([file])</code></h3> <p>Equivalent to <code>file:close()</code>. Without a <code>file</code>, closes the default output file. -<p><a name="pdf-io.flush"></a><hr/><h3><code>io.flush ()</code></h3> +<p><a name="pdf-io.flush"></a><hr /><h3><code>io.flush ()</code></h3> <p>Equivalent to <code>file:flush</code> over the default output file. -<p><a name="pdf-io.input"></a><hr/><h3><code>io.input ([file])</code></h3> +<p><a name="pdf-io.input"></a><hr /><h3><code>io.input ([file])</code></h3> <p>When called with a file name, it opens the named file (in text mode), and sets its handle as the default input file. @@ -5318,7 +5432,7 @@ it returns the current default input file. <p>In case of errors this function raises the error, instead of returning an error code. -<p><a name="pdf-io.lines"></a><hr/><h3><code>io.lines ([filename])</code></h3> +<p><a name="pdf-io.lines"></a><hr /><h3><code>io.lines ([filename])</code></h3> <p>Opens the given file name in read mode and returns an iterator function that, @@ -5333,11 +5447,11 @@ When the iterator function detects the end of file, it returns <b>nil</b> (to finish the loop) and automatically closes the file. <p>The call <code>io.lines()</code> (without a file name) is equivalent -to <code>io.input():lines()</code>, that is, it iterates over the -lines of the default input file. +to <code>io.input():lines()</code>; +that is, it iterates over the lines of the default input file. In that case it does not close the file when the loop ends. -<p><a name="pdf-io.open"></a><hr/><h3><code>io.open (filename [, mode])</code></h3> +<p><a name="pdf-io.open"></a><hr /><h3><code>io.open (filename [, mode])</code></h3> <p>This function opens a file, in the mode specified in the string <code>mode</code>. @@ -5346,24 +5460,24 @@ or, in case of errors, <b>nil</b> plus an error message. <p>The <code>mode</code> string can be any of the following: <ul> -<li><b>"r"</b> read mode (the default); -<li><b>"w"</b> write mode; -<li><b>"a"</b> append mode; -<li><b>"r+"</b> update mode, all previous data is preserved; -<li><b>"w+"</b> update mode, all previous data is erased; -<li><b>"a+"</b> append update mode, previous data is preserved, +<li><b>"r"</b> --- read mode (the default); +<li><b>"w"</b> --- write mode; +<li><b>"a"</b> --- append mode; +<li><b>"r+"</b> --- update mode, all previous data is preserved; +<li><b>"w+"</b> --- update mode, all previous data is erased; +<li><b>"a+"</b> --- append update mode, previous data is preserved, writing is only allowed at the end of file. </ul> -The <code>mode</code> string 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 exactly what is used in the standard C function <code>fopen</code>. -<p><a name="pdf-io.output"></a><hr/><h3><code>io.output ([file])</code></h3> +<p><a name="pdf-io.output"></a><hr /><h3><code>io.output ([file])</code></h3> <p>Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. -<p><a name="pdf-io.popen"></a><hr/><h3><code>io.popen ([prog [, mode]])</code></h3> +<p><a name="pdf-io.popen"></a><hr /><h3><code>io.popen ([prog [, mode]])</code></h3> <p>Starts program <code>prog</code> in a separated process and returns a file handle that you can use to read data from that program @@ -5372,40 +5486,41 @@ or to write data to that program (if <code>mode</code> is <code>"w"</code>). <p>This function is system dependent and is not available -in all platforms. +on all platforms. -<p><a name="pdf-io.read"></a><hr/><h3><code>io.read (format1, ...)</code></h3> +<p><a name="pdf-io.read"></a><hr /><h3><code>io.read (format1, ...)</code></h3> <p>Equivalent to <code>io.input():read</code>. -<p><a name="pdf-io.tmpfile"></a><hr/><h3><code>io.tmpfile ()</code></h3> +<p><a name="pdf-io.tmpfile"></a><hr /><h3><code>io.tmpfile ()</code></h3> <p>Returns a handle for a temporary file. -This file is open in update mode +This file is opened in update mode and it is automatically removed when the program ends. -<p><a name="pdf-io.type"></a><hr/><h3><code>io.type (obj)</code></h3> +<p><a name="pdf-io.type"></a><hr /><h3><code>io.type (obj)</code></h3> <p>Checks whether <code>obj</code> is a valid file handle. Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, <code>"closed file"</code> if <code>obj</code> is a closed file handle, and <b>nil</b> if <code>obj</code> is not a file handle. -<p><a name="pdf-io.write"></a><hr/><h3><code>io.write (value1, ...)</code></h3> +<p><a name="pdf-io.write"></a><hr /><h3><code>io.write (value1, ...)</code></h3> <p>Equivalent to <code>io.output():write</code>. -<p><a name="pdf-file:close"></a><hr/><h3><code>file:close ()</code></h3> +<p><a name="pdf-file:close"></a><hr /><h3><code>file:close ()</code></h3> <p>Closes <code>file</code>. -Note that files are automatically closed when garbage collected, +Note that files are automatically closed when +their handles are garbage collected, but that takes an unpredictable time to happen. -<p><a name="flush"></a><a name="pdf-file:flush"></a><hr/><h3><code>file:flush ()</code></h3> +<p><a name="flush"></a><a name="pdf-file:flush"></a><hr /><h3><code>file:flush ()</code></h3> <p>Saves any written data to <code>file</code>. -<p><a name="pdf-file:lines"></a><hr/><h3><code>file:lines ()</code></h3> +<p><a name="pdf-file:lines"></a><hr /><h3><code>file:lines ()</code></h3> <p>Returns an iterator function that, each time it is called, @@ -5418,7 +5533,7 @@ will iterate over all lines of the file. (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file when the loop ends.) -<p><a name="pdf-file:read"></a><hr/><h3><code>file:read (format1, ...)</code></h3> +<p><a name="pdf-file:read"></a><hr /><h3><code>file:read (format1, ...)</code></h3> <p>Reads the file <code>file</code>, according to the given formats, which specify what to read. @@ -5445,7 +5560,7 @@ it reads nothing and returns an empty string, or <b>nil</b> on end of file. </ul> -<p><a name="pdf-file:seek"></a><hr/><h3><code>file:seek ([whence] [, offset])</code></h3> +<p><a name="pdf-file:seek"></a><hr /><h3><code>file:seek ([whence] [, offset])</code></h3> <p>Sets and gets the file position, measured from the beginning of the file, @@ -5470,26 +5585,29 @@ beginning of the file (and returns 0); and the call <code>file:seek("end")</code> sets the position to the end of the file, and returns its size. -<p><a name="pdf-file:setvbuf"></a><hr/><h3><code>file:setvbuf (mode [, size])</code></h3> +<p><a name="pdf-file:setvbuf"></a><hr /><h3><code>file:setvbuf (mode [, size])</code></h3> <p>Sets the buffering mode for an output file. There are three available modes: <ul> -<li><b>"no"</b> no buffering; any output operation appear immediately. -<li><b>"full"</b> full buffering; output operation is performed only -when the buffer is full (or when you <code>flush</code> the file (see <a href="#flush">5.7</a>)). -<li><b>"line"</b> line buffering; output is buffered until a newline is -output or there is any input from some special files +<li><b>"no"</b> --- +no buffering; the result of any output operation appears immediately. +<li><b>"full"</b> --- +full buffering; output operation is performed only +when the buffer is full (or when you explicitly <code>flush</code> the file (see <a href="#flush">5.7</a>)). +<li><b>"line"</b> --- +line buffering; output is buffered until a newline is output +or there is any input from some special files (such as a terminal device). </ul> For the last two cases, <code>sizes</code> specifies the size of the buffer, in bytes. The default is an appropriate size. -<p><a name="pdf-file:write"></a><hr/><h3><code>file:write (value1, ...)</code></h3> +<p><a name="pdf-file:write"></a><hr /><h3><code>file:write (value1, ...)</code></h3> <p>Writes the value of each of its arguments to -the filehandle <code>file</code>. +the <code>file</code>. The arguments must be strings or numbers. To write other values, use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>. @@ -5498,12 +5616,12 @@ use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.fo <p>This library is implemented through table <code>os</code>. -<p><a name="pdf-os.clock"></a><hr/><h3><code>os.clock ()</code></h3> +<p><a name="pdf-os.clock"></a><hr /><h3><code>os.clock ()</code></h3> -<p>Returns an approximation of the amount of CPU time -used by the program, in seconds. +<p>Returns an approximation of the amount in seconds of CPU time +used by the program. -<p><a name="pdf-os.date"></a><hr/><h3><code>os.date ([format [, time]])</code></h3> +<p><a name="pdf-os.date"></a><hr /><h3><code>os.date ([format [, time]])</code></h3> <p>Returns a string or a table containing date and time, formatted according to the given string <code>format</code>. @@ -5533,43 +5651,46 @@ formatted according to the same rules as the C function <code>strftime</code>. the host system and on the current locale (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). -<p><a name="pdf-os.difftime"></a><hr/><h3><code>os.difftime (t2, t1)</code></h3> +<p><a name="pdf-os.difftime"></a><hr /><h3><code>os.difftime (t2, t1)</code></h3> <p>Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. In Posix, Windows, and some other systems, this value is exactly <code>t2</code><em>-</em><code>t1</code>. -<p><a name="pdf-os.execute"></a><hr/><h3><code>os.execute (command)</code></h3> +<p><a name="pdf-os.execute"></a><hr /><h3><code>os.execute ([command])</code></h3> <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 a status code, which is system-dependent. +If <code>command</code> is absent, then it returns nonzero if a shell is available +and zero otherwise. -<p><a name="pdf-os.exit"></a><hr/><h3><code>os.exit ([code])</code></h3> +<p><a name="pdf-os.exit"></a><hr /><h3><code>os.exit ([code])</code></h3> <p>Calls the C function <code>exit</code>, with an optional <code>code</code>, to terminate the host program. The default value for <code>code</code> is the success code. -<p><a name="pdf-os.getenv"></a><hr/><h3><code>os.getenv (varname)</code></h3> +<p><a name="pdf-os.getenv"></a><hr /><h3><code>os.getenv (varname)</code></h3> <p>Returns the value of the process environment variable <code>varname</code>, or <b>nil</b> if the variable is not defined. -<p><a name="pdf-os.remove"></a><hr/><h3><code>os.remove (filename)</code></h3> +<p><a name="pdf-os.remove"></a><hr /><h3><code>os.remove (filename)</code></h3> -<p>Deletes the file with the given name. +<p>Deletes the file or directory with the given name. +Directories must be empty to be removed. If this function fails, it returns <b>nil</b>, plus a string describing the error. -<p><a name="pdf-os.rename"></a><hr/><h3><code>os.rename (oldname, newname)</code></h3> +<p><a name="pdf-os.rename"></a><hr /><h3><code>os.rename (oldname, newname)</code></h3> -<p>Renames file named <code>oldname</code> to <code>newname</code>. +<p>Renames file or directory named <code>oldname</code> to <code>newname</code>. If this function fails, it returns <b>nil</b>, plus a string describing the error. -<p><a name="pdf-os.setlocale"></a><hr/><h3><code>os.setlocale (locale [, category])</code></h3> +<p><a name="pdf-os.setlocale"></a><hr /><h3><code>os.setlocale (locale [, category])</code></h3> <p>Sets the current locale of the program. <code>locale</code> is a string specifying a locale; @@ -5580,7 +5701,7 @@ the default category is <code>"all"</code>. The function returns the name of the new locale, or <b>nil</b> if the request cannot be honored. -<p><a name="pdf-os.time"></a><hr/><h3><code>os.time ([table])</code></h3> +<p><a name="pdf-os.time"></a><hr /><h3><code>os.time ([table])</code></h3> <p>Returns the current time when called without arguments, or a time representing the date and time specified by the given table. @@ -5595,16 +5716,16 @@ In other systems, the meaning is not specified, and the number returned by <code>time</code> can be used only as an argument to <code>date</code> and <code>difftime</code>. -<p><a name="pdf-os.tmpname"></a><hr/><h3><code>os.tmpname ()</code></h3> +<p><a name="pdf-os.tmpname"></a><hr /><h3><code>os.tmpname ()</code></h3> <p>Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use -and removed when no longer needed. +and explicitly removed when no longer needed. -<p><a name="libdebug"></a><a name="5.9"></a><h2>5.9 - The Reflexive Debug Interface</h2> +<p><a name="libdebug"></a><a name="5.9"></a><h2>5.9 - The Debug Library</h2> -<p>The <em>debug library</em> provides +<p>This library provides the functionality of the debug interface to Lua programs. You should exert care when using this library. The functions provided here should be used exclusively for debugging @@ -5614,14 +5735,15 @@ usual programming tool: They can be very slow. Moreover, several of its functions violate some assumptions about Lua code -(e.g., that local variables cannot be accessed from outside or +(e.g., that variables local to a function +cannot be accessed from outside or that userdata metatables cannot be changed by Lua code) -and therefore can compromise some otherwise secure code. +and therefore can compromise otherwise secure code. <p>All functions in this library are provided -inside a <code>debug</code> table. +inside the <code>debug</code> table. -<p><a name="pdf-debug.debug"></a><hr/><h3><code>debug.debug ()</code></h3> +<p><a name="pdf-debug.debug"></a><hr /><h3><code>debug.debug ()</code></h3> <p>Enters an interactive mode with the user, running each string that the user enters. @@ -5631,22 +5753,22 @@ change their values, evaluate expressions, and so on. A line containing only the word <code>cont</code> finishes this function, so that the caller continues its execution. -<p>Note that commands for <a href="#pdf-debug.debug"><code>debug.debug</code></a> are not lexically nested -with any function, so they have no direct access to local variables. +<p>Note that commands for <code>debug.debug</code> are not lexically nested +within any function, and so have no direct access to local variables. -<p><a name="pdf-debug.getfenv"></a><hr/><h3><code>debug.getfenv (o)</code></h3> +<p><a name="pdf-debug.getfenv"></a><hr /><h3><code>debug.getfenv (o)</code></h3> Returns the environment of object <code>o</code>. -<p><a name="pdf-debug.gethook"></a><hr/><h3><code>debug.gethook ()</code></h3> +<p><a name="pdf-debug.gethook"></a><hr /><h3><code>debug.gethook ()</code></h3> <p>Returns the current hook settings, as three values: the current hook function, the current hook mask, and the current hook count (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). -<p><a name="pdf-debug.getinfo"></a><hr/><h3><code>debug.getinfo (function [, what])</code></h3> +<p><a name="pdf-debug.getinfo"></a><hr /><h3><code>debug.getinfo (function [, what])</code></h3> -<p>This function returns a table with information about a function. +<p>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 call stack: @@ -5664,11 +5786,11 @@ the option `<code>f</code>´ adds a field named <code>func</code> with the function itself. <p>For instance, the expression <code>debug.getinfo(1,"n").name</code> returns -the name of the current function, if a reasonable name can be found, +a name of the current function, if a reasonable name can be found, and <code>debug.getinfo(print)</code> returns a table with all available information about the <a href="#pdf-print"><code>print</code></a> function. -<p><a name="pdf-debug.getlocal"></a><hr/><h3><code>debug.getlocal (level, local)</code></h3> +<p><a name="pdf-debug.getlocal"></a><hr /><h3><code>debug.getlocal (level, local)</code></h3> <p>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. @@ -5683,26 +5805,26 @@ and raises an error when called with a <code>level</code> out of range. represent internal variables (loop control variables, temporaries, and C function locals). -<p><a name="pdf-debug.getmetatable"></a><hr/><h3><code>debug.getmetatable (object)</code></h3> +<p><a name="pdf-debug.getmetatable"></a><hr /><h3><code>debug.getmetatable (object)</code></h3> -<p>If <code>object</code> does not have a metatable, returns <b>nil</b>. -Otherwise, returns the metatable of the given object. +<p>Returns the metatable of the given <code>object</code> +or <b>nil</b> if it does not have a metatable. -<p><a name="pdf-debug.getregistry"></a><hr/><h3><code>debug.getregistry ()</code></h3> +<p><a name="pdf-debug.getregistry"></a><hr /><h3><code>debug.getregistry ()</code></h3> <p>Returns the registry table (see <a href="#registry">3.5</a>). -<p><a name="pdf-debug.getupvalue"></a><hr/><h3><code>debug.getupvalue (func, up)</code></h3> +<p><a name="pdf-debug.getupvalue"></a><hr /><h3><code>debug.getupvalue (func, up)</code></h3> <p>This function returns the name and the value of the upvalue with index <code>up</code> of the function <code>func</code>. The function returns <b>nil</b> if there is no upvalue with the given index. -<p><a name="pdf-debug.setfenv"></a><hr/><h3><code>debug.setfenv (o, table)</code></h3> +<p><a name="pdf-debug.setfenv"></a><hr /><h3><code>debug.setfenv (object, table)</code></h3> -<p>Sets the environment of the given object. +<p>Sets the environment of the given <code>object</code> to the given <code>table</code>. -<p><a name="pdf-debug.sethook"></a><hr/><h3><code>debug.sethook (hook, mask [, count])</code></h3> +<p><a name="pdf-debug.sethook"></a><hr /><h3><code>debug.sethook (hook, mask [, count])</code></h3> <p>Sets the given function as a hook. The string <code>mask</code> and the number <code>count</code> describe @@ -5710,22 +5832,22 @@ when the hook will be called. The string mask may have the following characters, with the given meaning: <ul> -<li><b><code>"c"</code></b> The hook is called every time Lua calls a function; -<li><b><code>"r"</code></b> The hook is called every time Lua returns from a function; -<li><b><code>"l"</code></b> The hook is called every time Lua enters a new line of code. +<li><b><code>"c"</code></b> --- The hook is called every time Lua calls a function; +<li><b><code>"r"</code></b> --- The hook is called every time Lua returns from a function; +<li><b><code>"l"</code></b> --- The hook is called every time Lua enters a new line of code. </ul> With a <code>count</code> different from zero, the hook is called after every <code>count</code> instructions. <p>When called without arguments, -the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function turns off the hook. +<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. -<p>When the hook is called, its first parameter is always a string -describing the event that triggered its call: +<p>When the hook is called, its first parameter is a string +describing the event that has triggered its call: <code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>), <code>"line"</code>, and <code>"count"</code>. -Moreover, for line events, -it also gets as its second parameter the new line number. +For line events, +the hook also gets the new line number as its second parameter. Inside a hook, you can call <code>getinfo</code> with level 2 to get more information about the running function @@ -5735,7 +5857,7 @@ unless the event is <code>"tail return"</code>. In this case, Lua is only simulating the return, and a call to <code>getinfo</code> will return invalid data. -<p><a name="pdf-debug.setlocal"></a><hr/><h3><code>debug.setlocal (level, local, value)</code></h3> +<p><a name="pdf-debug.setlocal"></a><hr /><h3><code>debug.setlocal (level, local, value)</code></h3> <p>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. @@ -5745,11 +5867,12 @@ 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.) Otherwise, it returns the name of the local variable. -<p><a name="pdf-debug.setmetatable"></a><hr/><h3><code>debug.setmetatable (o, metatable)</code></h3> +<p><a name="pdf-debug.setmetatable"></a><hr /><h3><code>debug.setmetatable (object, table)</code></h3> -<p>Sets the metatable for the given object. +<p>Sets the metatable for the given <code>object</code> to the given id@{table} +(which can be <b>nil</b>). -<p><a name="pdf-debug.setupvalue"></a><hr/><h3><code>debug.setupvalue (func, up, value)</code></h3> +<p><a name="pdf-debug.setupvalue"></a><hr /><h3><code>debug.setupvalue (func, up, value)</code></h3> <p>This function assigns the value <code>value</code> to the upvalue with index <code>up</code> of the function <code>func</code>. @@ -5757,7 +5880,7 @@ The function returns <b>nil</b> if there is no upvalue with the given index. Otherwise, it returns the name of the upvalue. -<p><a name="pdf-debug.traceback"></a><hr/><h3><code>debug.traceback ([message])</code></h3> +<p><a name="pdf-debug.traceback"></a><hr /><h3><code>debug.traceback ([message])</code></h3> <p>Returns a string with a traceback of the call stack. An optional <code>message</code> string is appended @@ -5775,7 +5898,7 @@ An interpreter for Lua as a stand-alone language, called simply <code>lua</code>, is provided with the standard distribution. The stand-alone interpreter includes -all standard libraries plus the reflexive debug interface. +all standard libraries, including the debug library. Its usage is: <pre> lua [options] [script [args]] @@ -5790,30 +5913,31 @@ The options are: <li><b><code>-</code> </b> executes <code>stdin</code> as a file and stops handling options. </ul> After handling its options, <code>lua</code> runs the given <em>script</em>, -passing to it the given <em>args</em>. +passing to it the given <em>args</em> as string arguments. When called without arguments, -<code>lua</code> 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 the standard input (<code>stdin</code>) is a terminal, and as <code>lua -</code> otherwise. <p>Before running any argument, the interpreter checks for an environment variable <code>LUA_INIT</code>. If its format is @<em>filename</em>, -then lua executes the file. -Otherwise, lua executes the string itself. +then <code>lua</code> executes the file. +Otherwise, <code>lua</code> executes the string itself. <p>All options are handled in order, except <code>-i</code>. For instance, an invocation like <pre> $ lua -e'a=1' -e 'print(a)' script.lua </pre> -will first set <code>a</code> to 1, then print <code>a</code>, -and finally run the file <code>script.lua</code>. +will first set <code>a</code> to 1, then print the value of <code>a</code> (which is `<code>1</code>´), +and finally run the file <code>script.lua</code> with no arguments. (Here <code>$</code> is the shell prompt. Your prompt may be different.) <p>Before starting to run the script, <code>lua</code> collects all arguments in the command line in a global table called <code>arg</code>. -The script name is stored in index 0, +The script name is stored at index 0, the first argument after the script name goes to index 1, and so on. Any arguments before the script name @@ -5821,34 +5945,40 @@ Any arguments before the script name go to negative indices. For instance, in the call <pre> - $ lua -la.lua b.lua t1 t2 + $ lua -la b.lua t1 t2 </pre> the interpreter first runs the file <code>a.lua</code>, then creates a table <pre> - arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua", + arg = { [-2] = "lua", [-1] = "-la", + [0] = "b.lua", [1] = "t1", [2] = "t2" } </pre> and finally runs the file <code>b.lua</code>. The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ... as arguments; -it can access those arguments with the vararg expression <code>...</code>. +it can also access those arguments with the vararg expression `<code>...</code>´. <p>In interactive mode, if you write an incomplete statement, -the interpreter waits for its completion. +the interpreter waits for its completion +by issuing a different prompt. -<p>If the global variable <code>_PROMPT</code> is defined as a string, +<p>If the global variable <code>_PROMPT</code> contains a string, then its value is used as the prompt. -Therefore, the prompt can be changed directly on the command line: +Similarly, if the global variable <code>_PROMPT2</code> contains a string, +it its value is used as the secondary prompt +(issued during incomplete statements). +Therefore, both prompts can be changed directly on the command line. +For instance, <pre> $ lua -e"_PROMPT='myprompt> '" -i </pre> (the outer pair of quotes is for the shell, -the inner is for Lua), +the inner pair is for Lua), or in any Lua programs by assigning to <code>_PROMPT</code>. Note the use of <code>-i</code> to enter interactive mode; otherwise, -the program would end just after the assignment to <code>_PROMPT</code>. +the program would just end silently right after the assignment to <code>_PROMPT</code>. <p>To allow the use of Lua as a script interpreter in Unix systems, @@ -5869,17 +5999,17 @@ then </pre> is a more portable solution.) -<p><hr/> +<p><hr /> -<p><h1>Incompatibilities with Previous Version</h1> +<p><h1>Incompatibilities with the Previous Version</h1> -<p>Here we list the incompatibilities when moving a program +<p>Here we list the incompatibilities that may be found when moving a program from Lua 5.0 to Lua 5.1. You can avoid most of the incompatibilities compiling Lua with -appropriate options. +appropriate options (see file <code>luaconf.h</code>). However, -all those compatibility options will be removed in the next version. +all those compatibility options will be removed in the next version of Lua. <p><h2>Incompatibilities with version 5.0</h2> @@ -5888,25 +6018,21 @@ all those compatibility options will be removed in the next version. <li> The vararg system changed from the pseudo-argument <code>arg</code> with a table with the extra arguments to the vararg expression. -(Option <code>LUA_COMPAT_VARARG</code>) +(Option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) <p><li> There was a subtle change in the scope of the implicit -variables of the <b>for</b> constructor. +variables of the <b>for</b> statement and for the <b>repeat</b> statement. <p><li> The long string/long comment syntax (<code>[[...]]</code>) does not allow nesting. You can use the new syntax (<code>[=[...]=]</code>) in those cases. -(Option <code>LUA_COMPAT_LSTR</code>) +(Option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) <p></ul> <p><h3>Changes in the Libraries</h3> <ul> -<li> -Function <a href="#pdf-string.find"><code>string.find</code></a> does not return its captures. -Use <a href="#pdf-string.match"><code>string.match</code></a> for that. -(Option <code>LUA_COMPAT_FIND</code>) <p><li> Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. @@ -5935,10 +6061,10 @@ Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.f (Option <code>LUA_COMPAT_MOD</code>) <p><li> -There was substantial changes in function <a href="#pdf-require"><code>require</code></a> due to +There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to the new module system. However, the new behavior is mostly compatible with the old, -but it gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead +but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead of from <code>LUA_PATH</code>. <p><li> @@ -5952,7 +6078,7 @@ use <code>collectgarbage("count")</code> instead. <ul> <li> Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to -allow the user to set an allocation function. +allow the user to set a memory allocation function. You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to create a state with a standard allocation function (based on <code>realloc</code>). @@ -5973,6 +6099,11 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod <a name="BNF"></a><h1>The Complete Syntax of Lua</h1> +<p>Here is the complete syntax of Lua in extended BNF. +It does not describe operator priorities nor some syntactical restrictions, +such as <b>return</b> and <b>break</b> statements +can only appear as the <em>last</em> statement of a block. + <p> <p><pre> @@ -5991,7 +6122,7 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod <b>for</b> namelist <b>in</b> explist1 <b>do</b> block <b>end</b> | <b>function</b> funcname funcbody | <b>local</b> <b>function</b> Name funcbody | - <b>local</b> namelist [init] + <b>local</b> namelist [`<b>=</b>´ explist1] laststat ::= <b>return</b> [explist1] | <b>break</b> @@ -6003,18 +6134,16 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod namelist ::= Name {`<b>,</b>´ Name} - init ::= `<b>=</b>´ explist1 - explist1 ::= {exp `<b>,</b>´} exp - exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | Literal | `<b>...</b>´ | + exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function | prefixexp | tableconstructor | exp binop exp | unop exp prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args - args ::= `<b>(</b>´ [explist1] `<b>)</b>´ | tableconstructor | Literal + args ::= `<b>(</b>´ [explist1] `<b>)</b>´ | tableconstructor | String function ::= <b>function</b> funcbody @@ -6026,7 +6155,7 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod fieldlist ::= field {fieldsep field} [fieldsep] - field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | name `<b>=</b>´ exp | exp + field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp fieldsep ::= `<b>,</b>´ | `<b>;</b>´ @@ -6042,10 +6171,5 @@ Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><cod <p> -<HR> -<SMALL> -Last update: -Tue Nov 1 15:20:21 BRST 2005 -</SMALL> - </body></html> + diff --git a/src/Makefile b/src/Makefile index 60fd14c8..b042d9ab 100644 --- a/src/Makefile +++ b/src/Makefile @@ -4,6 +4,9 @@ # == CHANGE THE SETTINGS BELOW TO SUIT YOUR ENVIRONMENT ======================= +# Your platform. See PLATS for possible values. +PLAT= none + CC= gcc CFLAGS= -O2 -Wall $(MYCFLAGS) AR= ar rcu @@ -14,12 +17,11 @@ LIBS= -lm $(MYLIBS) MYCFLAGS= MYLDFLAGS= MYLIBS= -# enable dynamic loading and line editing in Linux -# MYCFLAGS= -DLUA_USE_DLOPEN -DLUA_USE_READLINE -# MYLIBS= -Wl,-E -ldl -lreadline -lhistory -lncurses # == END OF USER SETTINGS. NO NEED TO CHANGE ANYTHING BELOW THIS LINE ========= +PLATS= ansi bsd generic linux macosx mingw posix + LUA_A= liblua.a CORE_O= lapi.o lcode.o ldebug.o ldo.o ldump.o lfunc.o lgc.o llex.o lmem.o \ lobject.o lopcodes.o lparser.o lstate.o lstring.o ltable.o ltm.o \ @@ -37,6 +39,8 @@ ALL_O= $(CORE_O) $(LIB_O) $(LUA_O) $(LUAC_O) ALL_T= $(LUA_A) $(LUA_T) $(LUAC_T) ALL_A= $(LUA_A) +default: $(PLAT) + all: $(ALL_T) o: $(ALL_O) @@ -60,6 +64,7 @@ depend: @$(CC) $(CFLAGS) -MM l*.c print.c echo: + @echo "PLAT = $(PLAT)" @echo "CC = $(CC)" @echo "CFLAGS = $(CFLAGS)" @echo "AR = $(AR)" @@ -69,6 +74,34 @@ echo: @echo "MYLDFLAGS = $(MYLDFLAGS)" @echo "MYLIBS = $(MYLIBS)" +# convenience targets for usual platforms + +none: + @echo "Please choose a platform: $(PLATS)" + +ansi: + $(MAKE) all MYCFLAGS=-DLUA_ANSI + +bsd: + $(MAKE) all MYCFLAGS="-DLUA_USE_POSIX -DLUA_USE_DLOPEN" MYLIBS="-Wl,-E" + +generic: + $(MAKE) all MYCFLAGS= + +linux: + $(MAKE) all MYCFLAGS=-DLUA_USE_LINUX MYLIBS="-Wl,-E -ldl -lreadline -lhistory -lncurses" + +macosx: + $(MAKE) all MYCFLAGS=-DLUA_USE_MACOSX + +mingw: + $(MAKE) "LUA_A=lua51.dll" "LUA_T=lua.exe" \ + "AR=gcc -shared -o" "RANLIB=strip --strip-unneeded" \ + "MYCFLAGS=-DLUA_BUILD_AS_DLL" "MYLIBS=" "MYLDFLAGS=-s" lua.exe + +posix: + $(MAKE) all MYCFLAGS=-DLUA_USE_POSIX + # DO NOT DELETE lapi.o: lapi.c lua.h luaconf.h lapi.h lobject.h llimits.h ldebug.h \ @@ -86,8 +119,8 @@ ldebug.o: ldebug.c lua.h luaconf.h lapi.h lobject.h llimits.h lcode.h \ ldo.o: ldo.c lua.h luaconf.h ldebug.h lstate.h lobject.h llimits.h ltm.h \ lzio.h lmem.h ldo.h lfunc.h lgc.h lopcodes.h lparser.h ltable.h \ lstring.h lundump.h lvm.h -ldump.o: ldump.c lua.h luaconf.h lobject.h llimits.h lopcodes.h lstate.h \ - ltm.h lzio.h lmem.h lundump.h +ldump.o: ldump.c lua.h luaconf.h lobject.h llimits.h lstate.h ltm.h \ + lzio.h lmem.h lundump.h lfunc.o: lfunc.c lua.h luaconf.h lfunc.h lobject.h llimits.h lgc.h lmem.h \ lstate.h ltm.h lzio.h lgc.o: lgc.c lua.h luaconf.h ldebug.h lstate.h lobject.h llimits.h ltm.h \ @@ -99,10 +132,11 @@ llex.o: llex.c lua.h luaconf.h ldo.h lobject.h llimits.h lstate.h ltm.h \ lmathlib.o: lmathlib.c lua.h luaconf.h lauxlib.h lualib.h lmem.o: lmem.c lua.h luaconf.h ldebug.h lstate.h lobject.h llimits.h \ ltm.h lzio.h lmem.h ldo.h -loadlib.o: loadlib.c lua.h luaconf.h lauxlib.h lualib.h +loadlib.o: loadlib.c lauxlib.h lua.h luaconf.h lobject.h llimits.h \ + lualib.h lobject.o: lobject.c lua.h luaconf.h ldo.h lobject.h llimits.h lstate.h \ ltm.h lzio.h lmem.h lstring.h lgc.h lvm.h -lopcodes.o: lopcodes.c lua.h luaconf.h lobject.h llimits.h lopcodes.h +lopcodes.o: lopcodes.c lopcodes.h llimits.h lua.h luaconf.h loslib.o: loslib.c lua.h luaconf.h lauxlib.h lualib.h lparser.o: lparser.c lua.h luaconf.h lcode.h llex.h lobject.h llimits.h \ lzio.h lmem.h lopcodes.h lparser.h ltable.h ldebug.h lstate.h ltm.h \ @@ -122,8 +156,7 @@ luac.o: luac.c lua.h luaconf.h lauxlib.h ldo.h lobject.h llimits.h \ lstate.h ltm.h lzio.h lmem.h lfunc.h lopcodes.h lstring.h lgc.h \ lundump.h lundump.o: lundump.c lua.h luaconf.h ldebug.h lstate.h lobject.h \ - llimits.h ltm.h lzio.h lmem.h ldo.h lfunc.h lopcodes.h lstring.h lgc.h \ - lundump.h + llimits.h ltm.h lzio.h lmem.h ldo.h lfunc.h lstring.h lgc.h lundump.h lvm.o: lvm.c lua.h luaconf.h ldebug.h lstate.h lobject.h llimits.h ltm.h \ lzio.h lmem.h ldo.h lfunc.h lgc.h lopcodes.h lstring.h ltable.h lvm.h lzio.o: lzio.c lua.h luaconf.h llimits.h lmem.h lstate.h lobject.h ltm.h \ @@ -1,5 +1,5 @@ /* -** $Id: lapi.c,v 2.51 2005/10/20 11:35:50 roberto Exp $ +** $Id: lapi.c,v 2.53 2006/01/10 12:50:00 roberto Exp $ ** Lua API ** See Copyright Notice in lua.h */ @@ -40,7 +40,7 @@ const char lua_ident[] = #define api_checknelems(L, n) api_check(L, (n) <= (L->top - L->base)) -#define api_checkvalidindex(L, i) api_check(L, (i) != &luaO_nilobject) +#define api_checkvalidindex(L, i) api_check(L, (i) != luaO_nilobject) #define api_incr_top(L) {api_check(L, L->top < L->ci->top); L->top++;} @@ -50,7 +50,7 @@ static TValue *index2adr (lua_State *L, int idx) { if (idx > 0) { TValue *o = L->base + (idx - 1); api_check(L, idx <= L->ci->top - L->base); - if (o >= L->top) return cast(TValue *, &luaO_nilobject); + if (o >= L->top) return cast(TValue *, luaO_nilobject); else return o; } else if (idx > LUA_REGISTRYINDEX) { @@ -70,7 +70,7 @@ static TValue *index2adr (lua_State *L, int idx) { idx = LUA_GLOBALSINDEX - idx; return (idx <= func->c.nupvalues) ? &func->c.upvalue[idx-1] - : cast(TValue *, &luaO_nilobject); + : cast(TValue *, luaO_nilobject); } } } @@ -153,7 +153,7 @@ LUA_API lua_State *lua_newthread (lua_State *L) { LUA_API int lua_gettop (lua_State *L) { - return cast(int, L->top - L->base); + return cast_int(L->top - L->base); } @@ -234,7 +234,7 @@ LUA_API void lua_pushvalue (lua_State *L, int idx) { LUA_API int lua_type (lua_State *L, int idx) { StkId o = index2adr(L, idx); - return (o == &luaO_nilobject) ? LUA_TNONE : ttype(o); + return (o == luaO_nilobject) ? LUA_TNONE : ttype(o); } @@ -272,7 +272,7 @@ LUA_API int lua_isuserdata (lua_State *L, int idx) { LUA_API int lua_rawequal (lua_State *L, int index1, int index2) { StkId o1 = index2adr(L, index1); StkId o2 = index2adr(L, index2); - return (o1 == &luaO_nilobject || o2 == &luaO_nilobject) ? 0 + return (o1 == luaO_nilobject || o2 == luaO_nilobject) ? 0 : luaO_rawequalObj(o1, o2); } @@ -283,8 +283,7 @@ LUA_API int lua_equal (lua_State *L, int index1, int index2) { lua_lock(L); /* may call tag method */ o1 = index2adr(L, index1); o2 = index2adr(L, index2); - i = (o1 == &luaO_nilobject || o2 == &luaO_nilobject) ? 0 - : equalobj(L, o1, o2); + i = (o1 == luaO_nilobject || o2 == luaO_nilobject) ? 0 : equalobj(L, o1, o2); lua_unlock(L); return i; } @@ -296,7 +295,7 @@ LUA_API int lua_lessthan (lua_State *L, int index1, int index2) { lua_lock(L); /* may call tag method */ o1 = index2adr(L, index1); o2 = index2adr(L, index2); - i = (o1 == &luaO_nilobject || o2 == &luaO_nilobject) ? 0 + i = (o1 == luaO_nilobject || o2 == luaO_nilobject) ? 0 : luaV_lessthan(L, o1, o2); lua_unlock(L); return i; @@ -430,7 +429,7 @@ LUA_API void lua_pushnumber (lua_State *L, lua_Number n) { LUA_API void lua_pushinteger (lua_State *L, lua_Integer n) { lua_lock(L); - setnvalue(L->top, cast(lua_Number, n)); + setnvalue(L->top, cast_num(n)); api_incr_top(L); lua_unlock(L); } @@ -910,11 +909,11 @@ LUA_API int lua_gc (lua_State *L, int what, int data) { } case LUA_GCCOUNT: { /* GC values are expressed in Kbytes: #bytes/2^10 */ - res = cast(int, g->totalbytes >> 10); + res = cast_int(g->totalbytes >> 10); break; } case LUA_GCCOUNTB: { - res = cast(int, g->totalbytes & 0x3ff); + res = cast_int(g->totalbytes & 0x3ff); break; } case LUA_GCSTEP: { @@ -983,7 +982,7 @@ LUA_API void lua_concat (lua_State *L, int n) { api_checknelems(L, n); if (n >= 2) { luaC_checkGC(L); - luaV_concat(L, n, cast(int, L->top - L->base) - 1); + luaV_concat(L, n, cast_int(L->top - L->base) - 1); L->top -= (n-1); } else if (n == 0) { /* push empty string */ diff --git a/src/lauxlib.c b/src/lauxlib.c index 04620979..d3b54ee4 100644 --- a/src/lauxlib.c +++ b/src/lauxlib.c @@ -1,5 +1,5 @@ /* -** $Id: lauxlib.c,v 1.156 2005/10/21 13:47:42 roberto Exp $ +** $Id: lauxlib.c,v 1.157 2005/12/29 15:32:11 roberto Exp $ ** Auxiliary functions for building Lua libraries ** See Copyright Notice in lua.h */ @@ -226,16 +226,24 @@ LUALIB_API void (luaL_register) (lua_State *L, const char *libname, } +static int libsize (const luaL_Reg *l) { + int size = 0; + for (; l->name; l++) size++; + return size; +} + + LUALIB_API void luaI_openlib (lua_State *L, const char *libname, const luaL_Reg *l, int nup) { if (libname) { + int size = libsize(l); /* check whether lib already exists */ - luaL_findtable(L, LUA_REGISTRYINDEX, "_LOADED"); + luaL_findtable(L, LUA_REGISTRYINDEX, "_LOADED", size); lua_getfield(L, -1, libname); /* get _LOADED[libname] */ if (!lua_istable(L, -1)) { /* not found? */ lua_pop(L, 1); /* remove previous result */ /* try global variable (and create one if it does not exist) */ - if (luaL_findtable(L, LUA_GLOBALSINDEX, libname) != NULL) + if (luaL_findtable(L, LUA_GLOBALSINDEX, libname, size) != NULL) luaL_error(L, "name conflict for module " LUA_QS, libname); lua_pushvalue(L, -1); lua_setfield(L, -3, libname); /* _LOADED[libname] = new table */ @@ -331,7 +339,7 @@ LUALIB_API const char *luaL_gsub (lua_State *L, const char *s, const char *p, LUALIB_API const char *luaL_findtable (lua_State *L, int idx, - const char *fname) { + const char *fname, int szhint) { const char *e; lua_pushvalue(L, idx); do { @@ -341,7 +349,7 @@ LUALIB_API const char *luaL_findtable (lua_State *L, int idx, lua_rawget(L, -2); if (lua_isnil(L, -1)) { /* no such field? */ lua_pop(L, 1); /* remove this nil */ - lua_newtable(L); /* create a new table for field */ + lua_createtable(L, 0, (*e == '.' ? 1 : szhint)); /* new table for field */ lua_pushlstring(L, fname, e - fname); lua_pushvalue(L, -2); lua_settable(L, -4); /* set new table into field */ diff --git a/src/lauxlib.h b/src/lauxlib.h index ee503cc8..1bba1c04 100644 --- a/src/lauxlib.h +++ b/src/lauxlib.h @@ -1,5 +1,5 @@ /* -** $Id: lauxlib.h,v 1.86 2005/10/21 13:47:42 roberto Exp $ +** $Id: lauxlib.h,v 1.87 2005/12/29 15:32:11 roberto Exp $ ** Auxiliary functions for building Lua libraries ** See Copyright Notice in lua.h */ @@ -86,7 +86,7 @@ LUALIB_API const char *(luaL_gsub) (lua_State *L, const char *s, const char *p, const char *r); LUALIB_API const char *(luaL_findtable) (lua_State *L, int idx, - const char *fname); + const char *fname, int szhint); diff --git a/src/lbaselib.c b/src/lbaselib.c index 7d8724a5..1778e775 100644 --- a/src/lbaselib.c +++ b/src/lbaselib.c @@ -1,5 +1,5 @@ /* -** $Id: lbaselib.c,v 1.186 2005/10/21 13:47:42 roberto Exp $ +** $Id: lbaselib.c,v 1.188 2005/12/29 15:32:11 roberto Exp $ ** Basic library ** See Copyright Notice in lua.h */ @@ -201,7 +201,7 @@ static int luaB_collectgarbage (lua_State *L) { switch (optsnum[o]) { case LUA_GCCOUNT: { int b = lua_gc(L, LUA_GCCOUNTB, 0); - lua_pushnumber(L, ((lua_Number)res*1024 + b)/1000); + lua_pushnumber(L, ((lua_Number)res*1024 + b)/1024); return 1; } case LUA_GCSTEP: { @@ -625,7 +625,7 @@ static void base_open (lua_State *L) { auxopen(L, "ipairs", luaB_ipairs, ipairsaux); auxopen(L, "pairs", luaB_pairs, luaB_next); /* `newproxy' needs a weaktable as upvalue */ - lua_newtable(L); /* new table `w' */ + lua_createtable(L, 0, 1); /* new table `w' */ lua_pushvalue(L, -1); /* `w' will be its own metatable */ lua_setmetatable(L, -2); lua_pushliteral(L, "kv"); diff --git a/src/lcode.c b/src/lcode.c index ecda5cbf..dd3e37e7 100644 --- a/src/lcode.c +++ b/src/lcode.c @@ -1,5 +1,5 @@ /* -** $Id: lcode.c,v 2.22 2005/11/16 11:55:27 roberto Exp $ +** $Id: lcode.c,v 2.24 2005/12/22 16:19:56 roberto Exp $ ** Code generator for Lua ** See Copyright Notice in lua.h */ @@ -196,7 +196,7 @@ void luaK_checkstack (FuncState *fs, int n) { if (newstack > fs->f->maxstacksize) { if (newstack >= MAXSTACK) luaX_syntaxerror(fs->ls, "function or expression too complex"); - fs->f->maxstacksize = cast(lu_byte, newstack); + fs->f->maxstacksize = cast_byte(newstack); } } @@ -227,11 +227,11 @@ static int addk (FuncState *fs, TValue *k, TValue *v) { Proto *f = fs->f; int oldsize = f->sizek; if (ttisnumber(idx)) { - lua_assert(luaO_rawequalObj(&fs->f->k[cast(int, nvalue(idx))], v)); - return cast(int, nvalue(idx)); + lua_assert(luaO_rawequalObj(&fs->f->k[cast_int(nvalue(idx))], v)); + return cast_int(nvalue(idx)); } else { /* constant not found; create a new entry */ - setnvalue(idx, cast(lua_Number, fs->nk)); + setnvalue(idx, cast_num(fs->nk)); luaM_growvector(L, f->k, fs->nk, f->sizek, TValue, MAXARG_Bx, "constant table overflow"); while (oldsize < f->sizek) setnilvalue(&f->k[oldsize++]); @@ -647,7 +647,7 @@ static int constfolding (OpCode op, expdesc *e1, expdesc *e2) { case OP_LEN: return 0; /* no constant folding for 'len' */ default: lua_assert(0); r = 0; break; } - if (r != r) return 0; /* do not attempt to produce NaN */ + if (luai_numisnan(r)) return 0; /* do not attempt to produce NaN */ e1->u.nval = r; return 1; } diff --git a/src/ldblib.c b/src/ldblib.c index 5da6e1da..26a19b6a 100644 --- a/src/ldblib.c +++ b/src/ldblib.c @@ -1,5 +1,5 @@ /* -** $Id: ldblib.c,v 1.103 2005/11/01 16:08:32 roberto Exp $ +** $Id: ldblib.c,v 1.104 2005/12/29 15:32:11 roberto Exp $ ** Interface from Lua to its debug API ** See Copyright Notice in lua.h */ @@ -116,7 +116,7 @@ static int db_getinfo (lua_State *L) { return luaL_argerror(L, arg+1, "function or level expected"); if (!lua_getinfo(L1, options, &ar)) return luaL_argerror(L, arg+2, "invalid option"); - lua_newtable(L); + lua_createtable(L, 0, 2); if (strchr(options, 'S')) { settabss(L, "source", ar.source); settabss(L, "short_src", ar.short_src); @@ -246,7 +246,7 @@ static void gethooktable (lua_State *L) { lua_rawget(L, LUA_REGISTRYINDEX); if (!lua_istable(L, -1)) { lua_pop(L, 1); - lua_newtable(L); + lua_createtable(L, 0, 1); lua_pushlightuserdata(L, (void *)&KEY_HOOK); lua_pushvalue(L, -2); lua_rawset(L, LUA_REGISTRYINDEX); diff --git a/src/ldebug.c b/src/ldebug.c index 5fb11ce1..8919a017 100644 --- a/src/ldebug.c +++ b/src/ldebug.c @@ -1,5 +1,5 @@ /* -** $Id: ldebug.c,v 2.28 2005/11/01 16:08:52 roberto Exp $ +** $Id: ldebug.c,v 2.29 2005/12/22 16:19:56 roberto Exp $ ** Debug Interface ** See Copyright Notice in lua.h */ @@ -61,7 +61,7 @@ LUA_API int lua_sethook (lua_State *L, lua_Hook func, int mask, int count) { L->hook = func; L->basehookcount = count; resethookcount(L); - L->hookmask = cast(lu_byte, mask); + L->hookmask = cast_byte(mask); return 1; } @@ -92,7 +92,7 @@ LUA_API int lua_getstack (lua_State *L, int level, lua_Debug *ar) { } if (level == 0 && ci > L->base_ci) { /* level found? */ status = 1; - ar->i_ci = cast(int, ci - L->base_ci); + ar->i_ci = cast_int(ci - L->base_ci); } else if (level < 0) { /* level is of a lost tail call? */ status = 1; @@ -550,7 +550,7 @@ void luaG_typeerror (lua_State *L, const TValue *o, const char *op) { const char *name = NULL; const char *t = luaT_typenames[ttype(o)]; const char *kind = (isinstack(L->ci, o)) ? - getobjname(L, L->ci, cast(int, o - L->base), &name) : + getobjname(L, L->ci, cast_int(o - L->base), &name) : NULL; if (kind) luaG_runerror(L, "attempt to %s %s " LUA_QS " (a %s value)", @@ -1,5 +1,5 @@ /* -** $Id: ldo.c,v 2.36 2005/10/23 17:52:42 roberto Exp $ +** $Id: ldo.c,v 2.37 2005/12/22 16:19:56 roberto Exp $ ** Stack and Call structure of Lua ** See Copyright Notice in lua.h */ @@ -71,7 +71,7 @@ void luaD_seterrorobj (lua_State *L, int errcode, StkId oldtop) { static void restore_stack_limit (lua_State *L) { lua_assert(L->stack_last - L->stack == L->stacksize - EXTRA_STACK - 1); if (L->size_ci > LUAI_MAXCALLS) { /* there was an overflow? */ - int inuse = cast(int, L->ci - L->base_ci); + int inuse = cast_int(L->ci - L->base_ci); if (inuse + 1 < LUAI_MAXCALLS) /* can `undo' overflow? */ luaD_reallocCI(L, LUAI_MAXCALLS); } @@ -97,7 +97,7 @@ void luaD_throw (lua_State *L, int errcode) { LUAI_THROW(L, L->errorJmp); } else { - L->status = cast(lu_byte, errcode); + L->status = cast_byte(errcode); if (G(L)->panic) { resetstack(L, errcode); lua_unlock(L); @@ -189,7 +189,7 @@ void luaD_callhook (lua_State *L, int event, int line) { if (event == LUA_HOOKTAILRET) ar.i_ci = 0; /* tail call; no debug information about it */ else - ar.i_ci = cast(int, L->ci - L->base_ci); + ar.i_ci = cast_int(L->ci - L->base_ci); luaD_checkstack(L, LUA_MINSTACK); /* ensure minimum stack size */ L->ci->top = L->top + LUA_MINSTACK; lua_assert(L->ci->top <= L->stack_last); @@ -221,8 +221,7 @@ static StkId adjust_varargs (lua_State *L, Proto *p, int actual) { for (i=0; i<nvar; i++) /* put extra arguments into `arg' table */ setobj2n(L, luaH_setnum(L, htab, i+1), L->top - nvar + i); /* store counter in field `n' */ - setnvalue(luaH_setstr(L, htab, luaS_newliteral(L, "n")), - cast(lua_Number, nvar)); + setnvalue(luaH_setstr(L, htab, luaS_newliteral(L, "n")), cast_num(nvar)); } #endif /* move fixed parameters to final position */ @@ -282,7 +281,7 @@ int luaD_precall (lua_State *L, StkId func, int nresults) { L->top = base + p->numparams; } else { /* vararg function */ - int nargs = cast(int, L->top - func) - 1; + int nargs = cast_int(L->top - func) - 1; base = adjust_varargs(L, p, nargs); func = restorestack(L, funcr); /* previous call may change the stack */ } @@ -401,7 +400,7 @@ static void resume (lua_State *L, void *ud) { L->base = L->ci->base; } L->status = 0; - luaV_execute(L, cast(int, L->ci - L->base_ci)); + luaV_execute(L, cast_int(L->ci - L->base_ci)); } @@ -427,7 +426,7 @@ LUA_API int lua_resume (lua_State *L, int nargs) { lua_assert(L->errfunc == 0 && L->nCcalls == 0); status = luaD_rawrunprotected(L, resume, L->top - nargs); if (status != 0) { /* error? */ - L->status = cast(lu_byte, status); /* mark thread as `dead' */ + L->status = cast_byte(status); /* mark thread as `dead' */ luaD_seterrorobj(L, status, L->top); L->ci->top = L->top; } diff --git a/src/lfunc.c b/src/lfunc.c index c9286d91..b8cd67b2 100644 --- a/src/lfunc.c +++ b/src/lfunc.c @@ -1,5 +1,5 @@ /* -** $Id: lfunc.c,v 2.11 2005/05/05 20:47:02 roberto Exp $ +** $Id: lfunc.c,v 2.12 2005/12/22 16:19:56 roberto Exp $ ** Auxiliary functions to manipulate prototypes and closures ** See Copyright Notice in lua.h */ @@ -25,7 +25,7 @@ Closure *luaF_newCclosure (lua_State *L, int nelems, Table *e) { luaC_link(L, obj2gco(c), LUA_TFUNCTION); c->c.isC = 1; c->c.env = e; - c->c.nupvalues = cast(lu_byte, nelems); + c->c.nupvalues = cast_byte(nelems); return c; } @@ -35,7 +35,7 @@ Closure *luaF_newLclosure (lua_State *L, int nelems, Table *e) { luaC_link(L, obj2gco(c), LUA_TFUNCTION); c->l.isC = 0; c->l.env = e; - c->l.nupvalues = cast(lu_byte, nelems); + c->l.nupvalues = cast_byte(nelems); while (nelems--) c->l.upvals[nelems] = NULL; return c; } @@ -1,5 +1,5 @@ /* -** $Id: lgc.c,v 2.36 2005/08/24 17:06:36 roberto Exp $ +** $Id: lgc.c,v 2.37 2005/12/22 16:19:56 roberto Exp $ ** Garbage Collector ** See Copyright Notice in lua.h */ @@ -29,11 +29,10 @@ #define GCFINALIZECOST 100 -#define maskmarks \ - cast(lu_byte, ~(bitmask(BLACKBIT)|WHITEBITS)) +#define maskmarks cast_byte(~(bitmask(BLACKBIT)|WHITEBITS)) #define makewhite(g,x) \ - ((x)->gch.marked = ((x)->gch.marked & maskmarks) | luaC_white(g)) + ((x)->gch.marked = cast_byte(((x)->gch.marked & maskmarks) | luaC_white(g))) #define white2gray(x) reset2bits((x)->gch.marked, WHITE0BIT, WHITE1BIT) #define black2gray(x) resetbit((x)->gch.marked, BLACKBIT) @@ -169,8 +168,8 @@ static int traversetable (global_State *g, Table *h) { weakvalue = (strchr(svalue(mode), 'v') != NULL); if (weakkey || weakvalue) { /* is really weak? */ h->marked &= ~(KEYWEAK | VALUEWEAK); /* clear bits */ - h->marked |= cast(lu_byte, (weakkey << KEYWEAKBIT) | - (weakvalue << VALUEWEAKBIT)); + h->marked |= cast_byte((weakkey << KEYWEAKBIT) | + (weakvalue << VALUEWEAKBIT)); h->gclist = g->weak; /* must be cleared after GC, ... */ g->weak = obj2gco(h); /* ... so put in the appropriate list */ } @@ -240,8 +239,8 @@ static void traverseclosure (global_State *g, Closure *cl) { static void checkstacksizes (lua_State *L, StkId max) { - int ci_used = cast(int, L->ci - L->base_ci); /* number of `ci' in use */ - int s_used = cast(int, max - L->stack); /* part of stack in use */ + int ci_used = cast_int(L->ci - L->base_ci); /* number of `ci' in use */ + int s_used = cast_int(max - L->stack); /* part of stack in use */ if (L->size_ci > LUAI_MAXCALLS) /* handling overflow? */ return; /* do not touch the stacks */ if (4*ci_used < L->size_ci && 2*BASIC_CI_SIZE < L->size_ci) @@ -544,7 +543,7 @@ static void atomic (lua_State *L) { propagateall(g); /* remark, to propagate `preserveness' */ cleartable(g->weak); /* remove collected objects from weak tables */ /* flip current white */ - g->currentwhite = cast(lu_byte, otherwhite(g)); + g->currentwhite = cast_byte(otherwhite(g)); g->sweepstrgc = 0; g->sweepgc = &g->rootgc; g->gcstate = GCSsweepstring; diff --git a/src/linit.c b/src/linit.c index d30ff1e3..483d9c8c 100644 --- a/src/linit.c +++ b/src/linit.c @@ -1,5 +1,5 @@ /* -** $Id: linit.c,v 1.13 2005/08/26 17:36:32 roberto Exp $ +** $Id: linit.c,v 1.14 2005/12/29 15:32:11 roberto Exp $ ** Initialization of libraries for lua.c ** See Copyright Notice in lua.h */ @@ -16,13 +16,13 @@ static const luaL_Reg lualibs[] = { {"", luaopen_base}, + {LUA_LOADLIBNAME, luaopen_package}, {LUA_TABLIBNAME, luaopen_table}, {LUA_IOLIBNAME, luaopen_io}, {LUA_OSLIBNAME, luaopen_os}, {LUA_STRLIBNAME, luaopen_string}, {LUA_MATHLIBNAME, luaopen_math}, {LUA_DBLIBNAME, luaopen_debug}, - {LUA_LOADLIBNAME, luaopen_package}, {NULL, NULL} }; diff --git a/src/liolib.c b/src/liolib.c index cc493aff..f0a7602a 100644 --- a/src/liolib.c +++ b/src/liolib.c @@ -1,5 +1,5 @@ /* -** $Id: liolib.c,v 2.69 2005/10/19 13:05:11 roberto Exp $ +** $Id: liolib.c,v 2.70 2005/12/29 15:32:11 roberto Exp $ ** Standard I/O (and system) library ** See Copyright Notice in lua.h */ @@ -507,8 +507,8 @@ static void createstdfile (lua_State *L, FILE *f, int k, const char *fname) { LUALIB_API int luaopen_io (lua_State *L) { createmeta(L); - /* create new (private) environment */ - lua_newtable(L); + /* create (private) environment (with fields IO_INPUT, IO_OUTPUT, __close) */ + lua_createtable(L, 2, 1); lua_replace(L, LUA_ENVIRONINDEX); /* open library */ luaL_register(L, LUA_IOLIBNAME, iolib); @@ -518,7 +518,7 @@ LUALIB_API int luaopen_io (lua_State *L) { createstdfile(L, stderr, 0, "stderr"); /* create environment for 'popen' */ lua_getfield(L, -1, "popen"); - lua_newtable(L); + lua_createtable(L, 0, 1); lua_pushcfunction(L, io_pclose); lua_setfield(L, -2, "__close"); lua_setfenv(L, -2); @@ -1,11 +1,12 @@ /* -** $Id: llex.c,v 2.13 2005/11/08 19:45:14 roberto Exp $ +** $Id: llex.c,v 2.17 2005/12/22 16:19:56 roberto Exp $ ** Lexical Analyzer ** See Copyright Notice in lua.h */ #include <ctype.h> +#include <locale.h> #include <string.h> #define llex_c @@ -65,7 +66,7 @@ void luaX_init (lua_State *L) { TString *ts = luaS_new(L, luaX_tokens[i]); luaS_fix(ts); /* reserved words are never collected */ lua_assert(strlen(luaX_tokens[i])+1 <= TOKEN_LEN); - ts->tsv.reserved = cast(lu_byte, i+1); /* reserved word */ + ts->tsv.reserved = cast_byte(i+1); /* reserved word */ } } @@ -134,6 +135,7 @@ static void inclinenumber (LexState *ls) { void luaX_setinput (lua_State *L, LexState *ls, ZIO *z, TString *source) { + ls->decpoint = '.'; ls->L = L; ls->lookahead.token = TK_EOS; /* no look-ahead token */ ls->z = z; @@ -163,6 +165,27 @@ static int check_next (LexState *ls, const char *set) { } +static void buffreplace (LexState *ls, char from, char to) { + int n = luaZ_bufflen(ls->buff); + char *p = luaZ_buffer(ls->buff); + while (n--) + if (p[n] == from) p[n] = to; +} + + +static void trydecpoint (LexState *ls, SemInfo *seminfo) { + /* format error: try to update decimal point separator */ + struct lconv *cv = localeconv(); + char old = ls->decpoint; + ls->decpoint = (cv ? cv->decimal_point[0] : '.'); + buffreplace(ls, old, ls->decpoint); /* try updated decimal separator */ + if (!luaO_str2d(luaZ_buffer(ls->buff), &seminfo->r)) { + /* format error with correct decimal point: no more options */ + buffreplace(ls, ls->decpoint, '.'); /* undo change (for error message) */ + luaX_lexerror(ls, "malformed number", TK_NUMBER); + } +} + /* LUA_NUMBER */ static void read_numeral (LexState *ls, SemInfo *seminfo) { @@ -177,8 +200,9 @@ static void read_numeral (LexState *ls, SemInfo *seminfo) { } } save(ls, '\0'); - if (!luaO_str2d(luaZ_buffer(ls->buff), &seminfo->r)) - luaX_lexerror(ls, "malformed number", TK_NUMBER); + buffreplace(ls, '.', ls->decpoint); /* follow locale for decimal point */ + if (!luaO_str2d(luaZ_buffer(ls->buff), &seminfo->r)) /* format error? */ + trydecpoint(ls, seminfo); /* try to update decimal point separator */ } @@ -306,7 +330,7 @@ static void read_string (LexState *ls, int del, SemInfo *seminfo) { } -int luaX_lex (LexState *ls, SemInfo *seminfo) { +static int llex (LexState *ls, SemInfo *seminfo) { luaZ_resetbuffer(ls->buff); for (;;) { switch (ls->current) { @@ -419,4 +443,20 @@ int luaX_lex (LexState *ls, SemInfo *seminfo) { } } -#undef next + +void luaX_next (LexState *ls) { + ls->lastline = ls->linenumber; + if (ls->lookahead.token != TK_EOS) { /* is there a look-ahead token? */ + ls->t = ls->lookahead; /* use this one */ + ls->lookahead.token = TK_EOS; /* and discharge it */ + } + else + ls->t.token = llex(ls, &ls->t.seminfo); /* read next token */ +} + + +void luaX_lookahead (LexState *ls) { + lua_assert(ls->lookahead.token == TK_EOS); + ls->lookahead.token = llex(ls, &ls->lookahead.seminfo); +} + @@ -1,5 +1,5 @@ /* -** $Id: llex.h,v 1.55 2005/06/06 13:30:25 roberto Exp $ +** $Id: llex.h,v 1.57 2005/12/07 15:43:05 roberto Exp $ ** Lexical Analyzer ** See Copyright Notice in lua.h */ @@ -63,6 +63,7 @@ typedef struct LexState { ZIO *z; /* input stream */ Mbuffer *buff; /* buffer for tokens */ TString *source; /* current source name */ + char decpoint; /* locale decimal point */ } LexState; @@ -70,7 +71,8 @@ LUAI_FUNC void luaX_init (lua_State *L); LUAI_FUNC void luaX_setinput (lua_State *L, LexState *LS, ZIO *z, TString *source); LUAI_FUNC TString *luaX_newstring (LexState *LS, const char *str, size_t l); -LUAI_FUNC int luaX_lex (LexState *LS, SemInfo *seminfo); +LUAI_FUNC void luaX_next (LexState *ls); +LUAI_FUNC void luaX_lookahead (LexState *ls); LUAI_FUNC void luaX_lexerror (LexState *ls, const char *msg, int token); LUAI_FUNC void luaX_syntaxerror (LexState *ls, const char *s); LUAI_FUNC const char *luaX_token2str (LexState *ls, int token); diff --git a/src/llimits.h b/src/llimits.h index 68c28c8c..b03221ae 100644 --- a/src/llimits.h +++ b/src/llimits.h @@ -1,5 +1,5 @@ /* -** $Id: llimits.h,v 1.67 2005/08/24 16:15:49 roberto Exp $ +** $Id: llimits.h,v 1.69 2005/12/27 17:12:00 roberto Exp $ ** Limits, basic types, and some other `installation-dependent' definitions ** See Copyright Notice in lua.h */ @@ -15,9 +15,6 @@ #include "lua.h" -#define api_check luai_apicheck - - typedef LUAI_UINT32 lu_int32; typedef LUAI_UMEM lu_mem; @@ -54,7 +51,19 @@ typedef LUAI_USER_ALIGNMENT_T L_Umaxalign; typedef LUAI_UACNUMBER l_uacNumber; -#define check_exp(c,e) (lua_assert(c), (e)) +/* internal assertions for in-house debugging */ +#ifdef lua_assert + +#define check_exp(c,e) (lua_assert(c), (e)) +#define api_check(l,e) lua_assert(e) + +#else + +#define lua_assert(c) ((void)0) +#define check_exp(c,e) (e) +#define api_check luai_apicheck + +#endif #ifndef UNUSED @@ -66,6 +75,10 @@ typedef LUAI_UACNUMBER l_uacNumber; #define cast(t, exp) ((t)(exp)) #endif +#define cast_byte(i) cast(lu_byte, (i)) +#define cast_num(i) cast(lua_Number, (i)) +#define cast_int(i) cast(int, (i)) + /* @@ -1,5 +1,5 @@ /* -** $Id: lmem.c,v 1.69 2005/02/23 17:30:22 roberto Exp $ +** $Id: lmem.c,v 1.70 2005/12/26 13:35:47 roberto Exp $ ** Interface to Memory Manager ** See Copyright Notice in lua.h */ @@ -81,22 +81,6 @@ void *luaM_realloc_ (lua_State *L, void *block, size_t osize, size_t nsize) { luaD_throw(L, LUA_ERRMEM); lua_assert((nsize == 0) == (block == NULL)); g->totalbytes = (g->totalbytes - osize) + nsize; -#if 0 - { /* auxiliar patch to monitor garbage collection */ - static unsigned long total = 0; /* our "time" */ - static lu_mem last = 0; /* last totalmem that generated an output */ - static FILE *f = NULL; /* output file */ - if (nsize <= osize) total += 1; /* "time" always grow */ - else total += (nsize - osize); - if ((int)g->totalbytes - (int)last > 1000 || - (int)g->totalbytes - (int)last < -1000) { - last = g->totalbytes; - if (f == NULL) f = fopen("trace", "w"); - fprintf(f, "%lu %u %u %u %d\n", total, g->totalbytes, g->GCthreshold, - g->estimate, g->gcstate); - } - } -#endif return block; } diff --git a/src/loadlib.c b/src/loadlib.c index 9f992086..19edaca0 100644 --- a/src/loadlib.c +++ b/src/loadlib.c @@ -1,5 +1,5 @@ /* -** $Id: loadlib.c,v 1.48 2005/10/17 18:01:51 roberto Exp $ +** $Id: loadlib.c,v 1.51 2005/12/29 15:32:11 roberto Exp $ ** Dynamic library loader for Lua ** See Copyright Notice in lua.h ** @@ -16,8 +16,9 @@ #define loadlib_c #define LUA_LIB -#include "lua.h" #include "lauxlib.h" +#include "lobject.h" +#include "lua.h" #include "lualib.h" @@ -236,11 +237,8 @@ static lua_CFunction ll_sym (lua_State *L, void *lib, const char *sym) { #define LIB_FAIL "absent" -#if defined(__ELF__) || defined(__sun) || defined(sgi) || defined(__hpux) -#define DLMSG LUA_QL("loadlib") " not enabled; check your Lua installation" -#else -#define DLMSG LUA_QL("loadlib") " not supported" -#endif +#define DLMSG "dynamic libraries not enabled; check your Lua installation" + static void ll_unloadlib (void *lib) { (void)lib; /* to avoid warnings */ @@ -362,20 +360,23 @@ static const char *findfile (lua_State *L, const char *name, path = lua_tostring(L, -1); if (path == NULL) luaL_error(L, LUA_QL("package.%s") " must be a string", pname); + lua_pushstring(L, ""); /* error accumulator */ while ((path = pushnexttemplate(L, path)) != NULL) { const char *filename; filename = luaL_gsub(L, lua_tostring(L, -1), LUA_PATH_MARK, name); if (readable(filename)) /* does file exist and is readable? */ return filename; /* return that file name */ lua_pop(L, 2); /* remove path template and file name */ + luaO_pushfstring(L, "\n\tno file " LUA_QS, filename); + lua_concat(L, 2); } return NULL; /* not found */ } -static void loaderror (lua_State *L) { - luaL_error(L, "error loading module " LUA_QS " (%s)", - lua_tostring(L, 1), lua_tostring(L, -1)); +static void loaderror (lua_State *L, const char *filename) { + luaL_error(L, "error loading module " LUA_QS " from file " LUA_QS ":\n\t%s", + lua_tostring(L, 1), filename, lua_tostring(L, -1)); } @@ -383,9 +384,9 @@ static int loader_Lua (lua_State *L) { const char *filename; const char *name = luaL_checkstring(L, 1); filename = findfile(L, name, "path"); - if (filename == NULL) return 0; /* library not found in this path */ + if (filename == NULL) return 1; /* library not found in this path */ if (luaL_loadfile(L, filename) != 0) - loaderror(L); + loaderror(L, filename); return 1; /* library loaded successfully */ } @@ -405,10 +406,10 @@ static int loader_C (lua_State *L) { const char *funcname; const char *name = luaL_checkstring(L, 1); const char *filename = findfile(L, name, "cpath"); - if (filename == NULL) return 0; /* library not found in this path */ + if (filename == NULL) return 1; /* library not found in this path */ funcname = mkfuncname(L, name); if (ll_loadfunc(L, filename, funcname) != 0) - loaderror(L); + loaderror(L, filename); return 1; /* library loaded successfully */ } @@ -422,22 +423,26 @@ static int loader_Croot (lua_State *L) { if (p == NULL) return 0; /* is root */ lua_pushlstring(L, name, p - name); filename = findfile(L, lua_tostring(L, -1), "cpath"); - if (filename == NULL) return 0; /* root not found */ + if (filename == NULL) return 1; /* root not found */ funcname = mkfuncname(L, name); if ((stat = ll_loadfunc(L, filename, funcname)) != 0) { - if (stat == ERRFUNC) return 0; /* function not found */ - else - loaderror(L); /* real error */ + if (stat != ERRFUNC) loaderror(L, filename); /* real error */ + luaO_pushfstring(L, "\n\tno module " LUA_QS " in file " LUA_QS, + name, filename); + return 1; /* function not found */ } return 1; } static int loader_preload (lua_State *L) { + const char *name = luaL_checkstring(L, 1); lua_getfield(L, LUA_ENVIRONINDEX, "preload"); if (!lua_istable(L, -1)) luaL_error(L, LUA_QL("package.preload") " must be a table"); - lua_getfield(L, -1, luaL_checkstring(L, 1)); + lua_getfield(L, -1, name); + if (lua_isnil(L, -1)) /* not found? */ + luaO_pushfstring(L, "\n\tno field package.preload['%s']", name); return 1; } @@ -461,14 +466,20 @@ static int ll_require (lua_State *L) { lua_getfield(L, LUA_ENVIRONINDEX, "loaders"); if (!lua_istable(L, -1)) luaL_error(L, LUA_QL("package.loaders") " must be a table"); + lua_pushstring(L, ""); /* error message accumulator */ for (i=1; ; i++) { - lua_rawgeti(L, -1, i); /* get a loader */ + lua_rawgeti(L, -2, i); /* get a loader */ if (lua_isnil(L, -1)) - luaL_error(L, "module " LUA_QS " not found", name); + luaL_error(L, "module " LUA_QS " not found:%s", + name, lua_tostring(L, -2)); lua_pushstring(L, name); lua_call(L, 1, 1); /* call it */ - if (lua_isnil(L, -1)) lua_pop(L, 1); /* did not found module */ - else break; /* module loaded successfully */ + if (lua_isfunction(L, -1)) /* did it find module? */ + break; /* module loaded successfully */ + else if (lua_isstring(L, -1)) /* loader returned error message? */ + lua_concat(L, 2); /* accumulate it */ + else + lua_pop(L, 1); } lua_pushlightuserdata(L, sentinel); lua_setfield(L, 2, name); /* _LOADED[name] = sentinel */ @@ -539,7 +550,7 @@ static int ll_module (lua_State *L) { if (!lua_istable(L, -1)) { /* not found? */ lua_pop(L, 1); /* remove previous result */ /* try global variable (and create one if it does not exist) */ - if (luaL_findtable(L, LUA_GLOBALSINDEX, modname) != NULL) + if (luaL_findtable(L, LUA_GLOBALSINDEX, modname, 1) != NULL) return luaL_error(L, "name conflict for module " LUA_QS, modname); lua_pushvalue(L, -1); lua_setfield(L, loaded, modname); /* _LOADED[modname] = new table */ @@ -562,7 +573,7 @@ static int ll_module (lua_State *L) { static int ll_seeall (lua_State *L) { luaL_checktype(L, 1, LUA_TTABLE); if (!lua_getmetatable(L, 1)) { - lua_newtable(L); /* create new metatable */ + lua_createtable(L, 0, 1); /* create new metatable */ lua_pushvalue(L, -1); lua_setmetatable(L, 1); } @@ -629,7 +640,7 @@ LUALIB_API int luaopen_package (lua_State *L) { lua_pushvalue(L, -1); lua_replace(L, LUA_ENVIRONINDEX); /* create `loaders' table */ - lua_newtable(L); + lua_createtable(L, 0, sizeof(loaders)/sizeof(loaders[0]) - 1); /* fill it with pre-defined loaders */ for (i=0; loaders[i] != NULL; i++) { lua_pushcfunction(L, loaders[i]); @@ -643,7 +654,7 @@ LUALIB_API int luaopen_package (lua_State *L) { LUA_EXECDIR "\n" LUA_IGMARK); lua_setfield(L, -2, "config"); /* set field `loaded' */ - luaL_findtable(L, LUA_REGISTRYINDEX, "_LOADED"); + luaL_findtable(L, LUA_REGISTRYINDEX, "_LOADED", 2); lua_setfield(L, -2, "loaded"); /* set field `preload' */ lua_newtable(L); diff --git a/src/lobject.c b/src/lobject.c index 3974c683..e83b5240 100644 --- a/src/lobject.c +++ b/src/lobject.c @@ -1,5 +1,5 @@ /* -** $Id: lobject.c,v 2.19 2005/10/24 17:37:52 roberto Exp $ +** $Id: lobject.c,v 2.21 2006/01/10 12:50:00 roberto Exp $ ** Some generic functions over Lua objects ** See Copyright Notice in lua.h */ @@ -24,7 +24,7 @@ -const TValue luaO_nilobject = {{NULL}, LUA_TNIL}; +const TValue luaO_nilobject_ = {{NULL}, LUA_TNIL}; /* @@ -39,7 +39,7 @@ int luaO_int2fb (unsigned int x) { e++; } if (x < 8) return x; - else return ((e+1) << 3) | (cast(int, x) - 8); + else return ((e+1) << 3) | (cast_int(x) - 8); } @@ -129,12 +129,12 @@ const char *luaO_pushvfstring (lua_State *L, const char *fmt, va_list argp) { break; } case 'd': { - setnvalue(L->top, cast(lua_Number, va_arg(argp, int))); + setnvalue(L->top, cast_num(va_arg(argp, int))); incr_top(L); break; } case 'f': { - setnvalue(L->top, cast(lua_Number, va_arg(argp, l_uacNumber))); + setnvalue(L->top, cast_num(va_arg(argp, l_uacNumber))); incr_top(L); break; } @@ -161,7 +161,7 @@ const char *luaO_pushvfstring (lua_State *L, const char *fmt, va_list argp) { fmt = e+2; } pushstr(L, fmt); - luaV_concat(L, n+1, cast(int, L->top - L->base) - 1); + luaV_concat(L, n+1, cast_int(L->top - L->base) - 1); L->top -= n; return svalue(L->top - 1); } diff --git a/src/lobject.h b/src/lobject.h index 1416e360..928bedc7 100644 --- a/src/lobject.h +++ b/src/lobject.h @@ -1,5 +1,5 @@ /* -** $Id: lobject.h,v 2.18 2005/10/24 17:37:33 roberto Exp $ +** $Id: lobject.h,v 2.19 2006/01/10 12:51:53 roberto Exp $ ** Type definitions for Lua objects ** See Copyright Notice in lua.h */ @@ -323,9 +323,12 @@ typedef union Closure { ** Tables */ -typedef struct TKey { - TValuefields; - struct Node *next; /* for chaining */ +typedef union TKey { + struct { + TValuefields; + struct Node *next; /* for chaining */ + } nk; + TValue tvk; } TKey; @@ -360,8 +363,9 @@ typedef struct Table { #define sizenode(t) (twoto((t)->lsizenode)) +#define luaO_nilobject (&luaO_nilobject_) -LUAI_DATA const TValue luaO_nilobject; +LUAI_DATA const TValue luaO_nilobject_; #define ceillog2(x) (luaO_log2((x)-1) + 1) diff --git a/src/lopcodes.h b/src/lopcodes.h index 88e7e65c..2834b1d7 100644 --- a/src/lopcodes.h +++ b/src/lopcodes.h @@ -1,5 +1,5 @@ /* -** $Id: lopcodes.h,v 1.123 2005/10/23 17:37:55 roberto Exp $ +** $Id: lopcodes.h,v 1.124 2005/12/02 18:42:08 roberto Exp $ ** Opcodes for Lua virtual machine ** See Copyright Notice in lua.h */ @@ -208,7 +208,7 @@ OP_VARARG/* A B R(A), R(A+1), ..., R(A+B-1) = vararg */ } OpCode; -#define NUM_OPCODES (cast(int, OP_VARARG+1)) +#define NUM_OPCODES (cast(int, OP_VARARG) + 1) diff --git a/src/loslib.c b/src/loslib.c index 01458b90..235377e4 100644 --- a/src/loslib.c +++ b/src/loslib.c @@ -1,5 +1,5 @@ /* -** $Id: loslib.c,v 1.14 2005/10/21 13:47:42 roberto Exp $ +** $Id: loslib.c,v 1.16 2005/12/22 16:19:56 roberto Exp $ ** Standard Operating System library ** See Copyright Notice in lua.h */ @@ -37,26 +37,26 @@ static int os_pushresult (lua_State *L, int i, const char *filename) { } -static int io_execute (lua_State *L) { +static int os_execute (lua_State *L) { lua_pushinteger(L, system(luaL_optstring(L, 1, NULL))); return 1; } -static int io_remove (lua_State *L) { +static int os_remove (lua_State *L) { const char *filename = luaL_checkstring(L, 1); return os_pushresult(L, remove(filename) == 0, filename); } -static int io_rename (lua_State *L) { +static int os_rename (lua_State *L) { const char *fromname = luaL_checkstring(L, 1); const char *toname = luaL_checkstring(L, 2); return os_pushresult(L, rename(fromname, toname) == 0, fromname); } -static int io_tmpname (lua_State *L) { +static int os_tmpname (lua_State *L) { char buff[LUA_TMPNAMBUFSIZE]; int err; lua_tmpnam(buff, err); @@ -67,13 +67,13 @@ static int io_tmpname (lua_State *L) { } -static int io_getenv (lua_State *L) { +static int os_getenv (lua_State *L) { lua_pushstring(L, getenv(luaL_checkstring(L, 1))); /* if NULL push nil */ return 1; } -static int io_clock (lua_State *L) { +static int os_clock (lua_State *L) { lua_pushnumber(L, ((lua_Number)clock())/(lua_Number)CLOCKS_PER_SEC); return 1; } @@ -123,7 +123,7 @@ static int getfield (lua_State *L, const char *key, int d) { } -static int io_date (lua_State *L) { +static int os_date (lua_State *L) { const char *s = luaL_optstring(L, 1, "%c"); time_t t = lua_isnoneornil(L, 2) ? time(NULL) : (time_t)luaL_checknumber(L, 2); @@ -159,7 +159,7 @@ static int io_date (lua_State *L) { } -static int io_time (lua_State *L) { +static int os_time (lua_State *L) { time_t t; if (lua_isnoneornil(L, 1)) /* called without args? */ t = time(NULL); /* get current time */ @@ -179,12 +179,12 @@ static int io_time (lua_State *L) { if (t == (time_t)(-1)) lua_pushnil(L); else - lua_pushnumber(L, t); + lua_pushnumber(L, (lua_Number)t); return 1; } -static int io_difftime (lua_State *L) { +static int os_difftime (lua_State *L) { lua_pushnumber(L, difftime((time_t)(luaL_checknumber(L, 1)), (time_t)(luaL_optnumber(L, 2, 0)))); return 1; @@ -193,7 +193,7 @@ static int io_difftime (lua_State *L) { /* }====================================================== */ -static int io_setloc (lua_State *L) { +static int os_setlocale (lua_State *L) { static const int cat[] = {LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME}; static const char *const catnames[] = {"all", "collate", "ctype", "monetary", @@ -206,23 +206,23 @@ static int io_setloc (lua_State *L) { } -static int io_exit (lua_State *L) { +static int os_exit (lua_State *L) { exit(luaL_optint(L, 1, EXIT_SUCCESS)); return 0; /* to avoid warnings */ } static const luaL_Reg syslib[] = { - {"clock", io_clock}, - {"date", io_date}, - {"difftime", io_difftime}, - {"execute", io_execute}, - {"exit", io_exit}, - {"getenv", io_getenv}, - {"remove", io_remove}, - {"rename", io_rename}, - {"setlocale", io_setloc}, - {"time", io_time}, - {"tmpname", io_tmpname}, + {"clock", os_clock}, + {"date", os_date}, + {"difftime", os_difftime}, + {"execute", os_execute}, + {"exit", os_exit}, + {"getenv", os_getenv}, + {"remove", os_remove}, + {"rename", os_rename}, + {"setlocale", os_setlocale}, + {"time", os_time}, + {"tmpname", os_tmpname}, {NULL, NULL} }; diff --git a/src/lparser.c b/src/lparser.c index dd4715d0..b40ee794 100644 --- a/src/lparser.c +++ b/src/lparser.c @@ -1,5 +1,5 @@ /* -** $Id: lparser.c,v 2.38 2005/10/24 17:38:47 roberto Exp $ +** $Id: lparser.c,v 2.40 2005/12/22 16:19:56 roberto Exp $ ** Lua Parser ** See Copyright Notice in lua.h */ @@ -54,24 +54,6 @@ static void chunk (LexState *ls); static void expr (LexState *ls, expdesc *v); - -static void next (LexState *ls) { - ls->lastline = ls->linenumber; - if (ls->lookahead.token != TK_EOS) { /* is there a look-ahead token? */ - ls->t = ls->lookahead; /* use this one */ - ls->lookahead.token = TK_EOS; /* and discharge it */ - } - else - ls->t.token = luaX_lex(ls, &ls->t.seminfo); /* read next token */ -} - - -static void lookahead (LexState *ls) { - lua_assert(ls->lookahead.token == TK_EOS); - ls->lookahead.token = luaX_lex(ls, &ls->lookahead.seminfo); -} - - static void anchor_token (LexState *ls) { if (ls->t.token == TK_NAME || ls->t.token == TK_STRING) { TString *ts = ls->t.seminfo.ts; @@ -97,7 +79,7 @@ static void errorlimit (FuncState *fs, int limit, const char *what) { static int testnext (LexState *ls, int c) { if (ls->t.token == c) { - next(ls); + luaX_next(ls); return 1; } else return 0; @@ -111,7 +93,7 @@ static void check (LexState *ls, int c) { static void checknext (LexState *ls, int c) { check(ls, c); - next(ls); + luaX_next(ls); } @@ -136,7 +118,7 @@ static TString *str_checkname (LexState *ls) { TString *ts; check(ls, TK_NAME); ts = ls->t.seminfo.ts; - next(ls); + luaX_next(ls); return ts; } @@ -184,7 +166,7 @@ static void new_localvar (LexState *ls, TString *name, int n) { static void adjustlocalvars (LexState *ls, int nvars) { FuncState *fs = ls->fs; - fs->nactvar = cast(lu_byte, fs->nactvar + nvars); + fs->nactvar = cast_byte(fs->nactvar + nvars); for (; nvars; nvars--) { getlocvar(fs, fs->nactvar - nvars).startpc = fs->pc; } @@ -216,8 +198,8 @@ static int indexupvalue (FuncState *fs, TString *name, expdesc *v) { f->upvalues[f->nups] = name; luaC_objbarrier(fs->L, f, name); lua_assert(v->k == VLOCAL || v->k == VUPVAL); - fs->upvalues[f->nups].k = cast(lu_byte, v->k); - fs->upvalues[f->nups].info = cast(lu_byte, v->u.s.info); + fs->upvalues[f->nups].k = cast_byte(v->k); + fs->upvalues[f->nups].info = cast_byte(v->u.s.info); return f->nups++; } @@ -404,7 +386,7 @@ Proto *luaY_parser (lua_State *L, ZIO *z, Mbuffer *buff, const char *name) { luaX_setinput(L, &lexstate, z, luaS_new(L, name)); open_func(&lexstate, &funcstate); funcstate.f->is_vararg = VARARG_ISVARARG; /* main func. is always vararg */ - next(&lexstate); /* read first token */ + luaX_next(&lexstate); /* read first token */ chunk(&lexstate); check(&lexstate, TK_EOS); close_func(&lexstate); @@ -426,7 +408,7 @@ static void field (LexState *ls, expdesc *v) { FuncState *fs = ls->fs; expdesc key; luaK_exp2anyreg(fs, v); - next(ls); /* skip the dot or colon */ + luaX_next(ls); /* skip the dot or colon */ checkname(ls, &key); luaK_indexed(fs, v, &key); } @@ -434,7 +416,7 @@ static void field (LexState *ls, expdesc *v) { static void yindex (LexState *ls, expdesc *v) { /* index -> '[' expr ']' */ - next(ls); /* skip the '[' */ + luaX_next(ls); /* skip the '[' */ expr(ls, v); luaK_exp2val(ls->fs, v); checknext(ls, ']'); @@ -530,7 +512,7 @@ static void constructor (LexState *ls, expdesc *t) { closelistfield(fs, &cc); switch(ls->t.token) { case TK_NAME: { /* may be listfields or recfields */ - lookahead(ls); + luaX_lookahead(ls); if (ls->lookahead.token != '=') /* expression? */ listfield(ls, &cc); else @@ -571,7 +553,7 @@ static void parlist (LexState *ls) { break; } case TK_DOTS: { /* param -> `...' */ - next(ls); + luaX_next(ls); #if defined(LUA_COMPAT_VARARG) /* use `arg' as default name */ new_localvarliteral(ls, "arg", nparams++); @@ -585,7 +567,7 @@ static void parlist (LexState *ls) { } while (!f->is_vararg && testnext(ls, ',')); } adjustlocalvars(ls, nparams); - f->numparams = fs->nactvar - (f->is_vararg & VARARG_HASARG); + f->numparams = cast_byte(fs->nactvar - (f->is_vararg & VARARG_HASARG)); luaK_reserveregs(fs, fs->nactvar); /* reserve register for parameters */ } @@ -632,7 +614,7 @@ static void funcargs (LexState *ls, expdesc *f) { case '(': { /* funcargs -> `(' [ explist1 ] `)' */ if (line != ls->lastline) luaX_syntaxerror(ls,"ambiguous syntax (function call x new statement)"); - next(ls); + luaX_next(ls); if (ls->t.token == ')') /* arg list is empty? */ args.k = VVOID; else { @@ -648,7 +630,7 @@ static void funcargs (LexState *ls, expdesc *f) { } case TK_STRING: { /* funcargs -> STRING */ codestring(ls, &args, ls->t.seminfo.ts); - next(ls); /* must use `seminfo' before `next' */ + luaX_next(ls); /* must use `seminfo' before `next' */ break; } default: { @@ -686,7 +668,7 @@ static void prefixexp (LexState *ls, expdesc *v) { switch (ls->t.token) { case '(': { int line = ls->linenumber; - next(ls); + luaX_next(ls); expr(ls, v); check_match(ls, ')', '(', line); luaK_dischargevars(ls->fs, v); @@ -724,7 +706,7 @@ static void primaryexp (LexState *ls, expdesc *v) { } case ':': { /* `:' NAME funcargs */ expdesc key; - next(ls); + luaX_next(ls); checkname(ls, &key); luaK_self(fs, v, &key); funcargs(ls, v); @@ -779,7 +761,7 @@ static void simpleexp (LexState *ls, expdesc *v) { return; } case TK_FUNCTION: { - next(ls); + luaX_next(ls); body(ls, v, 0, ls->linenumber); return; } @@ -788,7 +770,7 @@ static void simpleexp (LexState *ls, expdesc *v) { return; } } - next(ls); + luaX_next(ls); } @@ -848,7 +830,7 @@ static BinOpr subexpr (LexState *ls, expdesc *v, unsigned int limit) { enterlevel(ls); uop = getunopr(ls->t.token); if (uop != OPR_NOUNOPR) { - next(ls); + luaX_next(ls); subexpr(ls, v, UNARY_PRIORITY); luaK_prefix(ls->fs, uop, v); } @@ -858,7 +840,7 @@ static BinOpr subexpr (LexState *ls, expdesc *v, unsigned int limit) { while (op != OPR_NOBINOPR && priority[op].left > limit) { expdesc v2; BinOpr nextop; - next(ls); + luaX_next(ls); luaK_infix(ls->fs, op, v); /* read sub-expression with higher priority */ nextop = subexpr(ls, &v2, priority[op].right); @@ -1009,7 +991,7 @@ static void whilestat (LexState *ls, int line) { int whileinit; int condexit; BlockCnt bl; - next(ls); /* skip WHILE */ + luaX_next(ls); /* skip WHILE */ whileinit = luaK_getlabel(fs); condexit = cond(ls); enterblock(fs, &bl, 1); @@ -1030,7 +1012,7 @@ static void repeatstat (LexState *ls, int line) { BlockCnt bl1, bl2; enterblock(fs, &bl1, 1); /* loop block */ enterblock(fs, &bl2, 0); /* scope block */ - next(ls); /* skip REPEAT */ + luaX_next(ls); /* skip REPEAT */ chunk(ls); check_match(ls, TK_UNTIL, TK_REPEAT, line); condexit = cond(ls); /* read condition (inside scope block) */ @@ -1130,7 +1112,7 @@ static void forstat (LexState *ls, int line) { TString *varname; BlockCnt bl; enterblock(fs, &bl, 1); /* scope for loop and control variables */ - next(ls); /* skip `for' */ + luaX_next(ls); /* skip `for' */ varname = str_checkname(ls); /* first variable name */ switch (ls->t.token) { case '=': fornum(ls, varname, line); break; @@ -1145,7 +1127,7 @@ static void forstat (LexState *ls, int line) { static int test_then_block (LexState *ls) { /* test_then_block -> [IF | ELSEIF] cond THEN block */ int condexit; - next(ls); /* skip IF or ELSEIF */ + luaX_next(ls); /* skip IF or ELSEIF */ condexit = cond(ls); checknext(ls, TK_THEN); block(ls); /* `then' part */ @@ -1167,7 +1149,7 @@ static void ifstat (LexState *ls, int line) { if (ls->t.token == TK_ELSE) { luaK_concat(fs, &escapelist, luaK_jump(fs)); luaK_patchtohere(fs, flist); - next(ls); /* skip ELSE (after patch, for correct line info) */ + luaX_next(ls); /* skip ELSE (after patch, for correct line info) */ block(ls); /* `else' part */ } else @@ -1228,7 +1210,7 @@ static void funcstat (LexState *ls, int line) { /* funcstat -> FUNCTION funcname body */ int needself; expdesc v, b; - next(ls); /* skip FUNCTION */ + luaX_next(ls); /* skip FUNCTION */ needself = funcname(ls, &v); body(ls, &b, needself, line); luaK_storevar(ls->fs, &v, &b); @@ -1255,7 +1237,7 @@ static void retstat (LexState *ls) { FuncState *fs = ls->fs; expdesc e; int first, nret; /* registers with returned values */ - next(ls); /* skip RETURN */ + luaX_next(ls); /* skip RETURN */ if (block_follow(ls->t.token) || ls->t.token == ';') first = nret = 0; /* return no values */ else { @@ -1295,7 +1277,7 @@ static int statement (LexState *ls) { return 0; } case TK_DO: { /* stat -> DO block END */ - next(ls); /* skip DO */ + luaX_next(ls); /* skip DO */ block(ls); check_match(ls, TK_END, TK_DO, line); return 0; @@ -1313,7 +1295,7 @@ static int statement (LexState *ls) { return 0; } case TK_LOCAL: { /* stat -> localstat */ - next(ls); /* skip LOCAL */ + luaX_next(ls); /* skip LOCAL */ if (testnext(ls, TK_FUNCTION)) /* local function? */ localfunc(ls); else @@ -1325,7 +1307,7 @@ static int statement (LexState *ls) { return 1; /* must be last statement */ } case TK_BREAK: { /* stat -> breakstat */ - next(ls); /* skip BREAK */ + luaX_next(ls); /* skip BREAK */ breakstat(ls); return 1; /* must be last statement */ } diff --git a/src/lstring.c b/src/lstring.c index 897089a4..4319930c 100644 --- a/src/lstring.c +++ b/src/lstring.c @@ -1,5 +1,5 @@ /* -** $Id: lstring.c,v 2.7 2005/02/18 12:40:02 roberto Exp $ +** $Id: lstring.c,v 2.8 2005/12/22 16:19:56 roberto Exp $ ** String table (keeps all strings handled by Lua) ** See Copyright Notice in lua.h */ @@ -35,7 +35,7 @@ void luaS_resize (lua_State *L, int newsize) { GCObject *next = p->gch.next; /* save next */ unsigned int h = gco2ts(p)->hash; int h1 = lmod(h, newsize); /* new position */ - lua_assert(cast(int, h%newsize) == lmod(h, newsize)); + lua_assert(cast_int(h%newsize) == lmod(h, newsize)); p->gch.next = newhash[h1]; /* chain it */ newhash[h1] = p; p = next; diff --git a/src/lstrlib.c b/src/lstrlib.c index 25258bfe..84478fd1 100644 --- a/src/lstrlib.c +++ b/src/lstrlib.c @@ -1,5 +1,5 @@ /* -** $Id: lstrlib.c,v 1.127 2005/10/26 13:28:19 roberto Exp $ +** $Id: lstrlib.c,v 1.130 2005/12/29 15:32:11 roberto Exp $ ** Standard library for string operations and pattern-matching ** See Copyright Notice in lua.h */ @@ -683,8 +683,13 @@ static int str_gsub (lua_State *L) { /* maximum size of each formatted item (> len(format('%99.99f', -1e308))) */ #define MAX_ITEM 512 -/* maximum size of each format specification (such as '%-099.99d') */ -#define MAX_FORMAT 20 +/* valid flags in a format specification */ +#define FLAGS "-+ #0" +/* +** maximum size of each format specification (such as '%-099.99d') +** (+10 accounts for %99.99x plus margin of error) +*/ +#define MAX_FORMAT (sizeof(FLAGS) + sizeof(LUA_INTFRMLEN) + 10) static void addquoted (lua_State *L, luaL_Buffer *b, int arg) { @@ -712,30 +717,37 @@ static void addquoted (lua_State *L, luaL_Buffer *b, int arg) { luaL_addchar(b, '"'); } - -static const char *scanformat (lua_State *L, const char *strfrmt, - char *form, int *hasprecision) { +static const char *scanformat (lua_State *L, const char *strfrmt, char *form) { const char *p = strfrmt; - while (strchr("-+ #0", *p)) p++; /* skip flags */ + while (strchr(FLAGS, *p)) p++; /* skip flags */ + if ((size_t)(p - strfrmt) >= sizeof(FLAGS)) + luaL_error(L, "invalid format (repeated flags)"); if (isdigit(uchar(*p))) p++; /* skip width */ if (isdigit(uchar(*p))) p++; /* (2 digits at most) */ if (*p == '.') { p++; - *hasprecision = 1; if (isdigit(uchar(*p))) p++; /* skip precision */ if (isdigit(uchar(*p))) p++; /* (2 digits at most) */ } if (isdigit(uchar(*p))) luaL_error(L, "invalid format (width or precision too long)"); - if (p-strfrmt+2 > MAX_FORMAT) /* +2 to include `%' and the specifier */ - luaL_error(L, "invalid format (too long)"); - form[0] = L_ESC; - strncpy(form+1, strfrmt, p-strfrmt+1); - form[p-strfrmt+2] = 0; + *(form++) = '%'; + strncpy(form, strfrmt, p - strfrmt + 1); + form += p - strfrmt + 1; + *form = '\0'; return p; } +static void addintlen (char *form) { + size_t l = strlen(form); + char spec = form[l - 1]; + strcpy(form + l - 1, LUA_INTFRMLEN); + form[l + sizeof(LUA_INTFRMLEN) - 2] = spec; + form[l + sizeof(LUA_INTFRMLEN) - 1] = '\0'; +} + + static int str_format (lua_State *L) { int arg = 1; size_t sfl; @@ -751,21 +763,26 @@ static int str_format (lua_State *L) { else { /* format item */ char form[MAX_FORMAT]; /* to store the format (`%...') */ char buff[MAX_ITEM]; /* to store the formatted item */ - int hasprecision = 0; arg++; - strfrmt = scanformat(L, strfrmt, form, &hasprecision); + strfrmt = scanformat(L, strfrmt, form); switch (*strfrmt++) { - case 'c': case 'd': case 'i': { - sprintf(buff, form, luaL_checkint(L, arg)); + case 'c': { + sprintf(buff, form, (int)luaL_checknumber(L, arg)); + break; + } + case 'd': case 'i': { + addintlen(form); + sprintf(buff, form, (LUA_INTFRM_T)luaL_checknumber(L, arg)); break; } case 'o': case 'u': case 'x': case 'X': { - sprintf(buff, form, (unsigned int)(luaL_checknumber(L, arg))); + addintlen(form); + sprintf(buff, form, (unsigned LUA_INTFRM_T)luaL_checknumber(L, arg)); break; } case 'e': case 'E': case 'f': case 'g': case 'G': { - sprintf(buff, form, luaL_checknumber(L, arg)); + sprintf(buff, form, (double)luaL_checknumber(L, arg)); break; } case 'q': { @@ -775,7 +792,7 @@ static int str_format (lua_State *L) { case 's': { size_t l; const char *s = luaL_checklstring(L, arg, &l); - if (!hasprecision && l >= 100) { + if (!strchr(form, '.') && l >= 100) { /* no precision and string is too long to be formatted; keep original string */ lua_pushvalue(L, arg); @@ -820,7 +837,7 @@ static const luaL_Reg strlib[] = { static void createmetatable (lua_State *L) { - lua_newtable(L); /* create metatable for strings */ + lua_createtable(L, 0, 1); /* create metatable for strings */ lua_pushliteral(L, ""); /* dummy string */ lua_pushvalue(L, -2); lua_setmetatable(L, -2); /* set string metatable */ diff --git a/src/ltable.c b/src/ltable.c index 5d4a828a..029cd506 100644 --- a/src/ltable.c +++ b/src/ltable.c @@ -1,5 +1,5 @@ /* -** $Id: ltable.c,v 2.27 2005/10/24 17:37:52 roberto Exp $ +** $Id: ltable.c,v 2.31 2006/01/10 13:13:06 roberto Exp $ ** Lua tables (hash) ** See Copyright Notice in lua.h */ @@ -66,13 +66,15 @@ /* ** number of ints inside a lua_Number */ -#define numints cast(int, sizeof(lua_Number)/sizeof(int)) +#define numints cast_int(sizeof(lua_Number)/sizeof(int)) -const Node luaH_dummynode = { +#define dummynode (&dummynode_) + +static const Node dummynode_ = { {{NULL}, LUA_TNIL}, /* value */ - {{NULL}, LUA_TNIL, NULL} /* key */ + {{{NULL}, LUA_TNIL, NULL}} /* key */ }; @@ -95,7 +97,7 @@ static Node *hashnum (const Table *t, lua_Number n) { ** returns the `main' position of an element in a table (that is, the index ** of its hash value) */ -Node *luaH_mainposition (const Table *t, const TValue *key) { +static Node *mainposition (const Table *t, const TValue *key) { switch (ttype(key)) { case LUA_TNUMBER: return hashnum(t, nvalue(key)); @@ -120,7 +122,7 @@ static int arrayindex (const TValue *key) { lua_Number n = nvalue(key); int k; lua_number2int(k, n); - if (luai_numeq(cast(lua_Number, k), nvalue(key))) + if (luai_numeq(cast_num(k), nvalue(key))) return k; } return -1; /* `key' did not match some condition */ @@ -139,13 +141,13 @@ static int findindex (lua_State *L, Table *t, StkId key) { if (0 < i && i <= t->sizearray) /* is `key' inside array part? */ return i-1; /* yes; that's the index (corrected to C) */ else { - Node *n = luaH_mainposition(t, key); + Node *n = mainposition(t, key); do { /* check whether `key' is somewhere in the chain */ /* key may be dead already, but it is ok to use it in `next' */ if (luaO_rawequalObj(key2tval(n), key) || (ttype(gkey(n)) == LUA_TDEADKEY && iscollectable(key) && gcvalue(gkey(n)) == gcvalue(key))) { - i = cast(int, n - gnode(t, 0)); /* key index in hash table */ + i = cast_int(n - gnode(t, 0)); /* key index in hash table */ /* hash elements are numbered after array ones */ return i + t->sizearray; } @@ -161,7 +163,7 @@ int luaH_next (lua_State *L, Table *t, StkId key) { int i = findindex(L, t, key); /* find original element */ for (i++; i < t->sizearray; i++) { /* try first array part */ if (!ttisnil(&t->array[i])) { /* a non-nil value? */ - setnvalue(key, cast(lua_Number, i+1)); + setnvalue(key, cast_num(i+1)); setobj2s(L, key+1, &t->array[i]); return 1; } @@ -270,7 +272,7 @@ static void setarrayvector (lua_State *L, Table *t, int size) { static void setnodevector (lua_State *L, Table *t, int size) { int lsize; if (size == 0) { /* no elements to hash part? */ - t->node = cast(Node *, &luaH_dummynode); /* use common `dummynode' */ + t->node = cast(Node *, dummynode); /* use common `dummynode' */ lsize = 0; } else { @@ -281,12 +283,13 @@ static void setnodevector (lua_State *L, Table *t, int size) { size = twoto(lsize); t->node = luaM_newvector(L, size, Node); for (i=0; i<size; i++) { - gnext(&t->node[i]) = NULL; - setnilvalue(gkey(gnode(t, i))); - setnilvalue(gval(gnode(t, i))); + Node *n = gnode(t, i); + gnext(n) = NULL; + setnilvalue(gkey(n)); + setnilvalue(gval(n)); } } - t->lsizenode = cast(lu_byte, lsize); + t->lsizenode = cast_byte(lsize); t->lastfree = gnode(t, size); /* all positions are free */ } @@ -316,13 +319,13 @@ static void resize (lua_State *L, Table *t, int nasize, int nhsize) { if (!ttisnil(gval(old))) setobjt2t(L, luaH_set(L, t, key2tval(old)), gval(old)); } - if (nold != &luaH_dummynode) + if (nold != dummynode) luaM_freearray(L, nold, twoto(oldhsize), Node); /* free old array */ } void luaH_resizearray (lua_State *L, Table *t, int nasize) { - int nsize = (t->node == &luaH_dummynode) ? 0 : sizenode(t); + int nsize = (t->node == dummynode) ? 0 : sizenode(t); resize(L, t, nasize, nsize); } @@ -356,12 +359,12 @@ Table *luaH_new (lua_State *L, int narray, int nhash) { Table *t = luaM_new(L, Table); luaC_link(L, obj2gco(t), LUA_TTABLE); t->metatable = NULL; - t->flags = cast(lu_byte, ~0); + t->flags = cast_byte(~0); /* temporary values (kept only if some malloc fails) */ t->array = NULL; t->sizearray = 0; t->lsizenode = 0; - t->node = cast(Node *, &luaH_dummynode); + t->node = cast(Node *, dummynode); setarrayvector(L, t, narray); setnodevector(L, t, nhash); return t; @@ -369,7 +372,7 @@ Table *luaH_new (lua_State *L, int narray, int nhash) { void luaH_free (lua_State *L, Table *t) { - if (t->node != &luaH_dummynode) + if (t->node != dummynode) luaM_freearray(L, t->node, sizenode(t), Node); luaM_freearray(L, t->array, t->sizearray, TValue); luaM_free(L, t); @@ -394,16 +397,16 @@ static Node *getfreepos (Table *t) { ** position), new key goes to an empty position. */ static TValue *newkey (lua_State *L, Table *t, const TValue *key) { - Node *mp = luaH_mainposition(t, key); - if (!ttisnil(gval(mp)) || mp == &luaH_dummynode) { + Node *mp = mainposition(t, key); + if (!ttisnil(gval(mp)) || mp == dummynode) { Node *othern; Node *n = getfreepos(t); /* get a free place */ if (n == NULL) { /* cannot find a free place? */ rehash(L, t, key); /* grow table */ return luaH_set(L, t, key); /* re-insert key into grown table */ } - lua_assert(n != &luaH_dummynode); - othern = luaH_mainposition(t, key2tval(mp)); + lua_assert(n != dummynode); + othern = mainposition(t, key2tval(mp)); if (othern != mp) { /* is colliding node out of its main position? */ /* yes; move colliding node into free position */ while (gnext(othern) != mp) othern = gnext(othern); /* find previous */ @@ -434,14 +437,14 @@ const TValue *luaH_getnum (Table *t, int key) { if (cast(unsigned int, key-1) < cast(unsigned int, t->sizearray)) return &t->array[key-1]; else { - lua_Number nk = cast(lua_Number, key); + lua_Number nk = cast_num(key); Node *n = hashnum(t, nk); do { /* check whether `key' is somewhere in the chain */ if (ttisnumber(gkey(n)) && luai_numeq(nvalue(gkey(n)), nk)) return gval(n); /* that's it */ else n = gnext(n); } while (n); - return &luaO_nilobject; + return luaO_nilobject; } } @@ -456,7 +459,7 @@ const TValue *luaH_getstr (Table *t, TString *key) { return gval(n); /* that's it */ else n = gnext(n); } while (n); - return &luaO_nilobject; + return luaO_nilobject; } @@ -465,24 +468,24 @@ const TValue *luaH_getstr (Table *t, TString *key) { */ const TValue *luaH_get (Table *t, const TValue *key) { switch (ttype(key)) { - case LUA_TNIL: return &luaO_nilobject; + case LUA_TNIL: return luaO_nilobject; case LUA_TSTRING: return luaH_getstr(t, rawtsvalue(key)); case LUA_TNUMBER: { int k; lua_Number n = nvalue(key); lua_number2int(k, n); - if (luai_numeq(cast(lua_Number, k), nvalue(key))) /* index is int? */ + if (luai_numeq(cast_num(k), nvalue(key))) /* index is int? */ return luaH_getnum(t, k); /* use specialized version */ /* else go through */ } default: { - Node *n = luaH_mainposition(t, key); + Node *n = mainposition(t, key); do { /* check whether `key' is somewhere in the chain */ if (luaO_rawequalObj(key2tval(n), key)) return gval(n); /* that's it */ else n = gnext(n); } while (n); - return &luaO_nilobject; + return luaO_nilobject; } } } @@ -491,11 +494,11 @@ const TValue *luaH_get (Table *t, const TValue *key) { TValue *luaH_set (lua_State *L, Table *t, const TValue *key) { const TValue *p = luaH_get(t, key); t->flags = 0; - if (p != &luaO_nilobject) + if (p != luaO_nilobject) return cast(TValue *, p); else { if (ttisnil(key)) luaG_runerror(L, "table index is nil"); - else if (ttisnumber(key) && !luai_numeq(nvalue(key), nvalue(key))) + else if (ttisnumber(key) && luai_numisnan(nvalue(key))) luaG_runerror(L, "table index is NaN"); return newkey(L, t, key); } @@ -504,11 +507,11 @@ TValue *luaH_set (lua_State *L, Table *t, const TValue *key) { TValue *luaH_setnum (lua_State *L, Table *t, int key) { const TValue *p = luaH_getnum(t, key); - if (p != &luaO_nilobject) + if (p != luaO_nilobject) return cast(TValue *, p); else { TValue k; - setnvalue(&k, cast(lua_Number, key)); + setnvalue(&k, cast_num(key)); return newkey(L, t, &k); } } @@ -516,7 +519,7 @@ TValue *luaH_setnum (lua_State *L, Table *t, int key) { TValue *luaH_setstr (lua_State *L, Table *t, TString *key) { const TValue *p = luaH_getstr(t, key); - if (p != &luaO_nilobject) + if (p != luaO_nilobject) return cast(TValue *, p); else { TValue k; @@ -528,11 +531,11 @@ TValue *luaH_setstr (lua_State *L, Table *t, TString *key) { static int unbound_search (Table *t, unsigned int j) { unsigned int i = j; /* i is zero or a present index */ - j = j+1; + j++; /* find `i' and `j' such that i is present and j is not */ while (!ttisnil(luaH_getnum(t, j))) { i = j; - j = i*2; + j *= 2; if (j > cast(unsigned int, MAX_INT)) { /* overflow? */ /* table was built with bad purposes: resort to linear search */ i = 1; @@ -541,7 +544,7 @@ static int unbound_search (Table *t, unsigned int j) { } } /* now do a binary search between them */ - while (i < j-1) { + while (j - i > 1) { unsigned int m = (i+j)/2; if (ttisnil(luaH_getnum(t, m))) j = m; else i = m; @@ -567,8 +570,19 @@ int luaH_getn (Table *t) { return i; } /* else must find a boundary in hash part */ - else if (t->node == &luaH_dummynode) /* hash part is empty? */ + else if (t->node == dummynode) /* hash part is empty? */ return j; /* that is easy... */ else return unbound_search(t, j); } + + +#if defined(LUA_DEBUG) + +Node *luaH_mainposition (const Table *t, const TValue *key) { + return mainposition(t, key); +} + +int luaH_isdummy (Node *n) { return n == dummynode; } + +#endif diff --git a/src/ltable.h b/src/ltable.h index 14a20448..09193cdb 100644 --- a/src/ltable.h +++ b/src/ltable.h @@ -1,5 +1,5 @@ /* -** $Id: ltable.h,v 2.8 2005/06/06 13:30:25 roberto Exp $ +** $Id: ltable.h,v 2.10 2006/01/10 13:13:06 roberto Exp $ ** Lua tables (hash) ** See Copyright Notice in lua.h */ @@ -11,15 +11,13 @@ #define gnode(t,i) (&(t)->node[i]) -#define gkey(n) (&(n)->i_key) +#define gkey(n) (&(n)->i_key.nk) #define gval(n) (&(n)->i_val) -#define gnext(n) ((n)->i_key.next) +#define gnext(n) ((n)->i_key.nk.next) -#define key2tval(n) (cast(const TValue *, gkey(n))) +#define key2tval(n) (&(n)->i_key.tvk) -LUAI_DATA const Node luaH_dummynode; - LUAI_FUNC const TValue *luaH_getnum (Table *t, int key); LUAI_FUNC TValue *luaH_setnum (lua_State *L, Table *t, int key); LUAI_FUNC const TValue *luaH_getstr (Table *t, TString *key); @@ -32,8 +30,11 @@ LUAI_FUNC void luaH_free (lua_State *L, Table *t); LUAI_FUNC int luaH_next (lua_State *L, Table *t, StkId key); LUAI_FUNC int luaH_getn (Table *t); -/* exported only for debugging */ + +#if defined(LUA_DEBUG) LUAI_FUNC Node *luaH_mainposition (const Table *t, const TValue *key); +LUAI_FUNC int luaH_isdummy (Node *n); +#endif #endif @@ -1,5 +1,5 @@ /* -** $Id: ltm.c,v 2.6 2005/05/20 15:53:42 roberto Exp $ +** $Id: ltm.c,v 2.8 2006/01/10 12:50:00 roberto Exp $ ** Tag methods ** See Copyright Notice in lua.h */ @@ -51,7 +51,7 @@ const TValue *luaT_gettm (Table *events, TMS event, TString *ename) { const TValue *tm = luaH_getstr(events, ename); lua_assert(event <= TM_EQ); if (ttisnil(tm)) { /* no tag method? */ - events->flags |= cast(lu_byte, 1u<<event); /* cache this fact */ + events->flags |= cast_byte(1u<<event); /* cache this fact */ return NULL; } else return tm; @@ -70,6 +70,6 @@ const TValue *luaT_gettmbyobj (lua_State *L, const TValue *o, TMS event) { default: mt = G(L)->mt[ttype(o)]; } - return (mt ? luaH_getstr(mt, G(L)->tmname[event]) : &luaO_nilobject); + return (mt ? luaH_getstr(mt, G(L)->tmname[event]) : luaO_nilobject); } @@ -1,5 +1,5 @@ /* -** $Id: lua.c,v 1.154 2005/10/24 17:38:47 roberto Exp $ +** $Id: lua.c,v 1.157 2005/12/29 16:23:32 roberto Exp $ ** Lua stand-alone interpreter ** See Copyright Notice in lua.h */ @@ -120,7 +120,7 @@ static int getargs (lua_State *L, char **argv, int n) { luaL_checkstack(L, narg + 3, "too many arguments to script"); for (i=n+1; i < argc; i++) lua_pushstring(L, argv[i]); - lua_newtable(L); + lua_createtable(L, narg, n + 1); for (i=0; i < argc; i++) { lua_pushstring(L, argv[i]); lua_rawseti(L, -2, i - n); @@ -215,7 +215,6 @@ static void dotty (lua_State *L) { int status; const char *oldprogname = progname; progname = NULL; - print_version(); while ((status = loadline(L)) != -1) { if (status == 0) status = docall(L, 0, 0); report(L, status); @@ -261,7 +260,7 @@ static int collectargs (char **argv, int *pi, int *pv, int *pe) { switch (argv[i][1]) { /* option */ case '-': return (argv[i+1] != NULL ? i+1 : 0); case '\0': return i; - case 'i': *pi = 1; break; + case 'i': *pi = 1; /* go through */ case 'v': *pv = 1; break; case 'e': *pe = 1; /* go through */ case 'l': @@ -330,7 +329,9 @@ static int pmain (lua_State *L) { int has_i = 0, has_v = 0, has_e = 0; globalL = L; if (argv[0] && argv[0][0]) progname = argv[0]; + lua_gc(L, LUA_GCSTOP, 0); /* stop collector during initialization */ luaL_openlibs(L); /* open libraries */ + lua_gc(L, LUA_GCRESTART, 0); s->status = handle_luainit(L); if (s->status != 0) return 0; script = collectargs(argv, &has_i, &has_v, &has_e); @@ -348,7 +349,10 @@ static int pmain (lua_State *L) { if (has_i) dotty(L); else if (script == 0 && !has_e && !has_v) { - if (lua_stdin_is_tty()) dotty(L); + if (lua_stdin_is_tty()) { + print_version(); + dotty(L); + } else dofile(L, NULL); /* executes stdin as a file */ } return 0; @@ -1,5 +1,5 @@ /* -** $Id: lua.h,v 1.214 2005/10/20 11:35:50 roberto Exp $ +** $Id: lua.h,v 1.216 2006/01/10 12:50:13 roberto Exp $ ** Lua - An Extensible Extension Language ** Lua.org, PUC-Rio, Brazil (http://www.lua.org) ** See Copyright Notice at the end of this file @@ -16,9 +16,9 @@ #include "luaconf.h" -#define LUA_VERSION "Lua 5.1 (beta)" +#define LUA_VERSION "Lua 5.1" #define LUA_VERSION_NUM 501 -#define LUA_COPYRIGHT "Copyright (C) 1994-2005 Lua.org, PUC-Rio" +#define LUA_COPYRIGHT "Copyright (C) 1994-2006 Lua.org, PUC-Rio" #define LUA_AUTHORS "R. Ierusalimschy, L. H. de Figueiredo & W. Celes" @@ -358,7 +358,7 @@ struct lua_Debug { /****************************************************************************** -* Copyright (C) 1994-2005 Lua.org, PUC-Rio. All rights reserved. +* Copyright (C) 1994-2006 Lua.org, PUC-Rio. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining * a copy of this software and associated documentation files (the diff --git a/src/luaconf.h b/src/luaconf.h index ea685a2d..37492955 100644 --- a/src/luaconf.h +++ b/src/luaconf.h @@ -1,5 +1,5 @@ /* -** $Id: luaconf.h,v 1.74 2005/11/16 16:24:28 roberto Exp $ +** $Id: luaconf.h,v 1.77 2005/12/27 17:12:00 roberto Exp $ ** Configuration file for Lua ** See Copyright Notice in lua.h */ @@ -28,6 +28,11 @@ #define LUA_ANSI #endif + +#if !defined(LUA_ANSI) && defined(_WIN32) +#define LUA_WIN +#endif + #if defined(LUA_USE_LINUX) #define LUA_USE_POSIX #define LUA_USE_DLOPEN /* needs an extra library: -ldl */ @@ -178,13 +183,6 @@ /* -@@ lua_assert describes the internal assertions in Lua. -** CHANGE that only if you need to debug Lua. -*/ -#define lua_assert(c) ((void)0) - - -/* @@ LUA_QL describes how error messages quote program elements. ** CHANGE it if you want a different appearance. */ @@ -217,7 +215,7 @@ #if defined(LUA_USE_ISATTY) #include <unistd.h> #define lua_stdin_is_tty() isatty(0) -#elif !defined(LUA_ANSI) && defined(_WIN32) +#elif defined(LUA_WIN) #include <io.h> #include <stdio.h> #define lua_stdin_is_tty() _isatty(_fileno(stdin)) @@ -368,8 +366,7 @@ #include <assert.h> #define luai_apicheck(L,o) { (void)L; assert(o); } #else -/* (By default lua_assert is empty, so luai_apicheck is also empty.) */ -#define luai_apicheck(L,o) { (void)L; lua_assert(o); } +#define luai_apicheck(L,o) { (void)L; } #endif @@ -529,6 +526,7 @@ #define luai_numeq(a,b) ((a)==(b)) #define luai_numlt(a,b) ((a)<(b)) #define luai_numle(a,b) ((a)<=(b)) +#define luai_numisnan(a) (!luai_numeq((a), (a))) #endif @@ -644,7 +642,7 @@ union luai_Cast { double l_d; long l_l; }; #define lua_popen(L,c,m) ((void)L, popen(c,m)) #define lua_pclose(L,file) ((void)L, (pclose(file) != -1)) -#elif !defined(LUA_ANSI) && defined(_WIN32) +#elif defined(LUA_WIN) #define lua_popen(L,c,m) ((void)L, _popen(c,m)) #define lua_pclose(L,file) ((void)L, (_pclose(file) != -1)) @@ -675,7 +673,7 @@ union luai_Cast { double l_d; long l_l; }; #define LUA_DL_DLOPEN #endif -#if !defined(LUA_ANSI) && defined(_WIN32) +#if defined(LUA_WIN) #define LUA_DL_DLL #endif @@ -702,6 +700,26 @@ union luai_Cast { double l_d; long l_l; }; #define luai_userstateyield(L,n) ((void)L) +/* +@@ LUA_INTFRMLEN is the length modifier for integer conversions +@* in 'string.fomat'. +@@ LUA_INTFRM_T is the integer type correspoding to the previous length +@* modifier. +** CHANGE them if your system supports long long or does not support long. +*/ + +#if defined(LUA_USELONGLONG) + +#define LUA_INTFRMLEN "ll" +#define LUA_INTFRM_T long long + +#else + +#define LUA_INTFRMLEN "l" +#define LUA_INTFRM_T long + +#endif + /* =================================================================== */ diff --git a/src/lualib.h b/src/lualib.h index f52bb888..0c76232c 100644 --- a/src/lualib.h +++ b/src/lualib.h @@ -1,5 +1,5 @@ /* -** $Id: lualib.h,v 1.35 2005/08/10 18:06:58 roberto Exp $ +** $Id: lualib.h,v 1.36 2005/12/27 17:12:00 roberto Exp $ ** Lua standard libraries ** See Copyright Notice in lua.h */ @@ -44,4 +44,10 @@ LUALIB_API int (luaopen_package) (lua_State *L); LUALIB_API void (luaL_openlibs) (lua_State *L); + +#ifndef lua_assert +#define lua_assert(x) ((void)0) +#endif + + #endif @@ -1,5 +1,5 @@ /* -** $Id: lvm.c,v 2.59 2005/11/01 16:08:45 roberto Exp $ +** $Id: lvm.c,v 2.61 2006/01/10 12:50:00 roberto Exp $ ** Lua virtual machine ** See Copyright Notice in lua.h */ @@ -509,16 +509,16 @@ void luaV_execute (lua_State *L, int nexeccalls) { const TValue *rb = RB(i); switch (ttype(rb)) { case LUA_TTABLE: { - setnvalue(ra, cast(lua_Number, luaH_getn(hvalue(rb)))); + setnvalue(ra, cast_num(luaH_getn(hvalue(rb)))); break; } case LUA_TSTRING: { - setnvalue(ra, cast(lua_Number, tsvalue(rb)->len)); + setnvalue(ra, cast_num(tsvalue(rb)->len)); break; } default: { /* try metamethod */ Protect( - if (!call_binTM(L, rb, &luaO_nilobject, ra, TM_LEN)) + if (!call_binTM(L, rb, luaO_nilobject, ra, TM_LEN)) luaG_typeerror(L, rb, "get length of"); ) } @@ -693,10 +693,10 @@ void luaV_execute (lua_State *L, int nexeccalls) { int last; Table *h; if (n == 0) { - n = cast(int, L->top - ra) - 1; + n = cast_int(L->top - ra) - 1; L->top = L->ci->top; } - if (c == 0) c = cast(int, *pc++); + if (c == 0) c = cast_int(*pc++); runtime_check(L, ttistable(ra)); h = hvalue(ra); last = ((c-1)*LFIELDS_PER_FLUSH) + n; @@ -737,7 +737,7 @@ void luaV_execute (lua_State *L, int nexeccalls) { int b = GETARG_B(i) - 1; int j; CallInfo *ci = L->ci; - int n = cast(int, ci->base - ci->func) - cl->p->numparams - 1; + int n = cast_int(ci->base - ci->func) - cl->p->numparams - 1; if (b == LUA_MULTRET) { Protect(luaD_checkstack(L, n)); ra = RA(i); /* previous call may change the stack */ diff --git a/src/print.c b/src/print.c index cfecba96..1c3a4457 100644 --- a/src/print.c +++ b/src/print.c @@ -1,5 +1,5 @@ /* -** $Id: print.c,v 1.53 2005/11/11 14:03:13 lhf Exp $ +** $Id: print.c,v 1.54 2006/01/11 22:49:27 lhf Exp $ ** print bytecodes ** See Copyright Notice in lua.h */ @@ -36,7 +36,10 @@ static void PrintString(const Proto* f, int n) case '\r': printf("\\r"); break; case '\t': printf("\\t"); break; case '\v': printf("\\v"); break; - default: printf(isprint((unsigned char)*s) ? "%c" : "\\%03d",*s); + default: if (isprint((unsigned char)*s)) + printf("%c",*s); + else + printf("\\%03u",(unsigned char)*s); } } putchar('"'); |