Lua: Metamethods

Lua
Basics
About Syntax Datatypes Hello World
Intermediate
Using Metatables Writing files Basic Object-orientation example Vararg statements MMF Interface
Advanced
Iterators How to take over Eastern Europe Basic Object engine
XLua
MMF Interface WIN Interface OpenGL C Libraries
Add to this template

This article assumes the use of Lua 5.1. Information may not be accurate or may need revision if you are using a different version.

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. An operation between two tables may succeed even if one of the tables doesn't have the relevant metamethod, as Lua will use the metamethod of the table on the left side of the operand to decide the behavior; if that fails, it will try the one on the right—only when both attempts fail will it generate an error. In the case of conflicting metamethods, the one on the left will win out.

Although tables are not the only data structures that can have metatables (in fact all of them can, even nil), they are the only ones that can have metatables added or removed without using the debug library. However, though it is possible to modify, for example, the strings' metatable without the debug library, some behavior such as concatenation is hardcoded and cannot be overridden.

Whenever possible, overridden operators should have meaning that is predictable or similar to what is normally understood for that operator. Therefore, you may consider using + for field-wise addition rather than concatenation, using .. for the latter operation.

Metamethods are also known as metafields, which is a more accurate term for the few that are in fact just normal values and not functions.

Current Metamethods

As of Lua 5.1.4, also includes parameters passed to the metamethod

Name	Kind	Arguments/Value	Triggered by	Notes
__add	Method	(self, right)	self + right
__sub	Method	(self, right)	self - right
__mul	Method	(self, right)	self * right
__div	Method	(self, right)	self / right
__mod	Method	(self, right)	self % right
__pow	Method	(self, right)	self * right
__unm	Method	(self)	-self
__concat	Method	(self, right)	self .. right
__eq	Method	(self, right)	self == right	1
__lt	Method	(self, right)	self < right	2
__le	Method	(self, right)	self <= right	3
__index	Method	(self, key)	self[key]	4, 5
__newindex	Method	(self, key, value)	self[key] = value	4, 6
__tostring	Method	(self)	tostring(self)
__call	Method	(self, ...)	self(...)	7
__metatable	Any value	[returned value]	getmetatable(self)
__mode	String	"k", "v", or "kv"
__gc	Method	(self)	[when collectible]	8
__len	Method	(self)	#self	9
__pairs	Method	(self)	pairs(self)	9
__ipairs	Method	(self)	ipairs(self)	9

1. Operands must be the same type and share the same __eq metamethod. Bypassable by rawequal()
2. Also called by self > right, but with the operands flipped. Operands must be same type
3. Also called by self >= right, but with the operands flipped. Operands must be same type
4. Triggered only if the specified key does not exist
5. Bypassable by rawget()
6. Bypassable by rawset()
7. __call may have extra parameters after the self reference
8. Userdata only, used to free resources allocated by the userdata before collection
9. Lua 5.2 required

Further details of __metatable and __mode are specified on the Metatables and Weak Tables pages, respectively.