🔀 標準の構文
Introduction
Ziは、構造化された文・式に対して2つの構文タイプを提供します。
- 標準構文
- The "For" syntax
どちらの構文を使うかはユーザー次第ですが、両方の構文に慣れることを強くお勧めします。 In this example, we will use an empty repository z-shell/0 to practice the basics of the standard syntax.
- ターミナルで以下のコマンドを実行します。
zi load z-shell/0
Successfully installed the Zsh plugin which usually contains all the setup instructions as described in the Zsh plugin standard.
スニペットは、再利用可能なソースコード、マシンコード、またはテキストの一部を含む単一のファイルで、ファイルへのフルパスまたはURLが必要です。
- ターミナルで以下のコマンドを実行します。
zi snippet https://raw.githubusercontent.com/z-shell/zi-src/main/lib/zsh/snippets/welcome.zsh
成功しました! しかし、必ずしもとても簡単でシンプルであるとは限りません。時には、特定の時間や条件であることを指定したいこともあります。 This can be achieved using ice-modifiers.
上の行には ice 修飾子が含まれており、下の行でプラグインを読み込んでいます。
- ターミナルで以下のコマンドを実行します。
zi ice id-as'zsh/plugin' atinit'print "Hello World!"'
zi load z-shell/0
This registered the plugin under the plugin ID zsh/plugin
instead of z-shell/0
. This will work as expected e.g. zi update zsh/plugin
, zi remove zsh/plugin
, etc. プラグインをロードする前に「Hello World!」が表示されます。
Ice-modifierを増やしてもう一度インストールしましょう 。
- ターミナルで以下のコマンドを実行します。
zi ice id-as'final/countdown' \
atinit'+zi-message "{bapo}Cloned!"' \
atclone'+zi-message "{quos}Boom!"' \
atload'+zi-message "{apo}Loaded!"' countdown
zi load z-shell/0
Order of execution
関連する ice-modifier の実行順序は次のとおりです。
atinit'' →
atpull'!' →
make'!!' →
mv'' →
cp'' →
make'!' →
atclone'' / atpull'' →
make'!' →
[ plugin script loading ] →
src'' →
multisrc'' →
atload''
A few remarks
- The syntax automatically detects if the object is a snippet or a plugin, by checking if the object is an URL, i.e.: if it starts with
http*://
orOMZ::
, etc. - To load a local-file snippet (which will be treated as a local-directory plugin by default) use the
is-snippet
ice, - To load a plugin in
light
mode use thelight-mode
ice. - If the plugin name collides with an ice name, precede the plugin name with
@
, e.g.:@sharkdp/fd
(collides with thesh
ice, ZI will take the plugin name assh"arkdp/fd"
), see the next section for an example.
Syntax alternatives
Zi supports alternatives such as the equal (=
) syntax:
zi ice id-as=equal atload="print Hello World"
zi load z-shell/0
The colon (:
) syntax:
zi ice id-as:colon atload:"print Hello World"
zi load z-shell/0
そして、上記の全てと併せて、GNU 構文も同様に利用できます。
zi ice id-as=GNU --atload="print Hello World"
zi load z-shell/0
代わりの構文はVimのようなエディタのハイライトを利用し、文字列とiceの表現を別の色にすることができます。 However, with zi-vim-syntax the syntax definition can be superseded with the highlighting specifically for Zi. syntax definition can be superseded with the highlighting specifically for Zi.
Utilizing "make"
Vim repository on GitHub – a typical source code that needs compilation, Zi can manage the run of ./configure
and other make
stuff. Ice-modifier pick
adds the binary program to $PATH
. You could also install the package under the path $ZPFX.
zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \
atpull"%atclone" make pick"src/vim"
zi light vim/vim
The make'…'
ice could also be: make"install PREFIX=$ZPFX"
, if "install" wouldn't be the only, default target.
$ZPFX is provided by Zi, it is set to ~/.zi/polaris
by default. However, it can be changed by specifying the $ZPFX=
target.
zi ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX"
zi light tj/git-extras
The Makefile
of the project above has only 2 tasks:
- Install the target.
- Build scripts that are required for installation.
The Makefile
with 2 tasks, can use:
make"all install PREFIX=…"
,pick'…'
willchmod +x
all matching files and add$ZPFX/bin/
to$PATH
.
Compiling programs
zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \
atpull"%atclone" make pick"src/vim"
zi light vim/vim
構文 | 説明 |
---|---|
as'program' | Add file selected by pick'…' to $PATH , and do not source it. |
atclone'…' | ダウンロード後、任意のコマンドを実行する。 |
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 the 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
構文 | 説明 |
---|---|
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
構文 | 説明 |
---|---|
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'…' 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/direnv
make'!'
– executemake
beforeatclone'…'
and beforeatpull'…'
(seemake
above),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
構文 | 説明 |
---|---|
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
構文 | 説明 |
---|---|
from'gh-r' | Install from direnv from GitHub 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. |
extract'…'
A swiss-knife tool for unpacking all kinds of archives – the extract'…'
ice. It works in two modes – automatic mode and fixed mode.
Automatic mode:
It is active if the ice is empty (or contains only flags). It works as follows:
- At first, a recursive search for files of known file extensions located not deeper than in a sub-directory is being performed. All such found files are then extracted.
- The directory-level limit is to skip extraction of some helper archive files, which are typically located somewhere deeper in the directory tree.
- If no such files will be found, then a recursive search for files of known archive types will be performed. This is done by running the
file
Unix command on each file in the plugin or snippet directory and then grepping the output for strings likeZip
,bzip2
, etc. All such discovered files are then extracted.- The directory-level requirement is imposed during this stage. The files located deeper than in a sub-directory are omitted.
- If no archive files will be discovered then no action is being performed and also no warning message is being printed.
Fixed mode:
It is active when a filename is being passed as the extract
's argument, e.g.: zi extract=archive.zip for z-shell/null
. Multiple files can be specified – separated by spaces. In this mode all and only the specified files are being extracted.
Filenames with spaces:
The filenames with spaces are supported when correctly passing such filenames to an extract
with the non-breaking spaces for the original in-filename.
The non-breaking space is easy to type by pressing right ALT and the SPACE.
Flags:
The value of the ice can begin with two special characters:
- Exclamation mark (
!
), i.e.:extract='!…'
– it'll cause the files to be moved one directory level up upon unpacking, - Two exclamation marks (
!!
), i.e.:extract='!!…'
– it'll cause the files to be moved two directory-level up upon unpacking, - Dash (
-
), i.e.:extract'-…'
– it'll prevent removal of the archive after unpacking.- This flag allows comparing timestamps with the server in case of snippet-downloaded file – it will prevent unnecessary downloads during
zi update
, as the timestamp of the archive file on the disk will be first compared with the HTTP last-modification time header.
- This flag allows comparing timestamps with the server in case of snippet-downloaded file – it will prevent unnecessary downloads during
The flags can be combined in any order: extract'!-'
.
ziextract
Sometimes a more uncommon unpacking operation is needed. In such a case you can directly use the function that implements the ice – it is called ziextract
.
It recognizes the following options:
--auto
– runs the automatic extraction.--move
– performs the one-directory-level-up move of the files after unpacking.--move2
– performs the two-directory-level-up move of the files after unpacking.--norm
- prevents the archive file removal.- And also one option specific only to the function:
--nobkp
, which prevents clearing the plugin's directory before the extraction. – All files besides the archive are being moved into the._backup
directory after extraction is done. -extract
ice also skips creating the backup if more than one archive is found or given as the argument.
Supported file formats
Zip, rar, tar.gz, tar.bz2, tar.xz, tar.7z, tar, tgz, tbz2, gz, bz2, txz, xz, 7z, exe, deb, OS X (dmg).
from'…'
To install and load a plugin whose repository is private - e.g: requires providing credentials to log in – use the from'…'
ice in the following way:
zi ice from"user@github.com"
zi load user/fsh-auto-themes
現在のプリセット:
Ice name | Domain name / URL |
---|---|
ge | gitee.com |
gitee | gitee.com |
github | github.com |
gh | github.com |
gitlab | gitlab.com |
gl | gitlab.com |
notabug | notabug.org |
nb | notabug.org |
bitbucket | bitbucket.org |
bb | bitbucket.org |
github-rel | github.com/$remote_url_path/releases |
gh-r | github.com/$remote_url_path/releases |
cygwin | cygwin |
If the from'…'
ice isn't one of the above tables, then it is treated as a domain name and inserted into the domain position into the git clone
URL:
git clone https://{from-ice-contents}/user/plugin
In order to change the protocol, use the proto'…'
ice.
id-as'…'
Load a plugin or snippet with a nickname with the id-as'…'
ice-modifier. For example, one could try to load docker/compose from GitHub binary releases:
zi ice as"program" from"gh-r" mv"docker-c* -> docker-compose"
zi light "docker/compose"
This registers the plugin under the ID docker/compose
. Now suppose the user would want to also load a completion from the project's GitHub repository (not the binary release catalog) which is also available under the GitHub URL …/docker/compose. The two IDs, both being "docker/compose", will collide.
The solution to this problem – the id-as'…'
(to be read as identify-as) ice to which this document is devoted: by using the id-as'…'
ice the user can resolve the conflict by loading the completion under a kind of a nickname, for example under "dc-complete", by issuing the following commands:
zi ice as"completion" id-as"dc-complete"
zi load docker/compose
The plugin (of the type completion
) is now seen under ID dc-complete
:
zi list | grep -i dc-complete
dc-complete
Issuing zi report dc-complete
will work as with regular command:
zi report dc-complete
Plugin report for dc-complete
-------------------------------
Completions:
_docker-compose [enabled]
The same method applies to nickname snippets. For instance, use it to create handy IDs in place of long URLs:
zi ice as"program" id-as"git-unique"
zi snippet https://github.com/Osse/git-scripts/blob/master/git-unique