CrLua.ttslua

-------------------------------------------------------------------------------
--- Create the base CrLua table, with require function for dependencies.
-- @author Darrell
--
-- Suggested use: at the END of the object script (so #include does not affect
-- line number reporting in the above portion), include CrLua and dependencies:
--
-- #include <~/CrLua/CrLua>
-- #include <~/CrLua/LockGlobals>
--
-- #include <~/CrLua/[OTHER_DEPENDENCY]> (repeat)
--
-- CrLua.assertRequired() -- do this BEFORE lock
-- CrLua.lock()
--
-- -- Optionally enable logging.
-- CrLua.Log.setLogLevel(CrLua.Log.LOG_LEVEL.DEBUG)
-------------------------------------------------------------------------------

local TAG = 'CrLua'

-- Create a GLOBAL CrLua table.
CrLua = CrLua or {}  -- global, <include> wraps in a do .. end block
CrLua._require = { 'LockTable' }

-------------------------------------------------------------------------------
--- Assert all required packages exist.
-- @param extraRequires table : list of additional require entries.
-- @param table : table to search for _require entries, or CrLua if nil.
--
-- Modules add dependencies by having a _require item in their root table,
-- with a list of module names.
-- e.g. CrLua.MyModule = { _require = { 'OtherModule1', 'OtherModule2' } }.
-------------------------------------------------------------------------------
function CrLua.assertRequired(extraRequires, table)
    local seen = {}
    local requireSet = {}
    local haveSet = {}

    if extraRequires then
        for _, name in ipairs(extraRequires) do
            requireSet[name] = true
        end
    end

    local function addRequireEntries(table, packagePath)
        assert(type(table) == 'table')
        if seen[table] then
            return
        end
        seen[table] = true
        if table._require then
            for _, name in ipairs(table._require) do
                requireSet[name] = true
            end
            if packagePath then
                haveSet[packagePath] = true
            end
        end
        for k, v in pairs(table) do
            if type(v) == 'table' and not string.match(k, '^[_%l]') then
                local recurse = type(k) == 'string' and string.match(k, '^%u')
                if recurse then
                    local childPackagePath = (packagePath and (packagePath .. '.') or '') .. k
                    addRequireEntries(v, childPackagePath)
                end
            end
        end
    end
    addRequireEntries(table or CrLua)

    -- Make sure all required packages are present.
    local message = false
    for package, _ in pairs(requireSet) do
        assert(type(package) == 'string')
        -- Descend dot-delimited sub-package names.
        local entry = CrLua
        for subPackage in string.gmatch(package, '[^%.]+') do
            entry = entry and entry[subPackage]
        end
        if not entry then
            message = (message and message .. ', ' or '') .. package
        end
    end
    if message then
        error(TAG .. ': assertRequired missing ' .. message)
    end

    -- Make sure all present packages are required.
    local message = false
    for package, _ in pairs(haveSet) do
        if not requireSet[package] then
            message = (message and message .. ', ' or '') .. package
        end
    end
    if message then
        error(TAG .. ': assertRequired have not-required ' .. message)
    end

end

-------------------------------------------------------------------------------
--- Lock CrLua packages.
--
-- @param tableName string : name of table being locked, or nil for CrLua.
-- @param table : table being locked, or nil for CrLua.
--
-- Make CrLua and nested packages read-only, with access requiring keys exist.
--
-- Locking rules:
--
-- (1.) '_data' is a reserved table name for mutable tables.  Do not lock.
--
-- (2.) If the table starts with a capital letter, make it read-only and
-- require keys exist.  These are packages or constants, attempting to access
-- a missing field is probably a typo.  (Override by adding an
-- _allowMissingKeys = { 'tableName1', 'tableName2'} entry at the same level
-- as the referenced tables.  Such tables allow reads to missing keys, as well
-- as all sub-tables in them.)
--
-- (2.) Otherwise make it read-only but allow reads to missing keys (value nil).
-- One can query membership by checking if a key exists.
--
-- This helps catch typos calling non-existent functions, or overwriting
-- a constant value by mistake.
-------------------------------------------------------------------------------
function CrLua.lock(tableName, table)
    local seen = {}

    local function lockRecursive(tableName, table, allowMissingKeys)
        assert(type(tableName) == 'string' and type(table) == 'table' and type(allowMissingKeys) == 'boolean')

        -- Watch out for cycles!  This might happen if a script defines
        -- an enum table, then later uses one of them in a different table.
        if seen[table] then
            return
        end
        seen[table] = true

        -- Leave _data tables alone.
        local isData = tableName == '_data'
        if isData then
            return
        end

        -- Get any missing keys entry BEFORE locking this table.
        local allowMissingKeysTableNameSet = {}
        if table._allowMissingKeys then
            for _, tableName in ipairs(table._allowMissingKeys) do
                allowMissingKeysTableNameSet[tableName] = true
            end
        end

        -- Lock the given table.
        local firstLetter = string.match(tableName, '%a')
        local isUpper = firstLetter and firstLetter == string.upper(firstLetter)
        if isUpper and not allowMissingKeys then
            CrLua.LockTable.readOnlyRequireKey(tableName, table)
        else
            CrLua.LockTable.readOnly(tableName, table)
        end

        -- Lock sub-tables, respecting _allowMissingKeys values.
        for k, v in pairs(table) do
            if type(v) == 'table' then
                local entryAllowMissingKeys = allowMissingKeys or allowMissingKeysTableNameSet[k] or false
                lockRecursive(tostring(k), v, entryAllowMissingKeys)
            end
        end
    end

    lockRecursive(tableName or 'CrLua', table or CrLua, false)
end