Modules in Lua

Intermediate ~30 min read

Modules are the key to organizing and reusing code in Lua. They allow you to split your code into separate files, create libraries, and manage dependencies. Lua's module system is simple yet powerful, using tables and the require() function. In this lesson, you'll learn how to create, use, and organize modules effectively. Let's dive in!

What are Modules?

A module is simply a Lua file that returns a table containing functions and values:

-- mymodule.lua
local M = {}

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

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

M.version = "1.0"

return M

Module Structure:

Create a local table (usually named M or the module name)
Add functions and values to the table
Return the table at the end

Using require()

Load modules with the require() function:

-- main.lua
local mymodule = require("mymodule")

print(mymodule.greet("Alice"))  -- Hello, Alice
print(mymodule.add(5, 3))       -- 8
print(mymodule.version)         -- 1.0

Tip: require() caches modules. If you require the same module multiple times, it only loads once and returns the cached version.

-- Creating Modules in Lua

-- A module is just a table that contains functions and variables
-- This is a simple module pattern

-- Method 1: Simple module table
local mymodule = {}

function mymodule.sayHello(name)
    print("Hello, " .. name .. "!")
end

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

mymodule.version = "1.0"

-- Use the module
mymodule.sayHello("World")
print("Sum:", mymodule.add(5, 3))
print("Version:", mymodule.version)

-- Method 2: Module with local (private) functions
local mathutils = {}

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

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

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

print("\nMath utils:")
print("Square of 5:", mathutils.square(5))
print("Cube of 3:", mathutils.cube(3))
-- print(validate(5))  -- Error: validate is not accessible

-- Method 3: Module with constructor pattern
local function createCounter()
    local count = 0  -- Private variable
    
    local counter = {}
    
    function counter.increment()
        count = count + 1
        return count
    end
    
    function counter.decrement()
        count = count - 1
        return count
    end
    
    function counter.getValue()
        return count
    end
    
    return counter
end

local counter1 = createCounter()
local counter2 = createCounter()

print("\nCounters:")
print("Counter1:", counter1.increment())
print("Counter1:", counter1.increment())
print("Counter2:", counter2.increment())
print("Counter1 value:", counter1.getValue())
print("Counter2 value:", counter2.getValue())

-- Method 4: Module with metatable
local StringUtils = {}
StringUtils.__index = StringUtils

function StringUtils.new()
    return setmetatable({}, StringUtils)
end

function StringUtils.reverse(str)
    return string.reverse(str)
end

function StringUtils.capitalize(str)
    return string.upper(string.sub(str, 1, 1)) .. string.sub(str, 2)
end

function StringUtils.split(str, delimiter)
    local result = {}
    for match in (str .. delimiter):gmatch("(.-)" .. delimiter) do
        table.insert(result, match)
    end
    return result
end

print("\nString utils:")
print("Reverse:", StringUtils.reverse("hello"))
print("Capitalize:", StringUtils.capitalize("hello"))
local parts = StringUtils.split("a,b,c", ",")
print("Split:", table.concat(parts, " | "))

-- Method 5: Module with namespace
local App = {}
App.Utils = {}
App.Models = {}

function App.Utils.log(message)
    print("[LOG] " .. message)
end

function App.Models.User(name)
    return {name = name}
end

App.Utils.log("Application started")
local user = App.Models.User("Alice")
print("User:", user.name)

-- Method 6: Returning a module
local function createLogger(prefix)
    local logger = {}
    
    function logger.info(message)
        print("[" .. prefix .. " INFO] " .. message)
    end
    
    function logger.error(message)
        print("[" .. prefix .. " ERROR] " .. message)
    end
    
    return logger
end

local appLogger = createLogger("APP")
local dbLogger = createLogger("DB")

appLogger.info("Application started")
dbLogger.error("Connection failed")

Output

Click Run to execute your code

Module Patterns

1. Basic Table Module

-- math_utils.lua
local M = {}

function M.square(x)
    return x * x
end

function M.cube(x)
    return x * x * x
end

return M

2. Module with Private Functions

-- calculator.lua
local M = {}

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

-- Public functions
function M.add(a, b)
    if not (validate(a) and validate(b)) then
        error("Arguments must be numbers")
    end
    return a + b
end

function M.multiply(a, b)
    if not (validate(a) and validate(b)) then
        error("Arguments must be numbers")
    end
    return a * b
end

return M

3. Module with State

-- counter.lua
local M = {}
local count = 0  -- Private state

function M.increment()
    count = count + 1
    return count
end

function M.decrement()
    count = count - 1
    return count
end

function M.get()
    return count
end

function M.reset()
    count = 0
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

Class Modules

Modules can export classes:

-- person.lua
local Person = {}
Person.__index = Person

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

function Person:greet()
    return "Hello, I'm " .. self.name
end

function Person:birthday()
    self.age = self.age + 1
end

return Person

-- main.lua
local Person = require("person")

local alice = Person:new("Alice", 25)
print(alice:greet())  -- Hello, I'm Alice
alice:birthday()
print(alice.age)  -- 26

Module Organization

Directory Structure

myapp/
├── main.lua
├── lib/
│   ├── utils.lua
│   ├── database.lua
│   └── models/
│       ├── user.lua
│       └── product.lua
└── config.lua

Loading from Subdirectories

-- Use dot notation for subdirectories
local User = require("lib.models.user")
local utils = require("lib.utils")

Important: Lua searches for modules in paths specified by package.path. Use forward slashes or dots for subdirectories, not backslashes.

Practical Examples

String Utilities Module

-- string_utils.lua
local M = {}

function M.trim(s)
    return s:match("^%s*(.-)%s*$")
end

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

function M.capitalize(s)
    return s:sub(1, 1):upper() .. s:sub(2):lower()
end

function M.reverse(s)
    return s:reverse()
end

return M

Configuration Module

-- config.lua
local M = {}

M.app = {
    name = "MyApp",
    version = "1.0.0",
    debug = true
}

M.database = {
    host = "localhost",
    port = 5432,
    name = "mydb"
}

M.server = {
    host = "0.0.0.0",
    port = 8080
}

function M.get(key)
    local keys = {}
    for k in key:gmatch("[^.]+") do
        table.insert(keys, k)
    end
    
    local value = M
    for i, k in ipairs(keys) do
        value = value[k]
        if not value then return nil end
    end
    return value
end

return M

Logger Module

-- logger.lua
local M = {}

local levels = {
    DEBUG = 1,
    INFO = 2,
    WARN = 3,
    ERROR = 4
}

local currentLevel = levels.INFO

function M.setLevel(level)
    currentLevel = levels[level] or levels.INFO
end

local function log(level, message)
    if levels[level] >= currentLevel then
        print(string.format("[%s] %s: %s", 
            os.date("%Y-%m-%d %H:%M:%S"),
            level,
            message))
    end
end

function M.debug(message)
    log("DEBUG", message)
end

function M.info(message)
    log("INFO", message)
end

function M.warn(message)
    log("WARN", message)
end

function M.error(message)
    log("ERROR", message)
end

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 Best Practices

Best Practices:

Always use local for the module table
Return the module table at the end
Keep private functions local (don't add to module table)
Use meaningful module names
Document your module's public API
Avoid global variables in modules
Keep modules focused on a single responsibility

Module Template

-- module_name.lua
-- Description: What this module does
-- Author: Your name
-- Version: 1.0

local M = {}

-- Private variables
local privateVar = "private"

-- Private functions
local function privateFunction()
    -- Implementation
end

-- Public functions
function M.publicFunction()
    -- Implementation
    privateFunction()  -- Can call private functions
end

-- Constants
M.VERSION = "1.0"
M.CONSTANT = "value"

return M

Practice Exercise

Try these module challenges:

-- Exercise: Modules
-- TODO: Complete the following exercises

-- 1. Create a simple math utilities module
local MathUtils = {}

function MathUtils.average(numbers)
    -- your code here
    -- calculate and return average of numbers table
end

function MathUtils.max(numbers)
    -- your code here
    -- find and return maximum value
end

function MathUtils.min(numbers)
    -- your code here
    -- find and return minimum value
end

-- local nums = {10, 20, 5, 15, 30}
-- print("Average:", MathUtils.average(nums))
-- print("Max:", MathUtils.max(nums))
-- print("Min:", MathUtils.min(nums))

-- 2. Create a string utilities module with private helper
local StringUtils = {}

-- Private helper function
local function isValid(str)
    -- your code here
    -- check if str is a non-empty string
end

function StringUtils.reverse(str)
    -- your code here
    -- use isValid() then reverse the string
end

function StringUtils.isPalindrome(str)
    -- your code here
    -- check if string is same forwards and backwards
end

-- print(StringUtils.reverse("hello"))
-- print(StringUtils.isPalindrome("racecar"))

-- 3. Create a counter module with private state
local function createCounter(initial)
    -- your code here
    -- return a module with increment, decrement, getValue methods
    -- use closure to keep count private
end

-- local counter = createCounter(10)
-- counter.increment()
-- counter.increment()
-- print("Count:", counter.getValue())

-- 4. Create a logger module with different levels
local Logger = {}

function Logger.info(message)
    -- your code here
    -- print with [INFO] prefix
end

function Logger.error(message)
    -- your code here
    -- print with [ERROR] prefix
end

function Logger.debug(message)
    -- your code here
    -- print with [DEBUG] prefix
end

-- Logger.info("Application started")
-- Logger.error("Something went wrong")
-- Logger.debug("Variable x = 10")

-- 5. Create a module with configuration
local Config = {}
Config.settings = {}

function Config.set(key, value)
    -- your code here
end

function Config.get(key)
    -- your code here
end

function Config.getAll()
    -- your code here
    -- return all settings
end

-- Config.set("debug", true)
-- Config.set("timeout", 30)
-- print("Debug:", Config.get("debug"))
-- print("All settings:", Config.getAll())

-- 6. Create a module that checks for dependencies
local function createModuleWithCheck()
    local M = {}
    
    -- Check if 'math' module is available
    local hasMath = pcall(require, "math")
    
    if hasMath then
        M.mathAvailable = true
        -- your code here
        -- add a function that uses math
    else
        M.mathAvailable = false
    end
    
    return M
end

-- local myModule = createModuleWithCheck()
-- print("Math available?", myModule.mathAvailable)

Output

Click Run to execute your code

Summary

In this lesson, you learned:

What modules are and why they're important
Using require() to load modules
Different module patterns (basic, private functions, state)
Creating class modules
Organizing modules in directories
Practical examples: string utils, config, logger
Module best practices and templates

What's Next?

Congratulations on completing Module 5! You've mastered OOP and modules in Lua. Next, we'll explore advanced topics including error handling, debugging, and best practices for writing robust Lua code. Let's continue! 🚀

Previous Inheritance

Next Creating Modules

What are Modules?

Using require()

Module Patterns

1. Basic Table Module

2. Module with Private Functions

3. Module with State

Class Modules

Module Organization

Directory Structure

Loading from Subdirectories

Practical Examples

String Utilities Module

Configuration Module

Logger Module

Module Best Practices

Module Template

Practice Exercise

Summary

What's Next?

Enjoying these tutorials?