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  con-
       tributed  items such as shell functions, look for comments in the func-
       tion source files.




UTILITIES

   Accessing On-Line Help
       The key sequence ESC h is normally bound by ZLE to execute the run-help
       widget  (see  zshzle(1)).   This  invokes the run-help command with the
       command word from the current input line as its argument.  By  default,
       run-help  is an alias for the man command, so this often fails when the
       command word is  a  shell  builtin  or  a  user-defined  function.   By
       redefining  the  run-help  alias, one can improve the on-line help pro-
       vided by the shell.

       The helpfiles utility, found in the Util directory of the distribution,
       is a Perl program that can be used to process the zsh manual to produce
       a separate help file for each shell builtin and for  many  other  shell
       features  as  well.  The autoloadable run-help function, found in Func-
       tions/Misc, searches for these helpfiles  and  performs  several  other
       tests to produce the most complete help possible for the command.

       There  may already be a directory of help files on your system; look in
       /usr/share/zsh or /usr/local/share/zsh and subdirectories below  those,
       or ask your system administrator.

       To create your own help files with helpfiles, choose or create a direc-
       tory where the individual command help files will reside.  For example,
       you  might  choose ~/zsh_help.  If you unpacked the zsh distribution in
       your home directory, you would use the commands:

              mkdir ~/zsh_help
              cd ~/zsh_help
              man zshall | colcrt - | \
              perl ~/zsh-4.2.1/Util/helpfiles

       Next, to use the run-help function, you need  to  add  lines  something
       like the following to your .zshrc or equivalent startup file:

              unalias run-help
              autoload run-help
              HELPDIR=~/zsh_help

       The  HELPDIR parameter tells run-help where to look for the help files.
       If your system already has a help file directory installed, set HELPDIR
       to the path of that directory instead.

       Note  that  in order for ‘autoload run-help’ to work, the run-help file
       must be in one of the directories named in your fpath array  (see  zsh-
       param(1)).   This should already be the case if you have a standard zsh
       installation; if it is not, copy Functions/Misc/run-help to  an  appro-
       priate directory.


   Recompiling Functions
       If  you frequently edit your zsh functions, or periodically update your
       zsh installation to track the latest developments, you  may  find  that
       function  digests compiled with the zcompile builtin are frequently out
       of date with respect to the function source files.  This is not usually
       a  problem, because zsh always looks for the newest file when loading a
       function, but it may cause slower shell startup and  function  loading.
       Also,  if  a digest file is explicitly used as an element of fpath, zsh
       won’t check whether any of its source files has changed.

       The zrecompile autoloadable function, found in Functions/Misc,  can  be
       used to keep function digests up to date.

       zrecompile [ -qt ] [ name ... ]
       zrecompile [ -qt ] -p args [ -- args ... ]
              This tries to find *.zwc files and automatically re-compile them
              if at least one of the original files is newer than the compiled
              file.  This works only if the names stored in the compiled files
              are full paths or are relative to the  directory  that  contains
              the .zwc file.

              In the first form, each name is the name of a compiled file or a
              directory containing *.zwc files that should be checked.  If  no
              arguments  are  given,  the directories and *.zwc files in fpath
              are used.

              When -t 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 -q option  qui-
              ets the chatty output that describes what zrecompile is doing.

              Without  the  -t  option, the return status is zero if all files
              that needed re-compilation could be  compiled  and  non-zero  if
              compilation for at least one of the files failed.

              If  the  -p  option is given, the args are interpreted as one or
              more sets of arguments for zcompile,  separated  by  ‘--’.   For
              example:

                     zrecompile -p \
                                -R ~/.zshrc -- \
                                -M ~/.zcompdump -- \
                                ~/zsh/comp.zwc ~/zsh/Completion/*/_*

              This  compiles  ~/.zshrc into ~/.zshrc.zwc if that doesn’t exist
              or if it is older than  ~/.zshrc.  The  compiled  file  will  be
              marked  for  reading  instead  of  mapping. The same is done for
              ~/.zcompdump and ~/.zcompdump.zwc, but  this  compiled  file  is
              marked   for   mapping.   The  last  line  re-creates  the  file
              ~/zsh/comp.zwc if any of the files matching the given pattern is
              newer than it.

              Without  the  -p  option,  zrecompile  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 fpath, assuming  that  you  have
       write permission to the directories:

              for ((i=1; i <= $#fpath; ++i)); do
                dir=$fpath[i]
                zwc=${dir:t}.zwc
                if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
                  continue
                fi
                files=($dir/*(N-.))
                if [[ -w $dir:h && -n $files ]]; then
                  files=(${${(M)files%/*/*}#/})
                  if ( cd $dir:h &&
                       zrecompile -p -U -z $zwc $files ); then
                    fpath[i]=$fpath[i].zwc
                  fi
                fi
              done

       The  -U and -z options are appropriate for functions in the default zsh
       installation fpath; you may need to use different options for your per-
       sonal function directories.

       Once  the digests have been created and your fpath modified to refer to
       them, you can keep them up to date by running zrecompile with no  argu-
       ments.


   Keyboard Definition
       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 zkbd utility,
       found in Functions/Misc, can help you quickly create key  bindings  for
       your configuration.

       Run zkbd either as an autoloaded function, or as a shell script:

              zsh -f ~/zsh-4.2.1/Functions/Misc/zkbd

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

       The  keystrokes  read by zkbd are recorded as a definition for an asso-
       ciative array named key, written to a file in  the  subdirectory  .zkbd
       within  either your HOME or ZDOTDIR directory.  The name of the file is
       composed from  the  TERM,  VENDOR  and  OSTYPE  parameters,  joined  by
       hyphens.

       You  may  read  this file into your .zshrc or another startup file with
       the "source" or "." commands, then reference the key parameter in bind-
       key commands, like this:

              source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
              [[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
              [[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
              # etc.

       Note  that  in order for ‘autoload zkbd’ to work, the zkdb file must be
       in one of the directories named in your fpath array (see  zshparam(1)).
       This  should  already  be the case if you have a standard zsh installa-
       tion; if it is not, copy Functions/Misc/zkbd to an  appropriate  direc-
       tory.


   Dumping Shell State
       Occasionally  you  may encounter what appears to be a bug in the shell,
       particularly if you are using a beta version of zsh  or  a  development
       release.  Usually it is sufficient to send a description of the problem
       to one of the zsh mailing lists (see 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 reporter, found in the Util directory of the distribu-
       tion,  is  provided for this purpose.  (It is also possible to autoload
       reporter, but reporter is not installed in  fpath  by  default.)   This
       script  outputs  a  detailed  dump  of  the shell state, in the form of
       another script that can be read with ‘zsh -f’ to recreate that state.

       To use reporter, read the script into your shell with the ‘.’   command
       and redirect the output into a file:

              . ~/zsh-4.2.1/Util/reporter > zsh.report

       You should check the zsh.report file for any sensitive information such
       as passwords and delete them by hand before sending the script  to  the
       developers.   Also,  as the output can be voluminous, it’s best to wait
       for the developers to ask for this information before sending it.

       You can also use reporter to dump only a subset  of  the  shell  state.
       This is sometimes useful for creating startup files for the first time.
       Most of the output from reporter is far more detailed than  usually  is
       necessary  for  a  startup  file, but the aliases, options, and zstyles
       states may be  useful  because  they  include  only  changes  from  the
       defaults.   The bindings state may be useful if you have created any of
       your own keymaps, because reporter arranges to dump the keymap creation
       commands as well as the bindings for every keymap.

       As  is  usual  with  automated tools, if you create a startup file with
       reporter, you should edit the results to remove  unnecessary  commands.
       Note  that  if  you’re  using the new completion system, you should not
       dump the functions state to your startup files with reporter;  use  the
       compdump function instead (see zshcompsys(1)).

       reporter [ state ... ]
              Print  to  standard  output  the indicated subset of the current
              shell state.  The state arguments may be one or more of:

              all    Output everything listed below.
              aliases
                     Output alias definitions.
              bindings
                     Output ZLE key maps and bindings.
              completion
                     Output old-style compctl  commands.   New  completion  is
                     covered by functions and zstyles.
              functions
                     Output autoloads and function definitions.
              limits Output limit commands.
              options
                     Output setopt commands.
              styles Same as zstyles.
              variables
                     Output  shell parameter assignments, plus export commands
                     for any environment variables.
              zstyles
                     Output zstyle commands.

              If the state is omitted, all is assumed.

       With the exception of ‘all’, every state can be abbreviated by any pre-
       fix, even a single letter; thus a is the same as aliases, z is the same
       as zstyles, etc.



PROMPT THEMES

   Installation
       You should make sure  all  the  functions  from  the  Functions/Prompts
       directory of the source distribution are available; they all begin with
       the string ‘prompt_’ except for the special function‘promptinit’.   You
       also  need  the  ‘colors’  function  from Functions/Misc.  All of these
       functions may already have been installed on your system; if  not,  you
       will  need  to find them and copy them.  The directory should appear as
       one of the elements of the fpath array (this should already be the case
       if they were installed), and at least the function promptinit should be
       autoloaded; it will autoload the rest.  Finally, to initialize the  use
       of  the system you need to call the promptinit function.  The following
       code in your .zshrc will arrange for this;  assume  the  functions  are
       stored in the directory ~/myfns:

              fpath=(~/myfns $fpath)
              autoload -U promptinit
              promptinit


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

       prompt [ -c | -l ]
       prompt [ -p | -h ] [ theme ... ]
       prompt [ -s ] 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 -l
              option to see a list.  The special  themerandom’  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:

              -c     Show the currently selected theme and its parameters,  if
                     any.
              -l     List all available prompt themes.
              -p     Preview  the  theme  named  by theme, or all themes if no
                     theme is given.
              -h     Show help for the theme named by theme, or for the prompt
                     function if no theme is given.
              -s     Set theme as the current theme and save state.

       prompt_theme_setup
              Each available theme has a setup function which is called by the
              prompt function to install that theme.  This function may define
              other  functions  as necessary to maintain the prompt, including
              functions used to preview the prompt or  provide  help  for  its
              use.   You  should  not  normally  call a theme’s setup function
              directly.



ZLE FUNCTIONS

   Widgets
       These functions all implement user-defined ZLE widgets (see  zshzle(1))
       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 func-
              tions described in the next section.  The  following  is  suffi-
              cient:

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

              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 zshmodules(1).  Each style is looked up in the con-
              text  :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 appro-
              priate 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)  pat-
              terns 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  gen-
                     erating  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  charac-
              ters  ‘-’  and  ‘:’.   Be  careful including ‘]’, ‘^’ and ‘-’ as
              these are special inside character classes.

              The final style is skip-chars.  This is mostly useful for trans-
              pose-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  cur-
              sor  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:wid-
              get,   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 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.

       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-begin-
              ning-search-backward-end    and    history-beginning-search-for-
              ward-end.  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 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

       history-pattern-search
              The function  history-pattern-search  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:

                     autoload -U history-pattern-search
                     zle -N history-pattern-search-backward history-pattern-search
                     zle -N history-pattern-search-forward history-pattern-search

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

              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 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  -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  recur-
              sive-edit  is  performed;  the  calling  widget should call this
              function with the option -S, perform its own editing on the com-
              mand  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 parame-
              ter will be local to the calling function.

              narrow-to-region-invisible is a simple widget which  calls  nar-
              row-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 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 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 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 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 neces-
              sary 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 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,
              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 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 $LBUFFER, and if  a
              third  argument  is  given  it is the initial value of $RBUFFER.
              This provides a default value  and  starting  cursor  placement.
              Upon return the entire buffer is the value of $REPLY.

              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, so depending on the terminal
              settings the input may not be visible, and only the  input  keys
              are  placed  in $REPLY, not the entire buffer.  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 exe-
              cuted-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  every-
              where 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 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:

                     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  cur-
              rent  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_COM-
              MENTS 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 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  dif-
              ferent 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  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.

       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:incremen-
              tal’.

              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  pat-
              tern (using full EXTENDED_GLOB syntax) that matches an interest-
              ing word.  The context is  the  name  of  the  widget  to  which
              smart-insert-last-word is bound (see above).  The default behav-
              ior 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  charac-
              ters 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 gen-
                     erated 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  pre-
                     fix, 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 func-
              tion.

       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 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 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 combi-
              nation 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 mul-
              tiple 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  sys-
              tems 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  over-
              written.

              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 exist-
              ing suffix aliases assigned to handlers other than zsh-mime-han-
              dler.   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  copi-
              ousoutput, see mailcap(4).

              The  functions  use the following styles, which are defined with
              the zstyle builtin command (see zshmodules(1)).  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 con-
                     text is :mime:.  A + in the list will be replaced by  the
                     default files.

              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 con-
                     text is :mime:.  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 :mime:.suffix:, and the format of the han-
                     dler  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 needstermi-
                     nal, 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 con-
                     text 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 mail-
              cap 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  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 ‘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 han-
              dler  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 nec-
              essary).  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  above).
              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  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
                     ‘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  fore-
                     ground 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 dis-
              tribution, 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.   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.

                     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 cant use is-at-least here."

       nslookup [ arg ... ]
              This wrapper function for  the  nslookup  command  requires  the
              zsh/zpty  module  (see  zshmodules(1)).  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  func-
              tion-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’ above.

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

       zargs [ 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 zargs command itself,
              which are the same as those of xargs.  The  input  list  is  the
              collection  of  strings (often file names) that become the argu-
              ments of the command, analogous to the standard input of  xargs.
              Finally,  the  arg  list  consists  of  those arguments (usually
              options) that are passed to the command each time it runs.   The
              arg  list precedes the elements from the input list in each run.
              If no command is provided, then no arg list may be provided, and
              in  that event the default command is ‘print’ with arguments ‘-r
              --’.

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

                     autoload -U zargs
                     zargs -- **/*(.) -- ls -l

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

                     zargs -e.. -- **/*(.) .. ls -l

              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 zargs  options,  see  xargs(1)  or  run
              zargs with the --help option.

       zcalc [ 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
              zsh/mathfunc  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 ‘4> ’ is available as
              $4.  Full command line editing, including the history of  previ-
              ous 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 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  ‘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
       zed -b This function uses the ZLE editor to edit a file or function.

              Only one name argument is allowed.  If the -f option  is  given,
              the  name  is taken to be that of a function; if the function is
              marked for autoloading, zed searches for it  in  the  fpath  and
              loads  it.   Note  that  functions edited this way are installed
              into the current shell, but not written  back  to  the  autoload
              file.

              Without  -f,  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 zed and  the
              vi  command  keymap to zed-vicmd.  These will be copied from the
              existing main and vicmd keymaps if they do not exist  the  first
              time  zed is run.  They can be used to provide special key bind-
              ings used only in zed.

              If it creates the keymap, zed rebinds the return key to insert a
              line  break and ‘^X^W’ to accept the edit in the zed keymap, and
              binds ‘ZZ’ to accept the edit in the zed-vicmd keymap.

              The bindings alone can be installed by running ‘zed  -b’.   This
              is  suitable  for  putting  into  a startup file.  Note that, if
              rerun, this  will  overwrite  the  existing  zed  and  zed-vicmd
              keymaps.

              Completion  is available, and styles may be set with the context
              prefix ‘:completion:zed’.

              A zle widget zed-set-file-name is available.  This can be called
              by  name  from  within  zed using ‘\ex zed-set-file-name’ (note,
              however, that because of zed’s rebindings you will have to  type
              ^j  at  the end instead of the return key), or can be bound to a
              key in either of the zed or zed-vicmd keymaps after ‘zed -b’ has
              been  run.  When the widget is called, it prompts for a new name
              for the file being edited.  When zed  exits  the  file  will  be
              written  under  that  name  and  the  original file will be left
              alone.  The widget has no effect with ‘zed -f’.

              While zed-set-file-name is running, zed uses the keymap zed-nor-
              mal-keymap,  which  is  linked from the main keymap in effect at
              the time zed initialised its bindings.  (This  is  to  make  the
              return  key  operate  normally.)  The result is that if the main
              keymap has been changed, the widget won’t notice.  This is not a
              concern for most users.

       zcp [ -finqQvwW ] srcpat dest
       zln [ -finqQsvwW ] srcpat dest
              Same as zmv -C and zmv -L, respectively.  These functions do not
              appear in the zsh distribution, but can be  created  by  linking
              zmv to the names zcp and zln in some directory in your fpath.

       zkbd   See ‘Keyboard Definition’ above.

       zmv  [ -finqQsvwW ] [ -C | -L | -M | -p program ] [ -o optstring ] src-
       pat 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} ref-
                     erences.
              -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 -- old-
                     name newname’ where oldname  and  newname  are  filenames
                     generated by zmv.
              -o optstring
                     The  optstring is split into words and passed down verba-
                     tim 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 distri-
              bution.

       zrecompile
              See ‘Recompiling Functions’ above.

       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 con-
              text :foo:bar:baz and ‘style3’ with ‘value3’ for  :foo:bar:frob.
              Any  subcontext may be the empty string to re-use the first con-
              text 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, respec-
              tively.   The  usual  expansions for the PS1 and RPS1 parameters
              may be used (see zshmisc(1)).



zsh 4.2.1                       August 13, 2004                  ZSHCONTRIB(1)

Man(1) output converted with man2html