Lua: Metamethods
| Lua |
|---|
|
| Basics |
| Intermediate |
| Advanced |
|
| XLua |
| Add to this template |
|
Metamethods are special variables (generally functions) that are called during some table and other datatype operations. They are important because they define the behavior of a table when Lua would otherwise not know how to handle it in that case.
Although tables are not the only data structures that can have metatables, they are the only ones intended for programmers to change within Lua itself. Therefore, these lists will only make mention of their use on tables. It is important to note that a metamethod will not call other metamethods, but a single operation may cause more than one metamethod to be executed.
Metamethods should be "transparent" if applicable; that is, a given operation on tables should behave like it would with other datatypes.
Current Metamethods
As of Lua 5.1.4
Arithmetic
- __add (op1, op2): called during an attempt to perform addition (+) on a table. Must be a function.
- __sub (op1, op2): called during an attempt to perform subtraction (-) on a table. Must be a function.
- __mul (op1, op2): called during an attempt to perform multiplication (*) on a table. Must be a function.
- __div (op1, op2): called during an attempt to perform division (/) on a table. Must be a function.
- __mod (op1, op2): called during an attempt to perform modulus division (%) on a table. Must be a function.
- __pow (op1, op2): called during an attempt to perform exponentiation (^) on a table. Must be a function.
- __unm (op1): called during an attempt to negate (-) a table. Must be a function.
- __concat(op1, op2): called during an attempt to concatenate (..) a table. Must be a function.
Comparison
- __eq (op1, op2): called during an attempt to compare equal-to (==).
- __lt (op1, op2): called during an attempt to compare less-than (<). Greater-than also calls this metamethod, but with the operands reversed.
- __le (op1, op2): called during an attempt to compare less-than-or-equal-to (<=). Greater-than-or-equal-to also calls this metamethod, but with the operands reversed.
Indexing
- __index (table, key): called during an attempt to access a nonexistent index. May be a function, or another table to look in instead. Bypassed by the rawget function.
- __newindex (table, key, value): called during an attempt to write to a nonexistent index. Bypassed by the rawset function.
Other
- __tostring (table): called during an attempt to coerce the table into a string, such as by concatenating it with another string or by using the print function on it.
- __call (table): called during an attempt to call a table as if it were a function.
- __metatable (table): essentially "locks" and hides the metatable for a given table so it can't be changed; functions like setmetatable will return the value of this metamethod instead of the actual metatable.
- __gc (): called for userdata, instructs Lua as to how to release other resources the userdata may be using.
Future Metamethods
Note: these have not totally been confirmed for Lua 5.2, so whether or not they will be implemented is unknown
- __len (table): called during an attempt to use the length operator (#). Must be a function. Lua 5.2+
