mirror of
git://git.code.sf.net/p/zsh/code
synced 2024-06-03 13:56:03 +02:00
0501efc54a
Here's a diff-stat: Doc/Zsh/contrib.yo | 506 ++++++++++++++------- Functions/VCS_Info/.distfiles | 1 + Functions/VCS_Info/Backends/VCS_INFO_detect_hg | 14 +- Functions/VCS_Info/Backends/VCS_INFO_get_data_git | 35 +- Functions/VCS_Info/Backends/VCS_INFO_get_data_hg | 295 +++++++++---- Functions/VCS_Info/VCS_INFO_formats | 26 +- Functions/VCS_Info/VCS_INFO_hook | 10 +- Functions/VCS_Info/VCS_INFO_quilt | 190 ++++++++ Functions/VCS_Info/vcs_info | 30 +- Misc/.distfiles | 1 + Misc/vcs_info-examples | 496 ++++++++++++++++++++ 11 files changed, 1303 insertions(+), 301 deletions(-) The major changes are vast improvements for the mercurial (hg) backend (which was done almost entirely by Seth); improved documentation (mostly done by Simon and again Seth); quilt support (as an addon and stand alone, see the manual for details); a number of new hooks and a fair share of bugfixes.
3311 lines
137 KiB
Plaintext
3311 lines
137 KiB
Plaintext
texinode(User Contributions)()(Zftp Function System)(Top)
|
|
chapter(User Contributions)
|
|
cindex(user contributions)
|
|
sect(Description)
|
|
|
|
The Zsh source distribution includes a number of items contributed by the
|
|
user community. These are not inherently a part of the shell, and some
|
|
may not be available in every zsh installation. The most significant of
|
|
these are documented here. For documentation on other contributed items
|
|
such as shell functions, look for comments in the function source files.
|
|
|
|
startmenu()
|
|
menu(Utilities)
|
|
menu(Version Control Information)
|
|
menu(Prompt Themes)
|
|
menu(ZLE Functions)
|
|
menu(Exception Handling)
|
|
menu(MIME Functions)
|
|
menu(Mathematical Functions)
|
|
menu(User Configuration Functions)
|
|
menu(Other Functions)
|
|
endmenu()
|
|
|
|
texinode(Utilities)(Version Control Information)()(User Contributions)
|
|
sect(Utilities)
|
|
|
|
subsect(Accessing On-Line Help)
|
|
cindex(helpfiles utility)
|
|
|
|
The key sequence tt(ESC h) is normally bound by ZLE to execute the
|
|
tt(run-help) widget (see
|
|
ifzman(zmanref(zshzle))\
|
|
ifnzman(noderef(Zsh Line Editor))\
|
|
). This invokes the tt(run-help) command with the command word from the
|
|
current input line as its argument. By default, tt(run-help) is an alias
|
|
for the tt(man) command, so this often fails when the command word is a
|
|
shell builtin or a user-defined function. By redefining the tt(run-help)
|
|
alias, one can improve the on-line help provided by the shell.
|
|
|
|
The tt(helpfiles) utility, found in the tt(Util) directory of the
|
|
distribution, is a Perl program that can be used to process the zsh manual
|
|
to produce a separate help file for each shell builtin and for many other
|
|
shell features as well. The autoloadable tt(run-help) function, found in
|
|
tt(Functions/Misc), searches for these helpfiles and performs several
|
|
other tests to produce the most complete help possible for the command.
|
|
|
|
There may already be a directory of help files on your system; look in
|
|
tt(/usr/share/zsh) or tt(/usr/local/share/zsh) and subdirectories below
|
|
those, or ask your system administrator.
|
|
|
|
To create your own help files with tt(helpfiles), choose or create a
|
|
directory where the individual command help files will reside. For
|
|
example, you might choose tt(~/zsh_help). If you unpacked the zsh
|
|
distribution in your home directory, you would use the commands:
|
|
|
|
example(mkdir ~/zsh_help
|
|
cd ~/zsh_help
|
|
man zshall | colcrt - | \
|
|
perl ~/zsh-version()/Util/helpfiles)
|
|
|
|
findex(run-help, use of)
|
|
Next, to use the tt(run-help) function, you need to add lines something
|
|
like the following to your tt(.zshrc) or equivalent startup file:
|
|
|
|
example(unalias run-help
|
|
autoload run-help
|
|
HELPDIR=~/zsh_help)
|
|
|
|
vindex(HELPDIR)
|
|
The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
|
|
files. If your system already has a help file directory installed, set
|
|
tt(HELPDIR) to the path of that directory instead.
|
|
|
|
Note that in order for `tt(autoload run-help)' to work, the tt(run-help)
|
|
file must be in one of the directories named in your tt(fpath) array (see
|
|
ifzman(zmanref(zshparam))\
|
|
ifnzman(noderef(Parameters Used By The Shell))\
|
|
). This should already be the case if you have a standard zsh
|
|
installation; if it is not, copy tt(Functions/Misc/run-help) to an
|
|
appropriate directory.
|
|
|
|
subsect(Recompiling Functions)
|
|
cindex(functions, recompiling)
|
|
cindex(zrecompile utility)
|
|
|
|
If you frequently edit your zsh functions, or periodically update your zsh
|
|
installation to track the latest developments, you may find that function
|
|
digests compiled with the tt(zcompile) builtin are frequently out of date
|
|
with respect to the function source files. This is not usually a problem,
|
|
because zsh always looks for the newest file when loading a function, but
|
|
it may cause slower shell startup and function loading. Also, if a digest
|
|
file is explicitly used as an element of tt(fpath), zsh won't check whether
|
|
any of its source files has changed.
|
|
|
|
The tt(zrecompile) autoloadable function, found in tt(Functions/Misc), can
|
|
be used to keep function digests up to date.
|
|
|
|
startitem()
|
|
findex(zrecompile)
|
|
xitem(tt(zrecompile) [ tt(-qt) ] [ var(name) ... ])
|
|
item(tt(zrecompile) [ tt(-qt) ] tt(-p) var(args) [ tt(-)tt(-) var(args) ... ])(
|
|
This tries to find tt(*.zwc) files and automatically re-compile them if at
|
|
least one of the original files is newer than the compiled file. This
|
|
works only if the names stored in the compiled files are full paths or are
|
|
relative to the directory that contains the tt(.zwc) file.
|
|
|
|
In the first form, each var(name) is the name of a compiled file or a
|
|
directory containing tt(*.zwc) files that should be checked. If no
|
|
arguments are given, the directories and tt(*.zwc) files in tt(fpath) are
|
|
used.
|
|
|
|
When tt(-t) is given, no compilation is performed, but a return status of
|
|
zero (true) is set if there are files that need to be re-compiled and
|
|
non-zero (false) otherwise. The tt(-q) option quiets the chatty output
|
|
that describes what tt(zrecompile) is doing.
|
|
|
|
Without the tt(-t) option, the return status is zero if all files that
|
|
needed re-compilation could be compiled and non-zero if compilation for at
|
|
least one of the files failed.
|
|
|
|
If the tt(-p) option is given, the var(args) are interpreted as one
|
|
or more sets of arguments for tt(zcompile), separated by `tt(-)tt(-)'.
|
|
For example:
|
|
|
|
example(zrecompile -p \
|
|
-R ~/.zshrc -- \
|
|
-M ~/.zcompdump -- \
|
|
~/zsh/comp.zwc ~/zsh/Completion/*/_*)
|
|
|
|
This compiles tt(~/.zshrc) into tt(~/.zshrc.zwc) if that doesn't exist or
|
|
if it is older than tt(~/.zshrc). The compiled file will be marked for
|
|
reading instead of mapping. The same is done for tt(~/.zcompdump) and
|
|
tt(~/.zcompdump.zwc), but this compiled file is marked for mapping. The
|
|
last line re-creates the file tt(~/zsh/comp.zwc) if any of the files
|
|
matching the given pattern is newer than it.
|
|
|
|
Without the tt(-p) option, tt(zrecompile) does not create function digests
|
|
that do not already exist, nor does it add new functions to the digest.
|
|
)
|
|
enditem()
|
|
|
|
The following shell loop is an example of a method for creating function
|
|
digests for all functions in your tt(fpath), assuming that you have write
|
|
permission to the directories:
|
|
|
|
example(for ((i=1; i <= $#fpath; ++i)); do
|
|
dir=$fpath[i]
|
|
zwc=${dir:t}.zwc
|
|
if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
|
|
continue
|
|
fi
|
|
files=($dir/*(N-.))
|
|
if [[ -w $dir:h && -n $files ]]; then
|
|
files=(${${(M)files%/*/*}#/})
|
|
if ( cd $dir:h &&
|
|
zrecompile -p -U -z $zwc $files ); then
|
|
fpath[i]=$fpath[i].zwc
|
|
fi
|
|
fi
|
|
done)
|
|
|
|
The tt(-U) and tt(-z) options are appropriate for functions in the default
|
|
zsh installation tt(fpath); you may need to use different options for your
|
|
personal function directories.
|
|
|
|
Once the digests have been created and your tt(fpath) modified to refer to
|
|
them, you can keep them up to date by running tt(zrecompile) with no
|
|
arguments.
|
|
|
|
subsect(Keyboard Definition)
|
|
cindex(keyboard definition)
|
|
|
|
findex(zkbd)
|
|
The large number of possible combinations of keyboards, workstations,
|
|
terminals, emulators, and window systems makes it impossible for zsh to
|
|
have built-in key bindings for every situation. The tt(zkbd) utility,
|
|
found in Functions/Misc, can help you quickly create key bindings for your
|
|
configuration.
|
|
|
|
Run tt(zkbd) either as an autoloaded function, or as a shell script:
|
|
|
|
example(zsh -f ~/zsh-version()/Functions/Misc/zkbd)
|
|
|
|
When you run tt(zkbd), it first asks you to enter your terminal type; if
|
|
the default it offers is correct, just press return. It then asks you to
|
|
press a number of different keys to determine characteristics of your
|
|
keyboard and terminal; tt(zkbd) warns you if it finds anything out of the
|
|
ordinary, such as a Delete key that sends neither tt(^H) nor tt(^?).
|
|
|
|
The keystrokes read by tt(zkbd) are recorded as a definition for an
|
|
associative array named tt(key), written to a file in the subdirectory
|
|
tt(.zkbd) within either your tt(HOME) or tt(ZDOTDIR) directory. The name
|
|
of the file is composed from the tt(TERM), tt(VENDOR) and tt(OSTYPE)
|
|
parameters, joined by hyphens.
|
|
|
|
You may read this file into your tt(.zshrc) or another startup file with
|
|
the `tt(source)' or `tt(.)' commands, then reference the tt(key) parameter
|
|
in bindkey commands, like this:
|
|
|
|
example(source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
|
|
[[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
|
|
[[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
|
|
# etc.)
|
|
|
|
Note that in order for `tt(autoload zkbd)' to work, the tt(zkdb) file must
|
|
be in one of the directories named in your tt(fpath) array (see
|
|
ifzman(zmanref(zshparam))\
|
|
ifnzman(noderef(Parameters Used By The Shell))\
|
|
). This should already be the case if you have a standard zsh
|
|
installation; if it is not, copy tt(Functions/Misc/zkbd) to an
|
|
appropriate directory.
|
|
|
|
subsect(Dumping Shell State)
|
|
cindex(reporter utility)
|
|
|
|
Occasionally you may encounter what appears to be a bug in the shell,
|
|
particularly if you are using a beta version of zsh or a development
|
|
release. Usually it is sufficient to send a description of the
|
|
problem to one of the zsh mailing lists (see
|
|
ifzman(zmanref(zsh))\
|
|
ifnzman(noderef(Mailing Lists))\
|
|
), but sometimes one of the zsh developers will need to recreate your
|
|
environment in order to track the problem down.
|
|
|
|
The script named tt(reporter), found in the tt(Util) directory of the
|
|
distribution, is provided for this purpose. (It is also possible to
|
|
tt(autoload reporter), but tt(reporter) is not installed in tt(fpath)
|
|
by default.) This script outputs a detailed dump of the shell state,
|
|
in the form of another script that can be read with `tt(zsh -f)' to
|
|
recreate that state.
|
|
|
|
To use tt(reporter), read the script into your shell with the `tt(.)'
|
|
command and redirect the output into a file:
|
|
|
|
example(. ~/zsh-version()/Util/reporter > zsh.report)
|
|
|
|
You should check the tt(zsh.report) file for any sensitive information
|
|
such as passwords and delete them by hand before sending the script to the
|
|
developers. Also, as the output can be voluminous, it's best to wait for
|
|
the developers to ask for this information before sending it.
|
|
|
|
You can also use tt(reporter) to dump only a subset of the shell state.
|
|
This is sometimes useful for creating startup files for the first time.
|
|
Most of the output from reporter is far more detailed than usually is
|
|
necessary for a startup file, but the tt(aliases), tt(options), and
|
|
tt(zstyles) states may be useful because they include only changes from
|
|
the defaults. The tt(bindings) state may be useful if you have created
|
|
any of your own keymaps, because tt(reporter) arranges to dump the keymap
|
|
creation commands as well as the bindings for every keymap.
|
|
|
|
As is usual with automated tools, if you create a startup file with
|
|
tt(reporter), you should edit the results to remove unnecessary commands.
|
|
Note that if you're using the new completion system, you should em(not)
|
|
dump the tt(functions) state to your startup files with tt(reporter); use
|
|
the tt(compdump) function instead (see
|
|
ifzman(zmanref(zshcompsys))\
|
|
ifnzman(noderef(Completion System))\
|
|
).
|
|
|
|
startitem()
|
|
item(tt(reporter) [ var(state) ... ])(
|
|
findex(reporter)
|
|
Print to standard output the indicated subset of the current shell state.
|
|
The var(state) arguments may be one or more of:
|
|
|
|
startsitem()
|
|
sitem(tt(all))(Output everything listed below.)
|
|
sitem(tt(aliases))(Output alias definitions.)
|
|
sitem(tt(bindings))(Output ZLE key maps and bindings.)
|
|
sitem(tt(completion))(Output old-style tt(compctl) commands.
|
|
New completion is covered by tt(functions) and tt(zstyles).)
|
|
sitem(tt(functions))(Output autoloads and function definitions.)
|
|
sitem(tt(limits))(Output tt(limit) commands.)
|
|
sitem(tt(options))(Output tt(setopt) commands.)
|
|
sitem(tt(styles))(Same as tt(zstyles).)
|
|
sitem(tt(variables))(Output shell parameter assignments, plus tt(export)
|
|
commands for any environment variables.)
|
|
sitem(tt(zstyles))(Output tt(zstyle) commands.)
|
|
endsitem()
|
|
|
|
If the var(state) is omitted, tt(all) is assumed.
|
|
)
|
|
|
|
With the exception of `tt(all)', every var(state) can be abbreviated by
|
|
any prefix, even a single letter; thus tt(a) is the same as tt(aliases),
|
|
tt(z) is the same as tt(zstyles), etc.
|
|
enditem()
|
|
|
|
subsect(Manipulating Hook Functions)
|
|
cindex(hook function utility)
|
|
|
|
startitem()
|
|
findex(add-zsh-hook)
|
|
item(tt(add-zsh-hook) [-dD] var(hook) var(function))(
|
|
Several functions are special to the shell, as described in the section
|
|
ifnzman(Special Functions, noderef(Functions))\
|
|
ifzman(SPECIAL FUNCTIONS, see zmanref(zshmisc)),
|
|
in that they are automatic called at a specific point during shell execution.
|
|
Each has an associated array consisting of names of functions to be
|
|
called at the same point; these are so-called `hook functions'.
|
|
The shell function tt(add-zsh-hook) provides a simple way of adding or
|
|
removing functions from the array.
|
|
|
|
var(hook) is one of tt(chpwd), tt(periodic), tt(precmd) or tt(preexec),
|
|
the special functions in question.
|
|
|
|
var(functions) is name of an ordinary shell function. If no options
|
|
are given this will be added to the array of functions to be executed.
|
|
in the given context.
|
|
|
|
If the option tt(-d) is given, the var(function) is removed from
|
|
the array of functions to be executed.
|
|
|
|
If the option tt(-D) is given, the var(function) is treated as a pattern
|
|
and any matching names of functions are removed from the array of
|
|
functions to be executed.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Version Control Information)(Prompt Themes)(Utilities)(User Contributions)
|
|
sect(Gathering information from version control systems)
|
|
cindex(version control utility)
|
|
|
|
In a lot of cases, it is nice to automatically retrieve information from
|
|
version control systems (VCSs), such as subversion, CVS or git, to be able
|
|
to provide it to the user; possibly in the user's prompt. So that you can
|
|
instantly tell which branch you are currently on, for example.
|
|
|
|
In order to do that, you may use the tt(vcs_info) function.
|
|
|
|
The following VCSs are supported, showing the abbreviated name by which
|
|
they are referred to within the system:
|
|
startsitem()
|
|
sitem(Bazaar (tt(bzr)))(http://bazaar-vcs.org/)
|
|
sitem(Codeville (tt(cdv)))(http://codeville.org/)
|
|
sitem(Concurrent Versioning System (tt(cvs)))(http://www.nongnu.org/cvs/)
|
|
sitem(Darcs (tt(darcs)))(http://darcs.net/)
|
|
sitem(Git (tt(git)))(http://git-scm.com/)
|
|
sitem(GNU arch (tt(tla)))(http://www.gnu.org/software/gnu-arch/)
|
|
sitem(Mercurial (tt(hg)))(http://mercurial.selenic.com/)
|
|
sitem(Monotone (tt(mtn)))(http://monotone.ca/)
|
|
sitem(Perforce (tt(p4)))(http://www.perforce.com/)
|
|
sitem(Subversion (tt(svn)))(http://subversion.tigris.org/)
|
|
sitem(SVK (tt(svk)))(http://svk.bestpractical.com/)
|
|
endsitem()
|
|
|
|
There is also support for the patch management system tt(quilt)
|
|
(http://savannah.nongnu.org/projects/quilt). See tt(Quilt Support)
|
|
below for details.
|
|
|
|
To load var(vcs_info):
|
|
|
|
example(autoload -Uz vcs_info)
|
|
|
|
It can be used in any existing prompt, because it does not require any
|
|
tt($psvar) entries to be left available.
|
|
|
|
subsect(Quickstart)
|
|
|
|
To get this feature working quickly (including colors), you can do the
|
|
following (assuming, you loaded var(vcs_info) properly - see above):
|
|
|
|
example(zstyle ':vcs_info:*' actionformats \
|
|
'%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
|
|
zstyle ':vcs_info:*' formats \
|
|
'%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '
|
|
zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
|
|
precmd () { vcs_info }
|
|
PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# ')
|
|
|
|
Obviously, the last two lines are there for demonstration. You need to
|
|
call var(vcs_info) from your var(precmd) function. Once that is done you need
|
|
a tt(single quoted) var('${vcs_info_msg_0_}') in your prompt.
|
|
|
|
To be able to use var('${vcs_info_msg_0_}') directly in your prompt like
|
|
this, you will need to have the tt(PROMPT_SUBST) option enabled.
|
|
|
|
Now call the tt(vcs_info_printsys) utility from the command line:
|
|
|
|
example(% vcs_info_printsys
|
|
## list of supported version control backends:
|
|
## disabled systems are prefixed by a hash sign (#)
|
|
bzr
|
|
cdv
|
|
cvs
|
|
darcs
|
|
git
|
|
hg
|
|
mtn
|
|
p4
|
|
svk
|
|
svn
|
|
tla
|
|
## flavours (cannot be used in the enable or disable styles; they
|
|
## are enabled and disabled with their master [git-svn -> git])
|
|
## they *can* be used in contexts: ':vcs_info:git-svn:*'.
|
|
git-p4
|
|
git-svn
|
|
hg-git
|
|
hg-hgsubversion
|
|
hg-hgsvn)
|
|
|
|
You may not want all of these because there is no point in running the
|
|
code to detect systems you do not use. So there is a way to disable
|
|
some backends altogether:
|
|
|
|
example(zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla)
|
|
|
|
You may also pick a few from that list and enable only those:
|
|
|
|
example(zstyle ':vcs_info:*' enable git cvs svn)
|
|
|
|
If you rerun tt(vcs_info_printsys) after one of these commands, you will
|
|
see the backends listed in the var(disable) style (or backends not in the
|
|
var(enable) style - if you used that) marked as disabled by a hash sign.
|
|
That means the detection of these systems is skipped tt(completely). No
|
|
wasted time there.
|
|
|
|
|
|
subsect(Configuration)
|
|
|
|
The var(vcs_info) feature can be configured via var(zstyle).
|
|
|
|
First, the context in which we are working:
|
|
example(:vcs_info:<vcs-string>:<user-context>:<repo-root-name>)
|
|
|
|
startitem()
|
|
item(tt(<vcs-string>))(
|
|
is one of: git, git-svn, git-p4, hg, hg-git, hg-hgsubversion, hg-hgsvn,
|
|
darcs, bzr, cdv, mtn, svn, cvs, svk, tla or p4. When hooks are active the
|
|
hooks name is added after a `+'. (See tt(Hooks in vcs_info) below.)
|
|
)
|
|
item(tt(<user-context>))(
|
|
is a freely configurable string, assignable by
|
|
the user as the first argument to var(vcs_info) (see its description
|
|
below).
|
|
)
|
|
item(tt(<repo-root-name>))(
|
|
is the name of a repository in which you want a
|
|
style to match. So, if you want a setting specific to var(/usr/src/zsh),
|
|
with that being a CVS checkout, you can set tt(<repo-root-name>) to
|
|
var(zsh) to make it so.
|
|
)
|
|
enditem()
|
|
|
|
There are three special values for tt(<vcs-string>): The first is named
|
|
var(-init-), that is in effect as long as there was no decision what VCS
|
|
backend to use. The second is var(-preinit-); it is used tt(before)
|
|
var(vcs_info) is run, when initializing the data exporting variables. The
|
|
third special value is var(formats) and is used by the tt(vcs_info_lastmsg)
|
|
for looking up its styles.
|
|
|
|
The initial value of tt(<repo-root-name>) is var(-all-) and it is replaced
|
|
with the actual name, as soon as it is known. Only use this part of the
|
|
context for defining the var(formats), var(actionformats) or
|
|
var(branchformat) styles. As it is guaranteed that tt(<repo-root-name>) is
|
|
set up correctly for these only. For all other styles, just use tt('*')
|
|
instead.
|
|
|
|
There are two pre-defined values for tt(<user-context>):
|
|
startsitem()
|
|
sitem(tt(default))(the one used if none is specified)
|
|
sitem(tt(command))(used by vcs_info_lastmsg to lookup its styles)
|
|
endsitem()
|
|
|
|
You can of course use tt(':vcs_info:*') to match all VCSs in all
|
|
user-contexts at once.
|
|
|
|
This is a description of all styles that are looked up.
|
|
|
|
startitem()
|
|
kindex(formats)
|
|
item(tt(formats))(
|
|
A list of formats, used when actionformats is not used
|
|
(which is most of the time).
|
|
)
|
|
kindex(actionformats)
|
|
item(tt(actionformats))(
|
|
A list of formats, used if a there is a special
|
|
action going on in your current repository; like an interactive rebase or
|
|
a merge conflict.
|
|
)
|
|
kindex(branchformat)
|
|
item(tt(branchformat))(
|
|
Some backends replace var(%b) in the formats and
|
|
actionformats styles above, not only by a branch name but also by a
|
|
revision number. This style lets you modify how that string should look.
|
|
)
|
|
kindex(nvcsformats)
|
|
item(tt(nvcsformats))(
|
|
These "formats" are exported when we didn't detect
|
|
a version control system for the current directory. This is useful if you
|
|
want var(vcs_info) to completely take over the generation of your prompt.
|
|
You would do something like tt(PS1='${vcs_info_msg_0_}') to accomplish
|
|
that.
|
|
)
|
|
kindex(hgrevformat)
|
|
item(tt(hgrevformat))(
|
|
tt(hg) uses both a hash and a revision number to reference a specific
|
|
changeset in a repository. With this style you can format the revision
|
|
string (see var(branchformat)) to include either or both. It's only
|
|
useful when var(get-revision) is true.
|
|
)
|
|
kindex(max-exports)
|
|
item(tt(max-exports))(
|
|
Defines the maximum number of
|
|
var(vcs_info_msg_*_) variables var(vcs_info) will export.
|
|
)
|
|
kindex(enable)
|
|
item(tt(enable))(
|
|
A list of backends you want to use. Checked in the var(-init-) context. If
|
|
this list contains an item called tt(NONE) no backend is used at all and
|
|
var(vcs_info) will do nothing. If this list contains tt(ALL) var(vcs_info)
|
|
will use all known backends. Only with tt(ALL) in tt(enable) will the
|
|
tt(disable) style have any effect. tt(ALL) and tt(NONE) are case insensitive.
|
|
)
|
|
kindex(disable)
|
|
item(tt(disable))(
|
|
A list of VCSs you don't want var(vcs_info) to test for
|
|
repositories (checked in the var(-init-) context, too). Only used if
|
|
tt(enable) contains tt(ALL).
|
|
)
|
|
kindex(disable-patterns)
|
|
item(tt(disable-patterns))(
|
|
A list of patterns that are checked against tt($PWD). If a pattern
|
|
matches, var(vcs_info) will be disabled. This style is checked in the
|
|
var(:vcs_info:-init-:*:-all-) context.
|
|
|
|
Say, tt(~/.zsh) is a directory under version control, in which you do
|
|
not want var(vcs_info) to be active, do:
|
|
example(zstyle ':vcs_info:*' disable-patterns "$HOME/.zsh+LPAR()|/*+RPAR()")
|
|
)
|
|
kindex(use-quilt)
|
|
item(tt(use-quilt))(
|
|
If enabled, the tt(quilt) support code is active in `addon' mode.
|
|
See tt(Quilt Support) for details.
|
|
)
|
|
kindex(quilt-standalone)
|
|
item(tt(quilt-standalone))(
|
|
If enabled, `standalone' mode detection is attempted if no VCS is active
|
|
in a given directory. See tt(Quilt Support) for details.
|
|
)
|
|
kindex(quilt-patch-dir)
|
|
item(tt(quilt-patch-dir))(
|
|
Overwrite the value of the var($QUILT_PATCHES) environment variable. See
|
|
tt(Quilt Support) for details.
|
|
)
|
|
kindex(quiltcommand)
|
|
item(tt(quiltcommand))(
|
|
When tt(quilt) itself is called in quilt support the value of this style
|
|
is used as the command name.
|
|
)
|
|
kindex(check-for-changes)
|
|
item(tt(check-for-changes))(
|
|
If enabled, this style causes the tt(%c) and tt(%u) format escapes to show
|
|
when the working directory has uncommitted changes. The strings displayed by
|
|
these escapes can be controlled via the var(stagedstr) and var(unstagedstr)
|
|
styles. The only backends that currently support this option are tt(git) and
|
|
tt(hg) (tt(hg) only supports unstaged).
|
|
|
|
Note, the actions taken if this style is enabled are potentially expensive
|
|
(read: they may be slow, depending on how big the current repository is).
|
|
Therefore, it is disabled by default.
|
|
)
|
|
kindex(stagedstr)
|
|
item(tt(stagedstr))(
|
|
This string will be used in the tt(%c) escape if there are staged changes in
|
|
the repository.
|
|
)
|
|
kindex(unstagedstr)
|
|
item(tt(unstagedstr))(
|
|
This string will be used in the tt(%u) escape if there are unstaged changes
|
|
in the repository.
|
|
)
|
|
kindex(command)
|
|
item(tt(command))(
|
|
This style causes var(vcs_info) to use the supplied string as the command
|
|
to use as the VCS's binary. Note, that setting this in ':vcs_info:*' is
|
|
not a good idea.
|
|
|
|
If the value of this style is empty (which is the default), the used binary
|
|
name is the name of the backend in use (e.g. var(svn) is used in an var(svn)
|
|
repository).
|
|
|
|
The var(repo-root-name) part in the context is always the default tt(-all-)
|
|
when this style is looked up.
|
|
|
|
For example, this style can be used to use binaries from non-default
|
|
installation directories. Assume, var(git) is installed in /usr/bin but
|
|
your sysadmin installed a newer version in /usr/bin/local. Instead of
|
|
changing the order of your tt($PATH) parameter, you can do this:
|
|
example(zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git)
|
|
)
|
|
kindex(use-server)
|
|
item(tt(use-server))(
|
|
This is used by the Perforce backend (tt(p4)) to decide if it should
|
|
contact the Perforce server to find out if a directory is managed
|
|
by Perforce. This is the only reliable way of doing this, but runs
|
|
the risk of a delay if the server name cannot be found. If the
|
|
server (more specifically, the var(host)tt(:)var(port) pair describing the
|
|
server) cannot be contacted, its name is put into the associative array
|
|
tt(vcs_info_p4_dead_servers) and is not contacted again during the session
|
|
until it is removed by hand. If you do not set this style, the tt(p4)
|
|
backend is only usable if you have set the environment variable
|
|
tt(P4CONFIG) to a file name and have corresponding files in the root
|
|
directories of each Perforce client. See comments in the function
|
|
tt(VCS_INFO_detect_p4) for more detail.
|
|
)
|
|
kindex(use-simple)
|
|
item(tt(use-simple))(
|
|
If there are two different ways of gathering
|
|
information, you can select the simpler one by setting this style to true;
|
|
the default is to use the not-that-simple code, which is potentially a lot
|
|
slower but might be more accurate in all possible cases. This style is
|
|
used by the tt(bzr) and tt(hg) backends. In the case of tt(hg) it will invoke
|
|
the external hexdump program to parse the binary dirstate cache file; this
|
|
method will not return the local revision number.
|
|
)
|
|
kindex(get-revision)
|
|
item(tt(get-revision))(
|
|
If set to true, vcs_info goes the extra mile to figure out the revision of
|
|
a repository's work tree (currently for the tt(git) and tt(hg) backends,
|
|
where this kind of information is not always vital). For tt(git), the
|
|
hash value of the currently checked out commit is available via the tt(%i)
|
|
expansion. With tt(hg), the local revision number and the corresponding
|
|
global hash are available via tt(%i).
|
|
)
|
|
kindex(get-mq)
|
|
item(tt(get-mq))(
|
|
If set to true, the tt(hg) backend will look for a Mercurial Queue (tt(mq))
|
|
patch directory. Information will be available via the `tt(%m)' replacement.
|
|
)
|
|
kindex(get-bookmarks)
|
|
item(tt(get-bookmarks))(
|
|
If set to true, the tt(hg) backend will try to get a list of current
|
|
bookmarks. They will be available via the `tt(%m)' replacement.
|
|
)
|
|
kindex(use-prompt-escapes)
|
|
item(tt(use-prompt-escapes))(
|
|
Determines if we assume that the assembled
|
|
string from var(vcs_info) includes prompt escapes. (Used by
|
|
tt(vcs_info_lastmsg).)
|
|
)
|
|
kindex(debug)
|
|
item(tt(debug))(
|
|
Enable debugging output to track possible problems. Currently this style
|
|
is only used by var(vcs_info)'s hooks system.
|
|
)
|
|
kindex(hooks)
|
|
item(tt(hooks))(
|
|
A list style that defines hook-function names. See tt(Hooks in vcs_info)
|
|
below for details.
|
|
)
|
|
enditem()
|
|
|
|
The default values for these styles in all contexts are:
|
|
|
|
startsitem()
|
|
sitem(tt(formats))(" (%s)-[%b]-")
|
|
sitem(tt(actionformats))(" (%s)-[%b|%a]-")
|
|
sitem(tt(branchformat))("%b:%r" (for bzr, svn, svk and hg))
|
|
sitem(tt(nvcsformats))("")
|
|
sitem(tt(hgrevformat))("%r:%h")
|
|
sitem(tt(max-exports))(2)
|
|
sitem(tt(enable))(ALL)
|
|
sitem(tt(disable))((empty list))
|
|
sitem(tt(disable-patterns))((empty list))
|
|
sitem(tt(check-for-changes))(false)
|
|
sitem(tt(stagedstr))((string: "S"))
|
|
sitem(tt(unstagedstr))((string: "U"))
|
|
sitem(tt(command))((empty string))
|
|
sitem(tt(use-server))(false)
|
|
sitem(tt(use-simple))(false)
|
|
sitem(tt(get-revision))(false)
|
|
sitem(tt(get-mq))(true)
|
|
sitem(tt(get-bookmarks))(false)
|
|
sitem(tt(use-prompt-escapes))(true)
|
|
sitem(tt(debug))(false)
|
|
sitem(tt(hooks))((empty list))
|
|
sitem(tt(use-quilt))(false)
|
|
sitem(tt(quilt-standalone))(false)
|
|
sitem(tt(quilt-patch-dir))(empty - use var($QUILT_PATCHES))
|
|
sitem(tt(quiltcommand))(quilt)
|
|
endsitem()
|
|
|
|
In normal tt(formats) and tt(actionformats) the following replacements are
|
|
done:
|
|
|
|
startsitem()
|
|
sitem(tt(%s))(The VCS in use (git, hg, svn, etc.).)
|
|
sitem(tt(%b))(Information about the current branch.)
|
|
sitem(tt(%a))(An identifier that describes the action. Only makes sense in
|
|
var(actionformats).)
|
|
sitem(tt(%i))(The current revision number or identifier. For tt(hg)
|
|
the var(hgrevformat) style may be used to customize the output.)
|
|
sitem(tt(%c))(The string from the var(stagedstr) style if there are staged
|
|
changes in the repository.)
|
|
sitem(tt(%u))(The string from the var(unstagedstr) style if there are
|
|
unstaged changes in the repository.)
|
|
sitem(tt(%R))(The base directory of the repository.)
|
|
sitem(tt(%r))(The repository name. If tt(%R) is var(/foo/bar/repoXY), tt(%r)
|
|
is var(repoXY).)
|
|
sitem(tt(%S))(A subdirectory within a repository. If tt($PWD) is
|
|
var(/foo/bar/repoXY/beer/tasty), tt(%S) is var(beer/tasty).)
|
|
sitem(tt(%m))(A "misc" replacement. It is at the discretion of the backend to
|
|
decide what this replacement expands to. It is currently used by the tt(hg)
|
|
and tt(git) backends to display patch information from the tt(mq) and
|
|
tt(stgit) extensions.)
|
|
endsitem()
|
|
|
|
In tt(branchformat) these replacements are done:
|
|
|
|
startsitem()
|
|
sitem(tt(%b))(The branch name.)
|
|
sitem(tt(%r))(The current revision number or the var(hgrevformat) style for
|
|
tt(hg).)
|
|
endsitem()
|
|
|
|
In tt(hgrevformat) these replacements are done:
|
|
|
|
startsitem()
|
|
sitem(tt(%r))(The current local revision number.)
|
|
sitem(tt(%h))(The current 40-character changeset ID hash identifier.)
|
|
endsitem()
|
|
|
|
In tt(patch-format) and tt(nopatch-format) these replacements are done:
|
|
|
|
startsitem()
|
|
sitem(tt(%p))(The name of the top-most applied patch.)
|
|
sitem(tt(%u))(The number of unapplied patches.)
|
|
sitem(tt(%n))(The number of applied patches.)
|
|
sitem(tt(%c))(The number of unapplied patches.)
|
|
sitem(tt(%g))(The names of active tt(mq) guards (tt(hg) backend).)
|
|
sitem(tt(%G))(The number of active tt(mq) guards (tt(hg) backend).)
|
|
endsitem()
|
|
|
|
Not all VCS backends have to support all replacements. For tt(nvcsformats)
|
|
no replacements are performed at all, it is just a string.
|
|
|
|
subsect(Oddities)
|
|
|
|
If you want to use the tt(%b) (bold off) prompt expansion in var(formats),
|
|
which expands tt(%b) itself, use tt(%%b). That will cause the var(vcs_info)
|
|
expansion to replace tt(%%b) with tt(%b). So zsh's prompt expansion
|
|
mechanism can handle it. Similarly, to hand down tt(%b) from
|
|
var(branchformat), use tt(%%%%b). Sorry for this inconvenience, but it
|
|
cannot be easily avoided. Luckily we do not clash with a lot of prompt
|
|
expansions and this only needs to be done for those.
|
|
|
|
|
|
subsect(Quilt Support)
|
|
|
|
tt(Quilt) is not a version control system, therefore this is not implemented
|
|
as a backend. It can help keeping track of a series of patches. People use it
|
|
to keep a set of changes they want to use on top of software packages (which
|
|
is tightly integrated into the package build process - the Debian project
|
|
does this for a large number of packages). Quilt can also help individual
|
|
developers keep track of their own patches on top of real version control
|
|
systems.
|
|
|
|
The var(vcs_info) integration tries to support both ways of using quilt by
|
|
having two slightly different modes of operation: `addon' mode and
|
|
`standalone' mode).
|
|
|
|
For `addon' mode to become active var(vcs_info) must have already detected a
|
|
real version control system controlling the directory. If that is the case,
|
|
a directory that holds quilt's patches needs to be found. That directory is
|
|
configurable via the var(`QUILT_PATCHES') environment variable. If that
|
|
variable exists its value is used, otherwise the value tt(`patches') is
|
|
assumed. The value from var($QUILT_PATCHES) can be overwritten using the
|
|
tt(`quilt-patches') style. (Note: you can use var(vcs_info) to keep the value
|
|
of var($QUILT_PATCHES) correct all the time via the tt(post-quilt) hook).
|
|
|
|
When the directory in question is found, quilt is assumed to be active. To
|
|
gather more information, var(vcs_info) looks for a directory called `.pc';
|
|
Quilt uses that directory to track its current state. If this directory does
|
|
not exist we know that quilt has not done anything to the working directory
|
|
(read: no patches have been applied yet).
|
|
|
|
If patches are applied, var(vcs_info) will try to find out which. If you want
|
|
to know which patches of a series are not yet applied, you need to activate
|
|
the tt(get-unapplied) style in the appropriate context.
|
|
|
|
var(vcs_info) allows for very detailed control over how the gathered
|
|
information is presented (see the below sections, tt(Styles) and tt(Hooks in
|
|
vcs_info)), all of which are documented below. Note there are a number of
|
|
other patch tracking systems that work on top of a certain version control
|
|
system (like tt(stgit) for tt(git), or tt(mq) for tt(hg)); the configuration
|
|
for systems like that are generally configured the same way as the tt(quilt)
|
|
support.
|
|
|
|
If the tt(quilt) support is working in `addon' mode, the produced string is
|
|
available as a simple format replacement (var(%Q) to be precise), which can
|
|
be used in tt(formats) and tt(actionformats); see below for details).
|
|
|
|
If, on the other hand, the support code is working in `standalone' mode,
|
|
var(vcs_info) will pretend as if tt(quilt) were an actual version control
|
|
system. That means that the version control system identifier (which
|
|
otherwise would be something like `svn' or `cvs') will be set to
|
|
`tt(-quilt-)'. This has implications on the used style context where this
|
|
identifier is the second element. var(vcs_info) will have filled in a proper
|
|
value for the "repository's" root directory and the string containing the
|
|
information about quilt's state will be available as the `misc' replacement
|
|
(and var(%Q) for compatibility with `addon' mode.
|
|
|
|
What is left to discuss is how `standalone' mode is detected. The detection
|
|
itself is a series of searches for directories. You can have this detection
|
|
enabled all the time in every directory that is not otherwise under version
|
|
control. If you know there is only a limited set of trees where you would
|
|
like var(vcs_info) to try and look for Quilt in `standalone' mode to minimise
|
|
the amount of searching on every call to var(vcs_info), there are a number of
|
|
ways to do that:
|
|
|
|
Essentially, `standalone' mode detection is controlled by a style called
|
|
`tt(quilt-standalone)'. It is a string style and its value can have different
|
|
effects. The simplest values are: `tt(always)' to run detection every time
|
|
var(vcs_info) is run, and `tt(never)' to turn the detection off entirely.
|
|
|
|
If the value of tt(quilt-standalone) is something else, it is interpreted
|
|
differently. If the value is the name of a scalar variable the value of that
|
|
variable is checked and that value is used in the same `always'/`never' way
|
|
as described above.
|
|
|
|
If the value of tt(quilt-standalone) is an array, the elements of that array
|
|
are used as directory names under which you want the detection to be active.
|
|
|
|
If tt(quilt-standalone) is an associative array, the keys are taken as
|
|
directory names under which you want the detection to be active, but only if
|
|
the corresponding value is the string `tt(true)'.
|
|
|
|
Last, but not least, if the value of tt(quilt-standalone) is the name of a
|
|
function, the function is called without arguments and the return value
|
|
decides whether detection should be active. A `0' return value is true; a
|
|
non-zero return value is interpreted as false.
|
|
|
|
Note, if there is both a function and a variable by the name of
|
|
tt(quilt-standalone), the function will take precedence.
|
|
|
|
|
|
subsect(Function Descriptions (Public API))
|
|
|
|
startitem()
|
|
findex(vcs_info)
|
|
item(tt(vcs_info) [var(user-context)])(
|
|
The main function, that runs all backends and assembles all data into
|
|
var(${vcs_info_msg_*_}). This is the function you want to call from
|
|
tt(precmd) if you want to include up-to-date information in your prompt (see
|
|
tt(Variable description) below). If an argument is given, that string will be
|
|
used instead of tt(default) in the tt(user-context) field of the style
|
|
context.
|
|
)
|
|
item(tt(vcs_info_lastmsg))(
|
|
Outputs the last var(${vcs_info_msg_*_}) value.
|
|
Takes into account the value of the tt(use-prompt-escapes) style in
|
|
var(':vcs_info:formats:command:-all-'). It also only prints tt(max-exports)
|
|
values.
|
|
)
|
|
findex(vcs_info_printsys)
|
|
item(tt(vcs_info_printsys) [var(user-context)])(
|
|
Prints a list of all
|
|
supported version control systems. Useful to find out possible contexts
|
|
(and which of them are enabled) or values for the var(disable) style.
|
|
)
|
|
item(tt(vcs_info_setsys))(
|
|
Initializes var(vcs_info)'s internal list of
|
|
available backends. With this function, you can add support for new VCSs
|
|
without restarting the shell.
|
|
)
|
|
enditem()
|
|
|
|
All functions named VCS_INFO_* are for internal use only.
|
|
|
|
subsect(Variable Description)
|
|
|
|
startitem()
|
|
item(tt(${vcs_info_msg_N_}) (Note the trailing underscore))
|
|
(
|
|
Where var(N) is an integer, e.g., var(vcs_info_msg_0_). These variables
|
|
are the storage for the informational message the last var(vcs_info) call
|
|
has assembled. These are strongly connected to the tt(formats),
|
|
tt(actionformats) and tt(nvcsformats) styles described above. Those styles
|
|
are lists. The first member of that list gets expanded into
|
|
var(${vcs_info_msg_0_}), the second into var(${vcs_info_msg_1_})
|
|
and the Nth into var(${vcs_info_msg_N-1_}). These parameters are
|
|
exported into the environment. (See the tt(max-exports) style above.)
|
|
)
|
|
enditem()
|
|
|
|
All variables named VCS_INFO_* are for internal use only.
|
|
|
|
subsect(Hooks in vcs_info)
|
|
|
|
Hooks are places in var(vcs_info) where you can run your own code. That
|
|
code can communicate with the code that called it and through that,
|
|
change the system's behaviour.
|
|
|
|
For configuration, hooks change the style context:
|
|
example(:vcs_info:<vcs-string>+<hook-name>:<user-context>:<repo-root-name>)
|
|
|
|
To register functions to a hook, you need to list them in the tt(hooks)
|
|
style in the appropriate context.
|
|
|
|
Example:
|
|
example(zstyle ':vcs_info:*+foo:*' hooks bar baz)
|
|
|
|
This registers functions to the hook `foo' for all backends. In order to
|
|
avoid namespace problems, all registered function names are prepended by
|
|
a `+vi-', so the actual functions called for the `foo' hook are
|
|
`tt(+vi-bar)' and `tt(+vi-baz)'.
|
|
|
|
If something seems weird, you can enable the `debug' boolean style in
|
|
the proper context and the hook-calling code will print what it tried
|
|
to execute and whether the function in question existed.
|
|
|
|
When you register more than one function to a hook, all functions are
|
|
executed one after another until one function returns non-zero or until
|
|
all functions have been called.
|
|
|
|
You may pass data between functions via an associative array, tt(user_data).
|
|
For example:
|
|
example(
|
|
+vi-git-myfirsthook+LPAR()RPAR(){
|
|
user_data[myval]=$myval
|
|
}
|
|
+vi-git-mysecondhook+LPAR()RPAR(){
|
|
# do something with ${user_data[myval]}
|
|
})
|
|
|
|
There are a number of variables that are special in hook contexts:
|
|
|
|
startitem()
|
|
item(tt(ret))(
|
|
The return value that the hooks system will return to the caller. The
|
|
default is an integer `zero'. If and how a changed tt(ret) value changes
|
|
the execution of the caller depends on the specific hook. See the hook
|
|
documentation below for details.
|
|
)
|
|
item(tt(hook_com))(
|
|
An associated array which is used for bidirectional communication from
|
|
the caller to hook functions. The used keys depend on the specific hook.
|
|
)
|
|
item(tt(context))(
|
|
The active context of the hook. Functions that wish to change this
|
|
variable should make it local scope first.
|
|
)
|
|
item(tt(vcs))(
|
|
The current VCS after it was detected. The same values as in the
|
|
enable/disable style are used. Available in all hooks except tt(start-up).
|
|
)
|
|
enditem()
|
|
|
|
Finally, the full list of currently available hooks:
|
|
|
|
startitem()
|
|
item(tt(start-up))(
|
|
Called after starting var(vcs_info) but before the VCS in this directory is
|
|
determined. It can be used to deactivate var(vcs_info) temporarily if
|
|
necessary. When tt(ret) is set to var(1), var(vcs_info) aborts and does
|
|
nothing; when set to var(2), var(vcs_info) sets up everything as if no
|
|
version control were active and exits.
|
|
)
|
|
item(tt(pre-get-data))(
|
|
Same as tt(start-up) but after the VCS was detected.
|
|
)
|
|
item(tt(gen-hg-bookmark-string))(
|
|
Called in the Mercurial backend when a bookmark string is generated; the
|
|
tt(get-revision) and tt(get-bookmarks) styles must be true.
|
|
|
|
This hook gets the names of the Mercurial bookmarks that
|
|
var(vcs_info) collected from `hg'.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[hg-bookmark-string]}) will be used in the var(%m) escape in
|
|
tt(formats) and tt(actionformats) and will be availabe in the global
|
|
var(backend_misc) array as tt(${backend_misc[bookmarks]}).
|
|
)
|
|
item(tt(gen-applied-string))(
|
|
Called in the tt(git) (with tt(stgit)), and tt(hg) (with tt(mq)) backends
|
|
and in tt(quilt) support when the var(applied-string) is generated; the
|
|
tt(use-quilt) zstyle must be true for tt(quilt) (the tt(mq) and tt(stgit)
|
|
backends are active by default).
|
|
|
|
This hook gets the names of all applied patches which var(vcs_info) collected
|
|
so far in the opposite order, which means that the first argument is the
|
|
top-most patch and so forth.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[applied-string]}) will be used in the var(%m) escape in
|
|
tt(formats) and tt(actionformats); it will be available in the global
|
|
var(backend_misc) array as tt($backend_misc[patches]}); and it will be
|
|
available as var(%p) in the tt(patch-format) and tt(nopatch-format) styles.
|
|
)
|
|
item(tt(gen-unapplied-string))(
|
|
Called in the tt(git) (with tt(stgit)), and tt(hg) (with tt(mq)) backend
|
|
and in tt(quilt) support when the var(unapplied-string) is generated; the
|
|
tt(get-unapplied) style must be true.
|
|
|
|
This hook gets the names of all unapplied patches which var(vcs_info)
|
|
collected so far in the opposite order, which mean that the first argument is
|
|
the patch next-in-line to be applied and so forth.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[unapplied-string]}) will be available as var(%u) in the
|
|
tt(patch-format) and tt(nopatch-format) styles.
|
|
)
|
|
item(tt(gen-mqguards-string))(
|
|
Called in the tt(hg) backend when tt(guards-string) is generated; the
|
|
tt(get-mq) style must be true (default).
|
|
|
|
This hook gets the names of any active tt(mq) guards.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[guards-string]}) will be used in the var(%g) escape in the
|
|
tt(patch-format) and tt(nopatch-format) styles.
|
|
)
|
|
item(tt(post-quilt))(
|
|
Called after the tt(quilt) support is done. The following information
|
|
is passed as arguments to the hook: 1. the quilt-support mode (`addon' or
|
|
`standalone'); 2. the directory that contains the patch series; 3. the
|
|
directory that holds quilt's status information (the `.pc' directory) or
|
|
the string tt("-nopc-") if that directory wasn't found.
|
|
|
|
The `hook_com' parameter is not used.
|
|
)
|
|
item(tt(set-branch-format))(
|
|
Called before `tt(branchformat)' is set. The only argument to the
|
|
hook is the format that is configured at this point.
|
|
|
|
The `tt(hook_com)' keys considered are `tt(branch)' and `tt(revision)'.
|
|
They are set to the values figured out so far by var(vcs_info) and any
|
|
change will be used directly when the actual replacement is done.
|
|
|
|
If tt(ret) is set to to non-zero, the string in
|
|
tt(${hook_com[branch-replace]}) will be used unchanged as the
|
|
`tt(%b)' replacement in the variables set by var(vcs_info).
|
|
)
|
|
item(tt(set-hgrev-format))(
|
|
Called before a `tt(hgrevformat)' is set. The only argument to the
|
|
hook is the format that is configured at this point.
|
|
|
|
The `tt(hook_com)' keys considered are `tt(hash)' and `tt(localrev)'.
|
|
They are set to the values figured out so far by var(vcs_info) and any
|
|
change will be used directly when the actual replacement is done.
|
|
|
|
If tt(ret) is set to to non-zero, the string in
|
|
tt(${hook_com[rev-replace]}) will be used unchanged as the
|
|
`tt(%i)' replacement in the variables set by var(vcs_info).
|
|
)
|
|
item(tt(set-message))(
|
|
Called each time before a `tt(vcs_info_msg_N_)' message is set.
|
|
It takes two arguments; the first being the `N' in the message
|
|
variable name, the second is the currently configured tt(formats) or
|
|
tt(actionformats).
|
|
|
|
There are a number of `tt(hook_com)' keys, that are used here:
|
|
`tt(action)', `tt(branch)', `tt(base)', `tt(base-name)', `tt(subdir)',
|
|
`tt(staged)', `tt(unstaged)', `tt(revision)', `tt(misc)', `tt(vcs)'
|
|
and one `tt(miscN)' entry for each backend-specific data field (tt(N)
|
|
starting at zero). They are set to the values figured out so far by
|
|
var(vcs_info) and any change will be used directly when the actual
|
|
replacement is done.
|
|
|
|
Since this hook is triggered multiple times (once for each configured
|
|
tt(formats) or tt(actionformats)), each of the `tt(hook_com)' keys mentioned
|
|
above (except for the tt(miscN) entries) has an `tt(_orig)' counterpart,
|
|
so even if you changed a value to your liking you can still get the
|
|
original value in the next run. Changing the `tt(_orig)' values is
|
|
probably not a good idea.
|
|
|
|
If tt(ret) is set to to non-zero, the string in
|
|
tt(${hook_com[message]}) will be used unchanged as the message by
|
|
var(vcs_info).
|
|
)
|
|
|
|
If all of this sounds rather confusing, take a look at the tt(Examples)
|
|
section below and also in the Misc/vcs_info-examples file in the Zsh source.
|
|
They contain some explanatory code.
|
|
|
|
subsect(Examples)
|
|
|
|
Don't use var(vcs_info) at all (even though it's in your prompt):
|
|
example(zstyle ':vcs_info:*' enable NONE)
|
|
|
|
Disable the backends for tt(bzr) and tt(svk):
|
|
example(zstyle ':vcs_info:*' disable bzr svk)
|
|
|
|
Disable everything em(but) tt(bzr) and tt(svk):
|
|
example(zstyle ':vcs_info:*' enable bzr svk)
|
|
|
|
Provide a special formats for tt(git):
|
|
example(zstyle ':vcs_info:git:*' formats ' GIT, BABY! [%b]'
|
|
zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]')
|
|
|
|
All tt(%x) expansion in all sorts of formats ("formats", "actionformats",
|
|
branchformat, you name it) are done using the `tt(zformat)' builtin from
|
|
the `tt(zsh/zutil)' module. That means you can do everything with these
|
|
tt(%x) items what zformat supports. In particular, if you want something
|
|
that is really long to have a fixed width, like a hash in a mercurial
|
|
branchformat, you can do this: tt(%12.12i). That'll shrink the 40 character
|
|
hash to its 12 leading characters. The form is actually
|
|
`tt(%)var(min)tt(.)var(max)tt(x)'. More is possible.
|
|
See ifzman(the section `The zsh/zutil Module' in zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zutil Module)) for details.
|
|
|
|
Use the quicker tt(bzr) backend
|
|
example(zstyle ':vcs_info:bzr:*' use-simple true)
|
|
|
|
If you do use tt(use-simple), please report if it does `the-right-thing[tm]'.
|
|
|
|
Display the revision number in yellow for tt(bzr) and tt(svn):
|
|
example(zstyle ':vcs_info:(svn|bzr):*' branchformat '%b%{'${fg[yellow]}'%}:%r')
|
|
|
|
If you want colors, make sure you enclose the color codes in tt(%{...%})
|
|
if you want to use the string provided by var(vcs_info) in prompts.
|
|
|
|
Here is how to print the VCS information as a command (not in a prompt):
|
|
example(alias vcsi='vcs_info command; vcs_info_lastmsg')
|
|
|
|
This way, you can even define different formats for output via
|
|
tt(vcs_info_lastmsg) in the ':vcs_info:*:command:*' namespace.
|
|
|
|
Now as promised, some code that uses hooks:
|
|
say, you'd like to replace the string `svn' by `subversion' in
|
|
var(vcs_info)'s tt(%s) tt(formats) replacement.
|
|
|
|
First, we will tell var(vcs_info) to call a function when populating
|
|
the message variables with the gathered information:
|
|
example(zstyle ':vcs_info:*+set-message:*' hooks svn2subversion)
|
|
|
|
Nothing happens. Which is reasonable, since we didn't define the actual
|
|
function yet. To see what the hooks subsystem is trying to do, enable the
|
|
`tt(debug)' style:
|
|
example(zstyle ':vcs_info:*+*:*' debug true)
|
|
|
|
That should give you an idea what is going on. Specifically, the function
|
|
that we are looking for is `tt(+vi-svn2subversion)'. Note, the `tt(+vi-)'
|
|
prefix. So, everything is in order, just as documented. When you are done
|
|
checking out the debugging output, disable it again:
|
|
example(zstyle ':vcs_info:*+*:*' debug false)
|
|
|
|
Now, let's define the function:
|
|
example(
|
|
function +vi-svn2subversion+LPAR()RPAR() {
|
|
[[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion
|
|
})
|
|
|
|
Simple enough. And it could have even been simpler, if only we had
|
|
registered our function in a less generic context. If we do it only in
|
|
the `tt(svn)' backend's context, we don't need to test which the active
|
|
backend is:
|
|
example(zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion)
|
|
example(
|
|
function +vi-svn2subversion+LPAR()RPAR() {
|
|
hook_com[vcs]=subversion
|
|
})
|
|
|
|
And finally a little more elaborate example, that uses a hook to create
|
|
a customised bookmark string for the tt(hg) backend.
|
|
|
|
Again, we start off by registering a function:
|
|
example(zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks)
|
|
|
|
And then we define the `tt(+vi-hgbookmarks) function:
|
|
example(
|
|
function +vi-hgbookmarks+LPAR()RPAR() {
|
|
# The default is to connect all bookmark names by
|
|
# commas. This mixes things up a little.
|
|
# Imagine, there's one type of bookmarks that is
|
|
# special to you. Say, because it's *your* work.
|
|
# Those bookmarks look always like this: "sh/*"
|
|
# (because your initials are sh, for example).
|
|
# This makes the bookmarks string use only those
|
|
# bookmarks. If there's more than one, it
|
|
# concatenates them using commas.
|
|
local s i
|
|
# The bookmarks returned by `hg' are available in
|
|
# the functions positional parameters.
|
|
(( $# == 0 )) && return 0
|
|
for i in "$@"; do
|
|
if [[ $i == sh/* ]]; then
|
|
[[ -n $s ]] && s=$s,
|
|
s=${s}$i
|
|
fi
|
|
done
|
|
# Now, the communication with the code that calls
|
|
# the hook functions is done via the hook_com[]
|
|
# hash. The key, at which the `gen-hg-bookmark-string'
|
|
# hook looks at is `hg-bookmark-string'. So:
|
|
hook_com[hg-bookmark-string]=$s
|
|
# And to signal, that we want to use the sting we
|
|
# just generated, set the special variable `ret' to
|
|
# something other than the default zero:
|
|
ret=1
|
|
return 0
|
|
}
|
|
)
|
|
|
|
Some longer examples and code snippets which might be useful are available in
|
|
the examples file located at Misc/vcs_info-examples in the Zsh source
|
|
directory.
|
|
|
|
This concludes our guided tour through zsh's var(vcs_info).
|
|
|
|
|
|
texinode(Prompt Themes)(ZLE Functions)(Version Control Information)(User Contributions)
|
|
sect(Prompt Themes)
|
|
|
|
subsect(Installation)
|
|
|
|
You should make sure all the functions from the tt(Functions/Prompts)
|
|
directory of the source distribution are available; they all begin with
|
|
the string `tt(prompt_)' except for the special function`tt(promptinit)'.
|
|
You also need the `tt(colors)' function from tt(Functions/Misc). All of
|
|
these functions may already have been installed on your system; if not,
|
|
you will need to find them and copy them. The directory should appear as
|
|
one of the elements of the tt(fpath) array (this should already be the
|
|
case if they were installed), and at least the function tt(promptinit)
|
|
should be autoloaded; it will autoload the rest. Finally, to initialize
|
|
the use of the system you need to call the tt(promptinit) function. The
|
|
following code in your tt(.zshrc) will arrange for this; assume the
|
|
functions are stored in the directory tt(~/myfns):
|
|
|
|
example(fpath=(~/myfns $fpath)
|
|
autoload -U promptinit
|
|
promptinit)
|
|
|
|
subsect(Theme Selection)
|
|
|
|
Use the tt(prompt) command to select your preferred theme. This command
|
|
may be added to your tt(.zshrc) following the call to tt(promptinit) in
|
|
order to start zsh with a theme already selected.
|
|
|
|
startitem()
|
|
xitem(tt(prompt) [ tt(-c) | tt(-l) ])
|
|
xitem(tt(prompt) [ tt(-p) | tt(-h) ] [ var(theme) ... ])
|
|
item(tt(prompt) [ tt(-s) ] var(theme) [ var(arg) ... ])(
|
|
Set or examine the prompt theme. With no options and a var(theme)
|
|
argument, the theme with that name is set as the current theme. The
|
|
available themes are determined at run time; use the tt(-l) option to see
|
|
a list. The special var(theme) `tt(random)' selects at random one of the
|
|
available themes and sets your prompt to that.
|
|
|
|
In some cases the var(theme) may be modified by one or more arguments,
|
|
which should be given after the theme name. See the help for each theme
|
|
for descriptions of these arguments.
|
|
|
|
Options are:
|
|
|
|
startsitem()
|
|
sitem(tt(-c))(Show the currently selected theme and its parameters, if any.)
|
|
sitem(tt(-l))(List all available prompt themes.)
|
|
sitem(tt(-p))(Preview the theme named by var(theme), or all themes if no
|
|
var(theme) is given.)
|
|
sitem(tt(-h))(Show help for the theme named by var(theme), or for the
|
|
tt(prompt) function if no var(theme) is given.)
|
|
sitem(tt(-s))(Set var(theme) as the current theme and save state.)
|
|
endsitem()
|
|
)
|
|
item(tt(prompt_)var(theme)tt(_setup))(
|
|
Each available var(theme) has a setup function which is called by the
|
|
tt(prompt) function to install that theme. This function may define
|
|
other functions as necessary to maintain the prompt, including functions
|
|
used to preview the prompt or provide help for its use. You should not
|
|
normally call a theme's setup function directly.
|
|
)
|
|
enditem()
|
|
|
|
texinode(ZLE Functions)(Exception Handling)(Prompt Themes)(User Contributions)
|
|
sect(ZLE Functions)
|
|
|
|
subsect(Widgets)
|
|
|
|
These functions all implement user-defined ZLE widgets (see
|
|
ifzman(zmanref(zshzle))\
|
|
ifnzman(noderef(Zsh Line Editor))\
|
|
) which can be bound to keystrokes in interactive shells. To use them,
|
|
your tt(.zshrc) should contain lines of the form
|
|
|
|
example(autoload var(function)
|
|
zle -N var(function))
|
|
|
|
followed by an appropriate tt(bindkey) command to associate the function
|
|
with a key sequence. Suggested bindings are described below.
|
|
|
|
startitem()
|
|
item(bash-style word functions)(
|
|
If you are looking for functions to implement moving over and editing
|
|
words in the manner of bash, where only alphanumeric characters are
|
|
considered word characters, you can use the functions described in
|
|
the next section. The following is sufficient:
|
|
|
|
example(autoload -U select-word-style
|
|
select-word-style bash)
|
|
|
|
)
|
|
tindex(forward-word-match)
|
|
tindex(backward-word-match)
|
|
tindex(kill-word-match)
|
|
tindex(backward-kill-word-match)
|
|
tindex(transpose-words-match)
|
|
tindex(capitalize-word-match)
|
|
tindex(up-case-word-match)
|
|
tindex(down-case-word-match)
|
|
tindex(select-word-style)
|
|
tindex(match-word-context)
|
|
tindex(match-words-by-style)
|
|
xitem(tt(forward-word-match), tt(backward-word-match))
|
|
xitem(tt(kill-word-match), tt(backward-kill-word-match))
|
|
xitem(tt(transpose-words-match), tt(capitalize-word-match))
|
|
xitem(tt(up-case-word-match), tt(down-case-word-match))
|
|
item(tt(select-word-style), tt(match-word-context), tt(match-words-by-style))(
|
|
The eight `tt(-match)' functions are drop-in replacements for the
|
|
builtin widgets without the suffix. By default they behave in a similar
|
|
way. However, by the use of styles and the function tt(select-word-style),
|
|
the way words are matched can be altered.
|
|
|
|
The simplest way of configuring the functions is to use
|
|
tt(select-word-style), which can either be called as a normal function with
|
|
the appropriate argument, or invoked as a user-defined widget that will
|
|
prompt for the first character of the word style to be used. The first
|
|
time it is invoked, the eight tt(-match) functions will automatically
|
|
replace the builtin versions, so they do not need to be loaded explicitly.
|
|
|
|
The word styles available are as follows. Only the first character
|
|
is examined.
|
|
|
|
startitem()
|
|
item(tt(bash))(
|
|
Word characters are alphanumeric characters only.
|
|
)
|
|
item(tt(normal))(
|
|
As in normal shell operation: word characters are alphanumeric characters
|
|
plus any characters present in the string given by the parameter
|
|
tt($WORDCHARS).
|
|
)
|
|
item(tt(shell))(
|
|
Words are complete shell command arguments, possibly including complete
|
|
quoted strings, or any tokens special to the shell.
|
|
)
|
|
item(tt(whitespace))(
|
|
Words are any set of characters delimited by whitespace.
|
|
)
|
|
item(tt(default))(
|
|
Restore the default settings; this is usually the same as `tt(normal)'.
|
|
)
|
|
enditem()
|
|
|
|
All but `tt(default)' can be input as an upper case character, which has
|
|
the same effect but with subword matching turned on. In this case, words
|
|
with upper case characters are treated specially: each separate run of
|
|
upper case characters, or an upper case character followed by any number of
|
|
other characters, is considered a word. The style tt(subword-range)
|
|
can supply an alternative character range to the default `tt([:upper:])';
|
|
the value of the style is treated as the contents of a `tt([)var(...)tt(])'
|
|
pattern (note that the outer brackets should not be supplied, only
|
|
those surrounding named ranges).
|
|
|
|
More control can be obtained using the tt(zstyle) command, as described in
|
|
ifzman(zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zutil Module)). Each style is looked up in the
|
|
context tt(:zle:)var(widget) where var(widget) is the name of the
|
|
user-defined widget, not the name of the function implementing it, so in
|
|
the case of the definitions supplied by tt(select-word-style) the
|
|
appropriate contexts are tt(:zle:forward-word), and so on. The function
|
|
tt(select-word-style) itself always defines styles for the context
|
|
`tt(:zle:*)' which can be overridden by more specific (longer) patterns as
|
|
well as explicit contexts.
|
|
|
|
The style tt(word-style) specifies the rules to use. This may have the
|
|
following values.
|
|
|
|
startitem()
|
|
item(tt(normal))(
|
|
Use the standard shell rules, i.e. alphanumerics and tt($WORDCHARS), unless
|
|
overridden by the styles tt(word-chars) or tt(word-class).
|
|
)
|
|
item(tt(specified))(
|
|
Similar to tt(normal), but em(only) the specified characters, and not also
|
|
alphanumerics, are considered word characters.
|
|
)
|
|
item(tt(unspecified))(
|
|
The negation of specified. The given characters are those which will
|
|
em(not) be considered part of a word.
|
|
)
|
|
item(tt(shell))(
|
|
Words are obtained by using the syntactic rules for generating shell
|
|
command arguments. In addition, special tokens which are never command
|
|
arguments such as `tt(())' are also treated as words.
|
|
)
|
|
item(tt(whitespace))(
|
|
Words are whitespace-delimited strings of characters.
|
|
)
|
|
enditem()
|
|
|
|
The first three of those rules usually use tt($WORDCHARS), but the value
|
|
in the parameter can be overridden by the style tt(word-chars), which works
|
|
in exactly the same way as tt($WORDCHARS). In addition, the style
|
|
tt(word-class) uses character class syntax to group characters and takes
|
|
precedence over tt(word-chars) if both are set. The tt(word-class) style
|
|
does not include the surrounding brackets of the character class; for
|
|
example, `tt(-:[:alnum:])' is a valid tt(word-class) to include all
|
|
alphanumerics plus the characters `tt(-)' and `tt(:)'. Be careful
|
|
including `tt(])', `tt(^)' and `tt(-)' as these are special inside
|
|
character classes.
|
|
|
|
tt(word-style) may also have `tt(-subword)' appended to its value to
|
|
turn on subword matching, as described above.
|
|
|
|
The style tt(skip-chars) is mostly useful for
|
|
tt(transpose-words) and similar functions. If set, it gives a count of
|
|
characters starting at the cursor position which will not be considered
|
|
part of the word and are treated as space, regardless of what they actually
|
|
are. For example, if
|
|
|
|
example(zstyle ':zle:transpose-words' skip-chars 1)
|
|
|
|
has been set, and tt(transpose-words-match) is called with the cursor on
|
|
the var(X) of tt(foo)var(X)tt(bar), where var(X) can be any character, then
|
|
the resulting expression is tt(bar)var(X)tt(foo).
|
|
|
|
Finer grained control can be obtained by setting the style tt(word-context)
|
|
to an array of pairs of entries. Each pair of entries consists of a
|
|
var(pattern) and a var(subcontext). The shell argument the cursor is on is
|
|
matched against each var(pattern) in turn until one matches; if it does,
|
|
the context is extended by a colon and the corresponding var(subcontext).
|
|
Note that the test is made against the original word on the line, with no
|
|
stripping of quotes. Special handling is done between words: the current
|
|
context is examined and if it contains the string tt(back), the word before
|
|
the cursor is considered, else the word after cursor is considered. Some
|
|
examples are given below.
|
|
|
|
Here are some examples of use of the styles, actually taken from the
|
|
simplified interface in tt(select-word-style):
|
|
|
|
example(zstyle ':zle:*' word-style standard
|
|
zstyle ':zle:*' word-chars '')
|
|
|
|
Implements bash-style word handling for all widgets, i.e. only
|
|
alphanumerics are word characters; equivalent to setting
|
|
the parameter tt(WORDCHARS) empty for the given context.
|
|
|
|
example(style ':zle:*kill*' word-style space)
|
|
|
|
Uses space-delimited words for widgets with the word `kill' in the name.
|
|
Neither of the styles tt(word-chars) nor tt(word-class) is used in this case.
|
|
|
|
Here are some examples of use of the tt(word-context) style to extend
|
|
the context.
|
|
|
|
example(zstyle ':zle:*' word-context "*/*" file "[[:space:]]" whitespace
|
|
zstyle ':zle:transpose-words:whitespace' word-style shell
|
|
zstyle ':zle:transpose-words:filename' word-style normal
|
|
zstyle ':zle:transpose-words:filename' word-chars '')
|
|
|
|
This provides two different ways of using tt(transpose-words) depending on
|
|
whether the cursor is on whitespace between words or on a filename, here
|
|
any word containing a tt(/). On whitespace, complete arguments as defined
|
|
by standard shell rules will be transposed. In a filename, only
|
|
alphanumerics will be transposed. Elsewhere, words will be transposed
|
|
using the default style for tt(:zle:transpose-words).
|
|
|
|
The word matching and all the handling of tt(zstyle) settings is actually
|
|
implemented by the function tt(match-words-by-style). This can be used to
|
|
create new user-defined widgets. The calling function should set the local
|
|
parameter tt(curcontext) to tt(:zle:)var(widget), create the local
|
|
parameter tt(matched_words) and call tt(match-words-by-style) with no
|
|
arguments. On return, tt(matched_words) will be set to an array with the
|
|
elements: (1) the start of the line (2) the word before the cursor (3) any
|
|
non-word characters between that word and the cursor (4) any non-word
|
|
character at the cursor position plus any remaining non-word characters
|
|
before the next word, including all characters specified by the
|
|
tt(skip-chars) style, (5) the word at or following the cursor (6) any
|
|
non-word characters following that word (7) the remainder of the line. Any
|
|
of the elements may be an empty string; the calling function should test
|
|
for this to decide whether it can perform its function.
|
|
|
|
It is possible to pass options with arguments to tt(match-words-by-style)
|
|
to override the use of styles. The options are:
|
|
startsitem()
|
|
sitem(tt(-w))(var(word-style))
|
|
sitem(tt(-s))(var(skip-chars))
|
|
sitem(tt(-c))(var(word-class))
|
|
sitem(tt(-C))(var(word-chars))
|
|
sitem(tt(-r))(var(subword-range))
|
|
endsitem()
|
|
|
|
For example, tt(match-words-by-style -w shell -c 0) may be used to
|
|
extract the command argument around the cursor.
|
|
|
|
The tt(word-context) style is implemented by the function
|
|
tt(match-word-context). This should not usually need to be called
|
|
directly.
|
|
)
|
|
tindex(delete-whole-word-match)
|
|
item(tt(delete-whole-word-match))(
|
|
This is another function which works like the tt(-match) functions
|
|
described immediately above, i.e. using styles to decide the word
|
|
boundaries. However, it is not a replacement for any existing function.
|
|
|
|
The basic behaviour is to delete the word around the cursor. There is no
|
|
numeric prefix handling; only the single word around the cursor is
|
|
considered. If the widget contains the string tt(kill), the removed text
|
|
will be placed in the cutbuffer for future yanking. This can be obtained
|
|
by defining tt(kill-whole-word-match) as follows:
|
|
|
|
example(zle -N kill-whole-word-match delete-whole-word-match)
|
|
|
|
and then binding the widget tt(kill-whole-word-match).
|
|
)
|
|
tindex(copy-earlier-word)
|
|
item(tt(copy-earlier-word))(
|
|
This widget works like a combination of tt(insert-last-word) and
|
|
tt(copy-prev-shell-word). Repeated invocations of the widget retrieve
|
|
earlier words on the relevant history line. With a numeric argument
|
|
var(N), insert the var(N)th word from the history line; var(N) may be
|
|
negative to count from the end of the line.
|
|
|
|
If tt(insert-last-word) has been used to retrieve the last word on a
|
|
previous history line, repeated invocations will replace that word with
|
|
earlier words from the same line.
|
|
|
|
Otherwise, the widget applies to words on the line currently being edited.
|
|
The tt(widget) style can be set to the name of another widget that should
|
|
be called to retrieve words. This widget must accept the same three
|
|
arguments as tt(insert-last-word).
|
|
)
|
|
tindex(cycle-completion-positions)
|
|
item(tt(cycle-completion-positions))(
|
|
After inserting an unambiguous string into the command line, the new
|
|
function based completion system may know about multiple places in
|
|
this string where characters are missing or differ from at least one
|
|
of the possible matches. It will then place the cursor on the
|
|
position it considers to be the most interesting one, i.e. the one
|
|
where one can disambiguate between as many matches as possible with as
|
|
little typing as possible.
|
|
|
|
This widget allows the cursor to be easily moved to the other interesting
|
|
spots. It can be invoked repeatedly to cycle between all positions
|
|
reported by the completion system.
|
|
)
|
|
tindex(edit-command-line)
|
|
item(tt(edit-command-line))(
|
|
Edit the command line using your visual editor, as in tt(ksh).
|
|
|
|
example(bindkey -M vicmd v edit-command-line)
|
|
)
|
|
tindex(history-beginning-search-backward-end)
|
|
tindex(history-beginning-search-forward-end)
|
|
item(tt(history-search-end))(
|
|
This function implements the widgets
|
|
tt(history-beginning-search-backward-end) and
|
|
tt(history-beginning-search-forward-end). These commands work by first
|
|
calling the corresponding builtin widget (see
|
|
ifzman(`History Control' in zmanref(zshzle))\
|
|
ifnzman(noderef(History Control))\
|
|
) and then moving the cursor to the end of the line. The original cursor
|
|
position is remembered and restored before calling the builtin widget a
|
|
second time, so that the same search is repeated to look farther through
|
|
the history.
|
|
|
|
Although you tt(autoload) only one function, the commands to use it are
|
|
slightly different because it implements two widgets.
|
|
|
|
example(zle -N history-beginning-search-backward-end \
|
|
history-search-end
|
|
zle -N history-beginning-search-forward-end \
|
|
history-search-end
|
|
bindkey '\e^P' history-beginning-search-backward-end
|
|
bindkey '\e^N' history-beginning-search-forward-end)
|
|
)
|
|
tindex(history-beginning-search-menu)
|
|
item(tt(history-beginning-search-menu))(
|
|
This function implements yet another form of history searching. The
|
|
text before the cursor is used to select lines from the history,
|
|
as for tt(history-beginning-search-backward) except that all matches are
|
|
shown in a numbered menu. Typing the appropriate digits inserts the
|
|
full history line. Note that leading zeroes must be typed (they are only
|
|
shown when necessary for removing ambiguity). The entire history is
|
|
searched; there is no distinction between forwards and backwards.
|
|
|
|
With a prefix argument, the search is not anchored to the start of
|
|
the line; the string typed by the use may appear anywhere in the line
|
|
in the history.
|
|
|
|
If the widget name contains `tt(-end)' the cursor is moved to the end of
|
|
the line inserted. If the widget name contains `tt(-space)' any space
|
|
in the text typed is treated as a wildcard and can match anything (hence
|
|
a leading space is equivalent to giving a prefix argument). Both
|
|
forms can be combined, for example:
|
|
|
|
example(zle -N history-beginning-search-menu-space-end \
|
|
history-beginning-search-menu)
|
|
)
|
|
tindex(history-pattern-search)
|
|
tindex(history-pattern-search-backward)
|
|
tindex(history-pattern-search-forward)
|
|
item(tt(history-pattern-search))(
|
|
The function tt(history-pattern-search) implements widgets which prompt
|
|
for a pattern with which to search the history backwards or forwards. The
|
|
pattern is in the usual zsh format, however the first character may be
|
|
tt(^) to anchor the search to the start of the line, and the last character
|
|
may be tt($) to anchor the search to the end of the line. If the
|
|
search was not anchored to the end of the line the cursor is positioned
|
|
just after the pattern found.
|
|
|
|
The commands to create bindable widgets are similar to those in the
|
|
example immediately above:
|
|
|
|
example(autoload -U history-pattern-search
|
|
zle -N history-pattern-search-backward history-pattern-search
|
|
zle -N history-pattern-search-forward history-pattern-search)
|
|
)
|
|
tindex(up-line-or-beginning-search)
|
|
tindex(down-line-or-beginning-search)
|
|
item(tt(up-line-or-beginning-search), tt(down-line-or-beginning-search))(
|
|
These widgets are similar to the builtin functions tt(up-line-or-search)
|
|
and tt(down-line-or-search): if in a multiline buffer they move up or
|
|
down within the buffer, otherwise they search for a history line matching
|
|
the start of the current line. In this case, however, they search for
|
|
a line which matches the current line up to the current cursor position, in
|
|
the manner of tt(history-beginning-search-backward) and tt(-forward), rather
|
|
than the first word on the line.
|
|
)
|
|
tindex(incarg)
|
|
vindex(incarg, use of)
|
|
item(tt(incarg))(
|
|
Typing the keystrokes for this widget with the cursor placed on or to the
|
|
left of an integer causes that integer to be incremented by one. With a
|
|
numeric prefix argument, the number is incremented by the amount of the
|
|
argument (decremented if the prefix argument is negative). The shell
|
|
parameter tt(incarg) may be set to change the default increment to
|
|
something other than one.
|
|
|
|
example(bindkey '^X+' incarg)
|
|
)
|
|
tindex(incremental-complete-word)
|
|
item(tt(incremental-complete-word))(
|
|
This allows incremental completion of a word. After starting this
|
|
command, a list of completion choices can be shown after every character
|
|
you type, which you can delete with tt(^H) or tt(DEL). Pressing return
|
|
accepts the completion so far and returns you to normal editing (that is,
|
|
the command line is em(not) immediately executed). You can hit tt(TAB) to
|
|
do normal completion, tt(^G) to abort back to the state when you started,
|
|
and tt(^D) to list the matches.
|
|
|
|
This works only with the new function based completion system.
|
|
|
|
example(bindkey '^Xi' incremental-complete-word)
|
|
)
|
|
tindex(insert-composed-char)
|
|
item(tt(insert-composed-char))(
|
|
This function allows you to compose characters that don't appear on the
|
|
keyboard to be inserted into the command line. The command is followed by
|
|
two keys corresponding to ASCII characters (there is no prompt). For
|
|
accented characters, the two keys are a base character followed by a code
|
|
for the accent, while for other special characters the two characters
|
|
together form a mnemonic for the character to be inserted. The
|
|
two-character codes are a subset of those given by RFC 1345 (see for
|
|
example tt(http://www.faqs.org/rfcs/rfc1345.html)).
|
|
|
|
The function may optionally be followed by up to two characters which
|
|
replace one or both of the characters read from the keyboard; if both
|
|
characters are supplied, no input is read. For example,
|
|
tt(insert-composed-char a:) can be used within a widget to insert an a with
|
|
umlaut into the command line. This has the advantages over use of a
|
|
literal character that it is more portable.
|
|
|
|
For best results zsh should have been built with support for multibyte
|
|
characters (configured with tt(--enable-multibyte)); however, the function
|
|
works for the limited range of characters available in single-byte
|
|
character sets such as ISO-8859-1.
|
|
|
|
The character is converted into the local representation and
|
|
inserted into the command line at the cursor position.
|
|
(The conversion is done within the shell, using whatever facilities
|
|
the C library provides.) With a numeric argument, the character and its
|
|
code are previewed in the status line
|
|
|
|
The function may be run outside zle in which case it prints the character
|
|
(together with a newline) to standard output. Input is still read from
|
|
keystrokes.
|
|
|
|
See tt(insert-unicode-char) for an alternative way of inserting Unicode
|
|
characters using their hexadecimal character number.
|
|
|
|
The set of accented characters is reasonably complete up to Unicode
|
|
character U+0180, the set of special characters less so. However, it it
|
|
is very sporadic from that point. Adding new characters is easy,
|
|
however; see the function tt(define-composed-chars). Please send any
|
|
additions to tt(zsh-workers@zsh.org).
|
|
|
|
The codes for the second character when used to accent the first are as
|
|
follows. Note that not every character can take every accent.
|
|
startsitem()
|
|
sitem(tt(!))(Grave.)
|
|
sitem(tt(RQUOTE()))(Acute.)
|
|
sitem(tt(>))(Circumflex.)
|
|
sitem(tt(?))(Tilde. (This is not tt(~) as RFC 1345 does not assume that
|
|
character is present on the keyboard.))
|
|
sitem(tt(-))(Macron. (A horizontal bar over the base character.))
|
|
sitem(tt(LPAR()))(Breve. (A shallow dish shape over the base character.))
|
|
sitem(tt(.))(Dot above the base character, or in the case of tt(i) no dot,
|
|
or in the case of tt(L) and tt(l) a centered dot.)
|
|
sitem(tt(:))(Diaeresis (Umlaut).)
|
|
sitem(tt(c))(Cedilla.)
|
|
sitem(tt(_))(Underline, however there are currently no underlined characters.)
|
|
sitem(tt(/))(Stroke through the base character.)
|
|
sitem(tt("))(Double acute (only supported on a few letters).)
|
|
sitem(tt(;))(Ogonek. (A little forward facing hook at the bottom right
|
|
of the character.))
|
|
sitem(tt(<))(Caron. (A little v over the letter.))
|
|
sitem(tt(0))(Circle over the base character.)
|
|
sitem(tt(2))(Hook over the base character.)
|
|
sitem(tt(9))(Horn over the base character.)
|
|
endsitem()
|
|
|
|
The most common characters from the Arabic, Cyrillic, Greek and Hebrew
|
|
alphabets are available; consult RFC 1345 for the appropriate sequences.
|
|
In addition, a set of two letter codes not in RFC 1345 are available for
|
|
the double-width characters corresponding to ASCII characters from tt(!)
|
|
to tt(~) (0x21 to 0x7e) by preceding the character with tt(^), for
|
|
example tt(^A) for a double-width tt(A).
|
|
|
|
The following other two-character sequences are understood.
|
|
|
|
startitem()
|
|
item(ASCII characters)(
|
|
These are already present on most keyboards:
|
|
startsitem()
|
|
sitem(tt(<LPAR()))(Left square bracket)
|
|
sitem(tt(//))(Backslash (solidus))
|
|
sitem(tt(RPAR()>))(Right square bracket)
|
|
sitem(tt(LPAR()!))(Left brace (curly bracket))
|
|
sitem(tt(!!))(Vertical bar (pipe symbol))
|
|
sitem(tt(!RPAR()))(Right brace (curly bracket))
|
|
sitem(tt(RQUOTE()?))(Tilde)
|
|
endsitem()
|
|
)
|
|
item(Special letters)(
|
|
Characters found in various variants of the Latin alphabet:
|
|
startsitem()
|
|
sitem(tt(ss))(Eszett (scafes S))
|
|
sitem(tt(D-), tt(d-))(Eth)
|
|
sitem(tt(TH), tt(th))(Thorn)
|
|
sitem(tt(kk))(Kra)
|
|
sitem(tt(RQUOTE()n))(RQUOTE()n)
|
|
sitem(tt(NG), tt(ng))(Ng)
|
|
sitem(tt(OI), tt(oi))(Oi)
|
|
sitem(tt(yr))(yr)
|
|
sitem(tt(ED))(ezh)
|
|
endsitem()
|
|
)
|
|
item(Currency symbols)(
|
|
startsitem()
|
|
sitem(tt(Ct))(Cent)
|
|
sitem(tt(Pd))(Pound sterling (also lira and others))
|
|
sitem(tt(Cu))(Currency)
|
|
sitem(tt(Ye))(Yen)
|
|
sitem(tt(Eu))(Euro (N.B. not in RFC 1345))
|
|
endsitem()
|
|
)
|
|
item(Punctuation characters)(
|
|
References to "right" quotes indicate the shape (like a 9 rather than 6)
|
|
rather than their grammatical use. (For example, a "right" low double
|
|
quote is used to open quotations in German.)
|
|
startsitem()
|
|
sitem(tt(!I))(Inverted exclamation mark)
|
|
sitem(tt(BB))(Broken vertical bar)
|
|
sitem(tt(SE))(Section)
|
|
sitem(tt(Co))(Copyright)
|
|
sitem(tt(-a))(Spanish feminine ordinal indicator)
|
|
sitem(tt(<<))(Left guillemet)
|
|
sitem(tt(-)tt(-))(Soft hyphen)
|
|
sitem(tt(Rg))(Registered trade mark)
|
|
sitem(tt(PI))(Pilcrow (paragraph))
|
|
sitem(tt(-o))(Spanish masculine ordinal indicator)
|
|
sitem(tt(>>))(Right guillemet)
|
|
sitem(tt(?I))(Inverted question mark)
|
|
sitem(tt(-1))(Hyphen)
|
|
sitem(tt(-N))(En dash)
|
|
sitem(tt(-M))(Em dash)
|
|
sitem(tt(-3))(Horizontal bar)
|
|
sitem(tt(:3))(Vertical ellipsis)
|
|
sitem(tt(.3))(Horizontal midline ellipsis)
|
|
sitem(tt(!2))(Double vertical line)
|
|
sitem(tt(=2))(Double low line)
|
|
sitem(tt(RQUOTE()6))(Left single quote)
|
|
sitem(tt(RQUOTE()9))(Right single quote)
|
|
sitem(tt(.9))("Right" low quote)
|
|
sitem(tt(9+RQUOTE()))(Reversed "right" quote)
|
|
sitem(tt("6))(Left double quote)
|
|
sitem(tt("9))(Right double quote)
|
|
sitem(tt(:9))("Right" low double quote)
|
|
sitem(tt(9"))(Reversed "right" double quote)
|
|
sitem(tt(/-))(Dagger)
|
|
sitem(tt(/=))(Double dagger)
|
|
endsitem()
|
|
)
|
|
item(Mathematical symbols)(
|
|
startsitem()
|
|
sitem(tt(DG))(Degree)
|
|
sitem(tt(-2), tt(+-), tt(-+))(- sign, +/- sign, -/+ sign)
|
|
sitem(tt(2S))(Superscript 2)
|
|
sitem(tt(3S))(Superscript 3)
|
|
sitem(tt(1S))(Superscript 1)
|
|
sitem(tt(My))(Micro)
|
|
sitem(tt(.M))(Middle dot)
|
|
sitem(tt(14))(Quarter)
|
|
sitem(tt(12))(Half)
|
|
sitem(tt(34))(Three quarters)
|
|
sitem(tt(*X))(Multiplication)
|
|
sitem(tt(-:))(Division)
|
|
sitem(tt(%0))(Per mille)
|
|
sitem(tt(FA), tt(TE), tt(/0))(For all, there exists, empty set)
|
|
sitem(tt(dP), tt(DE), tt(NB))(Partial derivative, delta (increment), del
|
|
(nabla))
|
|
sitem(tt(LPAR()-), tt(-RPAR()))(Element of, contains)
|
|
sitem(tt(*P), tt(+Z))(Product, sum)
|
|
sitem(tt(*-), tt(Ob), tt(Sb))(Asterisk, ring, bullet)
|
|
sitem(tt(RT), tt(0+LPAR()), tt(00))(Root sign, proportional to, infinity)
|
|
endsitem()
|
|
)
|
|
item(Other symbols)(
|
|
startsitem()
|
|
sitem(tt(cS), tt(cH), tt(cD), tt(cC))(Card suits: spades, hearts, diamonds,
|
|
clubs)
|
|
sitem(tt(Md), tt(M8), tt(M2), tt(Mb), tt(Mx), tt(MX))(Musical notation:
|
|
crotchet (quarter note), quaver (eighth note), semiquavers (sixteenth
|
|
notes), flag sign, natural sign, sharp sign)
|
|
sitem(tt(Fm), tt(Ml))(Female, male)
|
|
endsitem()
|
|
)
|
|
item(Accents on their own)(
|
|
startsitem()
|
|
sitem(tt(RQUOTE()>))(Circumflex (same as caret, tt(^)))
|
|
sitem(tt(RQUOTE()!))(Grave (same as backtick, tt(`)))
|
|
sitem(tt(RQUOTE(),))(Cedilla)
|
|
sitem(tt(RQUOTE():))(Diaeresis (Umlaut))
|
|
sitem(tt(RQUOTE()m))(Macron)
|
|
sitem(tt(RQUOTE()RQUOTE()))(Acute)
|
|
endsitem()
|
|
)
|
|
enditem()
|
|
)
|
|
tindex(insert-files)
|
|
item(tt(insert-files))(
|
|
This function allows you type a file pattern, and see the results of the
|
|
expansion at each step. When you hit return, all expansions are inserted
|
|
into the command line.
|
|
|
|
example(bindkey '^Xf' insert-files)
|
|
)
|
|
tindex(narrow-to-region)
|
|
tindex(narrow-to-region-invisible)
|
|
xitem(tt(narrow-to-region [ -p) var(pre) tt(] [ -P) var(post) tt(]))
|
|
xitem( tt([ -S) var(statepm) tt(| -R) var(statepm) tt(] [ -n ] [) var(start) var(end) tt(])))
|
|
item(tt(narrow-to-region-invisible))(
|
|
Narrow the editable portion of the buffer to the region between the cursor
|
|
and the mark, which may be in either order. The region may not be empty.
|
|
|
|
tt(narrow-to-region) may be used as a widget or called as a function from a
|
|
user-defined widget; by default, the text outside the editable area remains
|
|
visible. A tt(recursive-edit) is performed and the original widening
|
|
status is then restored. Various options and arguments are available when
|
|
it is called as a function.
|
|
|
|
The options tt(-p) var(pretext) and tt(-P) var(posttext) may be
|
|
used to replace the text before and after the display for the duration of
|
|
the function; either or both may be an empty string.
|
|
|
|
If the option tt(-n) is also given, var(pretext) or var(posttext) will only
|
|
be inserted if there is text before or after the region respectively which
|
|
will be made invisible.
|
|
|
|
Two numeric arguments may be given which will be used instead of the cursor
|
|
and mark positions.
|
|
|
|
The option tt(-S) var(statepm) is used to narrow according to the other
|
|
options while saving the original state in the parameter with name
|
|
var(statepm), while the option tt(-R) var(statepm) is used to restore the
|
|
state from the parameter; note in both cases the em(name) of the parameter
|
|
is required. In the second case, other options and arguments are
|
|
irrelevant. When this method is used, no tt(recursive-edit) is performed;
|
|
the calling widget should call this function with the option tt(-S),
|
|
perform its own editing on the command line or pass control to the user
|
|
via `tt(zle recursive-edit)', then call this function with the option
|
|
tt(-R). The argument var(statepm) must be a suitable name for an ordinary
|
|
parameter, except that parameters beginning with the prefix tt(_ntr_) are
|
|
reserved for use within tt(narrow-to-region). Typically the parameter will
|
|
be local to the calling function.
|
|
|
|
tt(narrow-to-region-invisible) is a simple widget which calls
|
|
tt(narrow-to-region) with arguments which replace any text outside the
|
|
region with `tt(...)'.
|
|
|
|
The display is restored (and the widget returns) upon any zle command
|
|
which would usually cause the line to be accepted or aborted. Hence an
|
|
additional such command is required to accept or abort the current line.
|
|
|
|
The return status of both widgets is zero if the line was accepted, else
|
|
non-zero.
|
|
|
|
Here is a trivial example of a widget using this feature.
|
|
example(local state
|
|
narrow-to-region -p $'Editing restricted region\n' \
|
|
-P '' -S state
|
|
zle recursive-edit
|
|
narrow-to-region -R state)
|
|
)
|
|
tindex(insert-unicode-char)
|
|
item(tt(insert-unicode-char))(
|
|
When first executed, the user inputs a set of hexadecimal digits.
|
|
This is terminated with another call to tt(insert-unicode-char).
|
|
The digits are then turned into the corresponding Unicode character.
|
|
For example, if the widget is bound to tt(^XU), the character sequence
|
|
`tt(^XU 4 c ^XU)' inserts tt(L) (Unicode U+004c).
|
|
|
|
See tt(insert-composed-char) for a way of inserting characters
|
|
using a two-character mnemonic.
|
|
)
|
|
tindex(predict-on)
|
|
tindex(predict-off)
|
|
item(tt(predict-on))(
|
|
This set of functions implements predictive typing using history search.
|
|
After tt(predict-on), typing characters causes the editor to look backward
|
|
in the history for the first line beginning with what you have typed so
|
|
far. After tt(predict-off), editing returns to normal for the line found.
|
|
In fact, you often don't even need to use tt(predict-off), because if the
|
|
line doesn't match something in the history, adding a key performs
|
|
standard completion, and then inserts itself if no completions were found.
|
|
However, editing in the middle of a line is liable to confuse prediction;
|
|
see the tt(toggle) style below.
|
|
|
|
With the function based completion system (which is needed for this), you
|
|
should be able to type tt(TAB) at almost any point to advance the cursor
|
|
to the next ``interesting'' character position (usually the end of the
|
|
current word, but sometimes somewhere in the middle of the word). And of
|
|
course as soon as the entire line is what you want, you can accept with
|
|
return, without needing to move the cursor to the end first.
|
|
|
|
The first time tt(predict-on) is used, it creates several additional
|
|
widget functions:
|
|
|
|
startsitem()
|
|
sitem(tt(delete-backward-and-predict))(Replaces the tt(backward-delete-char)
|
|
widget. You do not need to bind this yourself.)
|
|
sitem(tt(insert-and-predict))(Implements predictive typing by replacing the
|
|
tt(self-insert) widget. You do not need to bind this yourself.)
|
|
sitem(tt(predict-off))(Turns off predictive typing.)
|
|
endsitem()
|
|
|
|
Although you tt(autoload) only the tt(predict-on) function, it is
|
|
necessary to create a keybinding for tt(predict-off) as well.
|
|
|
|
example(zle -N predict-on
|
|
zle -N predict-off
|
|
bindkey '^X^Z' predict-on
|
|
bindkey '^Z' predict-off)
|
|
)
|
|
tindex(read-from-minibuffer)
|
|
item(tt(read-from-minibuffer))(
|
|
This is most useful when called as a function from inside a widget, but will
|
|
work correctly as a widget in its own right. It prompts for a value
|
|
below the current command line; a value may be input using all of the
|
|
standard zle operations (and not merely the restricted set available
|
|
when executing, for example, tt(execute-named-cmd)). The value is then
|
|
returned to the calling function in the parameter tt($REPLY) and the
|
|
editing buffer restored to its previous state. If the read was aborted
|
|
by a keyboard break (typically tt(^G)), the function returns status 1
|
|
and tt($REPLY) is not set.
|
|
|
|
If one argument is supplied to the function it is taken as a prompt,
|
|
otherwise `tt(? )' is used. If two arguments are supplied, they are the
|
|
prompt and the initial value of tt($LBUFFER), and if a third argument is
|
|
given it is the initial value of tt($RBUFFER). This provides a default
|
|
value and starting cursor placement. Upon return the entire buffer is the
|
|
value of tt($REPLY).
|
|
|
|
One option is available: `tt(-k) var(num)' specifies that var(num)
|
|
characters are to be read instead of a whole line. The line editor is not
|
|
invoked recursively in this case, so depending on the terminal settings
|
|
the input may not be visible, and only the input keys are placed in
|
|
tt($REPLY), not the entire buffer. Note that unlike the tt(read) builtin
|
|
var(num) must be given; there is no default.
|
|
|
|
The name is a slight misnomer, as in fact the shell's own minibuffer is
|
|
not used. Hence it is still possible to call tt(executed-named-cmd) and
|
|
similar functions while reading a value.
|
|
)
|
|
tindex(replace-string)
|
|
tindex(replace-string-again)
|
|
tindex(replace-pattern)
|
|
xitem(tt(replace-string), tt(replace-pattern))
|
|
item(tt(replace-string-again), tt(replace-pattern-again))(
|
|
The function tt(replace-string) implements three widgets.
|
|
If defined under the same name as the function, it prompts for two
|
|
strings; the first (source) string will be replaced by the second
|
|
everywhere it occurs in the line editing buffer.
|
|
|
|
If the widget name contains the word `tt(pattern)', for example by
|
|
defining the widget using the command `tt(zle -N replace-pattern
|
|
replace-string)', then the matching is performed using zsh patterns. All
|
|
zsh extended globbing patterns can be used in the source string; note
|
|
that unlike filename generation the pattern does not need to match an
|
|
entire word, nor do glob qualifiers have any effect. In addition, the
|
|
replacement string can contain parameter or command substitutions.
|
|
Furthermore, a `tt(&)' in the replacement string will be replaced with
|
|
the matched source string, and a backquoted digit `tt(\)var(N)' will be
|
|
replaced by the var(N)th parenthesised expression matched. The form
|
|
`tt(\{)var(N)tt(})' may be used to protect the digit from following
|
|
digits.
|
|
|
|
If the widget instead contains the word `tt(regex)' (or `tt(regexp)'),
|
|
then the matching is performed using regular expressions, respecting
|
|
the setting of the option tt(RE_MATCH_PCRE) (see the description of the
|
|
function tt(regexp-replace) below). The special replacement facilities
|
|
described above for pattern matching are available.
|
|
|
|
By default the previous source or replacement string will not be offered
|
|
for editing. However, this feature can be activated by setting the style
|
|
tt(edit-previous) in the context tt(:zle:)var(widget) (for example,
|
|
tt(:zle:replace-string)) to tt(true). In addition, a positive
|
|
numeric argument forces the previous values to be offered, a negative or
|
|
zero argument forces them not to be.
|
|
|
|
The function tt(replace-string-again) can be used to repeat the previous
|
|
replacement; no prompting is done. As with tt(replace-string), if the name
|
|
of the widget contains the word `tt(pattern)' or `tt(regex)', pattern or
|
|
regular expression matching is performed, else a literal string
|
|
replacement. Note that the previous source and replacement text are the
|
|
same whether pattern, regular expression or string matching is used.
|
|
|
|
For example, starting from the line:
|
|
|
|
example(print This line contains fan and fond)
|
|
|
|
and invoking tt(replace-pattern) with the source string
|
|
`tt(f+LPAR()?+RPAR()n)' and
|
|
the replacement string `tt(c\1r)' produces the not very useful line:
|
|
|
|
example(print This line contains car and cord)
|
|
|
|
The range of the replacement string can be limited by using the
|
|
tt(narrow-to-region-invisible) widget. One limitation of the current
|
|
version is that tt(undo) will cycle through changes to the replacement
|
|
and source strings before undoing the replacement itself.
|
|
)
|
|
tindex(smart-insert-last-word)
|
|
item(tt(smart-insert-last-word))(
|
|
This function may replace the tt(insert-last-word) widget, like so:
|
|
|
|
example(zle -N insert-last-word smart-insert-last-word)
|
|
|
|
With a numeric prefix, or when passed command line arguments in a call
|
|
from another widget, it behaves like tt(insert-last-word), except that
|
|
words in comments are ignored when tt(INTERACTIVE_COMMENTS) is set.
|
|
|
|
Otherwise, the rightmost ``interesting'' word from the previous command is
|
|
found and inserted. The default definition of ``interesting'' is that the
|
|
word contains at least one alphabetic character, slash, or backslash.
|
|
This definition may be overridden by use of the tt(match) style. The
|
|
context used to look up the style is the widget name, so usually the
|
|
context is tt(:insert-last-word). However, you can bind this function to
|
|
different widgets to use different patterns:
|
|
|
|
example(zle -N insert-last-assignment smart-insert-last-word
|
|
zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
|
|
bindkey '\e=' insert-last-assignment)
|
|
|
|
If no interesting word is found and the tt(auto-previous) style is set to
|
|
a true value, the search continues upward through the history. When
|
|
tt(auto-previous) is unset or false (the default), the widget must be
|
|
invoked repeatedly in order to search earlier history lines.
|
|
)
|
|
tindex(which-command)
|
|
item(tt(which-command))(
|
|
This function is a drop-in replacement for the builtin widget
|
|
tt(which-command). It has enhanced behaviour, in that it correctly
|
|
detects whether or not the command word needs to be expanded as an
|
|
alias; if so, it continues tracing the command word from the expanded
|
|
alias until it reaches the command that will be executed.
|
|
|
|
The style tt(whence) is available in the context tt(:zle:$WIDGET); this
|
|
may be set to an array to give the command and options that will be used to
|
|
investigate the command word found. The default is tt(whence -c).
|
|
)
|
|
enditem()
|
|
|
|
subsect(Utility Functions)
|
|
|
|
These functions are useful in constructing widgets. They
|
|
should be loaded with `tt(autoload -U) var(function)' and called
|
|
as indicated from user-defined widgets.
|
|
|
|
startitem()
|
|
tindex(split-shell-arguments)
|
|
item(tt(split-shell-arguments))(
|
|
This function splits the line currently being edited into shell arguments
|
|
and whitespace. The result is stored in the array tt(reply). The array
|
|
contains all the parts of the line in order, starting with any whitespace
|
|
before the first argument, and finishing with any whitespace after the last
|
|
argument. Hence (so long as the option tt(KSH_ARRAYS) is not set)
|
|
whitespace is given by odd indices in the array and arguments by
|
|
even indices. Note that no stripping of quotes is done; joining together
|
|
all the elements of tt(reply) in order is guaranteed to produce the
|
|
original line.
|
|
|
|
The parameter tt(REPLY) is set to the index of the word in tt(reply) which
|
|
contains the character after the cursor, where the first element has index
|
|
1. The parameter tt(REPLY2) is set to the index of the character under the
|
|
cursor in that word, where the first character has index 1.
|
|
|
|
Hence tt(reply), tt(REPLY) and tt(REPLY2) should all be made local to
|
|
the enclosing function.
|
|
|
|
See the function tt(modify-current-argument), described below, for
|
|
an example of how to call this function.
|
|
)
|
|
tindex(modify-current-argument)
|
|
item(tt(modify-current-argument) var(expr-using-)tt($ARG))(
|
|
This function provides a simple method of allowing user-defined widgets
|
|
to modify the command line argument under the cursor (or immediately to the
|
|
left of the cursor if the cursor is between arguments). The argument
|
|
should be an expression which when evaluated operates on the shell
|
|
parameter tt(ARG), which will have been set to the command line argument
|
|
under the cursor. The expression should be suitably quoted to prevent
|
|
it being evaluated too early.
|
|
|
|
For example, a user-defined widget containing the following code
|
|
converts the characters in the argument under the cursor into all upper
|
|
case:
|
|
|
|
example(modify-current-argument '${(U)ARG}')
|
|
|
|
The following strips any quoting from the current word (whether backslashes
|
|
or one of the styles of quotes), and replaces it with single quoting
|
|
throughout:
|
|
|
|
example(modify-current-argument '${(qq)${(Q)ARG}}')
|
|
)
|
|
enditem()
|
|
|
|
subsect(Styles)
|
|
|
|
The behavior of several of the above widgets can be controlled by the use
|
|
of the tt(zstyle) mechanism. In particular, widgets that interact with
|
|
the completion system pass along their context to any completions that
|
|
they invoke.
|
|
|
|
startitem()
|
|
kindex(break-keys, widget style)
|
|
item(tt(break-keys))(
|
|
This style is used by the tt(incremental-complete-word) widget. Its value
|
|
should be a pattern, and all keys matching this pattern will cause the
|
|
widget to stop incremental completion without the key having any further
|
|
effect. Like all styles used directly by
|
|
tt(incremental-complete-word), this style is looked up using the
|
|
context `tt(:incremental)'.
|
|
)
|
|
kindex(completer, completion style)
|
|
item(tt(completer))(
|
|
The tt(incremental-complete-word) and tt(insert-and-predict) widgets set
|
|
up their top-level context name before calling completion. This allows
|
|
one to define different sets of completer functions for normal completion
|
|
and for these widgets. For example, to use completion, approximation and
|
|
correction for normal completion, completion and correction for
|
|
incremental completion and only completion for prediction one could use:
|
|
|
|
example(zstyle ':completion:*' completer \
|
|
_complete _correct _approximate
|
|
zstyle ':completion:incremental:*' completer \
|
|
_complete _correct
|
|
zstyle ':completion:predict:*' completer \
|
|
_complete)
|
|
|
|
It is a good idea to restrict the completers used in prediction, because
|
|
they may be automatically invoked as you type. The tt(_list) and
|
|
tt(_menu) completers should never be used with prediction. The
|
|
tt(_approximate), tt(_correct), tt(_expand), and tt(_match) completers may
|
|
be used, but be aware that they may change characters anywhere in the word
|
|
behind the cursor, so you need to watch carefully that the result is what
|
|
you intended.
|
|
)
|
|
kindex(cursor, completion style)
|
|
item(tt(cursor))(
|
|
The tt(insert-and-predict) widget uses this style, in the context
|
|
`tt(:predict)', to decide where to place the cursor after completion has
|
|
been tried. Values are:
|
|
|
|
startitem()
|
|
item(tt(complete))(
|
|
The cursor is left where it was when completion finished, but only if
|
|
it is after a character equal to the one just inserted by the user. If
|
|
it is after another character, this value is the same as `tt(key)'.
|
|
)
|
|
item(tt(key))(
|
|
The cursor is left
|
|
after the var(n)th occurrence of the character just inserted, where
|
|
var(n) is the number of times that character appeared in the word
|
|
before completion was attempted. In short, this has the effect of
|
|
leaving the cursor after the character just typed even if the
|
|
completion code found out that no other characters need to be inserted
|
|
at that position.
|
|
)
|
|
enditem()
|
|
|
|
Any other value for this style unconditionally leaves the cursor at the
|
|
position where the completion code left it.
|
|
)
|
|
kindex(list, widget style)
|
|
item(tt(list))(
|
|
When using the tt(incremental-complete-word) widget, this style says
|
|
if the matches should be listed on every key press (if they fit on the
|
|
screen). Use the context prefix `tt(:completion:incremental)'.
|
|
|
|
The tt(insert-and-predict) widget uses this style to decide if the
|
|
completion should be shown even if there is only one possible completion.
|
|
This is done if the value of this style is the string tt(always). In this
|
|
case the context is `tt(:predict)' (em(not) `tt(:completion:predict)').
|
|
)
|
|
kindex(match, widget style)
|
|
item(tt(match))(
|
|
This style is used by tt(smart-insert-last-word) to provide a pattern
|
|
(using full tt(EXTENDED_GLOB) syntax) that matches an interesting word.
|
|
The context is the name of the widget to which tt(smart-insert-last-word)
|
|
is bound (see above). The default behavior of tt(smart-insert-last-word)
|
|
is equivalent to:
|
|
|
|
example(zstyle :insert-last-word match '*[[:alpha:]/\\]*')
|
|
|
|
However, you might want to include words that contain spaces:
|
|
|
|
example(zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*')
|
|
|
|
Or include numbers as long as the word is at least two characters long:
|
|
|
|
example(zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*')
|
|
|
|
The above example causes redirections like "2>" to be included.
|
|
)
|
|
kindex(prompt, widget style)
|
|
item(tt(prompt))(
|
|
The tt(incremental-complete-word) widget shows the value of this
|
|
style in the status line during incremental completion. The string
|
|
value may contain any of the following substrings in the manner of
|
|
the tt(PS1) and other prompt parameters:
|
|
|
|
startitem()
|
|
item(tt(%c))(
|
|
Replaced by the name of the completer function that generated the
|
|
matches (without the leading underscore).
|
|
)
|
|
item(tt(%l))(
|
|
When the tt(list) style is set,
|
|
replaced by `tt(...)' if the list of matches is too long to fit on the
|
|
screen and with an empty string otherwise. If the tt(list) style is
|
|
`false' or not set, `tt(%l)' is always removed.
|
|
)
|
|
item(tt(%n))(
|
|
Replaced by the number of matches generated.
|
|
)
|
|
item(tt(%s))(
|
|
Replaced by `tt(-no match-)', `tt(-no prefix-)', or an empty string
|
|
if there is no completion matching the word on the line, if the
|
|
matches have no common prefix different from the word on the line, or
|
|
if there is such a common prefix, respectively.
|
|
)
|
|
item(tt(%u))(
|
|
Replaced by the unambiguous part of all matches, if there
|
|
is any, and if it is different from the word on the line.
|
|
)
|
|
enditem()
|
|
|
|
Like `tt(break-keys)', this uses the `tt(:incremental)' context.
|
|
)
|
|
kindex(stop-keys, widget style)
|
|
item(tt(stop-keys))(
|
|
This style is used by the tt(incremental-complete-word) widget. Its value
|
|
is treated similarly to the one for the tt(break-keys) style (and uses
|
|
the same context: `tt(:incremental)'). However, in
|
|
this case all keys matching the pattern given as its value will stop
|
|
incremental completion and will then execute their usual function.
|
|
)
|
|
kindex(toggle, widget style)
|
|
item(tt(toggle))(
|
|
This boolean style is used by tt(predict-on) and its related widgets in
|
|
the context `tt(:predict)'. If set to one of the standard `true' values,
|
|
predictive typing is automatically toggled off in situations where it is
|
|
unlikely to be useful, such as when editing a multi-line buffer or after
|
|
moving into the middle of a line and then deleting a character. The
|
|
default is to leave prediction turned on until an explicit call to
|
|
tt(predict-off).
|
|
)
|
|
kindex(verbose, widget style)
|
|
item(tt(verbose))(
|
|
This boolean style is used by tt(predict-on) and its related widgets in
|
|
the context `tt(:predict)'. If set to one of the standard `true' values,
|
|
these widgets display a message below the prompt when the predictive state
|
|
is toggled. This is most useful in combination with the tt(toggle) style.
|
|
The default does not display these messages.
|
|
)
|
|
kindex(widget, widget style)
|
|
item(tt(widget))(
|
|
This style is similar to the tt(command) style: For widget functions that
|
|
use tt(zle) to call other widgets, this style can sometimes be used to
|
|
override the widget which is called. The context for this style is the
|
|
name of the calling widget (em(not) the name of the calling function,
|
|
because one function may be bound to multiple widget names).
|
|
|
|
example(zstyle :copy-earlier-word widget smart-insert-last-word)
|
|
|
|
Check the documentation for the calling widget or function to determine
|
|
whether the tt(widget) style is used.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Exception Handling)(MIME Functions)(ZLE Functions)(User Contributions)
|
|
sect(Exception Handling)
|
|
|
|
Two functions are provided to enable zsh to provide exception handling in a
|
|
form that should be familiar from other languages.
|
|
|
|
startitem()
|
|
findex(throw)
|
|
item(tt(throw) var(exception))(
|
|
The function tt(throw) throws the named var(exception). The name is
|
|
an arbitrary string and is only used by the tt(throw) and tt(catch)
|
|
functions. An exception is for the most part treated the same as a
|
|
shell error, i.e. an unhandled exception will cause the shell to abort all
|
|
processing in a function or script and to return to the top level in an
|
|
interactive shell.
|
|
)
|
|
item(tt(catch) var(exception-pattern))(
|
|
The function tt(catch) returns status zero if an exception was thrown and
|
|
the pattern var(exception-pattern) matches its name. Otherwise it
|
|
returns status 1. var(exception-pattern) is a standard
|
|
shell pattern, respecting the current setting of the tt(EXTENDED_GLOB)
|
|
option. An alias tt(catch) is also defined to prevent the argument to the
|
|
function from matching filenames, so patterns may be used unquoted. Note
|
|
that as exceptions are not fundamentally different from other shell errors
|
|
it is possible to catch shell errors by using an empty string as the
|
|
exception name. The shell variable tt(CAUGHT) is set by tt(catch) to the
|
|
name of the exception caught. It is possible to rethrow an exception by
|
|
calling the tt(throw) function again once an exception has been caught.
|
|
findex(catch)
|
|
)
|
|
enditem()
|
|
|
|
The functions are designed to be used together with the tt(always) construct
|
|
described in
|
|
ifzman(zmanref(zshmisc))\
|
|
ifnzman(noderef(Complex Commands)). This is important as only this
|
|
construct provides the required support for exceptions. A typical example
|
|
is as follows.
|
|
|
|
example({
|
|
# "try" block
|
|
# ... nested code here calls "throw MyExcept"
|
|
} always {
|
|
# "always" block
|
|
if catch MyExcept; then
|
|
print "Caught exception MyExcept"
|
|
elif catch ''; then
|
|
print "Caught a shell error. Propagating..."
|
|
throw ''
|
|
fi
|
|
# Other exceptions are not handled but may be caught further
|
|
# up the call stack.
|
|
})
|
|
|
|
If all exceptions should be caught, the following idiom might be
|
|
preferable.
|
|
|
|
example({
|
|
# ... nested code here throws an exception
|
|
} always {
|
|
if catch *; then
|
|
case $CAUGHT in
|
|
LPAR()MyExcept+RPAR()
|
|
print "Caught my own exception"
|
|
;;
|
|
LPAR()*RPAR()
|
|
print "Caught some other exception"
|
|
;;
|
|
esac
|
|
fi
|
|
})
|
|
|
|
In common with exception handling in other languages, the exception may be
|
|
thrown by code deeply nested inside the `try' block. However, note that it
|
|
must be thrown inside the current shell, not in a subshell forked for a
|
|
pipeline, parenthesised current-shell construct, or some form of
|
|
command or process substitution.
|
|
|
|
The system internally uses the shell variable tt(EXCEPTION) to record the
|
|
name of the exception between throwing and catching. One drawback of this
|
|
scheme is that if the exception is not handled the variable tt(EXCEPTION)
|
|
remains set and may be incorrectly recognised as the name of an exception
|
|
if a shell error subsequently occurs. Adding tt(unset EXCEPTION) at the
|
|
start of the outermost layer of any code that uses exception handling will
|
|
eliminate this problem.
|
|
|
|
texinode(MIME Functions)(Mathematical Functions)(Exception Handling)(User Contributions)
|
|
sect(MIME Functions)
|
|
|
|
Three functions are available to provide handling of files recognised by
|
|
extension, for example to dispatch a file tt(text.ps) when executed as a
|
|
command to an appropriate viewer.
|
|
|
|
startitem()
|
|
findex(zsh-mime-setup)
|
|
findex(zsh-mime-handler)
|
|
xitem(tt(zsh-mime-setup) [ tt(-fv) ] [ tt(-l) [ var(suffix ...) ] ])
|
|
item(tt(zsh-mime-handler))(
|
|
These two functions use the files tt(~/.mime.types) and tt(/etc/mime.types),
|
|
which associate types and extensions, as well as tt(~/.mailcap) and
|
|
tt(/etc/mailcap) files, which associate types and the programs that
|
|
handle them. These are provided on many systems with the Multimedia
|
|
Internet Mail Extensions.
|
|
|
|
To enable the system, the function tt(zsh-mime-setup) should be
|
|
autoloaded and run. This allows files with extensions to be treated
|
|
as executable; such files be completed by the function completion system.
|
|
The function tt(zsh-mime-handler) should not need to be called by the
|
|
user.
|
|
|
|
The system works by setting up suffix aliases with `tt(alias -s)'.
|
|
Suffix aliases already installed by the user will not be overwritten.
|
|
|
|
For suffixes defined in lower case, upper case variants will also
|
|
automatically be handled (e.g. tt(PDF) is automatically handled if
|
|
handling for the suffix tt(pdf) is defined), but not vice versa.
|
|
|
|
Repeated calls to tt(zsh-mime-setup) do not override the existing
|
|
mapping between suffixes and executable files unless the option tt(-f)
|
|
is given. Note, however, that this does not override existing suffix
|
|
aliases assigned to handlers other than tt(zsh-mime-handler).
|
|
|
|
Calling tt(zsh-mime-setup) with the option tt(-l) lists the existing
|
|
mappings without altering them. Suffixes to list (which may contain
|
|
pattern characters that should be quoted from immediate interpretation
|
|
on the command line) may be given as additional arguments, otherwise
|
|
all suffixes are listed.
|
|
|
|
Calling tt(zsh-mime-setup) with the option
|
|
tt(-v) causes verbose output to be shown during the setup operation.
|
|
|
|
The system respects the tt(mailcap) flags tt(needsterminal) and
|
|
tt(copiousoutput), see manref(mailcap)(4).
|
|
|
|
The functions use the following styles, which are defined with the
|
|
tt(zstyle) builtin command (\
|
|
ifzman(see zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zutil Module))). They should be defined
|
|
before tt(zsh-mime-setup) is run. The contexts used all
|
|
start with tt(:mime:), with additional components in some cases.
|
|
It is recommended that a trailing tt(*) (suitably quoted) be appended
|
|
to style patterns in case the system is extended in future. Some
|
|
examples are given below.
|
|
startitem()
|
|
kindex(current-shell, MIME style)
|
|
item(tt(current-shell))(
|
|
If this boolean style is true, the mailcap handler for the context in
|
|
question is run using the tt(eval) builtin instead of by starting a new
|
|
tt(sh) process. This is more efficient, but may not work in the occasional
|
|
cases where the mailcap handler uses strict POSIX syntax.
|
|
)
|
|
kindex(execute-as-is, MIME style)
|
|
item(tt(execute-as-is))(
|
|
This style gives a list of patterns to be matched against files
|
|
passed for execution with a handler program. If the file matches
|
|
the pattern, the entire command line is executed in its current form,
|
|
with no handler. This is useful for files which might have suffixes
|
|
but nonetheless be executable in their own right. If the style
|
|
is not set, the pattern tt(*+LPAR()*+RPAR() *+LPAR()/+RPAR()) is used;
|
|
hence executable files are executed directly and not passed to a
|
|
handler, and the option tt(AUTO_CD) may be used to change to directories
|
|
that happen to have MIME suffixes.
|
|
)
|
|
kindex(file-path, MIME style)
|
|
item(tt(file-path))(
|
|
Used if the style tt(find-file-in-path) is true for the same context.
|
|
Set to an array of directories that are used for searching for the
|
|
file to be handled; the default is the command path given by the
|
|
special parameter tt(path). The shell option tt(PATH_DIRS) is respected;
|
|
if that is set, the appropriate path will be searched even if the
|
|
name of the file to be handled as it appears on the command line contains
|
|
a `tt(/)'.
|
|
The full context is tt(:mime:.)var(suffix)tt(:), as described for the style
|
|
tt(handler).
|
|
)
|
|
kindex(find-file-in-path, MIME style)
|
|
item(tt(find-file-in-path))(
|
|
If set, allows files whose names do not contain absolute paths
|
|
to be searched for in the command path or the path specified by the
|
|
tt(file-path) style. If the file is not found in the path, it is looked
|
|
for locally (whether or not the current directory is in the path); if it is
|
|
not found locally, the handler will abort unless the tt(handle-nonexistent)
|
|
style is set. Files found in the path are tested as described for
|
|
the style tt(execute-as-is).
|
|
The full context is tt(:mime:.)var(suffix)tt(:), as described for the style
|
|
tt(handler).
|
|
)
|
|
kindex(flags, MIME style)
|
|
item(tt(flags))(
|
|
Defines flags to go with a handler; the context is as for the
|
|
tt(handler) style, and the format is as for the flags in tt(mailcap).
|
|
)
|
|
kindex(handle-nonexistent, MIME style)
|
|
item(tt(handle-nonexistent))(
|
|
By default, arguments that don't correspond to files are not passed
|
|
to the MIME handler in order to prevent it from intercepting commands found
|
|
in the path that happen to have suffixes. This style may be set to
|
|
an array of extended glob patterns for arguments that will be passed to the
|
|
handler even if they don't exist. If it is not explicitly set it
|
|
defaults to tt([[:alpha:]]#:/*) which allows URLs to be passed to the MIME
|
|
handler even though they don't exist in that format in the file system.
|
|
The full context is tt(:mime:.)var(suffix)tt(:), as described for the style
|
|
tt(handler).
|
|
)
|
|
kindex(handler, MIME style)
|
|
item(tt(handler))(
|
|
Specifies a handler for a suffix; the suffix is given by the context as
|
|
tt(:mime:.)var(suffix)tt(:), and the format of the handler is exactly
|
|
that in tt(mailcap). Note in particular the `tt(.)' and trailing colon
|
|
to distinguish this use of the context. This overrides any handler
|
|
specified by the tt(mailcap) files. If the handler requires a terminal,
|
|
the tt(flags) style should be set to include the word tt(needsterminal),
|
|
or if the output is to be displayed through a pager (but not if the
|
|
handler is itself a pager), it should include tt(copiousoutput).
|
|
)
|
|
kindex(mailcap, MIME style)
|
|
item(tt(mailcap))(
|
|
A list of files in the format of tt(~/.mailcap) and
|
|
tt(/etc/mailcap) to be read during setup, replacing the default list
|
|
which consists of those two files. The context is tt(:mime:).
|
|
A tt(PLUS()) in the list will be replaced by the default files.
|
|
)
|
|
kindex(mailcap-priorities, MIME style)
|
|
item(tt(mailcap-priorities))(
|
|
This style is used to resolve multiple mailcap entries for the same MIME
|
|
type. It consists of an array of the following elements, in descending
|
|
order of priority; later entries will be used if earlier entries are
|
|
unable to resolve the entries being compared. If none of the tests
|
|
resolve the entries, the first entry encountered is retained.
|
|
|
|
startitem()
|
|
item(tt(files))(
|
|
The order of files (entries in the tt(mailcap) style) read. Earlier
|
|
files are preferred. (Note this does not resolve entries in the same file.)
|
|
)
|
|
item(tt(priority))(
|
|
The priority flag from the mailcap entry. The priority is an integer
|
|
from 0 to 9 with the default value being 5.
|
|
)
|
|
item(tt(flags))(
|
|
The test given by the tt(mailcap-prio-flags) option is used to resolve
|
|
entries.
|
|
)
|
|
item(tt(place))(
|
|
Later entries are preferred; as the entries are strictly ordered, this
|
|
test always succeeds.
|
|
)
|
|
enditem()
|
|
|
|
Note that as this style is handled during initialisation, the context
|
|
is always tt(:mime:), with no discrimination by suffix.
|
|
)
|
|
kindex(mailcap-prio-flags, MIME style)
|
|
item(tt(mailcap-prio-flags))(
|
|
This style is used when the keyword tt(flags) is encountered in the
|
|
list of tests specified by the tt(mailcap-priorities) style.
|
|
It should be set to a list of patterns, each of which is tested against
|
|
the flags specified in the mailcap entry (in other words, the sets of
|
|
assignments found with some entries in the mailcap file). Earlier
|
|
patterns in the list are preferred to later ones, and matched patterns
|
|
are preferred to unmatched ones.
|
|
)
|
|
kindex(mime-types, MIME style)
|
|
item(tt(mime-types))(
|
|
A list of files in the format of tt(~/.mime.types) and
|
|
tt(/etc/mime.types) to be read during setup, replacing the default list
|
|
which consists of those two files. The context is tt(:mime:).
|
|
A tt(PLUS()) in the list will be replaced by the default files.
|
|
)
|
|
kindex(never-background, MIME style)
|
|
item(tt(never-background))(
|
|
If this boolean style is set, the handler for the given context is
|
|
always run in the foreground, even if the flags provided in the mailcap
|
|
entry suggest it need not be (for example, it doesn't require a
|
|
terminal).
|
|
)
|
|
kindex(pager, MIME style)
|
|
item(tt(pager))(
|
|
If set, will be used instead of tt($PAGER) or tt(more) to handle
|
|
suffixes where the tt(copiousoutput) flag is set. The context is
|
|
as for tt(handler), i.e. tt(:mime:.)var(suffix)tt(:) for handling
|
|
a file with the given var(suffix).
|
|
)
|
|
enditem()
|
|
|
|
Examples:
|
|
|
|
example(zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
|
|
zstyle ':mime:.txt:' handler less %s
|
|
zstyle ':mime:.txt:' flags needsterminal)
|
|
|
|
When tt(zsh-mime-setup) is subsequently run, it will look for
|
|
tt(mailcap) entries in the two files given. Files of suffix tt(.txt)
|
|
will be handled by running `tt(less) var(file.txt)'. The flag
|
|
tt(needsterminal) is set to show that this program must run attached to a
|
|
terminal.
|
|
|
|
As there are several steps to dispatching a command, the following
|
|
should be checked if attempting to execute a file by extension
|
|
tt(.)var(ext) does not have the expected effect.
|
|
|
|
The command `tt(alias -s) var(ext)' should show
|
|
`tt(ps=zsh-mime-handler)'. If it shows something else, another suffix
|
|
alias was already installed and was not overwritten. If it shows
|
|
nothing, no handler was installed: this is most likely because no
|
|
handler was found in the tt(.mime.types) and tt(mailcap) combination for
|
|
tt(.ext) files. In that case, appropriate handling should be added to
|
|
tt(~/.mime.types) and tt(mailcap).
|
|
|
|
If the extension is handled by tt(zsh-mime-handler) but the file is
|
|
not opened correctly, either the handler defined for the type is
|
|
incorrect, or the flags associated with it are in appropriate. Running
|
|
tt(zsh-mime-setup -l) will show the handler and, if there are any, the
|
|
flags. A tt(%s) in the handler is replaced by the file (suitably quoted
|
|
if necessary). Check that the handler program listed lists and can
|
|
be run in the way shown. Also check that the flags tt(needsterminal) or
|
|
tt(copiousoutput) are set if the handler needs to be run under a
|
|
terminal; the second flag is used if the output should be sent to a pager.
|
|
An example of a suitable tt(mailcap) entry for such a program is:
|
|
|
|
example(text/html; /usr/bin/lynx '%s'; needsterminal)
|
|
)
|
|
findex(pick-web-browser)
|
|
item(tt(pick-web-browser))(
|
|
This function is separate from the two MIME functions described above
|
|
and can be assigned directly to a suffix:
|
|
|
|
example(autoload -U pick-web-browser
|
|
alias -s html=pick-web-browser)
|
|
|
|
It is provided as an intelligent front end to dispatch a web browser.
|
|
It may be run as either a function or a shell script. The status
|
|
255 is returned if no browser could be started.
|
|
|
|
Various styles are available to customize the choice of browsers:
|
|
|
|
startitem()
|
|
item(tt(browser-style))(
|
|
The value of the style is an array giving preferences in decreasing order
|
|
for the type of browser to use. The values of elements may be
|
|
|
|
startitem()
|
|
item(tt(running))(
|
|
Use a GUI browser that is already running when an X Window display is
|
|
available. The browsers listed in the tt(x-browsers) style are tried
|
|
in order until one is found; if it is, the file will be displayed in
|
|
that browser, so the user may need to check whether it has appeared.
|
|
If no running browser is found, one is not started. Browsers other than
|
|
Firefox, Opera and Konqueror are assumed to understand the Mozilla
|
|
syntax for opening a URL remotely.
|
|
)
|
|
item(tt(x))(
|
|
Start a new GUI browser when an X Window display is available. Search for
|
|
the availability of one of the browsers listed in the tt(x-browsers) style
|
|
and start the first one that is found. No check is made for an already
|
|
running browser.
|
|
)
|
|
item(tt(tty))(
|
|
Start a terminal-based browser. Search for the availability of one
|
|
of the browsers listed in the tt(tty-browsers) style and start the
|
|
first one that is found.
|
|
)
|
|
enditem()
|
|
|
|
If the style is not set the default tt(running x tty) is used.
|
|
)
|
|
item(tt(x-browsers))(
|
|
An array in decreasing order
|
|
of preference of browsers to use when running under the X Window System.
|
|
The array consists of the command name under which to start the
|
|
browser. They are looked up in the context tt(:mime:) (which may
|
|
be extended in future, so appending `tt(*)' is recommended). For
|
|
example,
|
|
|
|
example(zstyle ':mime:*' x-browsers opera konqueror firefox)
|
|
|
|
specifies that tt(pick-web-browser) should first look for a running
|
|
instance of Opera, Konqueror or Firefox, in that order, and if it
|
|
fails to find any should attempt to start Opera. The default is
|
|
tt(firefox mozilla netscape opera konqueror).
|
|
)
|
|
item(tt(tty-browsers))(
|
|
An array similar to tt(x-browsers), except that it gives browsers to
|
|
use use when no X Window display is available. The default is
|
|
tt(elinks links lynx).
|
|
)
|
|
item(tt(command))(
|
|
If it is set this style is used to pick the command
|
|
used to open a page for a browser. The context is
|
|
tt(:mime:browser:new:$browser:) to start a new browser or
|
|
tt(:mime:browser:running:$browser:) to open a URL in a browser already
|
|
running on the current X display, where tt($browser) is the value matched
|
|
in the tt(x-browsers) or tt(tty-browsers) style. The escape sequence
|
|
tt(%b) in the style's value will be replaced by the browser, while tt(%u)
|
|
will be replaced by the URL. If the style is not set, the default for all
|
|
new instances is equivalent to tt(%b %u) and the defaults for using running
|
|
browsers are equivalent to the values tt(kfmclient openURL %u) for
|
|
Konqueror, tt(firefox -new-tab %u) for Firefox, tt(opera -newpage %u)
|
|
for Opera, and tt(%b -remote "openUrl+LPAR()%u+RPAR()") for all others.
|
|
)
|
|
enditem()
|
|
)
|
|
enditem()
|
|
|
|
texinode(Mathematical Functions)(User Configuration Functions)(MIME Functions)(User Contributions)
|
|
sect(Mathematical Functions)
|
|
|
|
startitem()
|
|
findex(zcalc)
|
|
item(tt(zcalc) [ var(expression) ... ])(
|
|
A reasonably powerful calculator based on zsh's arithmetic evaluation
|
|
facility. The syntax is similar to that of formulae in most programming
|
|
languages; see
|
|
ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
|
|
ifnzman(noderef(Arithmetic Evaluation)) for details. The mathematical
|
|
library tt(zsh/mathfunc) will be loaded if it is available; see
|
|
ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/mathfunc Module)). The mathematical functions
|
|
correspond to the raw system libraries, so trigonometric functions are
|
|
evaluated using radians, and so on.
|
|
|
|
Each line typed is evaluated as an expression. The prompt shows a number,
|
|
which corresponds to a positional parameter where the result of that
|
|
calculation is stored. For example, the result of the calculation on the
|
|
line preceded by `tt(4> )' is available as tt($4). The last value
|
|
calculated is available as tt(ans). Full command line editing, including
|
|
the history of previous calculations, is available; the history is saved in
|
|
the file tt(~/.zcalc_history). To exit, enter a blank line or type `tt(:q)'
|
|
on its own (`tt(q)' is allowed for historical compatibility).
|
|
|
|
If arguments are given to tt(zcalc) on start up, they are used to prime the
|
|
first few positional parameters. A visual indication of this is given when
|
|
the calculator starts.
|
|
|
|
The constants tt(PI) (3.14159...) and tt(E) (2.71828...) are provided.
|
|
Parameter assignment is possible, but note that all parameters will be put
|
|
into the global namespace.
|
|
|
|
The output base can be initialised by passing the option `tt(-#)var(base)',
|
|
for example `tt(zcalc -#16)' (the `tt(#)' may have to be quoted, depending
|
|
on the globbing options set).
|
|
|
|
The prompt is configurable via the parameter tt(ZCALCPROMPT), which
|
|
undergoes standard prompt expansion. The index of the current entry is
|
|
stored locally in the first element of the array tt(psvar), which can be
|
|
referred to in tt(ZCALCPROMPT) as `tt(%1v)'. The default prompt is
|
|
`tt(%1v> )'.
|
|
|
|
A few special commands are available; these are introduced by a colon.
|
|
For backward compatibility, the colon may be omitted for certain
|
|
commands. Completion is available if tt(compinit) has been run.
|
|
|
|
The output precision may be specified within zcalc by special commands
|
|
familiar from many calculators.
|
|
startitem()
|
|
item(tt(:norm))(
|
|
The default output format. It corresponds to the printf tt(%g)
|
|
specification. Typically this shows six decimal digits.
|
|
)
|
|
item(tt(:sci) var(digits))(
|
|
Scientific notation, corresponding to the printf tt(%g) output format with
|
|
the precision given by var(digits). This produces either fixed point or
|
|
exponential notation depending on the value output.
|
|
)
|
|
item(tt(:fix) var(digits))(
|
|
Fixed point notation, corresponding to the printf tt(%f) output format with
|
|
the precision given by var(digits).
|
|
)
|
|
item(tt(:eng) var(digits))(
|
|
Exponential notation, corresponding to the printf tt(%E) output format with
|
|
the precision given by var(digits).
|
|
)
|
|
item(tt(:raw))(
|
|
Raw output: this is the default form of the output from a math
|
|
evaluation. This may show more precision than the number actually
|
|
possesses.
|
|
)
|
|
enditem()
|
|
|
|
Other special commands:
|
|
startitem()
|
|
item(tt(:!)var(line...))(
|
|
Execute var(line...) as a normal shell command line. Note that it
|
|
is executed in the context of the function, i.e. with local variables.
|
|
Space is optional after tt(:!).
|
|
)
|
|
item(tt(:local) var(arg) ...)(
|
|
Declare variables local to the function. Note that certain variables
|
|
are used by the function for its own purposes. Other variables
|
|
may be used, too, but they will be taken from or put into the global
|
|
scope.
|
|
)
|
|
item(tt(:function) var(name) [ var(body) ])(
|
|
Define a mathematical function or (with no var(body)) delete it.
|
|
The function is defined using tt(zmathfuncdef), see below.
|
|
|
|
Note that tt(zcalc) takes care of all quoting. Hence for example:
|
|
|
|
example(function cube $1 * $1 * $1)
|
|
|
|
defines a function to cube the sole argument.
|
|
)
|
|
item(tt([#)var(base)tt(]))(
|
|
This is not a special command, rather part of normal arithmetic
|
|
syntax; however, when this form appears on a line by itself the default
|
|
output radix is set to var(base). Use, for example, `tt([#16])' to display
|
|
hexadecimal output preceded by an indication of the base, or `tt([##16])'
|
|
just to display the raw number in the given base. Bases themselves are
|
|
always specified in decimal. `tt([#])' restores the normal output format.
|
|
Note that setting an output base suppresses floating point output; use
|
|
`tt([#])' to return to normal operation.
|
|
)
|
|
enditem()
|
|
|
|
See the comments in the function for a few extra tips.
|
|
)
|
|
findex(zmathfuncdef)
|
|
item(tt(zmathfuncdef) [ var(mathfunc) [ var(body) ] ])(
|
|
A convenient front end to tt(functions -M).
|
|
|
|
With two arguments, define a mathematical function named var(mathfunc)
|
|
which can be used in any form of arithmetic evaluation. var(body)
|
|
is a mathematical expression to implement the function. It may
|
|
contain references to position parameters tt($1), tt($2), ...
|
|
to refer to mandatory parameters and tt(${1:-)var(defvalue)tt(}) ...
|
|
to refer to optional parameters. Note that the forms must be
|
|
strictly adhered to for the function to calculate the correct number
|
|
of arguments. The implementation is held in a shell function named
|
|
tt(zsh_math_func_)var(mathfunc); usually the user will not need
|
|
to refer to the shell function directly. Any existing function
|
|
of the same name is silently replaced.
|
|
|
|
With one argument, remove the mathematical function var(mathfunc)
|
|
as well as the shell function implementation.
|
|
|
|
With no arguments, list all var(mathfunc) functions in a form
|
|
suitable for restoring the definition.
|
|
The functions have not necessarily been defined by tt(zmathfuncdef).
|
|
)
|
|
enditem()
|
|
|
|
texinode(User Configuration Functions)(Other Functions)(Mathematical Functions)(User Contributions)
|
|
sect(User Configuration Functions)
|
|
|
|
The tt(zsh/newuser) module comes with a function to aid in configuring
|
|
shell options for new users. If the module is installed, this function can
|
|
also be run by hand. It is available even if the module's default
|
|
behaviour, namely running the function for a new user logging in without
|
|
startup files, is inhibited.
|
|
|
|
startitem()
|
|
item(tt(zsh-newuser-install) [ tt(-f) ])(
|
|
The function presents the user with various options for customizing
|
|
their initialization scripts. Currently only tt(~/.zshrc) is handled.
|
|
tt($ZDOTDIR/.zshrc) is used instead if the parameter tt(ZDOTDIR) is
|
|
set; this provides a way for the user to configure a file without
|
|
altering an existing tt(.zshrc).
|
|
|
|
By default the function exits immediately if it finds any of the files
|
|
tt(.zshenv), tt(.zprofile), tt(.zshrc), or tt(.zlogin) in the appropriate
|
|
directory. The option tt(-f) is required in order to force the function
|
|
to continue. Note this may happen even if tt(.zshrc) itself does not
|
|
exist.
|
|
|
|
As currently configured, the function will exit immediately if the
|
|
user has root privileges; this behaviour cannot be overridden.
|
|
|
|
Once activated, the function's behaviour is supposed to be
|
|
self-explanatory. Menus are present allowing the user to alter
|
|
the value of options and parameters. Suggestions for improvements are
|
|
always welcome.
|
|
|
|
When the script exits, the user is given the opportunity to save the new
|
|
file or not; changes are not irreversible until this point. However,
|
|
the script is careful to restrict changes to the file only to a group
|
|
marked by the lines `tt(# Lines configured by zsh-newuser-install)' and
|
|
`tt(# End of lines configured by zsh-newuser-install)'. In addition,
|
|
the old version of tt(.zshrc) is saved to a file with the suffix
|
|
tt(.zni) appended.
|
|
|
|
If the function edits an existing tt(.zshrc), it is up to the user
|
|
to ensure that the changes made will take effect. For example, if
|
|
control usually returns early from the existing tt(.zshrc) the lines
|
|
will not be executed; or a later initialization file may override
|
|
options or parameters, and so on. The function itself does not attempt to
|
|
detect any such conflicts.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Other Functions)()(User Configuration Functions)(User Contributions)
|
|
sect(Other Functions)
|
|
|
|
There are a large number of helpful functions in the tt(Functions/Misc)
|
|
directory of the zsh distribution. Most are very simple and do not
|
|
require documentation here, but a few are worthy of special mention.
|
|
|
|
subsect(Descriptions)
|
|
|
|
startitem()
|
|
findex(colors)
|
|
item(tt(colors))(
|
|
This function initializes several associative arrays to map color names to
|
|
(and from) the ANSI standard eight-color terminal codes. These are used
|
|
by the prompt theme system (ifzman(see above)\
|
|
ifnzman(noderef(Prompt Themes))). You seldom should need to run
|
|
tt(colors) more than once.
|
|
|
|
The eight base colors are: black, red, green, yellow, blue, magenta, cyan,
|
|
and white. Each of these has codes for foreground and background. In
|
|
addition there are eight intensity attributes: bold, faint, standout,
|
|
underline, blink, reverse, and conceal. Finally, there are six codes used
|
|
to negate attributes: none (reset all attributes to the defaults), normal
|
|
(neither bold nor faint), no-standout, no-underline, no-blink, and
|
|
no-reverse.
|
|
|
|
Some terminals do not support all combinations of colors and intensities.
|
|
|
|
The associative arrays are:
|
|
|
|
startitem()
|
|
xitem(color)
|
|
item(colour)(
|
|
Map all the color names to their integer codes, and integer codes to the
|
|
color names. The eight base names map to the foreground color codes, as
|
|
do names prefixed with `tt(fg-)', such as `tt(fg-red)'. Names prefixed
|
|
with `tt(bg-)', such as `tt(bg-blue)', refer to the background codes. The
|
|
reverse mapping from code to color yields base name for foreground codes
|
|
and the tt(bg-) form for backgrounds.
|
|
|
|
Although it is a misnomer to call them `colors', these arrays also map the
|
|
other fourteen attributes from names to codes and codes to names.
|
|
)
|
|
xitem(fg)
|
|
xitem(fg_bold)
|
|
item(fg_no_bold)(
|
|
Map the eight basic color names to ANSI terminal escape sequences that set
|
|
the corresponding foreground text properties. The tt(fg) sequences change
|
|
the color without changing the eight intensity attributes.
|
|
)
|
|
xitem(bg)
|
|
xitem(bg_bold)
|
|
item(bg_no_bold)(
|
|
Map the eight basic color names to ANSI terminal escape sequences that set
|
|
the corresponding background properties. The tt(bg) sequences change the
|
|
color without changing the eight intensity attributes.
|
|
)
|
|
enditem()
|
|
|
|
In addition, the scalar parameters tt(reset_color) and tt(bold_color) are
|
|
set to the ANSI terminal escapes that turn off all attributes and turn on
|
|
bold intensity, respectively.
|
|
)
|
|
findex(fned)
|
|
item(tt(fned) var(name))(
|
|
Same as tt(zed -f). This function does not appear in the zsh
|
|
distribution, but can be created by linking tt(zed) to the name tt(fned)
|
|
in some directory in your tt(fpath).
|
|
)
|
|
findex(is-at-least)
|
|
item(tt(is-at-least) var(needed) [ var(present) ])(
|
|
Perform a greater-than-or-equal-to comparison of two strings having the
|
|
format of a zsh version number; that is, a string of numbers and text with
|
|
segments separated by dots or dashes. If the var(present) string is not
|
|
provided, tt($ZSH_VERSION) is used. Segments are paired left-to-right in
|
|
the two strings with leading non-number parts ignored. If one string has
|
|
fewer segments than the other, the missing segments are considered zero.
|
|
|
|
This is useful in startup files to set options and other state that are
|
|
not available in all versions of zsh.
|
|
|
|
example(is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
|
|
is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
|
|
is-at-least 2.6-17 || print "You can't use is-at-least here.")
|
|
)
|
|
findex(nslookup)
|
|
item(tt(nslookup) [ var(arg) ... ])(
|
|
This wrapper function for the tt(nslookup) command requires the
|
|
tt(zsh/zpty) module (see
|
|
ifzman(zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zpty Module))\
|
|
). It behaves exactly like the standard tt(nslookup)
|
|
except that it provides customizable prompts (including a right-side
|
|
prompt) and completion of nslookup commands, host names, etc. (if you use
|
|
the function-based completion system). Completion styles may be set with
|
|
the context prefix `tt(:completion:nslookup)'.
|
|
|
|
See also the tt(pager), tt(prompt) and tt(rprompt) styles below.
|
|
)
|
|
findex(regexp-replace)
|
|
item(tt(regexp-replace) var(var) var(regexp) var(replace))(
|
|
Use regular expressions to perform a global search and replace operation
|
|
on a variable. If the option tt(RE_MATCH_PCRE) is not set, POSIX
|
|
extended regular expressions are used, else Perl-compatible regular
|
|
expressions (this requires the shell to be linked against the tt(pcre)
|
|
library).
|
|
|
|
var(var) is the name of the variable containing the string to be matched.
|
|
The variable will be modified directly by the function. The
|
|
variables tt(MATCH), tt(MBEGIN), tt(MEND), tt(match), tt(mbegin), tt(mend)
|
|
should be avoided as these are used by the regular expression code.
|
|
|
|
var(regexp) is the regular expression to match against the string.
|
|
|
|
var(replace) is the replacement text. This can contain parameter, command
|
|
and arithmetic expressions which will be replaced: in particular, a
|
|
reference to tt($MATCH) will be replaced by the text matched by the pattern.
|
|
|
|
The return status is 0 if at least one match was performed, else 1.
|
|
)
|
|
findex(run-help)
|
|
item(tt(run-help) var(cmd))(
|
|
This function is designed to be invoked by the tt(run-help) ZLE widget,
|
|
in place of the default alias. See `Accessing On-Line Help'
|
|
ifzman(above)\
|
|
ifnzman((noderef(Utilities))) for setup instructions.
|
|
|
|
In the discussion which follows, if var(cmd) is a file system path, it is
|
|
first reduced to its rightmost component (the file name).
|
|
|
|
Help is first sought by looking for a file named var(cmd) in the directory
|
|
named by the tt(HELPDIR) parameter. If no file is found, an assistant
|
|
function, alias, or command named tt(run-help-var(cmd)) is sought. If
|
|
found, the assistant is executed with the rest of the current command line
|
|
(everything after the command name var(cmd)) as its arguments. When
|
|
neither file nor assistant is found, the external command
|
|
`tt(man) var(cmd)' is run.
|
|
|
|
An example assistant for the "ssh" command:
|
|
|
|
example(run-help-ssh+LPAR()RPAR() {
|
|
emulate -LR zsh
|
|
local -a args
|
|
# Delete the "-l username" option
|
|
zparseopts -D -E -a args l:
|
|
# Delete other options, leaving: host command
|
|
args=(${@:#-*})
|
|
if [[ ${#args} -lt 2 ]]; then
|
|
man ssh
|
|
else
|
|
run-help $args[2]
|
|
fi
|
|
})
|
|
|
|
Several of these assistants are provided in the tt(Functions/Misc)
|
|
directory. These must be autoloaded, or placed as executable scripts in
|
|
your search path, in order to be found and used by tt(run-help).
|
|
|
|
startitem()
|
|
findex(run-help-git)
|
|
findex(run-help-svk)
|
|
findex(run-help-svn)
|
|
xitem(tt(run-help-git))
|
|
xitem(tt(run-help-svk))
|
|
item(tt(run-help-svn))(
|
|
Assistant functions for the tt(git), tt(svk), and tt(svn) commands.
|
|
)
|
|
enditem()
|
|
)
|
|
item(tt(tetris))(
|
|
Zsh was once accused of not being as complete as Emacs,
|
|
because it lacked a Tetris game. This function was written to
|
|
refute this vicious slander.
|
|
|
|
This function must be used as a ZLE widget:
|
|
|
|
example(autoload -U tetris
|
|
zle -N tetris
|
|
bindkey var(keys) tetris)
|
|
|
|
To start a game, execute the widget by typing the var(keys). Whatever command
|
|
line you were editing disappears temporarily, and your keymap is also
|
|
temporarily replaced by the Tetris control keys. The previous editor state
|
|
is restored when you quit the game (by pressing `tt(q)') or when you lose.
|
|
|
|
If you quit in the middle of a game, the next invocation of the tt(tetris)
|
|
widget will continue where you left off. If you lost, it will start a new
|
|
game.
|
|
)
|
|
findex(zargs)
|
|
item(tt(zargs) [ var(option) ... tt(-)tt(-) ] [ var(input) ... ] [ tt(-)tt(-) var(command) [ var(arg) ... ] ])(
|
|
This function works like GNU xargs, except that instead of reading lines
|
|
of arguments from the standard input, it takes them from the command line.
|
|
This is useful because zsh, especially with recursive glob operators,
|
|
often can construct a command line for a shell function that is longer
|
|
than can be accepted by an external command.
|
|
|
|
The var(option) list represents options of the tt(zargs) command itself,
|
|
which are the same as those of tt(xargs). The var(input) list is the
|
|
collection of strings (often file names) that become the arguments of the
|
|
tt(command), analogous to the standard input of tt(xargs). Finally, the
|
|
var(arg) list consists of those arguments (usually options) that are
|
|
passed to the var(command) each time it runs. The var(arg) list precedes
|
|
the elements from the tt(input) list in each run. If no var(command) is
|
|
provided, then no var(arg) list may be provided, and in that event the
|
|
default command is `tt(print)' with arguments `tt(-r -)tt(-)'.
|
|
|
|
For example, to get a long tt(ls) listing of all plain files in the
|
|
current directory or its subdirectories:
|
|
|
|
example(autoload -U zargs
|
|
zargs -- **/*(.) -- ls -l)
|
|
|
|
Note that `tt(-)tt(-)' is used both to mark the end of the var(option)
|
|
list and to mark the end of the var(input) list, so it must appear twice
|
|
whenever the var(input) list may be empty. If there is guaranteed to be
|
|
at least one var(input) and the first var(input) does not begin with a
|
|
`tt(-)', then the first `tt(-)tt(-)' may be omitted.
|
|
|
|
In the event that the string `tt(-)tt(-)' is or may be an var(input), the
|
|
tt(-e) option may be used to change the end-of-inputs marker. Note that
|
|
this does em(not) change the end-of-options marker. For example, to use
|
|
`tt(..)' as the marker:
|
|
|
|
example(zargs -e.. -- **/*(.) .. ls -l)
|
|
|
|
This is a good choice in that example because no plain file can be named
|
|
`tt(..)', but the best end-marker depends on the circumstances.
|
|
|
|
For details of the other tt(zargs) options, see zmanref(xargs) or run
|
|
tt(zargs) with the tt(-)tt(-help) option.
|
|
)
|
|
findex(zed)
|
|
xitem(tt(zed) [ tt(-f) ] var(name))
|
|
item(tt(zed -b))(
|
|
This function uses the ZLE editor to edit a file or function.
|
|
|
|
Only one var(name) argument is allowed.
|
|
If the tt(-f) option is given, the name is taken to be that of
|
|
a function; if the function is marked for autoloading, tt(zed) searches
|
|
for it in the tt(fpath) and loads it. Note that functions edited this way
|
|
are installed into the current shell, but em(not) written back to the
|
|
autoload file.
|
|
|
|
Without tt(-f), var(name) is the path name of the file to edit, which need
|
|
not exist; it is created on write, if necessary.
|
|
|
|
While editing, the function sets the main keymap to tt(zed) and the
|
|
vi command keymap to tt(zed-vicmd). These will be copied from the existing
|
|
tt(main) and tt(vicmd) keymaps if they do not exist the first time tt(zed)
|
|
is run. They can be used to provide special key bindings used only in zed.
|
|
|
|
If it creates the keymap, tt(zed) rebinds the return key to insert a line
|
|
break and `tt(^X^W)' to accept the edit in the tt(zed) keymap, and binds
|
|
`tt(ZZ)' to accept the edit in the tt(zed-vicmd) keymap.
|
|
|
|
The bindings alone can be installed by running `tt(zed -b)'. This is
|
|
suitable for putting into a startup file. Note that, if rerun,
|
|
this will overwrite the existing tt(zed) and tt(zed-vicmd) keymaps.
|
|
|
|
Completion is available, and styles may be set with the context prefix
|
|
`tt(:completion:zed)'.
|
|
|
|
A zle widget tt(zed-set-file-name) is available. This can be called by
|
|
name from within zed using `tt(\ex zed-set-file-name)' (note, however, that
|
|
because of zed's rebindings you will have to type tt(^j) at the end instead
|
|
of the return key), or can be bound to a key in either of the tt(zed) or
|
|
tt(zed-vicmd) keymaps after `tt(zed -b)' has been run. When the widget is
|
|
called, it prompts for a new name for the file being edited. When zed
|
|
exits the file will be written under that name and the original file will
|
|
be left alone. The widget has no effect with `tt(zed -f)'.
|
|
|
|
While tt(zed-set-file-name) is running, zed uses the keymap
|
|
tt(zed-normal-keymap), which is linked from the main keymap in effect
|
|
at the time zed initialised its bindings. (This is to make the return key
|
|
operate normally.) The result is that if the main keymap has been changed,
|
|
the widget won't notice. This is not a concern for most users.
|
|
)
|
|
findex(zcp)
|
|
findex(zln)
|
|
xitem(tt(zcp) [ tt(-finqQvwW) ] var(srcpat) var(dest))
|
|
item(tt(zln) [ tt(-finqQsvwW) ] var(srcpat) var(dest))(
|
|
Same as tt(zmv -C) and tt(zmv -L), respectively. These functions do not
|
|
appear in the zsh distribution, but can be created by linking tt(zmv) to
|
|
the names tt(zcp) and tt(zln) in some directory in your tt(fpath).
|
|
)
|
|
item(tt(zkbd))(
|
|
See `Keyboard Definition'
|
|
ifzman(above)\
|
|
ifnzman((noderef(Utilities))).
|
|
)
|
|
findex(zmv)
|
|
item(tt(zmv) [ tt(-finqQsvwW) ] [ -C | -L | -M | -p var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )(
|
|
Move (usually, rename) files matching the pattern var(srcpat) to
|
|
corresponding files having names of the form given by var(dest), where
|
|
var(srcpat) contains parentheses surrounding patterns which will be
|
|
replaced in turn by $1, $2, ... in var(dest). For example,
|
|
|
|
example(zmv '(*).lis' '$1.txt')
|
|
|
|
renames `tt(foo.lis)' to `tt(foo.txt)', `tt(my.old.stuff.lis)' to
|
|
`tt(my.old.stuff.txt)', and so on.
|
|
|
|
The pattern is always treated as an tt(EXTENDED_GLOB) pattern. Any file
|
|
whose name is not changed by the substitution is simply ignored. Any
|
|
error (a substitution resulted in an empty string, two substitutions gave
|
|
the same result, the destination was an existing regular file and tt(-f)
|
|
was not given) causes the entire function to abort without doing anything.
|
|
|
|
Options:
|
|
|
|
startsitem()
|
|
sitem(tt(-f))(Force overwriting of destination files. Not currently
|
|
passed down to the tt(mv)/tt(cp)/tt(ln) command due to vagaries of
|
|
implementations (but you can use tt(-o-f) to do that).)
|
|
sitem(tt(-i))(Interactive: show each line to be executed and ask the user
|
|
whether to execute it. `Y' or `y' will execute it, anything else will
|
|
skip it. Note that you just need to type one character.)
|
|
sitem(tt(-n))(No execution: print what would happen, but don't do it.)
|
|
sitem(tt(-q))(Turn bare glob qualifiers off: now assumed by default, so
|
|
this has no effect.)
|
|
sitem(tt(-Q))(Force bare glob qualifiers on. Don't turn this on unless
|
|
you are actually using glob qualifiers in a pattern.)
|
|
sitem(tt(-s))(Symbolic, passed down to tt(ln); only works with tt(-L).)
|
|
sitem(tt(-v))(Verbose: print each command as it's being executed.)
|
|
sitem(tt(-w))(Pick out wildcard parts of the pattern, as described above,
|
|
and implicitly add parentheses for referring to them.)
|
|
sitem(tt(-W))(Just like tt(-w), with the addition of turning wildcards in
|
|
the replacement pattern into sequential ${1} .. ${N} references.)
|
|
sxitem(tt(-C))
|
|
sxitem(tt(-L))
|
|
sitem(tt(-M))(Force tt(cp), tt(ln) or tt(mv), respectively, regardless of
|
|
the name of the function.)
|
|
sitem(tt(-p) var(program))(Call var(program) instead of tt(cp), tt(ln) or
|
|
tt(mv). Whatever it does, it should at least understand the form
|
|
ifzman(`var(program) tt(-)tt(-) var(oldname) var(newname)')\
|
|
ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname)))
|
|
where var(oldname) and var(newname) are filenames generated by tt(zmv).)
|
|
sitem(tt(-o) var(optstring))(The var(optstring) is split into words and
|
|
passed down verbatim to the tt(cp), tt(ln) or tt(mv) command called to
|
|
perform the work. It should probably begin with a `tt(-)'.)
|
|
endsitem()
|
|
|
|
Further examples:
|
|
|
|
example(zmv -v '(* *)' '${1// /_}')
|
|
|
|
For any file in the current directory with at least one space in the name,
|
|
replace every space by an underscore and display the commands executed.
|
|
|
|
For more complete examples and other implementation details, see the
|
|
tt(zmv) source file, usually located in one of the directories named in
|
|
your tt(fpath), or in tt(Functions/Misc/zmv) in the zsh distribution.
|
|
)
|
|
item(tt(zrecompile))(
|
|
See `Recompiling Functions'
|
|
ifzman(above)\
|
|
ifnzman((noderef(Utilities))).
|
|
)
|
|
findex(zstyle+)
|
|
item(tt(zstyle+) var(context) var(style) var(value) [ + var(subcontext) var(style) var(value) ... ])(
|
|
This makes defining styles a bit simpler by using a single `tt(+)' as a
|
|
special token that allows you to append a context name to the previously
|
|
used context name. Like this:
|
|
|
|
example(zstyle+ ':foo:bar' style1 value1 \
|
|
+ ':baz' style2 value2 \
|
|
+ ':frob' style3 value3)
|
|
|
|
This defines `style1' with `value1' for the context tt(:foo:bar) as usual,
|
|
but it also defines `style2' with `value2' for the context
|
|
tt(:foo:bar:baz) and `style3' with `value3' for tt(:foo:bar:frob). Any
|
|
var(subcontext) may be the empty string to re-use the first context
|
|
unchanged.
|
|
)
|
|
enditem()
|
|
|
|
subsect(Styles)
|
|
|
|
startitem()
|
|
kindex(insert-tab, completion style)
|
|
item(tt(insert-tab))(
|
|
The tt(zed) function em(sets) this style in context `tt(:completion:zed:*)'
|
|
to turn off completion when tt(TAB) is typed at the beginning of a line.
|
|
You may override this by setting your own value for this context and style.
|
|
)
|
|
kindex(pager, nslookup style)
|
|
item(tt(pager))(
|
|
The tt(nslookup) function looks up this style in the context
|
|
`tt(:nslookup)' to determine the program used to display output that does
|
|
not fit on a single screen.
|
|
)
|
|
kindex(prompt, nslookup style)
|
|
kindex(rprompt, nslookup style)
|
|
xitem(tt(prompt))
|
|
item(tt(rprompt))(
|
|
The tt(nslookup) function looks up this style in the context
|
|
`tt(:nslookup)' to set the prompt and the right-side prompt, respectively.
|
|
The usual expansions for the tt(PS1) and tt(RPS1) parameters may be used
|
|
(see
|
|
ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
|
|
ifnzman(noderef(Prompt Expansion))\
|
|
).
|
|
)
|
|
enditem()
|