🔀 常用语法
It is recommended to familiarize yourself with getting_started/overview before this.
The "make" syntax
zi ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX"zi light tj/git-extrasThe Makefile of the project above has only 2 tasks:
- 安装目标。
- 构建安装所需的脚本。
The Makefile with 2 tasks, can use:
make"all install PREFIX=…",pick'…'willchmod +xall matching files and add$ZPFX/bin/to$PATH.
$ZPFX is provided by Zi, it is set to ~/.zi/polaris by default. However, it can be changed by specifying the $ZPFX= target.
Compiling programs
zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \ atpull"%atclone" make pick"src/vim"zi light vim/vim| Syntax | Description |
|---|---|
as'program' | Add file selected by pick'…' to $PATH, and do not source it. |
atclone'…' | Execute code after downloading. |
atpull'%atclone' | Execute the same code atclone'…' is given, but after successful update. |
make | Run make after atclone'…' and atpull'…' (note: make'!' will execute before them). |
pick'src/vim' | Set executable flag on src/vim, hint that src/ should be added to $PATH. |
The same but with installation (make install) under $ZPFX by default:
zi ice as'program' atclone'rm -f src/auto/config.cache; \ ./configure --prefix=$ZPFX' atpull'%atclone' make'all install' pick'$ZPFX/bin/vim'zi light vim/vim| Syntax | Description |
|---|---|
as'program' | As above. |
atclone'…' | As above plus pass --prefix=$ZPFX to ./configure, to set the installation directory. |
atpull'%atclone' | As above. |
make | As above, but also run the install target. |
pick'src/vim' | as above, but for a different path $ZPFX/bin/vim. |
LS_COLORS
A repository trapd00r/LS_COLORS provides a file with color definitions for GNU ls command, and also for ogham/exa. Typically one does eval $( dircolors -b $HOME/LS_COLORS) to process this file and set the environment for ls. This means dircolors is run by every shell startup. It costs much time to create a fork and program, i.e., the dircolors binary needs to be loaded to obtain and process the color definitions. The following invocation solves this problem:
zi ice atclone'dircolors -b LS_COLORS > clrs.zsh' \ atpull'%atclone' pick"clrs.zsh" nocompile'!' \ atload'zstyle ":completion:*" list-colors “${(s.:.)LS_COLORS}”'zi light trapd00r/LS_COLORS| Syntax | Description |
|---|---|
atclone'…' | Generate shell script, passing it to eval. More: 1 |
atpull'%atclone' | Do the same at any update of the plugin. More: 2 |
pick"clrs.zsh" | Source the previously generated file clrs.zsh. |
nocompile'!' | Invokes compilation after the atclone'…' ice-modifier and the exclamation mark causes this. |
atload'…' | Additionally sets up the Zsh completion to use the colors provided by the trapd00r package. |
This way, except for the plugin installation and update, dircolors isn't run, just normal sourcing is done. The everyday sourced file, i.e. clrs.zsh, is being compiled to speed up the loading.
Direnv
The project direnv/direnv registers itself in the Z shell to modify the environment on directory change. This registration is most often done by eval "$(direnv hook zsh)" added to .zshrc.
zi ice as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' \ atpull'%atclone' src"zhook.zsh"zi light direnv/direnvmake'!'– executemakebeforeatclone'…'and beforeatpull'…'(seemakeabove),src'zhook.zsh'– source filezhook.zsh.
In general, direnv works by hooking up to Zsh. The code that does this is provided by the program direnv (built by make'…').
Above atclone'…' puts this code into file zhook.zsh, src'' sources it. This way direnv hook zsh is executed only on clone and update, and Zsh starts faster.
Glance at the 'for' syntax
The drawback of this standard procedure is that the direnv binary is run on every shell startup and significantly slows it down. Zi allows to solve this in the following way:
zi as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' \ atpull'%atclone' pick"direnv" src"zhook.zsh" for \ direnv/direnv| Syntax | Description |
|---|---|
make'!' | Compile direnv, the exclamation mark means: run the make first, before atclone'…' and atpull'…' hooks. |
atclone'…' | As soon as the plugin is installed generate the registration code and save it to zhook.zsh, instead of passing it to eval. |
atpull'%atclone' | The atclone'…' runs on installation while atpull'…' runs on update of the plugin. |
src'zhook.zsh' | Load generated registration code |
pick'direnv' | Ensure +x permission on the binary |
as'program' | The plugin is a program, there's no main file to the source. |
In this method, the registered code is generated once on every installation or update, then sourced without running direnv itself. The project is also available as a binary GitHub releases. This distribution can be installed by:
zi from"gh-r" as"program" mv"direnv* -> direnv" \ atclone'./direnv hook zsh > zhook.zsh' atpull'%atclone' \ pick"direnv" src="zhook.zsh" for \ direnv/direnv| Syntax | Description |
|---|---|
from'gh-r' | Install from direnv from GitHub releases. |
mv'direnv* -> direnv' | After installation, rename direnv.linux-386 or similar file to direnv. |
atclone'…', atpull'…' | Same above example. |
pick'direnv' | Same above example. |
as'program' | Same above example. |
Standard syntax
zi …zi ice …zi load …zi light …zi unload …zi snippet …The standard method of specifying ices and their values:
zi wait"1" from"gh-r" atload"print Hello World"zi load …There's no ice that can be used as a subcommand.
The alternative syntaxes
However, Zi also supports syntaxes such as the equal (=) syntax:
zi wait=1 from=gh-r atload="print Hello World"zi load …The colon (:) syntax:
zi wait:1 from:gh-r atload:"print Hello World"zi load …And also – in conjunction with all of the above – the GNU syntax:
zi --wait=1 --from=gh-r --atload="print Hello World"zi load …摘要
It's up to the user which syntax to use.
The motivation behind the syntaxes is to utilize the syntax highlighting of editors like Vim – and have the strings and ice expressions colorized with a distinct color. However, with the zi-vim-syntax syntax definition this motivation can be superseded with the highlighting specifically for Zi.
- The
%atcloneis just a special string that denotes theatclone'…'hook and is copied onto theatpull'…'hook.↩ - Save it to file. The
atclone'…'is being run on the installation while theatpull'…'hook is being run on an update of the trapd00r/LS_COLORS plugin.↩