diff options
Diffstat (limited to 'Doc/Zsh/contrib.yo')
| -rw-r--r-- | Doc/Zsh/contrib.yo | 213 |
1 files changed, 128 insertions, 85 deletions
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index c02d33cf1..cf42e28a9 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -302,10 +302,13 @@ called at the same point; these are so-called `hook functions'. The shell function tt(add-zsh-hook) provides a simple way of adding or removing functions from the array. -var(hook) is one of tt(chpwd), tt(periodic), tt(precmd) or tt(preexec), -the special functions in question. +var(hook) is one of tt(chpwd), tt(periodic), tt(precmd), tt(preexec), +tt(zshaddhistory), tt(zshexit), or tt(zsh_directory_name), +the special functions in question. Note that tt(zsh_directory_name) +is called in a different way from the other functions, but may +still be manipulated as a hook. -var(functions) is name of an ordinary shell function. If no options +var(function) is name of an ordinary shell function. If no options are given this will be added to the array of functions to be executed in the given context. @@ -315,6 +318,10 @@ the array of functions to be executed. If the option tt(-D) is given, the var(function) is treated as a pattern and any matching names of functions are removed from the array of functions to be executed. + +The options tt(-U), tt(-z) and tt(-k) are passed as arguments to +tt(autoload) for var(function). For functions contributed with zsh, the +options tt(-Uz) are appropriate. ) enditem() @@ -355,7 +362,7 @@ subsect(Use) All direct user interaction is via the tt(cdr) function. The argument to cdr is a number var(N) corresponding to the var(N)th most -recently changed-to directory. 1 is the immediately preceeding directory; +recently changed-to directory. 1 is the immediately preceding directory; the current directory is remembered but is not offered as a destination. Note that if you have multiple windows open 1 may refer to a directory changed to in another window; you can avoid this by having per-terminal @@ -544,36 +551,15 @@ enditem() subsect(Use with dynamic directory naming) It is possible to refer to recent directories using the dynamic directory -name syntax that appeared in zsh version 4.3.7. If you create and -autoload a function tt(zsh_directory_name) containing the following code, -tt(~[1]) will refer to the most recent directory other than $PWD, and so on. -This also includes completion. - -example(if [[ $1 = n ]]; then - if [[ $2 = <-> ]]; then - # Recent directory - typeset -ga reply - autoload -Uz cdr - cdr -r - if [[ -n ${reply[$2]} ]]; then - reply=LPAR()${reply[$2]}RPAR() - return 0 - else - reply=LPAR()RPAR() - return 1 - fi - fi -elif [[ $1 = c ]]; then - if [[ $PREFIX = <-> || -z $PREFIX ]]; then - typeset -a keys values - values=LPAR()${${(f)"$+LPAR()cdr -l+RPAR()"}/ ##/:}RPAR() - keys=LPAR()${values%%:*}RPAR() - _describe -t dir-index 'recent directory index' \ - values keys -V unsorted -S']' - return - fi -fi -return 1) +name syntax by using the supplied function tt(zsh_directory_name_cdr) +a hook: + +example(autoload -Uz add-zsh-hook +add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr) + +When this is done, tt(~[1]) will refer to the most recent +directory other than $PWD, and so on. Completion after tt(~[)var(...) +also works. subsect(Details of directory handling) @@ -614,6 +600,7 @@ sitem(Bazaar (tt(bzr)))(http://bazaar-vcs.org/) sitem(Codeville (tt(cdv)))(http://codeville.org/) sitem(Concurrent Versioning System (tt(cvs)))(http://www.nongnu.org/cvs/) sitem(Darcs (tt(darcs)))(http://darcs.net/) +sitem(Fossil (tt(fossil)))(http://fossil-scm.org/) sitem(Git (tt(git)))(http://git-scm.com/) sitem(GNU arch (tt(tla)))(http://www.gnu.org/software/gnu-arch/) sitem(Mercurial (tt(hg)))(http://mercurial.selenic.com/) @@ -663,6 +650,7 @@ bzr cdv cvs darcs +fossil git hg mtn @@ -706,8 +694,9 @@ example(:vcs_info:<vcs-string>:<user-context>:<repo-root-name>) startitem() item(tt(<vcs-string>))( is one of: git, git-svn, git-p4, hg, hg-git, hg-hgsubversion, hg-hgsvn, -darcs, bzr, cdv, mtn, svn, cvs, svk, tla or p4. When hooks are active the -hooks name is added after a `+'. (See tt(Hooks in vcs_info) below.) +darcs, bzr, cdv, mtn, svn, cvs, svk, tla, p4 or fossil. When hooks are +active the hooks name is added after a `+'. (See tt(Hooks in vcs_info) +below.) ) item(tt(<user-context>))( is a freely configurable string, assignable by @@ -767,11 +756,11 @@ revision number. This style lets you modify how that string should look. ) kindex(nvcsformats) item(tt(nvcsformats))( -These "formats" are exported when we didn't detect -a version control system for the current directory. This is useful if you -want var(vcs_info) to completely take over the generation of your prompt. -You would do something like tt(PS1='${vcs_info_msg_0_}') to accomplish -that. +These "formats" are exported when we didn't detect a version control system +for the current directory or var(vcs_info) was disabled. This is useful if +you want var(vcs_info) to completely take over the generation of your +prompt. You would do something like tt(PS1='${vcs_info_msg_0_}') to +accomplish that. ) kindex(hgrevformat) item(tt(hgrevformat))( @@ -837,6 +826,10 @@ these escapes can be controlled via the var(stagedstr) and var(unstagedstr) styles. The only backends that currently support this option are tt(git) and tt(hg) (tt(hg) only supports unstaged). +For this style to be evaluated with the tt(hg) backend, the var(get-revision) +style needs to be set and the var(use-simple) style needs to be unset. The +latter is the default; the former is not. + Note, the actions taken if this style is enabled are potentially expensive (read: they may be slow, depending on how big the current repository is). Therefore, it is disabled by default. @@ -1128,6 +1121,24 @@ tt(Variable description) below). If an argument is given, that string will be used instead of tt(default) in the tt(user-context) field of the style context. ) +findex(vcs_info_hookadd) +item(tt(vcs_info_hookadd))( +Statically registers a number of functions to a given hook. The hook needs +to be given as the first argument; what follows is a list of hook-function +names to register to the hook. The `tt(+vi-)' prefix needs to be left out +here. See tt(Hooks in vcs_info) below for details. +) +findex(vcs_info_hookdel) +item(tt(vcs_info_hookdel))( +Remove hook-functions from a given hook. The hook needs to be given as the +first non-option argument; what follows is a list of hook-function +names to un-register from the hook. If `tt(-a)' is used as the first +argument, tt(all) occurances of the functions are unregistered. Otherwise +only the last occurance is removed (if a function was registered to a hook +more than once) . The `tt(+vi-)' prefix needs to be left out here. See +tt(Hooks in vcs_info) below for details. +) +findex(vcs_info_lastmsg) item(tt(vcs_info_lastmsg))( Outputs the last var(${vcs_info_msg_*_}) value. Takes into account the value of the tt(use-prompt-escapes) style in @@ -1140,6 +1151,7 @@ Prints a list of all supported version control systems. Useful to find out possible contexts (and which of them are enabled) or values for the var(disable) style. ) +findex(vcs_info_setsys) item(tt(vcs_info_setsys))( Initializes var(vcs_info)'s internal list of available backends. With this function, you can add support for new VCSs @@ -1187,13 +1199,20 @@ avoid namespace problems, all registered function names are prepended by a `+vi-', so the actual functions called for the `foo' hook are `tt(+vi-bar)' and `tt(+vi-baz)'. +If you would like to register a function to a hook regardless of the +current context, you may use the var(vcs_info_hookadd) function. To remove +a function that was added like that, the var(vcs_info_hookdel) function +can be used. + If something seems weird, you can enable the `debug' boolean style in the proper context and the hook-calling code will print what it tried to execute and whether the function in question existed. When you register more than one function to a hook, all functions are executed one after another until one function returns non-zero or until -all functions have been called. +all functions have been called. Context-sensitive hook functions are +executed tt(before) statically registered ones (the ones added by +var(vcs_info_hookadd)). You may pass data between functions via an associative array, tt(user_data). For example: @@ -1292,6 +1311,11 @@ When setting tt(ret) to non-zero, the string in tt(${hook_com[guards-string]}) will be used in the var(%g) escape in the tt(patch-format) and tt(nopatch-format) styles. ) +item(tt(no-vcs))( +This hooks is called when no version control system was detected. + +The `hook_com' parameter is not used. +) item(tt(post-quilt))( Called after the tt(quilt) support is done. The following information is passed as arguments to the hook: 1. the quilt-support mode (`addon' or @@ -1309,7 +1333,7 @@ The `tt(hook_com)' keys considered are `tt(branch)' and `tt(revision)'. They are set to the values figured out so far by var(vcs_info) and any change will be used directly when the actual replacement is done. -If tt(ret) is set to to non-zero, the string in +If tt(ret) is set to non-zero, the string in tt(${hook_com[branch-replace]}) will be used unchanged as the `tt(%b)' replacement in the variables set by var(vcs_info). ) @@ -1321,7 +1345,7 @@ The `tt(hook_com)' keys considered are `tt(hash)' and `tt(localrev)'. They are set to the values figured out so far by var(vcs_info) and any change will be used directly when the actual replacement is done. -If tt(ret) is set to to non-zero, the string in +If tt(ret) is set to non-zero, the string in tt(${hook_com[rev-replace]}) will be used unchanged as the `tt(%i)' replacement in the variables set by var(vcs_info). ) @@ -1346,7 +1370,7 @@ so even if you changed a value to your liking you can still get the original value in the next run. Changing the `tt(_orig)' values is probably not a good idea. -If tt(ret) is set to to non-zero, the string in +If tt(ret) is set to non-zero, the string in tt(${hook_com[message]}) will be used unchanged as the message by var(vcs_info). ) @@ -1771,22 +1795,6 @@ The tt(word-context) style is implemented by the function tt(match-word-context). This should not usually need to be called directly. ) -tindex(delete-whole-word-match) -item(tt(delete-whole-word-match))( -This is another function which works like the tt(-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 tt(kill), the removed text -will be placed in the cutbuffer for future yanking. This can be obtained -by defining tt(kill-whole-word-match) as follows: - -example(zle -N kill-whole-word-match delete-whole-word-match) - -and then binding the widget tt(kill-whole-word-match). -) tindex(copy-earlier-word) item(tt(copy-earlier-word))( This widget works like a combination of tt(insert-last-word) and @@ -1818,6 +1826,33 @@ 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. ) +tindex(delete-whole-word-match) +item(tt(delete-whole-word-match))( +This is another function which works like the tt(-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 tt(kill), the removed text +will be placed in the cutbuffer for future yanking. This can be obtained +by defining tt(kill-whole-word-match) as follows: + +example(zle -N kill-whole-word-match delete-whole-word-match) + +and then binding the widget tt(kill-whole-word-match). +) +tindex(down-line-or-beginning-search) +tindex(up-line-or-beginning-search) +item(tt(up-line-or-beginning-search), tt(down-line-or-beginning-search))( +These widgets are similar to the builtin functions tt(up-line-or-search) +and tt(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 tt(history-beginning-search-backward) and tt(-forward), rather +than the first word on the line. +) tindex(edit-command-line) item(tt(edit-command-line))( Edit the command line using your visual editor, as in tt(ksh). @@ -1890,17 +1925,6 @@ example(autoload -U history-pattern-search zle -N history-pattern-search-backward history-pattern-search zle -N history-pattern-search-forward history-pattern-search) ) -tindex(up-line-or-beginning-search) -tindex(down-line-or-beginning-search) -item(tt(up-line-or-beginning-search), tt(down-line-or-beginning-search))( -These widgets are similar to the builtin functions tt(up-line-or-search) -and tt(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 tt(history-beginning-search-backward) and tt(-forward), rather -than the first word on the line. -) tindex(incarg) vindex(incarg, use of) item(tt(incarg))( @@ -1964,7 +1988,7 @@ See tt(insert-unicode-char) for an alternative way of inserting Unicode characters using their hexadecimal character number. The set of accented characters is reasonably complete up to Unicode -character U+0180, the set of special characters less so. However, it it +character U+0180, the set of special characters less so. However, it is very sporadic from that point. Adding new characters is easy, however; see the function tt(define-composed-chars). Please send any additions to tt(zsh-workers@zsh.org). @@ -2130,6 +2154,17 @@ into the command line. example(bindkey '^Xf' insert-files) ) +tindex(insert-unicode-char) +item(tt(insert-unicode-char))( +When first executed, the user inputs a set of hexadecimal digits. +This is terminated with another call to tt(insert-unicode-char). +The digits are then turned into the corresponding Unicode character. +For example, if the widget is bound to tt(^XU), the character sequence +`tt(^XU 4 c ^XU)' inserts tt(L) (Unicode U+004c). + +See tt(insert-composed-char) for a way of inserting characters +using a two-character mnemonic. +) tindex(narrow-to-region) tindex(narrow-to-region-invisible) xitem(tt(narrow-to-region [ -p) var(pre) tt(] [ -P) var(post) tt(])) @@ -2187,17 +2222,6 @@ narrow-to-region -p $'Editing restricted region\n' \ zle recursive-edit narrow-to-region -R state) ) -tindex(insert-unicode-char) -item(tt(insert-unicode-char))( -When first executed, the user inputs a set of hexadecimal digits. -This is terminated with another call to tt(insert-unicode-char). -The digits are then turned into the corresponding Unicode character. -For example, if the widget is bound to tt(^XU), the character sequence -`tt(^XU 4 c ^XU)' inserts tt(L) (Unicode U+004c). - -See tt(insert-composed-char) for a way of inserting characters -using a two-character mnemonic. -) tindex(predict-on) tindex(predict-off) item(tt(predict-on))( @@ -2325,6 +2349,25 @@ tt(narrow-to-region-invisible) widget. One limitation of the current version is that tt(undo) will cycle through changes to the replacement and source strings before undoing the replacement itself. ) +tindex(send-invisible) +item(tt(send-invisible))( +This is similar to read-from-minibuffer in that it may be called as a +function from a widget or as a widget of its own, and interactively reads +input from the keyboard. However, the input being typed is concealed and +a string of asterisks (`tt(*)') is shown instead. The value is saved in +the paramter tt($INVISIBLE) to which a reference is inserted into the +editing buffer at the restored cursor position. If the read was aborted +by a keyboard break (typically tt(^G)) or another escape from editing such +as tt(push-line), tt($INVISIBLE) is set to empty and the original buffer +is restored unchanged. + +If one argument is supplied to the function it is taken as a prompt, +otherwise `tt(Non-echoed text: )' is used (as in emacs). If a second and +third argument are supplied they are used to begin and end the reference +to tt($INVISIBLE) that is inserted into the buffer. The default is to +open with tt(${), then tt(INVISIBLE), and close with tt(}), but many +other effects are possible. +) tindex(smart-insert-last-word) item(tt(smart-insert-last-word))( This function may replace the tt(insert-last-word) widget, like so: @@ -3000,7 +3043,7 @@ tt(firefox mozilla netscape opera konqueror). ) item(tt(tty-browsers))( An array similar to tt(x-browsers), except that it gives browsers to -use use when no X Window display is available. The default is +use when no X Window display is available. The default is tt(elinks links lynx). ) item(tt(command))( |