Module system.util

The util module contains various functions that don’t have any specific system function, or help improve the usability of the general system.

Index

Data

syscall

util.syscall wraps all available syscalls into a table of functions, making it possible to call syscalls using direct function calls instead of manually yielding and managing the return values.

Function

addEventListener()	Adds an event listener to the listening module.
alarm()	Starts an alarm that will run until the specified time. A timer event will be queued on completion.
argparse()	Takes a list of valid arguments + the arguments to a program, and returns a table with the extracted arguments (and values if requested). If an argument with all -s is passed, processing of arguments stops, and all subsequent arguments are added to the list.
cancel()	Cancels a timer or alarm. This prevents the event from triggering.
copy()	Copies a value recursively, including all its keys and values.
crc32()	Calculates the CRC-32 checksum of the specified data.
filterEvent()	Waits until an event of the specified type(s) occurs.
peekEvent()	Peeks at the next event in the queue.
pullEvent()	Returns the next event from the event queue. This is intended to make it more clear when events are being pulled, and also has the benefit of supporting libsystem-craftos better.
queueEvent()	Queues an event to loop back to the process.
removeEventListener()	Removes an event listener from the listening module.
runEvents()	Runs the event listening loop on the current thread, blocking forever.
sleep()	Pauses the process for a certain amount of time.
split()	Splits a string into components.
startEvents()	Runs the event listening loop on a new thread, allowing code to run after.
timer()	Starts a timer that will run for the specified number of seconds. A timer event will be queued on completion.
type()	Returns the type of the parameter, with the ability to check the __name metamethod for custom types.

API Reference

system.util.syscall: {[string]: fun(...any): ...unknown}

util.syscall wraps all available syscalls into a table of functions, making it possible to call syscalls using direct function calls instead of manually yielding and managing the return values.

system.util.argparse(
    arguments: {[string]: boolean | string | nil},
    ...: string
): (
    args: {[string]: boolean | string | number | nil, [number]: string} | nil,
    err: string
)

Takes a list of valid arguments + the arguments to a program, and returns a table with the extracted arguments (and values if requested). If an argument with all -s is passed, processing of arguments stops, and all subsequent arguments are added to the list.

Single-character arguments are handled through -a, and longer arguments are handled through --argument. The value of the entry specifies how the argument is handled:

• If the value is a truthy value, this argument requires a parameter.

• If the value is "number", the argument requires a number parameter.

• If the value is "multiple", the argument can be specified multiple times, and will require a parameter. The values returned will be in a table.

• If the value is "multiple number", the argument can be specified multiple times, and will require a number parameter. These are also in a table.

• If the value is false, the argument does not take a parameter.

• If the value is nil, the argument does not exist and will throw an error if passed.

• If the value starts with @, the parameter is an alias and will be stored in that argument instead, following the same rules as that argument as well. Special parameters to the parser can be added in a [""] table. The following parameters are specified:

• stopProcessingOnPositionalArgument [boolean]: Whether to stop processing arguments when a positional argument is passed, e.g. myprog -s arg -i will return args.s = true, but args.i = nil.

Parameters:

• arguments ({[string]: boolean | string | nil}) – A list of arguments that the program accepts.

• ... (string) – The arguments as passed to the program.

Returns:

• args ({[string]: boolean | string | number | nil, [number]: string} | nil) – The arguments as parsed from the arguments table as key-value entries, plus positional arguments as list entries, or nil if the arguments passed are invalid.

• err (string) – An error string describing what was invalid, which can be printed for the user.

system.util.timer(time: number): (result: number)

Starts a timer that will run for the specified number of seconds. A timer event will be queued on completion.

Parameters:

time (number) – The number of seconds to wait until sending the event

Returns:

result (number) – The ID of the newly created timer

system.util.alarm(time: number): (result: number)

Starts an alarm that will run until the specified time. A timer event will be queued on completion.

Parameters:

time (number) – The time to send the event at

Returns:

result (number) – The ID of the newly created alarm

system.util.cancel(id: number): unknown

Cancels a timer or alarm. This prevents the event from triggering.

Parameters:

id (number) – The ID of the timer or alarm to cancel

system.util.sleep(time: number)

Pauses the process for a certain amount of time.

Parameters:

time (number) – The amount of time to wait for, in seconds

system.util.pullEvent(): (result: string, result: table)

Returns the next event from the event queue. This is intended to make it more clear when events are being pulled, and also has the benefit of supporting libsystem-craftos better.

Returns:

• result (table) – The event pulled

• result – The parameters for the event

system.util.filterEvent(...: string): (result: string, result: table)

Waits until an event of the specified type(s) occurs.

Parameters:

... (string) – The event names to filter for

Returns:

• result (table) – The event type that was matched

• result – The parameters for the event

system.util.queueEvent(event: string, param: table): unknown

Queues an event to loop back to the process.

Parameters:

• event (string) – The event name to send

• param (table) – The parameter table to send with the event

system.util.peekEvent(): (result: string | nil, result: table | nil)

Peeks at the next event in the queue.

Returns:

• result (table | nil) – The name of the next event, or nil if there is none

• result – The parameters of the next event.

system.util.split(str: string, sep?: string, includeEmpty?: boolean): table

Splits a string into components.

Parameters:

• str (string) – The string to split

• sep? (string) – The delimiter match class to split by (defaults to “%s”)

• includeEmpty? (boolean) – Whether to include empty matches (defaults to false)

Returns:

_1 (table) – } result The components of the string

system.util.copy(value: any): (result: any)

Copies a value recursively, including all its keys and values.

Parameters:

value (any) – The value to copy

Returns:

result (any) – A copy of the value, with all keys, values, and metatables duplicated.

system.util.addEventListener(
    event: string,
    callback: fun(string: any, table: any): boolean
)

Adds an event listener to the listening module.

the event is queued. If the function returns a truthy value, processing for the current event will stop. If the function throws an error, the loop will stop.

Parameters:

• event (string) – The event to listen for

• callback (fun(string: any, table: any): boolean) – The function to call when

system.util.removeEventListener(
    event: string,
    callback: fun(string: any, table: any)
)

Removes an event listener from the listening module.

Parameters:

• event (string) – The event to listen for

• callback (fun(string: any, table: any)) – The function to remove

system.util.runEvents(): (result: string)

Runs the event listening loop on the current thread, blocking forever.

Returns:

result (string) – The error that caused the function to stop

system.util.startEvents(): (result: number)

Runs the event listening loop on a new thread, allowing code to run after.

Returns:

result (number) – The ID of the new thread

system.util.type(value: any): (result: string)

Returns the type of the parameter, with the ability to check the __name metamethod for custom types.

Parameters:

value (any) – The value to check

Returns:

result (string) – The type of the value

system.util.crc32(str: string, polynomial?: number | table, crc?: number): (result: number)

Calculates the CRC-32 checksum of the specified data.

Parameters:

• str (string) – The data to checksum

• polynomial? (number | table) – The polynomial for the CRC, or the lookup table to use (defaults to 0xEDB88320)

• crc? (number) – The initial CRC value (defaults to 0xFFFFFFFF)

Returns:

result (number) – The calculated CRC checksum