From 8e2ec4517fcce11475d579abb827d851f858d9aa Mon Sep 17 00:00:00 2001 From: "Barton E. Schaefer" Date: Sun, 12 Jun 2016 18:50:10 -0700 Subject: 38670: New function for managing ZLE special widgets, modeled after Functions/Misc/add-zsh-hook. --- Doc/Zsh/contrib.yo | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) (limited to 'Doc/Zsh/contrib.yo') diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 923bb29a9..dd643a140 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -292,11 +292,11 @@ cindex(hook function utility) startitem() findex(add-zsh-hook) -item(tt(add-zsh-hook) [ tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))( +item(tt(add-zsh-hook) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(function))( Several functions are special to the shell, as described in the section ifnzman(Special Functions, noderef(Functions))\ ifzman(SPECIAL FUNCTIONS, see zmanref(zshmisc)), -in that they are automatic called at a specific point during shell execution. +in that they are automatically called at specific points during shell execution. Each has an associated array consisting of names of functions to be called at the same point; these are so-called `hook functions'. The shell function tt(add-zsh-hook) provides a simple way of adding or @@ -312,6 +312,9 @@ var(function) is name of an ordinary shell function. If no options are given this will be added to the array of functions to be executed in the given context. +If the option tt(-L) is given, the current values for the hook arrays +are listed with tt(typeset). + If the option tt(-d) is given, the var(function) is removed from the array of functions to be executed. @@ -323,6 +326,55 @@ The options tt(-U), tt(-z) and tt(-k) are passed as arguments to tt(autoload) for var(function). For functions contributed with zsh, the options tt(-Uz) are appropriate. ) +findex(add-zle-hook-widget) +item(tt(add-zle-hook-widget) [ tt(-L) | tt(-dD) ] [ tt(-Uzk) ] var(hook) var(widgetname))( +Several widget names are special to the line editor, as described in the section +ifnzman(Special Widgets, noderef(Zle Widgets))\ +ifzman(Special Widgets, see zmanref(zshzle)), +in that they are automatically called at specific points during editing. +Unlike function hooks, these do not use a predefined array of other names +to call at the same point; the shell function tt(add-zle-hook-widget) +maintains a similar array and arranges for the special widget to invoke +those additional widgets. + +var(hook) is one of tt(isearch-exit), tt(isearch-update), +tt(line-pre-redraw), tt(line-init), tt(line-finish), tt(history-line-set), +or tt(keymap-select), corresponding to each of the special widgets +tt(zle-isearch-exit), etc. + +var(widgetname) is the name of a ZLE widget. If no options are given this +is added to the array of widgets to be invoked in the given hook context. +Note that the hooks are called as widgets, that is, with +`tt(zle var(widgetname) -Nw)' rather than as a function call. + +The arrays of var(widgetname) are maintained in several tt(zstyle) +contexts, one for each var(hook) context, with a style of `tt(widgets)'. +If the tt(-L) option is given, this set of styles is listed with +`tt(zstyle -L)'. These styles may be updated directly with tt(zstyle) +commands, but the special widgets that refer to the styles are created +only if tt(add-zle-hook-widget) is called to add at least one widget. + +If the option tt(-d) is given, the var(widgename) is removed from +the array of widgets to be executed. + +If the option tt(-D) is given, the var(widgetname) is treated as a pattern +and any matching names of widgets are removed from the array. + +If var(widgetname) does not name an existing widget when added to the +array, it is assumed that a shell function also named var(widgetname) is +meant to provide the implementation of the widget. This name is therefore +marked for autoloading, and the options tt(-U), tt(-z) and tt(-k) are +passed as arguments to tt(autoload) as with tt(add-zsh-hook). The +widget is also created with `tt(zle -N var(widgetname))' to cause the +corresponding function to be loaded the first time the hook is called. + +In addition, var(widgetname) may be of the form var(index)tt(:)var(name). +In this case var(index) is an integer which determines the order in +which the widget var(name) will be called relative to other widgets in +the array. Widgets having the same var(index) are called in unspecified +order, and all widgets declared with an index are called before any +widgets that have no index. +) enditem() texinode(Recent Directories)(Other Directory Functions)(Utilities)(User Contributions) -- cgit 1.4.1