ZLE Functions
=============

Widgets
-------

These functions all implement user-defined ZLE widgets (see Zsh Line Editor)
which can be bound to keystrokes in interactive shells.
To use them, your .zshrc should contain lines of the form

     autoload FUNCTION
     zle -N FUNCTION

followed by an appropriate bindkey 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
     functions described in the next section.  The following is
     sufficient:

          autoload -U select-word-style
          select-word-style bash

forward-word-match, backward-word-match
kill-word-match, backward-kill-word-match
transpose-words-match, capitalize-word-match
up-case-word-match, down-case-word-match
select-word-style, match-words-by-style
     The eight `-match' functions are drop-in replacements for the
     builtin widgets without the suffix.  By default they behave in a
     similar way.  However, by the use of styles and the function
     select-word-style, the way words are matched can be altered.

     The simplest way of configuring the functions is to use
     select-word-style, which can either be called as a normal function
     with the appropriate argument, or invoked as a user-defined widget
     that will prompt for the first character of the word style to be
     used.  The first time it is invoked, the eight -match functions
     will automatically replace the builtin versions, so they do not
     need to be loaded explicitly.

     The word styles available are as follows.  Only the first character
     is examined.

    bash
          Word characters are alphanumeric characters only.

    normal
          As in normal shell operation:  word characters are
          alphanumeric characters plus any characters present in the
          string given by the parameter $WORDCHARS.

    shell
          Words are complete shell command arguments, possibly
          including complete quoted strings, or any tokens special to
          the shell.

    whitespace
          Words are any set of characters delimited by whitespace.

    default
          Restore the default settings; this is usually the same as
          `normal'.

     More control can be obtained using the zstyle command, as
     described in The zsh/zutil Module.  Each style is looked
     up in the context :zle: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 select-word-style the
     appropriate contexts are :zle:forward-word, and so on.  The
     function select-word-style itself always defines styles for the
     context `:zle:*' which can be overridden by more specific (longer)
     patterns as well as explicit contexts.

     The style word-style specifies the rules to use.  This may have the
     following values.

    normal
          Use the standard shell rules, i.e. alphanumerics and
          $WORDCHARS, unless overridden by the styles word-chars or
          word-class.

    specified
          Similar to normal, but _only_ the specified characters, and
          not also alphanumerics, are considered word characters.

    unspecified
          The negation of specified.  The given characters are those
          which will _not_ be considered part of a word.

    shell
          Words are obtained by using the syntactic rules for
          generating shell command arguments.  In addition, special
          tokens which are never command arguments such as `()' are
          also treated as words.

    whitespace
          Words are whitespace-delimited strings of characters.

     The first three of those styles usually use $WORDCHARS, but the
     value in the parameter can be overridden by the style word-chars,
     which works in exactly the same way as $WORDCHARS.  In addition,
     the style word-class uses character class syntax to group
     characters and takes precedence over word-chars if both are set.
     The word-class style does not include the surrounding brackets of
     the character class; for example, `-:[:alnum:]' is a valid
     word-class to include all alphanumerics plus the characters `-'
     and `:'.  Be careful including `]', `^' and `-' as these are
     special inside character classes.

     The final style is skip-chars.  This is mostly useful for
     transpose-words and similar functions.  If set, it gives a count of
     characters starting at the cursor position which will not be
     considered part of the word and are treated as space, regardless
     of what they actually are.  For example, if

          zstyle ':zle:transpose-words' skip-chars 1

     has been set, and transpose-words-match is called with the cursor
     on the X of fooXbar, where X can be any character, then the
     resulting expression is barXfoo.

     Here are some examples of use of the styles, actually taken from
     the simplified interface in select-word-style:

          zstyle ':zle:*' word-style standard
          zstyle ':zle:*' word-chars ''

     Implements bash-style word handling for all widgets, i.e. only
     alphanumerics are word characters; equivalent to setting the
     parameter WORDCHARS empty for the given context.

          style ':zle:*kill*' word-style space

     Uses space-delimited words for widgets with the word `kill' in the
     name.  Neither of the styles word-chars nor word-class is used in
     this case.

     The word matching and all the handling of zstyle settings is
     actually implemented by the function match-words-by-style.  This
     can be used to create new user-defined widgets.  The calling
     function should set the local parameter curcontext to :zle:WIDGET,
     create the local parameter matched_words and call
     match-words-by-style with no arguments.  On return, matched_words
     will be set to an array with the elements: (1) the start of the
     line (2) the word before the cursor (3) any non-word characters
     between that word and the cursor (4) any non-word character at the
     cursor position plus any remaining non-word characters before the
     next word, including all characters specified by the skip-chars
     style, (5) the word at or following the cursor (6) any non-word
     characters following that word (7) the remainder of the line.  Any
     of the elements may be an empty string; the calling function
     should test for this to decide whether it can perform its function.

delete-whole-word-match
     This is another function which works like the -match functions
     described immediately above, i.e. using styles to decide the word
     boundaries.  However, it is not a replacement for any existing
     function.

     The basic behaviour is to delete the word around the cursor.
     There is no numeric prefix handling; only the single word around
     the cursor is considered.  If the widget contains the string kill,
     the removed text will be placed in the cutbuffer for future
     yanking.  This can be obtained by defining kill-whole-word-match
     as follows:

          zle -N kill-whole-word-match delete-whole-word-match

     and then binding the widget kill-whole-word-match.

copy-earlier-word
     This widget works like a combination of insert-last-word and
     copy-prev-shell-word.  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 insert-last-word has been used to retrieve the last word on a
     previous history line, repeated invocations will replace that word
     with earlier words from the same line.

     Otherwise, the widget applies to words on the line currently being
     edited.  The widget style can be set to the name of another widget
     that should be called to retrieve words.  This widget must accept
     the same three arguments as insert-last-word.

cycle-completion-positions
     After inserting an unambiguous string into the command line, the
     new function based completion system may know about multiple
     places in this string where characters are missing or differ from
     at least one of the possible matches.  It will then place the
     cursor on the position it considers to be the most interesting
     one, i.e. the one where one can disambiguate between as many
     matches as possible with as little typing as possible.

     This widget allows the cursor to be easily moved to the other
     interesting spots.  It can be invoked repeatedly to cycle between
     all positions reported by the completion system.

edit-command-line
     Edit the command line using your visual editor, as in ksh.

          bindkey -M vicmd v edit-command-line

history-search-end
     This function implements the widgets
     history-beginning-search-backward-end and
     history-beginning-search-forward-end.  These commands work by first
     calling the corresponding builtin widget (see History Control)
     and then moving the cursor to the end of the line.  The
     original cursor position is remembered and restored before calling
     the builtin widget a second time, so that the same search is
     repeated to look farther through the history.

     Although you autoload only one function, the commands to use it are
     slightly different because it implements two widgets.

          zle -N history-beginning-search-backward-end \
                 history-search-end
          zle -N history-beginning-search-forward-end \
                 history-search-end
          bindkey '\e^P' history-beginning-search-backward-end
          bindkey '\e^N' history-beginning-search-forward-end

up-line-or-beginning-search, down-line-or-beginning-search
     These widgets are similar to the builtin functions
     up-line-or-search and down-line-or-search:  if in a multiline
     buffer they move up or down within the buffer, otherwise they
     search for a history line matching the start of the current line.
     In this case, however, they search for a line which matches the
     current line up to the current cursor position, in the manner of
     history-beginning-search-backward and -forward, rather than the
     first word on the line.

incarg
     Typing the keystrokes for this widget with the cursor placed on or
     to the left of an integer causes that integer to be incremented by
     one.  With a numeric prefix argument, the number is incremented by
     the amount of the argument (decremented if the prefix argument is
     negative).  The shell parameter incarg may be set to change the
     default increment something other than one.

          bindkey '^X+' incarg

incremental-complete-word
     This allows incremental completion of a word.  After starting this
     command, a list of completion choices can be shown after every
     character you type, which you can delete with ^H or DEL.  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 TAB to do normal completion, ^G to abort back to the
     state when you started, and ^D to list the matches.

     This works only with the new function based completion system.

          bindkey '^Xi' incremental-complete-word

insert-files
     This function allows you type a file pattern, and see the results
     of the expansion at each step.  When you hit return, all
     expansions are inserted into the command line.

          bindkey '^Xf' insert-files

narrow-to-region [ -p PRE ] [ -P POST ]
[ -S STATEPM | -R STATEPM ] [ -n ] [ START END ])
narrow-to-region-invisible
     Narrow the editable portion of the buffer to the region between
     the cursor and the mark, which may be in either order.  The region
     may not be empty.

     narrow-to-region may be used as a widget or called as a function
     from a user-defined widget; by default, the text outside the
     editable area remains visible.  A recursive-edit is performed and
     the original widening status is then restored.  Various options
     and arguments are available when it is called as a function.

     The options -p PRETEXT and -P 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 -n is also given, PRETEXT or POSTTEXT will only be
     inserted if there is text before or after the region respectively
     which will be made invisible.

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

     The option -S STATEPM is used to narrow according to the other
     options while saving the original state in the parameter with name
     STATEPM, while the option -R 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 recursive-edit is
     performed; the calling widget should call this function with the
     option -S, perform its own editing on the command line or pass
     control to the user via `zle recursive-edit', then call this
     function with the option -R.  The argument STATEPM must be a
     suitable name for an ordinary parameter, except that parameters
     beginning with the prefix _ntr_ are reserved for use within
     narrow-to-region.  Typically the parameter will be local to the
     calling function.

     narrow-to-region-invisible is a simple widget which calls
     narrow-to-region 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.
          local state
          narrow-to-region -p $'Editing restricted region\n' \
            -P '' -S state
          zle recursive-edit
          narrow-to-region -R state

predict-on
     This set of functions implements predictive typing using history
     search.  After predict-on, typing characters causes the editor to
     look backward in the history for the first line beginning with
     what you have typed so far.  After predict-off, editing returns to
     normal for the line found.  In fact, you often don't even need to
     use predict-off, because if the line doesn't match something in
     the history, adding a key performs standard completion, and then
     inserts itself if no completions were found.  However, editing in
     the middle of a line is liable to confuse prediction; see the
     toggle style below.

     With the function based completion system (which is needed for
     this), you should be able to type TAB at almost any point to
     advance the cursor to the next ``interesting'' character position
     (usually the end of the current word, but sometimes somewhere in
     the middle of the word).  And of course as soon as the entire line
     is what you want, you can accept with return, without needing to
     move the cursor to the end first.

     The first time predict-on is used, it creates several additional
     widget functions:

    delete-backward-and-predict
          Replaces the backward-delete-char widget.  You do not need to
          bind this yourself.

    insert-and-predict
          Implements predictive typing by replacing the self-insert
          widget.  You do not need to bind this yourself.

    predict-off
          Turns off predictive typing.

     Although you autoload only the predict-on function, it is
     necessary to create a keybinding for predict-off as well.

          zle -N predict-on
          zle -N predict-off
          bindkey '^X^Z' predict-on
          bindkey '^Z' predict-off

read-from-minibuffer
     This is most useful when called as a function from inside a
     widget, but will work correctly as a widget in its own right.  It
     prompts for a value below the current command line; a value may be
     input using all of the standard zle operations (and not merely the
     restricted set available when executing, for example,
     execute-named-cmd).  The value is then returned to the calling
     function in the parameter $REPLY and the editing buffer restored
     to its previous state.  If the read was aborted by a keyboard
     break (typically ^G), the function returns status 1 and $REPLY is
     not set.  If an argument is supplied to the function it is taken
     as a prompt, otherwise `? ' is used.

     One option is available: `-k NUM' specifies that NUM characters
     are to be read instead of a whole line.  The line editor is not
     invoked recursively in this case.  Note that unlike the read
     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
     executed-named-cmd and similar functions while reading a value.

replace-string, replace-pattern
     The function replace-string 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
     everywhere it occurs in the line editing buffer.

     If the widget name contains the word `pattern', for example by
     defining the widget using the command `zle -N replace-pattern
     replace-string', then the replacement is done by pattern matching.
     All zsh extended globbing patterns can be used in the source
     string; note that unlike filename generation the pattern does not
     need to match an entire word, nor do glob qualifiers have any
     effect.  In addition, the replacement string can contain parameter
     or command substitutions.  Furthermore, a `&' 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:

          print This line contains fan and fond

     and invoking replace-pattern with the source string `f(?)n' and
     the replacment string `c\1r' produces the not very useful line:

          print This line contains car and cord

     The range of the replacement string can be limited by using the
     narrow-to-region-invisible widget.  One limitation of the current
     version is that undo will cycle through changes to the replacement
     and source strings before undoing the replacement itself.

smart-insert-last-word
     This function may replace the insert-last-word widget, like so:

          zle -N insert-last-word smart-insert-last-word

     With a numeric prefix, or when passed command line arguments in a
     call from another widget, it behaves like insert-last-word, except
     that words in comments are ignored when INTERACTIVE_COMMENTS is
     set.

     Otherwise, the rightmost ``interesting'' word from the previous
     command is found and inserted.  The default definition of
     ``interesting'' is that the word contains at least one alphabetic
     character, slash, or backslash.  This definition may be overridden
     by use of the match style.  The context used to look up the style
     is the widget name, so usually the context is :insert-last-word.
     However, you can bind this function to different widgets to use
     different patterns:

          zle -N insert-last-assignment smart-insert-last-word
          zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
          bindkey '\e=' insert-last-assignment

Styles
------

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

break-keys
     This style is used by the incremental-complete-word widget. Its
     value should be a pattern, and all keys matching this pattern will
     cause the widget to stop incremental completion without the key
     having any further effect. Like all styles used directly by
     incremental-complete-word, this style is looked up using the
     context `:incremental'.

completer
     The incremental-complete-word and insert-and-predict widgets set
     up their top-level context name before calling completion.  This
     allows one to define different sets of completer functions for
     normal completion and for these widgets.  For example, to use
     completion, approximation and correction for normal completion,
     completion and correction for incremental completion and only
     completion for prediction one could use:

          zstyle ':completion:*' completer \
                  _complete _correct _approximate
          zstyle ':completion:incremental:*' completer \
                  _complete _correct
          zstyle ':completion:predict:*' completer \
                  _complete

     It is a good idea to restrict the completers used in prediction,
     because they may be automatically invoked as you type.  The _list
     and _menu completers should never be used with prediction.  The
     _approximate, _correct, _expand, and _match completers may be
     used, but be aware that they may change characters anywhere in the
     word behind the cursor, so you need to watch carefully that the
     result is what you intended.

cursor
     The insert-and-predict widget uses this style, in the context
     `:predict', to decide where to place the cursor after completion
     has been tried.  Values are:

    complete
          The cursor is left where it was when completion finished, but
          only if it is after a character equal to the one just
          inserted by the user.  If it is after another character, this
          value is the same as `key'.

    key
          The cursor is left after the Nth occurrence of the character
          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 completion 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.

list
     When using the incremental-complete-word widget, this style says
     if the matches should be listed on every key press (if they fit on
     the screen).  Use the context prefix `:completion:incremental'.

     The insert-and-predict widget uses this style to decide if the
     completion should be shown even if there is only one possible
     completion.  This is done if the value of this style is the string
     always.  In this case the context is `:predict' (_not_
     `:completion:predict').

match
     This style is used by smart-insert-last-word to provide a pattern
     (using full EXTENDED_GLOB syntax) that matches an interesting word.
     The context is the name of the widget to which
     smart-insert-last-word is bound (see above).  The default behavior
     of smart-insert-last-word is equivalent to:

          zstyle :insert-last-word match '*[[:alpha:]/\\]*'

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

          zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*'

     Or include numbers as long as the word is at least two characters
     long:

          zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*'

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

prompt
     The incremental-complete-word widget shows the value of this style
     in the status line during incremental completion.  The string
     value may contain any of the following substrings in the manner of
     the PS1 and other prompt parameters:

    %c
          Replaced by the name of the completer function that generated
          the matches (without the leading underscore).

    %l
          When the list 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 list style is `false' or not set,
          `%l' is always removed.

    %n
          Replaced by the number of matches generated.

    %s
          Replaced by `-no match-', `-no prefix-', or an empty string
          if there is no completion matching the word on the line, if
          the matches have no common prefix different from the word on
          the line, or if there is such a common prefix, respectively.

    %u
          Replaced by the unambiguous part of all matches, if there is
          any, and if it is different from the word on the line.

     Like `break-keys', this uses the `:incremental' context.

stop-keys
     This style is used by the incremental-complete-word widget.  Its
     value is treated similarly to the one for the break-keys style
     (and uses the same context: `:incremental').  However, in this
     case all keys matching the pattern given as its value will stop
     incremental completion and will then execute their usual function.

toggle
     This boolean style is used by predict-on and its related widgets in
     the context `:predict'.  If set to one of the standard `true'
     values, predictive typing is automatically toggled off in
     situations where it is unlikely to be useful, such as when editing
     a multi-line buffer or after moving into the middle of a line and
     then deleting a character.  The default is to leave prediction
     turned on until an explicit call to predict-off.

verbose
     This boolean style is used by predict-on and its related widgets in
     the context `:predict'.  If set to one of the standard `true'
     values, these widgets display a message below the prompt when the
     predictive state is toggled.  This is most useful in combination
     with the toggle style.  The default does not display these
     messages.

widget
     This style is similar to the command style: For widget functions
     that use zle to call other widgets, this style can sometimes be
     used to override the widget which is called.  The context for this
     style is the name of the calling widget (_not_ the name of the
     calling function, because one function may be bound to multiple
     widget names).

          zstyle :copy-earlier-word widget smart-insert-last-word

     Check the documentation for the calling widget or function to
     determine whether the widget style is used.

MIME Functions
==============

Three functions are available to provide handling of files recognised by
extension, for example to dispatch a file text.ps when executed as a
command to an appropriate viewer.

zsh-mime-setup [-flv]
zsh-mime-handler
     These two functions use the files ~/.mime.types and
     /etc/mime.types, which associate types and extensions, as well as
     ~/.mailcap and /etc/mailcap files, which associate types and the
     programs that handle them.  These are provided on many systems
     with the Multimedia Internet Mail Extensions.

     To enable the system, the function zsh-mime-setup should be
     autoloaded and run.  This allows files with extensions to be
     treated as executable; such files be completed by the function
     completion system.  The function zsh-mime-handler should not need
     to be called by the user.

     The system works by setting up suffix aliases with `alias -s'.
     Suffix aliases already installed by the user will not be
     overwritten.

     Repeated calls to zsh-mime-setup do not override the existing
     mapping between suffixes and executable files unless the option -f
     is given.  Note, however, that this does not override existing
     suffix aliases assigned to handlers other than zsh-mime-handler.
     Calling zsh-mime-setup with the option -l lists the existing
     mapping without altering it.  Calling zsh-mime-setup with the
     option -v causes verbose output to be shown during the setup
     operation.

     The system respects the mailcap flags needsterminal and
     copiousoutput, see man page mailcap(4).

     The functions use the following styles, which are defined with the
     zstyle builtin command (see The zsh/zutil Module).  They
     should be defined before zsh-mime-setup is run.  The contexts used
     all start with :mime:, 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 ~/.mime.types and
          /etc/mime.types to be read during setup, replacing the
          default list which consists of those two files.  The context
          is :mime:.

    mailcap
          A list of files in the format of ~/.mailcap and /etc/mailcap
          to be read during setup, replacing the default list which
          consists of those two files.  The context is :mime:.

    handler
          Specifies a handler for a suffix; the suffix is given by the
          context as :mime:.SUFFIX:, and the format of the handler is
          exactly that in mailcap.  Note in particular the `.' and
          trailing colon to distinguish this use of the context.  This
          overrides any handler specified by the mailcap files.  If the
          handler requires a terminal, the flags style should be set to
          include the word needsterminal, or if the output is to be
          displayed through a pager (but not if the handler is itself a
          pager), it should include copiousoutput.

    flags
          Defines flags to go with a handler; the context is as for the
          handler style, and the format is as for the flags in mailcap.

    pager
          If set, will be used instead of $PAGER or more to handle
          suffixes where the copiousoutput flag is set.  The context is
          as for handler, i.e. :mime:.SUFFIX: for handling a file with
          the given SUFFIX.

     Examples:

          zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
          zstyle ':mime:.txt' handler less %s
          zstyle ':mime:.txt' flags needsterminal

     When zsh-mime-setup is subsequently run, it will look for mailcap
     entries in the two files given.  Files of suffix .txt will be
     handled by running `less FILE.TXT'.  The flag needsterminal is set
     to show that this program must run attached to a terminal.

     As there are several steps to dispatching a command, the following
     should be checked if attempting to execute a file by extension
     .EXT does not have the expected effect.  starteit() eit()( The
     command `alias -s EXT' should show `ps=zsh-mime-handler'.  If it
     shows something else, another suffix alias was already installed
     and was not overwritten.  If it shows nothing, no handler was
     installed:  this is most likely because no handler was found in
     the .mime.types and mailcap combination for .ext files.  In that
     case, appropriate handling should be added to ~/.mime.types and
     mailcap.  ) eit()( If the extension is handled by zsh-mime-handler
     but the file is not opened correctly, either the handler defined
     for the type is incorrect, or the flags associated with it are in
     appropriate.  Running zsh-mime-setup -l will show the handler and,
     if there are any, the flags.  A %s in the handler is replaced by
     the file (suitably quoted if necessary).  Check that the handler
     program listed lists and can be run in the way shown.  Also check
     that the flags needsterminal or copiousoutput are set if the
     handler needs to be run under a terminal; the second flag is used
     if the output should be sent to a pager.  An example of a suitable
     mailcap entry for such a program is:

          text/html; /usr/bin/lynx '%s'; needsterminal
     ) endeit()

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

          autoload -U pick-web-browser
          alias -s html=pick-web-browser

     It is provided as an intelligent front end to dispatch a web
     browser.  It 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, pick-web-browser can be run as a zsh script.

     Two styles are available to customize the choice of browsers:
     x-browsers when running under the X Windows System, and
     tty-browsers 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 :mime: (which may be
     extended in future, so appending `*' is recommended).  For example,

          zstyle ':mime:*' x-browsers opera konqueror netscape

     specifies that pick-web-browser 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.

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.

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 (see 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 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 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 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.

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.

run-help
     See `Accessing On-Line Help' (see Utilities).

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.

zcalc [ EXPRESSION ... ]
     A reasonably powerful calculator based on zsh's arithmetic
     evaluation facility.  The syntax is similar to that of formulae in
     most programming languages; see Arithmetic Evaluation for
     details.  The mathematical library zsh/mathfunc will be loaded if
     it is available; see The zsh/mathfunc Module.  The
     mathematical functions correspond to the raw system libraries, so
     trigonometric functions are evaluated using radians, and so on.

     Each line typed is evaluated as an expression.  The prompt shows a
     number, which corresponds to a positional parameter where the
     result of that calculation is stored.  For example, the result of
     the calculation on the line preceded by `4> ' is available as $4.
     Full command line editing, including the history of previous
     calculations, is available; the history is saved in the file
     ~/.zcalc_history.  To exit, enter a blank line or type `q' on its
     own.

     If arguments are given to zcalc on start up, they are used to
     prime the first few positional parameters.  A visual indication of
     this is given when the calculator starts.

     The constants PI (3.14159...) and E (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, `[#16]' to display hexadecimal output
     preceded by an indication of the base, or `[##16]' just to display
     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 `zcalc -#16' (the `#' may have to be quoted, depending
     on the globbing options set).

     The prompt is configurable via the parameter ZCALCPROMPT, which
     undergoes standard prompt expansion.  The index of the current
     entry is stored locally in the first element of the array psvar,
     which can be referred to in ZCALCPROMPT as `%1v'.  The default
     prompt is `%1v> '.

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

zed [ -f ] NAME
     This function uses the ZLE editor to edit a file or function.  It
     rebinds the return key to insert a line break, and adds bindings
     for `^X^W' in the emacs keymap and `ZZ' in the vicmd keymap to
     accept (and therefore write, in the case of a file) the edited
     file or function.  Keybindings are otherwise the standard ones;
     completion is available, and styles may be set with the context
     prefix `:completion:zed'.

     Only one NAME argument is recognized (additional arguments are
     ignored).  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.

     Without -f, NAME is the path name of the file to edit, which need
     not exist; it is created on write, if necessary.

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' (see Utilities).

zmv [ -finqQsvwW ] [ -C | -L | -M | -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.

     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.

    -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 `-'.

     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' (see 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.

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

Functions Index
***************