Tbl

Source: shiva-fw/libs/tbl/init.lua

Table utility library with shallow/deep copy, dot-notation access, merge, pick/omit, and predicate helpers.

Availability

Tbl is a global in every shiva module (loaded by sh_init.lua). No import required.

Copying

Tbl.copy(t)

Shallow copy — top-level keys only.

local copy = Tbl.copy(original)

Tbl.deepCopy(t)

Recursive deep copy.

local copy = Tbl.deepCopy(nested)

Merging

Tbl.merge(...)

Shallow merge of any number of tables. Right values override left.

Tbl.merge({ a = 1 }, { b = 2 }, { a = 99 })  -- { a = 99, b = 2 }

Tbl.deepMerge(base, override)

Recursively merge override into base. Nested tables are merged, not replaced.

Tbl.deepMerge({ db = { host = 'localhost' } }, { db = { port = 3306 } })
-- { db = { host = 'localhost', port = 3306 } }

Dot-Notation Access

Tbl.get(t, path, default?)

Get a value by dot-separated path.

Tbl.get(config, 'database.host', 'localhost')

Tbl.set(t, path, value)

Set a value by dot-separated path. Creates intermediate tables as needed.

Tbl.set(config, 'database.port', 3306)

Tbl.has(t, key)

Check if a key (or dot-notation path) exists.

Tbl.has(config, 'database.host')  -- true/false

Introspection

Tbl.keys(t)      -- { 'a', 'b', 'c' }
Tbl.values(t)    -- { 1, 2, 3 }
Tbl.count(t)     -- works for non-sequential tables (uses pairs)
Tbl.isEmpty(t)   -- true if next(t) == nil
Tbl.isArray(t)   -- true if sequential integer keys from 1..n (no gaps)

Shape Operations

Tbl.flatten(t)

Flatten a nested array one level.

Tbl.flatten({ {1, 2}, {3, 4} })  -- { 1, 2, 3, 4 }

Tbl.pick(t, keys)

Return a new table with only the specified keys.

Tbl.pick(player, { 'id', 'name', 'job' })

Tbl.omit(t, keys)

Return a new table without the specified keys.

Tbl.omit(player, { 'password', 'token' })

Functional

Tbl.map(t, fn)

Transform values. Preserves keys.

Tbl.map({ a = 1, b = 2 }, function(v, k) return v * 2 end)
-- { a = 2, b = 4 }

Tbl.filter(t, fn)

Keep entries where fn(value, key) returns true.

Tbl.filter(players, function(p) return p.level > 10 end)

Tbl.any(t, fn)

Return true if any entry matches.

Tbl.any(players, function(p) return p.isAdmin end)

Tbl.all(t, fn)

Return true if all entries match.

Tbl.all(items, function(item) return item.weight < 10 end)

Immutability

Tbl.freeze(t)

Return a read-only proxy of t. Any write attempt throws an error.

local frozen = Tbl.freeze(constants)

Check if value is in array.

Tbl.contains({ 1, 2, 3 }, 2)  -- true

Tbl.copy(t)

Shallow copy a table.

local copy = Tbl.copy(original)

Tbl.deepCopy(t)

Deep copy a table.

local copy = Tbl.deepCopy(original)

Tbl.size(t)

Count entries in any table.

Tbl.size({ a = 1, b = 2 })  -- 2