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.

random_bytes(length) -> bytes

Read cryptographically secure random bytes

Returns length bytes from the kernel CSPRNG (getrandom(2), falling back to /dev/urandom). Accepts 0 to 65536 bytes.

This is the only randomness in this module fit for keys, tokens and salts. math.random backs everything else here, and its state is recoverable from a handful of outputs however well it was seeded.

salt(length) -> salt

Generate a random binary salt string

Returns a string of length random bytes (default 16) from the kernel CSPRNG. 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.

Returns nil, err if the kernel entropy source cannot be read. Callers must not paper over that: a salt that silently degrades is the failure this function exists to prevent.

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, so the result identifies but must never authorize.

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

home() -> path

Get the current user's home directory

Resolves the home directory using the HOME environment variable first, then falls back to getpwuid(getuid()). Returns nil if neither method succeeds. Result is cached on first call.

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.

prettify_json(json) -> pretty_json

Format a JSON string as "pretty" JSON