explain

Builtin index · REPL & diagnostics

result = explain("fnName")

Input: "fnName" · Output: result

What it is

Takes one argument, fnName (a string naming a user-defined function), and returns a string report — it does not print by itself, so wrap it in print(...) to see it. The report says whether that function is running the fast register-only ("soft-compiled") tier or falls back to the ordinary tree-walking interpreter, and — when interpreted — which construct disqualified it (a call to another user function, a loop, indexing, or a non-numeric value). This is the M4 "Phase 0" diagnostic surface: calling explain triggers the same lazy eligibility check an actual call would, so it works even before the function has ever been called, letting a script author ask "why is this function still slow" and get a real answer instead of a black box.

Overloads

One call shape — this function is not overloaded.

Examples

From the documentation, and run by the build -- the output and the figure below are what the engine actually produced. Simplest first.

function double(x)
    return x * 2
end
print(explain("double"))

from repl-diagnostics

How it works

M4 "Phase 0" scoping, § "explain"): reports whether a user-defined function is running the fast register-only tier or the ordinary interpreter, and why. Triggers the same lazy compile-check try_run_compiled would on an actual call, so explain works even before the function's ever been called.

From the note above this builtin in the interpreter, where the reasoning was written down as it was built.