Metatables

The metatables for Strings and all ROBLOX types are locked; however, in normal Lua (not RBX.lua) you can set the metatables of these objects using the debug library.[1]

What is a Metatable?

Metatables allow tables to become more powerful than before. They are attached to data and contain values called Metamethods. Metamethods are fired when a certain action is used with the datum that it is attached to. You may think that if you have code like this:

local list = {1, 2} print(list[3])

The code will search through the list for the third index in list, realize it's not there, and return nil. That's totally wrong. What really happens is the code will search through the list for the third index, realize it's not there, and then try to see if there's a metatable attached to the table, returning nil if there isn't one.

Manipulating Metatables

setmetatable() and getmetatable()

The two primary functions for giving and finding a table's metatable, are setmetatable() and getmetatable().

local x = {} local metaTable = {} -- metaTables are tables, too! setmetatable(x, metaTable) -- Give x a metatable called metaTable! print(getmetatable(x)) --> table: [hexadecimal memory address]

The setmetatable() function also returns the table that you're setting the metatable of, so these two scripts do the same thing:

local x = {} setmetatable(x, {})

local x = setmetatable({}, {})

Metamethods

Metamethods are the functions that are stored inside a metatable. They can go from calling a table, to adding a table, to even dividing tables as well. Here's a list of metamethods that can be used:

• __index(table, index) — Fires when table[index] is indexed, where table[index] is nil.
• __newindex(table, index, value) — Fires when table[index] tries to be set (table[index] = value), where table[index] is nil.
• __call(table, ...) — Fires when the table is called like a function, ... is the arguments that were passed.
• __concat(table, value) — Fires when the .. concatenation operator is used on the table.
• __unm(table) — Fires when the unary – operator is used on the table.
• __add(table, value) — The + addition operator.
• __sub(table, value) — The – subtraction operator.
• __mul(table, value) — The * mulitplication operator.
• __div(table, value) — The / division operator.
• __mod(table, value) — The % modulus operator.
• __pow(table, value) — The ^ exponentiation operator.
• __tostring() — Fired when tostring is called on the table.
• __metatable — if present, locks the metatable so getmetatable will return this instead of the metatable and setmetatable will error. Non-function value.
• __eq(table, value) — The == equal to operator˚
• __lt(table, value) — The < less than operator˚; NOTE: Using the >= greater than or equal to operator will invoke this metamethod and return the opposite of what this returns, as greater than or equal to is the same as not less than.
• __le(table, value) — The <= operator˚; NOTE: Using the > greater than operator will invoke this metamethod and return the opposite of what this returns, as greater than is the same as not less than or equal to.
• __mode — Used in Weak Tables, declaring whether the keys and/or values of a table are weak.
• __gc(table) — Fired when the table is garbage-collected.
• __len(table) — Fired when the # length operator is used on the Object. NOTE: Only userdatas actually respect the __len() metamethod in Lua 5.1

˚ Requires two values with the same metatable; does not work with a table and another random value.

Using Metatables

There are many ways to use metatables, for example the __unm metamethod (to make a table negative):

Example

{{{1}}}

Here's an interesting way to declare things using __index:

Example

{{{1}}}

__index was fired when x was indexed in the table and not found. Lua then searched through the __index table for an index called x, and, finding one, returned that.

Now you can easily do that with a simple function, but there's a lot more where that came from. Take this for example: local table = {10, 20, 30} print(table(5))

Now, obviously you can't call a table. That's just crazy, but (surprise, surprise!) with metatables you can.

Example

{{{1}}}

You can do a lot more as well, such as adding tables!

Example

{{{1}}}

If the two tables have two different __add functions, then Lua will go to table1 first and if it doesn't have an __add function, then it'll go to the second one. That means that you really only have to set the metatable of Table1 or Table2, but it's nicer and more readable to set the metatable of both.

Here is one last example breaking away from using separate variables when it isn't necessary.

Example

{{{1}}}

Use Cases

Now, I am well aware that you can do all of these as a simple function yourself, but there's a lot more than what you think it can do. Let's try a simple program that will memorize a number when a possibly laggy math problem is put into it.

For this one we will be using the __index metamethod just to make it simple:

Example

{{{1}}}

Rawset, Rawget, Rawequal

When playing with metatables, you may run into some problems. What happens if you need to use the __index metamethod to create new values in a table, but that table's metatable also has a __newindex metamethod in it? You'll want to use the Lua built-in function rawset to set the value without invoking any metamethods. Take the following code as an example of what happens if you don't use this functions.

Example

{{{1}}}

Now why would that cause a stack overflow? Stack overflows happen when you try to call a function from itself too many times, but what would cause that to happen? In the __index function, we set self[i] to a value, so when it gets to the next line, self[i] should exist, so it won't call the __index metamethod, right?

The problem is that __newindex doesn't let us set the value. Its presence stops values from being added to the table with the standard t[i] = v method. In order to get past this, you use the rawset function.

Example

{{{1}}}

See Also

• Lua 5.1 Reference Manual: Metatables
• Programming in Lua: Metatables and Metamethods