Object-orientation for Lua
Pull request Compare This branch is 95 commits behind kikito:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Lua OOP classes usually end being:

  • multi-file libraries, too difficult to understand
  • very small libraries, not very powerful

Middleclass attemps to be a mid-sized library (~140 lines of code, on a single file), with clean, easy to understand code, and yet powerful enough to be used in most cases.


See the github wiki page for examples & documentation.


  • ~140 lines of code
  • top-level Object class
  • all methods are virtual
  • instance.class returns the instance’s class
  • Class.name returns the class name (a string)
  • Class.super returns its super class
  • Class methods can be defined with Class.static.methodname
  • Subclassing:
    • class(name) creates a subclass of Object
    • class(name, Superclass) creates a subclass of the class SuperClass
    • SuperClass:subclass(name) also creates a subclass of the class SuperClass
  • Instantiation:
    • Classes can define an initialize method for initializing new instances. They can accept an arbitrary number of params.
    • Instances are created by doing Class:new(params) or also Class(params)
    • SuperClass’ methods can be used by using this syntax: SuperClass.initialize(self, params).
  • support for Lua metamethods: just define a method called __tostring, __add, etc. and your instances will be able to use it.
  • Mixins:
    • A very simple mechanism for sharing functionality among a group of classes that are otherwise non-related.
    • Mixins are just simple lua tables with functions inside them.
    • Class:include(mixin) will copy the function definitions of mixin to class
    • If mixin contains a function, called included, that function will be invoked right after the functions have been copied. It allows for modifying the class more profoundly.
  • The function instanceOf(class, instance) returns true if instance is an instance of the class Class
  • The function subclassOf(Superclass, Class) returns true if Class is a subclass of SuperClass
  • The function includes(mixin, Class) returns true if Class (or one of its superclasses) includes mixin.

Features left out:

  • metaclasses
  • classes are not Objects (instances are)
  • simulating a ‘super’ keyword (for performance concerns)


Just copy the middleclass.lua file wherever you want it (for example on a lib/ folder). Then write this in any Lua file where you want to use it:

require 'middleclass'

The package.path variable must be configured so that the folder in which middleclass.lua is copied is available, of course.

Please make sure that you read the license, too (for your convenience it’s now included at the beginning of the middleclass.lua file).


This project uses telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just execute the following from the root inspect folder:

tsc -f spec/*

Performance tests

Middleclass also comes with a small performance test suit. Just run the following commant:

lua performance/run.lua