Lua Scripting

VisiGrid includes a sandboxed Lua console for automating tasks and manipulating data programmatically. All operations are transactional and fully undoable.

Desktop only

The Lua console is part of the desktop app. It is not in the browser app.

Opening the Console

Press Alt+F11 to toggle the Lua console panel. On first open, the input is pre-filled with examples — press Enter to see available scripts.

Console Editor

The input area is a mini code editor with:

• Syntax highlighting — keywords, strings, numbers, comments, and operators are color-coded
• Line numbers with active line highlight
• Auto-expanding input — grows up to 12 visible lines as you type, scrolls beyond that
• Clipboard support — Ctrl+C/V/X work directly in the console input

Grouped Output

Each execution produces a visually distinct output block:

┌ sheet:get("A1")                         ┐
│ 42                                       │
└ ops: 1 | cells: 0 | time: 0.1ms         ┘
──────────────────────────────────────────
┌ for r = 1, 10 do                        ┐
│   sheet:set("A" .. r, r * 2)             │
│ end                                      │
│ nil                                      │
└ ops: 10 | cells: 10 | time: 1.2ms       ┘

Each block shows the input (accent-bordered), output lines, and a dimmed stats footer. Blocks are separated by a divider.

Console Commands

Type these directly in the input:

Command	Description
help	Show all commands and shortcuts
examples	List available example scripts
example N	Load example N into input
clear	Clear output history

Built-in Examples

#	Name	Description
1	Fill Series	Fill A1:A10 with powers of 2
2	Trim Whitespace	Remove leading/trailing spaces from column A
3	Find Duplicates	Find and report duplicate values in column A
4	Normalize Dates	Convert date formats to YYYY-MM-DD
5	Compare Columns	Find mismatches between columns A and B
6	Generate Multiplication Table	Create 10x10 table starting at A1
7	Sum Column	Calculate sum and average of numbers in column A

Load any example: example 1 or example "Fill Series"

Sheet API

All coordinates are 1-indexed to match spreadsheet conventions.

Cell Access

Method	Description
sheet:get("A1")	Get value using A1 notation (shorthand)
sheet:set("A1", val)	Set value using A1 notation (shorthand)
sheet:get_value(row, col)	Get typed value by row/col
sheet:set_value(row, col, val)	Set cell value
sheet:get_formula(row, col)	Get formula string or nil
sheet:set_formula(row, col, f)	Set formula

Sheet Info

Method	Description
sheet:rows()	Number of rows with data
sheet:cols()	Number of columns with data
sheet:selection()	Current selection (see below)

Selection API

local sel = sheet:selection()
print(sel.range)      -- "A1:C5"
print(sel.start_row)  -- 1
print(sel.start_col)  -- 1
print(sel.end_row)    -- 5
print(sel.end_col)    -- 3

Range API (Bulk Read/Write)

local r = sheet:range("A1:C5")

-- Read all values as 2D table
local data = r:values()
print(data[1][1])  -- value at A1
print(data[2][3])  -- value at C2

-- Write 2D table to range
r:set_values({
    {1, 2, 3},
    {4, 5, 6},
    {7, 8, 9}
})

-- Range info
r:rows()     -- → 5
r:cols()     -- → 3
r:address()  -- → "A1:C5"

Transaction Control

Method	Description
sheet:begin()	Start transaction (noop, for clarity)
sheet:rollback()	Discard pending changes, returns count
sheet:commit()	Commit changes (noop, auto-commits at end)

Example Scripts

-- Fill column with sequence
for i = 1, 100 do
    sheet:set("A" .. i, i * 2)
end
print("Filled 100 cells")

-- Process current selection
local sel = sheet:selection()
for row = sel.start_row, sel.end_row do
    for col = sel.start_col, sel.end_col do
        local val = sheet:get_value(row, col)
        if type(val) == "number" then
            sheet:set_value(row, col, val * 1.1)  -- +10%
        end
    end
end

-- Bulk transform with Range
local r = sheet:range("A1:C10")
local data = r:values()

for i, row in ipairs(data) do
    for j, val in ipairs(row) do
        if type(val) == "number" then
            data[i][j] = val * 2
        end
    end
end

r:set_values(data)

-- Conditional rollback
sheet:begin()
for i = 1, 100 do
    sheet:set("A" .. i, math.random(1, 100))
end

local sum = 0
for i = 1, 100 do
    sum = sum + (sheet:get("A" .. i) or 0)
end

if sum > 5000 then
    local discarded = sheet:rollback()
    print("Rolled back " .. discarded .. " ops (sum too high)")
else
    print("Sum: " .. sum)
end

Keyboard Shortcuts

Action	Shortcut
Toggle console	Alt+F11
Execute script	Enter or Ctrl+Enter
Newline (multiline)	Shift+Enter
Previous command	Up Arrow
Next command	Down Arrow
Copy	Ctrl+C
Paste	Ctrl+V
Cut	Ctrl+X
Scroll output up	Page Up
Scroll output down	Page Down
Scroll to top	Ctrl+Home
Scroll to bottom	Ctrl+End
Clear output	Ctrl+L
Close console	Escape

Execution Stats

After each script runs, the console shows:

ops: 100 | cells: 50 | time: 12.5ms

• ops: Total operations queued
• cells: Unique cells modified (deduplicated)
• time: Wall-clock execution time

Sandboxing and Safety

Enabled Libraries: table, string, math, utf8

Disabled (for security): os, io, debug, package, require, load, loadfile, dofile

Resource Limits

Limit	Value
Operations	1,000,000
Output lines	5,000
Instructions	100,000,000
Wall-clock	30 seconds

Safety Guarantees

• No filesystem or network access
• Single undo entry per script (Ctrl+Z reverses entire script)
• Deterministic execution (same input = same output)