std — lilu API

Module	Description
std.conv	Conversion utilities for formatting byte sizes, IP addresses, timestamps, and human-readable time spans.
std.fs	File system operations for reading, writing, and manipulating files and directories.
std.git	Pure-Lua git repository reader for shell prompt integration.
std.logger	JSON structured logging with configurable log levels and output routing to stdout or stderr.
std.mime	MIME type detection and default application lookup based on file extensions and XDG desktop entries.
std.ps	Process control and execution utilities.
std.tbl	Table utilities for deep copying, merging, sorting, searching, and rendering tables as strings or markdown pipe tables.
std.txt	Text processing utilities for line splitting, string wrapping, indentation, alignment, templating, and display truncation.
std.utf	UTF-8 string utilities for character counting, display width calculation, substring extraction, and validation.

Functions

Name	Signature
`sleep`	sleep(`seconds`)
`sleep_ms`	sleep_ms(`milliseconds`)
`system_users`	system_users() -> `users`
`envsubst`	envsubst(`filename`) -> `content`, `err`
`escape_magic_chars`	escape_magic_chars(`str`) -> `escaped`
`salt`	salt(`length`) -> `salt`
`uuid`	uuid() -> `id`
`nanoid`	nanoid(`length`) -> `id`
`module_available`	module_available(`name`) -> `available`
`environ`	environ() -> `env`
`hostname`	hostname() -> `name`
`progress_icon`	progress_icon() -> `handle`

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

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.

Overview

Submodules

Functions