RedcrabX – ProgramBox Guide

Lua scripting on the worksheet  |  Version 1.0
Available in RedcrabX from version 10.3.0

← Back to Quick Start Guide

Table of Contents

• 1. Overview
• 2. Inserting a ProgramBox
• 3. Box Layout
• 4. Running a Script
• 5. Lua Language Basics
• 6. Reading Worksheet Variables (var, arr)
• 7. Writing Variables to the Worksheet (setvar, setarr)
• 8. Evaluating MathBox Expressions (calc, calcarr)
• 9. Drawing on a DrawBox
• 10. Draw Function Reference
• 11. Examples
• 12. Error Messages
• 13. Tips and Limitations

Lua manual: https://www.lua.org/manual/

1. Overview

The ProgramBox embeds a Lua 5.2 interpreter (MoonSharp) directly in the worksheet. It lets you write small programs with loops, conditions, and functions that can:

• Read any scalar variable from the worksheet via var.name.
• Read any array variable via arr.name as a 1-based Lua table.
• Evaluate MathBox expressions with calc() (scalar) and calcarr() (array).
• Write scalar and array variables back to the worksheet with setvar() and setarr(), triggering automatic recalculation of all MathBoxes.
• Call all DrawBox drawing commands to generate graphics programmatically.
• Print text output that appears in the built-in output view below the editor.

2. Inserting a ProgramBox

1. Click the Code button in the ribbon (Insert in Workspace group).
2. The cursor changes to a crosshair.
3. Click anywhere on the worksheet canvas to place the box.
4. The box can be repositioned by dragging the top handle, and resized by dragging the bottom-right corner.

3. Box Layout

The ProgramBox consists of three areas stacked vertically:

4. Running a Script

There are two ways to run the script:

• Press Ctrl+Enter while the editor is focused.
• Click the ▶ Run button in the status toolbar.

Each run starts a fresh interpreter instance: variables from previous runs do not carry over. The output view is cleared and replaced with the new output.

5. Lua Language Basics

Lua is a lightweight scripting language with a clean, readable syntax. Here is a brief cheat-sheet for users new to Lua:

-- Comments start with two dashes

-- Variables (all variables are global by default; use 'local' for local scope)
local x = 42
local name = "RedcrabX"

-- Arithmetic
local area = math.pi * 5^2     -- ^ is the power operator

-- String formatting
print(string.format("Area = %.4f", area))

-- Conditions
if x > 40 then
    print("x is large")
elseif x == 40 then
    print("exactly 40")
else
    print("x is small")
end

-- Numeric for-loop  (start, stop, step)
for i = 1, 10 do
    io.write(i .. " ")          -- io.write is available in SoftSandbox
end

for i = 0, 360, 30 do          -- step = 30
    print(math.sin(math.rad(i)))
end

-- While loop
local n = 1
while n <= 5 do
    print(n)
    n = n + 1
end

-- Functions
local function square(v)
    return v * v
end
print(square(7))   --> 49

-- Tables (arrays use 1-based indexing)
local pts = {10, 20, 30, 40}
for i = 1, #pts do
    print(pts[i])
end

6. Reading Worksheet Variables

Scalar and array variables defined in MathBox cells on the same worksheet are available in the ProgramBox as two read-only global tables: var for scalars and arr for arrays. Both are snapshots taken at the moment the script starts.

MathBox (define variables)

r  := 50       // radius
cx := 120      // center x
cy := 100      // center y

ProgramBox (read those variables)

local r  = var.r    -- reads the MathBox variable 'r'
local cx = var.cx
local cy = var.cy

print("radius =", r)
print(string.format("center = (%.0f, %.0f)", cx, cy))

Defensive access pattern

-- Use 'or' to supply a default when a variable may be undefined
local r = var.r or 40
print("r =", r)

Reading array variables with arr

Array variables (defined with a range or list in MathBox) are accessible via arr.name. Each value is a 1-based Lua table of numbers.

-- MathBox: data := [1, 4, 9, 16, 25]
local d = arr.data         -- 1-based Lua table
print("length =", #d)
print("first  =", d[1])
print("last   =", d[#d])

-- Iterate over all elements
for i = 1, #arr.data do
    print(i, arr.data[i])
end

7. Writing Variables to the Worksheet

The ProgramBox can write scalar and array values back to the shared variable store, making them instantly visible to all MathBoxes on the worksheet. After any write via setvar or setarr, all MathBoxes are recalculated automatically.

setvar — write a scalar

setvar("result", 42)               -- create or overwrite scalar 'result'
setvar("I", var.U / var.R)         -- derive from existing variables
setvar("area", math.pi * var.r^2)  -- combine Lua math with worksheet variables

setarr — write an array

setarr("samples", {1, 2, 3, 4, 5})   -- write a literal array

-- Build a table dynamically and write it back
local t = {}
for i = 1, 10 do
    t[i] = math.sin(math.rad(i * 36))
end
setarr("wave", t)

Example — Fibonacci sequence

-- MathBox: n := 10
local n = var.n or 10
local a, b = 0, 1
local fibs = {}
for i = 1, n do
    fibs[i] = a
    a, b = b, a + b
end
setarr("fib", fibs)          -- write array back to worksheet
setvar("fib_last", fibs[n])  -- write last value as scalar
print("fib_last =", fibs[n])

8. Evaluating MathBox Expressions

calc and calcarr pass an expression string to the same engine used by MathBox cells. All current worksheet variables (scalars and arrays) are in scope inside the expression string.

calc — scalar expression

-- MathBox variables r, m, c are in scope inside the expression string
local area = calc("pi * r^2")
local E    = calc("m * c^2")
local ohm  = calc("U / I")

print(string.format("area = %.4f", area))

calcarr — array expression

-- Range generator [start..end:step]
local angles = calcarr("[0..360:10]")  -- 37 elements: 0, 10, 20, ..., 360
for i = 1, #angles do
    print(angles[i], math.sin(math.rad(angles[i])))
end

-- Read an existing array variable through the evaluator
local raw = calcarr("measurements")   -- same result as arr.measurements
print("count =", #raw, "  first =", raw[1])

The complete MathBox function library is available

Every function that works in a MathBox cell works identically inside a calc() or calcarr() string — including all special functions, aggregate functions, physics solvers, and electrical formulas. This makes calc / calcarr a particularly powerful bridge: Lua handles loops, conditions, and data structures while the MathBox engine provides the full domain-specific function set.

Example — Special functions element-wise over a range

-- Gamma function: Γ(5) = 4! = 24
print(calc("gamma(5)"))            -- 24

-- Error function at a fixed point
print(calc("erf(1)"))              -- ≈ 0.84270

-- sigmoid applied element-wise via calcarr
local xs  = calcarr("[−3..3:0.5]")
local sig = calcarr("sigmoid([−3..3:0.5])")
for i = 1, #xs do
    print(string.format("x=%5.1f  sigmoid=%.5f", xs[i], sig[i]))
end

-- Bessel function J₀ profile, written back as an array variable
local J0 = calcarr("besselj(0, [0..12:0.25])")
setarr("J0_profile", J0)
print(string.format("%d Bessel values written", #J0))

Example — Aggregate functions on worksheet array variables

-- MathBox: measurements := [3.1, 2.9, 3.4, 3.0, 2.8]
local n      = calc("count(measurements)")
local mean   = calc("sum(measurements) / count(measurements)")
local spread = calc("stddev(measurements)")
print(string.format("n=%d  mean=%.3f  σ=%.3f", n, mean, spread))

-- First differences (delta between successive samples)
local deltas = calcarr("diff(measurements)")
for i = 1, #deltas do
    print(string.format("Δ[%d] = %.4f", i, deltas[i]))
end

Example — Physics and electrical solvers

-- Physics: same named-parameter syntax as in a MathBox cell
local tf = calc("freefall(h=80)")          -- free-fall time from 80 m  [s]
local Ek = calc("kine(m=2, v=10)")         -- kinetic energy ½mv²       [J]
print(string.format("tf = %.3f s,  Ek = %.1f J", tf, Ek))

-- Electrical: parallel resistance of two worksheet variables R1, R2
local Rp = calc("parres(R1, R2)")
print(string.format("R_par = %.4f Ω", Rp))

-- RC voltage drop over a time range, stored as array
local t_vec = calcarr("[0..0.1:0.005]")
local u_vec = calcarr("rccharge(U=230, R=470, C=0.001, t=[0..0.1:0.005])")
setarr("rc_voltage", u_vec)
print(string.format("u(t=0.1 s) ≈ %.2f V", u_vec[#u_vec]))

9. Drawing on a DrawBox

All DrawBox draw functions are available as global Lua functions inside the ProgramBox. First select the target DrawBox with drawtarget, then call any draw function. The coordinate system is the same as in MathBox draw commands: origin at top-left (0, 0), X increases rightward, Y increases downward.

-- Select DrawBox D1 as the drawing target
drawtarget("D1")          -- note: string argument required in Lua

-- Draw a background grid
drawgrid(20)

-- Draw shapes using a loop
for i = 0, 11 do
    local angle = math.rad(i * 30)
    local x = 100 + 60 * math.cos(angle)
    local y = 100 + 60 * math.sin(angle)
    drawdot(x, y, 4)
end

drawtext(82, 10, "Clock positions")

10. Draw Function Reference

All functions below operate on the current DrawBox target set with drawtarget("name"). Coordinates are in pixels; the origin is the top-left corner of the canvas.

11. Examples

Hello World

print("Hello from ProgramBox!")
print("2 + 2 =", 2 + 2)
print(string.format("pi = %.6f", math.pi))

Output:

Hello from ProgramBox!
2 + 2 =    4
pi = 3.141593

Sine table

print(string.format("%-8s %10s %10s", "deg", "sin", "cos"))
print(string.rep("-", 30))
for deg = 0, 360, 30 do
    local r = math.rad(deg)
    print(string.format("%-8.0f %10.4f %10.4f", deg, math.sin(r), math.cos(r)))
end

Read a MathBox variable and use it in a calculation

-- MathBox: voltage := 230   resistance := 47
local U = var.voltage or 230
local R = var.resistance or 100

local I = U / R
local P = U * I

print(string.format("U = %.1f V", U))
print(string.format("R = %.1f Ω", R))
print(string.format("I = %.4f A", I))
print(string.format("P = %.2f W", P))

Draw a clock face on a DrawBox

drawtarget("D1")
drawclear()
drawgrid(20)

local cx, cy, r = 120, 120, 80

-- Outer circle
drawcircle(cx, cy, r)
drawdot(cx, cy, 3)

-- Hour marks
for h = 0, 11 do
    local angle = math.rad(h * 30 - 90)
    local x1 = cx + (r - 8) * math.cos(angle)
    local y1 = cy + (r - 8) * math.sin(angle)
    local x2 = cx + r * math.cos(angle)
    local y2 = cy + r * math.sin(angle)
    drawline(x1, y1, x2, y2)
end

-- Hour labels
local labels = {"12","1","2","3","4","5","6","7","8","9","10","11"}
for h = 0, 11 do
    local angle = math.rad(h * 30 - 90)
    local x = cx + (r - 20) * math.cos(angle) - 4
    local y = cy + (r - 20) * math.sin(angle) - 7
    drawtext(x, y, labels[h + 1])
end

-- Hands  (read from MathBox variables or use defaults)
local hour_angle   = math.rad((var.hh or 10) * 30 + (var.mm or 10) * 0.5 - 90)
local minute_angle = math.rad((var.mm or 10) * 6 - 90)

drawarrow(cx, cy, cx + 0.55 * r * math.cos(hour_angle),
                  cy + 0.55 * r * math.sin(hour_angle))
drawarrow(cx, cy, cx + 0.80 * r * math.cos(minute_angle),
                  cy + 0.80 * r * math.sin(minute_angle))

Draw a regular polygon from a MathBox variable

-- MathBox:  sides := 6    radius := 60
local n  = var.sides  or 6
local r  = var.radius or 60
local cx = 120
local cy = 100

drawtarget("D1")
drawclear()

local pts = {}
for i = 0, n - 1 do
    local angle = math.rad(i * 360 / n - 90)
    pts[#pts + 1] = cx + r * math.cos(angle)
    pts[#pts + 1] = cy + r * math.sin(angle)
end
drawpoly(pts)

drawtext(cx - 10, cy - 8, n .. "-gon")

Annotated dimension sketch

-- MathBox:  w := 120    h := 80
local W = var.w or 120
local H = var.h or 80
local ox, oy = 40, 40   -- origin of the rectangle

drawtarget("D1")
drawclear()
drawgrid(10)

drawrect(ox, oy, H, W)
drawcross(ox, oy, 12)
drawcross(ox + W, oy + H, 12)

-- Width dimension below
drawdim(ox, oy + H, ox + W, oy + H, 20)
drawtext(ox + W/2 - 15, oy + H + 26, W .. " px")

-- Height dimension to the right
drawdim(ox + W, oy, ox + W, oy + H, 20)
drawtext(ox + W + 28, oy + H/2 - 7, H .. " px")

Write a computed result back to the worksheet

-- MathBox: base := 3    height := 5
local b = var.base   or 3
local h = var.height or 5
local area = 0.5 * b * h

setvar("triangle_area", area)   -- MathBoxes that use 'triangle_area' now update
print(string.format("Area = %.4f", area))

Process an array variable and write the result back

-- MathBox: data := [1, 4, 9, 16, 25]
local src = arr.data
if src == nil then print("no 'data' array found") ; return end

local cumsum = {}
local s = 0
for i = 1, #src do
    s = s + src[i]
    cumsum[i] = s
end
setarr("cumsum", cumsum)    -- write cumulative sums back to worksheet
print("total sum =", s)

Evaluate MathBox expressions and generate a range

-- MathBox: f := 1000    L := 0.01
local Xc = calc("1 / (2 * pi * f * L)")
local Xl = calc("2 * pi * f * L")
print(string.format("Xc = %.4f Ω", Xc))
print(string.format("Xl = %.4f Ω", Xl))

-- Build a time vector and a sine wave from it
local t_vec = calcarr("[0..1:0.05]")   -- 0.00, 0.05, 0.10, ..., 1.00
local wave = {}
for i = 1, #t_vec do
    wave[i] = math.sin(2 * math.pi * t_vec[i])
end
setarr("sine_wave", wave)
print(string.format("%d samples written to 'sine_wave'", #wave))

12. Error Messages

13. Tips and Limitations

• Angle convention in draw functions. drawarc always uses degrees (clockwise from east), independent of the MathBox DEG/RAD setting. All other Lua math functions (math.sin, math.cos, etc.) use radians. Use math.rad() and math.deg() to convert.
• Script state is not persistent. Each run starts a fresh interpreter. Global variables defined in one run are not available in the next run.
• DrawBox is not cleared automatically. Unlike MathBox draw commands (which clear on worksheet refresh), ProgramBox does not clear the DrawBox automatically. Call drawclear() at the top of your script if you want a clean canvas on each run.
• Accessing undefined variables. If a scalar variable is not defined, var.name returns nil; if an array variable is not defined, arr.name returns nil. Use var.name or default to supply a fallback value and guard array access with if arr.name == nil then … end.
• Naming the ProgramBox. The name field (P1 by default) is saved with the workspace. It is not yet used as a target for other boxes, but serves as a label for identification.
• No file I/O. The sandbox blocks io.open, os.execute, and require. Standard output via print() is fully available.
• Performance. The Lua interpreter starts fresh on every run, which adds a small fixed overhead of a few milliseconds. Scripts with up to tens of thousands of loop iterations are fast.
• setvar / setarr trigger recalculation; var / arr do not. Reading var.x or arr.x is purely passive and never changes the worksheet. Only setvar and setarr write back and cause MathBoxes to update.
• Do not pass a table to setvar. setvar("x", {1,2,3}) raises a runtime error. Use setarr for array values and setvar only for single numbers.

RedcrabX ProgramBox Guide  —  further topics: Quick Start Guide  |  DrawBox Guide  |  MathBox Guide  |  Chart Guide  |  Plot Guide