CLua Documentation

🔧 Helper Functions

CLua provides a set of global helper functions and extensions defined in utils/utils.lua. These are available in all scripts automatically.

🎨 Color Helpers

Used wherever a color value is accepted (e.g. XLSX formatting, GUI).

RGB(r, g, b)            -- {red, green, blue}
RGBA(r, g, b, a)        -- {red, green, blue, alpha}
GRAY(v)                 -- {red=v, green=v, blue=v}
GRAYA(v, a)             -- gray with alpha
BLACK()                 -- RGB(0,0,0)
BLACKA(a)               -- black with alpha
WHITE()                 -- RGB(255,255,255)
WHITEA(a)               -- white with alpha

GetHexColor(rgb)        -- converts RGB table to "#rrggbb" string

local c = RGB(255, 128, 0)
print(GetHexColor(c))   -- "#ff8000"

Note: Neither CLua GUI elements nor XLSX tables use the alpha channel — any alpha value will be ignored.

For more about colors in the context of the GUI, see the Colors & Schemes tab.

📐 XYWH Constructor

Creates a coordinate/size table used for GUI element positioning.

XYWH(x, y, width, height)   -- returns {X, Y, W, H}

🔀 switch

A switch/case pattern for Lua:

switch(value) {
    [1] = function() print("one") end,
    [2] = function() print("two") end,
    default = function() print("other") end,
}

🛡️ safeCall

Wraps a function call in xpcall with debug.traceback as the error handler. Returns true/result on success, or false/traceback on error.

local ok, result = safeCall(myFunction, arg1, arg2)
if not ok then
    print("Error:", result)
end

⏱️ Time Helpers

clock           -- alias for os.clock (CPU time in seconds)

getTime(t)      -- formats a time value (from os.clock) as a readable string

🐛 Debug Helper

debugTracker    -- alias for debug.traceback
                -- preserved before the sandbox disables the debug library

🔤 String Extensions

Extensions added to the standard string library:

Function	Description
`string.trim(s)`	Remove leading and trailing whitespace
`string.rtrim(s)`	Remove trailing whitespace only
`string.ctrim(s)`	Collapse all internal whitespace to single spaces
`string.startswith(s, prefix)`	Returns `true` if `s` starts with `prefix`

local s = "  hello world  "
print(s:trim())               -- "hello world"
print(s:startswith("  he"))   -- true

Two additional global string helpers are also available:

Tab(n)              -- returns a string of n spaces (for indentation)
StripParnt(str)     -- removes content inside [...] brackets (including nested)

print(Tab(4) .. "item")                              -- "    item"
print(StripParnt("foo [bar] baz [x[y]z] end"))       -- "foo  baz  end"

📦 Table Extensions

Extensions added to the standard table library:

Function	Description
`table.contains(tbl, val)`	Returns `true` if `val` is in the table
`table.removeValue(tbl, val)`	Removes the first occurrence of `val`
`table.diff(tblA, tblB)`	Removes from `tblA` all values that are in `tblB`
`table.copytable(orig)`	Deep copy of a table
`table.serialize(val, name, ...)`	Serializes a value to a Lua string representation

local t = {1, 2, 3, 4, 5}
table.diff(t, {2, 4})
-- t is now {1, 3, 5}

🔢 Math Extensions

Extensions added to the standard math library:

Function	Description
`math.odd(n)`	Returns `true` if `n` is odd
`math.even(n)`	Returns `true` if `n` is even
`math.sign(n)`	Returns `-1`, `0`, or `1` based on the sign of `n`
`math.div(a, b)`	Integer division
`math.round(n)`	Round to nearest integer
`math.trunc(n)`	Truncate toward zero
`math.minmax(val, min, max)`	Clamp `val` between `min` and `max`
`math.roundup`	Alias for the original built-in `math.sign` (which behaves as roundup in this Lua build)

⚙️ Macro Utilities

Helper utilities for macro progress tracking and string formatting. Defined in utils/macros_utils.lua.

Progress controller

Used to manage a GUI progress window with up to 3 progress bars.

local prog = newProgress(
    winElement,              -- Window    (from getWindow)
    titleLblElement,         -- Label     (from getLabel)
    { lbl1, lbl2, lbl3 },    -- 3 Label elements        (from getLabel)
    { bar1, bar2, bar3 },    -- 3 ProgressBar elements  (from getProgressBar)
    doneBtnElement,          -- Button    (from getButton)
    cancelBtnElement         -- Button    (from getButton)
)

Parameter	Type	Description
`window`	Window element	The progress window (`getWindow`)
`mainLabel`	Label element	Title label (`getLabel`)
`processLabels`	table of 3 Label elements	One process label per bar (`getLabel`)
`progressBars`	table of 3 ProgressBar elements	Three progress bars (`getProgressBar`)
`returnButton`	Button element	"Done" / return button (`getButton`)
`cancelButton`	Button element	"Cancel" button (`getButton`)

Method	Description
`prog:Init(title, bar1, bar2, bar3)`	Initialize; show/hide each bar (pass `true`/`false`)
`prog:SetTitle(title)`	Update the title label
`prog:SetRange(barID, maxValue)`	Set the maximum value for a bar (used to auto-scale progress)
`prog:SetProces(barID, text)`	Set the process label text for a bar
`prog:SetProgres(barID, value)`	Set progress for a bar (auto-scaled: `value / maxValue`)
`prog:SetButtonVissible(done, cancel)`	Show/hide the return and cancel buttons

prog:Init("Exporting...", true, false, false);
prog:SetRange(1, totalRows);

for i = 1, totalRows do
    prog:SetProces(1, "Row " .. i);
    prog:SetProgres(1, i);
end

prog:SetButtonVissible(true, false);

📋 ListClass

A simple indexed list with automatic ID tracking. Defined in utils/lists.lua.

local list = ListClass.Make(useShift)

If useShift is true, deleted items are compacted (shifted) automatically; otherwise gaps remain.

Each item added to the list receives two fields automatically:

item.inList — reference to the list it belongs to
item.inListID — its index in the list

Method	Description
`list:Add(item)`	Append an item; returns the item
`list:Set(id, item)`	Set item at a specific index
`list:Get(id)`	Get item by index
`list:GetLast()`	Get the last item
`list:Delete(item)`	Remove item by reference
`list:DeleteID(id)`	Remove item by index
`list:FindFree()`	Find the first `nil` slot
`list:FindUsed(start)`	Find the first used slot from `start`
`list:Trim()`	Remove trailing nils; compact if `useShift` is set

local list = ListClass.Make(true);

local a = list:Add({ name = "Alpha" });
local b = list:Add({ name = "Beta" });

print(b.inListID)       -- 2
list:Delete(a);
print(list:Get(1).name) -- "Beta" (shifted)