users/15864: turn zsh_directory_name into a hook

2 files changed, 38 insertions, 39 deletions

diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index c5808fbeb..5b9af12f3 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -302,10 +302,13 @@ called at the same point; these are so-called `hook functions'.
 The shell function tt(add-zsh-hook) provides a simple way of adding or
 removing functions from the array.
 
-var(hook) is one of tt(chpwd), tt(periodic), tt(precmd) or tt(preexec),
-the special functions in question.
+var(hook) is one of tt(chpwd), tt(periodic), tt(precmd), tt(preexec),
+tt(zshaddhistory), tt(zshexit), or tt(zsh_directory_name),
+the special functions in question.  Note that tt(zsh_directory_name)
+is called in a different way from the other functions, but may
+still be manipulated as a hook.
 
-var(functions) is name of an ordinary shell function.  If no options
+var(function) is name of an ordinary shell function.  If no options
 are given this will be added to the array of functions to be executed
 in the given context.
 
@@ -315,6 +318,10 @@ the array of functions to be executed.
 If the option tt(-D) is given, the var(function) is treated as a pattern
 and any matching names of functions are removed from the array of
 functions to be executed.
+
+The options tt(-U), tt(-z) and tt(-k) are passed as arguments to
+tt(autoload) for var(function).  For functions contributed with zsh, the
+options tt(-Uz) are appropriate.
 )
 enditem()
 
@@ -544,36 +551,15 @@ enditem()
 subsect(Use with dynamic directory naming)
 
 It is possible to refer to recent directories using the dynamic directory
-name syntax that appeared in zsh version 4.3.7.  If you create and
-autoload a function tt(zsh_directory_name) containing the following code,
-tt(~[1]) will refer to the most recent directory other than $PWD, and so on.
-This also includes completion.
-
-example(if [[ $1 = n ]]; then
-  if [[ $2 = <-> ]]; then
-    # Recent directory
-    typeset -ga reply
-    autoload -Uz cdr
-    cdr -r
-    if [[ -n ${reply[$2]} ]]; then
-      reply=LPAR()${reply[$2]}RPAR()
-      return 0
-    else
-      reply=LPAR()RPAR()
-      return 1
-    fi
-  fi
-elif [[ $1 = c ]]; then
-  if [[ $PREFIX = <-> || -z $PREFIX ]]; then
-    typeset -a keys values
-    values=LPAR()${${(f)"$+LPAR()cdr -l+RPAR()"}/ ##/:}RPAR()
-    keys=LPAR()${values%%:*}RPAR()
-    _describe -t dir-index 'recent directory index' \
-      values keys -V unsorted -S']'
-    return
-  fi
-fi
-return 1)
+name syntax by using the supplied function tt(zsh_directory_name_cdr)
+a hook:
+
+example(autoload -Uz add-zsh-hook
+add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr)
+
+When this is done, tt(~[1]) will refer to the most recent
+directory other than $PWD, and so on.  Completion after tt(~[)var(...)
+also works.
 
 subsect(Details of directory handling)
 
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 9c4491386..1bace49c3 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1517,8 +1517,12 @@ cindex(directories, named, dynamic)
 cindex(named directories, dynamic)
 cindex(dynamic named directories)
 
-The feature described here is only available if the shell function
-tt(zsh_directory_name) exists.
+If the function tt(zsh_directory_name) exists, or the shell variable
+tt(zsh_directory_name_functions) exists and contains an array of
+function names, then the functions are used to implement dynamic
+directory naming.  The functions are tried in order until one returns
+status zero, so it is important that functions test whether they can
+handle the case in question and return an appropriate status.
 
 A `tt(~)' followed by a string var(namstr) in unquoted square brackets is
 treated specially as a dynamic directory name.  Note that the first
@@ -1529,11 +1533,12 @@ which is the directory corresponding to the name and return status zero
 (executing an assignment as the last statement is usually sufficient), or
 it should return status non-zero.  In the former case the element of reply
 is used as the directory; in the latter case the substitution is deemed to
-have failed and tt(NOMATCH) handling is applied if the option is set.
+have failed.  If all functions fail and the option tt(NOMATCH) is set,
+an error results.
 
-The function tt(zsh_directory_name) is also used to see if a directory can
+The functions defined as above are also used to see if a directory can
 be turned into a name, for example when printing the directory stack or
-when expanding tt(%~) in prompts.  In this case the function is passed two
+when expanding tt(%~) in prompts.  In this case each function is passed two
 arguments: the string tt(d) (for directory) and the candidate for dynamic
 naming.  The function should either return non-zero status, if the
 directory cannot be named by the function, or it should set the array reply
@@ -1551,7 +1556,15 @@ parts of the directory path, as described below; it is used if the prefix
 length matched (16 in the example) is longer than that matched by any
 static name.
 
-The completion system calls `tt(zsh_directory_name c)' in order to
+It is not a requirement that a function implements both
+tt(n) and tt(d) calls; for example, it might be appropriate for certain
+dynamic forms of expansion not to be contracted to names.  In that case
+any call with the first argument tt(d) should cause a non-zero status to
+be returned.
+
+The completion system calls `tt(zsh_directory_name c)' followed by
+equivalent calls to elements of the array
+tt(zsh_directory_name_functions), if it exists, in order to
 complete dynamic names for directories.  The code for this should be
 as for any other completion function as described in
 ifnzman(noderef(Completion System))\