Luau Examples

This page demonstrates some simple functions. It also introduces xllify's async Luau support.

Some of the examples are contrived and already implemented by Excel, so see them merely as illustrations.

Basic maths

example.luau

xllify.ExcelFunction({
    name = "ADD",
    category = "Math"
}, function(x, y)
    return x + y
end)

xllify.ExcelFunction({
    name = "MULTIPLY",
    category = "Math"
}, function(x, y)
    return x * y
end)

String operations

example.luau

xllify.ExcelFunction({
    name = "UPPER"
}, function(text)
    return string.upper(text)
end)

xllify.ExcelFunction({
    name = "WORDCOUNT"
}, function(text)
    local count = 0
    for word in string.gmatch(text, "%S+") do
        count = count + 1
    end
    return count
end)

Working with ranges

example.luau

xllify.ExcelFunction({
    name = "SUMRANGE",
    description = "Sum all numbers in range"
}, function(data)
    local sum = 0
    for i = 1, #data do
        for j = 1, #data[i] do
            if type(data[i][j]) == "number" then
                sum = sum + data[i][j]
            end
        end
    end
    return sum
end)

Usage: =SUMRANGE(A1:C10)

Date functions

example.luau

xllify.ExcelFunction({
    name = "TIMESTAMP"
}, function()
    return os.date("%Y-%m-%d %H:%M:%S")
end)

xllify.ExcelFunction({
    name = "ISLEAPYEAR"
}, function(year)
    return (year % 4 == 0 and year % 100 ~= 0) or (year % 400 == 0)
end)

Async example

Luau functions when marked as async do not block the thread they're running on. They run within a pool of worker threads. async.* functions automatically yield their thread and resume when the operation completes.

example.luau

xllify.ExcelFunction({
    name = "SLOWCALC",
    execution_type = "async"
}, function(seconds)
    -- Simulate delay
    async.sleep(seconds) # will yield until seconds elapses!
    return "Done after " .. seconds .. " seconds"
end)

Multiple scripts

math.luau

xllify.ExcelFunction({
    name = "SQUARE"
}, function(x)
    return x * x
end)

xllify.ExcelFunction({
    name = "CUBE"
}, function(x)
    return x * x * x
end)

text.luau

xllify.ExcelFunction({
    name = "REVERSE"
}, function(text)
    return string.reverse(text)
end)

Build:

build.sh

xllify MyAddin.xll math.luau text.luau

All functions will be available in Excel.

Combining Luau and Python

You can mix Luau and Python in one XLL for the best of both worlds.

fast_math.luau

xllify.ExcelFunction({
    name = "FASTSUM",
    description = "SUM not good enough for you?"
}, function(data)
    local sum = 0
    for i = 1, #data do
        for j = 1, #data[i] do
            if type(data[i][j]) == "number" then
                sum = sum + data[i][j]
            end
        end
    end
    return sum
end)

api_calls.py

import xllify
import requests

@xllify.fn("xllipy.FetchPrice")
def fetch_price(symbol: str) -> float:
    """Fetch stock price from API"""
    resp = requests.get(f"https://api.example.com/price/{symbol}")
    return resp.json()["price"]

Build:

build.sh

xllify HybridAddin.xll fast_math.luau api_calls.py \
    --py-entrypoint api_calls \
    --py-requirements requirements.txt

Load HybridAddin.xll into Excel:

=FASTSUM(A1:Z100)           → Ultra-fast Luau calculation
=xllipy.FetchPrice("AAPL")  → Python API call with requests library