manual/7448

11 files changed, 147 insertions, 19 deletions

diff --git a/Completion/Core/_description b/Completion/Core/_description
new file mode 100644
index 000000000..874ba8a96
--- /dev/null
+++ b/Completion/Core/_description
@@ -0,0 +1,22 @@
+#autoload
+
+local gropt=-J
+
+if [[ "$1" = -V ]]; then
+  gropt=-V
+  shift
+fi
+
+if [[ -n "$compconfig[group_matches]" ]]; then
+  if [[ -n "$compconfig[description_format]" ]]; then
+    eval "$1=($gropt ${(q)2} -X ${(q)compconfig[description_format]//\\%d/$2})"
+  else
+    eval "$1=($gropt ${(q)2})"
+  fi
+else
+  if [[ -n "$compconfig[description_format]" ]]; then
+    eval "$1=(-X ${(q)compconfig[description_format]//\\%d/$2})"
+  else
+    eval "$1=()"
+  fi
+fi
diff --git a/Completion/Core/_main_complete b/Completion/Core/_main_complete
index 4ac45d2cc..6e84818ee 100644
--- a/Completion/Core/_main_complete
+++ b/Completion/Core/_main_complete
@@ -22,6 +22,24 @@
 #  last_prompt
 #    If this is set to `always' the cursor is moved up to the last prompt
 #    after printing a list even if a numeric argument was given.
+#
+#
+# Also, most completion functions use the configuration keys:
+#
+#  description_format
+#    If this is set to a non-empty string, it will be displayed above
+#    all matches generated. The sequence `%d' in this string is replaced
+#    by a short description of what is completed in the current position
+#    of the command line.
+#
+#  message_format
+#    Like `description_format', but used in places where no completions
+#    can automatically be generated but the completion system still wants
+#    to give a hint what is expected in that position.
+#
+#  group_matches
+#    If this is set to a non-empty string, different types of matches will
+#    be put in different groups.
 
 
 # If you want to complete only set or unset options for the unsetopt
diff --git a/Completion/Core/_message b/Completion/Core/_message
new file mode 100644
index 000000000..0837cdf2f
--- /dev/null
+++ b/Completion/Core/_message
@@ -0,0 +1,19 @@
+#autoload
+
+local format
+
+format="$compconfig[message_format]"
+[[ -z "$format" ]] && "$compconfig[description_format]"
+
+if [[ -n "$format" ]]; then
+  if [[ $compstate[nmatches] -eq 0 ]]; then
+    compstate[list]=list
+    compstate[insert]=''
+    compadd -UX "${format//\\%d/$1}" -n ''
+  else
+    compadd -X "${format//\\%d/$1}" -n ''
+  fi
+  compstate[force_list]=yes
+else
+  compadd -n ''
+fi
diff --git a/Completion/Core/_normal b/Completion/Core/_normal
index d4e948e41..ffacc8f04 100644
--- a/Completion/Core/_normal
+++ b/Completion/Core/_normal
@@ -29,13 +29,15 @@ fi
 
 # See if there are any matching pattern completions.
 
-if [[ "$_compskip" != *patterns* ]]; then
+if [[ "$_compskip" != (all|*patterns*) ]]; then
   for i in "$_patcomps[@]"; do
     pat="${i% *}"
     val="${i#* }"
     if [[ "$cmd1" == $~pat || "$cmd2" == $~pat ]]; then
       "$val" && ret=0
-      if [[ "$_compskip" = *patterns* || "$_compskip" = all ]]; then
+      if [[ "$_compskip" = *patterns* ]]; then
+        break
+      elif [[ "$_compskip" = all ]]; then
         unset _compskip
         return ret
       fi
@@ -55,15 +57,36 @@ fi
 
 # And generate the matches, probably using default completion.
 
-if [[ -z "$comp" ]]; then
-  if [[ "$_compskip" = *default* ]]; then
-    unset _compskip
-    return 1
+if [[ -n "$comp" ]]; then
+  _compskip=patterns
+  "$comp" && ret=0
+  [[ "$_compskip" = (all|*patterns*) ]] && return ret
+else
+  if [[ "$_compskip" != *default* ]]; then
+    name=-default-
+    comp="$_comps[-default-]"
   fi
-  name=-default-
-  comp="$_comps[-default-]"
 fi
-[[ -z "$comp" ]] || "$comp" && ret=0
+  
+if [[ "$_compskip" != (all|*patterns*) ]]; then
+  for i in "$_postpatcomps[@]"; do
+    pat="${i% *}"
+    val="${i#* }"
+    if [[ "$cmd1" == $~pat || "$cmd2" == $~pat ]]; then
+      _compskip=default
+      "$val" && ret=0
+      if [[ "$_compskip" = *patterns* ]]; then
+	break
+      elif [[ "$_compskip" = all ]]; then
+        unset _compskip
+        return ret
+      fi
+    fi
+  done
+fi
+
+[[ "$name" = -default- && -n "$comp" && "$_compskip" != (all|*default*) ]] &&
+  "$comp" && ret=0
 
 unset _compskip
 
diff --git a/Completion/Core/_options b/Completion/Core/_options
index 0a852e6ce..356cd70db 100644
--- a/Completion/Core/_options
+++ b/Completion/Core/_options
@@ -2,4 +2,7 @@
 
 # This should be used to complete all option names.
 
-compgen "$@" -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' -o
+local expl
+
+_description expl 'zsh option'
+compgen "$expl[@]" "$@" -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' -o
diff --git a/Completion/Core/_parameters b/Completion/Core/_parameters
index a579e5ead..824d8dbc9 100644
--- a/Completion/Core/_parameters
+++ b/Completion/Core/_parameters
@@ -4,9 +4,13 @@
 # extra options of compadd. It completes only non-local parameters. All
 # arguments are given to compadd.
 
+local expl
+
+_description expl parameter
+
 if zmodload -e parameter; then
   setopt localoptions extendedglob
-  compadd "$@" - ${(k)parameters[(R)^*local*]}
+  compadd "$expl[@]" "$@" - ${(k)parameters[(R)^*local*]}
 else
-  compadd "$@" - ${${${(f)"$(typeset +)"}:#*local *}##* }
+  compadd "$expl[@]" "$@" - ${${${(f)"$(typeset +)"}:#*local *}##* }
 fi
diff --git a/Completion/Core/_path_files b/Completion/Core/_path_files
index 9494d5a4a..9aebc89d0 100644
--- a/Completion/Core/_path_files
+++ b/Completion/Core/_path_files
@@ -91,6 +91,14 @@ while getopts "P:S:qr:R:W:F:J:V:X:f/g:" opt; do
   esac
 done
 
+if (( ! ( $#group + $#expl ) )); then
+  if [[ "$sopt" = -/ ]]; then
+    _description expl directory
+  else
+    _description expl file
+  fi
+fi
+
 [[ -n "$tmp1" && $#addsfx -ne 0 ]] && addsfx[1]=-qS
 
 # If we were given no file selection option, we behave as if we were given
diff --git a/Completion/Core/_set_options b/Completion/Core/_set_options
index 5f634a2cd..947afdeae 100644
--- a/Completion/Core/_set_options
+++ b/Completion/Core/_set_options
@@ -4,4 +4,7 @@
 # names of the options that were set when it was called in the array
 # `_set_options'.
 
-compadd "$@" -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - $=_set_options
+local expl
+
+_description expl 'set zsh option'
+compadd "$expl[@]" "$@" -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - $=_set_options
diff --git a/Completion/Core/_unset_options b/Completion/Core/_unset_options
index c5150c2e5..f6a1c58f0 100644
--- a/Completion/Core/_unset_options
+++ b/Completion/Core/_unset_options
@@ -4,4 +4,7 @@
 # names of the options that were set when it was called in the array
 # `_set_options'.
 
-compadd "$@" -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - $=_unset_options
+local expl
+
+_description expl 'unset zsh option'
+compadd "$expl[@]" "$@" -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - $=_unset_options
diff --git a/Completion/Core/compdump b/Completion/Core/compdump
index 8f8a3ee77..b4530ea8e 100644
--- a/Completion/Core/compdump
+++ b/Completion/Core/compdump
@@ -39,6 +39,12 @@ for _d_f in "$_patcomps[@]"; do
 done >> $_d_file
 print ")" >> $_d_file
 
+print "\n_postpatcomps=(" >> $_d_file
+for _d_f in "$_postpatcomps[@]"; do
+  print -r - "'${_d_f//\'/'\\''}'"
+done >> $_d_file
+print ")" >> $_d_file
+
 print >> $_d_file
 
 # Now dump the key bindings. We dump all bindings for zle widgets
diff --git a/Completion/Core/compinit b/Completion/Core/compinit
index 808c20f5b..f160e7dcf 100644
--- a/Completion/Core/compinit
+++ b/Completion/Core/compinit
@@ -68,10 +68,12 @@ while [[ $# -gt 0 && $1 = -[dDf] ]]; do
 done
 
 # The associative array containing the definitions for the commands.
-# Definitions for patterns will be stored in the normal array `_patcomps'.
+# Definitions for patterns will be stored in the normal arrays `_patcomps'
+# and `_postpatcomps'.
 
 typeset -gA _comps
 _patcomps=()
+_postpatcomps=()
 
 # The associative array use to report information about the last
 # cmpletion to the outside.
@@ -106,6 +108,9 @@ fi
 # function will be invoked when completing for a command whose name 
 # matches the pattern given as argument after the function name (in this
 # case only one argument is accepted).
+# The option `-P' is like `-p', but the function will be called after
+# trying to find a function defined for the command on the line if no
+# such function could be found.
 # With the `-k' option a function for a special completion keys is 
 # defined and immediatly bound to those keys. Here, the extra arguments
 # are the name of one of the builtin completion widgets and any number
@@ -147,11 +152,11 @@ compdef() {
 
   # Get the options.
 
-  while getopts "anpkd" opt; do
+  while getopts "anpPkd" opt; do
     case "$opt" in
     a)    autol=yes;;
     n)    new=yes;;
-    [pk]) if [[ -n "$type" ]]; then
+    [pPk]) if [[ -n "$type" ]]; then
             # Error if both `-p' and `-k' are given (or one of them
 	    # twice).
             echo "$0: type already set to $type"
@@ -159,6 +164,8 @@ compdef() {
 	  fi
 	  if [[ "$opt" = p ]]; then
 	    type=pattern
+	  elif [[ "$opt" = P ]]; then
+	    type=postpattern
 	  else
 	    type=key
 	  fi
@@ -187,6 +194,13 @@ compdef() {
 
       _patcomps=("$_patcomps[@]" "$1 $func")
       ;;
+    postpattern)
+      if [[ $# -gt 1 ]]; then
+        echo "$0: only one pattern allowed"
+	return 1
+      fi
+      _postpatcomps=("$_postpatcomps[@]" "$1 $func")
+      ;;
     key)
       if [[ $# -lt 2 ]]; then
         echo "$0: missing keys"
@@ -230,7 +244,12 @@ compdef() {
     pattern)
       # Note the space.
       for i; do
-        _patcomps=("${(@)patcomps:#$i *}")
+        _patcomps=("${(@)_patcomps:#$i *}")
+      done
+      ;;
+    postpattern)
+      for i; do
+        _postpatcomps=("${(@)_postpatcomps:#$i *}")
       done
       ;;
     key)
@@ -359,7 +378,7 @@ if [[ -z "$_i_done" ]]; then
       shift _i_line
       case $_i_tag in
       (\#compdef)
-	if [[ $_i_line[1] = -[pk](n|) ]]; then
+	if [[ $_i_line[1] = -[pPk](n|) ]]; then
 	  compdef ${_i_line[1]}a "${_i_file:t}" "${(@)_i_line[2,-1]}"
 	else
 	  compdef -na "${_i_file:t}" "${_i_line[@]}"