setmetatable
Lua function

setmetatable

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
  • __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
  • __newindex - called when adding an entry to the table
  • __call - called if you attempt to "call" the table
  • __gc - called after garbage collection
  • __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 table to a string


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


See Also ...

Topics

DOC_lua_base Lua base functions
DOC_lua_bc Lua bc (big number) functions
DOC_lua_bit Lua bit manipulation functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_io Lua io functions
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua_rex Lua PCRE regular expression functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions
DOC_lua_tables Lua table functions
DOC_lua_utils Lua utilities
DOC_scripting Scripting

Lua functions

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

(Help topic: lua=setmetatable)

DOC_contents Documentation contents page