From 3052985d1fe4939ba571e942b9ff76ea9f59593a Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Wed, 28 Mar 2001 14:39:57 +0000 Subject: move ZLE builtin documentation from mod_zle.yo to zle.yo. --- Doc/Zsh/mod_zle.yo | 338 ----------------------------------------------------- 1 file changed, 338 deletions(-) (limited to 'Doc/Zsh/mod_zle.yo') diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo index cc6080b3d..162beb4bf 100644 --- a/Doc/Zsh/mod_zle.yo +++ b/Doc/Zsh/mod_zle.yo @@ -4,342 +4,4 @@ The Zsh Line Editor, including the tt(bindkey) and tt(vared) builtins. The tt(zsh/zle) module contains the Zsh Line Editor. See ifzman(zmanref(zshzle))\ ifnzman(noderef(Zsh Line Editor))\ -. It also contains three related builtin commands: - -startitem() -findex(bindkey) -cindex(keys, rebinding) -cindex(rebinding keys) -cindex(keys, binding) -cindex(binding keys) -cindex(keymaps) -xitem(tt(bindkey) [ var(options) ] tt(-l)) -xitem(tt(bindkey) [ var(options) ] tt(-d)) -xitem(tt(bindkey) [ var(options) ] tt(-D) var(keymap) ...) -xitem(tt(bindkey) [ var(options) ] tt(-A) var(old-keymap new-keymap)) -xitem(tt(bindkey) [ var(options) ] tt(-N) var(new-keymap) [ var(old-keymap) ]) -xitem(tt(bindkey) [ var(options) ] tt(-m)) -xitem(tt(bindkey) [ var(options) ] tt(-r) var(in-string) ...) -xitem(tt(bindkey) [ var(options) ] tt(-s) var(in-string out-string) ...) -xitem(tt(bindkey) [ var(options) ] var(in-string command) ...) -item(tt(bindkey) [ var(options) ] [ var(in-string) ])( -tt(bindkey)'s options can be divided into three categories: keymap selection, -operation selection, and others. The keymap selection options are: - -startitem() -item(tt(-e))( -Selects keymap `tt(emacs)', and also links it to `tt(main)'. -) -item(tt(-v))( -Selects keymap `tt(viins)', and also links it to `tt(main)'. -) -item(tt(-a))( -Selects keymap `tt(vicmd)'. -) -item(tt(-M))( -The first non-option argument is used as a keymap name, -and does not otherwise count as an argument. -) -enditem() - -If a keymap selection is required and none of the options above are used, the -`tt(main)' keymap is used. Some operations do not permit a keymap to be -selected, namely: - -startitem() -item(tt(-l))( -List all existing keymap names. If the tt(-L) -option is also used, list in the form of tt(bindkey) -commands to create the keymaps. -) -item(tt(-d))( -Delete all existing keymaps and reset to the default state. -) -item(tt(-D) var(keymap) ...)( -Delete the named var(keymap)s. -) -item(tt(-A) var(old-keymap new-keymap))( -Make the var(new-keymap) name an alias for var(old-keymap), so that -both names refer to the same keymap. The names have equal standing; -if either is deleted, the other remains. If there is already a keymap -with the var(new-keymap) name, it is deleted. -) -item(tt(-N) var(new-keymap) [ var(old-keymap) ])( -Create a new keymap, named var(new-keymap). If a keymap already has that -name, it is deleted. If an var(old-keymap) name is given, the new keymap -is initialized to be a duplicate of it, otherwise the new keymap will -be empty. -) -enditem() - -To use a newly created keymap, it should be linked to tt(main). Hence -the sequence of commands to create and use a new keymap `tt(mymap)' -initialized from the tt(emacs) keymap (which remains unchanged) is: - -example(bindkey -N mymap emacs -bindkey -A mymap main) - -Note that while `tt(bindkey -A) var(newmap) tt(main)' will work when -var(newmap) is tt(emacs) or tt(viins), it will not work for tt(vicmd), as -switching from vi insert to command mode becomes impossible. - -The following operations act on the `tt(main)' keymap if no keymap -selection option was given: - -startitem() -item(tt(-m))( -Add the built-in set of meta-key bindings to the selected keymap. -Only keys that are unbound or bound to tt(self-insert) are affected. -) -item(tt(-r) var(in-string) ...)( -Unbind the specified var(in-string)s in the selected keymap. -This is exactly equivalent to binding the strings to tt(undefined-key). -When tt(-R) is also used, interpret the var(in-string)s as ranges. -) -item(tt(-s) var(in-string out-string) ...)( -Bind each var(in-string) to each var(out-string). -When var(in-string) is typed, var(out-string) will be -pushed back and treated as input to the line editor. -When tt(-R) is also used, interpret the var(in-string)s as ranges. -) -item(var(in-string command) ...)( -Bind each var(in-string) to each var(command). -When tt(-R) is used, interpret the var(in-string)s as ranges. -) -item([ var(in-string) ])( -List key bindings. If an var(in-string) is specified, the binding of -that string in the selected keymap is displayed. Otherwise, all key -bindings in the selected keymap are displayed. (As a special case, -if the tt(-e) or tt(-v) option is used alone, the keymap is em(not) -displayed - the implicit linking of keymaps is the only thing that -happens.) - -When the tt(-L) option is used, the list is in the form of tt(bindkey) -commands to create the key bindings. -) -enditem() - -When the tt(-R) option is used as noted above, a valid range consists of -two characters, with an optional `tt(-)' between them. All characters -between the two specified, inclusive, are bound as specified. - -For either var(in-string) or var(out-string), the following -escape sequences are recognised: - -startsitem() -sitem(tt(\a))(bell character) -sitem(tt(\b))(backspace) -sitem(tt(\e), tt(\E))(escape) -sitem(tt(\f))(form feed) -sitem(tt(\n))(linefeed (newline)) -sitem(tt(\r))(carriage return) -sitem(tt(\t))(horizontal tab) -sitem(tt(\v))(vertical tab) -sitem(tt(\)var(NNN))(character code in octal) -sitem(tt(\x)var(NN))(character code in hexadecimal) -sitem(tt(\M)[tt(-)]var(X))(character with meta bit set) -sitem(tt(\C)[tt(-)]var(X))(control character) -sitem(tt(^)var(X))(control character) -endsitem() - -In all other cases, `tt(\)' escapes the following character. Delete is -written as `tt(^?)'. Note that `tt(\M^?)' and `tt(^\M?)' are not the same, -and that (unlike emacs), the bindings `tt(\M-)var(X)' and `tt(\e)var(X)' -are entirely distinct, although they are initialized to the same bindings -by `tt(bindkey -m)'. -) -findex(vared) -cindex(parameters, editing) -cindex(editing parameters) -item(tt(vared) [ tt(-Aache) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))( -The value of the parameter var(name) is loaded into the edit -buffer, and the line editor is invoked. When the editor exits, -var(name) is set to the string value returned by the editor. -When the tt(-c) flag is given, the parameter is created if it doesn't -already exist. The tt(-a) flag may be given with tt(-c) to create -an array parameter, or the tt(-A) flag to create an associative array. -If the type of an existing parameter does not match the type to be -created, the parameter is unset and recreated. - -If an array or array slice is being edited, separator characters as defined -in tt($IFS) will be shown quoted with a backslash, as will backslashes -themselves. Conversely, when the edited text is split into an array, a -backslash quotes an immediately following separator character or backslash; -no other special handling of backslashes, or any handling of quotes, is -performed. - -Individual elements of existing array or associative array parameters -may be edited by using subscript syntax on var(name). New elements are -created automatically, even without tt(-c). - -If the tt(-p) flag is given, the following string will be taken as -the prompt to display at the left. If the tt(-r) flag is given, -the following string gives the prompt to display at the right. If the -tt(-h) flag is specified, the history can be accessed from ZLE. If the -tt(-e) flag is given, typing tt(^D) (Control-D) on an empty line -causes tt(vared) to exit immediately with a non-zero return value. -) -findex(zle) -cindex(widgets, rebinding) -cindex(rebinding widgets) -cindex(widgets, binding) -cindex(binding widgets) -cindex(widgets, invoking) -cindex(invoking widgets) -cindex(widgets, calling) -cindex(calling widgets) -cindex(widgets, defining) -cindex(defining widgets) -xitem(tt(zle) tt(-l) [ tt(-L) | tt(-a) ] [ var(string) ... ]) -xitem(tt(zle) tt(-D) var(widget) ...) -xitem(tt(zle) tt(-A) var(old-widget) var(new-widget)) -xitem(tt(zle) tt(-N) var(widget) [ var(function) ]) -xitem(tt(zle) tt(-C) var(widget) var(completion-widget) var(function)) -xitem(tt(zle) tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ]) -xitem(tt(zle) tt(-M) var(string)) -xitem(tt(zle) tt(-U) var(string)) -xitem(tt(zle) tt(-I)) -xitem(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...) -item(tt(zle))( -The tt(zle) builtin performs a number of different actions concerning -ZLE. Which operation it performs depends on its options: - -startitem() -item(tt(-l) [ tt(-L) | tt(-a) ])( -List all existing user-defined widgets. If the tt(-L) -option is used, list in the form of tt(zle) -commands to create the widgets. - -When combined with the tt(-a) option, all widget names are listed, -including the builtin ones. In this case the tt(-L) option is ignored. - -If at least one var(string) is given, nothing will be printed but the -return status will be zero if all var(string)s are names of existing -widgets (or of user-defined widgets if the tt(-a) flag is not given) -and non-zero if at least one var(string) is not a name of an defined -widget. -) -item(tt(-D) var(widget) ...)( -Delete the named var(widget)s. -) -item(tt(-A) var(old-widget) var(new-widget))( -Make the var(new-widget) name an alias for var(old-widget), so that -both names refer to the same widget. The names have equal standing; -if either is deleted, the other remains. If there is already a widget -with the var(new-widget) name, it is deleted. -) -item(tt(-N) var(widget) [ var(function) ])( -Create a user-defined widget. If there is already a widget with the -specified name, it is overwritten. When the new -widget is invoked from within the editor, the specified shell var(function) -is called. If no function name is specified, it defaults to -the same name as the widget. For further information, see the section -em(Widgets) in -ifzman(zmanref(zshzle))\ -ifnzman(noderef(Zsh Line Editor))\ -. -) -cindex(completion widgets, creating) -item(tt(-C) var(widget) var(completion-widget) var(function))( -Create a user-defined completion widget named var(widget). The -completion widget will behave like the built-in completion-widget -whose name is given as var(completion-widget). To generate the -completions, the shell function var(function) will be called. -For further information, see -ifzman(zmanref(zshcompwid))\ -ifnzman(noderef(Completion Widgets))\ . -) -item(tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ])( -Redisplay the command line; this is to be called from within a user-defined -widget to allow changes to become visible. If a var(display-string) is -given and not empty, this is shown in the status line (immediately -below the line being edited). - -If the optional var(string)s are given they are listed below the -prompt in the same way as completion lists are printed. If no -var(string)s are given but the tt(-c) option is used such a list is -cleared. - -Note that this option is only useful for widgets that do not exit -immediately after using it because the strings displayed will be erased -immediately after return from the widget. - -This command can safely be called outside user defined widgets; if zle is -active, the display will be refreshed, while if zle is not active, the -command has no effect. In this case there will usually be no other -arguments. The status is zero if zle was active, else one. -) -item(tt(-M) var(string))( -As with the tt(-R) option, the var(string) will be displayed below the -command line; unlike the tt(-R) option, the string will not be put into -the status line but will instead be printed normally below the -prompt. This means that the var(string) will still be displayed after -the widget returns (until it is overwritten by subsequent commands). -) -item(tt(-U) var(string))( -This pushes the characters in the var(string) onto the input stack of -ZLE. After the widget currently executed finishes ZLE will behave as -if the characters in the var(string) were typed by the user. - -As ZLE uses a stack, if this option is used repeatedly -the last string pushed onto the stack will be processed first. However, -the characters in each var(string) will be processed in the order in which -they appear in the string. -) -item(tt(-I))( -Unusually, this option is only useful em(outside) ordinary widget functions. -It invalidates the current zle display in preparation for output; usually -this will be from a trap function. It has no effect if zle is not -active. When a trap exits, the shell checks to see if the display needs -restoring, hence the following will print output in such a way as not to -disturb the line being edited: - -example(TRAPUSR1() { - # Invalidate zle display - zle -I - # Show output - print Hello -}) - -Note that there are better ways of manipulating the display from within zle -widgets. In general, the trap function may need to test whether zle is -loaded before using this method; if it is not, there is no point in loading -it specially since the line editor will not be active. - -The status is zero if zle was active, else one. -) -item(var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...)( -Invoke the specified widget. This can only be done when ZLE is -active; normally this will be within a user-defined widget. - -With the options tt(-n) and tt(-N), the current numerical argument will be -saved and then restored after the call to tt(widget); `tt(-n) var(num)' -sets the numerical argument temporarily to var(num), while `tt(-N)' sets it -to the default, i.e. as if there were none. - -Any further arguments will be passed to the widget. If it is a shell -function, these are passed down as positional parameters; for builtin -widgets it is up to the widget in question what it does with them. -Currently arguments are only handled by the incremental-search commands, -the tt(history-search-forward) and tt(-backward) and the corresponding -functions prefixed by tt(vi-), and by tt(universal-argument). No error is -flagged if the command does not use the arguments, or only uses some of -them. - -The return status reflects the success or failure of the operation carried -out by the widget, or if it is a user-defined widget the return status of -the shell function. - -A non-zero return status causes the shell to beep when the widget exits, -unless the tt(BEEP) options was unset or the widget was called via the -tt(zle) command. Thus if a user defined widget requires an immediate beep, -it should call the tt(beep) widget directly. -) -enditem() - -With no options and no arguments, only the return status will be -set. It is zero if ZLE is currently active and widgets could be -invoked using this builtin command and non-zero if ZLE is not active. -) -enditem() -- cgit 1.4.1