Lua 5.1 reference manual

Goodreads helps you keep track of books you want to read. Want to Read saving…. Want to Read Currently Reading Read. Other editions. Enlarge cover. Error rating book. Refresh and try again. Open Preview See a Problem? Details if other :. Thanks for telling us about the problem.

Return to Book Page. Preview — Lua 5. Lua 5. Luiz Henrique de Figueiredo ,. Waldemar Celes. This manual is the official definition of Lua 5. Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programmin This manual is the official definition of Lua 5.

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 scripting language for any program that needs one. Get A Copy. Paperback , pages. More Details Original Title. Friend Reviews. To see what your friends thought of this book, please sign up. To ask other readers questions about Lua 5. Be the first to ask a question about Lua 5. Lists with This Book. As one Lua task is allocated to one lua command in the Lua script function, the Lua tasks will only use the number of scripts running at the same time.

As stated in Example 3, if multiple Lua scripts are specified with one lua command, multiple Lua scripts will execute in one task in the specified order. You can check the Lua script run and past execution status from the show status lua command. Also, to forcibly terminate running Lua scripts, use the terminate lua command. If a syntax error occurs in an executed Lua command or script, an INFO type error message will be output to the system log and script execution will be halted.

As duplicate checks of the script file are not performed, if you specify the same script file at the same time and execute lua command, the same script file will run with multiple Lua tasks.

If you mistakenly executed them, you can use the terminate lua command to forcibly terminate the unnecessary Lua task s. Complicated operations like the lua command cannot be performed.

As it is executed with a dedicated task, you can run resident Lua scripts that are endless in programs. Therefore, you need to make sure that the CPU usage rate does not become high for script programs as well see Precautions. The value of this expression is a list of all actual extra arguments, similar to a function with multiple results.

If a vararg expression is used inside another expression or in the middle of a list of expressions, then its return list is adjusted to one element.

If the expression is used as the last element of a list of expressions, then no adjustment is made unless that last expression is enclosed in parentheses. Results are returned using the return statement see 2. If control reaches the end of a function without encountering a return statement, then the function returns with no results. The colon syntax is used for defining methods , that is, functions that have an implicit extra parameter self.

Thus, the statement. Lua is a lexically scoped language. The scope of variables begins at the first statement after their declaration and lasts until the end of the innermost block that includes the declaration. Consider the following example:. Because of the lexical scoping rules, local variables can be freely accessed by functions defined inside their scope. A local variable used by an inner function is called an upvalue , or external local variable , inside the inner function.

Notice that each execution of a local statement defines new local variables. The loop creates ten closures that is, ten instances of the anonymous function. Each of these closures uses a different y variable, while all of them share the same x. Whenever an error occurs during Lua compilation or execution, control returns to C, which can take appropriate measures such as printing an error message.

Lua code can explicitly generate an error by calling the error function. If you need to catch errors in Lua, you can use the pcall function. Every value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain special operations.

You can change several aspects of the behavior of operations over a value by setting specific fields in its metatable.

If it finds one, Lua calls this function to perform the addition. We call the keys in a metatable events and the values metamethods. In the previous example, the event is "add" and the metamethod is the function that performs the addition.

You can query the metatable of any value through the getmetatable function. You can replace the metatable of tables through the setmetatable function. You cannot change the metatable of other types from Lua except by using the debug library ; you must use the C API for that.

Tables and userdata have individual metatables although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, and for all strings, etc.

A metatable controls how an object behaves in arithmetic operations, order comparisons, concatenation, length operation, and indexing. A metatable also can define a function to be called when a userdata is garbage collected. For each of these operations Lua associates a specific key called an event. When Lua performs one of these operations over a value, it checks whether this value has a metatable with the corresponding event.

If so, the value associated with that key the metamethod controls how Lua will perform the operation. Metatables control the operations listed next. Each operation is identified by its corresponding name. The semantics of these operations is better explained by a Lua function describing how the interpreter executes the operation. The code shown here in Lua is only illustrative; the real behavior is hard coded in the interpreter and it is much more efficient than this simulation.

All functions used in these descriptions rawget , tonumber , etc. In particular, to retrieve the metamethod of a given object, we use the expression. That is, the access to a metamethod does not invoke other metamethods, and the access to objects with no metatables does not fail it simply results in nil. The function getbinhandler below defines how Lua chooses a handler for a binary operation. First, Lua tries the first operand.

If its type does not define a handler for the operation, then Lua tries the second operand. The Length Operator for a description of the length of a table.

The function getcomphandler defines how Lua chooses a metamethod for comparison operators. A metamethod only is selected when both objects being compared have the same type and the same metamethod for the selected operation.

The indexing access table[key]. Besides metatables, objects of types thread, function, and userdata have another table associated with them, called their environment. Like metatables, environments are regular tables and multiple objects can share the same environment. Threads are created sharing the environment of the creating thread. Userdata and C functions are created sharing the environment of the creating C function.

Non-nested Lua functions created by loadfile , loadstring or load are created sharing the environment of the creating thread. Nested Lua functions are created sharing the environment of the creating Lua function.

Environments associated with userdata have no meaning for Lua. It is only a convenience feature for programmers to associate a table to a userdata. Environments associated with threads are called global environments. They are used as the default environment for threads and non-nested Lua functions created by the thread and can be directly accessed by C code see 3. The environment associated with a C functions can be directly accessed by C code see 3. It is used as the default environment for other C functions and userdata created by the function.

Environments associated with Lua functions are used to resolve all accesses to global variables within the function see 2. They are used as the default environment for nested Lua functions created by the function.

You can change the environment of a Lua function or the running thread by calling setfenv. You can get the environment of a Lua function or the running thread by calling getfenv.

To manipulate the environment of other objects userdata, C functions, other threads you must use the C API. Lua performs automatic memory management. This means that you have to worry neither about allocating memory for new objects nor about freeing it when the objects are no longer needed. Lua manages memory automatically by running a garbage collector from time to time to collect all dead objects that is, objects that are no longer accessible from Lua.

All memory used by Lua is subject to automatic management: tables, userdata, functions, threads, strings, etc. Lua implements an incremental mark-and-sweep collector. It uses two numbers to control its garbage-collection cycles: the garbage-collector pause and the garbage-collector step multiplier. Both use percentage points as units so that a value of means an internal value of 1. 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 mean the collector will not wait to start a new cycle. A value of means that the collector waits for the total memory in use to double before starting a new cycle. The step multiplier controls the relative speed of the collector relative to memory allocation. Larger values make the collector more aggressive but also increase the size of each incremental step. Values smaller than make the collector too slow and can result in the collector never finishing a cycle.

With these functions you can also control the collector directly e. Using the C API, you can set garbage-collector metamethods for userdata see 2. These metamethods are also called finalizers.

Instead, Lua puts them in a list. After the collection, Lua does the equivalent of the following function for each userdata in that list:. At the end of each garbage-collection cycle, the finalizers for userdata are called in reverse order of their creation, among those collected in that cycle. That is, the first finalizer to be called is the one associated with the userdata created last in the program. The userdata itself is freed only in the next garbage-collection cycle.

A weak table is a table whose elements are weak references. A weak reference is ignored by the garbage collector. In other words, if the only references to an object are weak references, then the garbage collector will collect this object. A weak table can have weak keys, weak values, or both. A table with weak keys allows the collection of its keys, but prevents the collection of its values. A table with both weak keys and weak values allows the collection of both keys and values.

In any case, if either the key or the value is collected, the whole pair is removed from the table. Otherwise, the weak behavior of the tables controlled by this metatable is undefined. Lua supports coroutines, also called collaborative multithreading. A coroutine in Lua represents an independent thread of execution. Unlike threads in multithread systems, however, a coroutine only suspends its execution by explicitly calling a yield function.

You create a coroutine with a call to coroutine. Its sole argument is a function that is the main function of the coroutine. The create function only creates a new coroutine and returns a handle to it an object of type thread ; it does not start the coroutine execution.

When you first call coroutine. Extra arguments passed to coroutine. After the coroutine starts running, it runs until it terminates or yields.

A coroutine can terminate its execution in two ways: normally, when its main function returns explicitly or implicitly, after the last instruction ; and abnormally, if there is an unprotected error. In the first case, coroutine. In case of errors, coroutine. A coroutine yields by calling coroutine. When a coroutine yields, the corresponding coroutine. In the case of a yield, coroutine.

The next time you resume the same coroutine, it continues its execution from the point where it yielded, with the call to coroutine. Like coroutine. Any arguments passed to this function go as extra arguments to coroutine. Unlike coroutine. The Application Program Interface. The Auxiliary Library. Some of these functions provide essential services to the language e.

Currently, Lua has the following standard libraries:. Except for the basic and package libraries, each library provides all its functions as fields of a global table or as methods of its objects. These functions are declared in lualib. Although Lua has been designed as an extension language, to be embedded in a host C program, it is also frequently used as a stand-alone language. An interpreter for Lua as a stand-alone language, called simply lua , is provided with the standard distribution.

The stand-alone interpreter includes all standard libraries, including the debug library. Its usage is:. After handling its options, lua runs the given script , passing to it the given args as string arguments. When called without arguments,. If its format is filename , then lua executes the file. Otherwise, lua executes the string itself. All options are handled in order, except -i. For instance, an invocation like. Your prompt may be different. Before starting to run the script, lua collects all arguments in the command line in a global table called arg.

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 that is, the interpreter name plus the options go to negative indices. For instance, in the call. In interactive mode, if you write an incomplete statement, the interpreter waits for its completion by issuing a different prompt. See the next example:. The outer pair of quotes is for the shell, the inner pair is for Lua.

To allow the use of Lua as a script interpreter in Unix systems, the stand-alone interpreter skips the first line of a chunk if it starts with. Of course, the location of the Lua interpreter may be different in your machine. If lua is in your PATH , then. Here we list the incompatibilities that you may find when moving a program from Lua 5.

You can avoid most of the incompatibilities compiling Lua with appropriate options see file luaconf. However, all these compatibility options will be removed in the next version of Lua. The vararg system changed from the pseudo-argument arg with a table with the extra arguments to the vararg expression. There was a subtle change in the scope of the implicit variables of the for statement and for the repeat statement.

Function string. When string. Function table. Function loadlib was renamed package. Function math. Functions table. You can use a for loop with pairs or ipairs instead. This document is from Lua version 5.