Zsh Lib

Awesome functions that make writing Z shell CLI applications easier.

Install

Automated install

To install this library for the current user run:

/bin/zsh -c "$(curl -fsSL https://raw.githubusercontent.com/astzweig/zshlib/main/bootstrap.sh)"

To install this library system wide run that as root.

Using release version

You can also just download the latest release and put in in your $fpath.

Using in development

To use this library in you own project add it as a git-submodule to your repository.

# Run inside your project directory
git submodule add https://github.com/astzweig/zshlib

Using on the command line

Just add the zshlib directory to the beginning of your PATH variable and you can call the commands from the command line. Alternatively you can enter the whole path e.g. /path/to/repo/hio --help.

Caveat: Remember that sudo does not inherit all environment variables. To pass your modified PATH variable run sudo --preserve-env=PATH.

Using as a library

Just source the specific commands that you want inside your script. Alternatively you can enable Zsh autoload:

  # This will register all commands to autoload
  FPATH="/path/to/zshlib:${FPATH}"
  local funcNames=("${(@f)$(find ./zshlib -type f -perm +u=x | awk -F/ '{ print $NF }')}")
  autoload -Uz "${funcNames[@]}"

Or if you want to autoload only specific commands:

  # This will register only hio and getPrefDir to autoload
  FPATH="/path/to/zshlib:${FPATH}"
  autoload -Uz hio getPrefDir

What's included

name	description	dependencies	supported platforms
pf	Convenience function for highlighted output, combining print and tput.	tput, docopts1	all
hio	Highlighted output for predefined text styles for pf.	pf2, isTerminalBackgroundDark2, docopts1	all
lop	Log messages to syslog, file or print to command line with highlight.	hio2, pf2, isTerminalBackgroundDark2, docopts1	all
indicateActivity	Show a spinner during run of a function if output is to a terminal else print three dots and done or failed afterwards.	lop2, hio2, pf2, isTerminalBackgroundDark2, docopts1	all
trim	Remove leading and trailing whitespace from string.	docopts1	all
loadModules	Find executable modules in module search paths and allow user to filter or inverse the list.	docopts1	all
askUserModuleQuestions	Ask user questions on behalf of modules with possibility to cache (or store) answers for future calls, e.g. using config.	docopts1	all
showSpinner	Show a loading animation during execution of a function.	traps2, docopts1	all
askUser	Ask user for input. Supports questions, password, selections or confirmations.	hio2, traps2, docopts1	all
getPrefDir	Get system specific preferences directory.	docopts1	macOS, Linux, Windows Subsystem for Linux
traps	A trap handler for zsh scripts.	docopts1	macOS, Linux, Windows Subsystem for Linux
config	Config file writer and reader.	getPrefDir2, PlistBuddy3, docopts1	macOS, Linux, Windows Subsystem for Linux
abbreviatePaths	Truncate the passed paths so that they are minimal in length and pairwise distinct. Useful to save the user long path specifications.	docopts1	all
isTerminalBackgroundDark	Queries the terminal for its background color and returns zero if the color is rather dark or 1 otherwise. If the output is not connected to a terminal, code 10 will be returned.	traps2	all

Usage

Run any command with the --help option to read about its usage. e.g. /path/to/zshlib/hio --help.

Footnotes

1. docopts with -f, --function option needed. See the Astzweig fork for example. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³

2. A command of Zsh Lib (this library). ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴

3. /usr/libexec/PlistBuddy is a utility found on macOS systems. Apple does not provide any documentation besides the man page and the programs --help output. ↩