Introduction

Every language has a standard library, Wi has one too. This page is a reference to it.

Module name	Description	Variables	Functions
std	Base, core functions		print, puts, input, ismain, exit, gc, memoryused, error, assert, try, call, type, isreal, isnull, isbool, isstring, isarray, ismap, isforeign, isfunction, isobject, isuserdata, isfalsy, real, bool, string, char, hasfield, fields, equals
os	OS utility functions		clock, monotonic, time, date, setenv, getenv, args, system, remove, rename, isdir, cwd, mkdir, listdir, sleep
io	File IO functions	stdin, stdout, stderr, SEEK_SET, SEEK_CUR, SEEK_END	exists, open, close, flush, write, read, writebytes, readbytes, seek
math	Math constants and functions	E, PI, HUGE	abs, acos, asin, atan, atan2, ceil, clamp, cos, deg, exp, floor, mod, log, log10, ln, max, min, pow, rad, seed, random, round, sin, sign, sqrt, tan

std

Functions

print

Print values to the standard output without any trailing newline
Parameters:

• any ...args: Values to print

puts

Print values to the standard output, each followed by its own newline
Parameters:

• any ...args: Values to print

input

Read a line from standard input
Parameters:

• string ...prompt: A prompt to print before input (up to 1)

Returns: string read line, or null on end of input

ismain

Check if current script is the main one, i.e. the script used to start program execution
Returns: bool true if the current script is the main script, false otherwise

exit

Request the state to stop execution
Parameters:

• real exit_code: Optional exit code returned to the embedding host program (defaults to 0)

gc

Force a major garbage collection cycle

memoryused

Get the total number of bytes currently allocated by the garbage collector
Returns: real total bytes allocated

error

Raise a runtime error
Parameters:

• string message: Error message

assert

Raise a runtime error if the value is falsy
Parameters:

• any value: Value to check
• string message: Error message

Returns: any the checked value – a falsy value raises a runtime error instead of returning

try

Safely execute an error-prone function
Parameters:

• function fn: Function to execute
• any ...args: Function arguments

Returns: object with fields ok, value, and error

call

Call a function with the items of an array as its arguments
Parameters:

• function fn: Function to call
• array args: Function arguments (up to 255)

Returns: any value returned by fn

type

Get value type (userdata reports its own name, e.g. file)
Parameters:

• any value: Value

Returns: string value type

isreal

Check if the value is a real
Parameters:

• any value: Value to check

Returns: bool true if the value is a real, false otherwise

isnull

Check if the value is null
Parameters:

• any value: Value to check

Returns: bool true if the value is null, false otherwise

isbool

Check if the value is a bool
Parameters:

• any value: Value to check

Returns: bool true if the value is a bool, false otherwise

isstring

Check if the value is a string
Parameters:

• any value: Value to check

Returns: bool true if the value is a string, false otherwise

isarray

Check if the value is an array
Parameters:

• any value: Value to check

Returns: bool true if the value is an array, false otherwise

ismap

Check if the value is a map
Parameters:

• any value: Value to check

Returns: bool true if the value is a map, false otherwise

isforeign

Check if the value is a foreign function
Parameters:

• any value: Value to check

Returns: bool true if the value is a foreign (C) function, false otherwise

isfunction

Check if the value is a function
Parameters:

• any value: Value to check

Returns: bool true if the value is a function, false otherwise

isobject

Check if the value is an object
Parameters:

• any value: Value to check

Returns: bool true if the value is an object, false otherwise

isuserdata

Check if the value is a userdata
Parameters:

• any value: Value to check

Returns: bool true if the value is a userdata, false otherwise

isfalsy

Check if the value is falsy
Parameters:

• any value: Value to check

Returns: bool true if the value is falsy, false otherwise

real

Try and convert a value to a real
Parameters:

• any value: Value to convert

Returns: real converted value

bool

Try and convert a value to a bool
Parameters:

• any value: Value to convert

Returns: bool converted value

string

Try and convert a value to a string
Parameters:

• any value: Value to convert

Returns: string converted value

char

Convert a codepoint to a one-character string
Parameters:

• real codepoint: Unicode codepoint

Returns: string the resulting one-character string

hasfield

Check if an object has a field
Parameters:

• object obj: Object
• string field: Field name

Returns: bool true if obj has a field named field, false otherwise

fields

Get an object's fields as a map
Parameters:

• object obj: Object

Returns: map object fields

equals

Deep equality check – compared to standard == it compares arrays, maps, and objects structurally and not by their reference in memory
Parameters:

• any a: Value A
• any b: Value B

Returns: bool true if a and b are structurally equal, false otherwise

os

Functions

clock

Get the number of CPU seconds elapsed since the program started
Returns: real CPU seconds elapsed since the program started

monotonic

Get the number of seconds elapsed on the monotonic clock, unaffected by system clock changes
Returns: real seconds elapsed on the monotonic clock

time

Get the current Unix timestamp (seconds since epoch)
Returns: real current Unix timestamp

date

Break a Unix timestamp down into its date/time components (in UTC)
Parameters:

• real timestamp: Unix timestamp (seconds since epoch)

Returns: object with fields year, month, day, hour, minute, second, weekday

setenv

Set the value of an environment variable
Parameters:

• string name: Environment variable name
• string value: Value to set
• bool overwrite: Whether to overwrite an existing value

Returns: bool true if the variable was set, false otherwise

getenv

Get the value of an environment variable
Parameters:

• string name: Environment variable name

Returns: string value, or null if not set

args

Get the command line arguments: the first item is the main script path, followed by everything passed after the --
Returns: array of string arguments

system

Run a system shell command
Parameters:

• string command: Command to run

Returns: real exit code

remove

Remove a file
Parameters:

• string path: File path

Returns: bool true if the file was removed, false otherwise

rename

Rename (or move) a file
Parameters:

• string old: Current file path
• string new: New file path

Returns: bool true if the rename succeeded, false otherwise

isdir

Check if a path is a directory
Parameters:

• string path: Path

Returns: bool true if the path is a directory, false otherwise

cwd

Get the current working directory
Returns: string current working directory

mkdir

Create a directory
Parameters:

• string path: Directory path

Returns: bool true if the directory was created, false otherwise

listdir

List the entries in a directory
Parameters:

• string path: Directory path

Returns: array of string entry names

sleep

Sleep for a number of milliseconds
Parameters:

• real ms: Milliseconds to sleep

io

Variables

stdin

Standard input file handle (read-only)
Closing it is a no-op

stdout

Standard output file handle (write-only), goes through the state's output callback
Closing it only flushes

stderr

Standard error file handle (write-only), goes through the state's error callback
Closing it only flushes

SEEK_SET

Seek from the beginning of the file
Value: platform-defined

SEEK_CUR

Seek from the current position
Value: platform-defined

SEEK_END

Seek from the end of the file
Value: platform-defined

Functions

exists

Check if a file exists
Parameters:

• string path: File path

Returns: bool true if the file exists, false otherwise

open

Open a file for reading or writing
Parameters:

• string path: File path
• string mode: File access mode (r/r+, w/w+, a/a+)

Returns: file handle

close

Close an open file, no-op on already closed file
Parameters:

• file f: File handle

flush

Flush a file's write buffer to disk
Parameters:

• file f: File handle

write

Write content (converted to string implicitly) to a file
Parameters:

• file f: File handle
• any content: Content to write

read

Read the entire file content
Parameters:

• file f: File handle

Returns: string file content

writebytes

Write an array of raw bytes to a file
Parameters:

• file f: File handle
• array bytes: Array of byte values (0-255)

readbytes

Read the entire file content as raw bytes
Parameters:

• file f: File handle

Returns: array of byte values (0-255)

seek

Move a file's read/write position
Parameters:

• file f: File handle
• real offset: Offset to seek to
• real whence: Seek origin (io::SEEK_SET, io::SEEK_CUR, or io::SEEK_END)

Returns: real new absolute position in the file

math

Variables

E

Euler's number
Value: 2.7182818284590452354

PI

The ratio of a circle's circumference to its diameter
Value: 3.14159265358979323846

HUGE

A value representing positive infinity
Value: inf

Functions

abs

Get the absolute value of a number
Parameters:

• real x: Value

Returns: real absolute value of x

acos

Get the arc cosine of a number, in radians
Parameters:

• real x: Value

Returns: real arc cosine of x, in radians

asin

Get the arc sine of a number, in radians
Parameters:

• real x: Value

Returns: real arc sine of x, in radians

atan

Get the arc tangent of a number, in radians
Parameters:

• real x: Value

Returns: real arc tangent of x, in radians

atan2

Get the arc tangent of y / x, using the signs of both arguments to determine the correct quadrant, in radians
Parameters:

• real y: Y value
• real x: X value

Returns: real arc tangent of y / x, in radians

ceil

Round a number up to the nearest integer
Parameters:

• real x: Value

Returns: real x rounded up to the nearest integer

clamp

Clamp a number between a minimum and maximum value
Parameters:

• real x: Value
• real min: Minimum value
• real max: Maximum value

Returns: real x clamped between min and max

cos

Get the cosine of an angle given in radians
Parameters:

• real x: Angle, in radians

Returns: real cosine of x

deg

Convert an angle from radians to degrees
Parameters:

• real x: Angle, in radians

Returns: real angle, in degrees

exp

Get e raised to the given power
Parameters:

• real x: Exponent

Returns: real e raised to the power of x

floor

Round a number down to the nearest integer
Parameters:

• real x: Value

Returns: real x rounded down to the nearest integer

mod

Get the floating-point remainder of a / b
Parameters:

• real a: Dividend
• real b: Divisor

Returns: real floating-point remainder of a / b

log

Get the logarithm of a value with the given base
Parameters:

• real value: Value
• real base: Logarithm base

Returns: real logarithm of value with base base

log10

Get the base-10 logarithm of a value
Parameters:

• real x: Value

Returns: real base-10 logarithm of x

ln

Get the natural logarithm (base e) of a value
Parameters:

• real x: Value

Returns: real natural logarithm of x

max

Get the largest of the given values (if any value is NaN, the result is NaN)
Parameters:

• real ...values: Values to compare (at least two)

Returns: real largest of the given values

min

Get the smallest of the given values (if any value is NaN, the result is NaN)
Parameters:

• real ...values: Values to compare (at least two)

Returns: real smallest of the given values

pow

Raise a number to the given power
Parameters:

• real base: Base
• real exp: Exponent

Returns: real base raised to the power of exp

rad

Convert an angle from degrees to radians
Parameters:

• real x: Angle, in degrees

Returns: real angle, in radians

seed

Seed the pseudo-random number generator
Parameters:

• real x: Seed value

random

Get a pseudo-random number
Parameters:

• real min: Optional inclusive lower bound (must be given together with max)
• real max: Optional inclusive upper bound (must be given together with min)

Returns: real a number in [0, 1) when called with no arguments, or a random integer in [min, max] when bounds are given

round

Round a number to the nearest integer, or to a given number of decimal places
Parameters:

• real x: Value
• real decimals: Optional number of decimal places to round to (up to 1)

Returns: real x rounded to the nearest integer, or to decimals decimal places if given

sin

Get the sine of an angle given in radians
Parameters:

• real x: Angle, in radians

Returns: real sine of x

sign

Get the sign of a number
Parameters:

• real x: Value

Returns: real 1 if positive, -1 if negative, or 0 if zero

sqrt

Get the square root of a number
Parameters:

• real x: Value

Returns: real square root of x

tan

Get the tangent of an angle given in radians
Parameters:

• real x: Angle, in radians

Returns: real tangent of x