setmetatable

t = setmetatable (t, metatable)

Sets the metatable for the nominated table. If metatable is nil, removes the metatable. If the original metatable has a "__metatable" entry an error is raised.

Returns the table.

Metatables let you add special entries that cause certain operations to behave in a different way. These operations are (each one starts with 2 underscore characters):

• __add - the + operation
• __sub - the - operation
• __mul - the * operation
• __div - the / operation
• __pow - the ^ (exponentiation) operation
• __unm - the unary minus operation
• __concat - the .. (concatenate) operation
• __eq - the == operation (a ~= b is the same as not (a == b))
• __lt - the < operation (a > b is the same as b < a)
• __le - the <= operation (a >= b is the same as b <= a)
• __index - called if an antry is not in the table - prototype is: function f (table, key)
• __newindex - called when adding an entry to the table - prototype is: function f (table, key, value)
• __call - called if you attempt to "call" the table
• __gc - called after garbage collection (userdata only)
• __mode - if it contains "k", keys are weak, if it contains "v", values are weak
• __metatable - if present metatable cannot be changed, and this is the error message
• __tostring - called to convert the argument to a string
• __len - the length operator (#)

If there is no __le metamethod, Lua tries the __lt metamethod, assuming that:

a <= b  is equivalent to:  not (b < a)

Examples:

-- define adding to the table
t = { age = 42, height = 102 }
m = { __add = function (tbl, n) return t.age + n end }
setmetatable (t, m)
print (t + 1)  --> 43

-- define calling the table
t = { age = 42, height = 102 }
m = { __call = function (t) table.foreach (t, print) end }
setmetatable (t, m)
t ()  -- "call" the table (this prints each entry)

-->

height 102
age 42