Luaoop

Table of Contents

• Install
• API
• Inheritance
• Special methods
  • Misc
  • Operators
• Private / Protected
• Behavior transfer
  • Class behavior
  • Instance behavior

Luaoop is a library to do OOP (Object Oriented Programming) which aims to be simple, powerful and optimized (especially for LuaJIT).

Look at the examples for more understanding of the library.

Install

See rockspecs or luarocks.

💡	Rockspecs are human-readable. They are useful even without using luarocks, as for manual installations.

API

-- create a new class
-- name: identifier for debugging purpose
-- ...: base classes (single/multiple inheritance)
-- return created class
class.new(name, ...)
-- SHORTCUT class(name, ...)

-- t: class or instance
-- return class name or nil
class.name(t)

-- t: class or instance
-- return the type (class) or nil
class.type(t)

-- check if an instance/class is/inherits from a specific class
-- t: class or instance
-- classdef: class
-- return true or nil
class.is(t, classdef)

-- return instance/class types map (type => true)
-- t: class or instance
-- return types map (type => true) or nil
class.types(t)

-- get the class metatable applied to the instances
-- useful to apply class behaviour to a custom table
-- will build the class if not already built
-- classdef: class
-- return meta or nil
class.meta(classdef)

-- create instance
-- classdef: class
-- ...: constructor arguments
class.instantiate(classdef, ...)
-- SHORTCUT Class(...)

-- build class
-- will build/re-build the class
-- (if a class is not already built, when used for inheritance or instantiation this function is called)
-- classdef: class
class.build(classdef)

-- get operator
-- lhs: instance
-- name: full name of the operator (starting with "__")
-- rhs: any value, can be nil for unary operators
-- no_error: if passed/true, will not trigger an error if no operator was found
class.getop(lhs, name, rhs, no_error)

Inheritance

• single and multiple inheritance

• all properties are inherited for classes

• all properties except specials (starting with __) are inherited for instances

ℹ️	Special tables inherit from bases' special tables.

⚠️	In case of multiple inheritance with functions with the same name, one will be taken arbitrarily. This issue can be solved by accessing directly a specific parent method/function using the class definition.

Inheritance is not dynamic (cached) and is built by class.build. class.build must be called for any later changes to the class definition or base classes (in order, build the dependencies, then build the class, then build the derived classes).

ℹ️	This function is already called when using a class for inheritance or instantiation for the first time; in most cases calling this function is not needed because the class is completely defined when used.

Example 1. Multiple inheritance and override

A = class("A")
function A:test()
  print("a")
end

B = class("B")
function B:test()
  print("b")
end

C = class("C", A, B) -- inheritance from A and B
function C:test() -- force the usage of B:test()
  B.test(self)
end

Example 2. Constructor override

A = class("A")

function A:__construct()
  print("A")
end

B = class("B", A)
function B:__construct()
  A.__construct(self) -- call parent (A) constructor
  print("B")
end

Special methods

Special methods for a class can be defined; they will be inherited (for a class) the same way other properties are. Each special method is prefixed by __.

ℹ️	They are not metamethods, they are named like this to keep consistency with the Lua notation.

Misc

construct	called at initialization
destruct	called at garbage collection

Operators

Operators can be defined like this:

function Object:__op() end -- unary
Object.__op[rhs] = function(self, rhs) end -- binary

ℹ️	rhs can be a class or a Lua type (as string).

Unary

call	like the metamethod
tostring	like the metamethod
unm	like the metamethod

Binary

concat	like the metamethod (no order, but has a second parameter "inverse" when the concat is not forward)
add	like the metamethod (no order)
sub	like the metamethod (can be omitted if add is defined and unm is defined for rhs)
mul	like the metamethod (no order)
div	like the metamethod
mod	like the metamethod
pow	like the metamethod
eq	like the metamethod (doesn’t throw an error if the operator is missing, will be false by default)
le	like the metamethod
lt	like the metamethod

🔥	Comparison of different instances with different types is possible, but this may change in the future.

Private / Protected

There are no private/protected mechanisms in Luaoop.

“Private” methods can be achieved with local functions in the class definition.

local function pmethod(self)
end

“Private” instance properties can be achieved using a local table in the class definition with weak keys for the instances.

local privates = setmetatable({}, {__mode = "k"})

function Object:__construct()
  privates[self] = { a = 1, b = 2 }
end

function Object:method()
  local p = privates[self]
  p.a = p.a*p.b
end

Behavior transfer

It’s possible to give Luaoop class and instance behavior to any object by adding the luaoop property (a table) to its metatable (and set some metamethods).

Class behavior

💡	class.new will check (and build if not built) base classes and initialize class special tables. It is easier to use this function and copy/modify the metatable afterwards.

Base properties

name	class name
bases	list of base classes

Optional build hooks can be added to customize some parts of the build process, they are functions starting with __.

Class hooks

postbuild(class, build)	used to add more properties to the build, called after the base classes inheritance process
postmeta(class, meta)	used to modify the built instance metatable, called at the end of the build process
instantiate(class, …​)	used to replace the default instantiate behavior, should return a valid new Luaoop instance (…​ are constructor arguments) ℹ️ this hook by-pass the construct/destruct default behavior (they will not be set/called)

After-build properties

build	table containing inherited properties and special tables for the class (not self)
instance_build	table containing inherited class properties without specials
types	map of type (class) ⇒ true
meta	metatable built used for the instances Base properties type instance type types map of type (class) ⇒ true name base class name Metamethods index inherits from class' instance_build call op call unm op unm add op add sub op sub mul op mul div op div pow op pow mod op mod eq op eq le op le lt op lt tostring op tostring concat op concat

ℹ️	It’s easier to let these properties being created by class.build and just implement the build hooks.

Metamethods

call	shortcut for class.instantiate
tostring	for regular classes, will print class<name>
index	inherits from the build table and each special table inherits from build special tables

Instance behavior

The instance behavior is set using the meta built metatable. In some cases if the class has a destructor, this metatable could be replaced by a copy (not deep) to have custom instance fields.

💡	The new metatable would be marked as custom with a luaoop.custom boolean property set to true.