Creating Lua modules

The Lua language doesn't impose strict policies on what a module should look like. Instead, it encourages programmers to find their own style depending on the situation.

Getting ready

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.

How to do it…

There are three types of modules that are commonly used:

• A module that returns a table as a module interface
• A module in the form of an object
• A module in the form of a singleton object

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.

A module that returns a table as an interface

In this case, the module uses locally defined variables and functions. Every function intended for external use is put into one table. This common table is used as an interface with the outer world and is returned at the end of the module:

-- 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',
}

A module in the form of an object

This module type doesn't manipulate the global namespace. Every object you create uses its own local namespace:

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

A module in the form of a singleton object

This is a special case of object module. There is only one and the same object instance:

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

How it works…

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())