diff options
Diffstat (limited to 'assets/info/zsh.info-3')
| -rw-r--r-- | assets/info/zsh.info-3 | 5810 |
1 files changed, 5810 insertions, 0 deletions
diff --git a/assets/info/zsh.info-3 b/assets/info/zsh.info-3 new file mode 100644 index 00000000..34127397 --- /dev/null +++ b/assets/info/zsh.info-3 @@ -0,0 +1,5810 @@ +This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi. + +INFO-DIR-SECTION Utilities +START-INFO-DIR-ENTRY +* ZSH: (zsh). The Z Shell Manual. +END-INFO-DIR-ENTRY + + +File: zsh.info, Node: History Control, Next: Modifying Text, Prev: Movement, Up: Zle Widgets + +18.6.2 History Control +---------------------- + + +beginning-of-buffer-or-history (ESC-<) (gg) (unbound) + Move to the beginning of the buffer, or if already there, move to + the first event in the history list. + +beginning-of-line-hist + Move to the beginning of the line. If already at the beginning of + the buffer, move to the previous history line. + +beginning-of-history + Move to the first event in the history list. + +down-line-or-history (^N ESC-[B) (j) (ESC-[B) + Move down a line in the buffer, or if already at the bottom line, + move to the next event in the history list. + +vi-down-line-or-history (unbound) (+) (unbound) + Move down a line in the buffer, or if already at the bottom line, + move to the next event in the history list. Then move to the + first non-blank character on the line. + +down-line-or-search + Move down a line in the buffer, or if already at the bottom line, + search forward in the history for a line beginning with the first + word in the buffer. + + If called from a function by the zle command with arguments, the + first argument is taken as the string for which to search, rather + than the first word in the buffer. + +down-history (unbound) (^N) (unbound) + Move to the next event in the history list. + +history-beginning-search-backward + Search backward in the history for a line beginning with the + current line up to the cursor. This leaves the cursor in its + original position. + +end-of-buffer-or-history (ESC->) (unbound) (unbound) + Move to the end of the buffer, or if already there, move to the + last event in the history list. + +end-of-line-hist + Move to the end of the line. If already at the end of the buffer, + move to the next history line. + +end-of-history + Move to the last event in the history list. + +vi-fetch-history (unbound) (G) (unbound) + Fetch the history line specified by the numeric argument. This + defaults to the current history line (i.e. the one that isn't + history yet). + +history-incremental-search-backward (^R ^Xr) (unbound) (unbound) + Search backward incrementally for a specified string. The search + is case-insensitive if the search string does not have uppercase + letters and no numeric argument was given. The string may begin + with `^' to anchor the search to the beginning of the line. When + called from a user-defined function returns the following + statuses: 0, if the search succeeded; 1, if the search failed; 2, + if the search term was a bad pattern; 3, if the search was aborted + by the send-break command. + + A restricted set of editing functions is available in the + mini-buffer. Keys are looked up in the special isearch keymap, + and if not found there in the main keymap (note that by default + the isearch keymap is empty). An interrupt signal, as defined by + the stty setting, will stop the search and go back to the original + line. An undefined key will have the same effect. Note that the + following always perform the same task within incremental searches + and cannot be replaced by user defined widgets, nor can the set of + functions be extended. The supported functions are: + + + accept-and-hold + accept-and-infer-next-history + accept-line + accept-line-and-down-history + Perform the usual function after exiting incremental search. + The command line displayed is executed. + + backward-delete-char + vi-backward-delete-char + Back up one place in the search history. If the search has + been repeated this does not immediately erase a character in + the minibuffer. + + accept-search + Exit incremental search, retaining the command line but + performing no further action. Note that this function is not + bound by default and has no effect outside incremental search. + + backward-delete-word + backward-kill-word + vi-backward-kill-word + Back up one character in the minibuffer; if multiple searches + have been performed since the character was inserted the + search history is rewound to the point just before the + character was entered. Hence this has the effect of repeating + backward-delete-char. + + clear-screen + Clear the screen, remaining in incremental search mode. + + history-incremental-search-backward + Find the next occurrence of the contents of the mini-buffer. + If the mini-buffer is empty, the most recent previously used + search string is reinstated. + + history-incremental-search-forward + Invert the sense of the search. + + magic-space + Inserts a non-magical space. + + quoted-insert + vi-quoted-insert + Quote the character to insert into the minibuffer. + + redisplay + Redisplay the command line, remaining in incremental search + mode. + + vi-cmd-mode + Select the `vicmd' keymap; the `main' keymap (insert mode) + will be selected initially. + + In addition, the modifications that were made while in vi + insert mode are merged to form a single undo event. + + vi-repeat-search + vi-rev-repeat-search + Repeat the search. The direction of the search is indicated + in the mini-buffer. + + + Any character that is not bound to one of the above functions, or + self-insert or self-insert-unmeta, will cause the mode to be + exited. The character is then looked up and executed in the + keymap in effect at that point. + + When called from a widget function by the zle command, the + incremental search commands can take a string argument. This will + be treated as a string of keys, as for arguments to the bindkey + command, and used as initial input for the command. Any + characters in the string which are unused by the incremental + search will be silently ignored. For example, + + + zle history-incremental-search-backward forceps + + will search backwards for forceps, leaving the minibuffer + containing the string `forceps'. + +history-incremental-search-forward (^S ^Xs) (unbound) (unbound) + Search forward incrementally for a specified string. The search is + case-insensitive if the search string does not have uppercase + letters and no numeric argument was given. The string may begin + with `^' to anchor the search to the beginning of the line. The + functions available in the mini-buffer are the same as for + history-incremental-search-backward. + +history-incremental-pattern-search-backward +history-incremental-pattern-search-forward + These widgets behave similarly to the corresponding widgets with + no -pattern, but the search string typed by the user is treated as + a pattern, respecting the current settings of the various options + affecting pattern matching. See *Note Filename Generation:: for a + description of patterns. If no numeric argument was given + lowercase letters in the search string may match uppercase letters + in the history. The string may begin with `^' to anchor the + search to the beginning of the line. + + The prompt changes to indicate an invalid pattern; this may simply + indicate the pattern is not yet complete. + + Note that only non-overlapping matches are reported, so an + expression with wildcards may return fewer matches on a line than + are visible by inspection. + +history-search-backward (ESC-P ESC-p) (unbound) (unbound) + Search backward in the history for a line beginning with the first + word in the buffer. + + If called from a function by the zle command with arguments, the + first argument is taken as the string for which to search, rather + than the first word in the buffer. + +vi-history-search-backward (unbound) (/) (unbound) + Search backward in the history for a specified string. The string + may begin with `^' to anchor the search to the beginning of the + line. + + A restricted set of editing functions is available in the + mini-buffer. An interrupt signal, as defined by the stty setting, + will stop the search. The functions available in the mini-buffer + are: accept-line, backward-delete-char, vi-backward-delete-char, + backward-kill-word, vi-backward-kill-word, clear-screen, redisplay, + quoted-insert and vi-quoted-insert. + + vi-cmd-mode is treated the same as accept-line, and magic-space is + treated as a space. Any other character that is not bound to + self-insert or self-insert-unmeta will beep and be ignored. If the + function is called from vi command mode, the bindings of the + current insert mode will be used. + + If called from a function by the zle command with arguments, the + first argument is taken as the string for which to search, rather + than the first word in the buffer. + +history-search-forward (ESC-N ESC-n) (unbound) (unbound) + Search forward in the history for a line beginning with the first + word in the buffer. + + If called from a function by the zle command with arguments, the + first argument is taken as the string for which to search, rather + than the first word in the buffer. + +vi-history-search-forward (unbound) (?) (unbound) + Search forward in the history for a specified string. The string + may begin with `^' to anchor the search to the beginning of the + line. The functions available in the mini-buffer are the same as + for vi-history-search-backward. Argument handling is also the same + as for that command. + +infer-next-history (^X^N) (unbound) (unbound) + Search in the history list for a line matching the current one and + fetch the event following it. + +insert-last-word (ESC-_ ESC-.) (unbound) (unbound) + Insert the last word from the previous history event at the cursor + position. If a positive numeric argument is given, insert that + word from the end of the previous history event. If the argument + is zero or negative insert that word from the left (zero inserts + the previous command word). Repeating this command replaces the + word just inserted with the last word from the history event prior + to the one just used; numeric arguments can be used in the same + way to pick a word from that event. + + When called from a shell function invoked from a user-defined + widget, the command can take one to three arguments. The first + argument specifies a history offset which applies to successive + calls to this widget: if it is -1, the default behaviour is used, + while if it is 1, successive calls will move forwards through the + history. The value 0 can be used to indicate that the history + line examined by the previous execution of the command will be + reexamined. Note that negative numbers should be preceded by a + `--' argument to avoid confusing them with options. + + If two arguments are given, the second specifies the word on the + command line in normal array index notation (as a more natural + alternative to the numeric argument). Hence 1 is the first word, + and -1 (the default) is the last word. + + If a third argument is given, its value is ignored, but it is used + to signify that the history offset is relative to the current + history line, rather than the one remembered after the previous + invocations of insert-last-word. + + For example, the default behaviour of the command corresponds to + + + zle insert-last-word -- -1 -1 + + while the command + + + zle insert-last-word -- -1 1 - + + always copies the first word of the line in the history + immediately before the line being edited. This has the side + effect that later invocations of the widget will be relative to + that line. + +vi-repeat-search (unbound) (n) (unbound) + Repeat the last vi history search. + +vi-rev-repeat-search (unbound) (N) (unbound) + Repeat the last vi history search, but in reverse. + +up-line-or-history (^P ESC-[A) (k) (ESC-[A) + Move up a line in the buffer, or if already at the top line, move + to the previous event in the history list. + +vi-up-line-or-history (unbound) (-) (unbound) + Move up a line in the buffer, or if already at the top line, move + to the previous event in the history list. Then move to the first + non-blank character on the line. + +up-line-or-search + Move up a line in the buffer, or if already at the top line, + search backward in the history for a line beginning with the first + word in the buffer. + + If called from a function by the zle command with arguments, the + first argument is taken as the string for which to search, rather + than the first word in the buffer. + +up-history (unbound) (^P) (unbound) + Move to the previous event in the history list. + +history-beginning-search-forward + Search forward in the history for a line beginning with the current + line up to the cursor. This leaves the cursor in its original + position. + +set-local-history + By default, history movement commands visit the imported lines as + well as the local lines. This widget lets you toggle this on and + off, or set it with the numeric argument. Zero for both local and + imported lines and nonzero for only local lines. + + + +File: zsh.info, Node: Modifying Text, Next: Arguments, Prev: History Control, Up: Zle Widgets + +18.6.3 Modifying Text +--------------------- + + +vi-add-eol (unbound) (A) (unbound) + Move to the end of the line and enter insert mode. + +vi-add-next (unbound) (a) (unbound) + Enter insert mode after the current cursor position, without + changing lines. + +backward-delete-char (^H ^?) (unbound) (unbound) + Delete the character behind the cursor. + +vi-backward-delete-char (unbound) (X) (^H) + Delete the character behind the cursor, without changing lines. + If in insert mode, this won't delete past the point where insert + mode was last entered. + +backward-delete-word + Delete the word behind the cursor. + +backward-kill-line + Kill from the beginning of the line to the cursor position. + +backward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound) + Kill the word behind the cursor. + +vi-backward-kill-word (unbound) (unbound) (^W) + Kill the word behind the cursor, without going past the point + where insert mode was last entered. + +capitalize-word (ESC-C ESC-c) (unbound) (unbound) + Capitalize the current word and move past it. + +vi-change (unbound) (c) (unbound) + Read a movement command from the keyboard, and kill from the + cursor position to the endpoint of the movement. Then enter + insert mode. If the command is vi-change, change the current line. + + For compatibility with vi, if the command is vi-forward-word or + vi-forward-blank-word, the whitespace after the word is not + included. If you prefer the more consistent behaviour with the + whitespace included use the following key binding: + + + bindkey -a -s cw dwi + +vi-change-eol (unbound) (C) (unbound) + Kill to the end of the line and enter insert mode. + +vi-change-whole-line (unbound) (S) (unbound) + Kill the current line and enter insert mode. + +copy-region-as-kill (ESC-W ESC-w) (unbound) (unbound) + Copy the area from the cursor to the mark to the kill buffer. + + If called from a ZLE widget function in the form `zle + copy-region-as-kill STRING' then STRING will be taken as the text + to copy to the kill buffer. The cursor, the mark and the text on + the command line are not used in this case. + +copy-prev-word (ESC-^_) (unbound) (unbound) + Duplicate the word to the left of the cursor. + +copy-prev-shell-word + Like copy-prev-word, but the word is found by using shell parsing, + whereas copy-prev-word looks for blanks. This makes a difference + when the word is quoted and contains spaces. + +vi-delete (unbound) (d) (unbound) + Read a movement command from the keyboard, and kill from the + cursor position to the endpoint of the movement. If the command + is vi-delete, kill the current line. + +delete-char + Delete the character under the cursor. + +vi-delete-char (unbound) (x) (unbound) + Delete the character under the cursor, without going past the end + of the line. + +delete-word + Delete the current word. + +down-case-word (ESC-L ESC-l) (unbound) (unbound) + Convert the current word to all lowercase and move past it. + +vi-down-case (unbound) (gu) (unbound) + Read a movement command from the keyboard, and convert all + characters from the cursor position to the endpoint of the + movement to lowercase. If the movement command is vi-down-case, + swap the case of all characters on the current line. + +kill-word (ESC-D ESC-d) (unbound) (unbound) + Kill the current word. + +gosmacs-transpose-chars + Exchange the two characters behind the cursor. + +vi-indent (unbound) (>) (unbound) + Indent a number of lines. + +vi-insert (unbound) (i) (unbound) + Enter insert mode. + +vi-insert-bol (unbound) (I) (unbound) + Move to the first non-blank character on the line and enter insert + mode. + +vi-join (^X^J) (J) (unbound) + Join the current line with the next one. + +kill-line (^K) (unbound) (unbound) + Kill from the cursor to the end of the line. If already on the + end of the line, kill the newline character. + +vi-kill-line (unbound) (unbound) (^U) + Kill from the cursor back to wherever insert mode was last entered. + +vi-kill-eol (unbound) (D) (unbound) + Kill from the cursor to the end of the line. + +kill-region + Kill from the cursor to the mark. + +kill-buffer (^X^K) (unbound) (unbound) + Kill the entire buffer. + +kill-whole-line (^U) (unbound) (unbound) + Kill the current line. + +vi-match-bracket (^X^B) (%) (unbound) + Move to the bracket character (one of {}, () or []) that matches + the one under the cursor. If the cursor is not on a bracket + character, move forward without going past the end of the line to + find one, and then go to the matching bracket. + +vi-open-line-above (unbound) (O) (unbound) + Open a line above the cursor and enter insert mode. + +vi-open-line-below (unbound) (o) (unbound) + Open a line below the cursor and enter insert mode. + +vi-oper-swap-case (unbound) (g~) (unbound) + Read a movement command from the keyboard, and swap the case of + all characters from the cursor position to the endpoint of the + movement. If the movement command is vi-oper-swap-case, swap the + case of all characters on the current line. + +overwrite-mode (^X^O) (unbound) (unbound) + Toggle between overwrite mode and insert mode. + +vi-put-before (unbound) (P) (unbound) + Insert the contents of the kill buffer before the cursor. If the + kill buffer contains a sequence of lines (as opposed to + characters), paste it above the current line. + +vi-put-after (unbound) (p) (unbound) + Insert the contents of the kill buffer after the cursor. If the + kill buffer contains a sequence of lines (as opposed to + characters), paste it below the current line. + +put-replace-selection (unbound) (unbound) (unbound) + Replace the contents of the current region or selection with the + contents of the kill buffer. If the kill buffer contains a + sequence of lines (as opposed to characters), the current line + will be split by the pasted lines. + +quoted-insert (^V) (unbound) (unbound) + Insert the next character typed into the buffer literally. An + interrupt character will not be inserted. + +vi-quoted-insert (unbound) (unbound) (^Q ^V) + Display a `^' at the cursor position, and insert the next + character typed into the buffer literally. An interrupt character + will not be inserted. + +quote-line (ESC-') (unbound) (unbound) + Quote the current line; that is, put a `'' character at the + beginning and the end, and convert all `'' characters to `'\'''. + +quote-region (ESC-") (unbound) (unbound) + Quote the region from the cursor to the mark. + +vi-replace (unbound) (R) (unbound) + Enter overwrite mode. + +vi-repeat-change (unbound) (.) (unbound) + Repeat the last vi mode text modification. If a count was used + with the modification, it is remembered. If a count is given to + this command, it overrides the remembered count, and is remembered + for future uses of this command. The cut buffer specification is + similarly remembered. + +vi-replace-chars (unbound) (r) (unbound) + Replace the character under the cursor with a character read from + the keyboard. + +self-insert (printable characters) (unbound) (printable characters and some control characters) + Insert a character into the buffer at the cursor position. + +self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound) + Insert a character into the buffer after stripping the meta bit + and converting ^M to ^J. + +vi-substitute (unbound) (s) (unbound) + Substitute the next character(s). + +vi-swap-case (unbound) (~) (unbound) + Swap the case of the character under the cursor and move past it. + +transpose-chars (^T) (unbound) (unbound) + Exchange the two characters to the left of the cursor if at end of + line, else exchange the character under the cursor with the + character to the left. + +transpose-words (ESC-T ESC-t) (unbound) (unbound) + Exchange the current word with the one before it. + + With a positive numeric argument _N_, the word around the cursor, + or following it if the cursor is between words, is transposed with + the preceding _N_ words. The cursor is put at the end of the + resulting group of words. + + With a negative numeric argument _-N_, the effect is the same as + using a positive argument _N_ except that the original cursor + position is retained, regardless of how the words are rearranged. + +vi-unindent (unbound) (<) (unbound) + Unindent a number of lines. + +vi-up-case (unbound) (gU) (unbound) + Read a movement command from the keyboard, and convert all + characters from the cursor position to the endpoint of the + movement to lowercase. If the movement command is vi-up-case, + swap the case of all characters on the current line. + +up-case-word (ESC-U ESC-u) (unbound) (unbound) + Convert the current word to all caps and move past it. + +yank (^Y) (unbound) (unbound) + Insert the contents of the kill buffer at the cursor position. + +yank-pop (ESC-y) (unbound) (unbound) + Remove the text just yanked, rotate the kill-ring (the history of + previously killed text) and yank the new top. Only works following + yank, vi-put-before, vi-put-after or yank-pop. + +vi-yank (unbound) (y) (unbound) + Read a movement command from the keyboard, and copy the region + from the cursor position to the endpoint of the movement into the + kill buffer. If the command is vi-yank, copy the current line. + +vi-yank-whole-line (unbound) (Y) (unbound) + Copy the current line into the kill buffer. + +vi-yank-eol + Copy the region from the cursor position to the end of the line + into the kill buffer. Arguably, this is what Y should do in vi, + but it isn't what it actually does. + + + +File: zsh.info, Node: Arguments, Next: Completion, Prev: Modifying Text, Up: Zle Widgets + +18.6.4 Arguments +---------------- + + +digit-argument (ESC-0..ESC-9) (1-9) (unbound) + Start a new numeric argument, or add to the current one. See also + vi-digit-or-beginning-of-line. This only works if bound to a key + sequence ending in a decimal digit. + + Inside a widget function, a call to this function treats the last + key of the key sequence which called the widget as the digit. + +neg-argument (ESC--) (unbound) (unbound) + Changes the sign of the following argument. + +universal-argument + Multiply the argument of the next command by 4. Alternatively, if + this command is followed by an integer (positive or negative), use + that as the argument for the next command. Thus digits cannot be + repeated using this command. For example, if this command occurs + twice, followed immediately by forward-char, move forward sixteen + spaces; if instead it is followed by -2, then forward-char, move + backward two spaces. + + Inside a widget function, if passed an argument, i.e. `zle + universal-argument NUM', the numeric argument will be set to NUM; + this is equivalent to `NUMERIC=NUM'. + +argument-base + Use the existing numeric argument as a numeric base, which must be + in the range 2 to 36 inclusive. Subsequent use of digit-argument + and universal-argument will input a new numeric argument in the + given base. The usual hexadecimal convention is used: the letter + a or A corresponds to 10, and so on. Arguments in bases requiring + digits from 10 upwards are more conveniently input with + universal-argument, since ESC-a etc. are not usually bound to + digit-argument. + + The function can be used with a command argument inside a + user-defined widget. The following code sets the base to 16 and + lets the user input a hexadecimal argument until a key out of the + digit range is typed: + + + zle argument-base 16 + zle universal-argument + + + +File: zsh.info, Node: Completion, Next: Miscellaneous, Prev: Arguments, Up: Zle Widgets + +18.6.5 Completion +----------------- + + +accept-and-menu-complete + In a menu completion, insert the current completion into the + buffer, and advance to the next possible completion. + +complete-word + Attempt completion on the current word. + +delete-char-or-list (^D) (unbound) (unbound) + Delete the character under the cursor. If the cursor is at the + end of the line, list possible completions for the current word. + +expand-cmd-path + Expand the current command to its full pathname. + +expand-or-complete (TAB) (unbound) (TAB) + Attempt shell expansion on the current word. If that fails, + attempt completion. + +expand-or-complete-prefix + Attempt shell expansion on the current word up to cursor. + +expand-history (ESC-space ESC-!) (unbound) (unbound) + Perform history expansion on the edit buffer. + +expand-word (^X*) (unbound) (unbound) + Attempt shell expansion on the current word. + +list-choices (ESC-^D) (^D =) (^D) + List possible completions for the current word. + +list-expand (^Xg ^XG) (^G) (^G) + List the expansion of the current word. + +magic-space + Perform history expansion and insert a space into the buffer. + This is intended to be bound to space. + +menu-complete + Like complete-word, except that menu completion is used. See the + MENU_COMPLETE option. + +menu-expand-or-complete + Like expand-or-complete, except that menu completion is used. + +reverse-menu-complete + Perform menu completion, like menu-complete, except that if a menu + completion is already in progress, move to the _previous_ + completion rather than the next. + +end-of-list + When a previous completion displayed a list below the prompt, this + widget can be used to move the prompt below the list. + + + +File: zsh.info, Node: Miscellaneous, Next: Text Objects, Prev: Completion, Up: Zle Widgets + +18.6.6 Miscellaneous +-------------------- + + +accept-and-hold (ESC-A ESC-a) (unbound) (unbound) + Push the contents of the buffer on the buffer stack and execute it. + +accept-and-infer-next-history + Execute the contents of the buffer. Then search the history list + for a line matching the current one and push the event following + onto the buffer stack. + +accept-line (^J ^M) (^J ^M) (^J ^M) + Finish editing the buffer. Normally this causes the buffer to be + executed as a shell command. + +accept-line-and-down-history (^O) (unbound) (unbound) + Execute the current line, and push the next history event on the + buffer stack. + +auto-suffix-remove + If the previous action added a suffix (space, slash, etc.) to the + word on the command line, remove it. Otherwise do nothing. + Removing the suffix ends any active menu completion or menu + selection. + + This widget is intended to be called from user-defined widgets to + enforce a desired suffix-removal behavior. + +auto-suffix-retain + If the previous action added a suffix (space, slash, etc.) to the + word on the command line, force it to be preserved. Otherwise do + nothing. Retaining the suffix ends any active menu completion or + menu selection. + + This widget is intended to be called from user-defined widgets to + enforce a desired suffix-preservation behavior. + +beep + Beep, unless the BEEP option is unset. + +bracketed-paste + This widget is invoked when text is pasted to the terminal + emulator. It is not intended to be bound to actual keys but + instead to the special sequence generated by the terminal emulator + when text is pasted. + + When invoked interactively, the pasted text is inserted to the + buffer and placed in the cutbuffer. If a numeric argument is + given, shell quoting will be applied to the pasted text before it + is inserted. + + When a named buffer is specified with vi-set-buffer ("x), the + pasted text is stored in that named buffer but not inserted. + + When called from a widget function as `bracketed-paste NAME`, the + pasted text is assigned to the variable NAME and no other + processing is done. + + See also the zle_bracketed_paste parameter. + +vi-cmd-mode (^X^V) (unbound) (^[) + Enter command mode; that is, select the `vicmd' keymap. Yes, this + is bound by default in emacs mode. + +vi-caps-lock-panic + Hang until any lowercase key is pressed. This is for vi users + without the mental capacity to keep track of their caps lock key + (like the author). + +clear-screen (^L ESC-^L) (^L) (^L) + Clear the screen and redraw the prompt. + +deactivate-region + Make the current region inactive. This disables vim-style visual + selection mode if it is active. + +describe-key-briefly + Reads a key sequence, then prints the function bound to that + sequence. + +exchange-point-and-mark (^X^X) (unbound) (unbound) + Exchange the cursor position (point) with the position of the mark. + Unless a negative numeric argument is given, the region between + point and mark is activated so that it can be highlighted. If a + zero numeric argument is given, the region is activated but point + and mark are not swapped. + +execute-named-cmd (ESC-x) (:) (unbound) + Read the name of an editor command and execute it. Aliasing this + widget with `zle -A' or replacing it with `zle -N' has no effect + when interpreting key bindings, but `zle execute-named-cmd' will + invoke such an alias or replacement. + + A restricted set of editing functions is available in the + mini-buffer. Keys are looked up in the special command keymap, + and if not found there in the main keymap. An interrupt signal, + as defined by the stty setting, will abort the function. Note + that the following always perform the same task within the + executed-named-cmd environment and cannot be replaced by user + defined widgets, nor can the set of functions be extended. The + allowed functions are: backward-delete-char, + vi-backward-delete-char, clear-screen, redisplay, quoted-insert, + vi-quoted-insert, backward-kill-word, vi-backward-kill-word, + kill-whole-line, vi-kill-line, backward-kill-line, list-choices, + delete-char-or-list, complete-word, accept-line, + expand-or-complete and expand-or-complete-prefix. + + kill-region kills the last word, and vi-cmd-mode is treated the + same as accept-line. The space and tab characters, if not bound + to one of these functions, will complete the name and then list the + possibilities if the AUTO_LIST option is set. Any other character + that is not bound to self-insert or self-insert-unmeta will beep + and be ignored. The bindings of the current insert mode will be + used. + + Currently this command may not be redefined or called by name. + +execute-last-named-cmd (ESC-z) (unbound) (unbound) + Redo the last function executed with execute-named-cmd. + + Like execute-named-cmd, this command may not be redefined, but it + may be called by name. + +get-line (ESC-G ESC-g) (unbound) (unbound) + Pop the top line off the buffer stack and insert it at the cursor + position. + +pound-insert (unbound) (#) (unbound) + If there is no # character at the beginning of the buffer, add one + to the beginning of each line. If there is one, remove a # from + each line that has one. In either case, accept the current line. + The INTERACTIVE_COMMENTS option must be set for this to have any + usefulness. + +vi-pound-insert + If there is no # character at the beginning of the current line, + add one. If there is one, remove it. The INTERACTIVE_COMMENTS + option must be set for this to have any usefulness. + +push-input + Push the entire current multiline construct onto the buffer stack + and return to the top-level (PS1) prompt. If the current parser + construct is only a single line, this is exactly like push-line. + Next time the editor starts up or is popped with get-line, the + construct will be popped off the top of the buffer stack and loaded + into the editing buffer. + +push-line (^Q ESC-Q ESC-q) (unbound) (unbound) + Push the current buffer onto the buffer stack and clear the buffer. + Next time the editor starts up, the buffer will be popped off the + top of the buffer stack and loaded into the editing buffer. + +push-line-or-edit + At the top-level (PS1) prompt, equivalent to push-line. At a + secondary (PS2) prompt, move the entire current multiline + construct into the editor buffer. The latter is equivalent to + push-input followed by get-line. + +read-command + Only useful from a user-defined widget. A keystroke is read just + as in normal operation, but instead of the command being executed + the name of the command that would be executed is stored in the + shell parameter REPLY. This can be used as the argument of a + future zle command. If the key sequence is not bound, status 1 is + returned; typically, however, REPLY is set to undefined-key to + indicate a useless key sequence. + +recursive-edit + Only useful from a user-defined widget. At this point in the + function, the editor regains control until one of the standard + widgets which would normally cause zle to exit (typically an + accept-line caused by hitting the return key) is executed. + Instead, control returns to the user-defined widget. The status + returned is non-zero if the return was caused by an error, but the + function still continues executing and hence may tidy up. This + makes it safe for the user-defined widget to alter the command + line or key bindings temporarily. + + The following widget, caps-lock, serves as an example. + + + self-insert-ucase() { + LBUFFER+=${(U)KEYS[-1]} + } + + integer stat + + zle -N self-insert self-insert-ucase + zle -A caps-lock save-caps-lock + zle -A accept-line caps-lock + + zle recursive-edit + stat=$? + + zle -A .self-insert self-insert + zle -A save-caps-lock caps-lock + zle -D save-caps-lock + + (( stat )) && zle send-break + + return $stat + + This causes typed letters to be inserted capitalised until either + accept-line (i.e. typically the return key) is typed or the + caps-lock widget is invoked again; the later is handled by saving + the old definition of caps-lock as save-caps-lock and then + rebinding it to invoke accept-line. Note that an error from the + recursive edit is detected as a non-zero return status and + propagated by using the send-break widget. + +redisplay (unbound) (^R) (^R) + Redisplays the edit buffer. + +reset-prompt (unbound) (unbound) (unbound) + Force the prompts on both the left and right of the screen to be + re-expanded, then redisplay the edit buffer. This reflects + changes both to the prompt variables themselves and changes in the + expansion of the values (for example, changes in time or + directory, or changes to the value of variables referred to by the + prompt). + + Otherwise, the prompt is only expanded each time zle starts, and + when the display has been interrupted by output from another part + of the shell (such as a job notification) which causes the command + line to be reprinted. + + reset-prompt doesn't alter the special parameter LASTWIDGET. + + + +send-break (^G ESC-^G) (unbound) (unbound) + Abort the current editor function, e.g. execute-named-command, or + the editor itself, e.g. if you are in vared. Otherwise abort the + parsing of the current line; in this case the aborted line is + available in the shell variable ZLE_LINE_ABORTED. If the editor + is aborted from within vared, the variable ZLE_VARED_ABORTED is + set. + +run-help (ESC-H ESC-h) (unbound) (unbound) + Push the buffer onto the buffer stack, and execute the command + `run-help CMD', where CMD is the current command. run-help is + normally aliased to man. + +vi-set-buffer (unbound) (") (unbound) + Specify a buffer to be used in the following command. There are + 37 buffers that can be specified: the 26 `named' buffers "a to "z, + the `yank' buffer "0, the nine `queued' buffers "1 to "9 and the + `black hole' buffer "_. The named buffers can also be specified + as "A to "Z. + + When a buffer is specified for a cut, change or yank command, the + text concerned replaces the previous contents of the specified + buffer. If a named buffer is specified using a capital, the newly + cut text is appended to the buffer instead of overwriting it. When + using the "_ buffer, nothing happens. This can be useful for + deleting text without affecting any buffers. + + If no buffer is specified for a cut or change command, "1 is used, + and the contents of "1 to "8 are each shifted along one buffer; + the contents of "9 is lost. If no buffer is specified for a yank + command, "0 is used. Finally, a paste command without a specified + buffer will paste the text from the most recent command regardless + of any buffer that might have been used with that command. + + When called from a widget function by the zle command, the buffer + can optionally be specified with an argument. For example, + + + zle vi-set-buffer A + +vi-set-mark (unbound) (m) (unbound) + Set the specified mark at the cursor position. + +set-mark-command (^@) (unbound) (unbound) + Set the mark at the cursor position. If called with a negative + numeric argument, do not set the mark but deactivate the region so + that it is no longer highlighted (it is still usable for other + purposes). Otherwise the region is marked as active. + +spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound) + Attempt spelling correction on the current word. + +split-undo + Breaks the undo sequence at the current change. This is useful in + vi mode as changes made in insert mode are coalesced on entering + command mode. Similarly, undo will normally revert as one all the + changes made by a user-defined widget. + +undefined-key + This command is executed when a key sequence that is not bound to + any command is typed. By default it beeps. + +undo (^_ ^Xu ^X^U) (u) (unbound) + Incrementally undo the last text modification. When called from a + user-defined widget, takes an optional argument indicating a + previous state of the undo history as returned by the + UNDO_CHANGE_NO variable; modifications are undone until that state + is reached, subject to any limit imposed by the UNDO_LIMIT_NO + variable. + + Note that when invoked from vi command mode, the full prior change + made in insert mode is reverted, the changes having been merged + when command mode was selected. + +redo (unbound) (^R) (unbound) + Incrementally redo undone text modifications. + +vi-undo-change (unbound) (unbound) (unbound) + Undo the last text modification. If repeated, redo the + modification. + +visual-mode (unbound) (v) (unbound) + Toggle vim-style visual selection mode. If line-wise visual mode is + currently enabled then it is changed to being character-wise. If + used following an operator, it forces the subsequent movement + command to be treated as a character-wise movement. + +visual-line-mode (unbound) (V) (unbound) + Toggle vim-style line-wise visual selection mode. If character-wise + visual mode is currently enabled then it is changed to being + line-wise. If used following an operator, it forces the subsequent + movement command to be treated as a line-wise movement. + +what-cursor-position (^X=) (ga) (unbound) + Print the character under the cursor, its code as an octal, + decimal and hexadecimal number, the current cursor position within + the buffer and the column of the cursor in the current line. + +where-is + Read the name of an editor command and print the listing of key + sequences that invoke the specified command. A restricted set of + editing functions is available in the mini-buffer. Keys are + looked up in the special command keymap, and if not found there in + the main keymap. + +which-command (ESC-?) (unbound) (unbound) + Push the buffer onto the buffer stack, and execute the command + `which-command CMD'. where CMD is the current command. + which-command is normally aliased to whence. + +vi-digit-or-beginning-of-line (unbound) (0) (unbound) + If the last command executed was a digit as part of an argument, + continue the argument. Otherwise, execute vi-beginning-of-line. + + + +File: zsh.info, Node: Text Objects, Prev: Miscellaneous, Up: Zle Widgets + +18.6.7 Text Objects +------------------- + +Text objects are commands that can be used to select a block of text +according to some criteria. They are a feature of the vim text editor +and so are primarily intended for use with vi operators or from visual +selection mode. However, they can also be used from vi-insert or emacs +mode. Key bindings listed below apply to the viopp and visual keymaps. + + +select-a-blank-word (aW) + Select a word including adjacent blanks, where a word is defined + as a series of non-blank characters. With a numeric argument, + multiple words will be selected. + +select-a-shell-word (aa) + Select the current command argument applying the normal rules for + quoting. + +select-a-word (aw) + Select a word including adjacent blanks, using the normal vi-style + word definition. With a numeric argument, multiple words will be + selected. + +select-in-blank-word (iW) + Select a word, where a word is defined as a series of non-blank + characters. With a numeric argument, multiple words will be + selected. + +select-in-shell-word (ia) + Select the current command argument applying the normal rules for + quoting. If the argument begins and ends with matching quote + characters, these are not included in the selection. + +select-in-word (iw) + Select a word, using the normal vi-style word definition. With a + numeric argument, multiple words will be selected. + + + + +File: zsh.info, Node: Character Highlighting, Prev: Zle Widgets, Up: Zsh Line Editor + +18.7 Character Highlighting +=========================== + +The line editor has the ability to highlight characters or regions of +the line that have a particular significance. This is controlled by +the array parameter zle_highlight, if it has been set by the user. + +If the parameter contains the single entry none all highlighting is +turned off. Note the parameter is still expected to be an array. + +Otherwise each entry of the array should consist of a word indicating a +context for highlighting, then a colon, then a comma-separated list of +the types of highlighting to apply in that context. + +The contexts available for highlighting are the following: + + +default + Any text within the command line not affected by any other + highlighting. Text outside the editable area of the command line + is not affected. + +isearch + When one of the incremental history search widgets is active, the + area of the command line matched by the search string or pattern. + +region + The currently selected text. In emacs terminology, this is + referred to as the region and is bounded by the cursor (point) and + the mark. The region is only highlighted if it is active, which is + the case after the mark is modified with set-mark-command or + exchange-point-and-mark. Note that whether or not the region is + active has no effect on its use within emacs style widgets, it + simply determines whether it is highlighted. In vi mode, the + region corresponds to selected text in visual mode. + +special + Individual characters that have no direct printable representation + but are shown in a special manner by the line editor. These + characters are described below. + +suffix + This context is used in completion for characters that are marked + as suffixes that will be removed if the completion ends at that + point, the most obvious example being a slash (/) after a + directory name. Note that suffix removal is configurable; the + circumstances under which the suffix will be removed may differ + for different completions. + +paste + Following a command to paste text, the characters that were + inserted. + + +When region_highlight is set, the contexts that describe a region -- +isearch, region, suffix, and paste -- are applied first, then +region_highlight is applied, then the remaining zle_highlight contexts +are applied. If a particular character is affected by multiple +specifications, the last specification wins. + +zle_highlight may contain additional fields for controlling how +terminal sequences to change colours are output. Each of the following +is followed by a colon and a string in the same form as for key +bindings. This will not be necessary for the vast majority of +terminals as the defaults shown in parentheses are widely used. + + +fg_start_code (\e[3) + The start of the escape sequence for the foreground colour. This + is followed by one to three ASCII digits representing the colour. + Only used for palette colors, i.e. not 24-bit colors specified via + a color triplet. + +fg_default_code (9) + The number to use instead of the colour to reset the default + foreground colour. + +fg_end_code (m) + The end of the escape sequence for the foreground colour. + +bg_start_code (\e[4) + The start of the escape sequence for the background colour. See + fg_start_code above. + +bg_default_code (9) + The number to use instead of the colour to reset the default + background colour. + +bg_end_code (m) + The end of the escape sequence for the background colour. + + +The available types of highlighting are the following. Note that not +all types of highlighting are available on all terminals: + + +none + No highlighting is applied to the given context. It is not useful + for this to appear with other types of highlighting; it is used to + override a default. + +fg=COLOUR + The foreground colour should be set to COLOUR, a decimal integer, + the name of one of the eight most widely-supported colours or as a + `#' followed by an RGB triplet in hexadecimal format. + + Not all terminals support this and, of those that do, not all + provide facilities to test the support, hence the user should + decide based on the terminal type. Most terminals support the + colours black, red, green, yellow, blue, magenta, cyan and white, + which can be set by name. In addition. default may be used to set + the terminal's default foreground colour. Abbreviations are + allowed; b or bl selects black. Some terminals may generate + additional colours if the bold attribute is also present. + + On recent terminals and on systems with an up-to-date terminal + database the number of colours supported may be tested by the + command `echotc Co'; if this succeeds, it indicates a limit on the + number of colours which will be enforced by the line editor. The + number of colours is in any case limited to 256 (i.e. the range 0 + to 255). + + Some modern terminal emulators have support for 24-bit true colour + (16 million colours). In this case, the hex triplet format can be + used. This consists of a `#' followed by either a three or six + digit hexadecimal number describing the red, green and blue + components of the colour. Hex triplets can also be used with 88 + and 256 colour terminals via the zsh/nearcolor module (see *Note + The zsh/nearcolor Module::). + + Colour is also known as color. + +bg=COLOUR + The background colour should be set to COLOUR. This works + similarly to the foreground colour, except the background is not + usually affected by the bold attribute. + +bold + The characters in the given context are shown in a bold font. Not + all terminals distinguish bold fonts. + +standout + The characters in the given context are shown in the terminal's + standout mode. The actual effect is specific to the terminal; on + many terminals it is inverse video. On some such terminals, where + the cursor does not blink it appears with standout mode negated, + making it less than clear where the cursor actually is. On such + terminals one of the other effects may be preferable for + highlighting the region and matched search string. + +underline + The characters in the given context are shown underlined. Some + terminals show the foreground in a different colour instead; in + this case whitespace will not be highlighted. + + +The characters described above as `special' are as follows. The +formatting described here is used irrespective of whether the characters +are highlighted: + + +ASCII control characters + Control characters in the ASCII range are shown as `^' followed by + the base character. + +Unprintable multibyte characters + This item applies to control characters not in the ASCII range, + plus other characters as follows. If the MULTIBYTE option is in + effect, multibyte characters not in the ASCII character set that + are reported as having zero width are treated as combining + characters when the option COMBINING_CHARS is on. If the option + is off, or if a character appears where a combining character is + not valid, the character is treated as unprintable. + + Unprintable multibyte characters are shown as a hexadecimal number + between angle brackets. The number is the code point of the + character in the wide character set; this may or may not be + Unicode, depending on the operating system. + +Invalid multibyte characters + If the MULTIBYTE option is in effect, any sequence of one or more + bytes that does not form a valid character in the current character + set is treated as a series of bytes each shown as a special + character. This case can be distinguished from other unprintable + characters as the bytes are represented as two hexadecimal digits + between angle brackets, as distinct from the four or eight digits + that are used for unprintable characters that are nonetheless + valid in the current character set. + + Not all systems support this: for it to work, the system's + representation of wide characters must be code values from the + Universal Character Set, as defined by IS0 10646 (also known as + Unicode). + +Wrapped double-width characters + When a double-width character appears in the final column of a + line, it is instead shown on the next line. The empty space left + in the original position is highlighted as a special character. + + +If zle_highlight is not set or no value applies to a particular +context, the defaults applied are equivalent to + + + zle_highlight=(region:standout special:standout + suffix:bold isearch:underline paste:standout) + +i.e. both the region and special characters are shown in standout mode. + +Within widgets, arbitrary regions may be highlighted by setting the +special array parameter region_highlight; see *Note Zle Widgets::. + + + + +File: zsh.info, Node: Completion Widgets, Next: Completion System, Prev: Zsh Line Editor, Up: Top + +19 Completion Widgets +********************* + + + +19.1 Description +================ + +The shell's programmable completion mechanism can be manipulated in two +ways; here the low-level features supporting the newer, function-based +mechanism are defined. A complete set of shell functions based on these +features is described in the next chapter, *Note Completion System::, +and users with no interest in adding to that system (or, potentially, +writing their own -- see dictionary entry for `hubris') should skip the +current section. The older system based on the compctl builtin command +is described in *Note Completion Using compctl::. + +Completion widgets are defined by the -C option to the zle builtin +command provided by the zsh/zle module (see *Note The zsh/zle +Module::). For example, + + + zle -C complete expand-or-complete completer + +defines a widget named `complete'. The second argument is the name of +any of the builtin widgets that handle completions: complete-word, +expand-or-complete, expand-or-complete-prefix, menu-complete, +menu-expand-or-complete, reverse-menu-complete, list-choices, or +delete-char-or-list. Note that this will still work even if the widget +in question has been re-bound. + +When this newly defined widget is bound to a key using the bindkey +builtin command defined in the zsh/zle module (*Note Zsh Line +Editor::), typing that key will call the shell function `completer'. +This function is responsible for generating the possible matches using +the builtins described below. As with other ZLE widgets, the function +is called with its standard input closed. + +Once the function returns, the completion code takes over control again +and treats the matches in the same manner as the specified builtin +widget, in this case expand-or-complete. + + + +* Menu: + +* Completion Special Parameters:: +* Completion Builtin Commands:: +* Completion Condition Codes:: +* Completion Matching Control:: +* Completion Widget Example:: + + + +File: zsh.info, Node: Completion Special Parameters, Next: Completion Builtin Commands, Up: Completion Widgets + +19.2 Completion Special Parameters +================================== + +The parameters ZLE_REMOVE_SUFFIX_CHARS and ZLE_SPACE_SUFFIX_CHARS are +used by the completion mechanism, but are not special. See *Note +Parameters Used By The Shell::. + +Inside completion widgets, and any functions called from them, some +parameters have special meaning; outside these functions they are not +special to the shell in any way. These parameters are used to pass +information between the completion code and the completion widget. Some +of the builtin commands and the condition codes use or change the +current values of these parameters. Any existing values will be hidden +during execution of completion widgets; except for compstate, the +parameters are reset on each function exit (including nested function +calls from within the completion widget) to the values they had when +the function was entered. + + +CURRENT + This is the number of the current word, i.e. the word the cursor is + currently on in the words array. Note that this value is only + correct if the ksharrays option is not set. + +IPREFIX + Initially this will be set to the empty string. This parameter + functions like PREFIX; it contains a string which precedes the one + in PREFIX and is not considered part of the list of matches. + Typically, a string is transferred from the beginning of PREFIX to + the end of IPREFIX, for example: + + + IPREFIX=${PREFIX%%\=*}= + PREFIX=${PREFIX#*=} + + causes the part of the prefix up to and including the first equal + sign not to be treated as part of a matched string. This can be + done automatically by the compset builtin, see below. + +ISUFFIX + As IPREFIX, but for a suffix that should not be considered part of + the matches; note that the ISUFFIX string follows the SUFFIX + string. + +PREFIX + Initially this will be set to the part of the current word from the + beginning of the word up to the position of the cursor; it may be + altered to give a common prefix for all matches. + +QIPREFIX + This parameter is read-only and contains the quoted string up to + the word being completed. E.g. when completing `"foo', this + parameter contains the double quote. If the -q option of compset + is used (see below), and the original string was `"foo bar' with + the cursor on the `bar', this parameter contains `"foo '. + +QISUFFIX + Like QIPREFIX, but containing the suffix. + +SUFFIX + Initially this will be set to the part of the current word from the + cursor position to the end; it may be altered to give a common + suffix for all matches. It is most useful when the option + COMPLETE_IN_WORD is set, as otherwise the whole word on the + command line is treated as a prefix. + +compstate + This is an associative array with various keys and values that the + completion code uses to exchange information with the completion + widget. The keys are: + + + all_quotes + The -q option of the compset builtin command (see below) + allows a quoted string to be broken into separate words; if + the cursor is on one of those words, that word will be + completed, possibly invoking `compset -q' recursively. With + this key it is possible to test the types of quoted strings + which are currently broken into parts in this fashion. Its + value contains one character for each quoting level. The + characters are a single quote or a double quote for strings + quoted with these characters, a dollars sign for strings + quoted with $'...' and a backslash for strings not starting + with a quote character. The first character in the value + always corresponds to the innermost quoting level. + + context + This will be set by the completion code to the overall context + in which completion is attempted. Possible values are: + + + array_value + when completing inside the value of an array parameter + assignment; in this case the words array contains the + words inside the parentheses. + + brace_parameter + when completing the name of a parameter in a parameter + expansion beginning with ${. This context will also be + set when completing parameter flags following ${(; the + full command line argument is presented and the handler + must test the value to be completed to ascertain that + this is the case. + + assign_parameter + when completing the name of a parameter in a parameter + assignment. + + command + when completing for a normal command (either in command + position or for an argument of the command). + + condition + when completing inside a `[[...]]' conditional + expression; in this case the words array contains only + the words inside the conditional expression. + + math + when completing in a mathematical environment such as a + `((...))' construct. + + parameter + when completing the name of a parameter in a parameter + expansion beginning with $ but not ${. + + redirect + when completing after a redirection operator. + + subscript + when completing inside a parameter subscript. + + value + when completing the value of a parameter assignment. + + + exact + Controls the behaviour when the REC_EXACT option is set. It + will be set to accept if an exact match would be accepted, + and will be unset otherwise. + + If it was set when at least one match equal to the string on + the line was generated, the match is accepted. + + exact_string + The string of an exact match if one was found, otherwise + unset. + + ignored + The number of words that were ignored because they matched + one of the patterns given with the -F option to the compadd + builtin command. + + insert + This controls the manner in which a match is inserted into + the command line. On entry to the widget function, if it is + unset the command line is not to be changed; if set to + unambiguous, any prefix common to all matches is to be + inserted; if set to automenu-unambiguous, the common prefix + is to be inserted and the next invocation of the completion + code may start menu completion (due to the AUTO_MENU option + being set); if set to menu or automenu menu completion will + be started for the matches currently generated (in the latter + case this will happen because the AUTO_MENU is set). The + value may also contain the string `tab' when the completion + code would normally not really do completion, but only insert + the TAB character. + + On exit it may be set to any of the values above (where + setting it to the empty string is the same as unsetting it), + or to a number, in which case the match whose number is given + will be inserted into the command line. Negative numbers + count backward from the last match (with `-1' selecting the + last match) and out-of-range values are wrapped around, so + that a value of zero selects the last match and a value one + more than the maximum selects the first. Unless the value of + this key ends in a space, the match is inserted as in a menu + completion, i.e. without automatically appending a space. + + Both menu and automenu may also specify the number of the + match to insert, given after a colon. For example, `menu:2' + says to start menu completion, beginning with the second + match. + + Note that a value containing the substring `tab' makes the + matches generated be ignored and only the TAB be inserted. + + Finally, it may also be set to all, which makes all matches + generated be inserted into the line. + + insert_positions + When the completion system inserts an unambiguous string into + the line, there may be multiple places where characters are + missing or where the character inserted differs from at least + one match. The value of this key contains a colon separated + list of all these positions, as indexes into the command line. + + last_prompt + If this is set to a non-empty string for every match added, + the completion code will move the cursor back to the previous + prompt after the list of completions has been displayed. + Initially this is set or unset according to the + ALWAYS_LAST_PROMPT option. + + list + This controls whether or how the list of matches will be + displayed. If it is unset or empty they will never be + listed; if its value begins with list, they will always be + listed; if it begins with autolist or ambiguous, they will be + listed when the AUTO_LIST or LIST_AMBIGUOUS options + respectively would normally cause them to be. + + If the substring force appears in the value, this makes the + list be shown even if there is only one match. Normally, the + list would be shown only if there are at least two matches. + + The value contains the substring packed if the LIST_PACKED + option is set. If this substring is given for all matches + added to a group, this group will show the LIST_PACKED + behavior. The same is done for the LIST_ROWS_FIRST option + with the substring rows. + + Finally, if the value contains the string explanations, only + the explanation strings, if any, will be listed and if it + contains messages, only the messages (added with the -x + option of compadd) will be listed. If it contains both + explanations and messages both kinds of explanation strings + will be listed. It will be set appropriately on entry to a + completion widget and may be changed there. + + list_lines + This gives the number of lines that are needed to display the + full list of completions. Note that to calculate the total + number of lines to display you need to add the number of + lines needed for the command line to this value, this is + available as the value of the BUFFERLINES special parameter. + + list_max + Initially this is set to the value of the LISTMAX parameter. + It may be set to any other value; when the widget exits this + value will be used in the same way as the value of LISTMAX. + + nmatches + The number of matches generated and accepted by the + completion code so far. + + old_insert + On entry to the widget this will be set to the number of the + match of an old list of completions that is currently + inserted into the command line. If no match has been + inserted, this is unset. + + As with old_list, the value of this key will only be used if + it is the string keep. If it was set to this value by the + widget and there was an old match inserted into the command + line, this match will be kept and if the value of the insert + key specifies that another match should be inserted, this + will be inserted after the old one. + + old_list + This is set to yes if there is still a valid list of + completions from a previous completion at the time the widget + is invoked. This will usually be the case if and only if the + previous editing operation was a completion widget or one of + the builtin completion functions. If there is a valid list + and it is also currently shown on the screen, the value of + this key is shown. + + After the widget has exited the value of this key is only + used if it was set to keep. In this case the completion code + will continue to use this old list. If the widget generated + new matches, they will not be used. + + parameter + The name of the parameter when completing in a subscript or + in the value of a parameter assignment. + + pattern_insert + Normally this is set to menu, which specifies that menu + completion will be used whenever a set of matches was + generated using pattern matching. If it is set to any other + non-empty string by the user and menu completion is not + selected by other option settings, the code will instead + insert any common prefix for the generated matches as with + normal completion. + + pattern_match + Locally controls the behaviour given by the GLOB_COMPLETE + option. Initially it is set to `*' if and only if the option + is set. The completion widget may set it to this value, to + an empty string (which has the same effect as unsetting it), + or to any other non-empty string. If it is non-empty, + unquoted metacharacters on the command line will be treated + as patterns; if it is `*', then additionally a wildcard `*' + is assumed at the cursor position; if it is empty or unset, + metacharacters will be treated literally. + + Note that the matcher specifications given to the compadd + builtin command are not used if this is set to a non-empty + string. + + quote + When completing inside quotes, this contains the quotation + character (i.e. either a single quote, a double quote, or a + backtick). Otherwise it is unset. + + quoting + When completing inside single quotes, this is set to the + string single; inside double quotes, the string double; + inside backticks, the string backtick. Otherwise it is unset. + + redirect + The redirection operator when completing in a redirection + position, i.e. one of <, >, etc. + + restore + This is set to auto before a function is entered, which + forces the special parameters mentioned above (words, + CURRENT, PREFIX, IPREFIX, SUFFIX, and ISUFFIX) to be restored + to their previous values when the function exits. If a + function unsets it or sets it to any other string, they will + not be restored. + + to_end + Specifies the occasions on which the cursor is moved to the + end of a string when a match is inserted. On entry to a + widget function, it may be single if this will happen when a + single unambiguous match was inserted or match if it will + happen any time a match is inserted (for example, by menu + completion; this is likely to be the effect of the + ALWAYS_TO_END option). + + On exit, it may be set to single as above. It may also be + set to always, or to the empty string or unset; in those + cases the cursor will be moved to the end of the string + always or never respectively. Any other string is treated as + match. + + unambiguous + This key is read-only and will always be set to the common + (unambiguous) prefix the completion code has generated for + all matches added so far. + + unambiguous_cursor + This gives the position the cursor would be placed at if the + common prefix in the unambiguous key were inserted, relative + to the value of that key. The cursor would be placed before + the character whose index is given by this key. + + unambiguous_positions + This contains all positions where characters in the + unambiguous string are missing or where the character + inserted differs from at least one of the matches. The + positions are given as indexes into the string given by the + value of the unambiguous key. + + vared + If completion is called while editing a line using the vared + builtin, the value of this key is set to the name of the + parameter given as an argument to vared. This key is only + set while a vared command is active. + + +words + This array contains the words present on the command line + currently being edited. + + + + +File: zsh.info, Node: Completion Builtin Commands, Next: Completion Condition Codes, Prev: Completion Special Parameters, Up: Completion Widgets + +19.3 Completion Builtin Commands +================================ + + +compadd [ -akqQfenUl12C ] [ -F ARRAY ] + [-P PREFIX ] [ -S SUFFIX ] + [-p HIDDEN-PREFIX ] [ -s HIDDEN-SUFFIX ] + [-i IGNORED-PREFIX ] [ -I IGNORED-SUFFIX ] + [-W FILE-PREFIX ] [ -d ARRAY ] + [-J GROUP-NAME ] [ -X EXPLANATION ] [ -x MESSAGE ] + [-V GROUP-NAME ] [ -o [ ORDER ] ] + [-r REMOVE-CHARS ] [ -R REMOVE-FUNC ] + [-D ARRAY ] [ -O ARRAY ] [ -A ARRAY ] + [-E NUMBER ] + [-M MATCH-SPEC ] [ -- ] [ WORDS ... ] + This builtin command can be used to add matches directly and + control all the information the completion code stores with each + possible match. The return status is zero if at least one match + was added and non-zero if no matches were added. + + The completion code breaks the string to complete into seven + fields in the order: + + + + <IPRE><APRE><HPRE><WORD><HSUF><ASUF><ISUF> + + The first field is an ignored prefix taken from the command line, + the contents of the IPREFIX parameter plus the string given with + the -i option. With the -U option, only the string from the -i + option is used. The field <APRE> is an optional prefix string + given with the -P option. The <HPRE> field is a string that is + considered part of the match but that should not be shown when + listing completions, given with the -p option; for example, + functions that do filename generation might specify a common path + prefix this way. <WORD> is the part of the match that should + appear in the list of completions, i.e. one of the WORDS given at + the end of the compadd command line. The suffixes <HSUF>, <ASUF> + and <ISUF> correspond to the prefixes <HPRE>, <APRE> and <IPRE> + and are given by the options -s, -S and -I, respectively. + + The supported flags are: + + + -P PREFIX + This gives a string to be inserted before the given WORDS. + The string given is not considered as part of the match and + any shell metacharacters in it will not be quoted when the + string is inserted. + + -S SUFFIX + Like -P, but gives a string to be inserted after the match. + + -p HIDDEN-PREFIX + This gives a string that should be inserted into the command + line before the match but that should not appear in the list + of matches. Unless the -U option is given, this string must + be matched as part of the string on the command line. + + -s HIDDEN-SUFFIX + Like `-p', but gives a string to insert after the match. + + -i IGNORED-PREFIX + This gives a string to insert into the command line just + before any string given with the `-P' option. Without `-P' + the string is inserted before the string given with `-p' or + directly before the match. + + -I IGNORED-SUFFIX + Like -i, but gives an ignored suffix. + + -a + With this flag the WORDS are taken as names of arrays and the + possible matches are their values. If only some elements of + the arrays are needed, the WORDS may also contain subscripts, + as in `foo[2,-1]'. + + -k + With this flag the WORDS are taken as names of associative + arrays and the possible matches are their keys. As for -a, + the WORDS may also contain subscripts, as in `foo[(R)*bar*]'. + + -d ARRAY + This adds per-match display strings. The ARRAY should contain + one element per WORD given. The completion code will then + display the first element instead of the first WORD, and so + on. The ARRAY may be given as the name of an array parameter + or directly as a space-separated list of words in parentheses. + + If there are fewer display strings than WORDS, the leftover + WORDS will be displayed unchanged and if there are more + display strings than WORDS, the leftover display strings will + be silently ignored. + + -l + This option only has an effect if used together with the -d + option. If it is given, the display strings are listed one + per line, not arrayed in columns. + + -o [ ORDER ] + This controls the order in which matches are sorted. ORDER is + a comma-separated list comprising the following possible + values. These values can be abbreviated to their initial two + or three characters. Note that the order forms part of the + group name space so matches with different orderings will not + be in the same group. + + + match + If given, the order of the output is determined by the + match strings; otherwise it is determined by the display + strings (i.e. the strings given by the -d option). This + is the default if `-o' is specified but the ORDER + argument is omitted. + + nosort + This specifies that the matches are pre-sorted and their + order should be preserved. This value only makes sense + alone and cannot be combined with any others. + + numeric + If the matches include numbers, sort them numerically + rather than lexicographically. + + reverse + Arrange the matches backwards by reversing the sort + ordering. + + + -J GROUP-NAME + Gives the name of the group of matches the words should be + stored in. + + -V GROUP-NAME + Like -J but naming an unsorted group. This option is + identical to the combination of -J and -o nosort. + + -1 + If given together with the -V option, makes only consecutive + duplicates in the group be removed. If combined with the -J + option, this has no visible effect. Note that groups with and + without this flag are in different name spaces. + + -2 + If given together with the -J or -V option, makes all + duplicates be kept. Again, groups with and without this flag + are in different name spaces. + + -X EXPLANATION + The EXPLANATION string will be printed with the list of + matches, above the group currently selected. + + Within the EXPLANATION, the following sequences may be used to + specify output attributes (see *Note Prompt Expansion::): + `%B', `%S', `%U', `%F', `%K' and their lower case + counterparts, as well as `%{...%}'. `%F', `%K' and `%{...%}' + take arguments in the same form as prompt expansion. (Note + that the sequence `%G' is not available; an argument to `%{' + should be used instead.) The sequence `%%' produces a + literal `%'. + + These sequences are most often employed by users when + customising the format style (see *Note Completion System::), + but they must also be taken into account when writing + completion functions, as passing descriptions with unescaped + `%' characters to utility functions such as _arguments and + _message may produce unexpected results. If arbitrary text is + to be passed in a description, it can be escaped using e.g. + ${my_str//\%/%%}. + + -x MESSAGE + Like -X, but the MESSAGE will be printed even if there are no + matches in the group. + + -q + The suffix given with -S will be automatically removed if the + next character typed is a blank or does not insert anything, + or if the suffix consists of only one character and the next + character typed is the same character. + + -r REMOVE-CHARS + This is a more versatile form of the -q option. The suffix + given with -S or the slash automatically added after + completing directories will be automatically removed if the + next character typed inserts one of the characters given in + the REMOVE-CHARS. This string is parsed as a characters + class and understands the backslash sequences used by the + print command. For example, `-r "a-z\t"' removes the suffix + if the next character typed inserts a lower case character or + a TAB, and `-r "^0-9"' removes the suffix if the next + character typed inserts anything but a digit. One extra + backslash sequence is understood in this string: `\-' stands + for all characters that insert nothing. Thus `-S "=" -q' is + the same as `-S "=" -r "= \t\n\-"'. + + This option may also be used without the -S option; then any + automatically added space will be removed when one of the + characters in the list is typed. + + -R REMOVE-FUNC + This is another form of the -r option. When a suffix has been + inserted and the completion accepted, the function + REMOVE-FUNC will be called after the next character typed. + It is passed the length of the suffix as an argument and can + use the special parameters available in ordinary + (non-completion) zle widgets (see *Note Zsh Line Editor::) to + analyse and modify the command line. + + -f + If this flag is given, all of the matches built from WORDS are + marked as being the names of files. They are not required to + be actual filenames, but if they are, and the option + LIST_TYPES is set, the characters describing the types of the + files in the completion lists will be shown. This also forces + a slash to be added when the name of a directory is completed. + + -e + This flag can be used to tell the completion code that the + matches added are parameter names for a parameter expansion. + This will make the AUTO_PARAM_SLASH and AUTO_PARAM_KEYS + options be used for the matches. + + -W FILE-PREFIX + This string is a pathname that will be prepended to each of + the matches formed by the given WORDS together with any + prefix specified by the -p option to form a complete filename + for testing. Hence it is only useful if combined with the -f + flag, as the tests will not otherwise be performed. + + -F ARRAY + Specifies an array containing patterns. Words matching one of + these patterns are ignored, i.e. not considered to be + possible matches. + + The ARRAY may be the name of an array parameter or a list of + literal patterns enclosed in parentheses and quoted, as in + `-F "(*?.o *?.h)"'. If the name of an array is given, the + elements of the array are taken as the patterns. + + -Q + This flag instructs the completion code not to quote any + metacharacters in the words when inserting them into the + command line. + + -M MATCH-SPEC + This gives local match specifications as described below in + *Note Completion Matching Control::. This option may be given + more than once. In this case all MATCH-SPECs given are + concatenated with spaces between them to form the + specification string to use. Note that they will only be + used if the -U option is not given. + + -n + Specifies that the words added are to be used as possible + matches, but are not to appear in the completion listing. + + -U + If this flag is given, all words given will be accepted and + no matching will be done by the completion code. Normally + this is used in functions that do the matching themselves. + + -O ARRAY + If this option is given, the WORDS are _not_ added to the set + of possible completions. Instead, matching is done as usual + and all of the WORDS given as arguments that match the string + on the command line will be stored in the array parameter + whose name is given as ARRAY. + + -A ARRAY + As the -O option, except that instead of those of the WORDS + which match being stored in ARRAY, the strings generated + internally by the completion code are stored. For example, + with a matching specification of `-M "L:|no="', the string + `nof' on the command line and the string `foo' as one of the + WORDS, this option stores the string `nofoo' in the array, + whereas the -O option stores the `foo' originally given. + + -D ARRAY + As with -O, the WORDS are not added to the set of possible + completions. Instead, the completion code tests whether each + WORD in turn matches what is on the line. If the Nth WORD + does not match, the Nth element of the ARRAY is removed. + Elements for which the corresponding WORD is matched are + retained. + + -C + This option adds a special match which expands to all other + matches when inserted into the line, even those that are + added after this option is used. Together with the -d option + it is possible to specify a string that should be displayed + in the list for this special match. If no string is given, + it will be shown as a string containing the strings that + would be inserted for the other matches, truncated to the + width of the screen. + + -E NUMBER + This option adds NUMBER empty matches after the WORDS have + been added. An empty match takes up space in completion + listings but will never be inserted in the line and can't be + selected with menu completion or menu selection. This makes + empty matches only useful to format completion lists and to + make explanatory string be shown in completion lists (since + empty matches can be given display strings with the -d + option). And because all but one empty string would + otherwise be removed, this option implies the -V and -2 + options (even if an explicit -J option is given). This can be + important to note as it affects the name space into which + matches are added. + + - + -- + This flag ends the list of flags and options. All arguments + after it will be taken as the words to use as matches even if + they begin with hyphens. + + + Except for the -M flag, if any of these flags is given more than + once, the first one (and its argument) will be used. + +compset -p NUMBER +compset -P [ NUMBER ] PATTERN +compset -s NUMBER +compset -S [ NUMBER ] PATTERN +compset -n BEGIN [ END ] +compset -N BEG-PAT [ END-PAT ] +compset -q + This command simplifies modification of the special parameters, + while its return status allows tests on them to be carried out. + + The options are: + + + -p NUMBER + If the value of the PREFIX parameter is at least NUMBER + characters long, the first NUMBER characters are removed from + it and appended to the contents of the IPREFIX parameter. + + -P [ NUMBER ] PATTERN + If the value of the PREFIX parameter begins with anything that + matches the PATTERN, the matched portion is removed from + PREFIX and appended to IPREFIX. + + Without the optional NUMBER, the longest match is taken, but + if NUMBER is given, anything up to the NUMBERth match is + moved. If the NUMBER is negative, the NUMBERth longest match + is moved. For example, if PREFIX contains the string `a=b=c', + then compset -P '*\=' will move the string `a=b=' into the + IPREFIX parameter, but compset -P 1 '*\=' will move only the + string `a='. + + -s NUMBER + As -p, but transfer the last NUMBER characters from the value + of SUFFIX to the front of the value of ISUFFIX. + + -S [ NUMBER ] PATTERN + As -P, but match the last portion of SUFFIX and transfer the + matched portion to the front of the value of ISUFFIX. + + -n BEGIN [ END ] + If the current word position as specified by the parameter + CURRENT is greater than or equal to BEGIN, anything up to the + BEGINth word is removed from the words array and the value of + the parameter CURRENT is decremented by BEGIN. + + If the optional END is given, the modification is done only if + the current word position is also less than or equal to END. + In this case, the words from position END onwards are also + removed from the words array. + + Both BEGIN and END may be negative to count backwards from + the last element of the words array. + + -N BEG-PAT [ END-PAT ] + If one of the elements of the words array before the one at + the index given by the value of the parameter CURRENT matches + the pattern BEG-PAT, all elements up to and including the + matching one are removed from the words array and the value + of CURRENT is changed to point to the same word in the + changed array. + + If the optional pattern END-PAT is also given, and there is an + element in the words array matching this pattern, the + parameters are modified only if the index of this word is + higher than the one given by the CURRENT parameter (so that + the matching word has to be after the cursor). In this case, + the words starting with the one matching end-pat are also + removed from the words array. If words contains no word + matching END-PAT, the testing and modification is performed + as if it were not given. + + -q + The word currently being completed is split on spaces into + separate words, respecting the usual shell quoting + conventions. The resulting words are stored in the words + array, and CURRENT, PREFIX, SUFFIX, QIPREFIX, and QISUFFIX + are modified to reflect the word part that is completed. + + + In all the above cases the return status is zero if the test + succeeded and the parameters were modified and non-zero otherwise. + This allows one to use this builtin in tests such as: + + + if compset -P '*\='; then ... + + This forces anything up to and including the last equal sign to be + ignored by the completion code. + +compcall [ -TD ] + This allows the use of completions defined with the compctl builtin + from within completion widgets. The list of matches will be + generated as if one of the non-widget completion functions + (complete-word, etc.) had been called, except that only compctls + given for specific commands are used. To force the code to try + completions defined with the -T option of compctl and/or the + default completion (whether defined by compctl -D or the builtin + default) in the appropriate places, the -T and/or -D flags can be + passed to compcall. + + The return status can be used to test if a matching compctl + definition was found. It is non-zero if a compctl was found and + zero otherwise. + + Note that this builtin is defined by the zsh/compctl module. + + + + +File: zsh.info, Node: Completion Condition Codes, Next: Completion Matching Control, Prev: Completion Builtin Commands, Up: Completion Widgets + +19.4 Completion Condition Codes +=============================== + + + +The following additional condition codes for use within the [[ ... ]] +construct are available in completion widgets. These work on the +special parameters. All of these tests can also be performed by the +compset builtin, but in the case of the condition codes the contents of +the special parameters are not modified. + + +-prefix [ NUMBER ] PATTERN + true if the test for the -P option of compset would succeed. + +-suffix [ NUMBER ] PATTERN + true if the test for the -S option of compset would succeed. + +-after BEG-PAT + true if the test of the -N option with only the BEG-PAT given + would succeed. + +-between BEG-PAT END-PAT + true if the test for the -N option with both patterns would + succeed. + + + + +File: zsh.info, Node: Completion Matching Control, Next: Completion Widget Example, Prev: Completion Condition Codes, Up: Completion Widgets + +19.5 Completion Matching Control +================================ + +It is possible by use of the -M option of the compadd builtin command +to specify how the characters in the string to be completed (referred +to here as the command line) map onto the characters in the list of +matches produced by the completion code (referred to here as the trial +completions). Note that this is not used if the command line contains a +glob pattern and the GLOB_COMPLETE option is set or the pattern_match +of the compstate special association is set to a non-empty string. + +The MATCH-SPEC given as the argument to the -M option (see *Note +Completion Builtin Commands::) consists of one or more matching +descriptions separated by whitespace. Each description consists of a +letter followed by a colon and then the patterns describing which +character sequences on the line match which character sequences in the +trial completion. Any sequence of characters not handled in this +fashion must match exactly, as usual. + +The forms of MATCH-SPEC understood are as follows. In each case, the +form with an upper case initial character retains the string already +typed on the command line as the final result of completion, while with +a lower case initial character the string on the command line is changed +into the corresponding part of the trial completion. + + +m:LPAT=TPAT +M:LPAT=TPAT + Here, LPAT is a pattern that matches on the command line, + corresponding to TPAT which matches in the trial completion. + +l:LANCHOR|LPAT=TPAT +L:LANCHOR|LPAT=TPAT +l:LANCHOR||RANCHOR=TPAT +L:LANCHOR||RANCHOR=TPAT +b:LPAT=TPAT +B:LPAT=TPAT + These letters are for patterns that are anchored by another + pattern on the left side. Matching for LPAT and TPAT is as for m + and M, but the pattern LPAT matched on the command line must be + preceded by the pattern LANCHOR. The LANCHOR can be blank to + anchor the match to the start of the command line string; + otherwise the anchor can occur anywhere, but must match in both + the command line and trial completion strings. + + If no LPAT is given but a RANCHOR is, this matches the gap between + substrings matched by LANCHOR and RANCHOR. Unlike LANCHOR, the + RANCHOR only needs to match the trial completion string. + + The b and B forms are similar to l and L with an empty anchor, but + need to match only the beginning of the word on the command line + or trial completion, respectively. + +r:LPAT|RANCHOR=TPAT +R:LPAT|RANCHOR=TPAT +r:LANCHOR||RANCHOR=TPAT +R:LANCHOR||RANCHOR=TPAT +e:LPAT=TPAT +E:LPAT=TPAT + As l, L, b and B, with the difference that the command line and + trial completion patterns are anchored on the right side. Here an + empty RANCHOR and the e and E forms force the match to the end of + the command line or trial completion string. + +x: + This form is used to mark the end of matching specifications: + subsequent specifications are ignored. In a single standalone list + of specifications this has no use but where matching specifications + are accumulated, such as from nested function calls, it can allow + one function to override another. + + +Each LPAT, TPAT or ANCHOR is either an empty string or consists of a +sequence of literal characters (which may be quoted with a backslash), +question marks, character classes, and correspondence classes; ordinary +shell patterns are not used. Literal characters match only themselves, +question marks match any character, and character classes are formed as +for globbing and match any character in the given set. + +Correspondence classes are defined like character classes, but with two +differences: they are delimited by a pair of braces, and negated classes +are not allowed, so the characters ! and ^ have no special meaning +directly after the opening brace. They indicate that a range of +characters on the line match a range of characters in the trial +completion, but (unlike ordinary character classes) paired according to +the corresponding position in the sequence. For example, to make any +ASCII lower case letter on the line match the corresponding upper case +letter in the trial completion, you can use `m:{a-z}={A-Z}' (however, +see below for the recommended form for this). More than one pair of +classes can occur, in which case the first class before the = +corresponds to the first after it, and so on. If one side has more +such classes than the other side, the superfluous classes behave like +normal character classes. In anchor patterns correspondence classes +also behave like normal character classes. + +The standard `[:NAME:]' forms described for standard shell patterns (see +*Note Filename Generation::) may appear in correspondence classes as +well as normal character classes. The only special behaviour in +correspondence classes is if the form on the left and the form on the +right are each one of [:upper:], [:lower:]. In these cases the +character in the word and the character on the line must be the same up +to a difference in case. Hence to make any lower case character on the +line match the corresponding upper case character in the trial +completion you can use `m:{[:lower:]}={[:upper:]}'. Although the +matching system does not yet handle multibyte characters, this is likely +to be a future extension, at which point this syntax will handle +arbitrary alphabets; hence this form, rather than the use of explicit +ranges, is the recommended form. In other cases `[:NAME:]' forms are +allowed. If the two forms on the left and right are the same, the +characters must match exactly. In remaining cases, the corresponding +tests are applied to both characters, but they are not otherwise +constrained; any matching character in one set goes with any matching +character in the other set: this is equivalent to the behaviour of +ordinary character classes. + +The pattern TPAT may also be one or two stars, `*' or `**'. This means +that the pattern on the command line can match any number of characters +in the trial completion. In this case the pattern must be anchored (on +either side); in the case of a single star, the ANCHOR then determines +how much of the trial completion is to be included -- only the +characters up to the next appearance of the anchor will be matched. +With two stars, substrings matched by the anchor can be matched, too. + +Examples: + +The keys of the options association defined by the parameter module are +the option names in all-lower-case form, without underscores, and +without the optional no at the beginning even though the builtins +setopt and unsetopt understand option names with upper case letters, +underscores, and the optional no. The following alters the matching +rules so that the prefix no and any underscore are ignored when trying +to match the trial completions generated and upper case letters on the +line match the corresponding lower case letters in the words: + + + compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \ + ${(k)options} + +The first part says that the pattern `[nN][oO]' at the beginning (the +empty anchor before the pipe symbol) of the string on the line matches +the empty string in the list of words generated by completion, so it +will be ignored if present. The second part does the same for an +underscore anywhere in the command line string, and the third part uses +correspondence classes so that any upper case letter on the line +matches the corresponding lower case letter in the word. The use of the +upper case forms of the specification characters (L and M) guarantees +that what has already been typed on the command line (in particular the +prefix no) will not be deleted. + +Note that the use of L in the first part means that it matches only +when at the beginning of both the command line string and the trial +completion. I.e., the string `_NO_f' would not be completed to +`_NO_foo', nor would `NONO_f' be completed to `NONO_foo' because of the +leading underscore or the second `NO' on the line which makes the +pattern fail even though they are otherwise ignored. To fix this, one +would use `B:[nN][oO]=' instead of the first part. As described above, +this matches at the beginning of the trial completion, independent of +other characters or substrings at the beginning of the command line +word which are ignored by the same or other MATCH-SPECs. + +The second example makes completion case insensitive. This is just the +same as in the option example, except here we wish to retain the +characters in the list of completions: + + + compadd -M 'm:{[:lower:]}={[:upper:]}' ... + +This makes lower case letters match their upper case counterparts. To +make upper case letters match the lower case forms as well: + + + compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ... + +A nice example for the use of * patterns is partial word completion. +Sometimes you would like to make strings like `c.s.u' complete to +strings like `comp.source.unix', i.e. the word on the command line +consists of multiple parts, separated by a dot in this example, where +each part should be completed separately -- note, however, that the +case where each part of the word, i.e. `comp', `source' and `unix' in +this example, is to be completed from separate sets of matches is a +different problem to be solved by the implementation of the completion +widget. The example can be handled by: + + + compadd -M 'r:|.=* r:|=*' \ + - comp.sources.unix comp.sources.misc ... + +The first specification says that LPAT is the empty string, while +ANCHOR is a dot; TPAT is *, so this can match anything except for the +`.' from the anchor in the trial completion word. So in `c.s.u', the +matcher sees `c', followed by the empty string, followed by the anchor +`.', and likewise for the second dot, and replaces the empty strings +before the anchors, giving `c[omp].s[ources].u[nix]', where the last +part of the completion is just as normal. + +With the pattern shown above, the string `c.u' could not be completed +to `comp.sources.unix' because the single star means that no dot +(matched by the anchor) can be skipped. By using two stars as in +`r:|.=**', however, `c.u' could be completed to `comp.sources.unix'. +This also shows that in some cases, especially if the anchor is a real +pattern, like a character class, the form with two stars may result in +more matches than one would like. + +The second specification is needed to make this work when the cursor is +in the middle of the string on the command line and the option +COMPLETE_IN_WORD is set. In this case the completion code would +normally try to match trial completions that end with the string as +typed so far, i.e. it will only insert new characters at the cursor +position rather than at the end. However in our example we would like +the code to recognise matches which contain extra characters after the +string on the line (the `nix' in the example). Hence we say that the +empty string at the end of the string on the line matches any characters +at the end of the trial completion. + +More generally, the specification + + + compadd -M 'r:|[.,_-]=* r:|=*' ... + +allows one to complete words with abbreviations before any of the +characters in the square brackets. For example, to complete +veryverylongfile.c rather than veryverylongheader.h with the above in +effect, you can just type very.c before attempting completion. + +The specifications with both a left and a right anchor are useful to +complete partial words whose parts are not separated by some special +character. For example, in some places strings have to be completed +that are formed `LikeThis' (i.e. the separate parts are determined by a +leading upper case letter) or maybe one has to complete strings with +trailing numbers. Here one could use the simple form with only one +anchor as in: + + + compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234 + +But with this, the string `H' would neither complete to `FooHoo' nor to +`LikeTHIS' because in each case there is an upper case letter before +the `H' and that is matched by the anchor. Likewise, a `2' would not be +completed. In both cases this could be changed by using +`r:|[[:upper:]0-9]=**', but then `H' completes to both `LikeTHIS' and +`FooHoo' and a `2' matches the other strings because characters can be +inserted before every upper case letter and digit. To avoid this one +would use: + + + compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \ + LikeTHIS FooHoo foo123 bar234 + +By using these two anchors, a `H' matches only upper case `H's that are +immediately preceded by something matching the left anchor +`[^[:upper:]0-9]'. The effect is, of course, that `H' matches only the +string `FooHoo', a `2' matches only `bar234' and so on. + +When using the completion system (see *Note Completion System::), users +can define match specifications that are to be used for specific +contexts by using the matcher and matcher-list styles. The values for +the latter will be used everywhere. + + + + +File: zsh.info, Node: Completion Widget Example, Prev: Completion Matching Control, Up: Completion Widgets + +19.6 Completion Widget Example +============================== + + + +The first step is to define the widget: + + + zle -C complete complete-word complete-files + +Then the widget can be bound to a key using the bindkey builtin command: + + + bindkey '^X\t' complete + +After that the shell function complete-files will be invoked after +typing control-X and TAB. The function should then generate the +matches, e.g.: + + + complete-files () { compadd - * } + +This function will complete files in the current directory matching the +current word. + + +File: zsh.info, Node: Completion System, Next: Completion Using compctl, Prev: Completion Widgets, Up: Top + +20 Completion System +******************** + + + +20.1 Description +================ + +This describes the shell code for the `new' completion system, referred +to as compsys. It is written in shell functions based on the features +described in the previous chapter, *Note Completion Widgets::. + +The features are contextual, sensitive to the point at which completion +is started. Many completions are already provided. For this reason, a +user can perform a great many tasks without knowing any details beyond +how to initialize the system, which is described in *Note +Initialization::. + +The context that decides what completion is to be performed may be + * an argument or option position: these describe the position on the + command line at which completion is requested. For example `first + argument to rmdir, the word being completed names a directory'; + + * a special context, denoting an element in the shell's syntax. For + example `a word in command position' or `an array subscript'. + + +A full context specification contains other elements, as we shall +describe. + +Besides commands names and contexts, the system employs two more +concepts, _styles_ and _tags_. These provide ways for the user to +configure the system's behaviour. + +Tags play a dual role. They serve as a classification system for the +matches, typically indicating a class of object that the user may need +to distinguish. For example, when completing arguments of the ls +command the user may prefer to try files before directories, so both of +these are tags. They also appear as the rightmost element in a context +specification. + +Styles modify various operations of the completion system, such as +output formatting, but also what kinds of completers are used (and in +what order), or which tags are examined. Styles may accept arguments +and are manipulated using the zstyle command described in *Note The +zsh/zutil Module::. + +In summary, tags describe _what_ the completion objects are, and style +how they are to be completed. At various points of execution, the +completion system checks what styles and/or tags are defined for the +current context, and uses that to modify its behavior. The full +description of context handling, which determines how tags and other +elements of the context influence the behaviour of styles, is described +in *Note Completion System Configuration::. + +When a completion is requested, a dispatcher function is called; see +the description of _main_complete in the list of control functions +below. This dispatcher decides which function should be called to +produce the completions, and calls it. The result is passed to one or +more _completers_, functions that implement individual completion +strategies: simple completion, error correction, completion with error +correction, menu selection, etc. + +More generally, the shell functions contained in the completion system +are of two types: + * those beginning `comp' are to be called directly; there are only a + few of these; + + * those beginning `_' are called by the completion code. The shell + functions of this set, which implement completion behaviour and + may be bound to keystrokes, are referred to as `widgets'. These + proliferate as new completions are required. + + + +* Menu: + +* Initialization:: +* Completion System Configuration:: +* Control Functions:: +* Bindable Commands:: +* Completion Functions:: +* Completion Directories:: +* Completion System Variables:: + + + +File: zsh.info, Node: Initialization, Next: Completion System Configuration, Up: Completion System + +20.2 Initialization +=================== + + + +If the system was installed completely, it should be enough to call the +shell function compinit from your initialization file; see the next +section. However, the function compinstall can be run by a user to +configure various aspects of the completion system. + +Usually, compinstall will insert code into .zshrc, although if that is +not writable it will save it in another file and tell you that file's +location. Note that it is up to you to make sure that the lines added +to .zshrc are actually run; you may, for example, need to move them to +an earlier place in the file if .zshrc usually returns early. So long +as you keep them all together (including the comment lines at the start +and finish), you can rerun compinstall and it will correctly locate and +modify these lines. Note, however, that any code you add to this +section by hand is likely to be lost if you rerun compinstall, although +lines using the command `zstyle' should be gracefully handled. + +The new code will take effect next time you start the shell, or run +.zshrc by hand; there is also an option to make them take effect +immediately. However, if compinstall has removed definitions, you will +need to restart the shell to see the changes. + +To run compinstall you will need to make sure it is in a directory +mentioned in your fpath parameter, which should already be the case if +zsh was properly configured as long as your startup files do not remove +the appropriate directories from fpath. Then it must be autoloaded +(`autoload -U compinstall' is recommended). You can abort the +installation any time you are being prompted for information, and your +.zshrc will not be altered at all; changes only take place right at the +end, where you are specifically asked for confirmation. + + + +20.2.1 Use of compinit +---------------------- + + + +This section describes the use of compinit to initialize completion for +the current session when called directly; if you have run compinstall +it will be called automatically from your .zshrc. + +To initialize the system, the function compinit should be in a +directory mentioned in the fpath parameter, and should be autoloaded +(`autoload -U compinit' is recommended), and then run simply as +`compinit'. This will define a few utility functions, arrange for all +the necessary shell functions to be autoloaded, and will then re-define +all widgets that do completion to use the new system. If you use the +menu-select widget, which is part of the zsh/complist module, you +should make sure that that module is loaded before the call to compinit +so that that widget is also re-defined. If completion styles (see +below) are set up to perform expansion as well as completion by +default, and the TAB key is bound to expand-or-complete, compinit will +rebind it to complete-word; this is necessary to use the correct form +of expansion. + +Should you need to use the original completion commands, you can still +bind keys to the old widgets by putting a `.' in front of the widget +name, e.g. `.expand-or-complete'. + +To speed up the running of compinit, it can be made to produce a dumped +configuration that will be read in on future invocations; this is the +default, but can be turned off by calling compinit with the option -D. +The dumped file is .zcompdump in the same directory as the startup +files (i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name +can be given by `compinit -d DUMPFILE'. The next invocation of +compinit will read the dumped file instead of performing a full +initialization. + +If the number of completion files changes, compinit will recognise this +and produce a new dump file. However, if the name of a function or the +arguments in the first line of a #compdef function (as described below) +change, it is easiest to delete the dump file by hand so that compinit +will re-create it the next time it is run. The check performed to see +if there are new functions can be omitted by giving the option -C. In +this case the dump file will only be created if there isn't one already. + +The dumping is actually done by another function, compdump, but you +will only need to run this yourself if you change the configuration +(e.g. using compdef) and then want to dump the new one. The name of +the old dumped file will be remembered for this purpose. + +If the parameter _compdir is set, compinit uses it as a directory where +completion functions can be found; this is only necessary if they are +not already in the function search path. + +For security reasons compinit also checks if the completion system +would use files not owned by root or by the current user, or files in +directories that are world- or group-writable or that are not owned by +root or by the current user. If such files or directories are found, +compinit will ask if the completion system should really be used. To +avoid these tests and make all files found be used without asking, use +the option -u, and to make compinit silently ignore all insecure files +and directories use the option -i. This security check is skipped +entirely when the -C option is given. + +The security check can be retried at any time by running the function +compaudit. This is the same check used by compinit, but when it is +executed directly any changes to fpath are made local to the function +so they do not persist. The directories to be checked may be passed as +arguments; if none are given, compaudit uses fpath and _compdir to find +completion system directories, adding missing ones to fpath as +necessary. To force a check of exactly the directories currently named +in fpath, set _compdir to an empty string before calling compaudit or +compinit. + +The function bashcompinit provides compatibility with bash's +programmable completion system. When run it will define the functions, +compgen and complete which correspond to the bash builtins with the +same names. It will then be possible to use completion specifications +and functions written for bash. + + + +20.2.2 Autoloaded files +----------------------- + + + +The convention for autoloaded functions used in completion is that they +start with an underscore; as already mentioned, the fpath/FPATH +parameter must contain the directory in which they are stored. If zsh +was properly installed on your system, then fpath/FPATH automatically +contains the required directories for the standard functions. + +For incomplete installations, if compinit does not find enough files +beginning with an underscore (fewer than twenty) in the search path, it +will try to find more by adding the directory _compdir to the search +path. If that directory has a subdirectory named Base, all +subdirectories will be added to the path. Furthermore, if the +subdirectory Base has a subdirectory named Core, compinit will add all +subdirectories of the subdirectories to the path: this allows the +functions to be in the same format as in the zsh source distribution. + +When compinit is run, it searches all such files accessible via +fpath/FPATH and reads the first line of each of them. This line should +contain one of the tags described below. Files whose first line does +not start with one of these tags are not considered to be part of the +completion system and will not be treated specially. + +The tags are: + + +#compdef NAME ... [ -{p|P} PATTERN ... [ -N NAME ... ] ] + The file will be made autoloadable and the function defined in it + will be called when completing NAMEs, each of which is either the + name of a command whose arguments are to be completed or one of a + number of special contexts in the form -CONTEXT- described below. + + Each NAME may also be of the form `CMD=SERVICE'. When completing + the command CMD, the function typically behaves as if the command + (or special context) SERVICE was being completed instead. This + provides a way of altering the behaviour of functions that can + perform many different completions. It is implemented by setting + the parameter $service when calling the function; the function may + choose to interpret this how it wishes, and simpler functions will + probably ignore it. + + If the #compdef line contains one of the options -p or -P, the + words following are taken to be patterns. The function will be + called when completion is attempted for a command or context that + matches one of the patterns. The options -p and -P are used to + specify patterns to be tried before or after other completions + respectively. Hence -P may be used to specify default actions. + + The option -N is used after a list following -p or -P; it + specifies that remaining words no longer define patterns. It is + possible to toggle between the three options as many times as + necessary. + +#compdef -k STYLE KEY-SEQUENCE ... + This option creates a widget behaving like the builtin widget + STYLE and binds it to the given KEY-SEQUENCEs, if any. The STYLE + must be one of the builtin widgets that perform completion, namely + complete-word, delete-char-or-list, expand-or-complete, + expand-or-complete-prefix, list-choices, menu-complete, + menu-expand-or-complete, or reverse-menu-complete. If the + zsh/complist module is loaded (see *Note The zsh/complist + Module::) the widget menu-select is also available. + + When one of the KEY-SEQUENCEs is typed, the function in the file + will be invoked to generate the matches. Note that a key will not + be re-bound if it already was (that is, was bound to something + other than undefined-key). The widget created has the same name + as the file and can be bound to any other keys using bindkey as + usual. + +#compdef -K WIDGET-NAME STYLE KEY-SEQUENCE [ NAME STYLE SEQ ... ] + This is similar to -k except that only one KEY-SEQUENCE argument + may be given for each WIDGET-NAME STYLE pair. However, the entire + set of three arguments may be repeated with a different set of + arguments. Note in particular that the WIDGET-NAME must be + distinct in each set. If it does not begin with `_' this will be + added. The WIDGET-NAME should not clash with the name of any + existing widget: names based on the name of the function are most + useful. For example, + + + #compdef -K _foo_complete complete-word "^X^C" \ + _foo_list list-choices "^X^D" + + (all on one line) defines a widget _foo_complete for completion, + bound to `^X^C', and a widget _foo_list for listing, bound to + `^X^D'. + +#autoload [ OPTIONS ] + Functions with the #autoload tag are marked for autoloading but + are not otherwise treated specially. Typically they are to be + called from within one of the completion functions. Any OPTIONS + supplied will be passed to the autoload builtin; a typical use is + +X to force the function to be loaded immediately. Note that the + -U and -z flags are always added implicitly. + + +The # is part of the tag name and no white space is allowed after it. +The #compdef tags use the compdef function described below; the main +difference is that the name of the function is supplied implicitly. + +The special contexts for which completion functions can be defined are: + + +-array-value- + The right hand side of an array-assignment (`NAME=(...)') + +-brace-parameter- + The name of a parameter expansion within braces (`${...}') + +-assign-parameter- + The name of a parameter in an assignment, i.e. on the left hand + side of an `=' + +-command- + A word in command position + +-condition- + A word inside a condition (`[[...]]') + +-default- + Any word for which no other completion is defined + +-equal- + A word beginning with an equals sign + +-first- + This is tried before any other completion function. The function + called may set the _compskip parameter to one of various values: + all: no further completion is attempted; a string containing the + substring patterns: no pattern completion functions will be + called; a string containing default: the function for the + `-default-' context will not be called, but functions defined for + commands will be. + +-math- + Inside mathematical contexts, such as `((...))' + +-parameter- + The name of a parameter expansion (`$...') + +-redirect- + The word after a redirection operator. + +-subscript- + The contents of a parameter subscript. + +-tilde- + After an initial tilde (`~'), but before the first slash in the + word. + +-value- + On the right hand side of an assignment. + + +Default implementations are supplied for each of these contexts. In +most cases the context -CONTEXT- is implemented by a corresponding +function _CONTEXT, for example the context `-tilde-' and the function +`_tilde'). + +The contexts -redirect- and -value- allow extra context-specific +information. (Internally, this is handled by the functions for each +context calling the function _dispatch.) The extra information is +added separated by commas. + +For the -redirect- context, the extra information is in the form +`-redirect-,OP,COMMAND', where OP is the redirection operator and +COMMAND is the name of the command on the line. If there is no command +on the line yet, the COMMAND field will be empty. + +For the -value- context, the form is `-value-,NAME,COMMAND', where NAME +is the name of the parameter on the left hand side of the assignment. +In the case of elements of an associative array, for example +`assoc=(key <TAB>', NAME is expanded to `NAME-KEY'. In certain special +contexts, such as completing after `make CFLAGS=', the COMMAND part +gives the name of the command, here make; otherwise it is empty. + +It is not necessary to define fully specific completions as the +functions provided will try to generate completions by progressively +replacing the elements with `-default-'. For example, when completing +after `foo=<TAB>', _value will try the names `-value-,foo,' (note the +empty COMMAND part), `-value-,foo,-default-' +and`-value-,-default-,-default-', in that order, until it finds a +function to handle the context. + +As an example: + + + compdef '_files -g "*.log"' '-redirect-,2>,-default-' + +completes files matching `*.log' after `2> <TAB>' for any command with +no more specific handler defined. + +Also: + + + compdef _foo -value-,-default-,-default- + +specifies that _foo provides completions for the values of parameters +for which no special function has been defined. This is usually +handled by the function _value itself. + +The same lookup rules are used when looking up styles (as described +below); for example + + + zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log' + +is another way to make completion after `2> <TAB>' complete files +matching `*.log'. + + + +20.2.3 Functions +---------------- + +The following function is defined by compinit and may be called +directly. + + +compdef [ -ane ] FUNCTION NAME ... [ -{p|P} PATTERN ... [ -N NAME ...]] +compdef -d NAME ... +compdef -k [ -an ] FUNCTION STYLE KEY-SEQUENCE [ KEY-SEQUENCE ... ] +compdef -K [ -an ] FUNCTION NAME STYLE KEY-SEQ [ NAME STYLE SEQ ... ] + The first form defines the FUNCTION to call for completion in the + given contexts as described for the #compdef tag above. + + Alternatively, all the arguments may have the form `CMD=SERVICE'. + Here SERVICE should already have been defined by `CMD1=SERVICE' + lines in #compdef files, as described above. The argument for CMD + will be completed in the same way as SERVICE. + + The FUNCTION argument may alternatively be a string containing + almost any shell code. If the string contains an equal sign, the + above will take precedence. The option -e may be used to specify + the first argument is to be evaluated as shell code even if it + contains an equal sign. The string will be executed using the + eval builtin command to generate completions. This provides a way + of avoiding having to define a new completion function. For + example, to complete files ending in `.h' as arguments to the + command foo: + + + compdef '_files -g "*.h"' foo + + The option -n prevents any completions already defined for the + command or context from being overwritten. + + The option -d deletes any completion defined for the command or + contexts listed. + + The NAMEs may also contain -p, -P and -N options as described for + the #compdef tag. The effect on the argument list is identical, + switching between definitions of patterns tried initially, + patterns tried finally, and normal commands and contexts. + + The parameter $_compskip may be set by any function defined for a + pattern context. If it is set to a value containing the substring + `patterns' none of the pattern-functions will be called; if it is + set to a value containing the substring `all', no other function + will be called. Setting $_compskip in this manner is of particular + utility when using the -p option, as otherwise the dispatcher will + move on to additional functions (likely the default one) after + calling the pattern-context one, which can mangle the display of + completion possibilities if not handled properly. + + The form with -k defines a widget with the same name as the + FUNCTION that will be called for each of the KEY-SEQUENCEs; this + is like the #compdef -k tag. The function should generate the + completions needed and will otherwise behave like the builtin + widget whose name is given as the STYLE argument. The widgets + usable for this are: complete-word, delete-char-or-list, + expand-or-complete, expand-or-complete-prefix, list-choices, + menu-complete, menu-expand-or-complete, and reverse-menu-complete, + as well as menu-select if the zsh/complist module is loaded. The + option -n prevents the key being bound if it is already to bound + to something other than undefined-key. + + The form with -K is similar and defines multiple widgets based on + the same FUNCTION, each of which requires the set of three + arguments NAME, STYLE and KEY-SEQuence, where the latter two are as + for -k and the first must be a unique widget name beginning with an + underscore. + + Wherever applicable, the -a option makes the FUNCTION + autoloadable, equivalent to autoload -U FUNCTION. + + +The function compdef can be used to associate existing completion +functions with new commands. For example, + + + compdef _pids foo + +uses the function _pids to complete process IDs for the command foo. + +Note also the _gnu_generic function described below, which can be used +to complete options for commands that understand the `--help' option. + + + + +File: zsh.info, Node: Completion System Configuration, Next: Control Functions, Prev: Initialization, Up: Completion System + +20.3 Completion System Configuration +==================================== + + + +This section gives a short overview of how the completion system works, +and then more detail on how users can configure how and when matches are +generated. + + + +20.3.1 Overview +--------------- + +When completion is attempted somewhere on the command line the +completion system begins building the context. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position. This takes account of a +number of things including the command word (such as `grep' or `zsh') +and options to which the current word may be an argument (such as the +`-o' option to zsh which takes a shell option as an argument). + +The context starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on). Therefore the context will vary during the +same call to the completion system. + +This context information is condensed into a string consisting of +multiple fields separated by colons, referred to simply as `the +context' in the remainder of the documentation. Note that a user of +the completion system rarely needs to compose a context string, unless +for example a new function is being written to perform completion for a +new command. What a user may need to do is compose a _style_ pattern, +which is matched against a context when needed to look up +context-sensitive options that configure the completion system. + +The next few paragraphs explain how a context is composed within the +completion function suite. Following that is discussion of how _styles_ +are defined. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control. They +are defined with the zstyle builtin command (*Note The zsh/zutil +Module::). + +The context string always consists of a fixed set of fields, separated +by colons and with a leading colon before the first. Fields which are +not yet known are left empty, but the surrounding colons appear anyway. +The fields are always in the order +:completion:FUNCTION:COMPLETER:COMMAND:ARGUMENT:TAG. These have the +following meaning: + + + * The literal string completion, saying that this style is used by + the completion system. This distinguishes the context from those + used by, for example, zle widgets and ZFTP functions. + + * The FUNCTION, if completion is called from a named widget rather + than through the normal completion system. Typically this is + blank, but it is set by special widgets such as predict-on and the + various functions in the Widget directory of the distribution to + the name of that function, often in an abbreviated form. + + * The COMPLETER currently active, the name of the function without + the leading underscore and with other underscores converted to + hyphens. A `completer' is in overall control of how completion is + to be performed; `complete' is the simplest, but other completers + exist to perform related tasks such as correction, or to modify + the behaviour of a later completer. See *Note Control Functions:: + for more information. + + * The COMMAND or a special -CONTEXT-, just at it appears following + the #compdef tag or the compdef function. Completion functions + for commands that have sub-commands usually modify this field to + contain the name of the command followed by a minus sign and the + sub-command. For example, the completion function for the cvs + command sets this field to cvs-add when completing arguments to + the add subcommand. + + * The ARGUMENT; this indicates which command line or option argument + we are completing. For command arguments this generally takes the + form argument-N, where N is the number of the argument, and for + arguments to options the form option-OPT-N where N is the number + of the argument to option OPT. However, this is only the case if + the command line is parsed with standard UNIX-style options and + arguments, so many completions do not set this. + + * The TAG. As described previously, tags are used to discriminate + between the types of matches a completion function can generate in + a certain context. Any completion function may use any tag name + it likes, but a list of the more common ones is given below. + + +The context is gradually put together as the functions are executed, +starting with the main entry point, which adds :completion: and the +FUNCTION element if necessary. The completer then adds the COMPLETER +element. The contextual completion adds the COMMAND and ARGUMENT +options. Finally, the TAG is added when the types of completion are +known. For example, the context name + + + :completion::complete:dvips:option-o-1:files + +says that normal completion was attempted as the first argument to the +option -o of the command dvips: + + + dvips -o ... + +and the completion function will generate filenames. + +Usually completion will be tried for all possible tags in an order given +by the completion function. However, this can be altered by using the +tag-order style. Completion is then restricted to the list of given +tags in the given order. + +The _complete_help bindable command shows all the contexts and tags +available for completion at a particular point. This provides an easy +way of finding information for tag-order and other styles. It is +described in *Note Bindable Commands::. + +When looking up styles the completion system uses full context names, +including the tag. Looking up the value of a style therefore consists +of two things: the context, which is matched to the most specific (best +fitting) style pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that style patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances. + +For example, many completion functions can generate matches in a simple +and a verbose form and use the verbose style to decide which form +should be used. To make all such functions use the verbose form, put + + + zstyle ':completion:*' verbose yes + +in a startup file (probably .zshrc). This gives the verbose style the +value yes in every context inside the completion system, unless that +context has a more specific definition. It is best to avoid giving the +context as `*' in case the style has some meaning outside the +completion system. + +Many such general purpose styles can be configured simply by using the +compinstall function. + +A more specific example of the use of the verbose style is by the +completion for the kill builtin. If the style is set, the builtin +lists full job texts and process command lines; otherwise it shows the +bare job numbers and PIDs. To turn the style off for this use only: + + + zstyle ':completion:*:*:kill:*:*' verbose no + +For even more control, the style can use one of the tags `jobs' or +`processes'. To turn off verbose display only for jobs: + + + zstyle ':completion:*:*:kill:*:jobs' verbose no + +The -e option to zstyle even allows completion function code to appear +as the argument to a style; this requires some understanding of the +internals of completion functions (see *Note Completion Widgets::)). +For example, + + + zstyle -e ':completion:*' hosts 'reply=($myhosts)' + +This forces the value of the hosts style to be read from the variable +myhosts each time a host name is needed; this is useful if the value of +myhosts can change dynamically. For another useful example, see the +example in the description of the file-list style below. This form can +be slow and should be avoided for commonly examined styles such as menu +and list-rows-first. + +Note that the order in which styles are _defined_ does not matter; the +style mechanism uses the most specific possible match for a particular +style to determine the set of values. More precisely, strings are +preferred over patterns (for example, `:completion::complete:::foo' is +more specific than `:completion::complete:::*'), and longer patterns are +preferred over shorter patterns. + +A good rule of thumb is that any completion style pattern that needs to +include more than one wildcard (*) and that does not end in a tag name, +should include all six colons (:), possibly surrounding additional +wildcards. + +Style names like those of tags are arbitrary and depend on the +completion function. However, the following two sections list some of +the most common tags and styles. + + + +20.3.2 Standard Tags +-------------------- + + + +Some of the following are only used when looking up particular styles +and do not refer to a type of match. + + +accounts + used to look up the users-hosts style + +all-expansions + used by the _expand completer when adding the single string + containing all possible expansions + +all-files + for the names of all files (as distinct from a particular subset, + see the globbed-files tag). + +arguments + for arguments to a command + +arrays + for names of array parameters + +association-keys + for keys of associative arrays; used when completing inside a + subscript to a parameter of this type + +bookmarks + when completing bookmarks (e.g. for URLs and the zftp function + suite) + +builtins + for names of builtin commands + +characters + for single characters in arguments of commands such as stty. + Also used when completing character classes after an opening + bracket + +colormapids + for X colormap ids + +colors + for color names + +commands + for names of external commands. Also used by complex commands + such as cvs when completing names subcommands. + +contexts + for contexts in arguments to the zstyle builtin command + +corrections + used by the _approximate and _correct completers for possible + corrections + +cursors + for cursor names used by X programs + +default + used in some contexts to provide a way of supplying a default when + more specific tags are also valid. Note that this tag is used + when only the FUNCTION field of the context name is set + +descriptions + used when looking up the value of the format style to generate + descriptions for types of matches + +devices + for names of device special files + +directories + for names of directories -- local-directories is used instead when + completing arguments of cd and related builtin commands when the + cdpath array is set + +directory-stack + for entries in the directory stack + +displays + for X display names + +domains + for network domains + +email-PLUGIN + for email addresses from the `_email-PLUGIN' backend of + _email_addresses + +expansions + used by the _expand completer for individual words (as opposed to + the complete set of expansions) resulting from the expansion of a + word on the command line + +extensions + for X server extensions + +file-descriptors + for numbers of open file descriptors + +files + the generic file-matching tag used by functions completing + filenames + +fonts + for X font names + +fstypes + for file system types (e.g. for the mount command) + +functions + names of functions -- normally shell functions, although certain + commands may understand other kinds of function + +globbed-files + for filenames when the name has been generated by pattern matching + +groups + for names of user groups + +history-words + for words from the history + +hosts + for hostnames + +indexes + for array indexes + +jobs + for jobs (as listed by the `jobs' builtin) + +interfaces + for network interfaces + +keymaps + for names of zsh keymaps + +keysyms + for names of X keysyms + +libraries + for names of system libraries + +limits + for system limits + +local-directories + for names of directories that are subdirectories of the current + working directory when completing arguments of cd and related + builtin commands (compare path-directories) -- when the cdpath + array is unset, directories is used instead + +manuals + for names of manual pages + +mailboxes + for e-mail folders + +maps + for map names (e.g. NIS maps) + +messages + used to look up the format style for messages + +modifiers + for names of X modifiers + +modules + for modules (e.g. zsh modules) + +my-accounts + used to look up the users-hosts style + +named-directories + for named directories (you wouldn't have guessed that, would you?) + +names + for all kinds of names + +newsgroups + for USENET groups + +nicknames + for nicknames of NIS maps + +options + for command options + +original + used by the _approximate, _correct and _expand completers when + offering the original string as a match + +other-accounts + used to look up the users-hosts style + +other-files + for the names of any non-directory files. This is used instead of + all-files when the list-dirs-first style is in effect. + +packages + for packages (e.g. rpm or installed Debian packages) + +parameters + for names of parameters + +path-directories + for names of directories found by searching the cdpath array when + completing arguments of cd and related builtin commands (compare + local-directories) + +paths + used to look up the values of the expand, ambiguous and + special-dirs styles + +pods + for perl pods (documentation files) + +ports + for communication ports + +prefixes + for prefixes (like those of a URL) + +printers + for print queue names + +processes + for process identifiers + +processes-names + used to look up the command style when generating the names of + processes for killall + +sequences + for sequences (e.g. mh sequences) + +sessions + for sessions in the zftp function suite + +signals + for signal names + +strings + for strings (e.g. the replacement strings for the cd builtin + command) + +styles + for styles used by the zstyle builtin command + +suffixes + for filename extensions + +tags + for tags (e.g. rpm tags) + +targets + for makefile targets + +time-zones + for time zones (e.g. when setting the TZ parameter) + +types + for types of whatever (e.g. address types for the xhost command) + +urls + used to look up the urls and local styles when completing URLs + +users + for usernames + +values + for one of a set of values in certain lists + +variant + used by _pick_variant to look up the command to run when + determining what program is installed for a particular command + name. + +visuals + for X visuals + +warnings + used to look up the format style for warnings + +widgets + for zsh widget names + +windows + for IDs of X windows + +zsh-options + for shell options + + + +20.3.3 Standard Styles +---------------------- + + + +Note that the values of several of these styles represent boolean +values. Any of the strings `true', `on', `yes', and `1' can be used +for the value `true' and any of the strings `false', `off', `no', and +`0' for the value `false'. The behavior for any other value is +undefined except where explicitly mentioned. The default value may be +either `true' or `false' if the style is not set. + +Some of these styles are tested first for every possible tag +corresponding to a type of match, and if no style was found, for the +default tag. The most notable styles of this type are menu, +list-colors and styles controlling completion listing such as +list-packed and last-prompt. When tested for the default tag, only the +FUNCTION field of the context will be set so that a style using the +default tag will normally be defined along the lines of: + + + zstyle ':completion:*:default' menu ... + + +accept-exact + This is tested for the default tag in addition to the tags valid + for the current context. If it is set to `true' and any of the + trial matches is the same as the string on the command line, this + match will immediately be accepted (even if it would otherwise be + considered ambiguous). + + When completing pathnames (where the tag used is `paths') this + style accepts any number of patterns as the value in addition to + the boolean values. Pathnames matching one of these patterns will + be accepted immediately even if the command line contains some + more partially typed pathname components and these match no file + under the directory accepted. + + This style is also used by the _expand completer to decide if + words beginning with a tilde or parameter expansion should be + expanded. For example, if there are parameters foo and foobar, + the string `$foo' will only be expanded if accept-exact is set to + `true'; otherwise the completion system will be allowed to + complete $foo to $foobar. If the style is set to `continue', + _expand will add the expansion as a match and the completion + system will also be allowed to continue. + +accept-exact-dirs + This is used by filename completion. Unlike accept-exact it is a + boolean. By default, filename completion examines all components + of a path to see if there are completions of that component, even + if the component matches an existing directory. For example, when + completion after /usr/bin/, the function examines possible + completions to /usr. + + When this style is `true', any prefix of a path that matches an + existing directory is accepted without any attempt to complete it + further. Hence, in the given example, the path /usr/bin/ is + accepted immediately and completion tried in that directory. + + This style is also useful when completing after directories that + magically appear when referenced, such as ZFS .zfs directories or + NetApp .snapshot directories. When the style is set the shell + does not check for the existence of the directory within the + parent directory. + + If you wish to inhibit this behaviour entirely, set the + path-completion style (see below) to `false'. + +add-space + This style is used by the _expand completer. If it is `true' (the + default), a space will be inserted after all words resulting from + the expansion, or a slash in the case of directory names. If the + value is `file', the completer will only add a space to names of + existing files. Either a boolean `true' or the value `file' may + be combined with `subst', in which case the completer will not add + a space to words generated from the expansion of a substitution of + the form `$(...)' or `${...}'. + + The _prefix completer uses this style as a simple boolean value to + decide if a space should be inserted before the suffix. + +ambiguous + This applies when completing non-final components of filename + paths, in other words those with a trailing slash. If it is set, + the cursor is left after the first ambiguous component, even if + menu completion is in use. The style is always tested with the + paths tag. + +assign-list + When completing after an equals sign that is being treated as an + assignment, the completion system normally completes only one + filename. In some cases the value may be a list of filenames + separated by colons, as with PATH and similar parameters. This + style can be set to a list of patterns matching the names of such + parameters. + + The default is to complete lists when the word on the line already + contains a colon. + +auto-description + If set, this style's value will be used as the description for + options that are not described by the completion functions, but + that have exactly one argument. The sequence `%d' in the value + will be replaced by the description for this argument. Depending + on personal preferences, it may be useful to set this style to + something like `specify: %d'. Note that this may not work for + some commands. + +avoid-completer + This is used by the _all_matches completer to decide if the string + consisting of all matches should be added to the list currently + being generated. Its value is a list of names of completers. If + any of these is the name of the completer that generated the + matches in this completion, the string will not be added. + + The default value for this style is `_expand _old_list _correct + _approximate', i.e. it contains the completers for which a string + with all matches will almost never be wanted. + +cache-path + This style defines the path where any cache files containing dumped + completion data are stored. It defaults to + `$ZDOTDIR/.zcompcache', or `$HOME/.zcompcache' if $ZDOTDIR is not + defined. The completion cache will not be used unless the + use-cache style is set. + +cache-policy + This style defines the function that will be used to determine + whether a cache needs rebuilding. See the section on the + _cache_invalid function below. + +call-command + This style is used in the function for commands such as make and + ant where calling the command directly to generate matches suffers + problems such as being slow or, as in the case of make can + potentially cause actions in the makefile to be executed. If it is + set to `true' the command is called to generate matches. The + default value of this style is `false'. + +command + In many places, completion functions need to call external + commands to generate the list of completions. This style can be + used to override the command that is called in some such cases. + The elements of the value are joined with spaces to form a command + line to execute. The value can also start with a hyphen, in which + case the usual command will be added to the end; this is most + useful for putting `builtin' or `command' in front to make sure + the appropriate version of a command is called, for example to + avoid calling a shell function with the same name as an external + command. + + As an example, the completion function for process IDs uses this + style with the processes tag to generate the IDs to complete and + the list of processes to display (if the verbose style is `true'). + The list produced by the command should look like the output of the + ps command. The first line is not displayed, but is searched for + the string `PID' (or `pid') to find the position of the process + IDs in the following lines. If the line does not contain `PID', + the first numbers in each of the other lines are taken as the + process IDs to complete. + + Note that the completion function generally has to call the + specified command for each attempt to generate the completion + list. Hence care should be taken to specify only commands that + take a short time to run, and in particular to avoid any that may + never terminate. + +command-path + This is a list of directories to search for commands to complete. + The default for this style is the value of the special parameter + path. + +commands + This is used by the function completing sub-commands for the system + initialisation scripts (residing in /etc/init.d or somewhere not + too far away from that). Its values give the default commands to + complete for those commands for which the completion function isn't + able to find them out automatically. The default for this style + are the two strings `start' and `stop'. + +complete + This is used by the _expand_alias function when invoked as a + bindable command. If set to `true' and the word on the command + line is not the name of an alias, matching alias names will be + completed. + +complete-options + This is used by the completer for cd, chdir and pushd. For these + commands a - is used to introduce a directory stack entry and + completion of these is far more common than completing options. + Hence unless the value of this style is `true' options will not be + completed, even after an initial -. If it is `true', options will + be completed after an initial - unless there is a preceding -- on + the command line. + +completer + The strings given as the value of this style provide the names of + the completer functions to use. The available completer functions + are described in *Note Control Functions::. + + Each string may be either the name of a completer function or a + string of the form `FUNCTION:NAME'. In the first case the + COMPLETER field of the context will contain the name of the + completer without the leading underscore and with all other + underscores replaced by hyphens. In the second case the FUNCTION + is the name of the completer to call, but the context will contain + the user-defined NAME in the COMPLETER field of the context. If + the NAME starts with a hyphen, the string for the context will be + build from the name of the completer function as in the first case + with the NAME appended to it. For example: + + + zstyle ':completion:*' completer _complete _complete:-foo + + Here, completion will call the _complete completer twice, once + using `complete' and once using `complete-foo' in the COMPLETER + field of the context. Normally, using the same completer more + than once only makes sense when used with the `FUNCTIONS:NAME' + form, because otherwise the context name will be the same in all + calls to the completer; possible exceptions to this rule are the + _ignored and _prefix completers. + + The default value for this style is `_complete _ignored': only + completion will be done, first using the ignored-patterns style + and the $fignore array and then without ignoring matches. + +condition + This style is used by the _list completer function to decide if + insertion of matches should be delayed unconditionally. The + default is `true'. + +delimiters + This style is used when adding a delimiter for use with history + modifiers or glob qualifiers that have delimited arguments. It is + an array of preferred delimiters to add. Non-special characters + are preferred as the completion system may otherwise become + confused. The default list is :, +, /, -, %. The list may be + empty to force a delimiter to be typed. + +disabled + If this is set to `true', the _expand_alias completer and bindable + command will try to expand disabled aliases, too. The default is + `false'. + +domains + A list of names of network domains for completion. If this is not + set, domain names will be taken from the file /etc/resolv.conf. + +environ + The environ style is used when completing for `sudo'. It is set + to an array of `VAR=VALUE' assignments to be exported into the + local environment before the completion for the target command is + invoked. + zstyle ':completion:*:sudo::' environ \ + PATH="/sbin:/usr/sbin:$PATH" HOME="/root" + +expand + This style is used when completing strings consisting of multiple + parts, such as path names. + + If one of its values is the string `prefix', the partially typed + word from the line will be expanded as far as possible even if + trailing parts cannot be completed. + + If one of its values is the string `suffix', matching names for + components after the first ambiguous one will also be added. This + means that the resulting string is the longest unambiguous string + possible. However, menu completion can be used to cycle through + all matches. + +fake + This style may be set for any completion context. It specifies + additional strings that will always be completed in that context. + The form of each string is `VALUE:DESCRIPTION'; the colon and + description may be omitted, but any literal colons in VALUE must + be quoted with a backslash. Any DESCRIPTION provided is shown + alongside the value in completion listings. + + It is important to use a sufficiently restrictive context when + specifying fake strings. Note that the styles fake-files and + fake-parameters provide additional features when completing files + or parameters. + +fake-always + This works identically to the fake style except that the + ignored-patterns style is not applied to it. This makes it + possible to override a set of matches completely by setting the + ignored patterns to `*'. + + The following shows a way of supplementing any tag with arbitrary + data, but having it behave for display purposes like a separate + tag. In this example we use the features of the tag-order style + to divide the named-directories tag into two when performing + completion with the standard completer complete for arguments of + cd. The tag named-directories-normal behaves as normal, but the + tag named-directories-mine contains a fixed set of directories. + This has the effect of adding the match group `extra directories' + with the given completions. + + + zstyle ':completion::complete:cd:*' tag-order \ + 'named-directories:-mine:extra\ directories + named-directories:-normal:named\ directories *' + zstyle ':completion::complete:cd:*:named-directories-mine' \ + fake-always mydir1 mydir2 + zstyle ':completion::complete:cd:*:named-directories-mine' \ + ignored-patterns '*' + +fake-files + This style is used when completing files and looked up without a + tag. Its values are of the form `DIR:NAMES...'. This will add + the NAMES (strings separated by spaces) as possible matches when + completing in the directory DIR, even if no such files really + exist. The dir may be a pattern; pattern characters or colons in + DIR should be quoted with a backslash to be treated literally. + + This can be useful on systems that support special file systems + whose top-level pathnames can not be listed or generated with glob + patterns (but see accept-exact-dirs for a more general way of + dealing with this problem). It can also be used for directories + for which one does not have read permission. + + The pattern form can be used to add a certain `magic' entry to all + directories on a particular file system. + +fake-parameters + This is used by the completion function for parameter names. Its + values are names of parameters that might not yet be set but + should be completed nonetheless. Each name may also be followed + by a colon and a string specifying the type of the parameter (like + `scalar', `array' or `integer'). If the type is given, the name + will only be completed if parameters of that type are required in + the particular context. Names for which no type is specified will + always be completed. + +file-list + This style controls whether files completed using the standard + builtin mechanism are to be listed with a long list similar to ls + -l. Note that this feature uses the shell module zsh/stat for + file information; this loads the builtin stat which will replace + any external stat executable. To avoid this the following code + can be included in an initialization file: + + + zmodload -i zsh/stat + disable stat + + The style may either be set to a `true' value (or `all'), or one + of the values `insert' or `list', indicating that files are to be + listed in long format in all circumstances, or when attempting to + insert a file name, or when listing file names without attempting + to insert one. + + More generally, the value may be an array of any of the above + values, optionally followed by =NUM. If NUM is present it gives + the maximum number of matches for which long listing style will be + used. For example, + + + zstyle ':completion:*' file-list list=20 insert=10 + + specifies that long format will be used when listing up to 20 files + or inserting a file with up to 10 matches (assuming a listing is + to be shown at all, for example on an ambiguous completion), else + short format will be used. + + + zstyle -e ':completion:*' file-list \ + '(( ${+NUMERIC} )) && reply=(true)' + + specifies that long format will be used any time a numeric + argument is supplied, else short format. + +file-patterns + This is used by the standard function for completing filenames, + _files. If the style is unset up to three tags are offered, + `globbed-files',`directories' and `all-files', depending on the + types of files expected by the caller of _files. The first two + (`globbed-files' and `directories') are normally offered together + to make it easier to complete files in sub-directories. + + The file-patterns style provides alternatives to the default tags, + which are not used. Its value consists of elements of the form + `PATTERN:TAG'; each string may contain any number of such + specifications separated by spaces. + + The PATTERN is a pattern that is to be used to generate filenames. + Any occurrence of the sequence `%p' is replaced by any pattern(s) + passed by the function calling _files. Colons in the pattern must + be preceded by a backslash to make them distinguishable from the + colon before the TAG. If more than one pattern is needed, the + patterns can be given inside braces, separated by commas. + + The TAGs of all strings in the value will be offered by _files and + used when looking up other styles. Any TAGs in the same word will + be offered at the same time and before later words. If no `:TAG' + is given the `files' tag will be used. + + The TAG may also be followed by an optional second colon and a + description, which will be used for the `%d' in the value of the + format style (if that is set) instead of the default description + supplied by the completion function. If the description given + here contains itself a `%d', that is replaced with the description + supplied by the completion function. + + For example, to make the rm command first complete only names of + object files and then the names of all files if there is no + matching object file: + + + zstyle ':completion:*:*:rm:*:*' file-patterns \ + '*.o:object-files' '%p:all-files' + + To alter the default behaviour of file completion -- offer files + matching a pattern and directories on the first attempt, then all + files -- to offer only matching files on the first attempt, then + directories, and finally all files: + + + zstyle ':completion:*' file-patterns \ + '%p:globbed-files' '*(-/):directories' '*:all-files' + + This works even where there is no special pattern: _files matches + all files using the pattern `*' at the first step and stops when it + sees this pattern. Note also it will never try a pattern more + than once for a single completion attempt. + + During the execution of completion functions, the EXTENDED_GLOB + option is in effect, so the characters `#', `~' and `^' have + special meanings in the patterns. + +file-sort + The standard filename completion function uses this style without + a tag to determine in which order the names should be listed; menu + completion will cycle through them in the same order. The possible + values are: `size' to sort by the size of the file; `links' to + sort by the number of links to the file; `modification' (or `time' + or `date') to sort by the last modification time; `access' to sort + by the last access time; and `inode' (or `change') to sort by the + last inode change time. If the style is set to any other value, + or is unset, files will be sorted alphabetically by name. If the + value contains the string `reverse', sorting is done in the + opposite order. If the value contains the string `follow', + timestamps are associated with the targets of symbolic links; the + default is to use the timestamps of the links themselves. + +file-split-chars + A set of characters that will cause _all_ file completions for the + given context to be split at the point where any of the characters + occurs. A typical use is to set the style to :; then everything + up to and including the last : in the string so far is ignored when + completing files. As this is quite heavy-handed, it is usually + preferable to update completion functions for contexts where this + behaviour is useful. + +filter + The ldap plugin of email address completion (see _email_addresses) + uses this style to specify the attributes to match against when + filtering entries. So for example, if the style is set to `sn', + matching is done against surnames. Standard LDAP filtering is + used so normal completion matching is bypassed. If this style is + not set, the LDAP plugin is skipped. You may also need to set the + command style to specify how to connect to your LDAP server. + +force-list + This forces a list of completions to be shown at any point where + listing is done, even in cases where the list would usually be + suppressed. For example, normally the list is only shown if there + are at least two different matches. By setting this style to + `always', the list will always be shown, even if there is only a + single match that will immediately be accepted. The style may also + be set to a number. In this case the list will be shown if there + are at least that many matches, even if they would all insert the + same string. + + This style is tested for the default tag as well as for each tag + valid for the current completion. Hence the listing can be forced + only for certain types of match. + +format + If this is set for the descriptions tag, its value is used as a + string to display above matches in completion lists. The sequence + `%d' in this string will be replaced with a short description of + what these matches are. This string may also contain the output + attribute sequences understood by compadd -X (see *Note Completion + Widgets::). + + The style is tested with each tag valid for the current completion + before it is tested for the descriptions tag. Hence different + format strings can be defined for different types of match. + + Note also that some completer functions define additional + `%'-sequences. These are described for the completer functions + that make use of them. + + Some completion functions display messages that may be customised + by setting this style for the messages tag. Here, the `%d' is + replaced with a message given by the completion function. + + Finally, the format string is looked up with the warnings tag, for + use when no matches could be generated at all. In this case the + `%d' is replaced with the descriptions for the matches that were + expected separated by spaces. The sequence `%D' is replaced with + the same descriptions separated by newlines. + + It is possible to use printf-style field width specifiers with `%d' + and similar escape sequences. This is handled by the zformat + builtin command from the zsh/zutil module, see *Note The zsh/zutil + Module::. + +glob + This is used by the _expand completer. If it is set to `true' + (the default), globbing will be attempted on the words resulting + from a previous substitution (see the substitute style) or else + the original string from the line. + +global + If this is set to `true' (the default), the _expand_alias + completer and bindable command will try to expand global aliases. + +group-name + The completion system can group different types of matches, which + appear in separate lists. This style can be used to give the + names of groups for particular tags. For example, in command + position the completion system generates names of builtin and + external commands, names of aliases, shell functions and + parameters and reserved words as possible completions. To have + the external commands and shell functions listed separately: + + + zstyle ':completion:*:*:-command-:*:commands' \ + group-name commands + zstyle ':completion:*:*:-command-:*:functions' \ + group-name functions + + As a consequence, any match with the same tag will be displayed in + the same group. + + If the name given is the empty string the name of the tag for the + matches will be used as the name of the group. So, to have all + different types of matches displayed separately, one can just set: + + + zstyle ':completion:*' group-name '' + + All matches for which no group name is defined will be put in a + group named -default-. + +group-order + This style is additional to the group-name style to specify the + order for display of the groups defined by that style (compare + tag-order, which determines which completions appear at all). The + groups named are shown in the given order; any other groups are + shown in the order defined by the completion function. + + For example, to have names of builtin commands, shell functions and + external commands appear in that order when completing in command + position: + + + zstyle ':completion:*:*:-command-:*:*' group-order \ + builtins functions commands + +groups + A list of names of UNIX groups. If this is not set, group names + are taken from the YP database or the file `/etc/group'. + +hidden + If this is set to `true', matches for the given context will not + be listed, although any description for the matches set with the + format style will be shown. If it is set to `all', not even the + description will be displayed. + + Note that the matches will still be completed; they are just not + shown in the list. To avoid having matches considered as possible + completions at all, the tag-order style can be modified as + described below. + +hosts + A list of names of hosts that should be completed. If this is not + set, hostnames are taken from the file `/etc/hosts'. + +hosts-ports + This style is used by commands that need or accept hostnames and + network ports. The strings in the value should be of the form + `HOST:PORT'. Valid ports are determined by the presence of + hostnames; multiple ports for the same host may appear. + +ignore-line + This is tested for each tag valid for the current completion. If + it is set to `true', none of the words that are already on the line + will be considered as possible completions. If it is set to + `current', the word the cursor is on will not be considered as a + possible completion. The value `current-shown' is similar but only + applies if the list of completions is currently shown on the + screen. Finally, if the style is set to `other', all words on the + line except for the current one will be excluded from the possible + completions. + + The values `current' and `current-shown' are a bit like the + opposite of the accept-exact style: only strings with missing + characters will be completed. + + Note that you almost certainly don't want to set this to `true' or + `other' for a general context such as `:completion:*'. This is + because it would disallow completion of, for example, options + multiple times even if the command in question accepts the option + more than once. + +ignore-parents + The style is tested without a tag by the function completing + pathnames in order to determine whether to ignore the names of + directories already mentioned in the current word, or the name of + the current working directory. The value must include one or both + of the following strings: + + + parent + The name of any directory whose path is already contained in + the word on the line is ignored. For example, when + completing after foo/../, the directory foo will not be + considered a valid completion. + + pwd + The name of the current working directory will not be + completed; hence, for example, completion after ../ will not + use the name of the current directory. + + + In addition, the value may include one or both of: + + + .. + Ignore the specified directories only when the word on the + line contains the substring `../'. + + directory + Ignore the specified directories only when names of + directories are completed, not when completing names of files. + + + Excluded values act in a similar fashion to values of the + ignored-patterns style, so they can be restored to consideration by + the _ignored completer. + +extra-verbose + If set, the completion listing is more verbose at the cost of a + probable decrease in completion speed. Completion performance + will suffer if this style is set to `true'. + +ignored-patterns + A list of patterns; any trial completion matching one of the + patterns will be excluded from consideration. The _ignored + completer can appear in the list of completers to restore the + ignored matches. This is a more configurable version of the shell + parameter $fignore. + + Note that the EXTENDED_GLOB option is set during the execution of + completion functions, so the characters `#', `~' and `^' have + special meanings in the patterns. + +insert + This style is used by the _all_matches completer to decide whether + to insert the list of all matches unconditionally instead of + adding the list as another match. + +insert-ids + When completing process IDs, for example as arguments to the kill + and wait builtins the name of a command may be converted to the + appropriate process ID. A problem arises when the process name + typed is not unique. By default (or if this style is set + explicitly to `menu') the name will be converted immediately to a + set of possible IDs, and menu completion will be started to cycle + through them. + + If the value of the style is `single', the shell will wait until + the user has typed enough to make the command unique before + converting the name to an ID; attempts at completion will be + unsuccessful until that point. If the value is any other string, + menu completion will be started when the string typed by the user + is longer than the common prefix to the corresponding IDs. + +insert-tab + If this is set to `true', the completion system will insert a TAB + character (assuming that was used to start completion) instead of + performing completion when there is no non-blank character to the + left of the cursor. If it is set to `false', completion will be + done even there. + + The value may also contain the substrings `pending' or + `pending=VAL'. In this case, the typed character will be inserted + instead of starting completion when there is unprocessed input + pending. If a VAL is given, completion will not be done if there + are at least that many characters of unprocessed input. This is + often useful when pasting characters into a terminal. Note + however, that it relies on the $PENDING special parameter from the + zsh/zle module being set properly which is not guaranteed on all + platforms. + + The default value of this style is `true' except for completion + within vared builtin command where it is `false'. + +insert-unambiguous + This is used by the _match and _approximate completers. These + completers are often used with menu completion since the word typed + may bear little resemblance to the final completion. However, if + this style is `true', the completer will start menu completion + only if it could find no unambiguous initial string at least as + long as the original string typed by the user. + + In the case of the _approximate completer, the completer field in + the context will already have been set to one of correct-NUM or + approximate-NUM, where NUM is the number of errors that were + accepted. + + In the case of the _match completer, the style may also be set to + the string `pattern'. Then the pattern on the line is left + unchanged if it does not match unambiguously. + +gain-privileges + If set to true, this style enables the use of commands like sudo + or doas to gain extra privileges when retrieving information for + completion. This is only done when a command such as sudo appears + on the command-line. To force the use of, e.g. sudo or to override + any prefix that might be added due to gain-privileges, the command + style can be used with a value that begins with a hyphen. + +keep-prefix + This style is used by the _expand completer. If it is `true', the + completer will try to keep a prefix containing a tilde or parameter + expansion. Hence, for example, the string `~/f*' would be + expanded to `~/foo' instead of `/home/user/foo'. If the style is + set to `changed' (the default), the prefix will only be left + unchanged if there were other changes between the expanded words + and the original word from the command line. Any other value + forces the prefix to be expanded unconditionally. + + The behaviour of _expand when this style is `true' is to cause + _expand to give up when a single expansion with the restored + prefix is the same as the original; hence any remaining completers + may be called. + +last-prompt + This is a more flexible form of the ALWAYS_LAST_PROMPT option. If + it is `true', the completion system will try to return the cursor + to the previous command line after displaying a completion list. + It is tested for all tags valid for the current completion, then + the default tag. The cursor will be moved back to the previous + line if this style is `true' for all types of match. Note that + unlike the ALWAYS_LAST_PROMPT option this is independent of the + numeric argument. + +known-hosts-files + This style should contain a list of files to search for host names + and (if the use-ip style is set) IP addresses in a format + compatible with ssh known_hosts files. If it is not set, the files + /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used. + +list + This style is used by the _history_complete_word bindable command. + If it is set to `true' it has no effect. If it is set to `false' + matches will not be listed. This overrides the setting of the + options controlling listing behaviour, in particular AUTO_LIST. + The context always starts with `:completion:history-words'. + +list-colors + If the zsh/complist module is loaded, this style can be used to set + color specifications. This mechanism replaces the use of the + ZLS_COLORS and ZLS_COLOURS parameters described in *Note The + zsh/complist Module::, but the syntax is the same. + + If this style is set for the default tag, the strings in the value + are taken as specifications that are to be used everywhere. If it + is set for other tags, the specifications are used only for + matches of the type described by the tag. For this to work best, + the group-name style must be set to an empty string. + + In addition to setting styles for specific tags, it is also + possible to use group names specified explicitly by the group-name + tag together with the `(group)' syntax allowed by the ZLS_COLORS + and ZLS_COLOURS parameters and simply using the default tag. + + It is possible to use any color specifications already set up for + the GNU version of the ls command: + + + zstyle ':completion:*:default' list-colors \ + ${(s.:.)LS_COLORS} + + The default colors are the same as for the GNU ls command and can + be obtained by setting the style to an empty string (i.e. ''). + +list-dirs-first + This is used by file completion. If set, directories to be + completed are listed separately from and before completion for + other files, regardless of tag ordering. In addition, the tag + other-files is used in place of all-files for the remaining files, + to indicate that no directories are presented with that tag. + +list-grouped + If this style is `true' (the default), the completion system will + try to make certain completion listings more compact by grouping + matches. For example, options for commands that have the same + description (shown when the verbose style is set to `true') will + appear as a single entry. However, menu selection can be used to + cycle through all the matches. + +list-packed + This is tested for each tag valid in the current context as well + as the default tag. If it is set to `true', the corresponding + matches appear in listings as if the LIST_PACKED option were set. + If it is set to `false', they are listed normally. + +list-prompt + If this style is set for the default tag, completion lists that + don't fit on the screen can be scrolled (see *Note The + zsh/complist Module::). The value, if not the empty string, will + be displayed after every screenful and the shell will prompt for a + key press; if the style is set to the empty string, a default + prompt will be used. + + The value may contain the escape sequences: `%l' or `%L', which + will be replaced by the number of the last line displayed and the + total number of lines; `%m' or `%M', the number of the last match + shown and the total number of matches; and `%p' and `%P', `Top' + when at the beginning of the list, `Bottom' when at the end and the + position shown as a percentage of the total length otherwise. In + each case the form with the uppercase letter will be replaced by a + string of fixed width, padded to the right with spaces, while the + lowercase form will be replaced by a variable width string. As in + other prompt strings, the escape sequences `%S', `%s', `%B', `%b', + `%U', `%u' for entering and leaving the display modes standout, + bold and underline, and `%F', `%f', `%K', `%k' for changing the + foreground background colour, are also available, as is the form + `%{...%}' for enclosing escape sequences which display with zero + (or, with a numeric argument, some other) width. + + After deleting this prompt the variable LISTPROMPT should be unset + for the removal to take effect. + +list-rows-first + This style is tested in the same way as the list-packed style and + determines whether matches are to be listed in a rows-first + fashion as if the LIST_ROWS_FIRST option were set. + +list-suffixes + This style is used by the function that completes filenames. If + it is `true', and completion is attempted on a string containing + multiple partially typed pathname components, all ambiguous + components will be shown. Otherwise, completion stops at the + first ambiguous component. + +list-separator + The value of this style is used in completion listing to separate + the string to complete from a description when possible (e.g. when + completing options). It defaults to `--' (two hyphens). + +local + This is for use with functions that complete URLs for which the + corresponding files are available directly from the file system. + Its value should consist of three strings: a hostname, the path to + the default web pages for the server, and the directory name used + by a user placing web pages within their home area. + + For example: + + + zstyle ':completion:*' local toast \ + /var/http/public/toast public_html + + Completion after `http://toast/stuff/' will look for files in the + directory /var/http/public/toast/stuff, while completion after + `http://toast/~yousir/' will look for files in the directory + ~yousir/public_html. + +mail-directory + If set, zsh will assume that mailbox files can be found in the + directory specified. It defaults to `~/Mail'. + +match-original + This is used by the _match completer. If it is set to only, + _match will try to generate matches without inserting a `*' at the + cursor position. If set to any other non-empty value, it will + first try to generate matches without inserting the `*' and if + that yields no matches, it will try again with the `*' inserted. + If it is unset or set to the empty string, matching will only be + performed with the `*' inserted. + +matcher + This style is tested separately for each tag valid in the current + context. Its value is placed before any match specifications + given by the matcher-list style so can override them via the use + of an x: specification. The value should be in the form described + in *Note Completion Matching Control::. For examples of this, see + the description of the tag-order style. + + For notes comparing the use of this and the matcher-list style, see + under the description of the tag-order style. + +matcher-list + This style can be set to a list of match specifications that are to + be applied everywhere. Match specifications are described in *Note + Completion Matching Control::. The completion system will try + them one after another for each completer selected. For example, + to try first simple completion and, if that generates no matches, + case-insensitive completion: + + + zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}' + + By default each specification replaces the previous one; however, + if a specification is prefixed with +, it is added to the existing + list. Hence it is possible to create increasingly general + specifications without repetition: + + + zstyle ':completion:*' matcher-list \ + '' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}' + + It is possible to create match specifications valid for particular + completers by using the third field of the context. This applies + only to completers that override the global matcher-list, which as + of this writing includes only _prefix and _ignored. For example, + to use the completers _complete and _prefix but allow + case-insensitive completion only with _complete: + + + zstyle ':completion:*' completer _complete _prefix + zstyle ':completion:*:complete:*:*:*' matcher-list \ + '' 'm:{a-zA-Z}={A-Za-z}' + + User-defined names, as explained for the completer style, are + available. This makes it possible to try the same completer more + than once with different match specifications each time. For + example, to try normal completion without a match specification, + then normal completion with case-insensitive matching, then + correction, and finally partial-word completion: + + + zstyle ':completion:*' completer \ + _complete _correct _complete:foo + zstyle ':completion:*:complete:*:*:*' matcher-list \ + '' 'm:{a-zA-Z}={A-Za-z}' + zstyle ':completion:*:foo:*:*:*' matcher-list \ + 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*' + + If the style is unset in any context no match specification is + applied. Note also that some completers such as _correct and + _approximate do not use the match specifications at all, though + these completers will only ever be called once even if the + matcher-list contains more than one element. + + Where multiple specifications are useful, note that the _entire_ + completion is done for each element of matcher-list, which can + quickly reduce the shell's performance. As a rough rule of thumb, + one to three strings will give acceptable performance. On the + other hand, putting multiple space-separated values into the same + string does not have an appreciable impact on performance. + + If there is no current matcher or it is empty, and the option + NO_CASE_GLOB is in effect, the matching for files is performed + case-insensitively in any case. However, any matcher must + explicitly specify case-insensitive matching if that is required. + + For notes comparing the use of this and the matcher style, see + under the description of the tag-order style. + +max-errors + This is used by the _approximate and _correct completer functions + to determine the maximum number of errors to allow. The completer + will try to generate completions by first allowing one error, then + two errors, and so on, until either a match or matches were found + or the maximum number of errors given by this style has been + reached. + + If the value for this style contains the string `numeric', the + completer function will take any numeric argument as the maximum + number of errors allowed. For example, with + + + zstyle ':completion:*:approximate:::' max-errors 2 numeric + + two errors are allowed if no numeric argument is given, but with a + numeric argument of six (as in `ESC-6 TAB'), up to six errors are + accepted. Hence with a value of `0 numeric', no correcting + completion will be attempted unless a numeric argument is given. + + If the value contains the string `not-numeric', the completer will + _not_ try to generate corrected completions when given a numeric + argument, so in this case the number given should be greater than + zero. For example, `2 not-numeric' specifies that correcting + completion with two errors will usually be performed, but if a + numeric argument is given, correcting completion will not be + performed. + + The default value for this style is `2 numeric'. + +max-matches-width + This style is used to determine the trade off between the width of + the display used for matches and the width used for their + descriptions when the verbose style is in effect. The value gives + the number of display columns to reserve for the matches. The + default is half the width of the screen. + + This has the most impact when several matches have the same + description and so will be grouped together. Increasing the style + will allow more matches to be grouped together; decreasing it will + allow more of the description to be visible. + +menu + If this is `true' in the context of any of the tags defined for + the current completion menu completion will be used. The value for + a specific tag will take precedence over that for the `default' + tag. + + If none of the values found in this way is `true' but at least one + is set to `auto', the shell behaves as if the AUTO_MENU option is + set. + + If one of the values is explicitly set to `false', menu completion + will be explicitly turned off, overriding the MENU_COMPLETE option + and other settings. + + In the form `yes=NUM', where `yes' may be any of the `true' values + (`yes', `true', `on' and `1'), menu completion will be turned on + if there are at least NUM matches. In the form `yes=long', menu + completion will be turned on if the list does not fit on the + screen. This does not activate menu completion if the widget + normally only lists completions, but menu completion can be + activated in that case with the value `yes=long-list' (Typically, + the value `select=long-list' described later is more useful as it + provides control over scrolling.) + + Similarly, with any of the `false' values (as in `no=10'), menu + completion will _not_ be used if there are NUM or more matches. + + The value of this widget also controls menu selection, as + implemented by the zsh/complist module. The following values may + appear either alongside or instead of the values above. + + If the value contains the string `select', menu selection will be + started unconditionally. + + In the form `select=NUM', menu selection will only be started if + there are at least NUM matches. If the values for more than one + tag provide a number, the smallest number is taken. + + Menu selection can be turned off explicitly by defining a value + containing the string`no-select'. + + It is also possible to start menu selection only if the list of + matches does not fit on the screen by using the value + `select=long'. To start menu selection even if the current widget + only performs listing, use the value `select=long-list'. + + To turn on menu completion or menu selection when there are a + certain number of matches _or_ the list of matches does not fit on + the screen, both of `yes=' and `select=' may be given twice, once + with a number and once with `long' or `long-list'. + + Finally, it is possible to activate two special modes of menu + selection. The word `interactive' in the value causes interactive + mode to be entered immediately when menu selection is started; see + *Note The zsh/complist Module:: for a description of interactive + mode. Including the string `search' does the same for incremental + search mode. To select backward incremental search, include the + string `search-backward'. + +muttrc + If set, gives the location of the mutt configuration file. It + defaults to `~/.muttrc'. + +numbers + This is used with the jobs tag. If it is `true', the shell will + complete job numbers instead of the shortest unambiguous prefix of + the job command text. If the value is a number, job numbers will + only be used if that many words from the job descriptions are + required to resolve ambiguities. For example, if the value is + `1', strings will only be used if all jobs differ in the first + word on their command lines. + +old-list + This is used by the _oldlist completer. If it is set to `always', + then standard widgets which perform listing will retain the + current list of matches, however they were generated; this can be + turned off explicitly with the value `never', giving the behaviour + without the _oldlist completer. If the style is unset, or any + other value, then the existing list of completions is displayed if + it is not already; otherwise, the standard completion list is + generated; this is the default behaviour of _oldlist. However, if + there is an old list and this style contains the name of the + completer function that generated the list, then the old list will + be used even if it was generated by a widget which does not do + listing. + + For example, suppose you type ^Xc to use the _correct_word widget, + which generates a list of corrections for the word under the + cursor. Usually, typing ^D would generate a standard list of + completions for the word on the command line, and show that. With + _oldlist, it will instead show the list of corrections already + generated. + + As another example consider the _match completer: with the + insert-unambiguous style set to `true' it inserts only a common + prefix string, if there is any. However, this may remove parts of + the original pattern, so that further completion could produce + more matches than on the first attempt. By using the _oldlist + completer and setting this style to _match, the list of matches + generated on the first attempt will be used again. + +old-matches + This is used by the _all_matches completer to decide if an old + list of matches should be used if one exists. This is selected by + one of the `true' values or by the string `only'. If the value is + `only', _all_matches will only use an old list and won't have any + effect on the list of matches currently being generated. + + If this style is set it is generally unwise to call the + _all_matches completer unconditionally. One possible use is for + either this style or the completer style to be defined with the -e + option to zstyle to make the style conditional. + +old-menu + This is used by the _oldlist completer. It controls how menu + completion behaves when a completion has already been inserted and + the user types a standard completion key such as TAB. The default + behaviour of _oldlist is that menu completion always continues + with the existing list of completions. If this style is set to + `false', however, a new completion is started if the old list was + generated by a different completion command; this is the behaviour + without the _oldlist completer. + + For example, suppose you type ^Xc to generate a list of + corrections, and menu completion is started in one of the usual + ways. Usually, or with this style set to `false', typing TAB at + this point would start trying to complete the line as it now + appears. With _oldlist, it instead continues to cycle through the + list of corrections. + +original + This is used by the _approximate and _correct completers to decide + if the original string should be added as a possible completion. + Normally, this is done only if there are at least two possible + corrections, but if this style is set to `true', it is always + added. Note that the style will be examined with the completer + field in the context name set to correct-NUM or approximate-NUM, + where NUM is the number of errors that were accepted. + +packageset + This style is used when completing arguments of the Debian `dpkg' + program. It contains an override for the default package set for + a given context. For example, + + + zstyle ':completion:*:complete:dpkg:option--status-1:*' \ + packageset avail + + causes available packages, rather than only installed packages, to + be completed for `dpkg --status'. + +path + The function that completes color names uses this style with the + colors tag. The value should be the pathname of a file containing + color names in the format of an X11 rgb.txt file. If the style is + not set but this file is found in one of various standard + locations it will be used as the default. + +path-completion + This is used by filename completion. By default, filename + completion examines all components of a path to see if there are + completions of that component. For example, /u/b/z can be + completed to /usr/bin/zsh. Explicitly setting this style to + `false' inhibits this behaviour for path components up to the / + before the cursor; this overrides the setting of accept-exact-dirs. + + Even with the style set to `false', it is still possible to + complete multiple paths by setting the option COMPLETE_IN_WORD and + moving the cursor back to the first component in the path to be + completed. For example, /u/b/z can be completed to /usr/bin/zsh + if the cursor is after the /u. + +pine-directory + If set, specifies the directory containing PINE mailbox files. + There is no default, since recursively searching this directory is + inconvenient for anyone who doesn't use PINE. + +ports + A list of Internet service names (network ports) to complete. If + this is not set, service names are taken from the file + `/etc/services'. + +prefix-hidden + This is used for certain completions which share a common prefix, + for example command options beginning with dashes. If it is + `true', the prefix will not be shown in the list of matches. + + The default value for this style is `false'. + +prefix-needed + This style is also relevant for matches with a common prefix. If + it is set to `true' this common prefix must be typed by the user + to generate the matches. + + The style is applicable to the options, signals, jobs, functions, + and parameters completion tags. + + For command options, this means that the initial `-', `+', or `--' + must be typed explicitly before option names will be completed. + + For signals, an initial `-' is required before signal names will + be completed. + + For jobs, an initial `%' is required before job names will be + completed. + + For function and parameter names, an initial `_' or `.' is + required before function or parameter names starting with those + characters will be completed. + + The default value for this style is `false' for function and + parameter completions, and `true' otherwise. + +preserve-prefix + This style is used when completing path names. Its value should + be a pattern matching an initial prefix of the word to complete + that should be left unchanged under all circumstances. For + example, on some Unices an initial `//' (double slash) has a + special meaning; setting this style to the string `//' will + preserve it. As another example, setting this style to `?:/' + under Cygwin would allow completion after `a:/...' and so on. + +range + This is used by the _history completer and the + _history_complete_word bindable command to decide which words + should be completed. + + If it is a single number, only the last N words from the history + will be completed. + + If it is a range of the form `MAX:SLICE', the last SLICE words + will be completed; then if that yields no matches, the SLICE words + before those will be tried and so on. This process stops either + when at least one match has been found, or MAX words have been + tried. + + The default is to complete all words from the history at once. + +recursive-files + If this style is set, its value is an array of patterns to be + tested against `$PWD/': note the trailing slash, which allows + directories in the pattern to be delimited unambiguously by + including slashes on both sides. If an ordinary file completion + fails and the word on the command line does not yet have a + directory part to its name, the style is retrieved using the same + tag as for the completion just attempted, then the elements tested + against $PWD/ in turn. If one matches, then the shell reattempts + completion by prepending the word on the command line with each + directory in the expansion of **/*(/) in turn. Typically the + elements of the style will be set to restrict the number of + directories beneath the current one to a manageable number, for + example `*/.git/*'. + + For example, + + + zstyle ':completion:*' recursive-files '*/zsh/*' + + If the current directory is /home/pws/zsh/Src, then zle_tr_TAB_ + can be completed to Zle/zle_tricky.c. + +regular + This style is used by the _expand_alias completer and bindable + command. If set to `true' (the default), regular aliases will be + expanded but only in command position. If it is set to `false', + regular aliases will never be expanded. If it is set to `always', + regular aliases will be expanded even if not in command position. + +rehash + If this is set when completing external commands, the internal + list (hash) of commands will be updated for each search by issuing + the rehash command. There is a speed penalty for this which is + only likely to be noticeable when directories in the path have + slow file access. + +remote-access + If set to `false', certain commands will be prevented from making + Internet connections to retrieve remote information. This + includes the completion for the CVS command. + + It is not always possible to know if connections are in fact to a + remote site, so some may be prevented unnecessarily. + +remove-all-dups + The _history_complete_word bindable command and the _history + completer use this to decide if all duplicate matches should be + removed, rather than just consecutive duplicates. + +select-prompt + If this is set for the default tag, its value will be displayed + during menu selection (see the menu style above) when the + completion list does not fit on the screen as a whole. The same + escapes as for the list-prompt style are understood, except that + the numbers refer to the match or line the mark is on. A default + prompt is used when the value is the empty string. + +select-scroll + This style is tested for the default tag and determines how a + completion list is scrolled during a menu selection (see the menu + style above) when the completion list does not fit on the screen + as a whole. If the value is `0' (zero), the list is scrolled by + half-screenfuls; if it is a positive integer, the list is scrolled + by the given number of lines; if it is a negative number, the list + is scrolled by a screenful minus the absolute value of the given + number of lines. The default is to scroll by single lines. + +separate-sections + This style is used with the manuals tag when completing names of + manual pages. If it is `true', entries for different sections are + added separately using tag names of the form `manual.X', where X + is the section number. When the group-name style is also in + effect, pages from different sections will appear separately. + This style is also used similarly with the words style when + completing words for the dict command. It allows words from + different dictionary databases to be added separately. The + default for this style is `false'. + +show-ambiguity + If the zsh/complist module is loaded, this style can be used to + highlight the first ambiguous character in completion lists. The + value is either a color indication such as those supported by the + list-colors style or, with a value of `true', a default of + underlining is selected. The highlighting is only applied if the + completion display strings correspond to the actual matches. + +show-completer + Tested whenever a new completer is tried. If it is `true', the + completion system outputs a progress message in the listing area + showing what completer is being tried. The message will be + overwritten by any output when completions are found and is + removed after completion is finished. + +single-ignored + This is used by the _ignored completer when there is only one + match. If its value is `show', the single match will be displayed + but not inserted. If the value is `menu', then the single match + and the original string are both added as matches and menu + completion is started, making it easy to select either of them. + +sort + This allows the standard ordering of matches to be overridden. + + If its value is `true' or `false', sorting is enabled or disabled. + Additionally the values associated with the `-o' option to compadd + can also be listed: match, nosort, numeric, reverse. If it is not + set for the context, the standard behaviour of the calling widget + is used. + + The style is tested first against the full context including the + tag, and if that fails to produce a value against the context + without the tag. + + In many cases where a calling widget explicitly selects a + particular ordering in lieu of the default, a value of `true' is + not honoured. An example of where this is not the case is for + command history where the default of sorting matches + chronologically may be overridden by setting the style to `true'. + + In the _expand completer, if it is set to `true', the expansions + generated will always be sorted. If it is set to `menu', then the + expansions are only sorted when they are offered as single strings + but not in the string containing all possible expansions. + +special-dirs + Normally, the completion code will not produce the directory names + `.' and `..' as possible completions. If this style is set to + `true', it will add both `.' and `..' as possible completions; if + it is set to `..', only `..' will be added. + + The following example sets special-dirs to `..' when the current + prefix is empty, is a single `.', or consists only of a path + beginning with `../'. Otherwise the value is `false'. + + + zstyle -e ':completion:*' special-dirs \ + '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)' + +squeeze-slashes + If set to `true', sequences of slashes in filename paths (for + example in `foo//bar') will be treated as a single slash. This is + the usual behaviour of UNIX paths. However, by default the file + completion function behaves as if there were a `*' between the + slashes. + +stop + If set to `true', the _history_complete_word bindable command will + stop once when reaching the beginning or end of the history. + Invoking _history_complete_word will then wrap around to the + opposite end of the history. If this style is set to `false' (the + default), _history_complete_word will loop immediately as in a + menu completion. + +strip-comments + If set to `true', this style causes non-essential comment text to + be removed from completion matches. Currently it is only used when + completing e-mail addresses where it removes any display name from + the addresses, cutting them down to plain USER@HOST form. + +subst-globs-only + This is used by the _expand completer. If it is set to `true', + the expansion will only be used if it resulted from globbing; + hence, if expansions resulted from the use of the substitute style + described below, but these were not further changed by globbing, + the expansions will be rejected. + + The default for this style is `false'. + +substitute + This boolean style controls whether the _expand completer will + first try to expand all substitutions in the string (such as + `$(...)' and `${...}'). + + The default is `true'. + +suffix + This is used by the _expand completer if the word starts with a + tilde or contains a parameter expansion. If it is set to `true', + the word will only be expanded if it doesn't have a suffix, i.e. + if it is something like `~foo' or `$foo' rather than `~foo/' or + `$foo/bar', unless that suffix itself contains characters eligible + for expansion. The default for this style is `true'. + +tag-order + This provides a mechanism for sorting how the tags available in a + particular context will be used. + + The values for the style are sets of space-separated lists of tags. + The tags in each value will be tried at the same time; if no match + is found, the next value is used. (See the file-patterns style for + an exception to this behavior.) + + For example: + + + zstyle ':completion:*:complete:-command-:*:*' tag-order \ + 'commands functions' + + specifies that completion in command position first offers + external commands and shell functions. Remaining tags will be + tried if no completions are found. + + In addition to tag names, each string in the value may take one of + the following forms: + + + - + If any value consists of only a hyphen, then _only_ the tags + specified in the other values are generated. Normally all + tags not explicitly selected are tried last if the specified + tags fail to generate any matches. This means that a single + value consisting only of a single hyphen turns off completion. + + ! TAGS... + A string starting with an exclamation mark specifies names of + tags that are _not_ to be used. The effect is the same as if + all other possible tags for the context had been listed. + + TAG:LABEL ... + Here, TAG is one of the standard tags and LABEL is an + arbitrary name. Matches are generated as normal but the name + LABEL is used in contexts instead of TAG. This is not useful + in words starting with !. + + If the LABEL starts with a hyphen, the TAG is prepended to the + LABEL to form the name used for lookup. This can be used to + make the completion system try a certain tag more than once, + supplying different style settings for each attempt; see + below for an example. + + TAG:LABEL:DESCRIPTION + As before, but description will replace the `%d' in the value + of the format style instead of the default description + supplied by the completion function. Spaces in the + description must be quoted with a backslash. A `%d' appearing + in DESCRIPTION is replaced with the description given by the + completion function. + + + In any of the forms above the tag may be a pattern or several + patterns in the form `{PAT1,PAT2...}'. In this case all matching + tags will be used except for any given explicitly in the same + string. + + One use of these features is to try one tag more than once, + setting other styles differently on each attempt, but still to use + all the other tags without having to repeat them all. For + example, to make completion of function names in command position + ignore all the completion functions starting with an underscore + the first time completion is tried: + + + zstyle ':completion:*:*:-command-:*:*' tag-order \ + 'functions:-non-comp *' functions + zstyle ':completion:*:functions-non-comp' \ + ignored-patterns '_*' + + On the first attempt, all tags will be offered but the functions + tag will be replaced by functions-non-comp. The ignored-patterns + style is set for this tag to exclude functions starting with an + underscore. If there are no matches, the second value of the + tag-order style is used which completes functions using the default + tag, this time presumably including all function names. + + The matches for one tag can be split into different groups. For + example: + + + zstyle ':completion:*' tag-order \ + 'options:-long:long\ options + options:-short:short\ options + options:-single-letter:single\ letter\ options' + zstyle ':completion:*:options-long' \ + ignored-patterns '[-+](|-|[^-]*)' + zstyle ':completion:*:options-short' \ + ignored-patterns '--*' '[-+]?' + zstyle ':completion:*:options-single-letter' \ + ignored-patterns '???*' + + With the group-names style set, options beginning with `--', + options beginning with a single `-' or `+' but containing multiple + characters, and single-letter options will be displayed in + separate groups with different descriptions. + + Another use of patterns is to try multiple match specifications + one after another. The matcher-list style offers something + similar, but it is tested very early in the completion system and + hence can't be set for single commands nor for more specific + contexts. Here is how to try normal completion without any match + specification and, if that generates no matches, try again with + case-insensitive matching, restricting the effect to arguments of + the command foo: + + + zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case' + zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}' + + First, all the tags offered when completing after foo are tried + using the normal tag name. If that generates no matches, the + second value of tag-order is used, which tries all tags again + except that this time each has -case appended to its name for + lookup of styles. Hence this time the value for the matcher style + from the second call to zstyle in the example is used to make + completion case-insensitive. + + It is possible to use the -e option of the zstyle builtin command + to specify conditions for the use of particular tags. For example: + + + zstyle -e '*:-command-:*' tag-order ' + if [[ -n $PREFIX$SUFFIX ]]; then + reply=( ) + else + reply=( - ) + fi' + + Completion in command position will be attempted only if the string + typed so far is not empty. This is tested using the PREFIX + special parameter; see *Note Completion Widgets:: for a + description of parameters which are special inside completion + widgets. Setting reply to an empty array provides the default + behaviour of trying all tags at once; setting it to an array + containing only a hyphen disables the use of all tags and hence of + all completions. + + If no tag-order style has been defined for a context, the strings + `(|*-)argument-* (|*-)option-* values' and `options' plus all tags + offered by the completion function will be used to provide a + sensible default behavior that causes arguments (whether normal + command arguments or arguments of options) to be completed before + option names for most commands. + +urls + This is used together with the urls tag by functions completing + URLs. + + If the value consists of more than one string, or if the only + string does not name a file or directory, the strings are used as + the URLs to complete. + + If the value contains only one string which is the name of a normal + file the URLs are taken from that file (where the URLs may be + separated by white space or newlines). + + Finally, if the only string in the value names a directory, the + directory hierarchy rooted at this directory gives the + completions. The top level directory should be the file access + method, such as `http', `ftp', `bookmark' and so on. In many + cases the next level of directories will be a filename. The + directory hierarchy can descend as deep as necessary. + + For example, + + + zstyle ':completion:*' urls ~/.urls + mkdir -p ~/.urls/ftp/ftp.zsh.org/pub + + allows completion of all the components of the URL + ftp://ftp.zsh.org/pub after suitable commands such as `netscape' + or `lynx'. Note, however, that access methods and files are + completed separately, so if the hosts style is set hosts can be + completed without reference to the urls style. + + See the description in the function _urls itself for more + information (e.g. `more $^fpath/_urls(N)'). + +use-cache + If this is set, the completion caching layer is activated for any + completions which use it (via the _store_cache, _retrieve_cache, + and _cache_invalid functions). The directory containing the cache + files can be changed with the cache-path style. + +use-compctl + If this style is set to a string _not_ equal to false, 0, no, and + off, the completion system may use any completion specifications + defined with the compctl builtin command. If the style is unset, + this is done only if the zsh/compctl module is loaded. The string + may also contain the substring `first' to use completions defined + with `compctl -T', and the substring `default' to use the + completion defined with `compctl -D'. + + Note that this is only intended to smooth the transition from + compctl to the new completion system and may disappear in the + future. + + Note also that the definitions from compctl will only be used if + there is no specific completion function for the command in + question. For example, if there is a function _foo to complete + arguments to the command foo, compctl will never be invoked for + foo. However, the compctl version will be tried if foo only uses + default completion. + +use-ip + By default, the function _hosts that completes host names strips + IP addresses from entries read from host databases such as NIS and + ssh files. If this style is `true', the corresponding IP addresses + can be completed as well. This style is not use in any context + where the hosts style is set; note also it must be set before the + cache of host names is generated (typically the first completion + attempt). + +users + This may be set to a list of usernames to be completed. If it is + not set all usernames will be completed. Note that if it is set + only that list of users will be completed; this is because on some + systems querying all users can take a prohibitive amount of time. + +users-hosts + The values of this style should be of the form `USER@HOST' or + `USER:HOST'. It is used for commands that need pairs of user- and + hostnames. These commands will complete usernames from this style + (only), and will restrict subsequent hostname completion to hosts + paired with that user in one of the values of the style. + + It is possible to group values for sets of commands which allow a + remote login, such as rlogin and ssh, by using the my-accounts tag. + Similarly, values for sets of commands which usually refer to the + accounts of other people, such as talk and finger, can be grouped + by using the other-accounts tag. More ambivalent commands may use + the accounts tag. + +users-hosts-ports + Like users-hosts but used for commands like telnet and containing + strings of the form `USER@HOST:PORT'. + +verbose + If set, as it is by default, the completion listing is more + verbose. In particular many commands show descriptions for + options if this style is `true'. + +word + This is used by the _list completer, which prevents the insertion + of completions until a second completion attempt when the line has + not changed. The normal way of finding out if the line has + changed is to compare its entire contents between the two + occasions. If this style is `true', the comparison is instead + performed only on the current word. Hence if completion is + performed on another word with the same contents, completion will + not be delayed. + + + + +File: zsh.info, Node: Control Functions, Next: Bindable Commands, Prev: Completion System Configuration, Up: Completion System + +20.4 Control Functions +====================== + + + +The initialization script compinit redefines all the widgets which +perform completion to call the supplied widget function _main_complete. +This function acts as a wrapper calling the so-called `completer' +functions that generate matches. If _main_complete is called with +arguments, these are taken as the names of completer functions to be +called in the order given. If no arguments are given, the set of +functions to try is taken from the completer style. For example, to +use normal completion and correction if that doesn't generate any +matches: + + + zstyle ':completion:*' completer _complete _correct + +after calling compinit. The default value for this style is `_complete +_ignored', i.e. normally only ordinary completion is tried, first with +the effect of the ignored-patterns style and then without it. The +_main_complete function uses the return status of the completer +functions to decide if other completers should be called. If the return +status is zero, no other completers are tried and the _main_complete +function returns. + +If the first argument to _main_complete is a single hyphen, the +arguments will not be taken as names of completers. Instead, the +second argument gives a name to use in the COMPLETER field of the +context and the other arguments give a command name and arguments to +call to generate the matches. + +The following completer functions are contained in the distribution, +although users may write their own. Note that in contexts the leading +underscore is stripped, for example basic completion is performed in the +context `:completion::complete:...'. + + +_all_matches + This completer can be used to add a string consisting of all other + matches. As it influences later completers it must appear as the + first completer in the list. The list of all matches is affected + by the avoid-completer and old-matches styles described above. + + It may be useful to use the _generic function described below to + bind _all_matches to its own keystroke, for example: + + + zle -C all-matches complete-word _generic + bindkey '^Xa' all-matches + zstyle ':completion:all-matches:*' old-matches only + zstyle ':completion:all-matches::::' completer _all_matches + + Note that this does not generate completions by itself: first use + any of the standard ways of generating a list of completions, then + use ^Xa to show all matches. It is possible instead to add a + standard completer to the list and request that the list of all + matches should be directly inserted: + + + zstyle ':completion:all-matches::::' completer \ + _all_matches _complete + zstyle ':completion:all-matches:*' insert true + + In this case the old-matches style should not be set. + +_approximate + This is similar to the basic _complete completer but allows the + completions to undergo corrections. The maximum number of errors + can be specified by the max-errors style; see the description of + approximate matching in *Note Filename Generation:: for how errors + are counted. Normally this completer will only be tried after the + normal _complete completer: + + + zstyle ':completion:*' completer _complete _approximate + + This will give correcting completion if and only if normal + completion yields no possible completions. When corrected + completions are found, the completer will normally start menu + completion allowing you to cycle through these strings. + + This completer uses the tags corrections and original when + generating the possible corrections and the original string. The + format style for the former may contain the additional sequences + `%e' and `%o' which will be replaced by the number of errors + accepted to generate the corrections and the original string, + respectively. + + The completer progressively increases the number of errors allowed + up to the limit by the max-errors style, hence if a completion is + found with one error, no completions with two errors will be + shown, and so on. It modifies the completer name in the context + to indicate the number of errors being tried: on the first try the + completer field contains `approximate-1', on the second try + `approximate-2', and so on. + + When _approximate is called from another function, the number of + errors to accept may be passed with the -a option. The argument + is in the same format as the max-errors style, all in one string. + + Note that this completer (and the _correct completer mentioned + below) can be quite expensive to call, especially when a large + number of errors are allowed. One way to avoid this is to set up + the completer style using the -e option to zstyle so that some + completers are only used when completion is attempted a second + time on the same string, e.g.: + + + zstyle -e ':completion:*' completer ' + if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then + _last_try="$HISTNO$BUFFER$CURSOR" + reply=(_complete _match _prefix) + else + reply=(_ignored _correct _approximate) + fi' + + This uses the HISTNO parameter and the BUFFER and CURSOR special + parameters that are available inside zle and completion widgets to + find out if the command line hasn't changed since the last time + completion was tried. Only then are the _ignored, _correct and + _approximate completers called. + +_canonical_paths [ -A VAR ] [ -N ] [ -MJV12nfX ] TAG DESCR [ PATHS ... ] + This completion function completes all paths given to it, and also + tries to offer completions which point to the same file as one of + the paths given (relative path when an absolute path is given, and + vice versa; when ..'s are present in the word to be completed; and + some paths got from symlinks). + + -A, if specified, takes the paths from the array variable + specified. Paths can also be specified on the command line as + shown above. -N, if specified, prevents canonicalizing the paths + given before using them for completion, in case they are already + so. The options -M, -J, -V, -1, -2, -n, -F, -X are passed to + compadd. + + See _description for a description of TAG and DESCR. + +_cmdambivalent + Completes the remaining positional arguments as an external + command. The external command and its arguments are completed as + separate arguments (in a manner appropriate for completing + /usr/bin/env) if there are two or more remaining positional + arguments on the command line, and as a quoted command string (in + the manner of system(...)) otherwise. See also _cmdstring and + _precommand. + + This function takes no arguments. + +_cmdstring + Completes an external command as a single argument, as for + system(...). + +_complete + This completer generates all possible completions in a + context-sensitive manner, i.e. using the settings defined with the + compdef function explained above and the current settings of all + special parameters. This gives the normal completion behaviour. + + To complete arguments of commands, _complete uses the utility + function _normal, which is in turn responsible for finding the + particular function; it is described below. Various contexts of + the form -CONTEXT- are handled specifically. These are all + mentioned above as possible arguments to the #compdef tag. + + Before trying to find a function for a specific context, _complete + checks if the parameter `compcontext' is set. Setting + `compcontext' allows the usual completion dispatching to be + overridden which is useful in places such as a function that uses + vared for input. If it is set to an array, the elements are taken + to be the possible matches which will be completed using the tag + `values' and the description `value'. If it is set to an + associative array, the keys are used as the possible completions + and the values (if non-empty) are used as descriptions for the + matches. If `compcontext' is set to a string containing colons, + it should be of the form `TAG:DESCR:ACTION'. In this case the TAG + and DESCR give the tag and description to use and the ACTION + indicates what should be completed in one of the forms accepted by + the _arguments utility function described below. + + Finally, if `compcontext' is set to a string without colons, the + value is taken as the name of the context to use and the function + defined for that context will be called. For this purpose, there + is a special context named -command-line- that completes whole + command lines (commands and their arguments). This is not used by + the completion system itself but is nonetheless handled when + explicitly called. + +_correct + Generate corrections, but not completions, for the current word; + this is similar to _approximate but will not allow any number of + extra characters at the cursor as that completer does. The effect + is similar to spell-checking. It is based on _approximate, but the + completer field in the context name is correct. + + For example, with: + + + zstyle ':completion:::::' completer \ + _complete _correct _approximate + zstyle ':completion:*:correct:::' max-errors 2 not-numeric + zstyle ':completion:*:approximate:::' max-errors 3 numeric + + correction will accept up to two errors. If a numeric argument is + given, correction will not be performed, but correcting completion + will be, and will accept as many errors as given by the numeric + argument. Without a numeric argument, first correction and then + correcting completion will be tried, with the first one accepting + two errors and the second one accepting three errors. + + When _correct is called as a function, the number of errors to + accept may be given following the -a option. The argument is in + the same form a values to the accept style, all in one string. + + This completer function is intended to be used without the + _approximate completer or, as in the example, just before it. + Using it after the _approximate completer is useless since + _approximate will at least generate the corrected strings + generated by the _correct completer -- and probably more. + +_expand + This completer function does not really perform completion, but + instead checks if the word on the command line is eligible for + expansion and, if it is, gives detailed control over how this + expansion is done. For this to happen, the completion system + needs to be invoked with complete-word, not expand-or-complete + (the default binding for TAB), as otherwise the string will be + expanded by the shell's internal mechanism before the completion + system is started. Note also this completer should be called + before the _complete completer function. + + The tags used when generating expansions are all-expansions for the + string containing all possible expansions, expansions when adding + the possible expansions as single matches and original when adding + the original string from the line. The order in which these + strings are generated, if at all, can be controlled by the + group-order and tag-order styles, as usual. + + The format string for all-expansions and for expansions may + contain the sequence `%o' which will be replaced by the original + string from the line. + + The kind of expansion to be tried is controlled by the substitute, + glob and subst-globs-only styles. + + It is also possible to call _expand as a function, in which case + the different modes may be selected with options: -s for + substitute, -g for glob and -o for subst-globs-only. + +_expand_alias + If the word the cursor is on is an alias, it is expanded and no + other completers are called. The types of aliases which are to be + expanded can be controlled with the styles regular, global and + disabled. + + This function is also a bindable command, see *Note Bindable + Commands::. + +_extensions + If the cursor follows the string `*.', filename extensions are + completed. The extensions are taken from files in current + directory or a directory specified at the beginning of the current + word. For exact matches, completion continues to allow other + completers such as _expand to expand the pattern. The standard + add-space and prefix-hidden styles are observed. + +_external_pwds + Completes current directories of other zsh processes belonging to + the current user. + + This is intended to be used via _generic, bound to a custom key + combination. Note that pattern matching is enabled so matching is + performed similar to how it works with the _match completer. + +_history + Complete words from the shell's command history. This completer + can be controlled by the remove-all-dups, and sort styles as for + the _history_complete_word bindable command, see *Note Bindable + Commands:: and *Note Completion System Configuration::. + +_ignored + The ignored-patterns style can be set to a list of patterns which + are compared against possible completions; matching ones are + removed. With this completer those matches can be reinstated, as + if no ignored-patterns style were set. The completer actually + generates its own list of matches; which completers are invoked is + determined in the same way as for the _prefix completer. The + single-ignored style is also available as described above. + +_list + This completer allows the insertion of matches to be delayed until + completion is attempted a second time without the word on the line + being changed. On the first attempt, only the list of matches + will be shown. It is affected by the styles condition and word, + see *Note Completion System Configuration::. + +_match + This completer is intended to be used after the _complete + completer. It behaves similarly but the string on the command + line may be a pattern to match against trial completions. This + gives the effect of the GLOB_COMPLETE option. + + Normally completion will be performed by taking the pattern from + the line, inserting a `*' at the cursor position and comparing the + resulting pattern with the possible completions generated. This + can be modified with the match-original style described above. + + The generated matches will be offered in a menu completion unless + the insert-unambiguous style is set to `true'; see the description + above for other options for this style. + + Note that matcher specifications defined globally or used by the + completion functions (the styles matcher-list and matcher) will + not be used. + +_menu + This completer was written as simple example function to show how + menu completion can be enabled in shell code. However, it has the + notable effect of disabling menu selection which can be useful with + _generic based widgets. It should be used as the first completer in + the list. Note that this is independent of the setting of the + MENU_COMPLETE option and does not work with the other menu + completion widgets such as reverse-menu-complete, or + accept-and-menu-complete. + +_oldlist + This completer controls how the standard completion widgets behave + when there is an existing list of completions which may have been + generated by a special completion (i.e. a separately-bound + completion command). It allows the ordinary completion keys to + continue to use the list of completions thus generated, instead of + producing a new list of ordinary contextual completions. It + should appear in the list of completers before any of the widgets + which generate matches. It uses two styles: old-list and + old-menu, see *Note Completion System Configuration::. + +_precommand + Complete an external command in word-separated arguments, as for + exec and /usr/bin/env. + +_prefix + This completer can be used to try completion with the suffix + (everything after the cursor) ignored. In other words, the suffix + will not be considered to be part of the word to complete. The + effect is similar to the expand-or-complete-prefix command. + + The completer style is used to decide which other completers are to + be called to generate matches. If this style is unset, the list of + completers set for the current context is used -- except, of + course, the _prefix completer itself. Furthermore, if this + completer appears more than once in the list of completers only + those completers not already tried by the last invocation of + _prefix will be called. + + For example, consider this global completer style: + + + zstyle ':completion:*' completer \ + _complete _prefix _correct _prefix:foo + + Here, the _prefix completer tries normal completion but ignoring + the suffix. If that doesn't generate any matches, and neither does + the call to the _correct completer after it, _prefix will be + called a second time and, now only trying correction with the + suffix ignored. On the second invocation the completer part of the + context appears as `foo'. + + To use _prefix as the last resort and try only normal completion + when it is invoked: + + + zstyle ':completion:*' completer _complete ... _prefix + zstyle ':completion::prefix:*' completer _complete + + The add-space style is also respected. If it is set to `true' then + _prefix will insert a space between the matches generated (if any) + and the suffix. + + Note that this completer is only useful if the COMPLETE_IN_WORD + option is set; otherwise, the cursor will be moved to the end of + the current word before the completion code is called and hence + there will be no suffix. + +_user_expand + This completer behaves similarly to the _expand completer but + instead performs expansions defined by users. The styles + add-space and sort styles specific to the _expand completer are + usable with _user_expand in addition to other styles handled more + generally by the completion system. The tag all-expansions is + also available. + + The expansion depends on the array style user-expand being defined + for the current context; remember that the context for completers + is less specific than that for contextual completion as the full + context has not yet been determined. Elements of the array may + have one of the following forms: + + + $HASH + HASH is the name of an associative array. Note this is not a + full parameter expression, merely a $, suitably quoted to + prevent immediate expansion, followed by the name of an + associative array. If the trial expansion word matches a key + in HASH, the resulting expansion is the corresponding value. + + _FUNC + _FUNC is the name of a shell function whose name must begin + with _ but is not otherwise special to the completion system. + The function is called with the trial word as an argument. + If the word is to be expanded, the function should set the + array reply to a list of expansions. Optionally, it can set + REPLY to a word that will be used as a description for the + set of expansions. The return status of the function is + irrelevant. + + + + + +File: zsh.info, Node: Bindable Commands, Next: Completion Functions, Prev: Control Functions, Up: Completion System + +20.5 Bindable Commands +====================== + + + +In addition to the context-dependent completions provided, which are +expected to work in an intuitively obvious way, there are a few widgets +implementing special behaviour which can be bound separately to keys. +The following is a list of these and their default bindings. + + +_bash_completions + This function is used by two widgets, _bash_complete-word and + _bash_list-choices. It exists to provide compatibility with + completion bindings in bash. The last character of the binding + determines what is completed: `!', command names; `$', environment + variables; `@', host names; `/', file names; `~' user names. In + bash, the binding preceded by `\e' gives completion, and preceded + by `^X' lists options. As some of these bindings clash with + standard zsh bindings, only `\e~' and `^X~' are bound by default. + To add the rest, the following should be added to .zshrc after + compinit has been run: + + + for key in '!' '$' '@' '/' '~'; do + bindkey "\e$key" _bash_complete-word + bindkey "^X$key" _bash_list-choices + done + + This includes the bindings for `~' in case they were already bound + to something else; the completion code does not override user + bindings. + +_correct_filename (^XC) + Correct the filename path at the cursor position. Allows up to + six errors in the name. Can also be called with an argument to + correct a filename path, independently of zle; the correction is + printed on standard output. + +_correct_word (^Xc) + Performs correction of the current argument using the usual + contextual completions as possible choices. This stores the string + `correct-word' in the FUNCTION field of the context name and then + calls the _correct completer. + +_expand_alias (^Xa) + This function can be used as a completer and as a bindable command. + It expands the word the cursor is on if it is an alias. The types + of alias expanded can be controlled with the styles regular, global + and disabled. + + When used as a bindable command there is one additional feature + that can be selected by setting the complete style to `true'. In + this case, if the word is not the name of an alias, _expand_alias + tries to complete the word to a full alias name without expanding + it. It leaves the cursor directly after the completed word so + that invoking _expand_alias once more will expand the now-complete + alias name. + +_expand_word (^Xe) + Performs expansion on the current word: equivalent to the standard + expand-word command, but using the _expand completer. Before + calling it, the FUNCTION field of the context is set to + `expand-word'. + +_generic + This function is not defined as a widget and not bound by default. + However, it can be used to define a widget and will then store + the name of the widget in the FUNCTION field of the context and + call the completion system. This allows custom completion widgets + with their own set of style settings to be defined easily. For + example, to define a widget that performs normal completion and + starts menu selection: + + + zle -C foo complete-word _generic + bindkey '...' foo + zstyle ':completion:foo:*' menu yes select=1 + + Note in particular that the completer style may be set for the + context in order to change the set of functions used to generate + possible matches. If _generic is called with arguments, those are + passed through to _main_complete as the list of completers in + place of those defined by the completer style. + +_history_complete_word (\e/) + Complete words from the shell's command history. This uses the + list, remove-all-dups, sort, and stop styles. + +_most_recent_file (^Xm) + Complete the name of the most recently modified file matching the + pattern on the command line (which may be blank). If given a + numeric argument N, complete the Nth most recently modified file. + Note the completion, if any, is always unique. + +_next_tags (^Xn) + This command alters the set of matches used to that for the next + tag, or set of tags, either as given by the tag-order style or as + set by default; these matches would otherwise not be available. + Successive invocations of the command cycle through all possible + sets of tags. + +_read_comp (^X^R) + Prompt the user for a string, and use that to perform completion + on the current word. There are two possibilities for the string. + First, it can be a set of words beginning `_', for example `_files + -/', in which case the function with any arguments will be called + to generate the completions. Unambiguous parts of the function + name will be completed automatically (normal completion is not + available at this point) until a space is typed. + + Second, any other string will be passed as a set of arguments to + compadd and should hence be an expression specifying what should + be completed. + + A very restricted set of editing commands is available when + reading the string: `DEL' and `^H' delete the last character; + `^U' deletes the line, and `^C' and `^G' abort the function, while + `RET' accepts the completion. Note the string is used verbatim as + a command line, so arguments must be quoted in accordance with + standard shell rules. + + Once a string has been read, the next call to _read_comp will use + the existing string instead of reading a new one. To force a new + string to be read, call _read_comp with a numeric argument. + +_complete_debug (^X?) + This widget performs ordinary completion, but captures in a + temporary file a trace of the shell commands executed by the + completion system. Each completion attempt gets its own file. A + command to view each of these files is pushed onto the editor + buffer stack. + +_complete_help (^Xh) + This widget displays information about the context names, the + tags, and the completion functions used when completing at the + current cursor position. If given a numeric argument other than 1 + (as in `ESC-2 ^Xh'), then the styles used and the contexts for + which they are used will be shown, too. + + Note that the information about styles may be incomplete; it + depends on the information available from the completion functions + called, which in turn is determined by the user's own styles and + other settings. + +_complete_help_generic + Unlike other commands listed here, this must be created as a + normal ZLE widget rather than a completion widget (i.e. with zle + -N). It is used for generating help with a widget bound to the + _generic widget that is described above. + + If this widget is created using the name of the function, as it is + by default, then when executed it will read a key sequence. This + is expected to be bound to a call to a completion function that + uses the _generic widget. That widget will be executed, and + information provided in the same format that the _complete_help + widget displays for contextual completion. + + If the widget's name contains debug, for example if it is created + as `zle -N _complete_debug_generic _complete_help_generic', it + will read and execute the keystring for a generic widget as before, + but then generate debugging information as done by _complete_debug + for contextual completion. + + If the widget's name contains noread, it will not read a keystring + but instead arrange that the next use of a generic widget run in + the same shell will have the effect as described above. + + The widget works by setting the shell parameter + ZSH_TRACE_GENERIC_WIDGET which is read by _generic. Unsetting the + parameter cancels any pending effect of the noread form. + + For example, after executing the following: + + + zle -N _complete_debug_generic _complete_help_generic + bindkey '^x:' _complete_debug_generic + + typing `C-x :' followed by the key sequence for a generic widget + will cause trace output for that widget to be saved to a file. + +_complete_tag (^Xt) + This widget completes symbol tags created by the etags or ctags + programmes (note there is no connection with the completion + system's tags) stored in a file TAGS, in the format used by etags, + or tags, in the format created by ctags. It will look back up the + path hierarchy for the first occurrence of either file; if both + exist, the file TAGS is preferred. You can specify the full path + to a TAGS or tags file by setting the parameter $TAGSFILE or + $tagsfile respectively. The corresponding completion tags used + are etags and vtags, after emacs and vi respectively. + + + |