agentic-lua-class

Lua Class Pattern

Basic class structure:

--- @class Animal
local Animal = {}
Animal.__index = Animal

function Animal:new()
    self = setmetatable({}, self)
    return self
end

function Animal:move()
    print("Animal moves")
end

Key points:

• Set __index to self for inheritance
• Use setmetatable to create instances
• Return the instance from constructor

Method definition syntax:

• function Class:method() - Instance method, receives self implicitly

  • Called as: instance:method() or instance.method(instance)
  • Use for methods that need access to instance state

• function Class.method() - Module function, static, does NOT receive self

  • Called as: Class.method() or instance.method() (both work, but no self)
  • Use for utility functions, constructors, or static helpers

Inheritance Pattern

Class setup (module-level):

local Parent = {}
Parent.__index = Parent

--- @class Child : Parent
local Child = setmetatable({}, { __index = Parent })
Child.__index = Child

Constructor with parent initialization:

function Parent:new(name)
    local instance = {
        name = name,
        parent_state = {}
    }
    return setmetatable(instance, self)
end

function Child:new(name, extra)
    -- Call parent constructor with Parent class
    local instance = Parent.new(Parent, name)

    -- Add child-specific state
    instance.child_state = extra

    -- Re-metatable to child class for proper inheritance chain
    return setmetatable(instance, Child)
end

Critical rules:

• Always pass parent class explicitly: Parent.new(Parent, ...) not Parent.new(self, ...)
• Re-assign metatable to child class after parent initialization
• Inheritance chain: instance → Child → Parent

Calling parent methods:

function Child:move()
    Parent.move(self)  -- Explicit parent method call
    print("Child-specific movement")
end

Class Design Guidelines: creating and modifying