Libraries

Libraries#

Zsh has three layers of re-use. Built-ins live inside the zsh binary. Loadable modules ship with zsh and attach more built-ins on demand. Autoloaded functions are shell-language files on $fpath that zsh parses the first time they are called. On top of those, the operator can source plain files and pull in external programs through $PATH.

Built-in Helpers#

Common built-ins worth knowing.

  • print, format and print (zsh-spelled echo with sane options like -l, -u2, -r).

  • printf, C-style format strings.

  • read, read a line from a stream.

  • trap, run a handler on signals or EXIT.

  • getopts, parse short flags (POSIX).

  • setopt / unsetopt, toggle shell options.

  • zstyle, the configuration system for completion and contrib functions.

Loadable Modules#

Compiled C modules ship with zsh and attach more built-ins on demand. Load with zmodload zsh/<name>. zmodload -L lists the load-on-demand mappings; zmodload with no arguments lists what is loaded.

Module

What it adds

zsh/datetime

$EPOCHSECONDS, $EPOCHREALTIME, strftime

zsh/mathfunc

Native math: sqrt, sin, cos, log, …

zsh/regex

PCRE backend for =~

zsh/sched

sched builtin: schedule jobs at a future time

zsh/net/tcp

TCP client / server through ztcp

zsh/net/socket

Unix-domain sockets through zsocket

zsh/zutil

zparseopts, zstyle, zformat, zregexparse

zsh/zprof

Profile shell startup and function calls

zsh/system

sysread, syswrite, syserror, zsystem flock

zsh/parameter

Expose internals ($functions, $builtins, $commands) as associative arrays

zsh/complist

Menu-select completion UI

zsh/curses

Bind zsh to ncurses for TUI work

 
$ zmodload zsh/datetime
$ print -- "$EPOCHSECONDS"

$ zmodload zsh/mathfunc
$ print -- "$(( sqrt(2.0) ))"

$ zmodload zsh/parameter
$ print -l -- ${(k)builtins} | head

Autoload Functions#

autoload -Uz NAME defers loading a function; the body is the file named NAME on $fpath. The function is parsed on first call, not at shell startup, so heavy helpers don’t bloat init time.

$ fpath=(~/.zsh/functions $fpath)
$ autoload -Uz add-zsh-hook bashcompinit run-help

The -U flag disables alias expansion inside the function (a common source of bugs); -z opts into zsh-style parsing. Always use -Uz for autoloaded code.

Zsh’s contrib library lives under ${prefix}/share/zsh/${version}/functions and ships dozens of useful helpers. run-help opens man pages from the prompt; zmv is a globbing rename; zcalc is a calculator REPL; add-zsh-hook wires functions into precmd / preexec cleanly.

$ autoload -Uz zmv
$ zmv '(*).JPG' '$1.jpg'              # rename .JPG → .jpg in-place

$ autoload -Uz zcalc
$ zcalc -e '22 / 7'

External Tools#

Most “library” functionality is the same coreutils + friends toolkit bash leans on.

  • Text: grep, sed, awk, cut, tr, sort, uniq

  • Files: find, xargs, stat, rsync

  • HTTP: curl, wget

  • JSON: jq

  • Process: ps, pgrep, kill, timeout

See Networking for the network-flavored slice and Coreutils for the catalog.

Sourcing a Module#

source FILE (or .) reads and executes a file in the current shell. Every function, variable, and trap it defines stays in scope after the file returns.

$ # ~/.zsh/lib/log.zsh
$ log::info() { print -- "[INFO] $*" }
$ log::warn() { print -u2 -- "[WARN] $*" }

$ source ~/.zsh/lib/log.zsh
$ log::info "starting"

The defensive idiom that protects against double-source.

$ # ~/.zsh/lib/common.zsh
$ [[ -n "${COMMON_LOADED:-}" ]] && return 0
$ COMMON_LOADED=1
$ log() { print -u2 -- "[$(date +%FT%T)] $*" }

References#

  • man 1 zshmodules (compiled C modules).

  • man 1 zshcontrib (autoload functions in the Functions subdirectory of the zsh distribution).

  • man 1 zshbuiltins (every shell builtin).

  • Frameworks for the third-party plugin managers (Oh My Zsh, Prezto, zinit, antidote) that automate $fpath and autoload setup.

  • Overview for the language-level source / autoload discussion.

Contents