implementing classes in Lua

this is the way people generally do object-oriented programming in the language.

Lua also has a syntax sugar for declaring functions on tables:

local t = {}

function t.do_stuff()
    print("hi")
end

to complement the : call syntax, there’s also the : function declaration syntax.

function t:do_thing()
    self.aaa = 1
end

-- desugars to

function t.do_thing(self)
    self.aaa = 1
end

as this example shows, this syntax simply inserts a parameter named self before all other parameters.

with that knowledge, we can move on to creating classes.

we can use __index fallback tables to model classes quite easily.

let’s create a class Cat with two methods meow and feed:

local Cat = {}

function Cat:meow()
    print("meow")
end

function Cat:feed()
    self.food = self.food + 1
end

we also need a method for creating cats, which I’ll call new:

function Cat:new()
    local cat = {}
    cat.food = 10
    return cat
end

we can now use the API like this:

local kitty = Cat:new()
Cat.meow(kitty)
Cat.feed(kitty)
print(kitty.food) --> 11

but, note how we have to namespace the Cat functions specifically, and we cannot use the : method call operator yet. the table returned by Cat:new() does not have the methods meow and feed for that to work.

so to provide it with these methods, we can use our handy __index metamethod:

function Cat:new()
    local cat = {}
    cat.food = 10
    -- setmetatable returns its first argument. How convenient!
    return setmetatable(cat, { __index = Cat })
end

now we’ll be able to create cats that can meow on their own:

kitty = Cat:new()
kitty:meow()
kitty:feed()
print(kitty.food) --> 11

however, creating an extra metatable every single time we create a cat is pretty inefficient! we can exploit the fact that Lua doesn’t really care about metatable fields it doesn’t know about, and make Cat itself into a metatable:

Cat.__index = Cat

function Cat:new()
    local cat = {}
    cat.food = 10
    return setmetatable(cat, Cat)
end

but note how we’ve declared Cat:new with the special method syntax. we call the method like Cat:new(), which desugars to Cat.new(Cat), which means that the implicit self parameter is already the Cat table! thus, we can simplify the call to setmetatable, to remove the redundant reference to Cat:

    return setmetatable(cat, self)

with all these improvements, here’s how the code looks so far.

local Cat = {}
Cat.__index = Cat

function Cat:new()
    local cat = {}
    cat.food = 10
    return setmetatable(cat, self)
end

function Cat:meow()
    print("meow!")
end

function Cat:feed()
    self.food = self.food + 1
end

given this fairly simple way of creating classes, we can now expand this idea to inheritance.

conceptually, inheriting from a class is pretty simple: what we want to do, is to have all of the parent class’s methods available on the child class. I think you might see where this is going now: all we need to do to create a subclass, is to create a new class, whose metatable’s __index points to the parent class.

let’s rewrite our example with the kitty to generalise animals under a single class:

Animal
- food: integer
: speak()
: feed()

Cat : Animal
: speak()

so, starting with the base Animal class…

local Animal = {}
Animal.__index = Animal

-- We don't create a `new` method, because we don't want people creating "generic" animals.
-- This makes our class _abstract_.

-- speak is a function that must be overridden by all subclasses, so we make it error by default.
function Animal:speak() error("not implemented") end

function Animal:feed()
    self.food = self.food + 1
end

now we can create instances of the Cat, and it will inherit the feed method from Animal:

local kitty = Cat:new()
kitty:speak()
kitty:feed()
print(kitty.food) --> 2

with all this, we are now ready to pack this subclassing functionality into a nicer package. speaking of packages, let’s create a module class.lua:

local Class = {}
Class.__index = Class

return Class

now, let’s create a method for inheriting from the class.

-- insert above `return Class`

function Class:inherit()
    local Subclass = {}
    Subclass.__index = Subclass
    -- Note how `self` in this instance is the parent class, as we call the method like `SomeClass:inherit()`.
    setmetatable(Subclass, self)
    return Subclass
end

this is going to let us cleanly inherit from classes, without needing to copy and paste all the __index and setmetatable boilerplate:

local Class = require "class"
local Sub = Class:inherit()

the other boilerplaty bit was initialisation, so let’s take care of that:

-- insert below the `end` of `function Class:inherit()`

-- By default, let's make the base `Class` impossible to instantiate.
-- This should catch bugs if a subclass forgets to override `initialize`. 
function Class:initialize()
    error("this class cannot be initialized")
end

-- `...` is Lua's notation for collecting a variable number of arguments
function Class:new(...)
    local instance = {}
    -- `self` is the class we're instantiating, as this method is called like `MyClass:new()`
    setmetatable(instance, self)
    -- We pass the instance to the class's `initialize()` method, along with all the arguments
    -- we received in `new()`.
    self.initialize(instance, ...)
    return instance
end

having that, we can now rewrite our Animal example to use our super-simple class library.

local Class = require "class"

---

local Animal = Class:inherit()

-- We'll provide a convenience function for implementers, for initialising the food value,
-- as well as any other base fields that may come up.
function Animal:_initialize()
    self.food = 1
end

function Animal:speak()
    error("unimplemented")
end

function Animal:feed()
    self.food = self.food + 1
end

---

local Cat = Animal:inherit()

-- Don't forget that our initialize() method errors by default, so it has to be overridden.
function Cat:initialize()
    self:_initialize()
end

function Cat:speak()
    print("meow")
end

having a nice class library like this makes things a lot more convenient. no longer do we have to mess with raw metatables! all we need to do is call inherit() or new(), and the magic is done for us.

local kitty = Cat:new()
kitty:speak()
kitty:feed()
print(kitty.food)

if you followed this tutorial from beginning to end, you now have a simple library for object-oriented programming in Lua, which supports creating classes, and inheriting from them.

you may wanna check these out for additional reference.

the Lua documentation on metatables—there’s lots of other operators you can overload!

rxi’s classic module—it’s an example of a good, but small class library that has all the features you’d ever need.