Creating Modules in Lua

Intermediate ~25 min read

Creating well-designed modules is essential for building maintainable Lua applications. In this lesson, you'll learn advanced module creation techniques including proper exports, private members, initialization patterns, and professional module design. Let's explore how to create robust, reusable modules!

Module Creation Patterns

Basic Module Pattern

-- mymodule.lua
local M = {}

function M.func1()
    return "Function 1"
end

function M.func2()
    return "Function 2"
end

return M

Module with Private Functions

-- validator.lua
local M = {}

-- Private helper function
local function isString(value)
    return type(value) == "string"
end

-- Private helper function
local function isNumber(value)
    return type(value) == "number"
end

-- Public function using private helpers
function M.validateEmail(email)
    if not isString(email) then
        return false, "Email must be a string"
    end
    if not email:match("^[%w.]+@[%w.]+%.%w+$") then
        return false, "Invalid email format"
    end
    return true
end

function M.validateAge(age)
    if not isNumber(age) then
        return false, "Age must be a number"
    end
    if age < 0 or age > 150 then
        return false, "Age must be between 0 and 150"
    end
    return true
end

return M

-- Module Creation in Lua

-- A module is simply a table that is returned
-- This file demonstrates how to create a proper Lua module

-- Method 1: Basic module structure
local M = {}

M.version = "1.0.0"
M.author = "Your Name"

function M.greet(name)
    return "Hello, " .. name .. "!"
end

function M.add(a, b)
    return a + b
end

-- To use this module, you would save it as a file (e.g., mymodule.lua)
-- and load it with: local mymodule = require("mymodule")

-- Method 2: Module with private functions
local M2 = {}

-- Private function (local, not exported)
local function validate(x)
    return type(x) == "number"
end

-- Public function (exported)
function M2.square(x)
    if not validate(x) then
        error("Input must be a number")
    end
    return x * x
end

function M2.cube(x)
    if not validate(x) then
        error("Input must be a number")
    end
    return x * x * x
end

-- Method 3: Module with initialization
local M3 = {}

-- Module initialization code
local initialized = false

local function init()
    if not initialized then
        print("Initializing module...")
        initialized = true
    end
end

function M3.doSomething()
    init()  -- Ensure module is initialized
    print("Doing something...")
end

-- Method 4: Module with constants
local M4 = {}

M4.CONSTANTS = {
    MAX_SIZE = 100,
    MIN_SIZE = 1,
    DEFAULT_NAME = "Unknown"
}

function M4.isValidSize(size)
    return size >= M4.CONSTANTS.MIN_SIZE and size <= M4.CONSTANTS.MAX_SIZE
end

-- Method 5: Module with state
local M5 = {}

local state = {
    count = 0,
    items = {}
}

function M5.addItem(item)
    table.insert(state.items, item)
    state.count = state.count + 1
end

function M5.getCount()
    return state.count
end

function M5.getItems()
    return state.items
end

-- Method 6: Module with metatable
local M6 = {}
M6.__index = M6

function M6.new(name)
    local self = setmetatable({}, M6)
    self.name = name
    return self
end

function M6:greet()
    return "Hello from " .. self.name
end

-- Method 7: Module with documentation
local M7 = {}

--- Adds two numbers together
-- @param a number First number
-- @param b number Second number
-- @return number Sum of a and b
function M7.add(a, b)
    return a + b
end

--- Multiplies two numbers
-- @param a number First number
-- @param b number Second number
-- @return number Product of a and b
function M7.multiply(a, b)
    return a * b
end

-- Method 8: Complete module example
-- This is how you would structure a real module file

local Calculator = {}
Calculator._VERSION = "1.0.0"
Calculator._DESCRIPTION = "A simple calculator module"
Calculator._LICENSE = "MIT"

-- Private helper
local function checkNumber(x, name)
    if type(x) ~= "number" then
        error(name .. " must be a number")
    end
end

-- Public API
function Calculator.add(a, b)
    checkNumber(a, "a")
    checkNumber(b, "b")
    return a + b
end

function Calculator.subtract(a, b)
    checkNumber(a, "a")
    checkNumber(b, "b")
    return a - b
end

function Calculator.multiply(a, b)
    checkNumber(a, "a")
    checkNumber(b, "b")
    return a * b
end

function Calculator.divide(a, b)
    checkNumber(a, "a")
    checkNumber(b, "b")
    if b == 0 then
        error("Division by zero")
    end
    return a / b
end

-- Return the module
return Calculator

-- To use this module:
-- 1. Save it as calculator.lua
-- 2. In another file: local calc = require("calculator")
-- 3. Use it: print(calc.add(5, 3))

Output

Click Run to execute your code

Module Exports

Explicit Exports

-- math_utils.lua
local M = {}

local function square(x)
    return x * x
end

local function cube(x)
    return x * x * x
end

-- Explicitly export functions
M.square = square
M.cube = cube

-- Or define directly
M.add = function(a, b)
    return a + b
end

return M

Selective Exports

-- database.lua
local M = {}

-- Internal state (not exported)
local connection = nil
local isConnected = false

-- Private function
local function validateConnection()
    if not isConnected then
        error("Not connected to database")
    end
end

-- Public API
function M.connect(host, port)
    connection = {host = host, port = port}
    isConnected = true
    return true
end

function M.disconnect()
    connection = nil
    isConnected = false
end

function M.query(sql)
    validateConnection()
    -- Execute query
    return "Query result"
end

-- Export only what's needed
return M

-- Module Exports in Lua

-- Different ways to export functions and values from a module

-- Method 1: Export individual functions
local M = {}

M.greet = function(name)
    return "Hello, " .. name
end

M.farewell = function(name)
    return "Goodbye, " .. name
end

-- Method 2: Export with function syntax
local M2 = {}

function M2.add(a, b)
    return a + b
end

function M2.multiply(a, b)
    return a * b
end

-- Method 3: Export constants
local M3 = {}

M3.VERSION = "1.0.0"
M3.MAX_SIZE = 100
M3.DEFAULT_NAME = "Unknown"

function M3.getVersion()
    return M3.VERSION
end

-- Method 4: Export with namespace
local M4 = {}

M4.math = {}
M4.math.add = function(a, b) return a + b end
M4.math.subtract = function(a, b) return a - b end

M4.string = {}
M4.string.reverse = function(s) return string.reverse(s) end
M4.string.upper = function(s) return string.upper(s) end

-- Method 5: Selective exports (only export what you want)
local M5 = {}

-- Private function (not exported)
local function privateHelper()
    return "This is private"
end

-- Public function (exported)
function M5.publicFunction()
    return "This is public: " .. privateHelper()
end

-- Method 6: Export class-like structure
local M6 = {}
M6.__index = M6

function M6.new(name, age)
    local self = setmetatable({}, M6)
    self.name = name
    self.age = age
    return self
end

function M6:introduce()
    return "I'm " .. self.name .. ", " .. self.age .. " years old"
end

-- Method 7: Export with factory pattern
local M7 = {}

function M7.createCounter(initial)
    local count = initial or 0
    
    return {
        increment = function()
            count = count + 1
            return count
        end,
        decrement = function()
            count = count - 1
            return count
        end,
        getValue = function()
            return count
        end
    }
end

-- Method 8: Export with configuration
local M8 = {}

M8.config = {
    debug = false,
    timeout = 30,
    maxRetries = 3
}

function M8.configure(options)
    for key, value in pairs(options) do
        M8.config[key] = value
    end
end

function M8.getConfig(key)
    return M8.config[key]
end

-- Method 9: Export with multiple return values
local M9 = {}

function M9.divmod(a, b)
    return math.floor(a / b), a % b
end

function M9.minmax(numbers)
    local min, max = numbers[1], numbers[1]
    for i = 2, #numbers do
        if numbers[i] < min then min = numbers[i] end
        if numbers[i] > max then max = numbers[i] end
    end
    return min, max
end

-- Method 10: Complete module with all exports
local StringUtils = {}

-- Module metadata
StringUtils._VERSION = "1.0.0"
StringUtils._DESCRIPTION = "String utility functions"

-- Private helpers
local function isString(s)
    return type(s) == "string"
end

-- Public functions
function StringUtils.reverse(s)
    if not isString(s) then
        error("Input must be a string")
    end
    return string.reverse(s)
end

function StringUtils.capitalize(s)
    if not isString(s) then
        error("Input must be a string")
    end
    return string.upper(string.sub(s, 1, 1)) .. string.sub(s, 2)
end

function StringUtils.split(s, delimiter)
    if not isString(s) then
        error("Input must be a string")
    end
    local result = {}
    for match in (s .. delimiter):gmatch("(.-)" .. delimiter) do
        table.insert(result, match)
    end
    return result
end

function StringUtils.trim(s)
    if not isString(s) then
        error("Input must be a string")
    end
    return s:match("^%s*(.-)%s*$")
end

-- Export constants
StringUtils.EMPTY = ""
StringUtils.SPACE = " "

-- Return the module
return StringUtils

-- Usage examples (in another file):
-- local utils = require("stringutils")
-- print(utils.reverse("hello"))
-- print(utils.capitalize("world"))
-- local parts = utils.split("a,b,c", ",")

Output

Click Run to execute your code

Module Initialization

Initialization on Load

-- config.lua
local M = {}

-- Initialize on module load
local defaults = {
    debug = false,
    timeout = 30,
    retries = 3
}

local settings = {}

-- Copy defaults
for k, v in pairs(defaults) do
    settings[k] = v
end

function M.set(key, value)
    settings[key] = value
end

function M.get(key)
    return settings[key]
end

function M.reset()
    for k, v in pairs(defaults) do
        settings[k] = v
    end
end

return M

Lazy Initialization

-- cache.lua
local M = {}

local cache = nil

local function initCache()
    if not cache then
        cache = {}
        print("Cache initialized")
    end
end

function M.set(key, value)
    initCache()
    cache[key] = value
end

function M.get(key)
    initCache()
    return cache[key]
end

return M

Module Constants and Metadata

-- http.lua
local M = {}

-- Constants
M.VERSION = "1.0.0"
M.AUTHOR = "Your Name"

M.STATUS_CODES = {
    OK = 200,
    NOT_FOUND = 404,
    SERVER_ERROR = 500
}

M.METHODS = {
    GET = "GET",
    POST = "POST",
    PUT = "PUT",
    DELETE = "DELETE"
}

-- Functions
function M.request(method, url)
    if not M.METHODS[method] then
        error("Invalid HTTP method")
    end
    -- Make request
    return {status = M.STATUS_CODES.OK}
end

return M

-- Module with Private Members

-- Demonstrates how to create truly private members in Lua modules

-- Method 1: Using local variables (closure-based privacy)
local function createBankAccount(initialBalance)
    -- Private variables
    local balance = initialBalance
    local transactions = {}
    
    -- Private function
    local function recordTransaction(type, amount)
        table.insert(transactions, {
            type = type,
            amount = amount,
            balance = balance,
            timestamp = os.time()
        })
    end
    
    -- Public interface
    local account = {}
    
    function account.deposit(amount)
        if amount <= 0 then
            return false, "Amount must be positive"
        end
        balance = balance + amount
        recordTransaction("deposit", amount)
        return true, balance
    end
    
    function account.withdraw(amount)
        if amount > balance then
            return false, "Insufficient funds"
        end
        balance = balance - amount
        recordTransaction("withdraw", amount)
        return true, balance
    end
    
    function account.getBalance()
        return balance
    end
    
    function account.getTransactionHistory()
        -- Return copy, not original
        local copy = {}
        for i, t in ipairs(transactions) do
            copy[i] = {
                type = t.type,
                amount = t.amount,
                balance = t.balance
            }
        end
        return copy
    end
    
    return account
end

-- Usage
local myAccount = createBankAccount(1000)
print("Initial balance:", myAccount.getBalance())
myAccount.deposit(500)
print("After deposit:", myAccount.getBalance())
myAccount.withdraw(200)
print("After withdraw:", myAccount.getBalance())
-- print(balance)  -- Error: balance is not accessible

-- Method 2: Module with private state
local Counter = {}

do
    -- Private state (in do...end block)
    local instances = 0
    local totalCount = 0
    
    function Counter.new()
        local count = 0  -- Private to each instance
        instances = instances + 1
        
        local counter = {}
        
        function counter.increment()
            count = count + 1
            totalCount = totalCount + 1
            return count
        end
        
        function counter.getValue()
            return count
        end
        
        return counter
    end
    
    function Counter.getTotalInstances()
        return instances
    end
    
    function Counter.getTotalCount()
        return totalCount
    end
end

local c1 = Counter.new()
local c2 = Counter.new()
c1.increment()
c1.increment()
c2.increment()

print("\nCounter instances:", Counter.getTotalInstances())
print("Total count:", Counter.getTotalCount())

-- Method 3: Module with private configuration
local Database = {}

do
    -- Private configuration
    local config = {
        host = "localhost",
        port = 5432,
        database = "mydb"
    }
    
    local connection = nil
    
    -- Private function
    local function validateConfig()
        return config.host ~= nil and config.port ~= nil
    end
    
    -- Public functions
    function Database.configure(options)
        for key, value in pairs(options) do
            if config[key] ~= nil then
                config[key] = value
            end
        end
    end
    
    function Database.connect()
        if not validateConfig() then
            error("Invalid configuration")
        end
        connection = {
            host = config.host,
            port = config.port,
            connected = true
        }
        print("Connected to " .. config.host .. ":" .. config.port)
        return connection
    end
    
    function Database.disconnect()
        if connection then
            connection.connected = false
            connection = nil
            print("Disconnected")
        end
    end
    
    function Database.isConnected()
        return connection ~= nil and connection.connected
    end
end

Database.configure({host = "192.168.1.1", port = 3306})
Database.connect()
print("Connected?", Database.isConnected())
Database.disconnect()

-- Method 4: Class with private methods
local Person = {}
Person.__index = Person

do
    -- Private validation function
    local function validateAge(age)
        return type(age) == "number" and age >= 0 and age <= 150
    end
    
    local function validateName(name)
        return type(name) == "string" and #name > 0
    end
    
    function Person.new(name, age)
        if not validateName(name) then
            error("Invalid name")
        end
        if not validateAge(age) then
            error("Invalid age")
        end
        
        local self = setmetatable({}, Person)
        self.name = name
        self.age = age
        return self
    end
    
    function Person:birthday()
        if validateAge(self.age + 1) then
            self.age = self.age + 1
        end
    end
end

function Person:introduce()
    return "I'm " .. self.name .. ", " .. self.age .. " years old"
end

local person = Person.new("Alice", 25)
print("\n" .. person:introduce())
person:birthday()
print(person:introduce())

-- Method 5: Module with truly private data
local SecureStorage = {}

do
    -- Private storage (completely inaccessible from outside)
    local storage = {}
    local accessLog = {}
    
    local function log(action, key)
        table.insert(accessLog, {
            action = action,
            key = key,
            time = os.time()
        })
    end
    
    function SecureStorage.set(key, value)
        storage[key] = value
        log("set", key)
    end
    
    function SecureStorage.get(key)
        log("get", key)
        return storage[key]
    end
    
    function SecureStorage.delete(key)
        storage[key] = nil
        log("delete", key)
    end
    
    function SecureStorage.has(key)
        return storage[key] ~= nil
    end
    
    function SecureStorage.getAccessLog()
        -- Return copy
        local copy = {}
        for i, entry in ipairs(accessLog) do
            copy[i] = {action = entry.action, key = entry.key}
        end
        return copy
    end
end

SecureStorage.set("password", "secret123")
SecureStorage.set("apiKey", "abc-def-ghi")
print("\nPassword:", SecureStorage.get("password"))
print("Has apiKey?", SecureStorage.has("apiKey"))
SecureStorage.delete("password")
print("Has password?", SecureStorage.has("password"))

Output

Click Run to execute your code

Module Documentation

--[[
    String Utilities Module
    
    Provides common string manipulation functions.
    
    @module string_utils
    @author Your Name
    @version 1.0.0
    @license MIT
]]

local M = {}

--[[
    Trims whitespace from both ends of a string
    
    @param s string The string to trim
    @return string The trimmed string
    @usage local result = string_utils.trim("  hello  ")
]]
function M.trim(s)
    return s:match("^%s*(.-)%s*$")
end

--[[
    Splits a string by a delimiter
    
    @param s string The string to split
    @param delimiter string The delimiter to split by
    @return table Array of string parts
    @usage local parts = string_utils.split("a,b,c", ",")
]]
function M.split(s, delimiter)
    local result = {}
    local pattern = string.format("([^%s]+)", delimiter)
    for match in s:gmatch(pattern) do
        table.insert(result, match)
    end
    return result
end

return M

Practical Module Examples

Event Emitter Module

-- event_emitter.lua
local M = {}

function M.new()
    local self = {
        listeners = {}
    }
    
    function self:on(event, callback)
        if not self.listeners[event] then
            self.listeners[event] = {}
        end
        table.insert(self.listeners[event], callback)
    end
    
    function self:emit(event, ...)
        if self.listeners[event] then
            for i, callback in ipairs(self.listeners[event]) do
                callback(...)
            end
        end
    end
    
    function self:off(event, callback)
        if self.listeners[event] then
            for i, cb in ipairs(self.listeners[event]) do
                if cb == callback then
                    table.remove(self.listeners[event], i)
                    break
                end
            end
        end
    end
    
    return self
end

return M

Validation Module

-- validation.lua
local M = {}

local validators = {}

function validators.required(value)
    if value == nil or value == "" then
        return false, "This field is required"
    end
    return true
end

function validators.email(value)
    if not value:match("^[%w.]+@[%w.]+%.%w+$") then
        return false, "Invalid email format"
    end
    return true
end

function validators.minLength(min)
    return function(value)
        if #value < min then
            return false, "Minimum length is " .. min
        end
        return true
    end
end

function validators.maxLength(max)
    return function(value)
        if #value > max then
            return false, "Maximum length is " .. max
        end
        return true
    end
end

function M.validate(value, rules)
    for i, rule in ipairs(rules) do
        local valid, error = rule(value)
        if not valid then
            return false, error
        end
    end
    return true
end

M.validators = validators

return M