Quirrel4.41.0

Standard library

Registering the standard modules, and the C entry points they expose to a host.

No part of the standard library is loaded automatically. A host registers the modules it wants a script to reach. This is how a sandbox is built: leave out io and system, and no script can open a file or run a command.

Each sqstd_register_*lib expects the target table on the stack. The other functions here let C code use what those modules implement: read a blob's bytes, open a file as a stream, run a regular expression.

Registration and error reporting

Most hosts want sqstd_seterrorhandlers early. Without it, an unhandled error leaves no trace.

void sqstd_seterrorhandlers(HSQUIRRELVM v)

Installs the standard error and compiler error handlers, which print the message and the call stack.

void sqstd_printcallstack(HSQUIRRELVM v)

Prints the current call stack through the VM's print function.

SQRESULT sqstd_formatcallstackstring(HSQUIRRELVM v)

Pushes the current call stack rendered as a string.

void sqstd_aux_error_to_string(HSQUIRRELVM v, SQInteger idx)

Renders the value of a thrown error as a string.

SQRESULT sqstd_formaterrortracestring(HSQUIRRELVM v, HSQOBJECT trace)

Push `trace` (the captured async-fault trace array) rendered as a string (SQ_ERROR when it is not an array / has no frames).

SQRESULT sqstd_formaterrorcontextstring(HSQUIRRELVM v, HSQOBJECT trace)

Push the live callstack if it has frames, else `trace` (the async fault's captured trace array) rendered as a string.

SQRESULT sqstd_throwerrorf(HSQUIRRELVM v, const char *err, ...)

Throws an error built with printf-style formatting.

Blobs

SQUserPointer sqstd_createblob(HSQUIRRELVM v, SQInteger size)

Creates a blob of the given size and pushes it.

SQRESULT sqstd_getblob(HSQUIRRELVM v, SQInteger idx, SQUserPointer *ptr)

Returns the payload pointer of the blob at idx.

SQInteger sqstd_getblobsize(HSQUIRRELVM v, SQInteger idx)

Returns the size of the blob at idx.

SQRESULT sqstd_register_bloblib(HSQUIRRELVM v)

Registers the blob library into the VM.

Files and streams

SQFILE sqstd_fopen(const char *, const char *)

Opens a file and returns a stream handle.

SQInteger sqstd_fread(SQUserPointer, SQInteger, SQInteger, SQFILE)

Reads bytes from a stream handle.

SQInteger sqstd_fwrite(const SQUserPointer, SQInteger, SQInteger, SQFILE)

Writes bytes to a stream handle.

SQInteger sqstd_fseek(SQFILE, SQInteger, SQInteger)

Moves the cursor of a stream handle.

SQInteger sqstd_ftell(SQFILE)

Returns the cursor position of a stream handle.

SQInteger sqstd_fflush(SQFILE)

Flushes a stream handle.

SQInteger sqstd_fclose(SQFILE)

Closes a stream handle.

SQInteger sqstd_feof(SQFILE)

Reports whether a stream handle is at its end.

SQRESULT sqstd_createfile(HSQUIRRELVM v, SQFILE file, SQBool own)

Pushes a script file object wrapping an open stream handle.

SQRESULT sqstd_getfile(HSQUIRRELVM v, SQInteger idx, SQFILE *file)

Returns the stream handle behind the file object at idx.

SQRESULT sqstd_init_streamclass(HSQUIRRELVM v)

Creates the stream class that blob and file both take their methods from.

SQRESULT sqstd_register_iolib(HSQUIRRELVM v)

Registers the io library into the VM.

Strings and regular expressions

The sqstd_rex_* family is the regular expression engine behind string.regexp, usable directly from C.

SQRex *sqstd_rex_compile(SQAllocContext ctx, const char *pattern, const char **error)

Compiles a regular expression.

void sqstd_rex_free(SQRex *exp)

Frees a compiled regular expression.

SQBool sqstd_rex_match(SQRex* exp, const char* text)

Tests whether a whole string matches a compiled expression.

SQBool sqstd_rex_searchrange(SQRex* exp, const char* text_begin, const char* text_end, const char** out_begin, const char** out_end)

Finds the first match within a range of a string.

SQInteger sqstd_rex_getsubexpcount(SQRex* exp)

Returns how many capturing groups a compiled expression has.

SQBool sqstd_rex_getsubexp(SQRex* exp, SQInteger n, SQRexMatch *subexp)

Returns the range one capturing group matched.

SQBool sqstd_rex_matchaborted(SQRex* exp)

Reports whether the last match gave up because it exhausted its backtracking budget.

SQRESULT sqstd_format(HSQUIRRELVM v, SQInteger nformatstringidx, SQInteger *outlen, char **output)

Formats values from the stack with a printf-style pattern.

void sqstd_pushstringf(HSQUIRRELVM v, const char *s, ...)

Pushes a string built with printf-style formatting.

SQRESULT sqstd_register_stringlib(HSQUIRRELVM v)

Registers the string library, including the regular expressions, into the VM.

The remaining modules

SQRESULT sqstd_register_datetimelib(HSQUIRRELVM v)

Registers the datetime library into the VM.

SQRESULT sqstd_register_debuglib(HSQUIRRELVM v)

Registers the debug library into the VM.

SQRESULT sqstd_register_mathlib(HSQUIRRELVM v)

Registers the math library into the VM.

SQRESULT sqstd_register_command_line_args(HSQUIRRELVM v, int argc, char ** argv)

Publishes the process command line to script as a global.

SQRESULT sqstd_register_systemlib(HSQUIRRELVM v)

Registers the system library into the VM.

Extras

Object-handle shortcuts that skip the stack, for reads a host does often.

SQRESULT sq_ext_getfuncinfo(HSQOBJECT obj, SQFunctionInfo *fi)

Fills a function info struct from an object handle, without touching the stack.

SQRESULT sq_ext_get_array_floats(HSQOBJECT obj, int start, int count, float * dest)

Copies a run of floats out of an array held as an object handle.

int sq_ext_get_array_int(HSQOBJECT obj, int index, int def = 0)

Reads one integer element of an array held as an object handle.

float sq_ext_get_array_float(HSQOBJECT obj, int index, float def = 0.f)

Reads one float element of an array held as an object handle.