Manual Pages for UNIX Darwin command on man zshcontrib

ZSHCONTRIB(1) ZSHCONTRIB(1)

NAME

zshcontrib - user contributions to zsh

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 signifi-

cant of these are documented here. For documentation on other contrib-

uted items such as shell functions, look for comments in the function source files. UUTTIILLIITTIIEESS

AAcccceessssiinngg OOnn-LLiinnee HHeellpp

The key sequence EESSCC hh is normally bound by ZLE to execute the rruunn-hheellpp

widget (see zshzle(1)). This invokes the rruunn-hheellpp command with the

command word from the current input line as its argument. By default,

rruunn-hheellpp is an alias for the mmaann command, so this often fails when the

command word is a shell builtin or a user-defined function. By

redefining the rruunn-hheellpp alias, one can improve the on-line help pro-

vided by the shell. The hheellppffiilleess utility, found in the UUttiill 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 rruunn-hheellpp function, found in FFuunncc-

ttiioonnss//MMiisscc, 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 //uussrr//sshhaarree//zzsshh or //uussrr//llooccaall//sshhaarree//zzsshh and subdirectories below those, or ask your system administrator.

To create your own help files with hheellppffiilleess, choose or create a direc-

tory where the individual command help files will reside. For example, you might choose ~~//zzsshhhheellpp. If you unpacked the zsh distribution in your home directory, you would use the commands: mmkkddiirr ~~//zzsshhhheellpp ccdd ~~//zzsshhhheellpp

mmaann zzsshhaallll || ccoollccrrtt - || \\

ppeerrll ~~//zzsshh-44..22..33//UUttiill//hheellppffiilleess

Next, to use the rruunn-hheellpp function, you need to add lines something

like the following to your ..zzsshhrrcc or equivalent startup file:

uunnaalliiaass rruunn-hheellpp

aauuttoollooaadd rruunn-hheellpp

HHEELLPPDDIIRR==~~//zzsshhhheellpp

The HHEELLPPDDIIRR parameter tells rruunn-hheellpp where to look for the help files.

If your system already has a help file directory installed, set HHEELLPPDDIIRR to the path of that directory instead.

Note that in order for `aauuttoollooaadd rruunn-hheellpp' to work, the rruunn-hheellpp file

must be in one of the directories named in your ffppaatthh array (see zsh-

param(1)). This should already be the case if you have a standard zsh

installation; if it is not, copy FFuunnccttiioonnss//MMiisscc//rruunn-hheellpp to an appro-

priate directory. RReeccoommppiilliinngg FFuunnccttiioonnss 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 zzccoommppiillee 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 ffppaatthh, zsh won't check whether any of its source files has changed. The zzrreeccoommppiillee autoloadable function, found in FFuunnccttiioonnss//MMiisscc, can be used to keep function digests up to date.

zzrreeccoommppiillee [ -qqtt ] [ name ... ]

zzrreeccoommppiillee [ -qqtt ] -pp args [ -- args ... ]

This tries to find **..zzwwcc 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 ..zzwwcc file. In the first form, each name is the name of a compiled file or a directory containing **..zzwwcc files that should be checked. If no arguments are given, the directories and **..zzwwcc files in ffppaatthh are used.

When -tt is given, no compilation is performed, but a return sta-

tus of zero (true) is set if there are files that need to be

re-compiled and non-zero (false) otherwise. The -qq option qui-

ets the chatty output that describes what zzrreeccoommppiillee is doing.

Without the -tt 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 -pp option is given, the args are interpreted as one or

more sets of arguments for zzccoommppiillee, separated by `--'. For

example:

zzrreeccoommppiillee -pp \\

-RR ~~//..zzsshhrrcc -- \\

-MM ~~//..zzccoommppdduummpp -- \\

~~//zzsshh//ccoommpp..zzwwcc ~~//zzsshh//CCoommpplleettiioonn//**//** This compiles ~~//..zzsshhrrcc into ~~//..zzsshhrrcc..zzwwcc if that doesn't exist or if it is older than ~~//..zzsshhrrcc. The compiled file will be marked for reading instead of mapping. The same is done for ~~//..zzccoommppdduummpp and ~~//..zzccoommppdduummpp..zzwwcc, but this compiled file is

marked for mapping. The last line re-creates the file

~~//zzsshh//ccoommpp..zzwwcc if any of the files matching the given pattern is newer than it.

Without the -pp option, zzrreeccoommppiillee does not create function

digests that do not already exist, nor does it add new functions to the digest.

The following shell loop is an example of a method for creating func-

tion digests for all functions in your ffppaatthh, assuming that you have write permission to the directories:

ffoorr ((((ii==11;; ii <<== $$##ffppaatthh;; ++++ii))));; ddoo

ddiirr==$$ffppaatthh[[ii]]

zzwwcc==$${{ddiirr::tt}}..zzwwcc

iiff [[[[ $$ddiirr ==== ((..||....)) |||| $$ddiirr ==== ((..||....))//** ]]]];; tthheenn

ccoonnttiinnuuee ffii

ffiilleess==(($$ddiirr//**((NN-..))))

iiff [[[[ -ww $$ddiirr::hh &&&& -nn $$ffiilleess ]]]];; tthheenn

ffiilleess==(($${{$${{((MM))ffiilleess%%//**//**}}##//}}))

iiff (( ccdd $$ddiirr::hh &&&&

zzrreeccoommppiillee -pp -UU -zz $$zzwwcc $$ffiilleess ));; tthheenn

ffppaatthh[[ii]]==$$ffppaatthh[[ii]]..zzwwcc

ffii ffii ddoonnee

The -UU and -zz options are appropriate for functions in the default zsh

installation ffppaatthh; you may need to use different options for your per-

sonal function directories. Once the digests have been created and your ffppaatthh modified to refer to

them, you can keep them up to date by running zzrreeccoommppiillee with no argu-

ments. KKeeyybbooaarrdd DDeeffiinniittiioonn 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 zzkkbbdd utility,

found in Functions/Misc, can help you quickly create key bindings for your configuration. Run zzkkbbdd either as an autoloaded function, or as a shell script:

zzsshh -ff ~~//zzsshh-44..22..33//FFuunnccttiioonnss//MMiisscc//zzkkbbdd

When you run zzkkbbdd, 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; zzkkbbdd warns you if it finds anything out of the ordinary, such as a Delete key that sends neither ^^HH nor ^^??.

The keystrokes read by zzkkbbdd are recorded as a definition for an asso-

ciative array named kkeeyy, written to a file in the subdirectory ..zzkkbbdd within either your HHOOMMEE or ZZDDOOTTDDIIRR directory. The name of the file is composed from the TTEERRMM, VVEENNDDOORR and OOSSTTYYPPEE parameters, joined by hyphens. You may read this file into your ..zzsshhrrcc or another startup file with

the "source" or "." commands, then reference the kkeeyy parameter in bind-

key commands, like this:

ssoouurrccee $${{ZZDDOOTTDDIIRR::-$$HHOOMMEE}}//..zzkkbbdd//$$TTEERRMM-$$VVEENNDDOORR-$$OOSSTTYYPPEE

[[[[ -nn $${{kkeeyy[[LLeefftt]]}} ]]]] &&&& bbiinnddkkeeyy ""$${{kkeeyy[[LLeefftt]]}}"" bbaacckkwwaarrdd-cchhaarr

[[[[ -nn $${{kkeeyy[[RRiigghhtt]]}} ]]]] &&&& bbiinnddkkeeyy ""$${{kkeeyy[[RRiigghhtt]]}}"" ffoorrwwaarrdd-cchhaarr

## eettcc..

Note that in order for `aauuttoollooaadd zzkkbbdd' to work, the zzkkddbb file must be in one of the directories named in your ffppaatthh array (see zshparam(1)).

This should already be the case if you have a standard zsh installa-

tion; if it is not, copy FFuunnccttiioonnss//MMiisscc//zzkkbbdd to an appropriate direc-

tory. DDuummppiinngg SShheellll SSttaattee 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 zsh(1)), but sometimes one of the zsh developers will need to recreate your environment in order to track the problem down.

The script named rreeppoorrtteerr, found in the UUttiill directory of the distribu-

tion, is provided for this purpose. (It is also possible to aauuttoollooaadd rreeppoorrtteerr, but rreeppoorrtteerr is not installed in ffppaatthh by default.) This script outputs a detailed dump of the shell state, in the form of

another script that can be read with `zzsshh -ff' to recreate that state.

To use rreeppoorrtteerr, read the script into your shell with the `..' command and redirect the output into a file:

.. ~~//zzsshh-44..22..33//UUttiill//rreeppoorrtteerr >> zzsshh..rreeppoorrtt

You should check the zzsshh..rreeppoorrtt 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 rreeppoorrtteerr 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 aalliiaasseess, ooppttiioonnss, and zzssttyylleess states may be useful because they include only changes from the defaults. The bbiinnddiinnggss state may be useful if you have created any of your own keymaps, because rreeppoorrtteerr 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 rreeppoorrtteerr, you should edit the results to remove unnecessary commands. Note that if you're using the new completion system, you should not dump the ffuunnccttiioonnss state to your startup files with rreeppoorrtteerr; use the ccoommppdduummpp function instead (see zshcompsys(1)). rreeppoorrtteerr [ state ... ] Print to standard output the indicated subset of the current shell state. The state arguments may be one or more of: aallll Output everything listed below. aalliiaasseess Output alias definitions. bbiinnddiinnggss Output ZLE key maps and bindings. ccoommpplleettiioonn

Output old-style ccoommppccttll commands. New completion is

covered by ffuunnccttiioonnss and zzssttyylleess. ffuunnccttiioonnss Output autoloads and function definitions. lliimmiittss Output lliimmiitt commands. ooppttiioonnss Output sseettoopptt commands. ssttyylleess Same as zzssttyylleess. vvaarriiaabblleess Output shell parameter assignments, plus eexxppoorrtt commands for any environment variables. zzssttyylleess Output zzssttyyllee commands. If the state is omitted, aallll is assumed.

With the exception of `aallll', every state can be abbreviated by any pre-

fix, even a single letter; thus aa is the same as aalliiaasseess, zz is the same as zzssttyylleess, etc. PPRROOMMPPTT TTHHEEMMEESS IInnssttaallllaattiioonn You should make sure all the functions from the FFuunnccttiioonnss//PPrroommppttss directory of the source distribution are available; they all begin with the string `pprroommpptt' except for the special function`pprroommppttiinniitt'. You also need the `ccoolloorrss' function from FFuunnccttiioonnss//MMiisscc. 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 ffppaatthh array (this should already be the case if they were installed), and at least the function pprroommppttiinniitt should be autoloaded; it will autoload the rest. Finally, to initialize the use of the system you need to call the pprroommppttiinniitt function. The following code in your ..zzsshhrrcc will arrange for this; assume the functions are stored in the directory ~~//mmyyffnnss:

ffppaatthh==((~~//mmyyffnnss $$ffppaatthh))

aauuttoollooaadd -UU pprroommppttiinniitt

pprroommppttiinniitt Theme Selection Use the pprroommpptt command to select your preferred theme. This command may be added to your ..zzsshhrrcc following the call to pprroommppttiinniitt in order to start zsh with a theme already selected.

pprroommpptt [ -cc | -ll ]

pprroommpptt [ -pp | -hh ] [ theme ... ]

pprroommpptt [ -ss ] theme [ arg ... ]

Set or examine the prompt theme. With no options and a theme argument, the theme with that name is set as the current theme.

The available themes are determined at run time; use the -ll

option to see a list. The special theme `rraannddoomm' selects at random one of the available themes and sets your prompt to that.

In some cases the theme may be modified by one or more argu-

ments, which should be given after the theme name. See the help for each theme for descriptions of these arguments. Options are:

-cc Show the currently selected theme and its parameters, if

any.

-ll List all available prompt themes.

-pp Preview the theme named by theme, or all themes if no

theme is given.

-hh Show help for the theme named by theme, or for the pprroommpptt

function if no theme is given.

-ss Set theme as the current theme and save state.

pprroommppttthemesseettuupp Each available theme has a setup function which is called by the pprroommpptt 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. ZZLLEE FFUUNNCCTTIIOONNSS WWiiddggeettss

These functions all implement user-defined ZLE widgets (see zshzle(1))

which can be bound to keystrokes in interactive shells. To use them, your ..zzsshhrrcc should contain lines of the form aauuttoollooaadd function

zzllee -NN function

followed by an appropriate bbiinnddkkeeyy command to associate the function with a key sequence. Suggested bindings are described below.

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 func-

tions described in the next section. The following is suffi-

cient:

aauuttoollooaadd -UU sseelleecctt-wwoorrdd-ssttyyllee

sseelleecctt-wwoorrdd-ssttyyllee bbaasshh

ffoorrwwaarrdd-wwoorrdd-mmaattcchh, bbaacckkwwaarrdd-wwoorrdd-mmaattcchh

kkiillll-wwoorrdd-mmaattcchh, bbaacckkwwaarrdd-kkiillll-wwoorrdd-mmaattcchh

ttrraannssppoossee-wwoorrddss-mmaattcchh, ccaappiittaalliizzee-wwoorrdd-mmaattcchh

uupp-ccaassee-wwoorrdd-mmaattcchh, ddoowwnn-ccaassee-wwoorrdd-mmaattcchh

sseelleecctt-wwoorrdd-ssttyyllee, mmaattcchh-wwoorrddss-bbyy-ssttyyllee

The eight `-mmaattcchh' 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

sseelleecctt-wwoorrdd-ssttyyllee, the way words are matched can be altered.

The simplest way of configuring the functions is to use

sseelleecctt-wwoorrdd-ssttyyllee, which can either be called as a normal func-

tion with the appropriate argument, or invoked as a user-defined

widget that will prompt for the first character of the word style to be used. The first time it is invoked, the eight

-mmaattcchh functions will automatically replace the builtin ver-

sions, so they do not need to be loaded explicitly.

The word styles available are as follows. Only the first char-

acter is examined. bbaasshh Word characters are alphanumeric characters only. nnoorrmmaall As in normal shell operation: word characters are alphanumeric characters plus any characters present in

the string given by the parameter $$WWOORRDDCCHHAARRSS.

sshheellll Words are complete shell command arguments, possibly including complete quoted strings, or any tokens special to the shell. wwhhiitteessppaaccee Words are any set of characters delimited by whitespace. ddeeffaauulltt Restore the default settings; this is usually the same as `nnoorrmmaall'. More control can be obtained using the zzssttyyllee command, as

described in zshmodules(1). Each style is looked up in the con-

text ::zzllee::widget where 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 sseelleecctt-wwoorrdd-ssttyyllee the appro-

priate contexts are ::zzllee::ffoorrwwaarrdd-wwoorrdd, and so on. The function

sseelleecctt-wwoorrdd-ssttyyllee itself always defines styles for the context

`::zzllee::**' which can be overridden by more specific (longer) pat-

terns as well as explicit contexts.

The style wwoorrdd-ssttyyllee specifies the rules to use. This may have

the following values. nnoorrmmaall Use the standard shell rules, i.e. alphanumerics and

$$WWOORRDDCCHHAARRSS, unless overridden by the styles wwoorrdd-cchhaarrss or

wwoorrdd-ccllaassss.

ssppeecciiffiieedd Similar to nnoorrmmaall, but only the specified characters, and not also alphanumerics, are considered word characters. uunnssppeecciiffiieedd The negation of specified. The given characters are those which will not be considered part of a word.

sshheellll Words are obtained by using the syntactic rules for gen-

erating shell command arguments. In addition, special tokens which are never command arguments such as `(())' are also treated as words. wwhhiitteessppaaccee

Words are whitespace-delimited strings of characters.

The first three of those styles usually use $$WWOORRDDCCHHAARRSS, but the

value in the parameter can be overridden by the style

wwoorrdd-cchhaarrss, which works in exactly the same way as $$WWOORRDDCCHHAARRSS.

In addition, the style wwoorrdd-ccllaassss uses character class syntax to

group characters and takes precedence over wwoorrdd-cchhaarrss if both

are set. The wwoorrdd-ccllaassss style does not include the surrounding

brackets of the character class; for example, `-::[[::aallnnuumm::]]' is a

valid wwoorrdd-ccllaassss to include all alphanumerics plus the charac-

ters `-' and `::'. Be careful including `]]', `^^' and `-' as

these are special inside character classes.

The final style is sskkiipp-cchhaarrss. This is mostly useful for ttrraannss-

ppoossee-wwoorrddss 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

zzssttyyllee ''::zzllee::ttrraannssppoossee-wwoorrddss'' sskkiipp-cchhaarrss 11

has been set, and ttrraannssppoossee-wwoorrddss-mmaattcchh is called with the cur-

sor on the X of ffooooXbbaarr, where X can be any character, then the resulting expression is bbaarrXffoooo. Here are some examples of use of the styles, actually taken from

the simplified interface in sseelleecctt-wwoorrdd-ssttyyllee:

zzssttyyllee ''::zzllee::**'' wwoorrdd-ssttyyllee ssttaannddaarrdd

zzssttyyllee ''::zzllee::**'' wwoorrdd-cchhaarrss ''''

Implements bash-style word handling for all widgets, i.e. only

alphanumerics are word characters; equivalent to setting the parameter WWOORRDDCCHHAARRSS empty for the given context.

ssttyyllee ''::zzllee::**kkiillll**'' wwoorrdd-ssttyyllee ssppaaccee

Uses space-delimited words for widgets with the word `kill' in

the name. Neither of the styles wwoorrdd-cchhaarrss nor wwoorrdd-ccllaassss is

used in this case. The word matching and all the handling of zzssttyyllee settings is

actually implemented by the function mmaattcchh-wwoorrddss-bbyy-ssttyyllee. This

can be used to create new user-defined widgets. The calling

function should set the local parameter ccuurrccoonntteexxtt to ::zzllee::wid-

get, create the local parameter mmaattcchheeddwwoorrddss and call

mmaattcchh-wwoorrddss-bbyy-ssttyyllee with no arguments. On return,

mmaattcchheeddwwoorrddss 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 charac-

ters specified by the sskkiipp-cchhaarrss style, (5) the word at or fol-

lowing the cursor (6) any non-word characters following that

word (7) the remainder of the line. Any of the elements may be an empty string; the calling function should test for this to decide whether it can perform its function. It is possible to pass options with arguments to

mmaattcchh-wwoorrddss-bbyy-ssttyyllee to override the use of styles. The options

are:

-ww word-style

-ss skip-chars

-cc word-class

-CC word-chars

For example, mmaattcchh-wwoorrddss-bbyy-ssttyyllee -ww sshheellll -cc 00 may be used to

extract the command argument around the cursor.

ddeelleettee-wwhhoollee-wwoorrdd-mmaattcchh

This is another function which works like the -mmaattcchh functions

described immediately above, i.e. using styles to decide the word boundaries. However, it is not a replacement for any existing function. The basic behaviour is to delete the word around the cursor. There is no numeric prefix handling; only the single word around the cursor is considered. If the widget contains the string kkiillll, the removed text will be placed in the cutbuffer for future yanking. This can be obtained by defining

kkiillll-wwhhoollee-wwoorrdd-mmaattcchh as follows:

zzllee -NN kkiillll-wwhhoollee-wwoorrdd-mmaattcchh ddeelleettee-wwhhoollee-wwoorrdd-mmaattcchh

and then binding the widget kkiillll-wwhhoollee-wwoorrdd-mmaattcchh.

ccooppyy-eeaarrlliieerr-wwoorrdd

This widget works like a combination of iinnsseerrtt-llaasstt-wwoorrdd and

ccooppyy-pprreevv-sshheellll-wwoorrdd. Repeated invocations of the widget

retrieve earlier words on the relevant history line. With a numeric argument N, insert the Nth word from the history line; N may be negative to count from the end of the line.

If iinnsseerrtt-llaasstt-wwoorrdd 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 wwiiddggeett 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 iinnsseerrtt-llaasstt-wwoorrdd.

ccyyccllee-ccoommpplleettiioonn-ppoossiittiioonnss

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 interest-

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

eeddiitt-ccoommmmaanndd-lliinnee

Edit the command line using your visual editor, as in kksshh.

bbiinnddkkeeyy -MM vviiccmmdd vv eeddiitt-ccoommmmaanndd-lliinnee

hhiissttoorryy-sseeaarrcchh-eenndd

This function implements the widgets hhiissttoorryy-bbeeggiinn-

nniinngg-sseeaarrcchh-bbaacckkwwaarrdd-eenndd and hhiissttoorryy-bbeeggiinnnniinngg-sseeaarrcchh-ffoorr-

wwaarrdd-eenndd. These commands work by first calling the correspond-

ing builtin widget (see `History Control' in zshzle(1)) 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 aauuttoollooaadd only one function, the commands to use it are slightly different because it implements two widgets.

zzllee -NN hhiissttoorryy-bbeeggiinnnniinngg-sseeaarrcchh-bbaacckkwwaarrdd-eenndd \\

hhiissttoorryy-sseeaarrcchh-eenndd

zzllee -NN hhiissttoorryy-bbeeggiinnnniinngg-sseeaarrcchh-ffoorrwwaarrdd-eenndd \\

hhiissttoorryy-sseeaarrcchh-eenndd

bbiinnddkkeeyy ''\\ee^^PP'' hhiissttoorryy-bbeeggiinnnniinngg-sseeaarrcchh-bbaacckkwwaarrdd-eenndd

bbiinnddkkeeyy ''\\ee^^NN'' hhiissttoorryy-bbeeggiinnnniinngg-sseeaarrcchh-ffoorrwwaarrdd-eenndd

hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh

The function hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh 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 ^^ to anchor the search to the start

of the line, and the last character may be $$ 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:

aauuttoollooaadd -UU hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh

zzllee -NN hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh-bbaacckkwwaarrdd hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh

zzllee -NN hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh-ffoorrwwaarrdd hhiissttoorryy-ppaatttteerrnn-sseeaarrcchh

uupp-lliinnee-oorr-bbeeggiinnnniinngg-sseeaarrcchh, ddoowwnn-lliinnee-oorr-bbeeggiinnnniinngg-sseeaarrcchh

These widgets are similar to the builtin functions

uupp-lliinnee-oorr-sseeaarrcchh and ddoowwnn-lliinnee-oorr-sseeaarrcchh: 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 hhiissttoorryy-bbeeggiinnnniinngg-sseeaarrcchh-bbaacckkwwaarrdd and -ffoorrwwaarrdd,

rather than the first word on the line. iinnccaarrgg Typing the keystrokes for this widget with the cursor placed on

or to the left of an integer causes that integer to be incre-

mented by one. With a numeric prefix argument, the number is incremented by the amount of the argument (decremented if the prefix argument is negative). The shell parameter iinnccaarrgg may be set to change the default increment something other than one. bbiinnddkkeeyy ''^^XX++'' iinnccaarrgg

iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd

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 ^^HH or DDEELL. Pressing return accepts the completion so far and returns you to normal editing (that is, the command line is not immediately executed). You can hit TTAABB to do normal completion, ^^GG to abort back to the state when you started, and ^^DD to list the matches. This works only with the new function based completion system.

bbiinnddkkeeyy ''^^XXii'' iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd

iinnsseerrtt-ffiilleess

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.

bbiinnddkkeeyy ''^^XXff'' iinnsseerrtt-ffiilleess

nnaarrrrooww-ttoo-rreeggiioonn [[ -pp pre ]] [[ -PP post ]]

[[ -SS statepm || -RR statepm ]] [[ -nn ]] [[ start end ]])

nnaarrrrooww-ttoo-rreeggiioonn-iinnvviissiibbllee

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.

nnaarrrrooww-ttoo-rreeggiioonn 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 rreeccuurrssiivvee-eeddiitt is performed

and the original widening status is then restored. Various

options and arguments are available when it is called as a func-

tion.

The options -pp pretext and -PP 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 -nn is also given, pretext or posttext will only be

inserted if there is text before or after the region respec-

tively which will be made invisible. Two numeric arguments may be given which will be used instead of the cursor and mark positions.

The option -SS statepm is used to narrow according to the other

options while saving the original state in the parameter with

name statepm, while the option -RR statepm is used to restore the

state from the parameter; note in both cases the name of the parameter is required. In the second case, other options and

arguments are irrelevant. When this method is used, no rreeccuurr-

ssiivvee-eeddiitt is performed; the calling widget should call this

function with the option -SS, perform its own editing on the com-

mand line or pass control to the user via `zzllee rreeccuurrssiivvee-eeddiitt',

then call this function with the option -RR. The argument

statepm must be a suitable name for an ordinary parameter, except that parameters beginning with the prefix nnttrr are

reserved for use within nnaarrrrooww-ttoo-rreeggiioonn. Typically the parame-

ter will be local to the calling function.

nnaarrrrooww-ttoo-rreeggiioonn-iinnvviissiibbllee is a simple widget which calls nnaarr-

rrooww-ttoo-rreeggiioonn with arguments which replace any text outside the

region with `......'. 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. llooccaall ssttaattee

nnaarrrrooww-ttoo-rreeggiioonn -pp $$''EEddiittiinngg rreessttrriicctteedd rreeggiioonn\\nn'' \\

-PP '''' -SS ssttaattee

zzllee rreeccuurrssiivvee-eeddiitt

nnaarrrrooww-ttoo-rreeggiioonn -RR ssttaattee

pprreeddiicctt-oonn

This set of functions implements predictive typing using history

search. After pprreeddiicctt-oonn, typing characters causes the editor

to look backward in the history for the first line beginning

with what you have typed so far. After pprreeddiicctt-ooffff, editing

returns to normal for the line found. In fact, you often don't

even need to use pprreeddiicctt-ooffff, because if the line doesn't match

something in the history, adding a key performs standard comple-

tion, and then inserts itself if no completions were found. However, editing in the middle of a line is liable to confuse prediction; see the ttooggggllee style below. With the function based completion system (which is needed for this), you should be able to type TTAABB at almost any point to

advance the cursor to the next ``interesting'' character posi-

tion (usually the end of the current word, but sometimes some-

where in the middle of the word). And of course as soon as the

entire line is what you want, you can accept with return, with-

out needing to move the cursor to the end first.

The first time pprreeddiicctt-oonn is used, it creates several additional

widget functions:

ddeelleettee-bbaacckkwwaarrdd-aanndd-pprreeddiicctt

Replaces the bbaacckkwwaarrdd-ddeelleettee-cchhaarr widget. You do not

need to bind this yourself.

iinnsseerrtt-aanndd-pprreeddiicctt

Implements predictive typing by replacing the sseellff-iinnsseerrtt

widget. You do not need to bind this yourself.

pprreeddiicctt-ooffff

Turns off predictive typing.

Although you aauuttoollooaadd only the pprreeddiicctt-oonn function, it is neces-

sary to create a keybinding for pprreeddiicctt-ooffff as well.

zzllee -NN pprreeddiicctt-oonn

zzllee -NN pprreeddiicctt-ooffff

bbiinnddkkeeyy ''^^XX^^ZZ'' pprreeddiicctt-oonn

bbiinnddkkeeyy ''^^ZZ'' pprreeddiicctt-ooffff

rreeaadd-ffrroomm-mmiinniibbuuffffeerr

This is most useful when called as a function from inside a wid-

get, 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,

eexxeeccuuttee-nnaammeedd-ccmmdd). The value is then returned to the calling

function in the parameter $$RREEPPLLYY and the editing buffer restored

to its previous state. If the read was aborted by a keyboard

break (typically ^^GG), the function returns status 1 and $$RREEPPLLYY

is not set. If one argument is supplied to the function it is taken as a prompt, otherwise `?? ' is used. If two arguments are supplied,

they are the prompt and the initial value of $$LLBBUUFFFFEERR, and if a

third argument is given it is the initial value of $$RRBBUUFFFFEERR.

This provides a default value and starting cursor placement.

Upon return the entire buffer is the value of $$RREEPPLLYY.

One option is available: `-kk num' specifies that 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 $$RREEPPLLYY, not the entire buffer. Note that unlike

the rreeaadd builtin 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 eexxee-

ccuutteedd-nnaammeedd-ccmmdd and similar functions while reading a value.

rreeppllaaccee-ssttrriinngg, rreeppllaaccee-ppaatttteerrnn

The function rreeppllaaccee-ssttrriinngg implements two 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 every-

where it occurs in the line editing buffer. If the widget name contains the word `ppaatttteerrnn', for example by

defining the widget using the command `zzllee -NN rreeppllaaccee-ppaatttteerrnn

rreeppllaaccee-ssttrriinngg', then the replacement is done by pattern match-

ing. 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 con-

tain parameter or command substitutions. Furthermore, a `&&' in the replacement string will be replaced with the matched source string, and a backquoted digit `\\N' will be replaced by the Nth parenthesised expression matched. The form `\\{{N}}' may be used to protect the digit from following digits. For example, starting from the line: pprriinntt TThhiiss lliinnee ccoonnttaaiinnss ffaann aanndd ffoonndd

and invoking rreeppllaaccee-ppaatttteerrnn with the source string `ff((??))nn' and

the replacment string `cc\\11rr' produces the not very useful line: pprriinntt TThhiiss lliinnee ccoonnttaaiinnss ccaarr aanndd ccoorrdd The range of the replacement string can be limited by using the

nnaarrrrooww-ttoo-rreeggiioonn-iinnvviissiibbllee widget. One limitation of the cur-

rent version is that uunnddoo will cycle through changes to the replacement and source strings before undoing the replacement itself.

ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd

This function may replace the iinnsseerrtt-llaasstt-wwoorrdd widget, like so:

zzllee -NN iinnsseerrtt-llaasstt-wwoorrdd ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd

With a numeric prefix, or when passed command line arguments in

a call from another widget, it behaves like iinnsseerrtt-llaasstt-wwoorrdd,

except that words in comments are ignored when IINNTTEERRAACCTTIIVVEECCOOMM-

MMEENNTTSS 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 alpha-

betic character, slash, or backslash. This definition may be overridden by use of the mmaattcchh style. The context used to look up the style is the widget name, so usually the context is

::iinnsseerrtt-llaasstt-wwoorrdd. However, you can bind this function to dif-

ferent widgets to use different patterns:

zzllee -NN iinnsseerrtt-llaasstt-aassssiiggnnmmeenntt ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd

zzssttyyllee ::iinnsseerrtt-llaasstt-aassssiiggnnmmeenntt mmaattcchh ''[[[[::aallpphhaa::]]]][[]][[[[::aallnnuumm::]]]]##==**''

bbiinnddkkeeyy ''\\ee=='' iinnsseerrtt-llaasstt-aassssiiggnnmmeenntt

SSttyylleess The behavior of several of the above widgets can be controlled by the use of the zzssttyyllee mechanism. In particular, widgets that interact with the completion system pass along their context to any completions that they invoke.

bbrreeaakk-kkeeyyss

This style is used by the iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd 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

iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd, this style is looked up using the

context `::iinnccrreemmeennttaall'. ccoommpplleetteerr

The iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd and iinnsseerrtt-aanndd-pprreeddiicctt 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: zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr \\ ccoommpplleettee ccoorrrreecctt aapppprrooxxiimmaattee zzssttyyllee ''::ccoommpplleettiioonn::iinnccrreemmeennttaall::**'' ccoommpplleetteerr \\ ccoommpplleettee ccoorrrreecctt zzssttyyllee ''::ccoommpplleettiioonn::pprreeddiicctt::**'' ccoommpplleetteerr \\ ccoommpplleettee It is a good idea to restrict the completers used in prediction, because they may be automatically invoked as you type. The lliisstt and mmeennuu completers should never be used with prediction. The aapppprrooxxiimmaattee, ccoorrrreecctt, eexxppaanndd, and mmaattcchh 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.

ccuurrssoorr The iinnsseerrtt-aanndd-pprreeddiicctt widget uses this style, in the context

`::pprreeddiicctt', to decide where to place the cursor after completion has been tried. Values are: ccoommpplleettee 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 `kkeeyy'.

kkeeyy The cursor is left after the nth occurrence of the char-

acter just inserted, where 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 comple-

tion code found out that no other characters need to be inserted at that position. Any other value for this style unconditionally leaves the cursor at the position where the completion code left it.

lliisstt When using the iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd widget, this style says

if the matches should be listed on every key press (if they fit

on the screen). Use the context prefix `::ccoommpplleettiioonn::iinnccrreemmeenn-

ttaall'.

The iinnsseerrtt-aanndd-pprreeddiicctt 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 aallwwaayyss. In this case the context is `::pprreeddiicctt' (not `::ccoommpplleettiioonn::pprreeddiicctt').

mmaattcchh This style is used by ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd to provide a pat-

tern (using full EEXXTTEENNDDEEDDGGLLOOBB syntax) that matches an interest-

ing word. The context is the name of the widget to which

ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd is bound (see above). The default behav-

ior of ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd is equivalent to:

zzssttyyllee ::iinnsseerrtt-llaasstt-wwoorrdd mmaattcchh ''**[[[[::aallpphhaa::]]//\\\\]]**''

However, you might want to include words that contain spaces:

zzssttyyllee ::iinnsseerrtt-llaasstt-wwoorrdd mmaattcchh ''**[[[[::aallpphhaa::]][[::ssppaaccee::]]//\\\\]]**''

Or include numbers as long as the word is at least two charac-

ters long:

zzssttyyllee ::iinnsseerrtt-llaasstt-wwoorrdd mmaattcchh ''**(([[[[::ddiiggiitt::]]]]??||[[[[::aallpphhaa::]]//\\\\]]))**''

The above example causes redirections like "2>" to be included.

pprroommpptt The iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd 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 PPSS11 and other prompt parameters:

%%cc Replaced by the name of the completer function that gen-

erated the matches (without the leading underscore).

%%ll When the lliisstt style is set, replaced by `......' if the list

of matches is too long to fit on the screen and with an empty string otherwise. If the lliisstt style is `false' or

not set, `%%ll' is always removed.

%%nn Replaced by the number of matches generated.

%%ss Replaced by `-nnoo mmaattcchh-', `-nnoo pprreeffiixx-', 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 pre-

fix, respectively.

%%uu Replaced by the unambiguous part of all matches, if there

is any, and if it is different from the word on the line.

Like `bbrreeaakk-kkeeyyss', this uses the `::iinnccrreemmeennttaall' context.

ssttoopp-kkeeyyss

This style is used by the iinnccrreemmeennttaall-ccoommpplleettee-wwoorrdd widget. Its

value is treated similarly to the one for the bbrreeaakk-kkeeyyss style

(and uses the same context: `::iinnccrreemmeennttaall'). However, in this case all keys matching the pattern given as its value will stop

incremental completion and will then execute their usual func-

tion.

ttooggggllee This boolean style is used by pprreeddiicctt-oonn and its related widgets

in the context `::pprreeddiicctt'. If set to one of the standard `true'

values, predictive typing is automatically toggled off in situa-

tions 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 pprreeddiicctt-ooffff.

vveerrbboossee

This boolean style is used by pprreeddiicctt-oonn and its related widgets

in the context `::pprreeddiicctt'. 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 combi-

nation with the ttooggggllee style. The default does not display these messages. wwiiddggeett This style is similar to the ccoommmmaanndd style: For widget functions that use zzllee 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 (not the name of

the calling function, because one function may be bound to mul-

tiple widget names).

zzssttyyllee ::ccooppyy-eeaarrlliieerr-wwoorrdd wwiiddggeett ssmmaarrtt-iinnsseerrtt-llaasstt-wwoorrdd

Check the documentation for the calling widget or function to determine whether the wwiiddggeett style is used. MMIIMMEE FFUUNNCCTTIIOONNSS Three functions are available to provide handling of files recognised by extension, for example to dispatch a file tteexxtt..ppss when executed as a command to an appropriate viewer.

zzsshh-mmiimmee-sseettuupp [[-ffllvv]]

zzsshh-mmiimmee-hhaannddlleerr

These two functions use the files ~~//..mmiimmee..ttyyppeess and //eettcc//mmiimmee..ttyyppeess, which associate types and extensions, as well as ~~//..mmaaiillccaapp and //eettcc//mmaaiillccaapp files, which associate types and

the programs that handle them. These are provided on many sys-

tems with the Multimedia Internet Mail Extensions.

To enable the system, the function zzsshh-mmiimmee-sseettuupp 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 zzsshh-mmiimmee-hhaannddlleerr should not

need to be called by the user.

The system works by setting up suffix aliases with `aalliiaass -ss'.

Suffix aliases already installed by the user will not be over-

written.

Repeated calls to zzsshh-mmiimmee-sseettuupp do not override the existing

mapping between suffixes and executable files unless the option

-ff is given. Note, however, that this does not override exist-

ing suffix aliases assigned to handlers other than zzsshh-mmiimmee-hhaann-

ddlleerr. Calling zzsshh-mmiimmee-sseettuupp with the option -ll lists the

existing mapping without altering it. Calling zzsshh-mmiimmee-sseettuupp

with the option -vv causes verbose output to be shown during the

setup operation.

The system respects the mmaaiillccaapp flags nneeeeddsstteerrmmiinnaall and ccooppii-

oouussoouuttppuutt, see mailcap(4). The functions use the following styles, which are defined with the zzssttyyllee builtin command (see zshmodules(1)). They should be

defined before zzsshh-mmiimmee-sseettuupp is run. The contexts used all

start with ::mmiimmee::, with additional components in some cases. It is recommended that a trailing ** (suitably quoted) be appended to style patterns in case the system is extended in future. Some examples are given below.

mime-types

A list of files in the format of ~~//..mmiimmee..ttyyppeess and //eettcc//mmiimmee..ttyyppeess to be read during setup, replacing the

default list which consists of those two files. The con-

text is ::mmiimmee::. A ++ in the list will be replaced by the default files. mailcap A list of files in the format of ~~//..mmaaiillccaapp and //eettcc//mmaaiillccaapp to be read during setup, replacing the

default list which consists of those two files. The con-

text is ::mmiimmee::. A ++ in the list will be replaced by the default files. handler Specifies a handler for a suffix; the suffix is given by

the context as ::mmiimmee::..suffix::, and the format of the han-

dler is exactly that in mmaaiillccaapp. Note in particular the `..' and trailing colon to distinguish this use of the context. This overrides any handler specified by the mmaaiillccaapp files. If the handler requires a terminal, the

ffllaaggss style should be set to include the word nneeeeddsstteerrmmii-

nnaall, or if the output is to be displayed through a pager (but not if the handler is itself a pager), it should include ccooppiioouussoouuttppuutt. flags Defines flags to go with a handler; the context is as for the hhaannddlleerr style, and the format is as for the flags in mmaaiillccaapp.

pager If set, will be used instead of $$PPAAGGEERR or mmoorree to handle

suffixes where the ccooppiioouussoouuttppuutt flag is set. The con-

text is as for hhaannddlleerr, i.e. ::mmiimmee::..suffix:: for handling a file with the given suffix. Examples: zzssttyyllee ''::mmiimmee::**'' mmaaiillccaapp ~~//..mmaaiillccaapp //uussrr//llooccaall//eettcc//mmaaiillccaapp

zzssttyyllee ''::mmiimmee::..ttxxtt'' hhaannddlleerr lleessss %%ss

zzssttyyllee ''::mmiimmee::..ttxxtt'' ffllaaggss nneeeeddsstteerrmmiinnaall

When zzsshh-mmiimmee-sseettuupp is subsequently run, it will look for mmaaiill-

ccaapp entries in the two files given. Files of suffix ..ttxxtt will be handled by running `lleessss file.txt'. The flag nneeeeddsstteerrmmiinnaall

is set to show that this program must run attached to a termi-

nal.

As there are several steps to dispatching a command, the follow-

ing should be checked if attempting to execute a file by exten-

sion ..ext does not have the expected effect. starteit() eit()(

The command `aalliiaass -ss ext' should show `ppss==zzsshh-mmiimmee-hhaannddlleerr'.

If it shows something else, another suffix alias was already

installed and was not overwritten. If it shows nothing, no han-

dler was installed: this is most likely because no handler was found in the ..mmiimmee..ttyyppeess and mmaaiillccaapp combination for ..eexxtt files. In that case, appropriate handling should be added to ~~//..mmiimmee..ttyyppeess and mmaaiillccaapp. ) eit()( If the extension is handled

by zzsshh-mmiimmee-hhaannddlleerr 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 zzsshh-mmiimmee-sseettuupp

-ll will show the handler and, if there are any, the flags. A %%ss

in the handler is replaced by the file (suitably quoted if nec-

essary). Check that the handler program listed lists and can be run in the way shown. Also check that the flags nneeeeddsstteerrmmiinnaall or ccooppiioouussoouuttppuutt 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 mmaaiillccaapp entry for such a program is:

tteexxtt//hhttmmll;; //uussrr//bbiinn//llyynnxx ''%%ss'';; nneeeeddsstteerrmmiinnaall

) endeit()

ppiicckk-wweebb-bbrroowwsseerr

This function is separate from the two MIME functions described above and can be assigned directly to a suffix:

aauuttoollooaadd -UU ppiicckk-wweebb-bbrroowwsseerr

aalliiaass -ss hhttmmll==ppiicckk-wweebb-bbrroowwsseerr

It is provided as an intelligent front end to dispatch a web browser. It will check if an X Windows display is available, and if so if there is already a browser running which can accept a remote connection. In that case, the file will be displayed in that browser; you should check explicitly if it has appeared in the running browser's window. Otherwise, it will start a new browser according to a builtin set of preferences.

Alternatively, ppiicckk-wweebb-bbrroowwsseerr can be run as a zsh script.

Two styles are available to customize the choice of browsers:

xx-bbrroowwsseerrss when running under the X Windows System, and

ttttyy-bbrroowwsseerrss otherwise. These are arrays in decreasing order of

preference consiting of the command name under which to start the browser. They are looked up in the context ::mmiimmee:: (which may be extended in future, so appending `**' is recommended). For example,

zzssttyyllee ''::mmiimmee::**'' xx-bbrroowwsseerrss ooppeerraa kkoonnqquueerroorr nneettssccaappee

specifies that ppiicckk-wweebb-bbrroowwsseerr should first look for a runing

instance of Opera, Konqueror or Netscape, in that order, and if it fails to find any should attempt to start Opera. OOTTHHEERR FFUUNNCCTTIIOONNSS There are a large number of helpful functions in the FFuunnccttiioonnss//MMiisscc directory of the zsh distribution. Most are very simple and do not require documentation here, but a few are worthy of special mention. DDeessccrriippttiioonnss ccoolloorrss 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 (see above). You seldom should need to run ccoolloorrss more than once. The eight base colors are: black, red, green, yellow, blue,

magenta, cyan, and white. Each of these has codes for fore-

ground 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: color

colour Map all the color names to their integer codes, and inte-

ger codes to the color names. The eight base names map to the foreground color codes, as do names prefixed with

`ffgg-', such as `ffgg-rreedd'. Names prefixed with `bbgg-', such

as `bbgg-bblluuee', refer to the background codes. The reverse

mapping from code to color yields base name for fore-

ground codes and the bbgg- 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 fgbold fgnobold Map the eight basic color names to ANSI terminal escape sequences that set the corresponding foreground text properties. The ffgg sequences change the color without changing the eight intensity attributes. bg bgbold bgnobold Map the eight basic color names to ANSI terminal escape

sequences that set the corresponding background proper-

ties. The bbgg sequences change the color without changing the eight intensity attributes. In addition, the scalar parameters rreesseettccoolloorr and bboollddccoolloorr are set to the ANSI terminal escapes that turn off all attributes and turn on bold intensity, respectively. ffnneedd name

Same as zzeedd -ff. This function does not appear in the zsh dis-

tribution, but can be created by linking zzeedd to the name ffnneedd in some directory in your ffppaatthh.

iiss-aatt-lleeaasstt 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, $$ZZSSHHVVEERRSSIIOONN is used. Seg-

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

iiss-aatt-lleeaasstt 33..11..66-1155 &&&& sseettoopptt NNOOGGLLOOBBAALLRRCCSS

iiss-aatt-lleeaasstt 33..11..00 &&&& sseettoopptt HHIISSTTRREEDDUUCCEEBBLLAANNKKSS

iiss-aatt-lleeaasstt 22..66-1177 |||| pprriinntt ""YYoouu ccaann''tt uussee iiss-aatt-lleeaasstt hheerree..""

nnssllooookkuupp [ arg ... ] This wrapper function for the nnssllooookkuupp command requires the zzsshh//zzppttyy module (see zshmodules(1)). It behaves exactly like the standard nnssllooookkuupp except that it provides customizable

prompts (including a right-side prompt) and completion of

nslookup commands, host names, etc. (if you use the func-

tion-based completion system). Completion styles may be set

with the context prefix `::ccoommpplleettiioonn::nnssllooookkuupp'. See also the ppaaggeerr, pprroommpptt and rrpprroommpptt styles below.

rruunn-hheellpp

See `Accessing On-Line Help' above.

tteettrriiss 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:

aauuttoollooaadd -UU tteettrriiss

zzllee -NN tteettrriiss

bbiinnddkkeeyy keys tteettrriiss

To start a game, execute the widget by typing the keys. What-

ever 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 `qq') or when you lose. If you quit in the middle of a game, the next invocation of the tteettrriiss widget will continue where you left off. If you lost, it will start a new game.

zzaarrggss [ option ... -- ] [ input ... ] [ -- command [ arg ... ] ]

This function works like GNU xargs, except that instead of read-

ing 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 zzaarrggss command itself, which are the same as those of xxaarrggss. The input list is the

collection of strings (often file names) that become the argu-

ments of the ccoommmmaanndd, analogous to the standard input of xxaarrggss. 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 iinnppuutt list in each run. If no command is provided, then no arg list may be provided, and

in that event the default command is `pprriinntt' with arguments `-rr

--'.

For example, to get a long llss listing of all plain files in the current directory or its subdirectories:

aauuttoollooaadd -UU zzaarrggss

zzaarrggss -- ****//**((..)) -- llss -ll

Note that `--' is used both to mark the end of the option list

and to mark the end of the input list, so it must appear twice whenever the input list may be empty. If there is guaranteed to be at least one input and the first input does not begin with a

`-', then the first `--' may be omitted.

In the event that the string `--' is or may be an input, the -ee

option may be used to change the end-of-inputs marker. Note

that this does not change the end-of-options marker. For exam-

ple, to use `....' as the marker:

zzaarrggss -ee.... -- ****//**((..)) .... llss -ll

This is a good choice in that example because no plain file can

be named `....', but the best end-marker depends on the circum-

stances. For details of the other zzaarrggss options, see xargs(1) or run

zzaarrggss with the --hheellpp option.

zzccaallcc [ expression ... ]

A reasonably powerful calculator based on zsh's arithmetic eval-

uation facility. The syntax is similar to that of formulae in

most programming languages; see the section `Arithmetic Evalua-

tion' in zshmisc(1) for details. The mathematical library zzsshh//mmaatthhffuunncc will be loaded if it is available; see the section `The zsh/mathfunc Module' in zshmodules(1). The mathematical

functions correspond to the raw system libraries, so trigonomet-

ric 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 `44>> ' is available as

$$44. Full command line editing, including the history of previ-

ous calculations, is available; the history is saved in the file ~~//..zzccaallcchhiissttoorryy. To exit, enter a blank line or type `qq' on its own. If arguments are given to zzccaallcc 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 PPII (3.14159...) and EE (2.71828...) are provided. Parameter assignment is possible, but note that all parameters will be put into the global namespace. An extra facility is provided for changing the default output

base. Use, for example, `[[##1166]]' to display hexadecimal output

preceded by an indication of the base, or `[[####1166]]' just to dis-

play the raw number in the given base. Bases themselves are

always specified in decimal. `[[##]]' restores the normal output

format. The output base can be initialised by passing the option

`-##base', for example `zzccaallcc -##1166' (the `##' may have to be

quoted, depending on the globbing options set). The prompt is configurable via the parameter ZZCCAALLCCPPRROOMMPPTT, which undergoes standard prompt expansion. The index of the current entry is stored locally in the first element of the array ppssvvaarr,

which can be referred to in ZZCCAALLCCPPRROOMMPPTT as `%%11vv'. The default

prompt is `%%11vv>> '.

See the comments in the function for a few extra tips.

zzeedd [ -ff ] name

zzeedd -bb This function uses the ZLE editor to edit a file or function.

Only one name argument is allowed. If the -ff option is given,

the name is taken to be that of a function; if the function is marked for autoloading, zzeedd searches for it in the ffppaatthh and loads it. Note that functions edited this way are installed into the current shell, but not written back to the autoload file.

Without -ff, 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 zzeedd and the

vi command keymap to zzeedd-vviiccmmdd. These will be copied from the

existing mmaaiinn and vviiccmmdd keymaps if they do not exist the first

time zzeedd is run. They can be used to provide special key bind-

ings used only in zed. If it creates the keymap, zzeedd rebinds the return key to insert a line break and `^^XX^^WW' to accept the edit in the zzeedd keymap, and

binds `ZZZZ' to accept the edit in the zzeedd-vviiccmmdd keymap.

The bindings alone can be installed by running `zzeedd -bb'. This

is suitable for putting into a startup file. Note that, if

rerun, this will overwrite the existing zzeedd and zzeedd-vviiccmmdd

keymaps. Completion is available, and styles may be set with the context prefix `::ccoommpplleettiioonn::zzeedd'.

A zle widget zzeedd-sseett-ffiillee-nnaammee is available. This can be called

by name from within zed using `\\eexx zzeedd-sseett-ffiillee-nnaammee' (note,

however, that because of zed's rebindings you will have to type ^^jj at the end instead of the return key), or can be bound to a

key in either of the zzeedd or zzeedd-vviiccmmdd keymaps after `zzeedd -bb' 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 `zzeedd -ff'.

While zzeedd-sseett-ffiillee-nnaammee is running, zed uses the keymap zzeedd-nnoorr-

mmaall-kkeeyymmaapp, 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.

zzccpp [ -ffiinnqqQQvvwwWW ] srcpat dest

zzllnn [ -ffiinnqqQQssvvwwWW ] srcpat dest

Same as zzmmvv -CC and zzmmvv -LL, respectively. These functions do not

appear in the zsh distribution, but can be created by linking zzmmvv to the names zzccpp and zzllnn in some directory in your ffppaatthh. zzkkbbdd See `Keyboard Definition' above.

zzmmvv [ -ffiinnqqQQssvvwwWW ] [ -C | -L | -M | -p program ] [ -o optstring ] src-

pat dest

Move (usually, rename) files matching the pattern srcpat to cor-

responding 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,

zzmmvv ''((**))..lliiss'' ''$$11..ttxxtt''

renames `ffoooo..lliiss' to `ffoooo..ttxxtt', `mmyy..oolldd..ssttuuffff..lliiss' to `mmyy..oolldd..ssttuuffff..ttxxtt', and so on. The pattern is always treated as an EEXXTTEENNDDEEDDGGLLOOBB 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 -ff was not given) causes the entire

function to abort without doing anything. Options:

-ff Force overwriting of destination files. Not currently

passed down to the mmvv/ccpp/llnn command due to vagaries of

implementations (but you can use -oo-ff to do that).

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

-nn No execution: print what would happen, but don't do it.

-qq Turn bare glob qualifiers off: now assumed by default, so

this has no effect.

-QQ Force bare glob qualifiers on. Don't turn this on unless

you are actually using glob qualifiers in a pattern.

-ss Symbolic, passed down to llnn; only works with -LL.

-vv Verbose: print each command as it's being executed.

-ww Pick out wildcard parts of the pattern, as described

above, and implicitly add parentheses for referring to them.

-WW Just like -ww, with the addition of turning wildcards in

the replacement pattern into sequential ${1} .. ${N} ref-

erences.

-CC

-LL

-MM Force ccpp, llnn or mmvv, respectively, regardless of the name

of the function.

-pp program

Call program instead of ccpp, llnn or mmvv. Whatever it does,

it should at least understand the form `program -- old-

name newname' where oldname and newname are filenames generated by zzmmvv.

-oo optstring

The optstring is split into words and passed down verba-

tim to the ccpp, llnn or mmvv command called to perform the

work. It should probably begin with a `-'.

For more complete examples and other implementation details, see the zzmmvv source file, usually located in one of the directories

named in your ffppaatthh, or in FFuunnccttiioonnss//MMiisscc//zzmmvv in the zsh distri-

bution. zzrreeccoommppiillee See `Recompiling Functions' above. zzssttyyllee++ 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: zzssttyyllee++ ''::ffoooo::bbaarr'' ssttyyllee11 vvaalluuee11 \\ ++ ''::bbaazz'' ssttyyllee22 vvaalluuee22 \\ ++ ''::ffrroobb'' ssttyyllee33 vvaalluuee33 This defines `style1' with `value1' for the context ::ffoooo::bbaarr as

usual, but it also defines `style2' with `value2' for the con-

text ::ffoooo::bbaarr::bbaazz and `style3' with `value3' for ::ffoooo::bbaarr::ffrroobb.

Any subcontext may be the empty string to re-use the first con-

text unchanged. SSttyylleess

iinnsseerrtt-ttaabb

The zzeedd function sets this style in context `::ccoommpplleettiioonn::zzeedd::**' to turn off completion when TTAABB is typed at the beginning of a line. You may override this by setting your own value for this context and style. ppaaggeerr The nnssllooookkuupp function looks up this style in the context `::nnssllooookkuupp' to determine the program used to display output that does not fit on a single screen. pprroommpptt rrpprroommpptt The nnssllooookkuupp function looks up this style in the context

`::nnssllooookkuupp' to set the prompt and the right-side prompt, respec-

tively. The usual expansions for the PPSS11 and RRPPSS11 parameters may be used (see zshmisc(1)). zsh 4.2.3 January 13, 2005 ZSHCONTRIB(1)