diff options
Diffstat (limited to 'Doc/Zsh/contrib.yo')
| -rw-r--r-- | Doc/Zsh/contrib.yo | 782 |
1 files changed, 782 insertions, 0 deletions
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo new file mode 100644 index 000000000..37cff337d --- /dev/null +++ b/Doc/Zsh/contrib.yo @@ -0,0 +1,782 @@ +texinode(User Contributions)()(Zftp Function System)(Top) +chapter(User Contributions) +cindex(user contributions) +sect(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 significant of +these are documented here. For documentation on other contributed items +such as shell functions, look for comments in the function source files. + +startmenu() +menu(Utilities) +menu(Prompt Themes) +menu(ZLE Functions) +menu(Other Functions) +endmenu() + +texinode(Utilities)(Prompt Themes)()(User Contributions) +sect(Utilities) + +subsect(Accessing On-Line Help) +cindex(helpfiles utility) + +The key sequence tt(ESC h) is normally bound by ZLE to execute the +tt(run-help) widget (see +ifzman(zmanref(zshzle))\ +ifnzman(noderef(Zsh Line Editor))\ +). This invokes the tt(run-help) command with the command word from the +current input line as its argument. By default, tt(run-help) is an alias +for the tt(man) command, so this often fails when the command word is a +shell builtin or a user-defined function. By redefining the tt(run-help) +alias, one can improve the on-line help provided by the shell. + +The tt(helpfiles) utility, found in the tt(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 tt(run-help) function, found in +tt(Functions/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 +tt(/usr/share/zsh) or tt(/usr/local/share/zsh) and subdirectories below +those, or ask your system administrator. + +To create your own help files with tt(helpfiles), choose or create a +directory where the individual command help files will reside. For +example, you might choose tt(~/zsh_help). If you unpacked the zsh +distribution in your home directory, you would use the commands: + +example(mkdir ~/zsh_help +cd ~/zsh_help +man zshall | colcrt - | \ +perl ~/zsh-version()/Util/helpfiles) + +findex(run-help, use of) +Next, to use the tt(run-help) function, you need to add lines something +like the following to your tt(.zshrc) or equivalent startup file: + +example(unalias run-help +autoload run-help +HELPDIR=~/zsh_help) + +vindex(HELPDIR) +The tt(HELPDIR) parameter tells tt(run-help) where to look for the help +files. If your system already has a help file directory installed, set +tt(HELPDIR) to the path of that directory instead. + +Note that in order for `tt(autoload run-help)' to work, the tt(run-help) +file must be in one of the directories named in your tt(fpath) array (see +ifzman(zmanref(zshparam))\ +ifnzman(noderef(Parameters Used By The Shell))\ +). This should already be the case if you have a standard zsh +installation; if it is not, copy tt(Functions/Misc/run-help) to an +appropriate directory. + +subsect(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 tt(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. + +The tt(zrecompile) autoloadable function, found in tt(Functions/Misc), can +be used to keep function digests up to date. + +startitem() +findex(zrecompile) +xitem(tt(zrecompile) [ tt(-qt) ] [ var(name) ... ]) +item(tt(zrecompile) [ tt(-qt) ] tt(-p) var(args) [ tt(-)tt(-) var(args) ... ])( +This tries to find wordcode files and automatically re-compile them if at +least one of the original files is newer than the wordcode file. This +works only if the names stored in the wordcode files are full paths or are +relative to the directory that contains the wordcode file. + +In the first form, each var(name) is the name of a wordcode file or a +directori containing wordcode files that should be checked. If no +arguments are given, the directories and wordcode files in $fpath are +used. + +When tt(-t) is given, no compilation is performed, but a return status of +zero (true) is set if there are files that need to be re-compiled and +non-zero (false) otherwise. The tt(-q) option quiets the chatty output +that describes what tt(zrecompile) is doing. + +Without the tt(-t) option, the return status is zero if all wordcode files +that needed re-compilation could be compiled and non-zero if compilation +for at least one of the files failed. + +If the tt(-p) option is given, the var(args) are interepted as one +or more sets of arguments for tt(zcompile), separated by `tt(-)tt(-)'. +For example: + +example(zrecompile -p \ + -R ~/.zshrc -- \ + -M ~/.zcompdump -- \ + ~/zsh/comp.zwc ~/zsh/Completion/*/_*) + +This compiles tt(~/.zshrc) into tt(~/.zshrc.zwc) if that doesn't exist or +if it is older than tt(~/.zshrc). The wordcode file will be marked for +reading instead of mapping. The same is done for tt(~/.zcompdump) and +tt(~/.zcompdump.zwc), but this wordcode file is marked for mapping. The +last line re-creates the file tt(~/zsh/comp.zwc) if any of the files +matching the given pattern is newer than it. + +Without the tt(-p) option, tt(zrecompile) does not create function digests +that do not already exist, nor does it add new functions to the digest. +) +enditem() + +The following shell loop is an example of a method for creating function +digests for all functions in your tt(fpath), assuming that you have write +permission to the directories: + +example(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 tt(-U) and tt(-z) options are appropriate for functions in the default +zsh installation tt(fpath); you may need to use different options for your +personal function directories. + +Once the digests have been created and your tt(fpath) modified to refer to +them, you can keep them up to date by running tt(zrecompile) with no +arguments. + +subsect(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 +ifzman(zmanref(zsh))\ +ifnzman(noderef(Mailing Lists))\ +), but sometimes one of the zsh developers will need to recreate your +environment in order to track the problem down. + +The script named tt(reporter), found in the tt(Util) directory of the +distribution, is provided for this purpose. (It is also possible to +tt(autoload reporter), but tt(reporter) is not installed in tt(fpath) +by default.) This script outputs a detailed dump of the shell state, +in the form of another script that can be read with `tt(zsh -f)' to +recreate that state. + +To use tt(reporter), read the script into your shell with the `tt(.)' +command and redirect the output into a file: + +example(. ~/zsh-version()/Util/reporter > zsh.report) + +You should check the tt(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 tt(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 tt(aliases), tt(options), and +tt(zstyles) states may be useful because they include only changes from +the defaults. The tt(bindings) state may be useful if you have created +any of your own keymaps, because tt(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 +tt(reporter), you should edit the results to remove unnecessary commands. +Note that if you're using the new completion system, you should em(not) +dump the tt(functions) state to your startup files with tt(reporter); use +the tt(compdump) function instead (see +ifzman(zmanref(zshcompsys))\ +ifnzman(noderef(Completion System))\ +). + +startitem() +item(tt(reporter) [ var(state) ... ])( +findex(reporter) +Print to standard output the indicated subset of the current shell state. +The var(state) arguments may be one or more of: + +startsitem() +sitem(tt(all))(Output everything listed below.) +sitem(tt(aliases))(Output alias definitions.) +sitem(tt(bindings))(Output ZLE key maps and bindings.) +sitem(tt(completion))(Output old-style tt(compctl) commands. +New completion is covered by tt(functions) and tt(zstyles).) +sitem(tt(functions))(Output autoloads and function definitions.) +sitem(tt(limits))(Output tt(limit) commands.) +sitem(tt(options))(Output tt(setopt) commands.) +sitem(tt(styles))(Same as tt(zstyles).) +sitem(tt(variables))(Output shell parameter assignments, plus tt(export) +commands for any environment variables.) +sitem(tt(zstyles))(Output tt(zstyle) commands.) +endsitem() + +If the var(state) is omitted, tt(all) is assumed. +) + +With the exception of `tt(all)', every var(state) can be abbreviated by +any prefix, even a single letter; thus tt(a) is the same as tt(aliases), +tt(z) is the same as tt(zstyles), etc. +enditem() + +texinode(Prompt Themes)(ZLE Functions)(Utilities)(User Contributions) +sect(Prompt Themes) + +subsect(Installation) + +You should make sure all the functions from the tt(Functions/Prompts) +directory of the source distribution are available; they all begin with +the string `tt(prompt_)' except for the special function`tt(promptinit)'. +You also need the `tt(colors)' function from tt(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 tt(fpath) array (this should already be the +case if they were installed), and at least the function tt(promptinit) +should be autoloaded; it will autoload the rest. Finally, to initialize +the use of the system you need to call the tt(promptinit) function. The +following code in your tt(.zshrc) will arrange for this; assume the +functions are stored in the directory tt(~/myfns): + +example(fpath=(~/myfns $fpath) +autoload -U promptinit +promptinit) + +subsect(Theme Selection) + +Use the tt(prompt) command to select your preferred theme. This command +may be added to your tt(.zshrc) following the call to tt(promptinit) in +order to start zsh with a theme already selected. + +startitem() +xitem(tt(prompt) [ tt(-c) | tt(-l) ]) +xitem(tt(prompt) [ tt(-p) | tt(-h) ] [ var(theme) ... ]) +item(tt(prompt) [ tt(-s) ] var(theme) [ var(arg) ... ])( +Set or examine the prompt theme. With no options and a var(theme) +argument, the theme with that name is set as the current theme. The +available themes are determined at run time; use the tt(-l) option to see +a list. The special var(theme) `tt(random)' selects at random one of the +available themes and sets your prompt to that. + +In some cases the var(theme) may be modified by one or more arguments, +which should be given after the theme name. See the help for each theme +for descriptions of these arguments. + +Options are: + +startsitem() +sitem(tt(-c))(Show the currently selected theme and its parameters, if any.) +sitem(tt(-l))(List all available prompt themes.) +sitem(tt(-p))(Preview the theme named by var(theme), or all themes if no +var(theme) is given.) +sitem(tt(-h))(Show help for the theme named by var(theme), or for the +tt(prompt) function if no var(theme) is given.) +sitem(tt(-s))(Set var(theme) as the current theme and save state.) +endsitem() +) +item(tt(prompt_)var(theme)tt(_setup))( +Each available var(theme) has a setup function which is called by the +tt(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. +) +enditem() + +texinode(ZLE Functions)(Other Functions)(Prompt Themes)(User Contributions) +sect(ZLE Functions) + +subsect(Widgets) + +These functions all implement user-defined ZLE widgets (see +ifzman(zmanref(zshzle))\ +ifnzman(noderef(Zsh Line Editor))\ +) which can be bound to keystrokes in interactive shells. To use them, +your tt(.zshrc) should contain lines of the form + +example(autoload var(function) +zle -N var(function)) + +followed by an appropriate tt(bindkey) command to associate the function +with a key sequence. Suggested bindings are described below. + +startitem() +tindex(edit-command-line) +item(tt(edit-command-line))( +Edit the command line using your visual editor, as in tt(ksh). + +example(bindkey -M vicmd v edit-command-line) +) +tindex(history-beginning-search-backward-end) +tindex(history-beginning-search-forward-end) +item(tt(history-search-end))( +This function implements the widgets +tt(history-beginning-search-backward-end) and +tt(history-beginning-search-forward-end). These commands work by first +calling the corresponding builtin widget (see +ifzman(`History Control' in zmanref(zshzle))\ +ifnzman(noderef(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 tt(autoload) only one function, the commands to use it are +slightly different because it implements two widgets. + +example(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) +) +tindex(incarg) +vindex(incarg, use of) +item(tt(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 +paramter tt(incarg) may be set to change the default increment something +other than one. + +example(bindkey '^X+' incarg) +) +tindex(incremental-complete-word) +item(tt(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 tt(^H) or tt(DEL). Pressing return +accepts the completion so far and returns you to normal editing (that is, +the command line is em(not) immediately executed). You can hit tt(TAB) to +do normal completion, tt(^G) to abort back to the state when you started, +and tt(^D) to list the matches. + +This works only with the new function based completion system. + +example(bindkey '^Xi' incremental-complete-word) +) +tindex(insert-files) +item(tt(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. + +example(bindkey '^Xf' insert-files) +) +tindex(predict-on) +tindex(predict-off) +item(tt(predict-on))( +This set of functions implements predictive typing using history search. +After tt(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 tt(predict-off), editing returns to normal for the line found. +In fact, you often don't even need to use tt(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 tt(toggle) style below. + +With the function based completion system (which is needed for this), you +should be able to type tt(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 tt(predict-on) is used, it creates several additional +widget functions: + +startsitem() +sitem(tt(delete-backward-and-predict))(Replaces the tt(backward-delete-char) +widget. You do not need to bind this yourself.) +sitem(tt(insert-and-predict))(Implements predictive typing by replacing the +tt(self-insert) widget. You do not need to bind this yourself.) +sitem(tt(predict-off))(Turns off predictive typing.) +endsitem() + +Although you tt(autoload) only the tt(predict-on) function, it is +necessary to create a keybinding for tt(predict-off) as well. + +example(zle -N predict-on +zle -N predict-off +bindkey '^X^Z' predict-on +bindkey '^Z' predict-off) +) +enditem() + +subsect(Styles) + +The behavior of several of the above widgets can be controlled by the use +of the tt(zstyle) mechanism. In particular, widgets that interact with +the completion system pass along their context to any completions that +they invoke. + +startitem() +kindex(break-keys, completion style) +item(tt(break-keys))( +This style is used by the tt(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. +) +kindex(completer, completion style) +item(tt(completer))( +The tt(incremental-complete-word) and tt(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: + +example(zstyle ':completion:*' completer \ + _complete _correct _approximate +zstyle ':completion:incremental:*' completer \ + _complete _correct +zstyle ':completion:predict:*' completer \ + _complete) +) +kindex(cursor, completion style) +item(tt(cursor))( +The tt(insert-and-predict) widget uses this style, in the context +`tt(:predict)', to decide where to place the cursor after completion has +been tried. Values are: + +startitem() +item(tt(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 `tt(key)'. +) +item(tt(key))( +The cursor is left +after the var(n)th occurrence of the character just inserted, where +var(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. +) +enditem() + +Any other value for this style unconditionally leaves the cursor at the +position where the completion code left it. +) +kindex(list, completion style) +item(tt(list))( +When using the tt(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 `tt(:completion:incremental)'. + +The tt(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 tt(always). In this +case the context is `tt(:predict)' (em(not) `tt(:completion:predict)'). +) +kindex(prompt, completion style) +item(tt(prompt))( +The tt(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 tt(PS1) and other prompt parameters: + +startitem() +item(tt(%c))( +Replaced by the name of the completer function that generated the +matches (without the leading underscore). +) +item(tt(%l))( +When the tt(list) style is set, +replaced by `tt(...)' if the list of matches is too long to fit on the +screen and with an empty string otherwise. If the tt(list) style is +`false' or not set, `tt(%l)' is always removed. +) +item(tt(%n))( +Replaced by the number of matches generated. +) +item(tt(%s))( +Replaced by `tt(-no match-)', `tt(-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. +) +item(tt(%u))( +Replaced by the unambiguous part of all matches, if there +is any, and if it is different from the word on the line. +) +enditem() +) +kindex(stop-keys, completion style) +item(tt(stop-keys))( +This style is used by the tt(incremental-complete-word) widget. Its value +is treated similarly to the one for the tt(break-keys) style. However, in +this case all keys matching the pattern given as its value will stop +incremental completion and will then execute their usual function. +) +kindex(toggle, completion style) +item(tt(toggle))( +This boolean style is used by tt(predict-on) and its related widgets in +the context `tt(: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 +tt(predict-off). +) +kindex(verbose, completion style) +item(tt(verbose))( +This boolean style is used by tt(predict-on) and its related widgets in +the context `tt(: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 tt(toggle) style. +The default does not display these messages. +) +enditem() + +texinode(Other Functions)()(ZLE Functions)(User Contributions) +sect(Other Functions) + +There are a large number of helpful functions in the tt(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. + +subsect(Descriptions) + +startitem() +findex(colors) +item(tt(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 (ifzman(see above)\ +ifnzman(noderef(Prompt Themes))). You seldom should need to run +tt(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: + +startitem() +xitem(color) +item(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 `tt(fg-)', such as `tt(fg-red)'. Names prefixed +with `tt(bg-)', such as `tt(bg-blue)', refer to the background codes. The +reverse mapping from code to color yields base name for foreground codes +and the tt(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. +) +xitem(fg) +xitem(fg_bold) +item(fg_no_bold)( +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding foreground text properties. The tt(fg) sequences change +the color without changing the eight intensity attributes. +) +xitem(bg) +xitem(bg_bold) +item(bg_no_bold)( +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding background properties. The tt(bg) sequences change the +color without changing the eight intensity attributes. +) +enditem() + +In addition, the scalar parameters tt(reset_color) and tt(bold_color) are +set to the ANSI terminal escapes that turn off all attributes and turn on +bold intensity, respectively. +) +findex(fned) +item(tt(fned) var(name))( +Same as tt(zed -f). This function does not appear in the zsh +distribution, but can be created by linking tt(zed) to the name tt(fned) +in some directory in your tt(fpath). +) +findex(is-at-least) +item(tt(is-at-least) var(needed) [ var(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 var(present) string is not +provided, tt($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. + +example(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.") +) +findex(nslookup) +item(tt(nslookup) [ var(arg) ... ])( +This wrapper function for the tt(nslookup) command requires the +tt(zsh/zpty) module. It behaves exactly like the standard tt(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 `tt(:completion:nslookup)'. + +See also the tt(pager), tt(prompt) and tt(rprompt) styles below. +) +item(tt(run-help))( +See `Accessing On-Line Help' +ifzman(above)\ +ifnzman((noderef(Utilities))). +) +findex(zed) +item(tt(zed) [ tt(-f) ] var(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 `tt(^X^W)' in +the tt(emacs) keymap and `tt(ZZ)' in the tt(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 `tt(:completion:zed)'. + +Only one var(name) argument is recognized (additional arguments are +ignored). If the tt(-f) option is given, the name is taken to be that of +a function; if the function is marked for autoloading, tt(zed) searches +for it in the tt(fpath) and loads it. Note that functions edited this way +are installed into the current shell, but em(not) written back to the +autoload file. + +Without tt(-f), var(name) is the path name of the file to edit, which need +not exist; it is created on write, if necessary. +) +findex(zcp) +findex(zln) +xitem(tt(zcp) [ tt(-finqQvw) ] var(srcpat) var(dest)) +item(tt(zln) [ tt(-finqQsvw) ] var(srcpat) var(dest))( +Same as tt(zmv -C) and tt(zmv -L), respectively. These functions do not +appear in the zsh distribution, but can be created by linking tt(zmv) to +the names tt(zcp) and tt(zln) in some directory in your tt(fpath). +) +findex(zmv) +item(tt(zmv) [ tt(-finqQsvw) ] [ -C | -L | -M | -p var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )( +Move (usually, rename) files matching the pattern var(srcpat) to +corresponding files having names of the form given by var(dest), where +var(srcpat) contains parentheses surrounding patterns which will be +replaced in turn by $1, $2, ... in var(dest). For example, + +example(zmv '(*).lis' '$1.txt') + +renames `tt(foo.lis)' to `tt(foo.txt)', `tt(my.old.stuff.lis)' to +`tt(my.old.stuff.txt)', and so on. + +The pattern is always treated as an tt(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 tt(-f) +was not given) causes the entire function to abort without doing anything. + +Options: + +startsitem() +sitem(tt(-f))(Force overwriting of destination files. Not currently +passed down to the tt(mv)/tt(cp)/tt(ln) command due to vagaries of +implementations (but you can use tt(-o-f) to do that).) +sitem(tt(-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.) +sitem(tt(-n))(No execution: print what would happen, but don't do it.) +sitem(tt(-q))(Turn bare glob qualifiers off: now assumed by default, so +this has no effect.) +sitem(tt(-Q))(Force bare glob qualifiers on. Don't turn this on unless +you are actually using glob qualifiers in a pattern.) +sitem(tt(-s))(Symbolic, passed down to tt(ln); only works with tt(-L).) +sitem(tt(-v))(Verbose: print each command as it's being executed.) +sitem(tt(-w))(Pick out wildcard parts of the pattern, as described above, +and implicitly add parentheses for referring to them.) +sxitem(tt(-C)) +sxitem(tt(-L)) +sitem(tt(-M))(Force tt(cp), tt(ln) or tt(mv), respectively, regardless of +the name of the function.) +sitem(tt(-p) var(program))(Call var(program) instead of tt(cp), tt(ln) or +tt(mv). Whatever it does, it should at least understand the form +ifzman(`var(program) tt(-)tt(-) var(oldname) var(newname)')\ +ifnzman(example(var(program) tt(-)tt(-) var(oldname) var(newname))) +where var(oldname) and var(newname) are filenames generated by tt(zmv).) +sitem(tt(-o) var(optstring))(The var(optstring) is split into words and +passed down verbatim to the tt(cp), tt(ln) or tt(mv) command called to +perform the work. It should probably begin with a `tt(-)'.) +endsitem() + +For more complete examples and other implementation details, see the +tt(zmv) source file, usually located in one of the directories named in +your tt(fpath), or in tt(Functions/Misc/zmv) in the zsh distribution. +) +item(tt(zrecompile))( +See `Recompiling Functions' +ifzman(above)\ +ifnzman((noderef(Utilities))). +) +findex(zstyle+) +item(tt(zstyle+) var(context) var(style) var(value) [ + var(subcontext) var(style) var(value) ... ])( +This makes defining styles a bit simpler by using a single `tt(+)' as a +special token that allows you to append a context name to the previously +used context name. Like this: + +example(zstyle+ ':foo:bar' style1 value1 \ + + ':baz' style2 value2 \ + + ':frob' style3 value3) + +This defines `style1' with `value1' for the context tt(:foo:bar) as usual, +but it also defines `style2' with `value2' for the context +tt(:foo:bar:baz) and `style3' with `value3' for tt(:foo:bar:frob). Any +var(subcontext) may be the empty string to re-use the first context +unchanged. +) +enditem() + +subsect(Styles) + +startitem() +kindex(insert-tab, completion style) +item(tt(insert-tab))( +The tt(zed) function em(sets) this style in context `tt(:completion:zed:*)' +to turn off completion when tt(TAB) is typed at the beginning of a line. +You may override this by setting your own value for this context and style. +) +kindex(pager, nslookup style) +item(tt(pager))( +The tt(nslookup) function looks up this style in the context +`tt(:nslookup)' to determine the program used to display output that does +not fit on a single screen. +) +kindex(prompt, nslookup style) +kindex(rprompt, nslookup style) +xitem(tt(prompt)) +item(tt(rprompt))( +The tt(nslookup) function looks up this style in the context +`tt(:nslookup)' to set the prompt and the right-side prompt, respectively. +The usual expansions for the tt(PS1) and tt(RPS1) parameters may be used +(see +ifzman(zmanref(zshmisc))\ +ifnzman(noderef(Prompt Expansion))\ +). +) +enditem() |