🌀 What can Annexes do?
Add a new ZI subcommand (i.e. the command that’s placed after the function
zi …
when calling ZI).Add new ice-modifiers.
Register four types of hooks:
3.1.
atclone
hook – run after cloning any plugin or downloading any snippet.3.2.
atpull
hook – run after pulling new commits (i.e. updating) for any plugin/snippet.3.3.
atinit
hook – run before loading any plugin/snippet, after it has been set up (i.e. downloaded).3.4.
atload
hook – run after loading any plugin/snippet.Register hooks for generating help text, shown by the
zi help
subcommand.
Recommended annexes
Common
Additional
Use meta plugins install common annexes as group:
zi light-mode for z-shell/z-a-meta-plugins @annexes
To install common and additional annexes:
zi light-mode for z-shell/z-a-meta-plugins @annexes+rec
How To Code Them?
Below is an example body of an atclone
hook taken from submods annex.
It shows how to:
- Obtain the arguments passed to the hook.
- Use an ice-modifier.
- It also shows a useful snippet that will trim the whitespace in array elements (see
# (4) …
in the code). - Utilize the last hook argument – the plugin’s/snippet’s containing directory.
emulate -L zsh -o extendedglob -o warncreateglobal -o typesetsilent
[[ -z "${ZI_ICE[submods]}" ]] && return 0
# (1) – get arguments
[[ "$1" = plugin ]] && \
local type="$1" user="$2" plugin="$3" id_as="$4" dir="$5" hook="$6" || \
local type="$1" url="$2" id_as="$3" dir="$4" hook="$6" # type: snippet
# (2) – we're interested only in plugins/snippets
# which have the submods'' ice in their load command
[[ -z ${ZI_ICE[submods]} ]] && return 0
local -a mods parts
local mod
# (3) – process the submods'' ice
mods=( ${(@s.;.)ZI_ICE[submods]} )
for mod in "${mods[@]}"; do
parts=( "${(@s:->:)mod}" )
# (4) Remove only leading and trailing whitespace
parts=( "${parts[@]//((#s)[[:space:]]##|[[:space:]]##(#e))/}" )
print "\nCloning submodule: ${parts[1]} to dir: ${parts[2]}"
parts[1]="https://github.com/${parts[1]}"
# (5) – the use of the input argument: `$dir'
command git -C "$dir" clone --progress "${parts[1]}" "${parts[2]}"
done
The recommended method of creating a hook is to place its body into a file that starts with a right arrow →
(more information, and also a za-
prefix, e.g. →za-myproject-atclone-hook
and then to mark it for autoloading via autoload -Uz →za-myproject-atclone-hook
. Then register the hook, presumably in the myproject.plugin.zsh
file, with the API call:
@zi-register-annex
:
@zi-register-annex myproject hook:atclone \
→za-myproject-atclone-handler \
→za-myproject-atclone-help-handler \
"submods''" # register a new ice-mod: submods''
The general syntax of the API call is:
@zi-register-annex {project-name} \
{hook: \
{name-of-the-handler-function} \
{name-of-the-HELP-handler-function} \
"{ice-mod1}|{ice-mod2}|…" < hook-type >| subcommand: < new-subcommand-name > }
The last argument, i.e. the |
-separated ice-list, is optional. That’s all! After this loading the plugin myproject
will set up the new ice-modifier submods
that will have syntax submods'{user}/{plugin} –> {output-dir}; …'
and will clone submodules when installing the original plugin or snippet! Example real-world use of the ice-modifier:
# Load the `zsh-autosuggestions' plugin via Prezto module: `autosuggestions'
zi ice svn submods'zsh-users/zsh-autosuggestions -> external'
zi snippet PZT::modules/autosuggestions
Check out the project which fully implements this idea, z-a-submods. It e.g. also implements the atpull
hook, i.e. supports the automatic update of the submodules. The z-a-*
prefix is recommended for projects which indicate annexes.
Récapitulatif
There are 2 or 3 subtypes for each of the hooks:
atinit
or!atinit
– the!
version is run before theatinit
ice-mod (i.e. beforezi ice atinit'echo this!'; …
), while the normal version runs after it.atload
or!atload
– analogous to theatinit
case: the!
version runs before theatload
ice-mod (while the normal version runs after it).atclone
or!atclone
– analogous to theatinit
andatload
cases.atpull
,!atpull
or%atpull
– the first two are being run only when there are new commits to be downloaded during the update. The%
version is being always run, regardless of whether the update will pull any actual commits or not, and it is being run after theatpull
ice-mod.