diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 702 |
1 files changed, 2 insertions, 700 deletions
diff --git a/doc/manual.html b/doc/manual.html index 4e41683..7110848 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -5537,10 +5537,8 @@ it simply registers all functions in the list <code>l</code> When called with a non-null <code>libname</code>, <code>luaL_register</code> creates a new table <code>t</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 -variable <code>libname</code>, +If there is a table in variable <code>libname</code>, reuses this table instead of creating a new one. @@ -5762,17 +5760,6 @@ Returns the previous value for <em>step</em>. -<p> -<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> -Opens the named file and executes its contents as a Lua chunk. -When called without arguments, -<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> <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> @@ -5850,71 +5837,6 @@ will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), &middo up to the first integer key absent from the table. - - -<p> -<hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></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 -with previous results. -A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. - - -<p> -If there are no errors, -returns the compiled chunk as a function; -otherwise, returns <b>nil</b> plus the error message. -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. -When absent, -it defaults to "<code>=(load)</code>". - - - - -<p> -<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3> - - -<p> -Similar to <a href="#pdf-load"><code>load</code></a>, -but gets the chunk from file <code>filename</code> -or from the standard input, -if no file name is given. - - - - -<p> -<hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3> - - -<p> -Similar to <a href="#pdf-load"><code>load</code></a>, -but gets the chunk from the given string. - - -<p> -To load and run a given string, use the idiom - -<pre> - assert(loadstring(s))() -</pre> - -<p> -When absent, -<code>chunkname</code> defaults to the given string. - - - - <p> <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> @@ -5975,25 +5897,6 @@ the table during its traversal. <p> -<hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3> - - -<p> -Calls function <code>f</code> with -the given arguments in <em>protected mode</em>. -This means that any error inside <code>f</code> is not propagated; -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, <code>pcall</code> also returns all results from the call, -after this first result. -In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. - - - - -<p> <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> Receives any number of arguments, and prints their values to <code>stdout</code>, @@ -6171,35 +6074,6 @@ The current contents of this variable is "<code>Lua 5.1</code>". -<p> -<hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3> - - -<p> -This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, -except that you can set a new error handler. - - -<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, <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 this case, <code>xpcall</code> also returns all results from the call, -after this first result. -In case of any error, -<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>. - - - - - - - <h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2> <p> @@ -6310,309 +6184,6 @@ Any arguments to <code>yield</code> are passed as extra results to <code>resume< -<h2>5.3 - <a name="5.3">Modules</a></h2> - -<p> -The package library provides basic -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 <a name="pdf-package"><code>package</code></a>. - - -<p> -<hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3> - - -<p> -Creates a module. -If there is a table in <code>package.loaded[name]</code>, -this table is the module. -Otherwise, if there is a global table <code>t</code> with the given name, -this table is the module. -Otherwise creates a new table <code>t</code> and -sets it as the value of the global <code>name</code> and -the value of <code>package.loaded[name]</code>. -This function also initializes <code>t._NAME</code> with the given name, -<code>t._M</code> with the module (<code>t</code> itself), -and <code>t._PACKAGE</code> with the package name -(the full module name minus last component; see below). -Finally, <code>module</code> sets <code>t</code> as the new environment -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 exist) -tables for each component. -For instance, if <code>name</code> is <code>a.b.c</code>, -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 can receive optional <em>options</em> after -the module name, -where each option is a function to be applied over the module. - - - - -<p> -<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> - - -<p> -Loads the given module. -The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table -to determine whether <code>modname</code> is already loaded. -If it is, then <code>require</code> returns the value stored -at <code>package.loaded[modname]</code>. -Otherwise, it tries to find a <em>loader</em> for the module. - - -<p> -To find a loader, -<code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array. -By changing this array, -we can change how <code>require</code> looks for a module. -The following explanation is based on the default configuration -for <a href="#pdf-package.loaders"><code>package.loaders</code></a>. - - -<p> -First <code>require</code> queries <code>package.preload[modname]</code>. -If it has a value, -this value (which should be a function) is the loader. -Otherwise <code>require</code> searches for a Lua loader using the -path stored in <a href="#pdf-package.path"><code>package.path</code></a>. -If that also fails, it searches for a C loader using the -path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. -If that also fails, -it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>). - - -<p> -Once a loader is found, -<code>require</code> calls the loader with a single argument, <code>modname</code>. -If the loader returns any value, -<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. -If the loader returns no value and -has not assigned any value to <code>package.loaded[modname]</code>, -then <code>require</code> assigns <b>true</b> to this entry. -In any case, <code>require</code> 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 the module, -then <code>require</code> signals an error. - - - - -<p> -<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></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 <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way -it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, -using the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a> -or a default path defined in <code>luaconf.h</code>. - - - - -<p> - -<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> - - -<p> -A table used by <a href="#pdf-require"><code>require</code></a> to control which -modules are already loaded. -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> -<hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3> - - -<p> -A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. - - -<p> -Each entry in this table is a <em>searcher function</em>. -When looking for a module, -<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, -with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its -sole parameter. -The function can return another function (the module <em>loader</em>) -or a string explaining why it did not find that module -(or <b>nil</b> if it has nothing to say). -Lua initializes this table with four functions. - - -<p> -The first searcher simply looks for a loader in the -<a href="#pdf-package.preload"><code>package.preload</code></a> table. - - -<p> -The second searcher looks for a loader as a Lua library, -using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. -A path is a sequence of <em>templates</em> separated by semicolons. -For each template, -the searcher will change each interrogation -mark in the template by <code>filename</code>, -which is the module name with each dot replaced by a -"directory separator" (such as "<code>/</code>" in Unix); -then it will try to open the resulting file name. -So, for instance, if the Lua path is the string - -<pre> - "./?.lua;./?.lc;/usr/local/?/init.lua" -</pre><p> -the search for a Lua file for module <code>foo</code> -will try to open the files -<code>./foo.lua</code>, <code>./foo.lc</code>, and -<code>/usr/local/foo/init.lua</code>, in that order. - - -<p> -The third searcher looks for a loader as a C library, -using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. -For instance, -if the C path is the string - -<pre> - "./?.so;./?.dll;/usr/local/?/init.so" -</pre><p> -the searcher for module <code>foo</code> -will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, -and <code>/usr/local/foo/init.so</code>, in that order. -Once it finds a C library, -this searcher first uses a dynamic link facility to link the -application with the library. -Then it tries to find a C function inside the library to -be used as the loader. -The name of this C function is the string "<code>luaopen_</code>" -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> -The fourth searcher tries an <em>all-in-one loader</em>. -It searches the C path for a library for -the root name of the given module. -For instance, when requiring <code>a.b.c</code>, -it will search for a C library for <code>a</code>. -If found, it looks into it for an open function for -the submodule; -in our example, that would be <code>luaopen_a_b_c</code>. -With this facility, a package can pack several C submodules -into one single library, -with each submodule keeping its original open function. - - - - -<p> -<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> - - -<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> -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 and -does not 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, Mac OS X, Solaris, BSD, -plus other Unix systems that support the <code>dlfcn</code> standard). - - - - -<p> -<hr><h3><a name="pdf-package.path"><code>package.path</code></a></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 <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or -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. - - - - -<p> -<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> - - -<p> -A table to store loaders for specific modules -(see <a href="#pdf-require"><code>require</code></a>). - - - - -<p> -<hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3> - - -<p> -Sets a metatable for <code>module</code> with -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>. - - - - - - - <h2>5.4 - <a name="5.4">String Manipulation</a></h2> <p> @@ -7556,29 +7127,6 @@ Returns the hyperbolic tangent of <code>x</code>. <h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2> -<p> -The I/O library provides two different styles for file manipulation. -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 these default files. -The second style uses explicit file descriptors. - - -<p> -When using implicit file descriptors, -all operations are supplied by table <a name="pdf-io"><code>io</code></a>. -When using explicit file descriptors, -the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor -and then all operations are supplied as methods of the file descriptor. - - -<p> -The table <code>io</code> also provides -three predefined file descriptors with their usual meanings from C: -<a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>. -The I/O library never closes these files. - <p> Unless otherwise stated, @@ -7589,71 +7137,11 @@ and some value different from <b>nil</b> on success. <p> -<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> +<hr><h3><a name="pdf-io.close"><code>io.close (file)</code></a></h3> <p> Equivalent to <code>file:close()</code>. -Without a <code>file</code>, closes the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> - - -<p> -Equivalent to <code>file:flush</code> over the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></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. -When called with a file handle, -it simply sets this file handle as the default input file. -When called without parameters, -it returns the current default input file. - - -<p> -In case of errors this function raises the error, -instead of returning an error code. - - - - -<p> -<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3> - - -<p> -Opens the given file name in read mode -and returns an iterator function that, -each time it is called, -returns a new line from the file. -Therefore, the construction - -<pre> - for line in io.lines(filename) do <em>body</em> end -</pre><p> -will iterate over all lines of the file. -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> (with no file name) is equivalent -to <code>io.input():lines()</code>; -that is, it iterates over the lines of the default input file. -In this case it does not close the file when the loop ends. - @@ -7689,45 +7177,6 @@ standard C function <code>fopen</code>. <p> -<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> - - -<p> -Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> - - -<p> -Starts program <code>prog</code> in a separated process and returns -a file handle that you can use to read data from this program -(if <code>mode</code> is <code>"r"</code>, the default) -or to write data to this program -(if <code>mode</code> is <code>"w"</code>). - - -<p> -This function is system dependent and is not available -on all platforms. - - - - -<p> -<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> - - -<p> -Equivalent to <code>io.input():read</code>. - - - - -<p> <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> @@ -7753,16 +7202,6 @@ or <b>nil</b> if <code>obj</code> is not a file handle. <p> -<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> - - -<p> -Equivalent to <code>io.output():write</code>. - - - - -<p> <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> @@ -8576,143 +8015,6 @@ is a more portable solution.) -<h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1> - -<p> -Here we list the incompatibilities that you may find when moving a program -from Lua 5.0 to Lua 5.1. -You can avoid most of the incompatibilities compiling Lua with -appropriate options (see file <code>luaconf.h</code>). -However, -all these compatibility options will be removed in the next version of Lua. - - - -<h2>7.1 - <a name="7.1">Changes in the Language</a></h2> -<ul> - -<li> -The vararg system changed from the pseudo-argument <code>arg</code> with a -table with the extra arguments to the vararg expression. -(See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.) -</li> - -<li> -There was a subtle change in the scope of the implicit -variables of the <b>for</b> statement and for the <b>repeat</b> statement. -</li> - -<li> -The long string/long comment syntax (<code>[[<em>string</em>]]</code>) -does not allow nesting. -You can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases. -(See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.) -</li> - -</ul> - - - - -<h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2> -<ul> - -<li> -Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>. -(See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.) -</li> - -<li> -When <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its -third argument, -whenever this function returns <b>nil</b> or <b>false</b> the -replacement string is the whole match, -instead of the empty string. -</li> - -<li> -Function <code>table.setn</code> was deprecated. -Function <code>table.getn</code> corresponds -to the new length operator (<code>#</code>); -use the operator instead of the function. -(See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.) -</li> - -<li> -Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>. -(See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.) -</li> - -<li> -Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>. -(See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.) -</li> - -<li> -Functions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated. -You can use a for loop with <code>pairs</code> or <code>ipairs</code> instead. -</li> - -<li> -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 <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead -of from <code>LUA_PATH</code>. -</li> - -<li> -Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments. -Function <code>gcinfo</code> is deprecated; -use <code>collectgarbage("count")</code> instead. -</li> - -</ul> - - - - -<h2>7.3 - <a name="7.3">Changes in the API</a></h2> -<ul> - -<li> -The <code>luaopen_*</code> functions (to open libraries) -cannot be called directly, -like a regular C function. -They must be called through Lua, -like a Lua function. -</li> - -<li> -Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to -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>). -</li> - -<li> -Functions <code>luaL_getn</code> and <code>luaL_setn</code> -(from the auxiliary library) are deprecated. -Use <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code> -and nothing instead of <code>luaL_setn</code>. -</li> - -<li> -Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>. -</li> - -<li> -Function <code>luaL_checkudata</code> now throws an error when the given value -is not a userdata of the expected type. -(In Lua 5.0 it returned <code>NULL</code>.) -</li> - -</ul> - - - - <h1>8 - <a name="8">The Complete Syntax of Lua</a></h1> <p> |