mirror of
git://git.code.sf.net/p/zsh/code
synced 2024-11-19 13:33:52 +01:00
856 lines
35 KiB
Plaintext
856 lines
35 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(Prompt Themes)
|
|
menu(ZLE Functions)
|
|
menu(Other Functions)
|
|
endmenu()
|
|
|
|
texinode(Utilities)(Prompt Themes)()(User Contributions)
|
|
sect(Utilities)
|
|
|
|
subsect(Accessing On-Line Help)
|
|
cindex(helpfiles utility)
|
|
|
|
The key sequence tt(ESC h) is normally bound by ZLE to execute the
|
|
tt(run-help) widget (see
|
|
ifzman(zmanref(zshzle))\
|
|
ifnzman(noderef(Zsh Line Editor))\
|
|
). This invokes the tt(run-help) command with the command word from the
|
|
current input line as its argument. By default, tt(run-help) is an alias
|
|
for the tt(man) command, so this often fails when the command word is a
|
|
shell builtin or a user-defined function. By redefining the tt(run-help)
|
|
alias, one can improve the on-line help provided by the shell.
|
|
|
|
The tt(helpfiles) utility, found in the tt(Util) directory of the
|
|
distribution, is a Perl program that can be used to process the zsh manual
|
|
to produce a separate help file for each shell builtin and for many other
|
|
shell features as well. The autoloadable tt(run-help) function, found in
|
|
tt(Functions/Misc), searches for these helpfiles and performs several
|
|
other tests to produce the most complete help possible for the command.
|
|
|
|
There may already be a directory of help files on your system; look in
|
|
tt(/usr/share/zsh) or tt(/usr/local/share/zsh) and subdirectories below
|
|
those, or ask your system administrator.
|
|
|
|
To create your own help files with tt(helpfiles), choose or create a
|
|
directory where the individual command help files will reside. For
|
|
example, you might choose tt(~/zsh_help). If you unpacked the zsh
|
|
distribution in your home directory, you would use the commands:
|
|
|
|
example(mkdir ~/zsh_help
|
|
cd ~/zsh_help
|
|
man zshall | colcrt - | \
|
|
perl ~/zsh-version()/Util/helpfiles)
|
|
|
|
findex(run-help, use of)
|
|
Next, to use the tt(run-help) function, you need to add lines something
|
|
like the following to your tt(.zshrc) or equivalent startup file:
|
|
|
|
example(unalias run-help
|
|
autoload run-help
|
|
HELPDIR=~/zsh_help)
|
|
|
|
vindex(HELPDIR)
|
|
The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
|
|
files. If your system already has a help file directory installed, set
|
|
tt(HELPDIR) to the path of that directory instead.
|
|
|
|
Note that in order for `tt(autoload run-help)' to work, the tt(run-help)
|
|
file must be in one of the directories named in your tt(fpath) array (see
|
|
ifzman(zmanref(zshparam))\
|
|
ifnzman(noderef(Parameters Used By The Shell))\
|
|
). This should already be the case if you have a standard zsh
|
|
installation; if it is not, copy tt(Functions/Misc/run-help) to an
|
|
appropriate directory.
|
|
|
|
subsect(Recompiling Functions)
|
|
|
|
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 element of tt(fpath), zsh won't check whether
|
|
any of its source files has changed.
|
|
|
|
The tt(zrecompile) autoloadable function, found in tt(Functions/Misc), can
|
|
be used to keep function digests up to date.
|
|
|
|
startitem()
|
|
findex(zrecompile)
|
|
xitem(tt(zrecompile) [ tt(-qt) ] [ var(name) ... ])
|
|
item(tt(zrecompile) [ tt(-qt) ] tt(-p) var(args) [ tt(-)tt(-) var(args) ... ])(
|
|
This tries to find tt(*.zwc) files and automatically re-compile them if at
|
|
least one of the original files is newer than the compiled file. This
|
|
works only if the names stored in the compiled files are full paths or are
|
|
relative to the directory that contains the tt(.zwc) file.
|
|
|
|
In the first form, each var(name) is the name of a compiled file or a
|
|
directory containing tt(*.zwc) files that should be checked. If no
|
|
arguments are given, the directories and tt(*.zwc) files in tt(fpath) are
|
|
used.
|
|
|
|
When tt(-t) is given, no compilation is performed, but a return status of
|
|
zero (true) is set if there are files that need to be re-compiled and
|
|
non-zero (false) otherwise. The tt(-q) option quiets the chatty output
|
|
that describes what tt(zrecompile) is doing.
|
|
|
|
Without the tt(-t) option, the return status is zero if all files that
|
|
needed re-compilation could be compiled and non-zero if compilation for at
|
|
least one of the files failed.
|
|
|
|
If the tt(-p) option is given, the var(args) are interepted 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(Dumping Shell State)
|
|
|
|
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()
|
|
|
|
texinode(Prompt Themes)(ZLE Functions)(Utilities)(User Contributions)
|
|
sect(Prompt Themes)
|
|
|
|
subsect(Installation)
|
|
|
|
You should make sure all the functions from the tt(Functions/Prompts)
|
|
directory of the source distribution are available; they all begin with
|
|
the string `tt(prompt_)' except for the special function`tt(promptinit)'.
|
|
You also need the `tt(colors)' function from tt(Functions/Misc). All of
|
|
these functions may already have been installed on your system; if not,
|
|
you will need to find them and copy them. The directory should appear as
|
|
one of the elements of the tt(fpath) array (this should already be the
|
|
case if they were installed), and at least the function tt(promptinit)
|
|
should be autoloaded; it will autoload the rest. Finally, to initialize
|
|
the use of the system you need to call the tt(promptinit) function. The
|
|
following code in your tt(.zshrc) will arrange for this; assume the
|
|
functions are stored in the directory tt(~/myfns):
|
|
|
|
example(fpath=(~/myfns $fpath)
|
|
autoload -U promptinit
|
|
promptinit)
|
|
|
|
subsect(Theme Selection)
|
|
|
|
Use the tt(prompt) command to select your preferred theme. This command
|
|
may be added to your tt(.zshrc) following the call to tt(promptinit) in
|
|
order to start zsh with a theme already selected.
|
|
|
|
startitem()
|
|
xitem(tt(prompt) [ tt(-c) | tt(-l) ])
|
|
xitem(tt(prompt) [ tt(-p) | tt(-h) ] [ var(theme) ... ])
|
|
item(tt(prompt) [ tt(-s) ] var(theme) [ var(arg) ... ])(
|
|
Set or examine the prompt theme. With no options and a var(theme)
|
|
argument, the theme with that name is set as the current theme. The
|
|
available themes are determined at run time; use the tt(-l) option to see
|
|
a list. The special var(theme) `tt(random)' selects at random one of the
|
|
available themes and sets your prompt to that.
|
|
|
|
In some cases the var(theme) may be modified by one or more arguments,
|
|
which should be given after the theme name. See the help for each theme
|
|
for descriptions of these arguments.
|
|
|
|
Options are:
|
|
|
|
startsitem()
|
|
sitem(tt(-c))(Show the currently selected theme and its parameters, if any.)
|
|
sitem(tt(-l))(List all available prompt themes.)
|
|
sitem(tt(-p))(Preview the theme named by var(theme), or all themes if no
|
|
var(theme) is given.)
|
|
sitem(tt(-h))(Show help for the theme named by var(theme), or for the
|
|
tt(prompt) function if no var(theme) is given.)
|
|
sitem(tt(-s))(Set var(theme) as the current theme and save state.)
|
|
endsitem()
|
|
)
|
|
item(tt(prompt_)var(theme)tt(_setup))(
|
|
Each available var(theme) has a setup function which is called by the
|
|
tt(prompt) function to install that theme. This function may define
|
|
other functions as necessary to maintain the prompt, including functions
|
|
used to preview the prompt or provide help for its use. You should not
|
|
normally call a theme's setup function directly.
|
|
)
|
|
enditem()
|
|
|
|
texinode(ZLE Functions)(Other Functions)(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()
|
|
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 to easily move the cursor to the other interesting
|
|
spots. It can be invoked repeatedly to cycle between all positions
|
|
reported by the completion system.
|
|
)
|
|
tindex(edit-command-line)
|
|
item(tt(edit-command-line))(
|
|
Edit the command line using your visual editor, as in tt(ksh).
|
|
|
|
example(bindkey -M vicmd v edit-command-line)
|
|
)
|
|
tindex(history-beginning-search-backward-end)
|
|
tindex(history-beginning-search-forward-end)
|
|
item(tt(history-search-end))(
|
|
This function implements the widgets
|
|
tt(history-beginning-search-backward-end) and
|
|
tt(history-beginning-search-forward-end). These commands work by first
|
|
calling the corresponding builtin widget (see
|
|
ifzman(`History Control' in zmanref(zshzle))\
|
|
ifnzman(noderef(History Control))\
|
|
) and then moving the cursor to the end of the line. The original cursor
|
|
position is remembered and restored before calling the builtin widget a
|
|
second time, so that the same search is repeated to look farther through
|
|
the history.
|
|
|
|
Although you tt(autoload) only one function, the commands to use it are
|
|
slightly different because it implements two widgets.
|
|
|
|
example(zle -N history-beginning-search-backward-end \
|
|
history-search-end
|
|
zle -N history-beginning-search-forward-end \
|
|
history-search-end
|
|
bindkey '\e^P' history-beginning-search-backward-end
|
|
bindkey '\e^N' history-beginning-search-forward-end)
|
|
)
|
|
tindex(incarg)
|
|
vindex(incarg, use of)
|
|
item(tt(incarg))(
|
|
Typing the keystrokes for this widget with the cursor placed on or to the
|
|
left of an integer causes that integer to be incremented by one. With a
|
|
numeric prefix argument, the number is incremented by the amount of the
|
|
argument (decremented if the prefix argument is negative). The shell
|
|
paramter tt(incarg) may be set to change the default increment 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-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(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)
|
|
)
|
|
findex(smart-insert-last-word)
|
|
item(tt(smart-insert-last-word))(
|
|
This function may replace the tt(insert-last-word) widget, like so:
|
|
|
|
example(zle -N insert-last-word smart-insert-last-word)
|
|
|
|
With a numeric prefix, 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)
|
|
)
|
|
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.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Other Functions)()(ZLE Functions)(User Contributions)
|
|
sect(Other Functions)
|
|
|
|
There are a large number of helpful functions in the tt(Functions/Misc)
|
|
directory of the zsh distribution. Most are very simple and do not
|
|
require documentation here, but a few are worthy of special mention.
|
|
|
|
subsect(Descriptions)
|
|
|
|
startitem()
|
|
findex(colors)
|
|
item(tt(colors))(
|
|
This function initializes several associative arrays to map color names to
|
|
(and from) the ANSI standard eight-color terminal codes. These are used
|
|
by the prompt theme system (ifzman(see above)\
|
|
ifnzman(noderef(Prompt Themes))). You seldom should need to run
|
|
tt(colors) more than once.
|
|
|
|
The eight base colors are: black, red, green, yellow, blue, magenta, cyan,
|
|
and white. Each of these has codes for foreground and background. In
|
|
addition there are eight intensity attributes: bold, faint, standout,
|
|
underline, blink, reverse, and conceal. Finally, there are six codes used
|
|
to negate attributes: none (reset all attributes to the defaults), normal
|
|
(neither bold nor faint), no-standout, no-underline, no-blink, and
|
|
no-reverse.
|
|
|
|
Some terminals do not support all combinations of colors and intensities.
|
|
|
|
The associative arrays are:
|
|
|
|
startitem()
|
|
xitem(color)
|
|
item(colour)(
|
|
Map all the color names to their integer codes, and integer codes to the
|
|
color names. The eight base names map to the foreground color codes, as
|
|
do names prefixed with `tt(fg-)', such as `tt(fg-red)'. Names prefixed
|
|
with `tt(bg-)', such as `tt(bg-blue)', refer to the background codes. The
|
|
reverse mapping from code to color yields base name for foreground codes
|
|
and the tt(bg-) form for backgrounds.
|
|
|
|
Although it is a misnomer to call them `colors', these arrays also map the
|
|
other fourteen attributes from names to codes and codes to names.
|
|
)
|
|
xitem(fg)
|
|
xitem(fg_bold)
|
|
item(fg_no_bold)(
|
|
Map the eight basic color names to ANSI terminal escape sequences that set
|
|
the corresponding foreground text properties. The tt(fg) sequences change
|
|
the color without changing the eight intensity attributes.
|
|
)
|
|
xitem(bg)
|
|
xitem(bg_bold)
|
|
item(bg_no_bold)(
|
|
Map the eight basic color names to ANSI terminal escape sequences that set
|
|
the corresponding background properties. The tt(bg) sequences change the
|
|
color without changing the eight intensity attributes.
|
|
)
|
|
enditem()
|
|
|
|
In addition, the scalar parameters tt(reset_color) and tt(bold_color) are
|
|
set to the ANSI terminal escapes that turn off all attributes and turn on
|
|
bold intensity, respectively.
|
|
)
|
|
findex(fned)
|
|
item(tt(fned) var(name))(
|
|
Same as tt(zed -f). This function does not appear in the zsh
|
|
distribution, but can be created by linking tt(zed) to the name tt(fned)
|
|
in some directory in your tt(fpath).
|
|
)
|
|
findex(is-at-least)
|
|
item(tt(is-at-least) var(needed) [ var(present) ])(
|
|
Perform a greater-than-or-equal-to comparison of two strings having the
|
|
format of a zsh version number; that is, a string of numbers and text with
|
|
segments separated by dots or dashes. If the var(present) string is not
|
|
provided, tt($ZSH_VERSION) is used. Segments are paired left-to-right in
|
|
the two strings with leading non-number parts ignored. If one string has
|
|
fewer segments than the other, the missing segments are considered zero.
|
|
|
|
This is useful in startup files to set options and other state that are
|
|
not available in all versions of zsh.
|
|
|
|
example(is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
|
|
is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
|
|
is-at-least 2.6-17 || print "You can't use is-at-least here.")
|
|
)
|
|
findex(nslookup)
|
|
item(tt(nslookup) [ var(arg) ... ])(
|
|
This wrapper function for the tt(nslookup) command requires the
|
|
tt(zsh/zpty) module (see
|
|
ifzman(zmanref(zshmodules))\
|
|
ifnzman(noderef(The zsh/zpty Module))\
|
|
). It behaves exactly like the standard tt(nslookup)
|
|
except that it provides customizable prompts (including a right-side
|
|
prompt) and completion of nslookup commands, host names, etc. (if you use
|
|
the function-based completion system). Completion styles may be set with
|
|
the context prefix `tt(:completion:nslookup)'.
|
|
|
|
See also the tt(pager), tt(prompt) and tt(rprompt) styles below.
|
|
)
|
|
item(tt(run-help))(
|
|
See `Accessing On-Line Help'
|
|
ifzman(above)\
|
|
ifnzman((noderef(Utilities))).
|
|
)
|
|
findex(zed)
|
|
item(tt(zed) [ tt(-f) ] var(name))(
|
|
This function uses the ZLE editor to edit a file or function. It rebinds
|
|
the return key to insert a line break, and adds bindings for `tt(^X^W)' in
|
|
the tt(emacs) keymap and `tt(ZZ)' in the tt(vicmd) keymap to accept (and
|
|
therefore write, in the case of a file) the edited file or function.
|
|
Keybindings are otherwise the standard ones; completion is available, and
|
|
styles may be set with the context prefix `tt(:completion:zed)'.
|
|
|
|
Only one var(name) argument is recognized (additional arguments are
|
|
ignored). If the tt(-f) option is given, the name is taken to be that of
|
|
a function; if the function is marked for autoloading, tt(zed) searches
|
|
for it in the tt(fpath) and loads it. Note that functions edited this way
|
|
are installed into the current shell, but em(not) written back to the
|
|
autoload file.
|
|
|
|
Without tt(-f), var(name) is the path name of the file to edit, which need
|
|
not exist; it is created on write, if necessary.
|
|
)
|
|
findex(zcp)
|
|
findex(zln)
|
|
xitem(tt(zcp) [ tt(-finqQvw) ] var(srcpat) var(dest))
|
|
item(tt(zln) [ tt(-finqQsvw) ] 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).
|
|
)
|
|
findex(zmv)
|
|
item(tt(zmv) [ tt(-finqQsvw) ] [ -C | -L | -M | -p var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )(
|
|
Move (usually, rename) files matching the pattern var(srcpat) to
|
|
corresponding files having names of the form given by var(dest), where
|
|
var(srcpat) contains parentheses surrounding patterns which will be
|
|
replaced in turn by $1, $2, ... in var(dest). For example,
|
|
|
|
example(zmv '(*).lis' '$1.txt')
|
|
|
|
renames `tt(foo.lis)' to `tt(foo.txt)', `tt(my.old.stuff.lis)' to
|
|
`tt(my.old.stuff.txt)', and so on.
|
|
|
|
The pattern is always treated as an tt(EXTENDED_GLOB) pattern. Any file
|
|
whose name is not changed by the substitution is simply ignored. Any
|
|
error (a substitution resulted in an empty string, two substitutions gave
|
|
the same result, the destination was an existing regular file and tt(-f)
|
|
was not given) causes the entire function to abort without doing anything.
|
|
|
|
Options:
|
|
|
|
startsitem()
|
|
sitem(tt(-f))(Force overwriting of destination files. Not currently
|
|
passed down to the tt(mv)/tt(cp)/tt(ln) command due to vagaries of
|
|
implementations (but you can use tt(-o-f) to do that).)
|
|
sitem(tt(-i))(Interactive: show each line to be executed and ask the user
|
|
whether to execute it. `Y' or `y' will execute it, anything else will
|
|
skip it. Note that you just need to type one character.)
|
|
sitem(tt(-n))(No execution: print what would happen, but don't do it.)
|
|
sitem(tt(-q))(Turn bare glob qualifiers off: now assumed by default, so
|
|
this has no effect.)
|
|
sitem(tt(-Q))(Force bare glob qualifiers on. Don't turn this on unless
|
|
you are actually using glob qualifiers in a pattern.)
|
|
sitem(tt(-s))(Symbolic, passed down to tt(ln); only works with tt(-L).)
|
|
sitem(tt(-v))(Verbose: print each command as it's being executed.)
|
|
sitem(tt(-w))(Pick out wildcard parts of the pattern, as described above,
|
|
and implicitly add parentheses for referring to them.)
|
|
sxitem(tt(-C))
|
|
sxitem(tt(-L))
|
|
sitem(tt(-M))(Force tt(cp), tt(ln) or tt(mv), respectively, regardless of
|
|
the name of the function.)
|
|
sitem(tt(-p) var(program))(Call var(program) instead of tt(cp), tt(ln) or
|
|
tt(mv). Whatever it does, it should at least understand the form
|
|
ifzman(`var(program) tt(-)tt(-) var(oldname) var(newname)')\
|
|
ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname)))
|
|
where var(oldname) and var(newname) are filenames generated by tt(zmv).)
|
|
sitem(tt(-o) var(optstring))(The var(optstring) is split into words and
|
|
passed down verbatim to the tt(cp), tt(ln) or tt(mv) command called to
|
|
perform the work. It should probably begin with a `tt(-)'.)
|
|
endsitem()
|
|
|
|
For more complete examples and other implementation details, see the
|
|
tt(zmv) source file, usually located in one of the directories named in
|
|
your tt(fpath), or in tt(Functions/Misc/zmv) in the zsh distribution.
|
|
)
|
|
item(tt(zrecompile))(
|
|
See `Recompiling Functions'
|
|
ifzman(above)\
|
|
ifnzman((noderef(Utilities))).
|
|
)
|
|
findex(zstyle+)
|
|
item(tt(zstyle+) var(context) var(style) var(value) [ + var(subcontext) var(style) var(value) ... ])(
|
|
This makes defining styles a bit simpler by using a single `tt(+)' as a
|
|
special token that allows you to append a context name to the previously
|
|
used context name. Like this:
|
|
|
|
example(zstyle+ ':foo:bar' style1 value1 \
|
|
+ ':baz' style2 value2 \
|
|
+ ':frob' style3 value3)
|
|
|
|
This defines `style1' with `value1' for the context tt(:foo:bar) as usual,
|
|
but it also defines `style2' with `value2' for the context
|
|
tt(:foo:bar:baz) and `style3' with `value3' for tt(:foo:bar:frob). Any
|
|
var(subcontext) may be the empty string to re-use the first context
|
|
unchanged.
|
|
)
|
|
enditem()
|
|
|
|
subsect(Styles)
|
|
|
|
startitem()
|
|
kindex(insert-tab, completion style)
|
|
item(tt(insert-tab))(
|
|
The tt(zed) function em(sets) this style in context `tt(:completion:zed:*)'
|
|
to turn off completion when tt(TAB) is typed at the beginning of a line.
|
|
You may override this by setting your own value for this context and style.
|
|
)
|
|
kindex(pager, nslookup style)
|
|
item(tt(pager))(
|
|
The tt(nslookup) function looks up this style in the context
|
|
`tt(:nslookup)' to determine the program used to display output that does
|
|
not fit on a single screen.
|
|
)
|
|
kindex(prompt, nslookup style)
|
|
kindex(rprompt, nslookup style)
|
|
xitem(tt(prompt))
|
|
item(tt(rprompt))(
|
|
The tt(nslookup) function looks up this style in the context
|
|
`tt(:nslookup)' to set the prompt and the right-side prompt, respectively.
|
|
The usual expansions for the tt(PS1) and tt(RPS1) parameters may be used
|
|
(see
|
|
ifzman(zmanref(zshmisc))\
|
|
ifnzman(noderef(Prompt Expansion))\
|
|
).
|
|
)
|
|
enditem()
|