mirror of
git://git.code.sf.net/p/zsh/code
synced 2024-05-06 23:56:16 +02:00
b110d6d5af
The example code is a reduced version of my function from workers/47519, with one bug fixed. (In workers/47519, if $1 doesn't contain spaces - which is the case under hg mq - then $H and $s will be set to the same value.) Tweaked: Extended the contrib.yo hunk with details about mq.
4698 lines
198 KiB
Plaintext
4698 lines
198 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(Recent Directories)
|
|
menu(Other Directory Functions)
|
|
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)(Recent Directories)()(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.
|
|
|
|
Help files are installed by default to a subdirectory of tt(/usr/share/zsh)
|
|
or tt(/usr/local/share/zsh).
|
|
|
|
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
|
|
perl ~/zsh-version()/Util/helpfiles ~/zsh_help)
|
|
|
|
vindex(HELPDIR)
|
|
The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
|
|
files. When unset, it uses the default installation path.
|
|
To use your own set of help files, set this to the appropriate path
|
|
in one of your startup files:
|
|
|
|
example(HELPDIR=~/zsh_help)
|
|
|
|
findex(run-help, use of)
|
|
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)
|
|
|
|
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(arg) ... [ tt(-)tt(-) var(arg) ... ])(
|
|
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(arg)s 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 tt(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) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] 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 automatically called at specific points 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), tt(preexec),
|
|
tt(zshaddhistory), tt(zshexit), or tt(zsh_directory_name),
|
|
the special functions in question. Note that tt(zsh_directory_name)
|
|
is called in a different way from the other functions, but may
|
|
still be manipulated as a hook.
|
|
|
|
var(function) 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.
|
|
Functions are invoked in the order they were added.
|
|
|
|
If the option tt(-L) is given, the current values for the hook arrays
|
|
are listed with tt(typeset).
|
|
|
|
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.
|
|
|
|
The options tt(-U), tt(-z) and tt(-k) are passed as arguments to
|
|
tt(autoload) for var(function). For functions contributed with zsh, the
|
|
options tt(-Uz) are appropriate.
|
|
)
|
|
findex(add-zle-hook-widget)
|
|
item(tt(add-zle-hook-widget) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(widgetname))(
|
|
Several widget names are special to the line editor, as described in the section
|
|
ifnzman(Special Widgets, noderef(Zle Widgets))\
|
|
ifzman(Special Widgets, see zmanref(zshzle)),
|
|
in that they are automatically called at specific points during editing.
|
|
Unlike function hooks, these do not use a predefined array of other names
|
|
to call at the same point; the shell function tt(add-zle-hook-widget)
|
|
maintains a similar array and arranges for the special widget to invoke
|
|
those additional widgets.
|
|
|
|
var(hook) is one of tt(isearch-exit), tt(isearch-update),
|
|
tt(line-pre-redraw), tt(line-init), tt(line-finish), tt(history-line-set),
|
|
or tt(keymap-select), corresponding to each of the special widgets
|
|
tt(zle-isearch-exit), etc. The special widget names are also accepted
|
|
as the var(hook) argument.
|
|
|
|
var(widgetname) is the name of a ZLE widget. If no options are given this
|
|
is added to the array of widgets to be invoked in the given hook context.
|
|
Widgets are invoked in the order they were added, with
|
|
example(tt(zle )var(widgetname)tt( -Nw -f "nolast" -- "$@"))
|
|
|
|
vindex(WIDGET, in hooks)
|
|
Note that this means that the `tt(WIDGET)' special parameter tracks the
|
|
var(widgetname) when the widget function is called, rather than tracking
|
|
the name of the corresponding special hook widget.
|
|
|
|
If the option tt(-d) is given, the var(widgetname) is removed from
|
|
the array of widgets to be executed.
|
|
|
|
If the option tt(-D) is given, the var(widgetname) is treated as a pattern
|
|
and any matching names of widgets are removed from the array.
|
|
|
|
If var(widgetname) does not name an existing widget when added to the
|
|
array, it is assumed that a shell function also named var(widgetname) is
|
|
meant to provide the implementation of the widget. This name is therefore
|
|
marked for autoloading, and the options tt(-U), tt(-z) and tt(-k) are
|
|
passed as arguments to tt(autoload) as with tt(add-zsh-hook). The
|
|
widget is also created with `tt(zle -N )var(widgetname)' to cause the
|
|
corresponding function to be loaded the first time the hook is called.
|
|
|
|
The arrays of var(widgetname) are currently maintained in tt(zstyle)
|
|
contexts, one for each var(hook) context, with a style of `tt(widgets)'.
|
|
If the tt(-L) option is given, this set of styles is listed with
|
|
`tt(zstyle -L)'. This implementation may change, and the special widgets
|
|
that refer to the styles are created only if tt(add-zle-hook-widget) is
|
|
called to add at least one widget, so if this function is used for any
|
|
hooks, then all hooks should be managed only via this function.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Recent Directories)(Other Directory Functions)(Utilities)(User Contributions)
|
|
cindex(recent directories, maintaining list of)
|
|
cindex(directories, maintaining list of recent)
|
|
findex(cdr)
|
|
findex(_cdr)
|
|
findex(chpwd_recent_add)
|
|
findex(chpwd_recent_dirs)
|
|
findex(chpwd_recent_filehandler)
|
|
sect(Remembering Recent Directories)
|
|
|
|
The function tt(cdr) allows you to change the working directory to a
|
|
previous working directory from a list maintained automatically. It is
|
|
similar in concept to the directory stack controlled by the tt(pushd),
|
|
tt(popd) and tt(dirs) builtins, but is more configurable, and as it stores
|
|
all entries in files it is maintained across sessions and (by default)
|
|
between terminal emulators in the current session. Duplicates are
|
|
automatically removed, so that the list reflects the single most recent
|
|
use of each directory.
|
|
|
|
Note that the tt(pushd) directory stack is not actually modified or used
|
|
by tt(cdr) unless you configure it to do so as described in the
|
|
configuration section below.
|
|
|
|
subsect(Installation)
|
|
|
|
The system works by means of a hook function that is called every time the
|
|
directory changes. To install the system, autoload the required functions
|
|
and use the tt(add-zsh-hook) function described above:
|
|
|
|
example(autoload -Uz chpwd_recent_dirs cdr add-zsh-hook
|
|
add-zsh-hook chpwd chpwd_recent_dirs)
|
|
|
|
Now every time you change directly interactively, no matter which
|
|
command you use, the directory to which you change will be remembered
|
|
in most-recent-first order.
|
|
|
|
subsect(Use)
|
|
|
|
All direct user interaction is via the tt(cdr) function.
|
|
|
|
The argument to cdr is a number var(N) corresponding to the var(N)th most
|
|
recently changed-to directory. 1 is the immediately preceding directory;
|
|
the current directory is remembered but is not offered as a destination.
|
|
Note that if you have multiple windows open 1 may refer to a directory
|
|
changed to in another window; you can avoid this by having per-terminal
|
|
files for storing directory as described for the
|
|
tt(recent-dirs-file) style below.
|
|
|
|
If you set the tt(recent-dirs-default) style described below tt(cdr)
|
|
will behave the same as tt(cd) if given a non-numeric argument, or more
|
|
than one argument. The recent directory list is updated just the same
|
|
however you change directory.
|
|
|
|
If the argument is omitted, 1 is assumed. This is similar to tt(pushd)'s
|
|
behaviour of swapping the two most recent directories on the stack.
|
|
|
|
Completion for the argument to tt(cdr) is available if compinit has been
|
|
run; menu selection is recommended, using:
|
|
|
|
example(zstyle ':completion:*:*:cdr:*:*' menu selection)
|
|
|
|
to allow you to cycle through recent directories; the order is preserved,
|
|
so the first choice is the most recent directory before the current one.
|
|
The verbose style is also recommended to ensure the directory is shown; this
|
|
style is on by default so no action is required unless you have changed it.
|
|
|
|
subsect(Options)
|
|
|
|
The behaviour of tt(cdr) may be modified by the following options.
|
|
|
|
startitem()
|
|
item(tt(-l))(
|
|
lists the numbers and the corresponding directories in
|
|
abbreviated form (i.e. with tt(~) substitution reapplied), one per line.
|
|
The directories here are not quoted (this would only be an issue if a
|
|
directory name contained a newline). This is used by the completion
|
|
system.
|
|
)
|
|
item(tt(-r))(
|
|
sets the variable tt(reply) to the current set of directories. Nothing
|
|
is printed and the directory is not changed.
|
|
)
|
|
item(tt(-e))(
|
|
allows you to edit the list of directories, one per line. The
|
|
list can be edited to any extent you like; no sanity checking is
|
|
performed. Completion is available. No quoting is necessary (except for
|
|
newlines, where I have in any case no sympathy); directories are in
|
|
unabbreviated form and contain an absolute path, i.e. they start with tt(/).
|
|
Usually the first entry should be left as the current directory.
|
|
)
|
|
item(tt(-p ')var(pattern)tt('))(
|
|
Prunes any items in the directory list that match the given extended glob
|
|
pattern; the pattern needs to be quoted from immediate expansion on the
|
|
command line. The pattern is matched against each completely expanded
|
|
file name in the list; the full string must match, so wildcards at the
|
|
end (e.g. tt('*removeme*')) are needed to remove entries with a given
|
|
substring.
|
|
|
|
If output is to a terminal, then the function will print the new list
|
|
after pruning and prompt for confirmation by the user. This output and
|
|
confirmation step can be skipped by using tt(-P) instead of tt(-p).
|
|
)
|
|
enditem()
|
|
|
|
subsect(Configuration)
|
|
|
|
Configuration is by means of the styles mechanism that should be familiar
|
|
from completion; if not, see the description of the tt(zstyle) command in
|
|
ifzman(see zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zutil Module)). The context for setting styles
|
|
should be tt(':chpwd:*') in case the meaning of the context is extended in
|
|
future, for example:
|
|
|
|
example(zstyle ':chpwd:*' recent-dirs-max 0)
|
|
|
|
sets the value of the tt(recent-dirs-max) style to 0. In practice the
|
|
style name is specific enough that a context of '*' should be fine.
|
|
|
|
An exception is tt(recent-dirs-insert), which is used exclusively by the
|
|
completion system and so has the usual completion system context
|
|
(tt(':completion:*') if nothing more specific is needed), though again
|
|
tt('*') should be fine in practice.
|
|
|
|
startitem()
|
|
item(tt(recent-dirs-default))(
|
|
If true, and the command is expecting a recent directory index, and
|
|
either there is more than one argument or the argument is not an
|
|
integer, then fall through to "cd". This allows the lazy to use only
|
|
one command for directory changing. Completion recognises this, too;
|
|
see recent-dirs-insert for how to control completion when this option
|
|
is in use.
|
|
)
|
|
item(tt(recent-dirs-file))(
|
|
The file where the list of directories is saved. The default
|
|
is tt(${ZDOTDIR:-$HOME}/.chpwd-recent-dirs), i.e. this is in your
|
|
home directory unless you have set the variable tt(ZDOTDIR) to point
|
|
somewhere else. Directory names are saved in tt($')var(...)tt(') quoted
|
|
form, so each line in the file can be supplied directly to the shell as an
|
|
argument.
|
|
|
|
The value of this style may be an array. In this case, the first
|
|
file in the list will always be used for saving directories while any
|
|
other files are left untouched. When reading the recent directory
|
|
list, if there are fewer than the maximum number of entries in the
|
|
first file, the contents of later files in the array will be appended
|
|
with duplicates removed from the list shown. The contents of the two
|
|
files are not sorted together, i.e. all the entries in the first file
|
|
are shown first. The special value tt(+) can appear in the list to
|
|
indicate the default file should be read at that point. This allows
|
|
effects like the following:
|
|
|
|
example(zstyle ':chpwd:*' recent-dirs-file \
|
|
~/.chpwd-recent-dirs-${TTY##*/} +)
|
|
|
|
Recent directories are read from a file numbered according to
|
|
the terminal. If there are insufficient entries the list
|
|
is supplemented from the default file.
|
|
|
|
It is possible to use tt(zstyle -e) to make the directory configurable
|
|
at run time:
|
|
|
|
example(zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file
|
|
pick-recent-dirs-file+LPAR()RPAR() {
|
|
if [[ $PWD = ~/text/writing+LPAR()|/*RPAR() ]]; then
|
|
reply=(~/.chpwd-recent-dirs-writing)
|
|
else
|
|
reply=(+)
|
|
fi
|
|
})
|
|
|
|
In this example, if the current directory is tt(~/text/writing) or a
|
|
directory under it, then use a special file for saving recent
|
|
directories, else use the default.
|
|
)
|
|
item(tt(recent-dirs-insert))(
|
|
Used by completion. If tt(recent-dirs-default) is true, then setting
|
|
this to tt(true) causes the actual directory, rather than its index, to
|
|
be inserted on the command line; this has the same effect as using
|
|
the corresponding index, but makes the history clearer and the line
|
|
easier to edit. With this setting, if part of an argument was
|
|
already typed, normal directory completion rather than recent
|
|
directory completion is done; this is because recent directory
|
|
completion is expected to be done by cycling through entries menu
|
|
fashion.
|
|
|
|
If the value of the style is tt(always), then only recent directories will
|
|
be completed; in that case, use the tt(cd) command when you want to
|
|
complete other directories.
|
|
|
|
If the value is tt(fallback), recent directories will be tried first, then
|
|
normal directory completion is performed if recent directory completion
|
|
failed to find a match.
|
|
|
|
Finally, if the value is tt(both) then both sets of completions are
|
|
presented; the usual tag mechanism can be used to distinguish results, with
|
|
recent directories tagged as tt(recent-dirs). Note that the recent
|
|
directories inserted are abbreviated with directory names where appropriate.
|
|
)
|
|
item(tt(recent-dirs-max))(
|
|
The maximum number of directories to save to the file. If
|
|
this is zero or negative there is no maximum. The default is 20.
|
|
Note this includes the current directory, which isn't offered,
|
|
so the highest number of directories you will be offered
|
|
is one less than the maximum.
|
|
)
|
|
item(tt(recent-dirs-prune))(
|
|
This style is an array determining what directories should (or should
|
|
not) be added to the recent list. Elements of the array can include:
|
|
|
|
startitem()
|
|
item(tt(parent))(
|
|
Prune parents (more accurately, ancestors) from the recent list.
|
|
If present, changing directly down by any number of directories
|
|
causes the current directory to be overwritten. For example,
|
|
changing from ~pws to ~pws/some/other/dir causes ~pws not to be
|
|
left on the recent directory stack. This only applies to direct
|
|
changes to descendant directories; earlier directories on the
|
|
list are not pruned. For example, changing from ~pws/yet/another
|
|
to ~pws/some/other/dir does not cause ~pws to be pruned.
|
|
)
|
|
item(tt(pattern:)var(pattern))(
|
|
Gives a zsh pattern for directories that should not be
|
|
added to the recent list (if not already there). This element
|
|
can be repeated to add different patterns. For example,
|
|
tt('pattern:/tmp+LPAR()|/*RPAR()') stops tt(/tmp) or its descendants
|
|
from being added. The tt(EXTENDED_GLOB) option is always turned on
|
|
for these patterns.
|
|
)
|
|
enditem()
|
|
)
|
|
item(tt(recent-dirs-pushd))(
|
|
If set to true, tt(cdr) will use tt(pushd) instead of tt(cd) to change the
|
|
directory, so the directory is saved on the directory stack. As the
|
|
directory stack is completely separate from the list of files saved
|
|
by the mechanism used in this file there is no obvious reason to do
|
|
this.
|
|
)
|
|
enditem()
|
|
|
|
subsect(Use with dynamic directory naming)
|
|
|
|
It is possible to refer to recent directories using the dynamic directory
|
|
name syntax by using the supplied function tt(zsh_directory_name_cdr)
|
|
a hook:
|
|
|
|
example(autoload -Uz add-zsh-hook
|
|
add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr)
|
|
|
|
When this is done, tt(~[1]) will refer to the most recent
|
|
directory other than $PWD, and so on. Completion after tt(~[)var(...)
|
|
also works.
|
|
|
|
subsect(Details of directory handling)
|
|
|
|
This section is for the curious or confused; most users will not
|
|
need to know this information.
|
|
|
|
Recent directories are saved to a file immediately and hence are
|
|
preserved across sessions. Note currently no file locking is applied:
|
|
the list is updated immediately on interactive commands and nowhere else
|
|
(unlike history), and it is assumed you are only going to change
|
|
directory in one window at once. This is not safe on shared accounts,
|
|
but in any case the system has limited utility when someone else is
|
|
changing to a different set of directories behind your back.
|
|
|
|
To make this a little safer, only directory changes instituted from the
|
|
command line, either directly or indirectly through shell function calls
|
|
(but not through subshells, evals, traps, completion functions and the
|
|
like) are saved. Shell functions should use tt(cd -q) or tt(pushd -q) to
|
|
avoid side effects if the change to the directory is to be invisible at the
|
|
command line. See the contents of the function tt(chpwd_recent_dirs) for
|
|
more details.
|
|
|
|
texinode(Other Directory Functions)(Version Control Information)(Recent Directories)(User Contributions)
|
|
cindex(directories, named, dynamic, helper function)
|
|
cindex(dynamic directory naming, helper function)
|
|
cindex(named directories, dynamic, helper function)
|
|
findex(zsh_directory_name_generic)
|
|
sect(Abbreviated dynamic references to directories)
|
|
|
|
The dynamic directory naming system is described in the subsection
|
|
em(Dynamic named directories) of
|
|
ifzman(the section em(Filename Expansion) in zmanref(zshexpn))\
|
|
ifnzman(noderef(Filename Expansion)). In this, a reference to
|
|
tt(~[)var(...)tt(]) is expanded by a function found by the hooks
|
|
mechanism.
|
|
|
|
The contributed function tt(zsh_directory_name_generic) provides a
|
|
system allowing the user to refer to directories with only a limited
|
|
amount of new code. It supports all three of the standard interfaces
|
|
for directory naming: converting from a name to a directory, converting
|
|
in the reverse direction to find a short name, and completion of names.
|
|
|
|
The main feature of this function is a path-like syntax,
|
|
combining abbreviations at multiple levels separated by ":".
|
|
As an example, ~[g:p:s] might specify:
|
|
startitem()
|
|
item(tt(g))(
|
|
The top level directory for your git area. This first component
|
|
has to match, or the function will return indicating another
|
|
directory name hook function should be tried.
|
|
)
|
|
item(tt(p))(
|
|
The name of a project within your git area.
|
|
)
|
|
item(tt(s))(
|
|
The source area within that project.
|
|
)
|
|
enditem()
|
|
This allows you to collapse references to long hierarchies to a very
|
|
compact form, particularly if the hierarchies are similar across different
|
|
areas of the disk.
|
|
|
|
Name components may be completed: if a description is shown at the top
|
|
of the list of completions, it includes the path to which previous
|
|
components expand, while the description for an individual completion
|
|
shows the path segment it would add. No additional configuration is
|
|
needed for this as the completion system is aware of the dynamic
|
|
directory name mechanism.
|
|
|
|
subsect(Usage)
|
|
|
|
To use the function, first define a wrapper function for your specific
|
|
case. We'll assume it's to be autoloaded. This can have any name but
|
|
we'll refer to it as zdn_mywrapper. This wrapper function will define
|
|
various variables and then call this function with the same arguments
|
|
that the wrapper function gets. This configuration is described below.
|
|
|
|
Then arrange for the wrapper to be run as a zsh_directory_name hook:
|
|
|
|
example(autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper
|
|
add-zsh-hook -U zsh_directory_name zdn_mywrapper)
|
|
|
|
subsect(Configuration)
|
|
|
|
The wrapper function should define a local associative array zdn_top.
|
|
Alternatively, this can be set with a style called tt(mapping). The
|
|
context for the style is tt(:zdn:)var(wrapper-name) where
|
|
var(wrapper-name) is the function calling zsh_directory_name_generic;
|
|
for example:
|
|
|
|
example(zstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top)
|
|
|
|
The keys in this associative array correspond to the first component of
|
|
the name. The values are matching directories. They may have an
|
|
optional suffix with a slash followed by a colon and the name of a
|
|
variable in the same format to give the next component. (The slash
|
|
before the colon is to disambiguate the case where a colon is needed in
|
|
the path for a drive. There is otherwise no syntax for escaping this,
|
|
so path components whose names start with a colon are not supported.) A
|
|
special component tt(:default:) specifies a variable in the form
|
|
tt(/:)var(var) (the path section is ignored and so is usually empty)
|
|
that will be used for the next component if no variable is given for the
|
|
path. Variables referred to within tt(zdn_top) have the same format as
|
|
tt(zdn_top) itself, but contain relative paths.
|
|
|
|
For example,
|
|
|
|
example(local -A zdn_top=(
|
|
g ~/git
|
|
ga ~/alternate/git
|
|
gs /scratch/$USER/git/:second2
|
|
:default: /:second1
|
|
))
|
|
|
|
This specifies the behaviour of a directory referred to as tt(~[g:...])
|
|
or tt(~[ga:...]) or tt(~[gs:...]). Later path components are optional;
|
|
in that case tt(~[g]) expands to tt(~/git), and so on. tt(gs) expands
|
|
to tt(/scratch/$USER/git) and uses the associative array tt(second2) to
|
|
match the second component; tt(g) and tt(ga) use the associative array
|
|
tt(second1) to match the second component.
|
|
|
|
When expanding a name to a directory, if the first component is not tt(g) or
|
|
tt(ga) or tt(gs), it is not an error; the function simply returns 1 so that a
|
|
later hook function can be tried. However, matching the first component
|
|
commits the function, so if a later component does not match, an error
|
|
is printed (though this still does not stop later hooks from being
|
|
executed).
|
|
|
|
For components after the first, a relative path is expected, but note that
|
|
multiple levels may still appear. Here is an example of tt(second1):
|
|
|
|
example(local -A second1=(
|
|
p myproject
|
|
s somproject
|
|
os otherproject/subproject/:third
|
|
))
|
|
|
|
The path as found from tt(zdn_top) is extended with the matching
|
|
directory, so tt(~[g:p]) becomes tt(~/git/myproject). The slash between
|
|
is added automatically (it's not possible to have a later component
|
|
modify the name of a directory already matched). Only tt(os) specifies
|
|
a variable for a third component, and there's no tt(:default:), so it's
|
|
an error to use a name like tt(~[g:p:x]) or tt(~[ga:s:y]) because
|
|
there's nowhere to look up the tt(x) or tt(y).
|
|
|
|
The associative arrays need to be visible within this function; the
|
|
generic function therefore uses internal variable names beginning
|
|
tt(_zdn_) in order to avoid clashes. Note that the variable tt(reply)
|
|
needs to be passed back to the shell, so should not be local in the
|
|
calling function.
|
|
|
|
The function does not test whether directories assembled by component
|
|
actually exist; this allows the system to work across automounted
|
|
file systems. The error from the command trying to use a non-existent
|
|
directory should be sufficient to indicate the problem.
|
|
|
|
subsect(Complete example)
|
|
|
|
Here is a full fictitious but usable autoloadable definition of the
|
|
example function defined by the code above. So tt(~[gs:p:s]) expands
|
|
to tt(/scratch/$USER/git/myscratchproject/top/srcdir) (with tt($USER)
|
|
also expanded).
|
|
|
|
example(local -A zdn_top=(
|
|
g ~/git
|
|
ga ~/alternate/git
|
|
gs /scratch/$USER/git/:second2
|
|
:default: /:second1
|
|
)
|
|
|
|
local -A second1=(
|
|
p myproject
|
|
s somproject
|
|
os otherproject/subproject/:third
|
|
)
|
|
|
|
local -A second2=(
|
|
p myscratchproject
|
|
s somescratchproject
|
|
)
|
|
|
|
local -A third=(
|
|
s top/srcdir
|
|
d top/documentation
|
|
)
|
|
|
|
# autoload not needed if you did this at initialisation...
|
|
autoload -Uz zsh_directory_name_generic
|
|
zsh_directory_name_generic "$@)
|
|
|
|
It is also possible to use global associative arrays, suitably named,
|
|
and set the style for the context of your wrapper function to
|
|
refer to this. Then your set up code would contain the following:
|
|
|
|
example(typeset -A zdn_mywrapper_top=(...)
|
|
# ... and so on for other associative arrays ...
|
|
zstyle ':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top
|
|
autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper
|
|
add-zsh-hook -U zsh_directory_name zdn_mywrapper)
|
|
|
|
and the function tt(zdn_mywrapper) would contain only the following:
|
|
|
|
example(zsh_directory_name_generic "$@")
|
|
|
|
texinode(Version Control Information)(Prompt Themes)(Other Directory Functions)(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)))(uref(https://bazaar.canonical.com/))
|
|
sitem(Codeville (tt(cdv)))(uref(http://freecode.com/projects/codeville/))
|
|
sitem(Concurrent Versioning System (tt(cvs)))(uref(https://www.nongnu.org/cvs/))
|
|
sitem(Darcs (tt(darcs)))(uref(http://darcs.net/))
|
|
sitem(Fossil (tt(fossil)))(uref(https://fossil-scm.org/))
|
|
sitem(Git (tt(git)))(uref(https://git-scm.com/))
|
|
sitem(GNU arch (tt(tla)))(uref(https://www.gnu.org/software/gnu-arch/))
|
|
sitem(Mercurial (tt(hg)))(uref(https://www.mercurial-scm.org/))
|
|
sitem(Monotone (tt(mtn)))(uref(https://monotone.ca/))
|
|
sitem(Perforce (tt(p4)))(uref(https://www.perforce.com/))
|
|
sitem(Subversion (tt(svn)))(uref(https://subversion.apache.org/))
|
|
sitem(SVK (tt(svk)))(uref(https://svk.bestpractical.com/))
|
|
endsitem()
|
|
|
|
There is also support for the patch management system tt(quilt)
|
|
(uref(https://savannah.nongnu.org/projects/quilt)). See
|
|
ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support))
|
|
below for details.
|
|
|
|
To load tt(vcs_info):
|
|
|
|
example(autoload -Uz vcs_info)
|
|
|
|
It can be used in any existing prompt, because it does not require any
|
|
specific tt($psvar) entries to be available.
|
|
|
|
startmenu()
|
|
menu(vcs_info Quickstart)
|
|
menu(vcs_info Configuration)
|
|
menu(vcs_info Oddities)
|
|
menu(vcs_info Quilt Support)
|
|
menu(vcs_info API)
|
|
menu(vcs_info Variables)
|
|
menu(vcs_info Hooks)
|
|
menu(vcs_info Examples)
|
|
endmenu()
|
|
|
|
texinode(vcs_info Quickstart)(vcs_info Configuration)()(Version Control Information)
|
|
subsect(Quickstart)
|
|
|
|
To get this feature working quickly (including colors), you can do the
|
|
following (assuming, you loaded tt(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 tt(vcs_info) from your tt(precmd) function. Once that is done you need
|
|
a em(single quoted) tt('${vcs_info_msg_0_}') in your prompt.
|
|
|
|
To be able to use tt('${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
|
|
fossil
|
|
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 tt(disable) style (or backends not in the
|
|
tt(enable) style - if you used that) marked as disabled by a hash sign.
|
|
That means the detection of these systems is skipped em(completely). No
|
|
wasted time there.
|
|
|
|
|
|
texinode(vcs_info Configuration)(vcs_info Oddities)(vcs_info Quickstart)(Version Control Information)
|
|
subsect(Configuration)
|
|
|
|
The tt(vcs_info) feature can be configured via tt(zstyle).
|
|
|
|
First, the context in which we are working:
|
|
example(:vcs_info:var(vcs-string):var(user-context):var(repo-root-name))
|
|
|
|
startitem()
|
|
item(var(vcs-string))(
|
|
is one of: tt(git), tt(git-svn), tt(git-p4), tt(hg), tt(hg-git),
|
|
tt(hg-hgsubversion), tt(hg-hgsvn), tt(darcs), tt(bzr), tt(cdv), tt(mtn),
|
|
tt(svn), tt(cvs), tt(svk), tt(tla), tt(p4) or tt(fossil).
|
|
This is followed by `tt(.quilt-)var(quilt-mode)' in Quilt mode
|
|
(see ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details)
|
|
and by `tt(+)var(hook-name)' while hooks are active
|
|
(see ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) for details).
|
|
|
|
COMMENT(users/20807)
|
|
Currently, hooks in quilt mode don't add the `tt(.quilt-)var(quilt-mode)' information.
|
|
This may change in the future.
|
|
)
|
|
item(var(user-context))(
|
|
is a freely configurable string, assignable by
|
|
the user as the first argument to tt(vcs_info) (see its description
|
|
below).
|
|
)
|
|
item(var(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 tt(/usr/src/zsh),
|
|
with that being a CVS checkout, you can set var(repo-root-name) to
|
|
tt(zsh) to make it so.
|
|
)
|
|
enditem()
|
|
|
|
There are three special values for var(vcs-string): The first is named
|
|
tt(-init-), that is in effect as long as there was no decision what VCS
|
|
backend to use. The second is tt(-preinit-); it is used em(before)
|
|
tt(vcs_info) is run, when initializing the data exporting variables. The
|
|
third special value is tt(formats) and is used by the tt(vcs_info_lastmsg)
|
|
for looking up its styles.
|
|
|
|
The initial value of var(repo-root-name) is tt(-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 tt(formats), tt(actionformats) or
|
|
tt(branchformat) styles, as it is guaranteed that var(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 var(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 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 tt(%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 set when we didn't detect a version control system
|
|
for the current directory or tt(vcs_info) was disabled. This is useful if
|
|
you want tt(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 tt(branchformat)) to include either or both. It's only
|
|
useful when tt(get-revision) is true. Note, the full 40-character revision id
|
|
is not available (except when using the tt(use-simple) option) because
|
|
executing hg more than once per prompt is too slow; you may customize this
|
|
behavior using hooks.
|
|
)
|
|
kindex(max-exports)
|
|
item(tt(max-exports))(
|
|
Defines the maximum number of
|
|
tt(vcs_info_msg_*_) variables tt(vcs_info) will set.
|
|
)
|
|
kindex(enable)
|
|
item(tt(enable))(
|
|
A list of backends you want to use. Checked in the tt(-init-) context. If
|
|
this list contains an item called tt(NONE) no backend is used at all and
|
|
tt(vcs_info) will do nothing. If this list contains tt(ALL), tt(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 tt(vcs_info) to test for
|
|
repositories (checked in the tt(-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, tt(vcs_info) will be disabled. This style is checked in the
|
|
tt(:vcs_info:-init-:*:-all-) context.
|
|
|
|
Say, tt(~/.zsh) is a directory under version control, in which you do
|
|
not want tt(vcs_info) to be active, do:
|
|
example(zstyle ':vcs_info:*' disable-patterns "${+LPAR()b+RPAR()HOME}/.zsh+LPAR()|/*+RPAR()")
|
|
)
|
|
kindex(use-quilt)
|
|
item(tt(use-quilt))(
|
|
If enabled, the tt(quilt) support code is active in `addon' mode.
|
|
See ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info 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 ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details.
|
|
)
|
|
kindex(quilt-patch-dir)
|
|
item(tt(quilt-patch-dir))(
|
|
Overwrite the value of the tt($QUILT_PATCHES) environment variable. See
|
|
ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info 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 tt(stagedstr) and tt(unstagedstr)
|
|
styles. The only backends that currently support this option are tt(git),
|
|
tt(hg), and tt(bzr) (the latter two only support unstaged).
|
|
|
|
For this style to be evaluated with the tt(hg) backend, the tt(get-revision)
|
|
style needs to be set and the tt(use-simple) style needs to be unset. The
|
|
latter is the default; the former is not.
|
|
|
|
With the tt(bzr) backend, em(lightweight checkouts) only honor this style if
|
|
the tt(use-server) style is set.
|
|
|
|
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(check-for-staged-changes)
|
|
item(tt(check-for-staged-changes))(
|
|
This style is like tt(check-for-changes), but it never checks the worktree
|
|
files, only the metadata in the tt(.${vcs}) dir. Therefore,
|
|
this style initializes only the tt(%c) escape (with tt(stagedstr)) but
|
|
not the tt(%u) escape. This style is faster than tt(check-for-changes).
|
|
|
|
In the tt(git) backend, this style checks for changes in the index.
|
|
Other backends do not currently implement this style.
|
|
|
|
This style 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 tt(vcs_info) to use the supplied string as the command
|
|
to use as the VCS's binary. Note, that setting this in 'tt(: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. tt(svn) is used in an tt(svn)
|
|
repository).
|
|
|
|
The tt(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, tt(git) is installed in /usr/bin but
|
|
your sysadmin installed a newer version in /usr/local/bin. 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 tt(host)tt(:)tt(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.
|
|
|
|
The Bazaar backend (tt(bzr)) uses this to permit contacting the server
|
|
about lightweight checkouts, see the tt(check-for-changes) style.
|
|
)
|
|
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), tt(hg), and tt(git) 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.
|
|
|
|
The default is to generate a comma-separated list of all bookmark names
|
|
that refer to the currently checked out revision. If a bookmark is active,
|
|
its name is suffixed an asterisk and placed first in the list.
|
|
)
|
|
kindex(use-prompt-escapes)
|
|
item(tt(use-prompt-escapes))(
|
|
Determines if we assume that the assembled
|
|
string from tt(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 tt(vcs_info)'s hooks system.
|
|
)
|
|
kindex(hooks)
|
|
item(tt(hooks))(
|
|
A list style that defines hook-function names. See ifzman(bf(Hooks in vcs_info))\
|
|
ifnzman(noderef(vcs_info Hooks))
|
|
below for details.
|
|
)
|
|
kindex(patch-format)
|
|
kindex(nopatch-format)
|
|
xitem(tt(patch-format))
|
|
item(tt(nopatch-format))(
|
|
This pair of styles format the patch information used by the tt(%m) expando in
|
|
formats and actionformats for the tt(git) and tt(hg) backends. The value is
|
|
subject to certain tt(%)-expansions described below.
|
|
The expanded value is made available in the global tt(backend_misc) array as
|
|
tt(${backend_misc[patches]}) (also if a tt(set-patch-format) hook is used).
|
|
)
|
|
kindex(get-unapplied)
|
|
item(tt(get-unapplied))(
|
|
This boolean style controls whether a backend should attempt to gather a list
|
|
of unapplied patches (for example with Mercurial Queue patches).
|
|
|
|
Used by the tt(quilt), tt(hg), and tt(git) backends.
|
|
)
|
|
enditem()
|
|
|
|
The default values for these styles in all contexts are:
|
|
|
|
startsitem()
|
|
sitem(tt(formats))(" (%s)-[%b]%u%c-")
|
|
sitem(tt(actionformats))(" (%s)-[%b|%a]%u%c-")
|
|
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(check-for-staged-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 tt($QUILT_PATCHES))
|
|
sitem(tt(quiltcommand))(quilt)
|
|
sitem(tt(patch-format))(var(backend dependent))
|
|
sitem(tt(nopatch-format))(var(backend dependent))
|
|
sitem(tt(get-unapplied))(false)
|
|
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
|
|
tt(actionformats).)
|
|
sitem(tt(%i))(The current revision number or identifier. For tt(hg)
|
|
the tt(hgrevformat) style may be used to customize the output.)
|
|
sitem(tt(%c))(The string from the tt(stagedstr) style if there are staged
|
|
changes in the repository.)
|
|
sitem(tt(%u))(The string from the tt(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 tt(/foo/bar/repoXY), tt(%r)
|
|
is tt(repoXY).)
|
|
sitem(tt(%S))(A subdirectory within a repository. If tt($PWD) is
|
|
tt(/foo/bar/repoXY/beer/tasty), tt(%S) is tt(beer/tasty).)
|
|
endsitem()
|
|
startitem()
|
|
item(tt(%m))(
|
|
A "misc" replacement. It is at the discretion of the backend to
|
|
decide what this replacement expands to.
|
|
|
|
The tt(hg) and tt(git) backends use this expando to display patch information.
|
|
tt(hg) sources patch information from the tt(mq) extensions; tt(git) from in-progress
|
|
tt(rebase) and tt(cherry-pick) operations and from the tt(stgit) extension. The tt(patch-format)
|
|
and tt(nopatch-format) styles control the generated string. The former is used
|
|
when at least one patch from the patch queue has been applied, and the latter
|
|
otherwise.
|
|
|
|
The tt(hg) backend displays bookmark information in this expando (in addition
|
|
to tt(mq) information). See the tt(get-mq) and tt(get-bookmarks) styles. Both
|
|
of these styles may be enabled at the same time. If both are enabled, both
|
|
resulting strings will be shown separated by a semicolon (that cannot currently
|
|
be customized).
|
|
|
|
The tt(quilt) `standalone' backend sets this expando to the same value as the
|
|
tt(%Q) expando.
|
|
)
|
|
item(tt(%Q))(
|
|
Quilt series information.
|
|
When quilt is used (either in `addon' mode or as a `standalone' backend),
|
|
this expando is set to quilt series' tt(patch-format) string.
|
|
The tt(set-patch-format) hook and tt(nopatch-format) style are honoured.
|
|
|
|
See ifzman(tt(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details.
|
|
)
|
|
enditem()
|
|
|
|
In tt(branchformat) these replacements are done:
|
|
|
|
startsitem()
|
|
sitem(tt(%b))(The branch name. For tt(hg), the branch name can include a
|
|
topic name.)
|
|
sitem(tt(%r))(The current revision number or the tt(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 global revision 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; may be overridden by the tt(applied-string) hook.)
|
|
sitem(tt(%u))(The number of unapplied patches; may be overridden by the tt(unapplied-string) hook.)
|
|
sitem(tt(%n))(The number of applied patches.)
|
|
sitem(tt(%c))(The number of unapplied patches.)
|
|
sitem(tt(%a))(The number of all patches (tt(%a = %n + %c)).)
|
|
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.
|
|
|
|
texinode(vcs_info Oddities)(vcs_info Quilt Support)(vcs_info Configuration)(Version Control Information)
|
|
subsect(Oddities)
|
|
|
|
If you want to use the tt(%b) (bold off) prompt expansion in tt(formats),
|
|
which expands tt(%b) itself, use tt(%%b). That will cause the tt(vcs_info)
|
|
expansion to replace tt(%%b) with tt(%b), so that zsh's prompt expansion
|
|
mechanism can handle it. Similarly, to hand down tt(%b) from
|
|
tt(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.
|
|
|
|
When one of the tt(gen-applied-string), tt(gen-unapplied-string), and
|
|
tt(set-patch-format) hooks is defined,
|
|
applying tt(%)-escaping (`tt(foo=${foo//'%'/%%})') to the interpolated values
|
|
for use in the prompt is the responsibility of those hooks (jointly);
|
|
when neither of those hooks is defined, tt(vcs_info) handles escaping by itself.
|
|
We regret this coupling, but it was required for backwards compatibility.
|
|
|
|
texinode(vcs_info Quilt Support)(vcs_info API)(vcs_info Oddities)(Version Control Information)
|
|
subsect(Quilt Support)
|
|
|
|
bf(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 tt(vcs_info) integration tries to support both ways of using quilt by
|
|
having two slightly different modes of operation: `addon' mode and
|
|
`standalone' mode).
|
|
|
|
Quilt integration is off by default; to enable it, set the tt(use-quilt) style,
|
|
and add tt(%Q) to your tt(formats) or tt(actionformats) style:
|
|
example(zstyle ':vcs_info:*' use-quilt true)
|
|
|
|
Styles looked up from the Quilt support code include `tt(.quilt-)var(quilt-mode)'
|
|
in the var(vcs-string) part of the context, where var(quilt-mode) is either
|
|
tt(addon) or tt(standalone).
|
|
Example: tt(:vcs_info:git.quilt-addon:default:)var(repo-root-name).
|
|
|
|
For `addon' mode to become active tt(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 `tt(QUILT_PATCHES)' environment variable. If that
|
|
variable exists its value is used, otherwise the value `tt(patches)' is
|
|
assumed. The value from tt($QUILT_PATCHES) can be overwritten using the
|
|
`tt(quilt-patches)' style. (Note: you can use tt(vcs_info) to keep the value
|
|
of tt($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, tt(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, tt(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.
|
|
|
|
tt(vcs_info) allows for very detailed control over how the gathered
|
|
information is presented (see
|
|
ifzman(the bf(Configuration) and bf(Hooks in vcs_info) sections)\
|
|
ifnzman(noderef(vcs_info Configuration) and noderef(vcs_info Hooks))),
|
|
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 bf(git), or tt(mq) for bf(hg)); the configuration
|
|
for systems like that are generally configured the same way as the bf(quilt)
|
|
support.
|
|
|
|
If the bf(quilt) support is working in `addon' mode, the produced string is
|
|
available as a simple format replacement (tt(%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,
|
|
tt(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. tt(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 tt(%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 tt(vcs_info) to try and look for Quilt in `standalone' mode to minimise
|
|
the amount of searching on every call to tt(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
|
|
tt(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.
|
|
|
|
|
|
texinode(vcs_info API)(vcs_info Variables)(vcs_info Quilt Support)(Version Control Information)
|
|
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
|
|
tt(${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
|
|
ifzman(bf(Variable Description))ifnzman(noderef(vcs_info Variables))
|
|
below). If an argument is given, that string will be
|
|
used instead of tt(default) in the var(user-context) field of the style
|
|
context.
|
|
)
|
|
findex(vcs_info_hookadd)
|
|
item(tt(vcs_info_hookadd))(
|
|
Statically registers a number of functions to a given hook. The hook needs
|
|
to be given as the first argument; what follows is a list of hook-function
|
|
names to register to the hook. The `tt(+vi-)' prefix needs to be left out
|
|
here. See ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks))
|
|
below for details.
|
|
)
|
|
findex(vcs_info_hookdel)
|
|
item(tt(vcs_info_hookdel))(
|
|
Remove hook-functions from a given hook. The hook needs to be given as the
|
|
first non-option argument; what follows is a list of hook-function
|
|
names to un-register from the hook. If `tt(-a)' is used as the first
|
|
argument, tt(all) occurrences of the functions are unregistered. Otherwise
|
|
only the last occurrence is removed (if a function was registered to a hook
|
|
more than once). The `tt(+vi-)' prefix needs to be left out here.
|
|
See ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks))
|
|
below for details.
|
|
)
|
|
findex(vcs_info_lastmsg)
|
|
item(tt(vcs_info_lastmsg))(
|
|
Outputs the current values of tt(${vcs_info_msg_*_}).
|
|
Takes into account the value of the tt(use-prompt-escapes) style in
|
|
tt(':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 tt(disable) style.
|
|
)
|
|
findex(vcs_info_setsys)
|
|
item(tt(vcs_info_setsys))(
|
|
Initializes tt(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 tt(VCS_INFO_*) are for internal use only.
|
|
|
|
texinode(vcs_info Variables)(vcs_info Hooks)(vcs_info API)(Version Control Information)
|
|
subsect(Variable Description)
|
|
|
|
startitem()
|
|
item(tt(${vcs_info_msg_)var(N)tt(_}) (Note the trailing underscore))(
|
|
Where var(N) is an integer, e.g., tt(vcs_info_msg_0_). These variables
|
|
are the storage for the informational message the last tt(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
|
|
tt(${vcs_info_msg_0_}), the second into tt(${vcs_info_msg_1_})
|
|
and the Nth into tt(${vcs_info_msg_N-1_}). (See the tt(max-exports)
|
|
style above.)
|
|
)
|
|
enditem()
|
|
|
|
All variables named tt(VCS_INFO_*) are for internal use only.
|
|
|
|
texinode(vcs_info Hooks)(vcs_info Examples)(vcs_info Variables)(Version Control Information)
|
|
subsect(Hooks in vcs_info)
|
|
|
|
Hooks are places in tt(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:var(vcs-string)PLUS()var(hook-name):var(user-context):var(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 `tt(+vi-)', so the actual functions called for the `foo' hook are
|
|
`tt(+vi-bar)' and `tt(+vi-baz)'.
|
|
|
|
If you would like to register a function to a hook regardless of the
|
|
current context, you may use the tt(vcs_info_hookadd) function. To remove
|
|
a function that was added like that, the tt(vcs_info_hookdel) function
|
|
can be used.
|
|
|
|
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. Context-sensitive hook functions are
|
|
executed tt(before) statically registered ones (the ones added by
|
|
tt(vcs_info_hookadd)).
|
|
|
|
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 tt(vcs_info) but before the VCS in this directory is
|
|
determined. It can be used to deactivate tt(vcs_info) temporarily if
|
|
necessary. When tt(ret) is set to tt(1), tt(vcs_info) aborts and does
|
|
nothing; when set to tt(2), tt(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
|
|
tt(vcs_info) collected from `hg'.
|
|
|
|
If a bookmark is active, the key tt(${hook_com[hg-active-bookmark]}) is
|
|
set to its name. The key is otherwise unset.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[hg-bookmark-string]}) will be used in the tt(%m) escape in
|
|
tt(formats) and tt(actionformats) and will be available in the global
|
|
tt(backend_misc) array as tt(${backend_misc[bookmarks]}).
|
|
)
|
|
item(tt(gen-applied-string))(
|
|
Called in the tt(git) (with tt(stgit) or during rebase or merge), and tt(hg)
|
|
(with tt(mq)) backends and in tt(quilt) support when the tt(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).
|
|
|
|
The arguments to this hook describe applied patches
|
|
in the opposite order, which means that the first argument is the
|
|
top-most patch and so forth.
|
|
|
|
When the patches' log messages can be extracted, those are embedded
|
|
within each argument after a space, so each argument is of the form
|
|
`var(patch-name) var(first line of the log message)', where var(patch-name)
|
|
contains no whitespace. The tt(mq) backend passes arguments of
|
|
the form `var(patch name)', with possible embedded spaces, but without
|
|
extracting the patch's log message.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[applied-string]}) will be
|
|
available as tt(%p) in the tt(patch-format) and tt(nopatch-format) styles.
|
|
This hook is, in concert with tt(set-patch-format), responsible for
|
|
tt(%)-escaping that value for use in the prompt.
|
|
(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).)
|
|
)
|
|
item(tt(gen-unapplied-string))(
|
|
Called in the tt(git) (with tt(stgit) or during rebase), and tt(hg) (with
|
|
tt(mq)) backend and in tt(quilt) support when the tt(unapplied-string) is
|
|
generated; the tt(get-unapplied) style must be true.
|
|
|
|
This hook gets the names of all unapplied patches which tt(vcs_info)
|
|
in order, which means that the first argument is
|
|
the patch next-in-line to be applied and so forth.
|
|
|
|
The format of each argument is as for tt(gen-applied-string), above.
|
|
|
|
When setting tt(ret) to non-zero, the string in
|
|
tt(${hook_com[unapplied-string]}) will be available as tt(%u) in the
|
|
tt(patch-format) and tt(nopatch-format) styles.
|
|
This hook is, in concert with tt(set-patch-format), responsible for
|
|
tt(%)-escaping that value for use in the prompt.
|
|
(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).)
|
|
)
|
|
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 tt(%g) escape in the
|
|
tt(patch-format) and tt(nopatch-format) styles.
|
|
)
|
|
item(tt(no-vcs))(
|
|
This hooks is called when no version control system was detected.
|
|
|
|
The `tt(hook_com)' parameter is not used.
|
|
)
|
|
item(tt(post-backend))(
|
|
Called as soon as the backend has finished collecting information.
|
|
|
|
The `tt(hook_com)' keys available are as for the tt(set-message) hook.
|
|
)
|
|
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 tt(vcs_info) and any
|
|
change will be used directly when the actual replacement is done.
|
|
|
|
If tt(ret) is set 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 tt(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 tt(vcs_info) and any
|
|
change will be used directly when the actual replacement is done.
|
|
|
|
If tt(ret) is set 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 tt(vcs_info).
|
|
)
|
|
item(tt(pre-addon-quilt))(
|
|
This hook is used when tt(vcs_info)'s quilt functionality is active in "addon"
|
|
mode (quilt used on top of a real version control system). It is activated
|
|
right before any quilt specific action is taken.
|
|
|
|
Setting the `tt(ret)' variable in this hook to a non-zero value avoids any
|
|
quilt specific actions from being run at all.
|
|
)
|
|
item(tt(set-patch-format))(
|
|
This hook is used to control some of the possible expansions in
|
|
tt(patch-format) and tt(nopatch-format) styles with patch queue systems such as
|
|
quilt, mqueue and the like.
|
|
|
|
This hook is used in the tt(git), tt(hg) and tt(quilt) backends.
|
|
|
|
The hook allows the control of the tt(%p) (tt(${hook_com[applied]})) and tt(%u)
|
|
(tt(${hook_com[unapplied]})) expansion in all backends that use the hook. With
|
|
the mercurial backend, the tt(%g) (tt(${hook_com[guards]})) expansion is
|
|
controllable in addition to that.
|
|
|
|
If tt(ret) is set to non-zero, the string in tt(${hook_com[patch-replace]})
|
|
will be used unchanged instead of an expanded format from tt(patch-format) or
|
|
tt(nopatch-format).
|
|
|
|
This hook is, in concert with the tt(gen-applied-string) or
|
|
tt(gen-unapplied-string) hooks if they are defined, responsible for
|
|
tt(%)-escaping the final tt(patch-format) value for use in the prompt.
|
|
(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).)
|
|
)
|
|
item(tt(set-message))(
|
|
Called each time before a `tt(vcs_info_msg_)var(N)tt(_)' message is set.
|
|
It takes two arguments; the first being the `var(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
|
|
tt(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 non-zero, the string in
|
|
tt(${hook_com[message]}) will be used unchanged as the message by
|
|
tt(vcs_info).
|
|
)
|
|
enditem()
|
|
|
|
If all of this sounds rather confusing, take a look at
|
|
ifzman(the bf(Examples) section below)ifnzman(noderef(vcs_info Examples))
|
|
and also in the tt(Misc/vcs_info-examples) file in the Zsh source.
|
|
They contain some explanatory code.
|
|
|
|
texinode(vcs_info Examples)()(vcs_info Hooks)(Version Control Information)
|
|
subsect(Examples)
|
|
|
|
Don't use tt(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 (tt(formats), tt(actionformats),
|
|
tt(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%%F{yellow}:%r')
|
|
|
|
The doubled percent sign is explained in
|
|
ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).
|
|
|
|
Alternatively, one can use the raw colour codes directly:
|
|
|
|
example(zstyle ':vcs_info:(svn|bzr):*' \
|
|
branchformat '%b%{'${fg[yellow]}'%}:%r')
|
|
|
|
Normally when a variable is interpolated into a format string, the variable
|
|
needs to be tt(%)-escaped. In this example we skipped that because we assume
|
|
the value of tt(${fg[yellow]}) doesn't contain any tt(%) signs.
|
|
|
|
Make sure you enclose the color codes in tt(%{)var(...)tt(%})
|
|
if you want to use the string provided by tt(vcs_info) in prompts.
|
|
|
|
Here is how to print the VCS information as a command (not in a prompt):
|
|
example(vcsi+LPAR()+RPAR() { vcs_info interactive; vcs_info_lastmsg })
|
|
|
|
This way, you can even define different formats for output via
|
|
tt(vcs_info_lastmsg) in the 'tt(:vcs_info:*:interactive:*)' namespace.
|
|
|
|
Now as promised, some code that uses hooks:
|
|
say, you'd like to replace the string `svn' by `subversion' in
|
|
tt(vcs_info)'s tt(%s) tt(formats) replacement.
|
|
|
|
First, we will tell tt(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.
|
|
# The bookmarks returned by `hg' are available in
|
|
# the function's positional parameters.
|
|
local s="${(Mj:,:)@:#sh/*}"
|
|
# 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 is `hg-bookmark-string'. So:
|
|
hook_com[hg-bookmark-string]=$s
|
|
# And to signal that we want to use the string 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 tt(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)' and `tt(add-zsh-hook)' functions from
|
|
tt(Functions/Misc).
|
|
All these functions may already be 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()
|
|
|
|
subsect(Utility Themes)
|
|
|
|
startitem()
|
|
item(tt(prompt off))(
|
|
The theme `tt(off)' sets all the prompt variables to minimal values with
|
|
no special effects.
|
|
)
|
|
item(tt(prompt default))(
|
|
The theme `tt(default)' sets all prompt variables to the same state as
|
|
if an interactive zsh was started with no initialization files.
|
|
)
|
|
item(tt(prompt restore))(
|
|
The special theme `tt(restore)' erases all theme settings and sets prompt
|
|
variables to their state before the first time the `tt(prompt)' function
|
|
was run, provided each theme has properly defined its cleanup (see below).
|
|
|
|
Note that you can undo `tt(prompt off)' and `tt(prompt default)' with
|
|
`tt(prompt restore)', but a second restore does not undo the first.
|
|
)
|
|
enditem()
|
|
|
|
subsect(Writing Themes)
|
|
|
|
The first step for adding your own theme is to choose a name for it,
|
|
and create a file `tt(prompt_var(name)_setup)' in a directory in your
|
|
tt(fpath), such as tt(~/myfns) in the example above. The file should
|
|
at minimum contain assignments for the prompt variables that your
|
|
theme wishes to modify. By convention, themes use tt(PS1), tt(PS2),
|
|
tt(RPS1), etc., rather than the longer tt(PROMPT) and tt(RPROMPT).
|
|
|
|
The file is autoloaded as a function in the current shell context, so
|
|
it may contain any necessary commands to customize your theme, including
|
|
defining additional functions. To make some complex tasks easier, your
|
|
setup function may also do any of the following:
|
|
|
|
startitem()
|
|
item(Assign tt(prompt_opts))(
|
|
The array tt(prompt_opts) may be assigned any of tt("bang"), tt("cr"),
|
|
tt("percent"), tt("sp"), and/or tt("subst") as values. The corresponding
|
|
setopts (tt(promptbang), etc.) are turned on, all other prompt-related
|
|
options are turned off. The tt(prompt_opts) array preserves setopts even
|
|
beyond the scope of tt(localoptions), should your function need that.
|
|
)
|
|
item(Modify precmd and preexec)(
|
|
Use of tt(add-zsh-hook) is recommended. The tt(precmd) and tt(preexec)
|
|
hooks are automatically adjusted if the prompt theme changes or is
|
|
disabled.
|
|
)
|
|
item(Declare cleanup)(
|
|
If your function makes any other changes that should be undone when the
|
|
theme is disabled, your setup function may call
|
|
|
|
example(prompt_cleanup var(command))
|
|
|
|
where var(command) should be suitably quoted. If your theme is ever
|
|
disabled or replaced by another, var(command) is executed with tt(eval).
|
|
You may declare more than one such cleanup hook.
|
|
)
|
|
item(Define preview)(
|
|
Define or autoload a function tt(prompt_)var(name)tt(_preview) to display
|
|
a simulated version of your prompt. A simple default previewer is
|
|
defined by tt(promptinit) for themes that do not define their own.
|
|
This preview function is called by `tt(prompt -p)'.
|
|
)
|
|
item(Provide help)(
|
|
Define or autoload a function tt(prompt_)var(name)tt(_help) to display
|
|
documentation or help text for your theme.
|
|
This help function is called by `tt(prompt -h)'.
|
|
)
|
|
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(delete-whole-word-match)
|
|
tindex(select-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))
|
|
xitem(tt(delete-whole-word-match), tt(select-word-match))
|
|
item(tt(select-word-style), tt(match-word-context), tt(match-words-by-style))(
|
|
The first 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. tt(select-word-match) is intended
|
|
to be used as a text object in vi mode but with custom word styles. For
|
|
comparison, the widgets described in ifzman(zmanref(zshzle) under Text Objects)\
|
|
ifnzman(noderef(Text Objects)) use fixed definitions of words, compatible
|
|
with the tt(vim) editor.
|
|
|
|
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 first 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(between) the word
|
|
is set to a single space; else if it is contains the string tt(back),
|
|
the word before the cursor is considered, else the word after cursor is
|
|
considered. Some examples are given below.
|
|
|
|
The style tt(skip-whitespace-first) is only used with the
|
|
tt(forward-word) widget. If it is set to true, then tt(forward-word)
|
|
skips any non-word-characters, followed by any non-word-characters:
|
|
this is similar to the behaviour of other word-orientated widgets,
|
|
and also that used by other editors, however it differs from the
|
|
standard zsh behaviour. When using tt(select-word-style) the widget
|
|
is set in the context tt(:zle:*) to tt(true) if the word style is
|
|
tt(bash) and tt(false) otherwise. It may be overridden by setting it in
|
|
the more specific context tt(:zle:forward-word*).
|
|
|
|
It is possible to create widgets with specific behaviour by defining
|
|
a new widget implemented by the appropriate generic function, then
|
|
setting a style for the context of the specific widget. For example,
|
|
the following defines a widget tt(backward-kill-space-word) using
|
|
tt(backward-kill-word-match), the generic widget implementing
|
|
tt(backward-kill-word) behaviour, and ensures that the new widget
|
|
always implements space-delimited behaviour.
|
|
|
|
example(zle -N backward-kill-space-word backward-kill-word-match
|
|
zstyle :zle:backward-kill-space-word word-style space)
|
|
|
|
The widget tt(backward-kill-space-word) can now be bound to a key.
|
|
|
|
Here are some further 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 \
|
|
"*/*" filename "[[: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.
|
|
|
|
If the variable tt(matched_words) is defined by the caller to
|
|
tt(match-words-by-style) as an associative array (tt(local -A
|
|
matched_words)), then the seven values given above should be retrieved
|
|
from it as elements named tt(start), tt(word-before-cursor),
|
|
tt(ws-before-cursor), tt(ws-after-cursor), tt(word-after-cursor),
|
|
tt(ws-after-word), and tt(end). In addition the element
|
|
tt(is-word-start) is 1 if the cursor is on the start of a word or
|
|
subword, or on white space before it (the cases can be distinguished by
|
|
testing the tt(ws-after-cursor) element) and 0 otherwise. This form is
|
|
recommended for future compatibility.
|
|
|
|
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(bracketed-paste-magic)
|
|
item(tt(bracketed-paste-magic))(
|
|
The tt(bracketed-paste) widget (see ifzman(subsection Miscellaneous in
|
|
zmanref(zshzle))ifnzman(noderef(Miscellaneous) in noderef(Zle Widgets)))
|
|
inserts pasted text literally into the editor buffer rather than interpret
|
|
it as keystrokes. This disables some common usages where the self-insert
|
|
widget is replaced in order to accomplish some extra processing. An
|
|
example is the contributed tt(url-quote-magic) widget described below.
|
|
|
|
The tt(bracketed-paste-magic) widget is meant to replace tt(bracketed-paste)
|
|
with a wrapper that re-enables these self-insert actions, and other
|
|
actions as selected by zstyles. Therefore this widget is installed with
|
|
ifzman()
|
|
example(autoload -Uz bracketed-paste-magic
|
|
zle -N bracketed-paste bracketed-paste-magic)
|
|
|
|
Other than enabling some widget processing, tt(bracketed-paste-magic)
|
|
attempts to replicate tt(bracketed-paste) as faithfully as possible.
|
|
|
|
The following zstyles may be set to control processing of pasted text.
|
|
All are looked up in the context `tt(:bracketed-paste-magic)'.
|
|
|
|
startitem()
|
|
item(tt(active-widgets))(
|
|
A list of patterns matching widget names that should be activated during
|
|
the paste. All other key sequences are processed as self-insert-unmeta.
|
|
The default is `tt(self-*)' so any user-defined widgets named with that
|
|
prefix are active along with the builtin self-insert.
|
|
|
|
If this style is not set (explicitly deleted) or set to an empty value,
|
|
no widgets are active and the pasted text is inserted literally. If the
|
|
value includes `tt(undefined-key)', any unknown sequences are discarded
|
|
from the pasted text.
|
|
)
|
|
item(tt(inactive-keys))(
|
|
The inverse of tt(active-widgets), a list of key sequences that always use
|
|
tt(self-insert-unmeta) even when bound to an active widget. Note that
|
|
this is a list of literal key sequences, not patterns.
|
|
)
|
|
item(tt(paste-init))(
|
|
A list of function names, called in widget context (but not as widgets).
|
|
The functions are called in order until one of them returns a non-zero
|
|
status. The parameter `tt(PASTED)' contains the initial state of the
|
|
pasted text. All other ZLE parameters such as `tt(BUFFER)' have their
|
|
normal values and side-effects, and full history is available, so for
|
|
example tt(paste-init) functions may move words from tt(BUFFER) into
|
|
tt(PASTED) to make those words visible to the tt(active-widgets).
|
|
|
|
A non-zero return from a tt(paste-init) function does em(not) prevent the
|
|
paste itself from proceeding.
|
|
|
|
Loading tt(bracketed-paste-magic) defines tt(backward-extend-paste), a
|
|
helper function for use in tt(paste-init).
|
|
|
|
example(zstyle :bracketed-paste-magic paste-init \
|
|
backward-extend-paste)
|
|
|
|
When a paste would insert into the middle of a word or append text to a
|
|
word already on the line, tt(backward-extend-paste) moves the prefix
|
|
from tt(LBUFFER) into tt(PASTED) so that the tt(active-widgets) see the
|
|
full word so far. This may be useful with tt(url-quote-magic).
|
|
)
|
|
item(tt(paste-finish))(
|
|
Another list of function names called in order until one returns non-zero.
|
|
These functions are called em(after) the pasted text has been processed
|
|
by the tt(active-widgets), but em(before) it is inserted into `tt(BUFFER)'.
|
|
ZLE parameters have their normal values and side-effects.
|
|
|
|
A non-zero return from a tt(paste-finish) function does em(not) prevent
|
|
the paste itself from proceeding.
|
|
|
|
Loading tt(bracketed-paste-magic) also defines tt(quote-paste), a helper
|
|
function for use in tt(paste-finish).
|
|
|
|
example(zstyle :bracketed-paste-magic paste-finish \
|
|
quote-paste
|
|
zstyle :bracketed-paste-magic:finish quote-style \
|
|
qqq)
|
|
|
|
When the pasted text is inserted into tt(BUFFER), it is quoted per the
|
|
tt(quote-style) value. To forcibly turn off the built-in numeric prefix
|
|
quoting of tt(bracketed-paste), use:
|
|
|
|
example(zstyle :bracketed-paste-magic:finish quote-style \
|
|
none)
|
|
)
|
|
enditem()
|
|
|
|
em(Important:) During tt(active-widgets) processing of the paste (after
|
|
tt(paste-init) and before tt(paste-finish)), tt(BUFFER) starts empty and
|
|
history is restricted, so cursor motions, etc., may not pass outside of
|
|
the pasted content. Text assigned to tt(BUFFER) by the active widgets
|
|
is copied back into tt(PASTED) before tt(paste-finish).
|
|
)
|
|
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(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 argument 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(down-line-or-beginning-search)
|
|
tindex(up-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(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)
|
|
|
|
The editor to be used can also be specified using the tt(editor) style in
|
|
the context of the widget. It is specified as an array of command and
|
|
arguments:
|
|
|
|
example(zstyle :zle:edit-command-line editor gvim -f)
|
|
)
|
|
tindex(expand-absolute-path)
|
|
item(tt(expand-absolute-path))(
|
|
Expand the file name under the cursor to an absolute path, resolving
|
|
symbolic links. Where possible, the initial path segment is turned
|
|
into a named directory or reference to a user's home directory.
|
|
)
|
|
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 numeric 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 numeric 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(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 argument, the number is incremented by the amount of the
|
|
argument (decremented if the numeric 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 uref(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
|
|
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 (scharfes 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(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(narrow-to-region)
|
|
tindex(narrow-to-region-invisible)
|
|
redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ ))ifnztexi( )))
|
|
xitem(tt(narrow-to-region )[ tt(-p) var(pre) ] [ tt(-P) var(post) ])
|
|
xitem(SPACES()[ tt(-S) var(statepm) | tt(-R) var(statepm) | [ tt(-l) var(lbufvar) ] [ tt(-r) var(rbufvar) ] ])
|
|
xitem(SPACES()[ tt(-n) ] [ var(start) var(end) ])
|
|
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.
|
|
|
|
The options tt(-l) var(lbufvar) and tt(-r) var(rbufvar) may be used to
|
|
specify parameters where the widget will store the resulting text from
|
|
the operation. The parameter var(lbufvar) will contain tt(LBUFFER)
|
|
and var(rbufvar) will contain tt(RBUFFER). Neither of these two options
|
|
may be used with tt(-S) or tt(-R).
|
|
|
|
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(...)'. It does not take any arguments.
|
|
|
|
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(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-argument)
|
|
tindex(replace-argument-edit)
|
|
item(tt(replace-argument), tt(replace-argument-edit))
|
|
(
|
|
The function tt(replace-argument) can be used to replace a command
|
|
line argument in the current command line or, if the current command
|
|
line is empty, in the last command line executed (the new command line
|
|
is not executed). Arguments are as delimited by standard shell syntax,
|
|
|
|
If a numeric argument is given, that specifies the argument to be
|
|
replaced. 0 means the command name, as in history expansion.
|
|
A negative numeric argument counts backward from the last word.
|
|
|
|
If no numeric argument is given, the current argument is replaced;
|
|
this is the last argument if the previous history line is being used.
|
|
|
|
The function prompts for a replacement argument.
|
|
|
|
If the widget contains the string tt(edit), for example is defined as
|
|
|
|
example(zle -N replace-argument-edit replace-argument)
|
|
|
|
then the function presents the current value of the argument for
|
|
editing, otherwise the editing buffer for the replacement is
|
|
initially empty.
|
|
)
|
|
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.
|
|
|
|
In addition, tt(replace-string) shows the previous replacement above
|
|
the prompt, so long as there was one during the current session; if the
|
|
source string is empty, that replacement will be repeated without
|
|
the widget prompting for a replacement string.
|
|
|
|
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(send-invisible)
|
|
item(tt(send-invisible))(
|
|
This is similar to read-from-minibuffer in that it may be called as a
|
|
function from a widget or as a widget of its own, and interactively reads
|
|
input from the keyboard. However, the input being typed is concealed and
|
|
a string of asterisks (`tt(*)') is shown instead. The value is saved in
|
|
the parameter tt($INVISIBLE) to which a reference is inserted into the
|
|
editing buffer at the restored cursor position. If the read was aborted
|
|
by a keyboard break (typically tt(^G)) or another escape from editing such
|
|
as tt(push-line), tt($INVISIBLE) is set to empty and the original buffer
|
|
is restored unchanged.
|
|
|
|
If one argument is supplied to the function it is taken as a prompt,
|
|
otherwise `tt(Non-echoed text: )' is used (as in emacs). If a second and
|
|
third argument are supplied they are used to begin and end the reference
|
|
to tt($INVISIBLE) that is inserted into the buffer. The default is to
|
|
open with tt(${), then tt(INVISIBLE), and close with tt(}), but many
|
|
other effects are possible.
|
|
)
|
|
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 argument, 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(transpose-lines)
|
|
item(tt(transpose-lines))(
|
|
Only useful with a multi-line editing buffer; the lines here are
|
|
lines within the current on-screen buffer, not history lines.
|
|
The effect is similar to the function of the same name in Emacs.
|
|
|
|
Transpose the current line with the previous line and move the cursor
|
|
to the start of the next line. Repeating this (which can be done by
|
|
providing a positive numeric argument) has the effect of moving
|
|
the line above the cursor down by a number of lines.
|
|
|
|
With a negative numeric argument, requires two lines above the
|
|
cursor. These two lines are transposed and the cursor moved to the
|
|
start of the previous line. Using a numeric argument less than -1
|
|
has the effect of moving the line above the cursor up by minus that
|
|
number of lines.
|
|
)
|
|
tindex(url-quote-magic)
|
|
item(tt(url-quote-magic))(
|
|
This widget replaces the built-in tt(self-insert) to make it easier to
|
|
type URLs as command line arguments. As you type, the input character is
|
|
analyzed and, if it may need quoting, the current word is checked for a
|
|
URI scheme. If one is found and the current word is not already in
|
|
quotes, a backslash is inserted before the input character.
|
|
|
|
Styles to control quoting behavior:
|
|
|
|
startitem()
|
|
item(tt(url-metas))(
|
|
This style is looked up in the context `tt(:url-quote-magic:)var(scheme)'
|
|
(where var(scheme) is that of the current URL, e.g. "tt(ftp)"). The value
|
|
is a string listing the characters to be treated as globbing
|
|
metacharacters when appearing in a URL using that scheme. The default is
|
|
to quote all zsh extended globbing characters, excluding 'tt(<)' and
|
|
'tt(>)' but including braces (as in brace expansion). See also
|
|
tt(url-seps).
|
|
)
|
|
item(tt(url-seps))(
|
|
Like tt(url-metas), but lists characters that should be considered command
|
|
separators, redirections, history references, etc. The default is to
|
|
quote the standard set of shell separators, excluding those that overlap
|
|
with the extended globbing characters, but including 'tt(<)' and
|
|
'tt(>)' and the first character of tt($histchars).
|
|
)
|
|
item(tt(url-globbers))(
|
|
This style is looked up in the context `tt(:url-quote-magic)'. The values
|
|
form a list of command names that are expected to do their own globbing
|
|
on the URL string. This implies that they are aliased to use the
|
|
`tt(noglob)' modifier. When the first word on the line matches one of the
|
|
values em(and) the URL refers to a local file (see tt(url-local-schema)),
|
|
only the tt(url-seps) characters are quoted; the tt(url-metas) are left
|
|
alone, allowing them to affect command-line parsing, completion, etc. The
|
|
default values are a literal `tt(noglob)' plus (when the tt(zsh/parameter)
|
|
module is available) any commands aliased to the helper function
|
|
`tt(urlglobber)' or its alias `tt(globurl)'.
|
|
)
|
|
item(tt(url-local-schema))(
|
|
This style is always looked up in the context `tt(:urlglobber)', even
|
|
though it is used by both url-quote-magic and urlglobber. The values form
|
|
a list of URI schema that should be treated as referring to local files by
|
|
their real local path names, as opposed to files which are specified
|
|
relative to a web-server-defined document root. The defaults are
|
|
"tt(ftp)" and "tt(file)".
|
|
)
|
|
item(tt(url-other-schema))(
|
|
Like tt(url-local-schema), but lists all other URI schema upon which
|
|
tt(urlglobber) and tt(url-quote-magic) should act. If the URI on the
|
|
command line does not have a scheme appearing either in this list or in
|
|
tt(url-local-schema), it is not magically quoted. The default values are
|
|
"tt(http)", "tt(https)", and "tt(ftp)". When a scheme appears both here
|
|
and in tt(url-local-schema), it is quoted differently depending on whether
|
|
the command name appears in tt(url-globbers).
|
|
)
|
|
enditem()
|
|
|
|
Loading tt(url-quote-magic) also defines a helper function `tt(urlglobber)'
|
|
and aliases `tt(globurl)' to `tt(noglob urlglobber)'. This function takes
|
|
a local URL apart, attempts to pattern-match the local file portion of the
|
|
URL path, and then puts the results back into URL format again.
|
|
)
|
|
tindex(vi-pipe)
|
|
item(tt(vi-pipe))(
|
|
This function reads a movement command from the keyboard and then
|
|
prompts for an external command. The part of the buffer covered by
|
|
the movement is piped to the external command and then replaced by
|
|
the command's output. If the movement command is bound to vi-pipe,
|
|
the current line is used.
|
|
|
|
The function serves as an example for reading a vi movement command
|
|
from within a user-defined widget.
|
|
)
|
|
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).
|
|
)
|
|
tindex(zcalc-auto-insert)
|
|
item(tt(zcalc-auto-insert))(
|
|
This function is useful together with the tt(zcalc) function described in
|
|
ifzman(the section Mathematical Functions)\
|
|
ifnzman(noderef(Mathematical Functions)).
|
|
It should be bound to a key representing a binary operator such
|
|
as `tt(PLUS())', `tt(-)', `tt(*)' or `tt(/)'. When running in zcalc,
|
|
if the key occurs at the start of the line or immediately following
|
|
an open parenthesis, the text tt("ans ") is inserted before the
|
|
representation of the key itself. This allows easy use of the
|
|
answer from the previous calculation in the current line. The
|
|
text to be inserted before the symbol typed can be modified by setting
|
|
the variable tt(ZCALC_AUTO_INSERT_PREFIX).
|
|
|
|
Hence, for example, typing `tt(PLUS()12)' followed by return adds 12
|
|
to the previous result.
|
|
|
|
If zcalc is in RPN mode (tt(-r) option) the effect of this binding is
|
|
automatically suppressed as operators alone on a line are meaningful.
|
|
|
|
When not in zcalc, the key simply inserts the symbol itself.
|
|
)
|
|
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) | var(func) ])(
|
|
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 can 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.
|
|
|
|
Alternatively, if the argument does not contain the string tt(ARG), it
|
|
is assumed to be a shell function, to which the current command line
|
|
argument is passed as the only argument. The function should set the
|
|
variable tt(REPLY) to the new value for the command line argument.
|
|
If the function returns non-zero status, so does the calling function.
|
|
|
|
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}}')
|
|
|
|
The following performs directory expansion on the command line
|
|
argument and replaces it by the absolute path:
|
|
|
|
example(expand-dir+LPAR()RPAR() {
|
|
REPLY=${~1}
|
|
REPLY=${REPLY:a}
|
|
}
|
|
modify-current-argument expand-dir)
|
|
|
|
In practice the function tt(expand-dir) would probably not be defined
|
|
within the widget where tt(modify-current-argument) is called.
|
|
)
|
|
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) [ tt(-l) ] var(command argument) ...)(
|
|
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) or manref(mailcap)(5)
|
|
(the man page's name varies across platforms).
|
|
|
|
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.
|
|
|
|
For files that have multiple suffixes, e.g. tt(.pdf.gz), where the
|
|
context includes the suffix it will be looked up starting with the
|
|
longest possible suffix until a match for the style is found.
|
|
For example, if tt(.pdf.gz) produces a match for the handler, that
|
|
will be used; otherwise the handler for tt(.gz) will be used. Note
|
|
that, owing to the way suffix aliases work, it is always required that
|
|
there be a handler for the shortest possible suffix, so in this example
|
|
tt(.pdf.gz) can only be handled if tt(.gz) is also handled (though
|
|
not necessarily in the same way). Alternatively, if no handling
|
|
for tt(.gz) on its own is needed, simply adding the command
|
|
|
|
example(alias -s gz=zsh-mime-handler)
|
|
|
|
to the initialisation code is sufficient; tt(.gz) will not be handled
|
|
on its own, but may be in combination with other suffixes.
|
|
|
|
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(disown, MIME style)
|
|
item(tt(disown))(
|
|
If this boolean style is true, mailcap handlers started in the
|
|
background will be disowned, i.e. not subject to job control within
|
|
the parent shell. Such handlers nearly always produce their own
|
|
windows, so the only likely harmful side effect of setting the style is
|
|
that it becomes harder to kill jobs from within the shell.
|
|
)
|
|
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(execute-never, MIME style)
|
|
item(tt(execute-never))(
|
|
This style is useful in combination with tt(execute-as-is). It is
|
|
set to an array of patterns corresponding to full paths to files that
|
|
should never be treated as executable, even if the file passed to
|
|
the MIME handler matches tt(execute-as-is). This is useful for file
|
|
systems that don't handle execute permission or that contain executables
|
|
from another operating system. For example, if tt(/mnt/windows) is a
|
|
Windows mount, then
|
|
|
|
example(zstyle ':mime:*' execute-never '/mnt/windows/*')
|
|
|
|
will ensure that any files found in that area will be executed as MIME
|
|
types even if they are executable. As this example shows, the complete
|
|
file name is matched against the pattern, regardless of how the file
|
|
was passed to the handler. The file is resolved to a full path using
|
|
the tt(:P) modifier described in
|
|
ifzman(the subsection Modifiers in zmanref(zshexpn))\
|
|
ifnzman(noderef(Modifiers));
|
|
this means that symbolic links are resolved where possible, so that
|
|
links into other file systems behave in the correct fashion.
|
|
)
|
|
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)
|
|
|
|
Running `tt(zsh-mime-handler -l) var(command line)' prints the command
|
|
line that would be executed, simplified to remove the effect of any
|
|
flags, and quoted so that the output can be run as a complete zsh
|
|
command line. This is used by the completion system to decide how to
|
|
complete after a file handled by tt(zsh-mime-setup).
|
|
)
|
|
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 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) [ tt(-erf) ] [ 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.
|
|
|
|
Non-programmers should note that, as in many other programming
|
|
languages, expressions involving only integers (whether constants
|
|
without a `tt(.)', variables containing such constants as strings, or
|
|
variables declared to be integers) are by default evaluated using
|
|
integer arithmetic, which is not how an ordinary desk calculator
|
|
operates. To force floating point operation, pass the option tt(-f);
|
|
see further notes below.
|
|
|
|
If the file tt(~/.zcalcrc) exists it will be sourced inside the function
|
|
once it is set up and about to process the command line. This
|
|
can be used, for example, to set shell options; tt(emulate -L zsh)
|
|
and tt(setopt extendedglob) are in effect at this point. Any
|
|
failure to source the file if it exists is treated as fatal.
|
|
As with other initialisation files, the directory tt($ZDOTDIR) is used
|
|
instead of tt($HOME) if it is set.
|
|
|
|
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).
|
|
|
|
A line ending with a single backslash is treated in the same fashion
|
|
as it is in command line editing: the backslash is removed, the
|
|
function prompts for more input (the prompt is preceded by `tt(...)'
|
|
to indicate this), and the lines are combined into one to get the final
|
|
result. In addition, if the input so far contains more open than
|
|
close parentheses tt(zcalc) will prompt for more input.
|
|
|
|
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 unless the tt(:local) special command is
|
|
used. The function creates local variables whose names start with
|
|
tt(_), so users should avoid doing so. The variables tt(ans) (the last
|
|
answer) and tt(stack) (the stack in RPN mode) may be referred to
|
|
directly; tt(stack) is an array but elements of it are numeric. Various
|
|
other special variables are used locally with their standard meaning,
|
|
for example tt(compcontext), tt(match), tt(mbegin), tt(mend), tt(psvar).
|
|
|
|
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).
|
|
|
|
If the option `tt(-e)' is set, the function runs non-interactively:
|
|
the arguments are treated as expressions to be evaluated as if entered
|
|
interactively line by line.
|
|
|
|
If the option `tt(-f)' is set, all numbers are treated as floating
|
|
point, hence for example the expression `tt(3/4)' evaluates to 0.75
|
|
rather than 0. Options must appear in separate words.
|
|
|
|
If the option `tt(-r)' is set, RPN (Reverse Polish Notation) mode is
|
|
entered. This has various additional properties:
|
|
startitem()
|
|
item(Stack)(
|
|
Evaluated values are maintained in a stack; this is contained in
|
|
an array named tt(stack) with the most recent value in tt(${stack[1]}).
|
|
)
|
|
item(Operators and functions)(
|
|
If the line entered matches an operator (tt(+), tt(-), tt(*),
|
|
tt(/), tt(**), tt(^), tt(|) or tt(&)) or a function supplied by the
|
|
tt(zsh/mathfunc) library, the bottom element or elements of the stack
|
|
are popped to use as the argument or arguments. The higher elements
|
|
of stack (least recent) are used as earlier arguments. The result is
|
|
then pushed into tt(${stack[1]}).
|
|
)
|
|
item(Expressions)(
|
|
Other expressions are evaluated normally, printed, and added to the
|
|
stack as numeric values. The syntax within expressions on a single line
|
|
is normal shell arithmetic (not RPN).
|
|
)
|
|
item(Stack listing)(
|
|
If an integer follows the option tt(-r) with no space, then
|
|
on every evaluation that many elements of the stack, where available,
|
|
are printed instead of just the most recent result. Hence, for example,
|
|
tt(zcalc -r4) shows tt($stack[4]) to tt($stack[1]) each time results
|
|
are printed.
|
|
)
|
|
item(Duplication: tt(=))(
|
|
The pseudo-operator tt(=) causes the most recent element of
|
|
the stack to be duplicated onto the stack.
|
|
)
|
|
item(tt(pop))(
|
|
The pseudo-function tt(pop) causes the most recent element of
|
|
the stack to be popped. A `tt(>)' on its own has the same effect.
|
|
)
|
|
item(tt(>)var(ident))(
|
|
The expression tt(>) followed (with no space) by a shell identifier
|
|
causes the most recent element of the stack to be popped and
|
|
assigned to the variable with that name. The variable is
|
|
local to the tt(zcalc) function.
|
|
)
|
|
item(tt(<)var(ident))(
|
|
The expression tt(<) followed (with no space) by a shell identifier
|
|
causes the value of the variable with that name to be pushed
|
|
onto the stack. var(ident) may be an integer, in which
|
|
case the previous result with that number (as shown before
|
|
the tt(>) in the standard tt(zcalc) prompt) is put on the stack.
|
|
)
|
|
item(Exchange: tt(xy))(
|
|
The pseudo-function tt(xy) causes the most recent two elements of
|
|
the stack to be exchanged. `tt(<>)' has the same effect.
|
|
)
|
|
enditem()
|
|
|
|
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> )'.
|
|
|
|
The variable tt(ZCALC_ACTIVE) is set within the function and can
|
|
be tested by nested functions; it has the value tt(rpn) if RPN mode is
|
|
active, else 1.
|
|
|
|
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. 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.
|
|
tt(:function) may be abbreviated to tt(:func) or simply tt(:f).
|
|
The var(name) may contain the same characters as a shell function name.
|
|
The function is defined using tt(zmathfuncdef), see below.
|
|
|
|
Note that tt(zcalc) takes care of all quoting. Hence for example:
|
|
|
|
example(:f cube $1 * $1 * $1)
|
|
|
|
defines a function to cube the sole argument. Functions so defined, or
|
|
indeed any functions defined directly or indirectly using tt(functions
|
|
-M), are available to execute by typing only the name on the line in RPN
|
|
mode; this pops the appropriate number of arguments off the stack
|
|
to pass to the function, i.e. 1 in the case of the example tt(cube)
|
|
function. If there are optional arguments only the mandatory
|
|
arguments are supplied by this means.
|
|
)
|
|
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.
|
|
)
|
|
item(tt($)var(var))(
|
|
Print out the value of var literally; does not affect the calculation.
|
|
To use the value of var, omit the leading `tt($)'.
|
|
)
|
|
enditem()
|
|
|
|
See the comments in the function for a few extra tips.
|
|
)
|
|
findex(max)
|
|
findex(min)
|
|
findex(sum)
|
|
findex(zmathfunc)
|
|
xitem(tt(min+LPAR())var(arg)tt(, ...+RPAR()))
|
|
xitem(tt(max+LPAR())var(arg)tt(, ...+RPAR()))
|
|
xitem(tt(sum+LPAR())var(arg)tt(, ...+RPAR()))
|
|
item(tt(zmathfunc))(
|
|
The function tt(zmathfunc) defines the three mathematical functions
|
|
tt(min), tt(max), and tt(sum). The functions tt(min) and tt(max) take
|
|
one or more arguments. The function tt(sum) takes zero or more arguments.
|
|
Arguments can be of different types (ints and floats).
|
|
|
|
Not to be confused with the tt(zsh/mathfunc) module, described in
|
|
ifzman(the section `The zsh/mathfunc Module' in zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/mathfunc Module)).
|
|
)
|
|
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: tt(black), tt(red), tt(green), tt(yellow),
|
|
tt(blue), tt(magenta), tt(cyan), and tt(white). Each of these has codes for
|
|
foreground and background. In addition there are seven intensity attributes:
|
|
tt(bold), tt(faint), tt(standout), tt(underline), tt(blink), tt(reverse),
|
|
and tt(conceal). Finally, there are seven codes used to negate attributes:
|
|
tt(none) (reset all attributes to the defaults), tt(normal)
|
|
(neither bold nor faint), tt(no-standout), tt(no-underline), tt(no-blink),
|
|
tt(no-reverse), and tt(no-conceal).
|
|
|
|
Some terminals do not support all combinations of colors and intensities.
|
|
|
|
The associative arrays are:
|
|
|
|
startitem()
|
|
xitem(tt(color))
|
|
item(tt(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(tt(fg))
|
|
xitem(tt(fg_bold))
|
|
item(tt(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(tt(bg))
|
|
xitem(tt(bg_bold))
|
|
item(tt(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) [ tt(-x) var(num) ] 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. POSIX extended regular expressions are used,
|
|
unless the option tt(RE_MATCH_PCRE) has been set, in which case
|
|
Perl-compatible regular expressions are used
|
|
(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-btrfs)
|
|
findex(run-help-git)
|
|
findex(run-help-ip)
|
|
findex(run-help-openssl)
|
|
findex(run-help-p4)
|
|
findex(run-help-sudo)
|
|
findex(run-help-svk)
|
|
findex(run-help-svn)
|
|
xitem(tt(run-help-btrfs))
|
|
xitem(tt(run-help-git))
|
|
xitem(tt(run-help-ip))
|
|
xitem(tt(run-help-openssl))
|
|
xitem(tt(run-help-p4))
|
|
xitem(tt(run-help-sudo))
|
|
xitem(tt(run-help-svk))
|
|
item(tt(run-help-svn))(
|
|
Assistant functions for the
|
|
tt(btrfs),
|
|
tt(git),
|
|
tt(ip),
|
|
tt(openssl),
|
|
tt(p4),
|
|
tt(sudo),
|
|
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.
|
|
)
|
|
item(tt(tetriscurses))(
|
|
This is a port of the above to zcurses. The input handling is improved
|
|
a bit so that moving a block sideways doesn't automatically advance a
|
|
timestep, and the graphics use unicode block graphics.
|
|
|
|
This version does not save the game state between invocations, and is not
|
|
invoked as a widget, but rather as:
|
|
|
|
example(autoload -U tetriscurses
|
|
tetriscurses)
|
|
)
|
|
findex(zargs)
|
|
item(tt(zargs) [ var(option) ... tt(-)tt(-) ] [ var(input) ... ] [ tt(-)tt(-) var(command) [ var(arg) ... ] ])(
|
|
This function has a similar purpose to GNU xargs. 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 non-hidden plain files
|
|
in the current directory or its subdirectories:
|
|
|
|
example(autoload -U zargs
|
|
zargs -- **/*(.) -- ls -ld --)
|
|
|
|
The first and third occurrences of `tt(-)tt(-)' are used to mark the end
|
|
of options for tt(zargs) and tt(ls) respectively to guard against
|
|
filenames starting with `tt(-)', while the second is used to separate the
|
|
list of files from the command to run (`tt(ls -ld --)').
|
|
|
|
The first `tt(-)tt(-)' would also be needed if there was a chance the
|
|
list might be empty as in:
|
|
|
|
example(zargs -r -- ./*.back+LPAR()#qN+RPAR() -- rm -f)
|
|
|
|
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 -ld --)
|
|
|
|
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.
|
|
|
|
The options tt(-i), tt(-I), tt(-l), tt(-L), and tt(-n) differ slightly
|
|
from their usage in tt(xargs). There are no input lines for tt(zargs) to
|
|
count, so tt(-l) and tt(-L) count through the var(input) list, and tt(-n)
|
|
counts the number of arguments passed to each execution of var(command),
|
|
em(including) any var(arg) list. Also, any time tt(-i) or tt(-I) is used,
|
|
each var(input) is processed separately as if by `tt(-L) tt(1)'.
|
|
|
|
For details of the other tt(zargs) options, see the manref(xargs)(1) man page (but note
|
|
the difference in function between tt(zargs) and tt(xargs)) or run
|
|
tt(zargs) with the tt(-)tt(-help) option.
|
|
)
|
|
findex(zed)
|
|
xitem(tt(zed) [ tt(-f) [ tt(-x) var(num) ] ] 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. In this case the tt(-x) option specifies that leading
|
|
tabs indenting the function according to syntax should be converted into
|
|
the given number of spaces; `tt(-x 2)' is consistent with the layout
|
|
of functions distributed with the shell.
|
|
|
|
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)
|
|
redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ ))ifnztexi( )))
|
|
xitem(tt(zmv) [ tt(-finqQsvwW) ] [ tt(-C) | tt(-L) | tt(-M) | -{tt(p)|tt(P)} var(program) ] [ tt(-o) var(optstring) ])
|
|
item(SPACES()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 tt($1), tt($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.
|
|
|
|
In addition to pattern replacement, the variable tt($f) can be referred
|
|
to in the second (replacement) argument. This makes it possible to
|
|
use variable substitution to alter the argument; see examples below.
|
|
|
|
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. `tt(Y)' or `tt(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 tt(${1}) .. tt(${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).
|
|
var(program) will be split into words, so might be e.g. the name
|
|
of an archive tool plus a copy or rename subcommand.)
|
|
sitem(tt(-P) var(program))(As tt(-p) var(program), except that
|
|
var(program) does not accept a following tt(-)tt(-) to indicate the
|
|
end of options. In this case filenames must already be in a sane
|
|
form for the program in question.)
|
|
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.
|
|
|
|
example(zmv -v '* *' '${f// /_}')
|
|
|
|
This does exactly the same by referring to the file name stored in tt($f).
|
|
|
|
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) [ tt(+) 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' var(style1) var(value1) \
|
|
+ ':baz' var(style2) var(value2) \
|
|
+ ':frob' var(style3) var(value3))
|
|
|
|
This defines var(style1) with var(value1) for the context tt(:foo:bar) as usual,
|
|
but it also defines var(style2) with var(value2) for the context
|
|
tt(:foo:bar:baz) and var(style3) with var(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()
|