26.12 Other Functions

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.

26.12.1 Descriptions

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 ] name

Same 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 replace

Use 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 cmd

This 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.

run-help-btrfs
run-help-git
run-help-ip
run-help-openssl
run-help-p4
run-help-sudo
run-help-svk
run-help-svn

Assistant functions for the btrfs, git, ip, openssl, p4, sudo, svk, and svn, commands.

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 ] ] name
zed [ -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 dest
zln [ -finqQsvwW ] srcpat dest

Same 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 dest

Move (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 program

Call 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 program

As -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 optstring

The 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.

26.12.2 Styles

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).