Summary

Sets the metatable for a table

Prototype

t = setmetatable (t, metatable)

Description

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 (#)
  
  

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

-- 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

See Also ...

Lua functions

assert - Asserts that condition is not nil and not false
collectgarbage - Collects garbage
dofile - Executes a Lua file
error - Raises an error message
gcinfo - Returns amount of dynamic memory in use
getfenv - Returns the current environment table
getmetatable - Returns the metatable for the object
ipairs - Iterates over a numerically keyed table
load - Loads a chunk by calling a function repeatedly
loadfile - Loads a Lua file and parses it
loadlib - Loads a DLL (obsolete in Lua 5.1)
loadstring - Compiles a string of Lua code
module - Creates a Lua module
next - Returns next key / value pair in a table
pairs - Traverse all items in a table
pcall - Calls a function in protected mode
print - Prints its arguments
rawequal - Compares two values for equality without invoking metamethods
rawget - Gets the value of a table item without invoking metamethods
rawset - Sets the value of a table item without invoking metamethods
require - Loads a module
select - Returns items in a list
setfenv - Sets a function's environment
tonumber - Converts a string (of the given base) to a number
tostring - Converts its argument to a string
type - Returns the type of a variable
unpack - Unpacks a table into individual items
xpcall - Calls a function with a custom error handler

Topics

Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Scripting
Scripting callbacks - plugins

(Help topic: lua=setmetatable)