Classes Tutorial

Classes Tutorial

This article supposes that you are already more or less familiar with object-oriented programming. If not, please read the Terminology in order to fully understand this tutorial.

Overview

A class is a table that contains a bunch of variables and functions. Using Lua's metatable functionality, classes behave in special ways, for example, you can call them to create an instance.

In Sheets, you define a class like this:

class "ClassName" {
    -- variables
}

Once you've made a class, it will be in the global environment with the name you gave it. The name you give the class should be descriptive, for example Button or KeyboardEvent, and should be camel case starting with an upper case letter. This helps you to differentiate between libraries and classes.

Instances

When a class is defined, it is possible to make instances of that class. Each instance will have the same properties as its parent class, but is unique to all other instances of that same class. It could be said that the class simply describes what the instance should look like.

You create an instance by calling the class as if it were a function:

local instance = SomeClass()

Some classes require or allow you to pass in values when you create an instance, for example a Button:

local button = Button( x, y, width, height, text )

Each instance also has a property class which is the class it is a member of.

Constructors

Constructors, as mentioned above, are functions called when an instance is created. Take this as an example:

class "Something" {}  -- Create an empty class

-- Constructors share the name of their class
function Something:Something( ... )
    -- This function will get called every time we call Something() to create a new instace
    print( "An instance of the 'Something' class has been created!" )

    -- Note that constructors don't return a value, the class system handles the actual class creation
end

When creating an instance of Something, the constructor method is called. It is also given the arguments the class was called with, so calling Something( 1, 2 ) would pass 1 and 2 to the constructor. Errors from within constructors must use an error level 1 higher than if they would error from ordinary code, otherwise the error would be reported at an incorrect position (inside the class system).

Using self

Lua has a keyword, self, which is great for OOP. When used with colon notation, the variable self is a reference to the instance the method is being called on. Take this as an example:

class "Person" {
    name = ""; -- even if the variable will be defined in the constructor, list it here, with some value that shows it is not final or a default, such as 0 or ""
}

function Person:Person( name )
    self.name = name -- self is the newly created instance
end

function Person:printName()
    print( self.name ) -- self is some instance
end

local a = Person "Benedict"
local b = Person "Allen"

a:printName() --> Benedict
b:printName() --> Allen

print( a.name ) --> Benedict
print( b.name ) --> Allen

Syntax

Having a common syntax/coding style across files is useful for finding information and making changes later on. With Sheets, the following style is recommended for classes:

[local variables]

[local functions]

class "ClassName" [modifiers] {
    [variables]

    [static variables]
}

[static functions]

[constructor]

[methods]

Methods and variables should be lower camel case. Methods should be defined with colon notation as follows:

function ClassName:methodName( arguments, ... )

end

Local functions should follow the same naming conventions:

local function f( arguments, ... )

end