There are a large number of helpful functions in the 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.
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 (Prompt Themes). You seldom should need to run
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 seven intensity attributes:
bold
, faint
, standout
, underline
, blink
, reverse
,
and conceal
. Finally, there are seven codes used to negate attributes:
none
(reset all attributes to the defaults), normal
(neither bold nor faint), no-standout
, no-underline
, no-blink
,
no-reverse
, and no-conceal
.
Some terminals do not support all combinations of colors and intensities.
The associative arrays are:
color
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 ‘fg-
’, such as ‘fg-red
’. Names prefixed
with ‘bg-
’, such as ‘bg-blue
’, refer to the background codes. The
reverse mapping from code to color yields base name for foreground codes
and the 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.
fg
fg_bold
fg_no_bold
Map the eight basic color names to ANSI terminal escape sequences that set
the corresponding foreground text properties. The fg
sequences change
the color without changing the eight intensity attributes.
bg
bg_bold
bg_no_bold
Map the eight basic color names to ANSI terminal escape sequences that set
the corresponding background properties. The bg
sequences change the
color without changing the eight intensity attributes.
In addition, the scalar parameters reset_color
and bold_color
are
set to the ANSI terminal escapes that turn off all attributes and turn on
bold intensity, respectively.
fned
[ -x
num ] nameSame as zed -f
. This function does not appear in the zsh
distribution, but can be created by linking zed
to the name fned
in some directory in your fpath
.
histed
[ [ name ] size ]Same as zed -h
. This function does not appear in the zsh
distribution, but can be created by linking zed
to the name histed
in some directory in your fpath
.
is-at-least
needed [ 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 present string is not
provided, $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.
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."
nslookup
[ arg ... ]This wrapper function for the nslookup
command requires the
zsh/zpty
module (see
The zsh/zpty Module). It behaves exactly like the standard 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 ‘:completion:nslookup
’.
See also the pager
, prompt
and rprompt
styles below.
regexp-replace
var regexp replaceUse regular expressions to perform a global search and replace operation
on a variable. POSIX extended regular expressions (ERE) are used,
unless the option RE_MATCH_PCRE
has been set, in which case
Perl-compatible regular expressions are used
(this requires the shell to be linked against the pcre
library).
var is the name of the variable containing the string to be matched.
The variable will be modified directly by the function. The
variables MATCH
, MBEGIN
, MEND
, match
, mbegin
, mend
should be avoided as these are used by the regular expression code.
regexp is the regular expression to match against the string.
replace is the replacement text. This can contain parameter, command
and arithmetic expressions which will be replaced: in particular, a
reference to $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.
Note that if using POSIX EREs, the ^
or word boundary operators
(where available) may not work properly.
run-help
cmdThis function is designed to be invoked by the run-help
ZLE widget,
in place of the default alias. See ‘Accessing On-Line Help’
(Utilities) for setup instructions.
In the discussion which follows, if 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 cmd in the directory
named by the HELPDIR
parameter. If no file is found, an assistant
function, alias, or command named run-help-cmd
is sought. If
found, the assistant is executed with the rest of the current command line
(everything after the command name cmd) as its arguments. When
neither file nor assistant is found, the external command
‘man
cmd’ is run.
An example assistant for the "ssh" command:
run-help-ssh() { 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 Functions/Misc
directory. These must be autoloaded, or placed as executable scripts in
your search path, in order to be found and used by run-help
.
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:
autoload -U tetris zle -N tetris bindkey keys tetris
To start a game, execute the widget by typing the 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 ‘q
’) or when you lose.
If you quit in the middle of a game, the next invocation of the tetris
widget will continue where you left off. If you lost, it will start a new
game.
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:
autoload -U tetriscurses tetriscurses
zargs
[ option ... -
-
] [ input ... ] [ -
-
command [ 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 option list represents options of the zargs
command itself,
which are the same as those of xargs
. The input list is the
collection of strings (often file names) that become the arguments of the
command
, analogous to the standard input of xargs
. Finally, the
arg list consists of those arguments (usually options) that are
passed to the command each time it runs. The arg list precedes
the elements from the input
list in each run. If no command is
provided, then no arg list may be provided, and in that event the
default command is ‘print
’ with arguments ‘-r -
-
’.
For example, to get a long ls
listing of all non-hidden plain files
in the current directory or its subdirectories:
autoload -U zargs zargs -- **/*(.) -- ls -ld --
The first and third occurrences of ‘-
-
’ are used to mark the end
of options for zargs
and ls
respectively to guard against
filenames starting with ‘-
’, while the second is used to separate the
list of files from the command to run (‘ls -ld --
’).
The first ‘-
-
’ would also be needed if there was a chance the
list might be empty as in:
zargs -r -- ./*.back(#qN) -- rm -f
In the event that the string ‘-
-
’ is or may be an input, the
-e
option may be used to change the end-of-inputs marker. Note that
this does not change the end-of-options marker. For example, to use
‘..
’ as the marker:
zargs -e.. -- **/*(.) .. ls -ld --
This is a good choice in that example because no plain file can be named
‘..
’, but the best end-marker depends on the circumstances.
The options -i
, -I
, -l
, -L
, and -n
differ slightly
from their usage in xargs
. There are no input lines for zargs
to
count, so -l
and -L
count through the input list, and -n
counts the number of arguments passed to each execution of command,
including any arg list. Also, any time -i
or -I
is used,
each input is processed separately as if by ‘-L
1
’.
For details of the other zargs
options, see the xargs(1) man page (but note
the difference in function between zargs
and xargs
) or run
zargs
with the -
-help
option.
zed
[ -f
[ -x
num ] ] namezed
[ -h
[ name ] size ]zed -b
This function uses the ZLE editor to edit a file or function.
Only one name argument is allowed.
If the -f
option is given, the name is taken to be that of
a function; if the function is marked for autoloading, zed
searches
for it in the fpath
and loads it. Note that functions edited this way
are installed into the current shell, but not written back to the
autoload file. In this case the -x
option specifies that leading
tabs indenting the function according to syntax should be converted into
the given number of spaces; ‘-x 2
’ is consistent with the layout
of functions distributed with the shell.
Without -f
, name is the path name of the file to edit, which need
not exist; it is created on write, if necessary. With -h
, the file is
presumed to contain history events.
When no file name is provided for -h
the current shell history is edited
in place. The history is renumbered when zed exits successfully.
When editing history, multi-line events must have a trailing backslash on every line before the last.
While editing, the function sets the main keymap to zed
and the
vi command keymap to zed-vicmd
. These will be copied from the existing
main
and vicmd
keymaps if they do not exist the first time zed
is run. They can be used to provide special key bindings used only in zed.
If it creates the keymap, zed
rebinds the return key to insert a line
break and ‘^X^W
’ to accept the edit in the zed
keymap, and binds
‘ZZ
’ to accept the edit in the zed-vicmd
keymap.
The bindings alone can be installed by running ‘zed -b
’. This is
suitable for putting into a startup file. Note that, if rerun,
this will overwrite the existing zed
and zed-vicmd
keymaps.
Completion is available, and styles may be set with the context prefix
‘:completion:zed:
’.
A zle widget zed-set-file-name
is available. This can be called
by name from within zed using ‘\ex zed-set-file-name
’ or can be
bound to a key in either of the zed
or zed-vicmd
keymaps after
‘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 when invoked from ‘zed -f
’. The completion
context is changed to ‘:completion:zed-set-file-name:
’. When editing
the current history with ‘zed -h
’, the history is first updated and
then the file is written, but the global setting of HISTFILE
is not
altered.
While zed-set-file-name
is running, zed uses the keymap
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.
zcp
[ -finqQvwW
] srcpat destzln
[ -finqQsvwW
] srcpat destSame as zmv -C
and zmv -L
, respectively. These functions do not
appear in the zsh distribution, but can be created by linking zmv
to
the names zcp
and zln
in some directory in your fpath
.
zkbd
See ‘Keyboard Definition’ (Utilities).
zmv
[ -finqQsvwW
] [ -C
| -L
| -M
| -{p
|P
} program ] [ -o
optstring ]
srcpat destMove (usually, rename) files matching the pattern srcpat to
corresponding files having names of the form given by dest, where
srcpat contains parentheses surrounding patterns which will be
replaced in turn by $1
, $2
, ... in dest. For example,
zmv '(*).lis' '$1.txt'
renames ‘foo.lis
’ to ‘foo.txt
’, ‘my.old.stuff.lis
’ to
‘my.old.stuff.txt
’, and so on.
The pattern is always treated as an 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 -f
was not given) causes the entire function to abort without doing
anything.
In addition to pattern replacement, the variable $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:
-f
Force overwriting of destination files. Not currently
passed down to the mv
/cp
/ln
command due to vagaries of
implementations (but you can use -o-f
to do that).
-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.
-n
No execution: print what would happen, but don’t do it.
-q
Turn bare glob qualifiers off: now assumed by default, so this has no effect.
-Q
Force bare glob qualifiers on. Don’t turn this on unless you are actually using glob qualifiers in a pattern.
-s
Symbolic, passed down to ln
; only works with -L
.
-v
Verbose: print each command as it’s being executed.
-w
Pick out wildcard parts of the pattern, as described above, and implicitly add parentheses for referring to them.
-W
Just like -w
, with the addition of turning wildcards in
the replacement pattern into sequential ${1}
.. ${N}
references.
-C
-L
-M
Force cp
, ln
or mv
, respectively, regardless of
the name of the function.
-p
programCall program instead of cp
, ln
or
mv
. Whatever it does, it should at least understand the form
program-
-
oldname newname
where oldname and newname are filenames generated by zmv
.
program will be split into words, so might be e.g. the name
of an archive tool plus a copy or rename subcommand.
-P
programAs -p
program, except that
program does not accept a following -
-
to indicate the
end of options. In this case filenames must already be in a sane
form for the program in question.
-o
optstringThe optstring is split into words and
passed down verbatim to the cp
, ln
or mv
command called to
perform the work. It should probably begin with a ‘-
’.
Further examples:
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.
zmv -v '* *' '${f// /_}'
This does exactly the same by referring to the file name stored in $f
.
For more complete examples and other implementation details, see the
zmv
source file, usually located in one of the directories named in
your fpath
, or in Functions/Misc/zmv
in the zsh distribution.
zrecompile
See ‘Recompiling Functions’ (Utilities).
zstyle+
context style value [ +
subcontext style value ... ]This makes defining styles a bit simpler by using a single ‘+
’ as a
special token that allows you to append a context name to the previously
used context name. Like this:
zstyle+ ':foo:bar' style1 value1 \ +':baz' style2 value2 \ +':frob' style3 value3
This defines style1 with value1 for the context :foo:bar
as usual,
but it also defines style2 with value2 for the context
:foo:bar:baz
and style3 with value3 for :foo:bar:frob
. Any
subcontext may be the empty string to re-use the first context
unchanged.
insert-tab
The zed
function sets this style in context ‘:completion:zed:*
’
to turn off completion when TAB
is typed at the beginning of a line.
You may override this by setting your own value for this context and style.
pager
The nslookup
function looks up this style in the context
‘:nslookup
’ to determine the program used to display output that does
not fit on a single screen.
prompt
rprompt
The nslookup
function looks up this style in the context
‘:nslookup
’ to set the prompt and the right-side prompt, respectively.
The usual expansions for the PS1
and RPS1
parameters may be used
(see
Prompt Expansion).