z

A zsh utility library for me who can't memorize shell script syntax. Provide functions with readable names for syntax that is not intuitive for me.

Installation

First time

curl -sL https://raw.githubusercontent.com/milkeclair/z/main/install.zsh | zsh

Update

z.update updates the loaded installation and its installed mods from one branch archive. Required mod dependencies are included. The command asks once, prepares the new files before replacement, and reloads the current shell. Git checkouts are updated with Git.

Reinstall core

z.install replaces the core while preserving installed mods. Use z.install.mod <mod_name> to update a single mod.

z.install.mod.list lists available and installed mods: green for installed, orange for different contents, and red for not installed. It compares against Z_INSTALL_BRANCH (default: main); local edits also appear orange.

Uninstall

z.uninstall

Version

• z.version
  • echo the current version
• z.version.latest
  • echo the latest version from GitHub
• z.version.note
  • echo the release note of the current version
• z.version.latest.note
  • echo the release note of the latest version from GitHub

Usage

Help

z.help displays this README.

z.help <function_name> displays the function docs. If no doc block is found, it displays Document not found.

Examples

Script to check if the number of arguments is more than 2.

my.argument_check() {
  z.arg.named max $@ default=2 && local max=$REPLY
  z.arg.named.shift max $@
  z.arr.count $REPLY

  if z.int.is.gt $REPLY $max; then
    z.io "more than $max args"
  else
    z.io.error "$max or less args"
  fi
}

Test

z.t.describe "my.argument_check"; {
  z.t.context "when more than max args"; {
    z.t.it "prints 'more than max args'"; {
      z.t.mock.call_original name="z.io"

      z.io.null my.argument_check max=3 "1" "2" "3" "4"

      z.t.mock.result
      z.t.expect.reply.includes "more than 3 args"
    }
  }

  z.t.context "when 2 or less args"; {
    z.t.it "prints '2 or less args' to stderr"; {
      z.t.mock name="z.int.is.gt" behavior="return 1"
      z.t.mock name="z.io"
      z.t.mock name="z.io.error"

      z.io.null my.argument_check "1" "2" "3"

      z.t.mock.result name="z.io"
      z.t.expect.reply.is.null skip_unmock=true

      z.t.mock.result name="z.io.error"
      z.t.expect.reply.includes "2 or less args"
    }
  }
}

Library

This library provides a set of utility functions for common tasks.

Functions are namespaced with z. prefix. And modules are namespaced with z.<module>. prefix.

The following rules apply under lib.

• analysis
  • Analyze without modifying the data.
  • If the function has a return value, it is placed in REPLY (not return).
• operator
  • Check arguments and return true or false.
  • If the function has a return value, it is returned (i.e. placed in the function's return value, not in REPLY).
  • It can be used in if statements.
• process
  • Modify the data.
  • If the function has a return value, it is placed in REPLY (not return).

Modules

• arg
  • named and positional argument parsing
• arr
  • join, split, unique...
• common
  • eq, is.null, guard...
• debug
  • interactive debugging
• dir
  • make, remove, exists...
• file
  • read, write, make.with_dir...
• fn
  • list, show, edit...
• hash
  • keys, values, merge...
• int
  • is.gteq, is.lteq, is.eq...
• io
  • is.empty, oneline, indent...
• mode
  • interactive mode
• path
  • dir, base, stem...
• perm
  • chmod, chown, chgrp wrapper
• status
  • abstract exit status handling
• str
  • color, is.path_like, gsub...
• t
  • testing framework
• var
  • exists, sets, get...

Testing

This library provides a testing framework for writing and running tests. Tests are written in zsh and use a RSpec-like syntax.

Run z.t to run all tests. z.t accepts the following options.

z.t searches tests from the current directory. Run it from a directory whose path ends with /test. If the current directory is not /test, z.t returns an error.

z_main is the main test file that sets up the test environment and runs the tests. z.t looks for main.zsh in the test directory and sources it before running the tests.

• -l, --log
  • Display test details.
• -f, --failed
  • Display only failed tests.
• -c, --compact
  • Display compact dot output (. for success, F for failure, * for pending).
• <name|path>
  • Run matched tests only.
  • If a directory path is provided (e.g. z.t mod), tests under the directory are collected recursively.
  • If a test file path is provided (e.g. z.t arg/process), only that file is run.

Tests are placed in the test directory. Tests are namespaced with z.t. prefix. And modules are namespaced with z.t.<module>. prefix.

The following rules apply under test.

• describe
  • Describe the function or feature being tested.
• xdescribe
  • Skip the describe block.
• context
  • Describe the context in which the tests are run.
• xcontext
  • Skip the context block.
• it
  • Describe the expected behavior of the function or feature.
• xit
  • Skip the it block.
• expect
  • Assert the expected behavior of the function or feature.
  • The expectation functions are namespaced with z.t.expect. prefix.
• mock
  • Mock a function or command.
  • The mock is automatically restored after the test and assertion.
  • If you want to skip restoring in assertion, use skip_unmock option.
  • The mock result is placed in REPLY, not return.
  • Modes:
    • Default mode: Records function calls without executing original behavior.
    • call_original mode: Executes original function after recording the call.
      • z.t.mock.call_original function: Same as call_original mode.
    • Provide custom behavior: You can provide custom behavior by passing a command as the second argument.

Debug

This library provides a debug function for interactive debugging.

Using the Debug Function

Call z.debug in your script to enter debug mode. When debug mode is enabled, the function will pause execution and provide an interactive prompt.

To enable debug mode, use the z.debug.enable function. To disable debug mode, use the z.debug.disable function.

Available commands in debug mode:

• c or continue: Continue execution.
• p <var> or print <var>: Print the value of a variable.
• h or help: Show help.
• q or quit or exit: Exit the script.

my.function() {
  local var="hello"
  z.debug
  z.io $var
}

Mode

This library provides an interactive mode. It is similar to debug, but with a prefix applied to the functions being executed. For example, it is used in operations such as git, where the motivation is to avoid repeatedly typing 'git' as a prefix.

$ z.mode git
git> status
git> add file.txt
git> commit -m "Add file.txt"
git> push origin branch
git> q
$

$ z.mode z.io split="."
z.io> oneline "This.is.a.test"
z.io> line "Indented" "line" indent=2
z.io> q
$

Modifier

This library provides modifiers that enhance the execution of your specific tasks. You will individually install the ones you wish to use.

Install or Update

z.install.mod <mod_name>

Mod dependencies are resolved and installed first.

Uninstall

z.uninstall.mod <mod_name>

List of Mods

• z.git
  • Git command modifier. README
• z.wtproxy
  • Docker Compose worktree proxy modifier. README
• z.job
  • A very simple background job. README
• z.completion
  • Completing document or function names in the shell. README

Language Server

This library provides a language server.

Download: https://marketplace.visualstudio.com/items?itemName=milkeclair.z-ls

Features

• Autocompletion
  • Function names
• Hover information
  • name
  • description
  • parameters
  • returns
  • example
• Signature Help
  • argument documentation
• Go to definition
• Diagnostics
  • Function not found with suggestion
  • Empty line
    • Start of file
    • Whitespace only line
    • Final newline
  • Unused function arguments
  • Missing required positional arguments
  • Missing required named arguments
  • Suppression comment (# zls: ignore)