sleep(seconds)

Sleep for the given number of seconds

sleep_ms(milliseconds)

Sleep for the given number of milliseconds

system_users() -> users

Parse /etc/passwd and return a table of system users keyed by UID

Returns a table mapping numeric UIDs to tables with login and gid fields. Unknown UIDs return {login="unknown", gid=-1} via metatable.

envsubst(filename) -> content, err

Read a file and substitute environment variables in its content

Reads filename and replaces every ${VAR} placeholder with the corresponding value from the process environment at the time of the call. Variables set via ps.setenv are visible. Returns nil and an error string if the file cannot be read.

escape_magic_chars(str) -> escaped

Escape Lua pattern magic characters in a string

Prepends % before each of the eleven Lua pattern magic characters: + * % . $ [ ] ? ( ) -. The result is safe to use as a literal pattern inside string.find, string.match, etc.

salt(length) -> salt

Generate a random binary salt string

Returns a string of length random bytes (default 16). The output is raw binary, NOT hex-encoded. Byte value 0x00 is excluded. Suitable for use as HMAC key material or a password-hashing salt.

Requires math.randomseed to have been called before use.

uuid() -> id

Generate a random UUID v4 string

Returns a randomly generated UUID in the canonical form xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx, where 4 fixes the version and y is constrained to 8–b per RFC 4122. Uses math.random; call math.randomseed before use.

nanoid(length) -> id

Generate a compact random ID (nanoid)

Generates a URL-safe random ID using alphanumeric characters plus - and _. Default length is 21 characters. Port of https://github.com/ai/nanoid.

module_available(name) -> available

Check if a Lua module is available for require

Returns true if the module name can be loaded, without actually loading it. If name is not already in package.loaded, each package.searcher is tried in order. When a searcher returns a loader function, it is registered in package.preload so the next require(name) call is instant.

environ() -> env

Get all environment variables as a table

Returns a table mapping each environment variable name to its value string. For the raw "NAME=VALUE" array used internally by the process, see ps.environ().

hostname() -> name

Get the system hostname

replace_tilde_with_home(line) -> line

Replace ~ in the line with current user's home directory

Replaces tilde occurrences in the line with user's home directory. Tilde is replaced only in those position where it makes sense to replace it with home, thus it won't be replaced in a middle of a word. Returns nil if user's home can't be determined or if line is nil.

progress_icon() -> handle

Start an animated progress indicator in the terminal

Returns a handle with a `handle.stop() method that kills the animation and cleans up. The indicator renders braille characters at ~5 fps.

progress_text(text, r, g) -> handle

Start an animated progress indicator rendering text as a braille-masked cycling string

Returns a handle with a handle.stop() method that kills the animation and cleans up. Each frame re-renders text via std.txt.mask_with_braille, then erases it with backspaces before the next frame. The optional r and g values anchor the hue so the animation stays in one color family; omit them for per-frame-randomized colors.

now() -> id

Returns unique monotonic IDs based on timestamp, pseudo mircoseconds

clockticks() -> ticks

Get the current CPU time in seconds

create_shm(name, data) -> ret, err

Create a POSIX shared memory object

Creates a POSIX shared memory segment named name and initializes it with the contents of data. Returns 0 on success, or nil and an error string on failure.

pack3d(x, y, z) -> packed

Pack three numbers into a 12-byte little-endian binary string

Packs three 32-bit float values into a 12-byte binary string using little-endian byte order. Useful for compact serialization of 3D coordinates.

unpack3d(packed) -> x, y, z

Unpack a 12-byte binary string into three numbers

Unpacks a 12-byte binary string (as produced by pack3d) back into three 32-bit float values. Raises an error if the input is not exactly 12 bytes.