Formula tokens and user functions

HotXLS exposes caller-owned formula token streams for lossless inspection and guarded writeback in both workbook engines, plus hierarchical user-function registries for custom calculation

Token model

TXLSFormulaTokenClass, TXLSFormulaTokenKind, and TXLSFormulaTokenSource classify each TXLSFormulaToken and record whether it came from parsed text, classic BIFF bytes, or another supported source

Syntax tree

CloneSyntaxTree returns a caller-owned parsed tree of TXLSSyntaxItem nodes for structural inspection: each node reports its ItemType, literal payload (Value, IntValue, DecValue), leading Spaces, tree links (Parent, Child, ChildCount), the reference leaf as a TXLSRangeItem through Range, and array-constant data (ArrayRows, ArrayCols, ArrayValueCount, and the TXLSArraySerVal entries in ArrayValues). The tree is a detached copy, so walking it never touches the workbook's compiled formulas, and the mutation members (AddChild, PushChild, CopyObject, OffsetCopyReferences, AdjustForShift, and TXLSRangeItem.CopyObject / AdjustForShift) exist for tools that rewrite a cloned tree before recompilation

Workbook entry points

Tokens := Worksheet.ParseFormulaTokens('SUM(A1:A4)', 1, 1);
try
  if Tokens.ReplaceReference(OldRef, NewRef) then
    Worksheet.SetFormulaTokens(1, 1, Tokens);
finally
  Tokens.Free;
end;

ParseFormulaTokens, GetFormulaTokens, FormulaTokensToText, and SetFormulaTokens keep ownership explicit and validate context, BIFF version, token support, array ownership, and reference bounds before a cell is changed

User-function registries

TXLSUserFunctionResolver and TXLSUserFunctionRegistry provide by-name lookup through RegisterHandler, UnregisterHandler, Clear, Contains, TryGetHandler, and Count

Workbook.RegisterUserFunction('NETMARGIN', CalculateNetMargin);
Workbook.RegisterGlobalUserFunction('FISCALYEAR', CalculateFiscalYear);
try
  Workbook.Calculate;
finally
  Workbook.UnregisterUserFunction('NETMARGIN');
  Workbook.UnregisterGlobalUserFunction('FISCALYEAR');
end;

IXLSWorkbook, TXLSWorkbook, and TXLSXWorkbook expose RegisterUserFunction, UnregisterUserFunction, ClearUserFunctions, RegisteredUserFunctionCount, RegisterGlobalUserFunction, UnregisterGlobalUserFunction, ClearGlobalUserFunctions, and RegisteredGlobalUserFunctionCount

The equivalent unit-level entry points are XLSRegisterGlobalUserFunction, XLSUnregisterGlobalUserFunction, XLSClearGlobalUserFunctions, XLSRegisteredGlobalUserFunctionCount, and XLSGlobalUserFunctionRegistered

TXLSCalculator.OnUserFunctionResolve participates before the legacy event fallback, and registry handlers are invoked outside the registry lock so a handler may unregister itself safely

Dangerous external and macro-style function names are blocked before argument evaluation and handler lookup unless AllowUnsafeFormulaCallbacks is explicitly enabled for the workbook or the individual contextual evaluation; ordinary user-function names remain available by default

Formula diagnostics

TXLSXFormulaIssueKind, TXLSXFormulaLocation, and TXLSXFormulaIssue are returned by TXLSXWorkbook.AnalyzeFormulaIssues for missing functions, external references, and circular dependency components

Macro-sheet inspection

TXLSSheetKind distinguishes worksheet, macro sheet, chart sheet, VBA module, and unknown sheet records through TXLSWorksheet.SheetKind; TXLSMacroRisk, TXLSMacroCommandInfo, and TXLSMacroCommandArray describe the typed results from TXLSWorksheet.ScanMacroCommands

Merged AutoFit and sorting types

TXLSMergedAutoFitStrategy and TXLSXMergedAutoFitStrategy choose first, last, or balanced growth for merged spans, while TXLSSortOrientation, TXLSSortFormulaMode, and TXLSSortCompareEvent control vertical or horizontal stable sorting and formula movement

See also

• Excel calculation engine
• Formula trace and audit
• Advanced workbook workflows