Creating Lua modules

In this recipe, you will create three versions of a module that contains one local variable, one variable accessible from outside the module, one function that returns a simple value, and a function that uses a value from the current module.

There are three types of modules that are commonly used:

The first case is used mostly with modules that contain an interface to third-party libraries. The second type of module is used less often, but it's useful if you need multiple instances of the same object, for example, a network stack. The last one uses a similar approach as in the previous case, but this time there's always only one instance of the object. Many games use the singleton object for the resource management system.

-- module1.lua
local var1 = 'ipsum'
local function local_function1()
  return 'lorem'
end

local function local_function2(self)
  return var1 .. self.var2
end
-- returns module interface
return {
  lorem = local_function1,
  ipsum = local_function2,
  var2 = 'sit',
}

-- module2.lua
local M = function()
  local instance
  local var1 = 'ipsum'
  instance = {
    var2 = 'sit',
    lorem = function()
      return 'lorem'
    end,
    ipsum = function(self)
      return var1 .. self.var2
    end,
  }
  return instance
end

return M

-- module3.lua
local instance

local M = function()
  if not instance then
    local var1 = 'ipsum'
    instance = {
      var2 = 'sit',
      lorem = function()
        return 'lorem'
      end,
      ipsum = function(self)
        return var1 .. self.var2
         end,
    }
  end
  return instance
end

return M

Modules are used with the require function that registers them in the global table modules.loaded. This table contains the compiled code of every module used and ensures that each module is loaded only once.

Object modules return a local variable M, which contains an object interface. However, you can use any other name for this variable. Choosing between tables or closure as object contained is mostly a matter of application design.

Variable var1 is always hidden from the outside world and can be changed only by the exposed function. Variable var2 is freely accessible and can be modified anytime.

The following lines of code show the usage patterns for all three types of module:

local module1 = require 'module1'
local module2 = require 'module2'
local module3 = require 'module3'
-- create two instances of module2
local module2_A = module2()
local module2_B = module2()
-- try to create an instance of module2 twice
local module3_A = module3()
local module3_B = module3()

-- usage of a module with interface table
print('Module 1 - Before:', module1:lorem() .. module1:ipsum())
module1.var2 = 'amet'
print('Module 1 - After:', module1:lorem() .. module1:ipsum())

-- usage of a module in a form of an object
print('Module 2a - Before:', module2_A:lorem() .. module2_A:ipsum())
module2_A.var2 = 'amet'
print('Module 2a - After:', module2_A:lorem() .. module2_A:ipsum())
print('Module 2b - After:', module2_B:lorem() .. module2_B:ipsum())

-- usage of a module in a form of a singleton object
print('Module 3a - Before:', module3_A:lorem() .. module3_A:ipsum())
module3_A.var2 = 'amet'
print('Module 3a - After:', module3_A:lorem() .. module3_A:ipsum())
print('Module 3b - After:', module3_B:lorem() .. module3_B:ipsum())