Compiler and static analysis

Turning source into a closure, and configuring the diagnostics that run with it.

Compiler

sq_compile is enough for most hosts. It takes a buffer and leaves a callable closure on the stack. The AST entry points below it are for tools that want the tree: a formatter, a coverage pass, an analyzer run without codegen. They follow the pipeline the compiler uses internally: parse, analyze, translate.

SQRESULT sq_compile(HSQUIRRELVM v, const char *s, SQInteger size, const char *sourcename, SQBool raiseerror, const HSQOBJECT *bindings = nullptr)

Compiles a source buffer and pushes the result as a closure. Nothing runs until that closure is called.

SQCompilation::SqASTData *sq_parsetoast(HSQUIRRELVM v, const char *s, SQInteger size, const char *sourcename, SQBool preserveComments, SQBool raiseerror)

Parses source into an AST without generating bytecode.

SQRESULT sq_translateasttobytecode(HSQUIRRELVM v, SQCompilation::SqASTData *astData, const HSQOBJECT *bindings, const char *s, SQInteger size, SQBool raiseerror)

Generates a closure from an AST already parsed and analyzed.

void sq_analyzeast(HSQUIRRELVM v, SQCompilation::SqASTData *astData, const HSQOBJECT *bindings, const char *s, SQInteger size)

Runs the static analyzer over an AST and reports its diagnostics.

void sq_checktrailingspaces(HSQUIRRELVM v, const char *sourceName, const char *s, SQInteger size)

Makes the compiler report trailing whitespace as a diagnostic.

SQRESULT sq_getimports(HSQUIRRELVM v, SQCompilation::SqASTData *astData, SQInteger *num, SQModuleImport **imports)

Returns the list of modules a compiled unit imports.

void sq_freeimports(HSQUIRRELVM v, SQInteger num, SQModuleImport *imports)

Frees the import list returned by sq_getimports.

void sq_dumpast(HSQUIRRELVM v, SQCompilation::SqASTData *astData, bool nodesLocation, SQStreamWriteFunc write, void *ud)

Writes a parsed AST in readable form, as the -ast-dump command line flag does.

void sq_dumpbytecode(HSQUIRRELVM v, HSQOBJECT obj, SQStreamWriteFunc write, void *ud, int instruction_index = -1)

Writes the bytecode of a compiled closure in readable form.

void sq_reset_static_memos(HSQUIRRELVM v, HSQOBJECT func)

Clears every cached static expression, so each is evaluated again on next use.

SQCompilation::SqASTData *sq_allocateASTData(HSQUIRRELVM v)

Allocates the arena an AST lives in. Release it with sq_releaseASTData.

void sq_releaseASTData(HSQUIRRELVM v, SQCompilation::SqASTData *astData)

Frees an AST arena and everything allocated from it.

void sq_setcompilationoption(HSQUIRRELVM v, enum CompilationOptions co, bool value)

Turns one compilation option on or off for this VM.

bool sq_checkcompilationoption(HSQUIRRELVM v, enum CompilationOptions co)

Reports whether a compilation option is on.

void sq_enablevartrace(HSQUIRRELVM v, SQBool enable)

Turns on recording of where a container field was last written, for debugging.

SQBool sq_isvartracesupported(void)

Reports whether this build was compiled with variable tracing.

void sq_lineinfo_in_expressions(HSQUIRRELVM v, SQBool enable)

Makes the compiler emit line information inside expressions, for finer error positions.

void sq_notifyallexceptions(HSQUIRRELVM v, SQBool enable)

Enable/disable the error callback notification of handled exceptions.

void sq_setcompilererrorhandler(HSQUIRRELVM v, SQCOMPILERERROR f)

Sets the compiler error handler function.

void sq_setcompilerdiaghandler(HSQUIRRELVM v, SQ_COMPILER_DIAG_CB f)

Sets the compiler diagnostic callback function.

SQCOMPILERERROR sq_getcompilererrorhandler(HSQUIRRELVM v)

Gets the current compiler error handler function.

void sq_set_table_iter_seed(HSQUIRRELVM v, SQUnsignedInteger32 iter_seed)

Sets the seed that randomizes table iteration order, which keeps scripts from depending on it.

Static analysis

Diagnostic state is process-wide, not per VM, so a host configures it once at startup. A diagnostic can be addressed by name or by number. sq_printwarningslist writes the full set.

void sq_resetanalyzerconfig(void)

Returns every diagnostic to its default state.

bool sq_loadanalyzerconfig(const char *configFileName)

Loads analyzer settings from a file.

bool sq_loadanalyzerconfigblk(const KeyValueFile &config)

Loads analyzer settings from an already parsed key-value file.

bool sq_setdiagnosticstatebyname(const char *diagId, bool val)

Turns one diagnostic on or off by name.

bool sq_setdiagnosticstatebyid(int32_t id, bool val)

Turns one diagnostic on or off by number.

void sq_printwarningslist(FILE *ostream)

Writes every diagnostic the analyzer knows, as --warnings-list does.

void sq_enablesyntaxwarnings(bool on)

Turns the syntax-level warnings on or off.

void sq_checkglobalnames(HSQUIRRELVM v)

Reports uses of global names that no compilation unit defines.

void sq_mergeglobalnames(const HSQOBJECT *bindings)

Adds a bindings object's names to the set sq_checkglobalnames accepts.