Skip to content
Make Lua module and init.lua becomes easy
Branch: master
Clone or download
Latest commit 50195df Jan 12, 2015
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE newmodule improvement Jan 11, 2015 README fix Jan 11, 2015
init.lua newmodule improvement Jan 11, 2015
newmodule.lua newmodule improvement Jan 11, 2015

If you play with Lua module, You probably know that becomes complicate with lot of modules, directories, path, etc.

Now I use newmodule everywhere.

What is the problem ?

More about Lua modules ?

You should read the following article :

kikito wrote:

    I wrote about modules, packages and multiple files here:

You should also read :


On github :


You can copy it on the main directory. Or change the package path.

I choose to create my own framework to keep my newmodule in subdirectories (and lot of other stuff) The framework will be release soon at )



Use the newmodule to create a new table. Detect the name of the module (_M._NAME usefull for debug message) Detect the module name, usefull to require sub module Detect the module parent name, usefull to require module in the same directory The table returns follow the format :

loccal _M = require("newmodule")(...)

equal to :

local _M = {
  _NAME = "",
  _PATH = "",
  _PPATH = "lua-foo",

In this case _NAME will always equal to _PATH.

Load a sub module :

local child = require(_M.PATH .. ".childmodule")
local child = child_require("childmodule")

Load another module in the same directory :

local bro = require(_M.PPATH .. ".brothermodule")
local bro = brother_require("brothermodule")

require("newmodule"):from(a_table, ...)

Returns : the modified table passed as argument a_table Like the require("newmodule")(...) except you are able a provide the table. require("newmodule")(...) equals require("newmodule"):from({}, ...)

local _M = { _VERSION = "0.1" }
require("newmodule"):from(_M, ...)
return _M

require("newmodule"):initload("modulename", ...)

A special stuff for the init.lua file that is only use to redirect the loader to the real module.

return require("newmodule"):initload("realmodule", ...)

Details about the module fields

The _NAME field will be kept if already exists.

The _PATH, _PPATH and _CALLEDWITH field will be overwritten if exists.

If not exists all fields will be created.


In some cases it's interesting to include in error message the name of the module. I think the _NAME should contains module name readable by human text, like "bar, the sub-module of foo" instead of ""

Other implementation of module seems use this field. I can not use it to manage module path for automatic loading...


It's the module path (without ".init" suffix if present)


It's the _PATH without one level. if _PATH = then _PPATH will be


CALLEDWITH is most for debug purpose. It's a copy of the 1st argument passed (like the _PATH but the ".init" suffix is never removed)

Localised Loaders

What is the difference between child and brother module


In mod.lua the bro.lua is in the same parent directory, it's a brother module, should be loaded with brother_require("bro") In mod.lua the child.lua is in a subdirectory with the name of mod.lua (mod.child) it's a child of mod and should be loaded with child_require("child"). It equals to brother_require("mod.child").

Where is the child_require

and brother_require ?

Both are generated during the require("newmodule")(...) call.


local _M, child_require, brother_require = require("newmodule")(...)
local bro = brother_require("bro")
local child = child_require("child")


The child_require will internally use the _M. _PATH.

mod.lua :

local _M, child_require = require("newmodule")(...)
local child = child_require("child")


The child_require will internally use the _M. _PPATH.

local _M, child_require, brother_require = require("newmodule")(...)
local bro = brother_require("bro")

Sample of use

init.lua :

return require("newmodule"):initload("foo", ...)

foo.lua :

local _M, creq, breq = require("newmodule")(...)
print("foo: _NAME=", _M._NAME)
print("foo: _PATH=", _M._PATH)
print("foo: _PPATH=", _M._PPATH)

local x = (breq "x") -- require("foo.x")
return _M

x.lua :

local _M = {
    __OK = "ok",
require'newmodule':from(_M, ...)
print("x ok?", _M.__OK)
return _M

test with :

lua -l newmodule -e 'require"foo"'
lua -l newmodule -e 'require"foo.init"'
lua -l newmodule -e 'require""'
cd foo ; lua -l newmodule -e 'require"foo"'
You can’t perform that action at this time.