Changing what a table means
By default, a table does very little. You cannot add two tables, compare them by contents, print them meaningfully or call them, and reading a missing key quietly gives nil. That is a deliberate blank slate. A metatable lets you fill it in: you attach a second table to the first, and fields in it, named with two underscores such as __add or __index, tell Lua what to do when the first table meets an operator or a missing key.
With this one mechanism, Lua programs build vectors and complex numbers that support +, tables with default values, read-only constants, tables that report typos, proxies that log every access, caches that let their entries be garbage-collected, and the whole of object-oriented programming: classes, methods and inheritance. Almost every substantial Lua code base, from game engines to Neovim plugins, uses metatables, usually for objects.
Metamethods for operators
Definition— Metatable and metamethod
A metatable is an ordinary table attached to a value with setmetatable(t, mt) (which returns t) and read back with getmetatable(t). When Lua performs an operation it does not know how to do on a value, such as adding a table, it looks in the value's metatable for a field named after the event, like __add; the function found there, the metamethod, performs the operation. From Lua you can set the metatables of tables only; strings share one metatable (whose __index is the string library, which is why s:upper() works), and C code can give metatables to its own userdata.
-- A metatable gives tables new behaviour for operators and built-ins.
local Vector = {}
Vector.__index = Vector -- methods are looked up in Vector (explained below)
local function new(x, y)
return setmetatable({ x = x, y = y }, Vector)
end
Vector.__add = function(a, b) return new(a.x + b.x, a.y + b.y) end
Vector.__sub = function(a, b) return new(a.x - b.x, a.y - b.y) end
Vector.__mul = function(a, b) -- number * vector or vector * number
if type(a) == "number" then return new(a * b.x, a * b.y) end
return new(a.x * b, a.y * b)
end
Vector.__unm = function(v) return new(-v.x, -v.y) end
Vector.__eq = function(a, b) return a.x == b.x and a.y == b.y end
Vector.__lt = function(a, b) return a:length() < b:length() end
Vector.__len = function(v) return 2 end -- # gives the dimension
Vector.__tostring = function(v) return "(" .. v.x .. ", " .. v.y .. ")" end
Vector.__concat = function(a, b) return tostring(a) .. tostring(b) end
function Vector:length() return math.sqrt(self.x ^ 2 + self.y ^ 2) end
local a, b = new(3, 4), new(1, -2)
print(a + b, a - b, 2 * a, a * 0.5, -b)
print(a == new(3, 4), a == b, rawequal(a, new(3, 4)))
print(b < a, #a, a:length())
print("a is " .. a, getmetatable(a) == Vector)It printed:
(4, 2) (2, 6) (6, 8) (1.5, 2.0) (-1, 2)
true false false
true 2 5.0
a is (3, 4) trueHow Lua chose each metamethod:
- Arithmetic (
__add,__sub,__mul,__div,__mod,__pow,__unm,__idiv, and the bitwise ones): Lua looks at the first operand's metatable, then the second's. That is how2 * afound__muleven though2is a number; the metamethod receives the operands in their original order and must handle both cases. __eqis used only when both operands are tables (or both userdata) and are not the same object;rawequalbypasses it and compares identity.__ltand__ledefine<and<=;a > bis evaluated asb < a. Here vectors compare by length.__lendefines#,__concatdefines..,__tostringis used bytostringand therefore byprint, and__call(shown next) makes a value callable.
Operator overloading is a tool for types where the meaning of the operator is obvious, such as vectors, matrices, complex numbers, money or dates. If a reader has to look up what + does, a method with a name is better.
__index and __newindex
The two most important metamethods deal with keys. __index is consulted when you read a key that is absent from the table; __newindex when you assign to a key that is absent. Each can be a table (Lua looks the key up there instead, which can itself have a metatable, forming a chain) or a function (Lua calls it with the table and the key, and for __newindex the value).
-- __index: where to look when a key is missing. A table or a function.
local defaults = { colour = "blue", size = 12 }
local style = setmetatable({ size = 16 }, { __index = defaults })
print(style.size, style.colour, rawget(style, "colour"))
local squares = setmetatable({}, {
__index = function(t, n) -- compute on demand, then remember
local v = n * n
rawset(t, n, v)
return v
end,
})
print(squares[12], rawget(squares, 12), rawget(squares, 13))
-- __newindex: intercept assignments to missing keys. Here, a read-only view.
local function read_only(t)
return setmetatable({}, {
__index = t,
__newindex = function(_, k) error("attempt to change read-only key '" .. tostring(k) .. "'", 2) end,
__len = function() return #t end,
__pairs = function() return next, t, nil end,
})
end
local DAYS = read_only({ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" })
print(DAYS[1], #DAYS)
print(pcall(function() DAYS[8] = "Funday" end))
-- A strict table: reading a missing key is an error instead of a silent nil.
local function strict(t)
return setmetatable(t, {
__index = function(_, k) error("no field '" .. tostring(k) .. "'", 2) end,
})
end
local config = strict({ host = "localhost", port = 8080 })
print(config.port, pcall(function() return config.prot end))
-- __call makes a table callable like a function.
local greeter = setmetatable({ greeting = "Sawubona" }, {
__call = function(self, name) return self.greeting .. ", " .. name end,
})
print(greeter("Zanele"))It printed:
16 blue nil
144 144 nil
Mon 7
false main.lua:26: attempt to change read-only key '8'
8080 false main.lua:35: no field 'prot'
Sawubona, ZaneleThe patterns, one by one:
- Defaults.
stylehas its ownsizebut nocolour, so the read falls through todefaults.rawgetreads without consulting the metatable, provingcolouris not really instyle. - Computed values. An
__indexfunction can compute a value on demand and store it withrawset(which writes without triggering__newindex), so the second lookup is an ordinary table read: memoisation through the metatable. - Read-only tables. The trick is to return an empty proxy whose
__indexpoints to the real data. Every assignment to the proxy is to a missing key, so__newindexsees it and refuses. Because the proxy is empty,#andpairsneed their own metamethods (__lenand__pairs) to see the real contents. The error was raised with level 2, so the message points at the line that tried the assignment, not at the metamethod. - Strict tables. An
__indexfunction that raises an error turns a silent typo (config.prot) into a loud one. The same trick on the environment table catches misspelt global variables in Lua versions before 5.5. - Callable tables.
__calllets a table act as a function while carrying data: here, a greeter with its own greeting.
Classes, methods and inheritance
Lua has no classes, but __index gives you everything needed to build them. The standard pattern: a class is a table holding the methods; each instance is a table holding its own data, whose metatable is the class; and the class's __index field points to the class itself, so any method missing from the instance is found in the class.
Definition— Method call syntax
function Class:method(args) is shorthand for function Class.method(self, args): it adds a hidden first parameter named self. obj:method(args) is shorthand for obj.method(obj, args): it passes the object as that first argument. The colon is pure syntax; methods are ordinary functions stored in tables.
-- A class is a table of methods that serves as the metatable of its instances.
local Entity = {}
Entity.__index = Entity
function Entity.new(name, x, y)
local self = setmetatable({}, Entity)
self.name, self.x, self.y = name, x or 0, y or 0
return self
end
function Entity:move(dx, dy) -- the colon adds a hidden 'self' parameter
self.x, self.y = self.x + dx, self.y + dy
return self
end
function Entity:describe()
return string.format("%s at (%d, %d)", self.name, self.x, self.y)
end
Entity.__tostring = function(e) return e:describe() end
-- Inheritance: Player's methods fall back to Entity's.
local Player = setmetatable({}, { __index = Entity })
Player.__index = Player
Player.__tostring = Entity.__tostring -- metamethods are not inherited through __index
function Player.new(name, x, y)
local self = Entity.new(name, x, y) -- build the base part
self.health = 100
return setmetatable(self, Player) -- then make it a Player
end
function Player:hit(damage)
self.health = math.max(0, self.health - damage)
end
function Player:describe() -- override, and call the base version
return Entity.describe(self) .. ", health " .. self.health
end
local rock = Entity.new("rock", 2, 2)
local hero = Player.new("Ayo", 0, 0)
hero:move(3, 1):move(1, 1) -- methods returning self can be chained
hero:hit(30)
for _, thing in ipairs({ rock, hero }) do
print(tostring(thing)) -- each finds its own describe
end
print(hero.move == rock.move, getmetatable(hero) == Player, rawget(hero, "move"))
-- obj:method(...) is just obj.method(obj, ...).
print(Entity.describe(hero), hero.describe(hero) == hero:describe())It printed:
rock at (2, 2)
Ayo at (4, 2), health 70
true true nil
Ayo at (4, 2) trueRead the pieces:
- The constructor
Entity.newcreates a table, sets its metatable toEntity, and fills in fields. BecauseEntity.__index = Entity,rock:describe()findsdescribeinEntity. The method is shared, not copied:rawget(hero, "move")isnil, andhero.move == rock.move. - Inheritance.
Playeris a class whose own metatable has__index = Entity. A lookup on a player tries the instance, thenPlayer, thenEntity: an__indexchain.Player.newbuilds the base part withEntity.newand re-blesses the result withsetmetatable(self, Player). - Overriding and calling the base method.
Player:describereplacesEntity:describefor players, and calls the original explicitly asEntity.describe(self). There is nosuperkeyword; you name the parent. - Metamethods are not inherited through
__index. Lua looks for__tostringdirectly in the metatable with a raw access, soPlayerneeds its own copy; the linePlayer.__tostring = Entity.__tostringprovides it. - Chaining.
movereturnsself, so calls can be chained.
Misconception
"obj.method() and obj:method() are interchangeable." They are not. The dot form passes no object, so inside the method self is nil (or whatever the first argument happens to be), and the error, often "attempt to index a nil value (local 'self')", appears inside the method rather than at the faulty call. When you see that message, check the call site for a dot that should be a colon.
Many projects use a small class library to remove the boilerplate; middleclass and classic are popular pure-Lua examples. They build on exactly this pattern, so understanding it lets you read any of them.
Weak tables, finalisers and private state
-- Weak tables: entries that do not keep their keys or values alive.
local cache = setmetatable({}, { __mode = "k" }) -- weak keys
local function remember(obj, info) cache[obj] = info end
local kept = {}
remember(kept, "still referenced")
remember({}, "garbage soon") -- nothing else refers to this key
local function count(t) local n = 0 for _ in pairs(t) do n = n + 1 end return n end
print("before collection:", count(cache))
collectgarbage()
print("after collection:", count(cache), cache[kept])
-- __gc: a finaliser that runs when the garbage collector frees a table.
do
local resource = setmetatable({ name = "temp file" }, {
__gc = function(r) print("finalising " .. r.name) end,
})
end
collectgarbage()
-- Private state with closures instead of metatables.
local function new_counter()
local count = 0 -- invisible from outside
return {
increment = function() count = count + 1 end,
value = function() return count end,
}
end
local c = new_counter()
c.increment(); c.increment()
print("counter:", c.value(), c.count)
-- __metatable hides and protects a metatable.
local locked = setmetatable({}, { __metatable = "locked" })
print(getmetatable(locked), pcall(setmetatable, locked, {}))It printed:
before collection: 2
after collection: 1 still referenced
finalising temp file
counter: 2 nil
locked false cannot change a protected metatable- Weak tables. A metatable field
__mode = "k"makes the table's keys weak: an entry does not by itself keep its key alive. Aftercollectgarbage()the entry for the temporary table vanished, while the entry forkept, still referenced by a local, remained."v"makes values weak, and"kv"both. Weak tables are how Lua code attaches extra data to objects, or caches results, without causing memory leaks. - Finalisers. A
__gcmetamethod runs when the collector frees the table. Do not rely on finalisers for anything that must happen promptly, such as closing files: when the collector runs is not under your control. Lesson 6's to-be-closed variables release resources at a precise point. - Private state with closures. A table of functions that close over local variables gives truly private fields:
c.countisnilbecausecountis not in the table at all. Closure objects are simple and fully private; metatable objects use less memory per instance (methods are shared rather than created per object) and support inheritance and operators. Large programs mostly use metatable classes, and closures for small one-off objects. __metatable. Setting this field makesgetmetatablereturn its value instead of the real metatable, and makessetmetatablefail, protecting objects from tampering by other code.
From fallbacks to metatables
Metatables were not part of Lua from the start, and their history shows the "mechanisms, not policies" principle being refined. Lua 2.1 (1995) introduced fallbacks: global functions Lua called when an operation failed, such as indexing a non-table. They were enough to build objects with inheritance, which users promptly did, but a fallback was global, so two libraries that each wanted their own could not coexist. Lua 3.0 (1997) replaced them with tag methods, attached to numeric tags that values carried, which allowed different behaviours for different kinds of value but was awkward to use. Lua 5.0 (2003) replaced tags with metatables: an ordinary table attached to a value, its fields naming the events. Because a metatable is a table, it can be shared, built at run time, inspected and inherited from, all with the tools you already have.
Each step kept the mechanism small and moved more of the policy into libraries. The language never gained a class keyword; the class pattern in this lesson is a convention, which is why you will meet slightly different versions of it in different code bases.
Common metatable mistakes
Misconception
"__index runs on every read." It runs only when the key is absent from the table itself. If an instance stores its own name, reading obj.name never consults the class. This is why a field can shadow a method of the same name: setting obj.describe = "x" hides the class's describe for that one object, and a later obj:describe() fails with "attempt to call a string value".
Misconception
"setmetatable copies the metatable into the object." It stores a reference. All instances of a class share one metatable, so adding a method to the class later makes it available to every existing instance at once. That is handy for live reloading in games and editors, and a surprise if you expected objects to be independent.
Misconception
"I can give numbers or strings their own metatables to add methods." From Lua code you can set the metatables of tables only. All strings share one metatable, which the standard library set up with __index = string; adding a function to the string table therefore gives every string a new method, which is legal but a change that every library in the program will see. Prefer plain functions.
Metatables in practice
- Keep the class pattern boring. One file per class,
Class.__index = Class, anewfunction, methods with the colon. Readers recognise it immediately. - Use
__indextables, not functions, for method lookup. A table lookup is fast; an__indexfunction runs Lua code on every missing key. - Avoid deep inheritance chains. Each level is another lookup on every inherited method call, and deep hierarchies are as hard to understand in Lua as anywhere else. Prefer composition: an object that holds another object and forwards a few calls.
- Use
rawgetandrawsetinside metamethods to avoid triggering them recursively. - Make typos loud. A strict
__indexon configuration tables, or Lua 5.5'sglobaldeclarations for global variables, catches whole classes of bugs before users see them. - Do not overload operators to be clever.
..on two buttons is not obviously "group them"; a method calledgroupis.
Exercises
1. Metatables and objects
Warm-upComputationalWhat does this program print?
local base = { a = 1, b = 2 }
local t = setmetatable({ b = 20 }, { __index = base })
t.c = 30
print(t.a + t.b + t.c .. " " .. tostring(rawget(t, "a")))
2. Metatables and objects
CoreComputationalWhat does this program print?
local Money = {}
Money.__index = Money
local function money(cents) return setmetatable({ cents = cents }, Money) end
Money.__add = function(a, b) return money(a.cents + b.cents) end
Money.__tostring = function(m)
return string.format("%d.%02d", m.cents // 100, m.cents % 100)
end
print(tostring(money(250) + money(1375)))
3. Metatables and objects
CoreComputationalWhat number does this program print?
local Counter = {}
Counter.__index = Counter
function Counter.new() return setmetatable({ n = 0 }, Counter) end
function Counter:inc(by)
self.n = self.n + (by or 1)
return self
end
local c = Counter.new()
c:inc():inc(5)
Counter.inc(c, 10)
print(c.n)
4. Metatables and objects
StretchComputationalWhat does this program print?
local A = {}
A.__index = A
function A:who() return "A" end
function A:hello() return "hello from " .. self:who() end
local B = setmetatable({}, { __index = A })
B.__index = B
function B:who() return "B" end
local a, b = setmetatable({}, A), setmetatable({}, B)
print(b:hello() .. ", " .. a:hello())
5. Metatables and objects
CoreComputationalWhat does this program print?
local log = {}
local t = setmetatable({ x = 1 }, {
__newindex = function(tbl, k, v)
log[#log + 1] = k
rawset(tbl, k, v)
end,
})
t.x = 2
t.y = 3
t.y = 4
t.z = 5
print(table.concat(log, ","))
6. Metatables and objects
StretchComputationalWhat number does this program print?
local w = setmetatable({}, { __mode = "v" })
local keep = {}
w[1], w[2], w[3] = keep, {}, {}
collectgarbage()
local n = 0
for _ in pairs(w) do n = n + 1 end
print(n)
7. Metatables and objects
StretchHumanA base class Shape defines Shape.__tostring. A subclass Circle is set up with setmetatable(Circle, { __index = Shape }) and Circle.__index = Circle, and circles are created with setmetatable({}, Circle). Printing a circle shows table: 0x... instead of the description. Why?
Further reading and resources
- Reference Manual: Metatables and MetamethodsEvery metamethod and exactly when Lua calls it.
- Reference Manual: Garbage CollectionFinalisers (__gc) and weak tables (__mode).
- Reference Manual: Basic Functionssetmetatable, getmetatable, rawget, rawset, rawequal, rawlen, pairs and next.
- Programming in Lua (first edition, online)The free first edition (written for Lua 5.0) has chapters on metatables and object-oriented programming whose ideas still apply.