Skip to content

Miscellaneous Utility Functions

Jump to bottom
Shadowfen edited this page Jul 30, 2026 · 9 revisions

Utility Functions Reference

This section documents the miscellaneous helper functions provided by LibSFUtils. These utilities simplify common Lua tasks, provide safer function invocation, assist with argument handling, formatting, addon metadata, chat output, and several ESO-specific conveniences.

Argument Utilities

iter_args(...)

Creates an iterator for a variable argument list without requiring Lua 5.2's table.pack().

Unlike iterating over a temporary table directly, the iterator returns the current argument index, the argument value, and the total number of arguments on each iteration.

Syntax

for index, value, total in sfutil.iter_args(...) do
    ...
end

Parameters

Parameter Description
... Any number of arguments.

Returns

An iterator function returning:

Return Description
index Current argument index.
value Current argument value.
total Total number of arguments originally supplied.

Example

for i, value, total in sfutil.iter_args("a", 5, true) do
    d(i, value, total)
end

Output

1    a      3
2    5      3
3    true   3

Function Utilities

closure(callback, tblself, ...)

Creates a closure that binds a callback function to a specific self table and optionally pre-binds one or more leading arguments.

The returned function behaves like a partially applied function. When it is called, the bound arguments are supplied first, followed by any arguments passed to the returned function.

This is useful for:

  • Registering callbacks that require a specific object as self.
  • Creating event handlers with preconfigured arguments.
  • Implementing partial function application.

Syntax

local fn = sfutil.closure(callback, tblself, ...)

Parameters

Parameter Description
callback Function to invoke when the closure is called.
tblself Table passed as the first argument to callback. May be nil for normal functions.
... Optional arguments to bind to the callback. These are inserted before the arguments supplied when the returned function is called.

Returns

A function that calls:

callback(tblself, boundArgs..., runtimeArgs...)

Examples

Bind only self 

local update = sfutil.closure(MyObject.Update, MyObject)

update(10, 20)

Equivalent to:

MyObject.Update(MyObject, 10, 20)

Bind self and leading arguments

local addFive = sfutil.closure(MyObject.AddValue, MyObject, 5)

addFive(10)

Equivalent to:

MyObject.AddValue(MyObject, 5, 10)

Bind a normal function

tblself may be nil when binding a regular function.

local greet = sfutil.closure(print, nil, "Hello")

greet("World")

Equivalent to:

print("Hello", "World")

Notes

  • Bound arguments are supplied before any arguments provided when the returned function is invoked.
  • The callback is not executed until the returned function is called.
  • This function provides a simple form of partial application, allowing commonly used arguments to be fixed in advance.
  • Intended for Lua 5.1 compatibility and does not require table.pack().

WrapFunction([namespace], functionName, wrapper)

Wraps an existing function so that all future calls are redirected through a wrapper function.

The wrapper receives the original function as its first argument, followed by the arguments supplied by the caller. This allows the wrapper to intercept, modify, extend, or completely replace the original function's behavior.

If no namespace is supplied, the function is assumed to exist in the global namespace (_G).

This utility is useful for:

  • Hooking existing functions
  • Logging or debugging function calls
  • Profiling execution time
  • Injecting additional behavior before or after a function executes
  • Temporarily overriding existing implementations

This function is primarily intended for debugging as it likely does not play well with other addons!

Syntax

Wrap a global function:

sfutil.WrapFunction(functionName, wrapper)

Wrap a function in a table (namespace):

sfutil.WrapFunction(namespace, functionName, wrapper)

Parameters

Parameter Description
namespace (Optional) Table containing the function to wrap. If omitted, _G is used.
functionName Name of the function to wrap.
wrapper Function that will replace the original function. It receives the original function as its first argument.

Wrapper Signature

function wrapper(originalFunction, ...)
Parameter Description
originalFunction The original function being wrapped.
... Arguments passed by the caller.

The wrapper may:

  • Call the original function.
  • Modify the arguments before calling it.
  • Modify the return values.
  • Skip calling the original function entirely.

Returns

Nothing.

The specified function is replaced with a wrapped version.

Examples

Wrap a Global Function

function SayHello(name)
    d("Hello " .. name)
end

sfutil.WrapFunction("SayHello",
    function(original, name)
        d("Before")
        original(name)
        d("After")
    end)

SayHello("Alice")

Output:

Before
Hello Alice
After

Wrap a Namespaced Function

MyAddon = {}

function MyAddon.Update(value)
    d("Updating:", value)
end

sfutil.WrapFunction(MyAddon, "Update",
    function(original, value)
        d("Intercepted")
        return original(value)
    end)

MyAddon.Update(42)

Output:

Intercepted
Updating: 42

Modify Arguments

The wrapper can alter the arguments before forwarding them.

sfutil.WrapFunction(MyAddon, "Update",
    function(original, value)
        return original(value * 2)
    end)

Calling

MyAddon.Update(10)

actually invokes

original(20)

Replace the Original Function

The wrapper is not required to call the original function.

sfutil.WrapFunction("DangerousFunction",
    function(original, ...)
        d("DangerousFunction has been disabled.")
    end)

Every call to DangerousFunction() now prints a message without executing the original implementation.

Notes

  • Wrapping affects all subsequent calls to the function.
  • The original function is preserved only within the wrapper as the first parameter.
  • Wrappers can modify arguments, return values, or completely replace the original behavior.
  • Multiple calls to WrapFunction() on the same function create nested wrappers, with the most recently installed wrapper executing first.
  • This utility is particularly useful for debugging, instrumentation, and extending third-party code without modifying its source.
  • Function cannot be 'unwrapped'.

Safe Function Calls

safeCall10(fn, ...)

Executes a function inside pcall() and safely returns up to ten return values without creating a temporary table.

This version minimizes memory allocations and is useful for frequently called functions.

Syntax

local ok, result1, result2 = sfutil.safeCall10(fn, ...)

Returns

Return Description
ok true if the call succeeded.
remaining Up to ten return values from the function.

On failure

false, errorMessage

Example

local ok, value = sfutil.safeCall10(MyFunction)

safeCall(fn, ...)

Executes a function safely using pcall().

Unlike safeCall10(), this version preserves every return value by storing them temporarily in a table.

Syntax

local ok, ... = sfutil.safeCall(fn, ...)

Returns

Return Description
ok Success flag.
remaining All values returned by the function.

Example

local ok, a, b, c, d = sfutil.safeCall(MyFunction)

Boolean Utilities

bool2str(bool)

Converts a boolean value into "true" or "false".

Example

sfutil.bool2str(true)

Returns

true

str2bool(str)

Converts a string representation into a boolean.

Accepted true values:

  • "true"
  • "1"

Everything else returns false.

Example

sfutil.str2bool("true")

Returns

true

isTrue(value)

Performs a stricter boolean test than Lua's built-in truthiness.

Returns true only for the following values:

  • true
  • "true"
  • 1
  • "1"

Everything else returns false.

Example

sfutil.isTrue("1")

Returns

true

Default Value Utilities

nilDefault(value, default)

Returns default only if value is nil.

Unlike Lua's or operator, false is preserved.

Example

local enabled = sfutil.nilDefault(saved.enabled, false)

nilDefaultStr(value, default)

Returns default if the value is either:

  • nil
  • an empty string

Example

local name = sfutil.nilDefaultStr(userName, "Unknown")

Addon Metadata

addonMeta(namespace, addonName)

Creates or populates a table containing information about the current addon and player.

Collected Fields

Field Description
addonName Addon name.
server Current world/server name.
account Account display name.
charId Character ID.
charName Character name.
fmtCharName Formatted character name.
API Current ESO API version.

Example

local meta = sfutil.addonMeta("MyAddon")

Time Utilities

secondsToClock(seconds)

Converts a number of seconds into an HH:MM:SS string.

Example

sfutil.secondsToClock(3665)

Returns

01:01:05

System Chat Utilities

initSystemMsgPrefix(addonName[, color])

Creates a colored prefix suitable for addon chat messages.

Example

local prefix = sfutil.initSystemMsgPrefix("MyAddon")

Produces something similar to

[MyAddon]

with color formatting applied.

systemMsg(prefix, text[, color])

Displays a colored message in the ESO system chat.

Example

sfutil.systemMsg(prefix, "Settings loaded.")

AddonChatter and SlashHelp Utilities

addonChatter provides a complete lightweight messaging to chat system for ESO addons.

Centralized Formatting

All chat output uses the same:

  • Addon Identifier Prefix.
  • Normal color.
  • Debug color.
  • Formatting rules.

This keeps addon messages consistent and easier to maintain.

Main features:

Feature Function
Create chat handler New()
Normal messages systemMessage()
Debug messages debugMsg() / d()
Enable debugging enableDebug()
Disable debugging disableDebug()
Toggle debugging toggleDebug()
Check debug state isDebugEnabled()
Configure colors setNormalColor() / setDebugColor()
Display command help slashHelp()

It is designed to provide simple, consistent, and efficient addon communication.

For more details, look at AddonChatter & SlashHelp Chat Utilities

Summary

These utility functions provide convenient wrappers around many common Lua and ESO programming tasks, including:

  • Safe function invocation
  • Argument iteration
  • Closure creation
  • Function wrapping
  • Boolean conversion
  • Default value handling
  • Addon metadata collection
  • Time formatting
  • System chat output
  • Debug message management

They are intended to reduce boilerplate while providing consistent behavior throughout an addon.

Clone this wiki locally