lua_open and persists until a call to lua_close, or the end of the embedding program.
If necessary, the host programmer can create multiple independent global environments, and freely switch between them. The global environment can be manipulated by Lua code or by the embedding program, which can read and write global variables using API functions from the library that implements Lua.
Global variables in Lua do not need to be declared. Any variable is assumed to be global unless explicitly declared local. Before the first assignment, the value of a global variable is nil. A table is used to keep all global names and values.
The unit of execution of Lua is called a chunk. A chunk is simply a sequence of statements, which are executed sequentially. Each statement can be optionally followed by a semicolon.
A chunk may be stored in a file or in a string inside the host program. When a chunk is executed, first it is pre-compiled into bytecodes for a virtual machine, and then the statements are executed in sequential order, by simulating the virtual machine. All modifications a chunk effects on the global environment persist after the chunk ends.
Chunks may also be pre-compiled into binary form and stored in files. Text files with chunks and their binary pre-compiled forms are interchangeable. Lua automatically detects the file type and acts accordingly.
There are six basic types in Lua: nil, number, string, function, userdata, and
table. Nil is the type of the value nil, whose main property is to be different from any other value.
Number represents real (double-precision floating-point) numbers, while string has the usual meaning. Lua is 8-bit
clean, and so strings may contain any 8-bit character, including embedded zeros ('\0') The type function
returns a string describing the type of a given value.
Functions are considered first-class values in Lua. This means that functions can be stored in variables, passed as
arguments to other functions, and returned as results. Lua can call (and manipulate) functions written in Lua and functions written
in C. The two kinds of functions can be distinguished by their tags: all Lua functions have the same tag, and all C functions
have the same tag, which is different from the tag of Lua functions. The tag function returns the tag of a given value.
The type userdata is provided to allow arbitrary C pointers to be stored in Lua variables. This type corresponds to a
void* and has no pre-defined operations in Lua, except assignment and equality test. However, by using
tag methods, the programmer can define operations for userdata values.
The type table implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value
(except nil). Therefore, this type may be used not only to represent ordinary arrays, but also symbol tables, sets, records,
graphs, trees, etc. Tables are the main data structuring mechanism in Lua. To represent records, Lua uses the field name as an
index. The language supports this representation by providing a.name as syntactic sugar for a["name"].
Tables may also carry methods: Because functions are first class values, table fields may contain functions. The form
t:f(x) is syntactic sugar for t.f(t,x), which calls the method f from the table
t passing the table itself as the first parameter.
Note that tables are objects, and not values. Variables do not contain tables, only references to them. Assignment, parameter passing, and returns always manipulate references to tables, and do not imply any kind of copy. Moreover, tables must be explicitly created before used.
Each of the types nil, number, and string has a different tag. All values of each of these types have the
same pre-defined tag. As explained above, values of type function can have two different tags, depending on whether they
are Lua functions or C functions. Finally, values of type userdata and table can have variable tags,
assigned by the programmer. The tag function returns the tag of a given value. User tags are created with the function
newtag. The settag function is used to change the tag of a table. The tag of userdata values can only be
set from C. Tags are mainly used to select tag methods when some events occur. Tag methods are the main mechanism for
extending the semantics of Lua.
and break do else elseif
end for function if in
local nil not or repeat
return then until while
Lua is a case-sensitive language: and is a reserved word, but And and ánd (if the locale permits) are two
different, valid identifiers. As a convention, identifiers starting with underscore followed by uppercase letters
(such as _INPUT) are reserved for internal variables.
The following strings denote other tokens:
~= <= >= < > == = + - * /
( ) { } [ ] ; , . .. ...
Literal strings can be delimited by matching single or double quotes, and can contain the C-like escape sequences
`\a' (bell), `\b' (backspace), `\f' (form feed), `\n' (newline),
`\r' (carriage return), `\t' (horizontal tab), `\v' (vertical tab),
`\\' (backslash), `\"' (double quote), `\'' (single quote), and
`\newline' (that is, a backslash followed by a real newline, which results in a newline in the string).
A character in a string may also be specified by its numerical value, through the escape sequence `\ddd',
where ddd is a sequence of up to three decimal digits. Strings in Lua may contain any 8-bit value, including
embedded zeros, which can be specified as `\000'.
Literal strings can also be delimited by matching [[ ... ]]. Literals in this bracketed form may run for
several lines, may contain nested [[ ... ]] pairs, and do not interpret escape sequences. This form is
specially convenient for writing strings that contain program pieces or other quoted strings. As an example, in a system using ASCII,
the following three literals are equivalent:
1) "alo\n123\""
2) '\97lo\10\04923"'
3) [[alo
123"]]
Comments start anywhere outside a string with a double hyphen (--) and run until the end of the line.
Moreover, the first line of a chunk is skipped if it starts with #. This facility allows the use of Lua as a script
interpreter in Unix systems.
Numerical constants may be written with an optional decimal part and an optional decimal exponent. Examples of valid numerical constants are
3 3.0 3.1416 314.16e-2 0.31416E1
format function.
Explicit blocks are useful to control the scope of local variables. Explicit blocks are also sometimes used to add a return or break statement in the middle of another block.
i = 3
i, a[i] = 4, 20
sets a[3] to 20, but does not affect a[4] because the i in a[i] is evaluated
before it is assigned 4. Multiple assignment can be used to exchange two values, as in
x, y = y, x
The two lists in a multiple assignment may have different lengths. Before the assignment, the list of values is adjusted to the length of the list of variables.
A single name can denote a global variable, a local variable, or a formal parameter.
Square brackets are used to index a table. The syntax var.NAME is just syntactic sugar for var["NAME"].
The meaning of assignments and evaluations of global variables and indexed variables can be changed by tag methods. Actually, an
assignment x = val, where x is a global variable, is equivalent to a call setglobal("x", val)
and an assignment t[i] = val is equivalent to settable_event(t,i,val). (setglobal is in the
basic library; settable_event is used for explanatory purposes only).
while exp1 do block end
repeat block until exp1
if exp1 then block {elseif exp1 then block} [else block] end
The condition expression exp1 of a control structure may return any value. All values different from nil are
considered true; only nil is considered false. The return statement is used to return values from a function or from a chunk. Because functions or chunks may return more than one value, the syntax for the return statement is
return [explist1]
The break statement can be used to terminate the execution of a loop, skipping to the next statement after the loop:
break
A break ends the innermost enclosing loop (while, repeat, or for).
For syntactic reasons, return and break statements can only be written as the last statements of a block.
If it is really necessary to return or break in the middle of a block, an explicit inner block can used, as in the
idiom `do return end', because now return is last statement in the inner block.
for name = exp1 , exp1 [, exp1] do block end
A for statement like
for var = e1 ,e2, e3 do block end
is equivalent to the code:
do
local var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3)
if not (var and _limit and _step) then error() end
while (_step>0 and var<=_limit) or (_step<=0 and var>=_limit) do
block
var = var+_step
end
end
Note the following:
_limit and _step are invisible variables. The names are here for explanatory purposes only.
var inside the block.
var is local to the statement; you cannot use its value after the for ends.
The table for statement traverses all pairs (index,value) of a given table. It has the following syntax:
for name , name in exp1 do block end
A for statement like
for index, value in exp do block end
is equivalent to the code:
do
local _t = exp
local index, value = next(t, nil)
while index do
block
index, value = next(t, index)
end
end
Note the following:
_t is an invisible variable. The name is here for explanatory purposes only.
index inside the block.
_t during the traversal.
index and value are local to the statement; you cannot use their values after the
for ends.
index or value, assign
them to other variables before breaking.
local declist [init]
If present, an initial assignment has the same semantics of a multiple assignment. Otherwise, all variables are initialized with
nil. A chunk is also a block, and so local variables can be declared outside any explicit block.
The scope of local variables begins after the declaration and lasts until the end of the block. Thus, the code local
print=print creates a local variable called print whose initial value is that of the global variable of
the same name.
nil
number
literal
var
upvalue
function
functioncall
tableconstructor
An access to a global variable x is equivalent to a call getglobal("x") and an access to an indexed
variable t[i] is equivalent to a call gettable_event(t,i). (getglobal is in the basic
library; gettable_event is used for explanatory purposes only).
The non-terminal exp1 is used to indicate that the values returned by an expression must be adjusted to one single value.
+ (addition), - (subtraction), *
(multiplication), / (division), and ^ (exponentiation); and unary - (negation). If the
operands are numbers, or strings that can be converted to numbers, then all operations except exponentiation have the usual
meaning. Otherwise, an appropriate tag method is called. An exponentiation always calls a tag method. The standard mathematical
library redefines this method for numbers, giving the expected meaning to exponentiation.
== ~= < > <= >=
These operators return nil as false and a value different from nil as true.
Equality (==) first compares the tags of its operands. If they are different, then the result is nil.
Otherwise, their values are compared. Numbers and strings are compared in the usual way. Tables, userdata, and functions are
compared by reference, that is, two tables are considered equal only if they are the same table. The operator
~= is exactly the negation of equality (==).
The conversion rules (explained later) do not apply to equality comparisons. Thus, "0"==0 evaluates to
false, and t[0] and t["0"] denote different entries in a table.
The order operators work as follows. If both arguments are numbers, then they are compared as such. Otherwise, if both arguments are strings, then their values are compared using lexicographical order. Otherwise, the ``lt'' tag method is called.
and or not
Like the control structures, all logical operators consider nil as false and anything else as true.
The conjunction operator and returns nil if its first argument is nil; otherwise, it returns its second
argument. The disjunction operator or returns its first argument if it is different from nil; otherwise, it
returns its second argument. Both and and or use short-cut evaluation, that is, the second operand is
evaluated only if necessary.
There are two useful Lua idioms that use logical operators. The first idiom is
x = x or v
which is equivalent to
if x == nil then x = v end
This idiom sets x to a default value v when x is not set. The second idiom is
x = a and b or c
which should be read as x = (a and b) or c. This idiom is equivalent to
if a then x = b else x = c end
provided that b is not nil.
and or
< > <= >= ~= ==
..
+ -
* /
not - (unary)
^
All binary operators are left associative, except for ^ (exponentiation), which is right associative. The pre-compiler
may rearrange the order of evaluation of associative operators (such as .. or +), as long as
these optimizations do not change normal results. However, these optimizations may change some results if you define non-associative
tag methods for these operators.
tableconstructor = `{' fieldlist `}'
fieldlist = lfieldlist | ffieldlist | lfieldlist `;' ffieldlist | ffieldlist `;' lfieldlist
lfieldlist = [lfieldlist1]
ffieldlist = [ffieldlist1]
The form lfieldlist1 is used to initialize lists:
lfieldlist1 = exp {`,' exp} [`,']
The expressions in the list are assigned to consecutive numerical indices, starting with 1. For example,
a = {"v1", "v2", 34}
is equivalent to
do
local temp = {}
temp[1] = "v1"
temp[2] = "v2"
temp[3] = 34
a = temp
end
The form ffieldlist1 initializes other fields in a table:
ffieldlist1 = ffield {`,' ffield} [`,']
ffield = `[' exp `]' `=' exp | name `=' exp
For example,
a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c}
is equivalent to
do
local temp = {}
temp[f(k)] = g(y)
temp.x = 1 -- or temp["x"] = 1
temp.y = 3 -- or temp["y"] = 3
temp[0] = b+c
a = temp
end
An expression like {x = 1, y = 4} is in fact syntactic sugar for {["x"] = 1, ["y"] = 4}. Both forms may have an optional trailing comma, and can be used in the same constructor separated by a semi-colon. For example, all forms below are correct.
x = {;}
x = {"a", "b",}
x = {type="list"; "a", "b"}
x = {f(0), f(1), f(2),; n=3,}
varorfunc (args)
First, varorfunc is evaluated. If its value has type function, then this function is called, with the given
arguments. Otherwise, the ``function'' tag method is called, having as first parameter the value of varorfunc, and then
the original call arguments. The form
varorfunc:name (args)
can be used to call ``methods''. A call v:name(...) is syntactic sugar for v.name(v, ...), except that
v is evaluated only once. args can be:
( [explist1] )
tableconstructor
literal
All argument expressions are evaluated before the call. A call of the form f{...} is syntactic sugar for
f({...}), that is, the argument list is a single new table. A call of the form f'...'
(or f"..." or f[[...]]) is syntactic sugar for f('...'), that is, the argument list is a
single literal string. Because a function can return any number of results, the number of results must be adjusted before they are used. If the function is called as a statement, then its return list is adjusted to 0, thus discarding all returned values. If the function is called in a place that needs a single value (syntactically denoted by the non-terminal exp1), then its return list is adjusted to 1, thus discarding all returned values but the first one. If the function is called in a place that can hold many values (syntactically denoted by the non-terminal exp), then no adjustment is made. The only places that can hold many values is the last (or the only) expression in an assignment, in an argument list, or in the return statement. Here are some examples:
f() -- adjusted to 0 results
g(f(), x) -- f() is adjusted to 1 result
g(x, f()) -- g gets x plus all values returned by f()
a,b,c = f(), x -- f() is adjusted to 1 result (and c gets nil)
a,b,c = x, f() -- f() is adjusted to 2
a,b,c = f() -- f() is adjusted to 3
return f() -- returns all values returned by f()
return x,y,f() -- returns a, b, and all values returned by f()
function = function `(' [parmlist1] `)' block end
function funcname `(' [parmlist1] `)' block end
funcname = name | name `.' name | name `:' name
The statement
function f () ... end
is just syntactic sugar for
f = function () ... end
and the statement
function v.f () ... end
is syntactic sugar for
v.f = function () ... end
A function definition is an executable expression, whose value has type function. When Lua pre-compiles a chunk, all its function bodies are pre-compiled too. Then, whenever Lua executes the function definition, its upvalues are fixed. and the function is instantiated (or closed). This function instance (or closure) is the final value of the expression. Different instances of the same function may have different upvalues.
Parameters act as local variables, initialized with the argument values:
parmlist1 = ...
parmlist1 = name {, name} [, ...]
When a function is called, the list of arguments is adjusted to the length of the list of parameters, unless the function is a
vararg function, which is indicated by three dots (`...') at the end of its parameter list. A vararg function
does not adjust its argument list; instead, it collects all extra arguments into an implicit parameter, called arg.
The value of arg is a table, with a field n whose value is the number of extra arguments, and the
extra arguments at positions 1, 2, ..., n. As an example, consider the following definitions:
function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end
Then, we have the following mapping from arguments to parameters:
CALL PARAMETERS
f(3) a=3, b=nil
f(3, 4) a=3, b=4
f(3, 4, 5) a=3, b=4
f(r(), 10) a=1, b=10
f(r()) a=1, b=2
g(3) a=3, b=nil, arg={n=0}
g(3, 4) a=3, b=4, arg={n=0}
g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2}
g(5, r()) a=5, b=1, arg={2, 3; n=2}
Results are returned using the return statement. If control reaches the end of a function without encountering a return statement, then the function returns with no results.
The syntax
funcname = name : name
is used for defining methods, that is, functions that have an implicit extra parameter self. The statement
function v:f (...) ... end
is just syntactic sugar for
v.f = function (self, ...) ... end
Note that the function gets an extra formal parameter called self.
upvalue = % name
An upvalue is somewhat similar to a variable expression, but whose value is frozen when the function wherein it appears is instantiated. The name used in an upvalue may be the name of any variable visible at the point where the function is defined, that is, global variables and local variables from the immediately enclosing function. Note that when the upvalue is a table, only the reference to that table (which is the value of the upvalue) is frozen; the table contents can be changed at will. Using table values as upvalues is a technique for having writable but private state attached to functions.
Here are some examples:
a,b,c = 1,2,3 -- global variables
local d
function f (x)
local b = {} -- x and b are local to f; b shadows the global b
local g = function (a)
local y -- a and y are local to g
p = a -- OK, access local `a'
p = c -- OK, access global `c'
p = b -- ERROR: cannot access a variable in outer scope
p = %b -- OK, access frozen value of `b' (local to `f')
%b = 3 -- ERROR: cannot change an upvalue
%b.x = 3 -- OK, change the table contents
p = %c -- OK, access frozen value of global `c'
p = %y -- ERROR: `y' is not visible where `g' is defined
p = %d -- ERROR: `d' is not visible where `g' is defined
end -- g
end -- f
_ERRORMESSAGE is called
(provided it is different from nil), and then the corresponding function from the library (lua_dofile,
lua_dostring, lua_dobuffer, or lua_call) is terminated, returning an error condition.
Memory allocation errors are an exception to the previous rule. When memory allocation fails, Lua may not be able to execute the
_ERRORMESSAGE function. So, for this kind of error, Lua does not call the _ERRORMESSAGE function;
instead, the corresponding function from the library returns immediately with a special error code (LUA_ERRMEM).
This and other error codes are defined in lua.h.
The only argument to _ERRORMESSAGE is a string describing the error. The default definition for this function calls
_ALERT, which prints the message to stderr. The standard I/O library redefines _ERRORMESSAGE
and uses the debug facilities to print some extra information, such as a call stack traceback.
Lua code can explicitly generate an error by calling the function error. Lua code can ``catch'' an error using the
function call.
The tag method called for any specific event is selected according to the tag of the values involved in the event. The function
settagmethod changes the tag method associated with a given pair (tag, event). Its first parameter is the tag,
the second parameter is the event name (a string; see below), and the third parameter is the new method (a function), or nil
to restore the default behavior for the pair. The settagmethod function returns the previous tag method for that pair.
A companion function gettagmethod receives a tag and an event name and returns the current method associated with the pair.
Tag methods are called in the following events, identified by the given names. The semantics of tag methods is better explained by a Lua function describing the behavior of the interpreter at each event. This function not only shows when a tag method is called, but also its arguments, its results, and the default behavior. The code shown here is only 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 are described in the lua function reference.
+ operation is applied to non-numerical operands.
The function getbinmethod below defines how Lua chooses a tag method
for a binary operation.
First, Lua tries the first operand.
If its tag does not define a tag method for the operation,
then Lua tries the second operand.
If it also fails, then it gets a tag method from tag 0.
function getbinmethod (op1, op2, event)
return gettagmethod(tag(op1), event) or
gettagmethod(tag(op2), event) or
gettagmethod(0, event)
end
Using this function,
the tag method for the ``add'' event is
function add_event (op1, op2)
local o1, o2 = tonumber(op1), tonumber(op2)
if o1 and o2 then -- both operands are numeric
return o1+o2 -- '+' here is the primitive 'add'
else -- at least one of the operands is not numeric
local tm = getbinmethod(op1, op2, "add")
if tm then
-- call the method with both operands and an extra
-- argument with the event name
return tm(op1, op2, "add")
else -- no tag method available: default behavior
error("unexpected type at arithmetic operation")
end
end
end
- operation is applied to non-numerical operands.
Behavior similar to the ``add'' event.
* operation is applied to non-numerical operands.
Behavior similar to the ``add'' event.
/ operation is applied to non-numerical operands.
Behavior similar to the ``add'' event.
^ operation (exponentiation) is applied,
even for numerical operands.
function pow_event (op1, op2)
local tm = getbinmethod(op1, op2, "pow")
if tm then
-- call the method with both operands and an extra
-- argument with the event name
return tm(op1, op2, "pow")
else -- no tag method available: default behavior
error("unexpected type at arithmetic operation")
end
end
- operation is applied to a non-numerical operand.
function unm_event (op)
local o = tonumber(op)
if o then -- operand is numeric
return -o -- '-' here is the primitive 'unm'
else -- the operand is not numeric.
-- Try to get a tag method from the operand;
-- if it does not have one, try a "global" one (tag 0)
local tm = gettagmethod(tag(op), "unm") or
gettagmethod(0, "unm")
if tm then
-- call the method with the operand, nil, and an extra
-- argument with the event name
return tm(op, nil, "unm")
else -- no tag method available: default behavior
error("unexpected type at arithmetic operation")
end
end
end
< operator.
function lt_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 < op2 -- numeric comparison
elseif type(op1) == "string" and type(op2) == "string" then
return op1 < op2 -- lexicographic comparison
else
local tm = getbinmethod(op1, op2, "lt")
if tm then
return tm(op1, op2, "lt")
else
error("unexpected type at comparison");
end
end
end
The other order operators use this tag method according to the
usual equivalences:
a>b <=> b<a
a<=b <=> not (b<a)
a>=b <=> not (a<b)
function concat_event (op1, op2)
if (type(op1) == "string" or type(op1) == "number") and
(type(op2) == "string" or type(op2) == "number") then
return op1..op2 -- primitive string concatenation
else
local tm = getbinmethod(op1, op2, "concat")
if tm then
return tm(op1, op2, "concat")
else
error("unexpected type for concatenation")
end
end
end
newtag.
Note that
the tag is that of the current value of the global variable.
function getglobal (varname)
-- access the table of globals
local value = rawget(globals(), varname)
local tm = gettagmethod(tag(value), "getglobal")
if not tm then
return value
else
return tm(varname, value)
end
end
The function getglobal is defined in the basic library (see Section 6.1).
function setglobal (varname, newvalue)
local oldvalue = rawget(globals(), varname)
local tm = gettagmethod(tag(oldvalue), "setglobal")
if not tm then
rawset(globals(), varname, newvalue)
else
tm(varname, oldvalue, newvalue)
end
end
The function setglobal is defined in the basic library (see Section 6.1).
function gettable_event (table, index)
local tm = gettagmethod(tag(table), "gettable")
if tm then
return tm(table, index)
elseif type(table) ~= "table" then
error("indexed expression not a table");
else
local v = rawget(table, index)
tm = gettagmethod(tag(table), "index")
if v == nil and tm then
return tm(table, index)
else
return v
end
end
end
function settable_event (table, index, value)
local tm = gettagmethod(tag(table), "settable")
if tm then
tm(table, index, value)
elseif type(table) ~= "table" then
error("indexed expression not a table")
else
rawset(table, index, value)
end
end
function function_event (func, ...)
if type(func) == "function" then
return call(func, arg)
else
local tm = gettagmethod(tag(func), "function")
if tm then
for i=arg.n,1,-1 do
arg[i+1] = arg[i]
end
arg.n = arg.n+1
arg[1] = func
return call(tm, arg)
else
error("call expression not a function")
end
end
end
function gc_event (obj)
local tm = gettagmethod(tag(obj), "gc")
if tm then
tm(obj)
end
end
In a garbage-collection cycle,
the tag methods for userdata are called in reverse order of tag creation,
that is, the first tag methods to be called are those associated
with the last tag created in the program.
Moreover, at the end of the cycle,
Lua does the equivalent of the call gc_event(nil).