# Lua Metatable Events #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
--- # Metatable Events
--- A listing of all the 'special' keys in a metatable, and the metamethods which they perform.

--[[

(1) __index

Control 'prototype' inheritance. When accessing "myTable[key]" and the key does not appear in the table, but the
metatable has an __index property:

- if the value is a function, the function is called, passing in the table and the key; the return value of that
function is returned as the result.

- if the value is another table, the value of the key in that table is asked for and returned (and if it does not
exist in that table, but that table's metatable has an __index property, then it continues on up.)

- Use "rawget(myTable,key)" to skip this metamethod.

(2) __newindex

Control property assignment. When calling "myTable[key] = value", if the metatable has a __newindex key pointing to a
function, call that function, passing it the table, key, and value.

- Use "rawset(myTable,key,value)" to skip this metamethod.
- if the __newindex function does not set the key on the table(using rawset) then the key/value pair is not added
to myTable.

(3) __mode

Control weak references. A string value with one or both of the characters 'k' and 'v' which specifies that the keys
and/or values in the table are weak references.

(4) __call

Treat a table like a function. When a table is followed by parenthesis such as "myTable('foo')" and the metatable has a
__call key pointing to a function, that function is invoked (passing the table as the first argument, followd by any
specified arguments) and the return value is returned.

(5) __metatable

Hide the metatable. When "getmetatable(myTable)" is called, if the metatable for myTable has a __metatable key, the
value of that key is returned instead of the actual metatable.

(6) __tostring

Control string representation. When the builtin "tostring(myTable)" function is called, if the metatable for myTable has
a __tostring property set to a function, that function is invoked(passing myTable to it) and the return value is used as
the string representation.

(7) __len

Control table length. When the table length is requested using the length operator('#'), if the metatable for myTable
has a __len key pointing to a function, that function is invoked(passing myTable to it) and the return value used as the
value of "#myTable".

(8) __gc

Userdata finalizer code, when usedata is set to be garbage collected, if the metatable has a __gc field pointing to a
function, that function is first invoked, passing the userdata to it. The __gc metamethod is not called for tables.

--]]


--- Mathematic Operators

--[[

__unm : Unary minus. When writing "-myTable", if the metatable has a __unm key pointing to a function, that
function, that function is invoked(passing the table), and the return value used as the value of "-myTable".

__add : Addition. When writing "myTable + object" or "object + myTable", if myTable's metatable has an __add key
pointing to a function, that function is invoked(passing the left and right operands in order) and the return value
used.
if both operands are tables, the left table is checked before the right table for the presence of an _add metaevent.

__sub : Subtraction. Invoked similar to addition, using the "-" operator.

__mul : Multiplication. Invoked similar to addtion, using the "*" operator.

__div : Division. Invoked similar to addtion, using the "/" operator.

__idiv : (Lua 5.3) Floor division, division with rounding down to nearest integer. "//" operator.

__mod : Modulo. Invoked similar to addition, using the "%" operator.

__pow : Involution. Invoked similar to addition, using the "^" operator.

__concat : Concatenation. Invoked similar to addition, using the '..' operator.

--]]


--- Bitwise Operator
--- Lua 5.3 introduced the ability to use true integers, and with it bitwise operations. These operations are invoked
--- similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a
--- value coercible to an integer.

--[[

__band : the bitwise AND & operation
__bor : the bitwise OR | operation
__bxor : the bitwise exclusive OR (binary ~) operation
__bnot : the bitwise NOT(unary ~) operation
__bshl : the bitwise left shift(<<) operation
__bshr : the bitwise right shift(>>) operation

--]]


--- Equivlence Comparison Operators

--- __eq : Check for equality. This method is invoked when "myTable1 == myTable2" is evaluated, but only if both tables
--- have the exact same metamethod for __eq.
-- For example, see the following code:

tla = {}
tlb = {}
t2 = {}
mt1 = { __eq = function(o1, o2)
return 'whee'
end }
mt2 = { __eq = function(o1, o2)
return "whee"
end }

setmetatable(tla, mt1)
setmetatable(tlb, mt1)
setmetatable(t2, mt2)

print(tla == tlb) --> true
print(tla == t2) --> false

-- If the function returns nil or false, the result of the comparison is false; otherwise, the result is true.

-- If t1 and t2 are referencing the same table, the __eq method is not invoked for t1 == t2

function foo(o1, o2)
print('__eq call')
return false
end

t1 = {}
setmetatable(t1, { __eq = foo })

t2 = t1
print(t1 == t2) --> true

-- string '__eq call' not printed(and comparison result is true, not like the return value of foo(...)), so no foo(...) call here

t3 = {}
setmetatable(t3, { __eq = foo })

if t1 == t3 then
-- __eq call
-- foo is called
end

--- __lt : Check for less-than. Similar to equality, using the '<' operator.
--- Greater-than is evaluated by reversing the order of the operands passed to the __lt function.

-- a > b == b < a

--- __le Check for less-than-or-equal. Similar to equality, using the '<=' operator.
--- Greater-than-or-equal is evaluated by reversing the order of the operands passed to the __le function.

-- a>=b == b<=a

--- end.