08 — Modules, Packages & Dependency Management

-- package.path: semicolon-separated template paths for Lua modules
-- ? is replaced with the module name (dots → slashes for subdirectories)
-- Example: "./?.lua;./?/init.lua;/usr/share/lua/5.4/?.lua"

-- require("a.b.c") searches:
--   ./a/b/c.lua
--   ./a/b/c/init.lua
--   /usr/share/lua/5.4/a/b/c.lua
--   ...

-- package.cpath: same for C modules (.so/.dll)
-- require("cjson") searches cpath for cjson.so, loads via luaopen_cjson

-- Add a custom search path:
package.path = package.path .. ";./lib/?.lua;./lib/?/init.lua"

-- package.searchpath(name, path, sep?, rep?): find file, return path or nil+err
local path, err = package.searchpath("mylib.utils", package.path)
-- path = "./lib/mylib/utils.lua" (or nil with error listing tried paths)

-- Custom search with a different separator:
local path = package.searchpath("mylib::utils", package.path, "::", "/")
-- treats :: as separator, replaces with / for file path

Searchers (package.searchers)

-- package.searchers (5.2+, called package.loaders in 5.1): ordered list of functions
-- Each searcher(name) returns: loader_fn | "error message" | nil (try next)
-- Default searchers (in order):
-- 1. package.preload[name] — check preloaded loaders (programmatic registration)
-- 2. package.path searcher — find .lua file on package.path
-- 3. package.cpath searcher — find .so/.dll on package.cpath, call luaopen_name
-- 4. all-in-one loader — find submodules of C packages

-- Register a module without a file (useful for testing/mocking):
package.preload["fake_http"] = function()
  return {
    get = function(url) return "mocked response for " .. url end,
  }
end
local http = require("fake_http")  -- uses preload, no file needed

-- Custom searcher: load from a database or embedded string
table.insert(package.searchers, 1, function(name)
  local source = embedded_modules[name]  -- your custom source map
  if not source then return nil end  -- not found, try next searcher
  local fn, err = load(source, name, "t")  -- compile
  if not fn then return err end
  return fn  -- loader function (will be called by require)
end)

-- Module = table of exported functions. Local helpers stay private.
local M = {}  -- the module table (exported)

-- Local (private) helper — not in M, not accessible externally
local function validate(x)
  assert(type(x) == "number", "expected number")
  return x
end

-- Public functions assigned to M
function M.add(a, b)
  validate(a); validate(b)
  return a + b
end

function M.multiply(a, b)
  validate(a); validate(b)
  return a * b
end

return M  -- the require() return value

-- No table returned; the module's value is a single function (or a few closures)
-- All state is in upvalues — truly private, not even accessible via M

local count = 0  -- private upvalue

local function inc() count = count + 1; return count end
local function get() return count end
local function reset() count = 0 end

return {
  inc = inc,
  get = get,
  reset = reset,
}
-- count is NOT accessible — it's an upvalue of the closures, not in the returned table

-- Module is a class (metatable); require returns the class table
local Point = {}
Point.__index = Point

function Point.new(x, y)
  return setmetatable({x = x, y = y}, Point)
end

function Point:distance(other)
  local dx, dy = self.x - other.x, self.y - other.y
  return math.sqrt(dx * dx + dy * dy)
end

function Point:__tostring()
  return string.format("(%d, %d)", self.x, self.y)
end

return Point  -- callers do: local Point = require("point"); local p = Point.new(1, 2)

-- Change _ENV so all globals write to the module table — no `M.` prefix needed
local M = {}
do
  local _ENV = M  -- all unqualified assignments go to M, not _G

  host = "localhost"      -- M.host (not _G.host)
  port = 8080            -- M.port

  function connect()      -- M.connect
    return "connecting to " .. host .. ":" .. port
  end

  function reload(new_host, new_port)
    host = new_host or host  -- _ENV.host, but _ENV = M, so M.host
    port = new_port or port
  end
end
return M
-- Clean syntax, no M. prefix; but reads of `host` inside the block also
-- go through _ENV (M), so they read M.host (correct)

-- Problem: A requires B, B requires A. When A is loading, it requires B.
-- B then requires A — but A is still loading (incomplete). B gets the
-- partially-constructed A (or the true sentinel if A hasn't returned yet).

-- a.lua
local B = require("b")     -- B not loaded yet → loads b.lua
local M = {}
M.value = 1
function M.use_b() return B.value end  -- uses B (which is loaded by now)
return M

-- b.lua
local A = require("a")     -- A is ALREADY loading (in package.loaded as a sentinel)
-- At this point, A is the chunk's return value — but a.lua hasn't returned yet!
-- So A might be nil (if a.lua hasn't reached `return M`)
local M = {}
M.value = 2
function M.use_a()
  -- SAFE: defer the access to call time (A is fully loaded by now)
  return A.value  -- A is the complete module at call time
end
return M

Anti-pattern: accessing circular dep at module load time

-- BAD: b.lua accesses A at load time — A isn't ready
local A = require("a")
local M = {}
M.cached_a_value = A.value  -- ERROR: A is nil or incomplete at load time
return M

-- GOOD: defer to function call time
local A = require("a")
local M = {}
function M.get_a_value() return A.value end  -- A is complete by call time
return M

-- If even the require order is problematic, defer the require to call time
local M = {}
function M.use_a()
  local A = require("a")  -- require inside function — runs at call, not load
  return A.value
end
return M

-- Evict from cache + re-require: gets a fresh module, preserving state externally
local function reload(name, state_transfer)
  local old = package.loaded[name]
  package.loaded[name] = nil  -- evict
  local new = require(name)   -- re-execute (fresh module table)
  if state_transfer then state_transfer(old, new) end
  return new, old
end

-- Usage: reload game system, preserving player score
local GameState = require("game.state")
GameState = reload("game.state", function(old, new)
  new.player_score = old.player_score  -- transfer state to new module
  new.player_name = old.player_name
end)

-- WARNING: side effects in module body run AGAIN on reload
-- If module registers callbacks at load time, you get double registration
-- Solution: provide an init() function called explicitly, not at load time

Package Structure & init.lua

-- Directory structure:
-- mylib/
--   init.lua        → require("mylib") finds this via ?/init.lua path
--   utils.lua      → require("mylib.utils")
--   models/
--     user.lua     → require("mylib.models.user")
--     post.lua     → require("mylib.models.post")

-- mylib/init.lua: the package entry point, re-exports submodules
return {
  utils  = require("mylib.utils"),
  models = {
    user = require("mylib.models.user"),
    post = require("mylib.models.post"),
  },
}

-- Usage:
local mylib = require("mylib")
mylib.utils.trim("  hello  ")
local user = mylib.models.user.new("Alice")

# Install luarocks
brew install luarocks        # macOS

# Install packages (into the system Lua tree)
luarocks install lua-cjson   # C JSON encoder/decoder
luarocks install luasocket   # networking
luarocks install lpeg        # parsing expression grammars
luarocks install luaunit     # testing framework
luarocks install luacheck    # static analyzer

# Project-local installation (doesn't pollute system)
luarocks install --local lua-cjson  # → ~/.luarocks/

# Create a rockspec (package descriptor)
luarocks new-mod  -- generates a template rockspec

-- rockspec: declarative package metadata for luarocks
package = "myproject"
version = "1.0-1"
source = { url = "git+https://github.com/me/myproject.git" }
description = { summary = "A Lua project", license = "MIT" }
dependencies = {
  "lua >= 5.3",
  "lua-cjson >= 2.1",
  "luasocket",
}
build = {
  type = "builtin",
  modules = {
    myproject = "src/myproject.lua",
    ["myproject.utils"] = "src/myproject/utils.lua",
  },
}

-- test.lua
package.preload["db"] = function()
  return {
    query = function(sql) return {"mock", "rows"} end,
  }
end
local app = require("app")  -- app requires "db" → gets the mock

local M = {}
local json  -- not loaded yet
function M.encode(data)
  if not json then json = require("cjson") end  -- load on first call
  return json.encode(data)
end
return M

-- Inside a module chunk, `...` is the module name (for require'd modules)
local module_name = ...  -- "mylib.utils" when require'd as that

-- hooks.lua
hooks["on_tick"] = function() print("tick") end  -- side effect at load time
return {}

-- Evicting and re-requiring registers the hook AGAIN:
package.loaded["hooks"] = nil
require("hooks")  -- hooks["on_tick"] now registered twice → prints "tick" twice per tick

-- bad_module.lua
local x = 1 + 1  -- no return statement
-- require("bad_module") → true (not nil!), subsequent requires return true

-- Always return a table explicitly:
return {}

-- a.lua
local M = {}
local helper = require("a.helper")  -- requires a/helper.lua
function M.process(x) return helper.transform(x) end
return M

-- b.lua
local A = require("a")
function M.use(x) return A.process(x) + 1 end

-- What happens when b.lua is required first?