Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
CModule Release v1.00 -Module loading facility.
v0.1.0: (5/21/2013)
* added search path for locating relative module paths; search path can be
set/inspected using cmodule.path(); pass no args for a list of projects in the path,
or pass a variable list of projects, i.e. cmodule.path("project1", "project2", "project3").
search path may only be set once.
* added optional fallback project param to cimport/cload and cmodule.loaded/exists/unload;
if a module is not found in the running project or in the search path, an attempt will
be made to load from the fallback project if specified.
* __pathto no longer returns fully qualified path to current module when no
module name is specified; use __pathto(__file) instead.
* no longer generating module closures for cload; use cload(__proj "MyModule") instead.
* renamed overridden module cimport to cinclude; cinclude only takes a module
name, not an absolute path; it is intended for loading from the containing project
only (it is syntactic sugar for cimport(__pathto "MyModule"))
* memoized module cinclude/__pathto closures, which can reduce memory
footprint considerably, and speed up loading/importing as well by not having
to create 2 closures per model per owning project (now it's 2 closures per owning project)
* removed redundant cmodule.import and cmodule.load. use cimport/cload instead.
v0.0.9: (5/17/2013):
* removed cmodule.null. it is no longer necessary since module
module returns are no longer weak referenced, and all modules
loaded with cimport are kept alive unless explicitly unloaded.
* replaced cmodule.nocache with cmodule.cache; to achieve the same effect,
put this line of code in your module file: _M[cmodule.cache] = false
v0.0.8 (5/17/2013):
* cmodule now keeps strong references to module return values
* added API cmodule.unload() to unload a loaded module.
v0.0.7 (5/17/2013):
* cimport/cload now only return 1 value, the value returned from the loaded module
* added cmodule.resolve, which returns the project and file names for the given path
if it is valid, nil otherwise.
v0.0.6 (5/17/2013):
* cmodule.loaded now auto-applies the .lua extension if no extension is specified.
* cmodule.loaded auto pre-pends the running project name if no project is specified
v0.0.5 (5/16/2013):
* fixed bug from 0.0.4 where cmodule would not return nil for newly loaded
modules that return cmodule.null
* added function cmodule.gexport, that accepts a table of key value pairs
that are batch exported to the global environment
* add value cmodule.nocache that can be returned from a module to indicate
* that cmodule should not cache the module (useful for running once-off scripts)
v0.0.4 (5/15/2013):
* added unique null type, accessible via cmodule.null
* cimport will now return nil for modules that return cmodule.null
-- cmodule
-- v0.1.0
-- todo:
-- * investigate better ways to handle dependency cycles
-- * support exported projects
-- - detect whether program is running in Codea or exported project
-- - reverse engineer exported project file layout
-- - load from alternate location when running an exported project
-- import global functions
local loadstring, fopen = loadstring,
local insert = table.insert
local format, rep = string.format, string.rep
local setfenv, setmetatable = setfenv, setmetatable
local pairs, ipairs = pairs, ipairs
-- loaded modules
local _modules = {}
-- search path projects
local _path = nil
-- unique module environment key to specify caching options
local function opt_cache() return opt_cache end
-- path to Codea's document's directory
local _docs = os.getenv("HOME") .. "/Documents/"
-- name of currently running project
local _this = nil -- set by cmodule()
-- boilerplate function headers for modules
local _importHeader = "return function(_M, __proj, __file, __pathto, cinclude)"
local _loadHeader = "return function(__proj, __file, __pathto)"
-- convert codea path to filesystem path
local function _fspath(p, f)
return _docs .. p .. ".codea/" .. f
local function _appendExt(f)
return f:find('%.') and f or (f..".lua")
local function _removeExt(f)
local dot = f:find('.', 1, true)
return dot and f:sub(1, dot-1) or f
-- parse for module name when compiler exceptions occur
local function _shortsource(s, maxlength)
local max = 60
s, maxlength = s:sub(1, max), maxlength or 30
max = 1 + s:len()
local n, c
for i = 1, max do
n, c = i, s:sub(i, i)
if not(c == ' ' or c == '\n') then
if n == max then return '' end
local start = n
for i = start, max do
c = s:sub(i, i)
if not(c == '\n' or i >= start + maxlength) then
n = i
else break end
return s:sub(start, n)
-- TODO: when Codea allows optional tab execution,
-- we'll need to take into account added boilerplate line
-- at the top of the module when reporting errors
local function _traceback(minlevel)
minlevel = minlevel or 2
local t = {}
for level = minlevel, math.huge do
local info = debug.getinfo(level, "Sln")
if not info then break end
if info.what == "C" then
insert(t, 'C function');
local name, desc =, _shortsource(info.source)
if desc == '' then desc = 'unknown' end
desc = '[' .. desc .. ']'
if name then desc = desc .. ":" .. name end
local currentline = info.currentline
if info.currentline == -1 then currentline = '?' end
s = desc .. ":" .. currentline .. "\n"
insert(t, s)
return "\ntrace:\n" .. table.concat(t)
-- remove the block comment wrapper, and
-- wrap the contents of a file with our boilerplate code
local function _wrap(s, p, t, header)
-- TODO: present error on malformed long comment wrapper
-- find the first occurrence of a long comment, so
-- we can see how many = are in it to refine our search
local b, e = s:find('--%[[%=]*%[')
local ne = rep('[%=]', (e-b)-3)
-- do end first
b, e = s:find('--%]' .. ne .. '%]')
e = s:find('\n', e, true)
local cs = s:sub(b, e):gsub('%]', '%%%]')
s = s:gsub(cs, 'end')
-- now do function header
b, e = s:find('--%[' .. ne .. '%[')
e = s:find('\n', e, true)
-- wrap the source and return it
local oc = '--[[ ' .. p .. ':' .. t .. ' --]] '
cs = s:sub(b, e-1):gsub('%[', '%%%[')
return s:gsub(cs, oc..header)
-- check to see if a module has already been loaded;
-- if so, return it's data
local function _findLoaded(cpath, fallback)
local spos = cpath:find(":", 1, true)
if spos ~= nil then
cpath = _appendExt(cpath)
return _modules[cpath], true, cpath, cpath:sub(1, spos-1), cpath:sub(spos+1)
-- check running project first
local file, cpath = cpath, _appendExt(_this .. ":" .. cpath)
local mod = _modules[cpath]
if mod ~= nil then
return mod, false, cpath, _this, cpath:sub(#_this+2)
-- now check all of the projects in the search path
if _path then
local project
for i = 1, #_path do
project = _path[i]
cpath = _appendExt(project .. ":" .. file)
mod = _modules[cpath]
if mod ~= nil then
return mod, false, cpath, project, cpath:sub(#project+2)
-- check fallback
if fallback then
cpath = _appendExt(fallback .. ":" .. file)
mod = _modules[cpath]
if mod ~= nil then
return mod, false, cpath, fallback, cpath:sub(#fallback+2)
-- module is not loaded
return nil, false, nil, nil, _appendExt(file)
-- search for a module's file in the search chain
local function _search(f, fallback)
-- check running project first
local file = fopen(_fspath(_this, f), "r")
if file ~= nil then
return _this, file
-- check search path
if _path then
local p = _this
for i = 1, #_path do
p = _path[i]
file = fopen(_fspath(p, f), "r")
if file ~= nil then
return p, file
-- check fallback
if fallback then
file = fopen(_fspath(fallback, f), "r")
if file ~= nil then
return fallback, file
-- load a module given a file, project name, file name, and module header
local function _readmodule(file, p, f, header)
local s = file:read("*a")
local tab = _removeExt(f)
local chunk, e = loadstring(_wrap(s, p, tab, header), tab)
if e then
error(format("\n\n%s\n%s", e, _traceback(4)))
return chunk
-- forward declare for _include
local import
-- memoize overridden cinclude closures
-- since we only need one per owning project.
local _overrides = {}
-- provide syntactic sugar for cimport when overriding
-- search path to load from containing project. e.g.:
-- cinclude "SomeModule"
-- is the same as
-- cimport(__proj "SomeModule")
local function _override(prefix)
local override = _overrides[prefix]
if not override then
override = function(modulename)
return _import(prefix .. modulename)
_overrides[prefix] = override
return override
-- default module metatable/index
local _defaultMT = {__index = _G}
-- memoize __pathto closures, since we only need
-- one per owning project
local _pathto = {}
-- prepare sandboxed environment for loaded modules
local function _makeEnv(p, f, e)
e = setmetatable({}, e and {__index = e} or _defaultMT)
local prefix = p .. ":"
local pathto = _pathto[prefix]
if not pathto then
pathto = function(f) return prefix .. f end
_pathto[prefix] = pathto
return e, pathto, prefix
-- return a string listing the current project path
local function _pathString()
local spath
if _path and #_path > 0 then
spath = "{"
for i, v in ipairs(_path) do
spath = spath .. v
if i < #_path then
spath = spath .. ", "
return spath .. "}"
return "{none}"
-- keep track of modules that are currently loading,
-- so that we can detect dependency cycles
local _loading = {}
-- import a module. imported module is memoized so
-- successive imports do not have to re-load the module
-- each time. If nothing is returned, the module environment
-- itself will be imported (i.e. the module's _M table)
function _import(codeapath, fallback)
local mod, absolute, cpath, p, f = _findLoaded(codeapath)
if mod == nil then
local file
if absolute then
if p then
file = fopen(_fspath(p, f), "r")
p, file = _search(f, fallback)
if p then cpath = p .. ":" .. f end
if not file then
local spath = _pathString()
error(format("Module not found: %s\n\nin search path:%s\n\nfallback:%s\n\n%s", codeapath,
spath, fallback or "none", _traceback(3)))
if _loading[cpath] then
error(format("circular dependency detected loading %s\n%s", cpath, _traceback(3)))
_loading[cpath] = true
local loaded = _readmodule(file, p, f, _importHeader)()
local env, pathto, prefix = _makeEnv(p, f)
mod = setfenv(loaded, env)(env, p, f, pathto, _override(prefix)) or env
_loading[cpath] = nil
local cache = env[opt_cache]
if cache then
env[opt_cache] = nil
if cache == false then
return mod
_modules[cpath] = mod
return mod
-- load a data module. if an environment is provided, it will
-- be the sandboxed module environment. if no environment
-- is provided, the global table will be exposed to the
-- module environment.
local function _load(codeapath, environment, fallback)
if not fallback and type(environment) == "string" then
fallback, environment = environment
local spos, p, f, cpath, file = codeapath:find(":", 1, true)
if spos ~= nil then
cpath = _appendExt(codeapath)
p, f = cpath:sub(1, spos-1), cpath:sub(spos+1)
file = fopen(_fspath(p, f), "r")
f = _appendExt(codeapath)
p, file = _search(f, fallback)
if p then cpath = p .. ":" .. f end
if not file then
local spath = _pathString()
error(format("Module not found: %s\n\nin search path:%s\n\nfallback:%s\n\n%s", codeapath,
spath or "{none}", fallback or "none", _traceback(3)))
if _loading[cpath] then
error(format("circular dependency detected loading %s\n%s", cpath, _traceback(3)))
_loading[cpath] = true
local loaded = _readmodule(file, p, f, _loadHeader)()
local env, pathto = _makeEnv(p, f, environment)
mod = setfenv(loaded, env)(p, f, pathto) or env
_loading[cpath] = nil
return mod
-- exports
-- import a source module; identical to cmodule.import
_G.cimport = _import
-- load a data module; identical to cmodule.load
_G.cload = _load
-- cmodule utitlities
_G.cmodule = setmetatable({
-- set/get the project path. the path may only be set once
path = function(...)
local narg = select("#", ...)
-- return the current path if no params are specified
if narg == 0 then
-- return a copy of the path so it can't be modified
return _path and {unpack(_path)} or nil
if _path then
error("cmodule.path may only be set once")
_path = {...}
-- return the name of the running project
project = function() return _this end,
-- unload a loaded module
-- params: module name or absolute module path
unload = function(codeapath, fallback)
local mod, _, cpath = _findLoaded(codeapath, fallback)
if mod then
_modules[cpath] = nil
-- params: module name or absolute module path
-- returns: true if a module can be located and loaded; else false
exists = function(codeapath, fallback)
local spos = codeapath:find(":", 1, true)
local absolute = (spos ~= nil)
local p, f, cpath, file
if absolute then
cpath = _appendExt(codeapath)
p, f = cpath:sub(1, spos-1), cpath:sub(spos+1)
file = fopen(_fspath(p, f), "r")
f = _appendExt(codeapath)
p, file = _search(f, fallback)
if p then cpath = p .. ":" .. f end
if file then
return true, cpath
return false
-- params: none, module name, or absolute module path
-- returns: if no params are specified, array of loaded modules;
-- otherwise, module path if module is found, or nil if not found
loaded = function(codeapath, fallback)
if codeapath then
local _, _, cpath = _findLoaded(codeapath, fallback)
return cpath
local loaded = {}
for k in pairs(_modules) do insert(loaded, k) end
return loaded
-- split an absolute path into separate project and file components;
-- if relative path is used, currently running project name is appended
-- params: absolute module path or module name in current project
-- returns: project name, tab name
resolve = function(cpath)
cpath = _appendExt(cpath)
local i = cpath:find(":", 1, true)
if i then
return cpath:sub(1, i-1), cpath:sub(i+1), cpath
return _this, cpath, _this .. ":" .. cpath
-- utility to export multiple variables to the global namespace
-- params: table containing key/value pairs to be exported to _G
gexport = function(exports)
for k, v in pairs(exports) do
_G[k] = v
-- by default, all modules loaded by cimport are cached.
-- to disable caching for a module, add this to your module file:
-- _M[cmodule.cache] = false
cache = opt_cache,
}, {
-- params: project name.
-- returns: cmodule.import, as a convenience.
-- notes: this should be executed before any
-- other code in your program.
__call = function (_, thisProject)
-- set currently running project name
_this = thisProject
-- return import to allow for a chained initialization/import,
-- for example: cmodule "myProject" "setup"
return _import
-- Main
-- see cmodule_tests at:
-- for very basic examples of cmodule usage;
-- better tests are on the way.
function setup()
AutoGist.setProjectInfo("CModule","toadkick","Module loading facility.",GIST_VERSION)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.