manual/9058

14 files changed, 135 insertions, 127 deletions

diff --git a/Completion/Base/_arguments b/Completion/Base/_arguments
index 16293a098..5a6ee1930 100644
--- a/Completion/Base/_arguments
+++ b/Completion/Base/_arguments
@@ -259,7 +259,8 @@ if (( $# )) && comparguments -i "$autod" "$@"; then
 
       if [[ -z "$matched" ]] && _requested options &&
           { ! zstyle -t ":completion${curcontext}:options" prefix-needed ||
-            [[ "$origpre" = [-+]* ]] } ; then
+            [[ "$origpre" = [-+]* ||
+               ( -z "$aret$mesg" && nm -eq compstate[nmatches] ) ]] } ; then
 	local prevpre="$PREFIX" previpre="$IPREFIX"
 
 	PREFIX="$origpre"
diff --git a/Completion/Base/_combination b/Completion/Base/_combination
index ffda5cae9..e7548f19f 100644
--- a/Completion/Base/_combination
+++ b/Completion/Base/_combination
@@ -21,7 +21,7 @@
 #  `_telnet' completes hosts as:
 #
 #    _combination my-accounts hosts-ports-users \
-#      ${options[-l]:+users=${options[-l]:q}} \
+#      ${opt_args[-l]:+users=${opt_args[-l]:q}} \
 #      hosts "$expl[@]"
 #
 #  This completes `host1', `host2', `mail-server', `news-server' and
@@ -31,7 +31,7 @@
 #  `_telnet' completes ports as:
 #
 #    _combination my-accounts hosts-ports-users \
-#      ${options[-l]:+users=${options[-l]:q}} \
+#      ${opt_args[-l]:+users=${opt_args[-l]:q}} \
 #      hosts="${line[2]:q}" \
 #      ports "$expl[@]"
 #
diff --git a/Completion/Base/_command_names b/Completion/Base/_command_names
index 63c8601e9..12caf926f 100644
--- a/Completion/Base/_command_names
+++ b/Completion/Base/_command_names
@@ -17,11 +17,11 @@ else
   [[ "$1" = - ]] && shift
 
   defs=( "$defs[@]"
-    'jobs:: _jobs'
     'builtins:builtin command:compadd - ${(@k)builtins}'
     'functions:shell function:compadd - ${(@k)functions}'
     'aliases:alias:compadd - ${(@k)aliases}'
     'reserved-words:reserved word:compadd - ${(@k)reswords}'
+    'jobs:: _jobs -t'
   )
 fi
 
diff --git a/Completion/Base/_jobs b/Completion/Base/_jobs
index ff9fa5a62..48d74c307 100644
--- a/Completion/Base/_jobs
+++ b/Completion/Base/_jobs
@@ -1,11 +1,14 @@
 #autoload
 
-local expl disp jobs job jids pfx='%' desc
+local expl disp jobs job jids pfx='%' desc how
 
 _tags jobs || return 1
 
-zstyle -t ":completion${curcontext}:jobs" prefix-needed &&
-    [[ "$PREFIX" != %* ]] && return 1
+if [[ "$1" = -t ]]; then
+  zstyle -t ":completion${curcontext}:jobs" prefix-needed &&
+      [[ "$PREFIX" != %* || compstate[nmatches] -eq 0 ]] && return 1
+  shift
+fi
 zstyle -t ":completion${curcontext}:jobs" prefix-hidden && pfx=''
 zstyle -t ":completion${curcontext}:jobs" verbose       && desc=yes
 
@@ -31,8 +34,12 @@ if [[ -n "$desc" ]]; then
   done
 fi
 
-if zstyle -t ":completion${curcontext}:jobs" strings; then
-  local texts i text str tmp
+zstyle -s ":completion${curcontext}:jobs" numbers how
+
+if [[ "$how" = (yes|true|on|1) ]]; then
+  jobs=( "$jids[@]" )
+else
+  local texts i text str tmp num max=0
 
   # Find shortest unambiguous strings.
 
@@ -47,6 +54,7 @@ if zstyle -t ":completion${curcontext}:jobs" strings; then
       text=""
     fi
     tmp=( "${(@M)texts:#${str}*}" )
+    num=1
     while [[ -n "$text" && $#tmp -ge 2 ]]; do
       str="${str} ${text%% *}"
       if [[ "$text" = *\ * ]]; then
@@ -55,14 +63,19 @@ if zstyle -t ":completion${curcontext}:jobs" strings; then
         text=""
       fi
       tmp=( "${(@M)texts:#${str}*}" )
+      (( num++ ))
     done
 
+    [[ num -gt max ]] && max="$num"
+
     jobs=( "$jobs[@]" "$str" )
   done
 
-  [[ -n "$pfx" && -n "$desc" ]] && disp=( "${(@)disp#%}" )
-else
-  jobs=( "$jids[@]" )
+  if [[ "$how" = [0-9]## && max -gt how ]]; then
+    jobs=( "$jids[@]" )
+  else
+    [[ -z "$pfx" && -n "$desc" ]] && disp=( "${(@)disp#%}" )
+  fi
 fi
 
 if [[ -n "$desc" ]]; then
diff --git a/Completion/Base/_tilde b/Completion/Base/_tilde
index bba928f50..128fd7ffa 100644
--- a/Completion/Base/_tilde
+++ b/Completion/Base/_tilde
@@ -4,7 +4,7 @@
 # for you or if there are too many of them, you may want to use
 # `compadd -qS/ - "$friends[@]"' or something like that.
 
-local expl suf dirs list lines revlines i ret disp
+local expl suf dirs list lines revlines i ret disp nm="$compstate[nmatches]"
 
 if [[ "$SUFFIX" = */* ]]; then
   ISUFFIX="/${SUFFIX#*/}$ISUFFIX"
@@ -23,7 +23,7 @@ while _tags; do
 
   if _requested -V directory-stack expl 'directory stack' &&
      { ! zstyle -t ":completion${curcontext}:directory-stack" prefix-needed ||
-       [[ "$PREFIX" = [-+]* ]] }; then
+       [[ "$PREFIX" = [-+]* || nm -eq compstate[nmatches] ]] }; then
     if zstyle -t ":completion${curcontext}:directory-stack" verbose; then
       integer i
 
diff --git a/Completion/Builtins/_cd b/Completion/Builtins/_cd
index f8b01bc66..8e72bd7ad 100644
--- a/Completion/Builtins/_cd
+++ b/Completion/Builtins/_cd
@@ -39,7 +39,7 @@ elif _popd || [[ $PREFIX != (\~|/|./|../)* && $#cdpath -ne 0 ]]; then
   else
     _alternative \
         'local-directories:local directories:_path_files -/' \
-	'path-directories: directories in cdpath:_path_files -W \(${cdpath:#.}\) -/'
+	"path-directories: directories in cdpath:_path_files -W \\(${${(@)cdpath:#.}}\\) -/"
   fi
 else
   _path_files -/
diff --git a/Completion/Builtins/_kill b/Completion/Builtins/_kill
index 44442ef8f..5e3caed6a 100644
--- a/Completion/Builtins/_kill
+++ b/Completion/Builtins/_kill
@@ -2,5 +2,5 @@
 
 _alternative \
     'signals:: _signals -p' \
-    'jobs:: _jobs' \
-    'processes:: _pids'
+    'processes:: _pids' \
+    'jobs:: _jobs -t'
diff --git a/Completion/Builtins/_stat b/Completion/Builtins/_stat
index 232cf672b..3b192c297 100644
--- a/Completion/Builtins/_stat
+++ b/Completion/Builtins/_stat
@@ -1,19 +1,19 @@
 #compdef stat
 
-local expl
+local expl ret=1
 
 if [[ "$words[CURRENT-1]" = -[AH] ]]; then
   _arrays
 else
-  _tags options files || return 1
+  _tags files options || return 1
 
   while _tags; do
+    _requested files && _files && ret=0
     _requested options expl 'inode element' &&
         { ! zstyle -t ":completion${curcontext}:options" prefix-needed ||
-          [[ "$PREFIX[1]" = + ]] } &&
+          [[ "$PREFIX[1]" = + || ret -eq 1 ]] } &&
         compadd "$expl[@]" - +device +inode +mode +nlink +uid +gid +rdev \
                              +size +atime +mtime +ctime +blksize +block +link
     fi
-    _requested files && _files
   done
 fi
diff --git a/Completion/Builtins/_wait b/Completion/Builtins/_wait
index 28fdb7985..c007cab90 100644
--- a/Completion/Builtins/_wait
+++ b/Completion/Builtins/_wait
@@ -1,3 +1,3 @@
 #compdef wait
 
-_alternative 'jobs:: _jobs' 'processes:: _pids'
+_alternative 'processes:: _pids' 'jobs:: _jobs -t'
diff --git a/Completion/Core/_path_files b/Completion/Core/_path_files
index bbed17a1f..dd9934506 100644
--- a/Completion/Core/_path_files
+++ b/Completion/Core/_path_files
@@ -4,7 +4,7 @@
 # to complete to `/usr/local/bin'.
 
 local linepath realpath donepath prepath testpath exppath
-local tmp1 tmp2 tmp3 tmp4 i orig pre suf tpre tsuf opre osuf cpre
+local tmp1 tmp2 tmp3 tmp4 i orig eorig pre suf tpre tsuf opre osuf cpre
 local pats haspats=no ignore group expl addpfx addsfx remsfx
 local nm=$compstate[nmatches] menu match matcher mopts atmp
 
@@ -108,6 +108,7 @@ suf="$SUFFIX"
 opre="$PREFIX"
 osuf="$SUFFIX"
 orig="${PREFIX}${SUFFIX}"
+eorig="$orig"
 
 [[ $compstate[insert] = (*menu|[0-9]*) || -n "$_comp_correct" ||
    ( $#compstate[pattern_match] -ne 0 &&
@@ -265,7 +266,11 @@ for prepath in "$prepaths[@]"; do
 	  if [[ "$tmp2[1]" = */* ]]; then
 	    tmp2=( "${(@)tmp2:h}" )
 	    compquote tmp2
-	    exppaths=( "$exppaths[@]" ${^tmp2}/${tpre}${tsuf} )
+	    if [[ "$tmp2" = */ ]]; then
+	      exppaths=( "$exppaths[@]" ${^tmp2}${tpre}${tsuf} )
+	    else
+	      exppaths=( "$exppaths[@]" ${^tmp2}/${tpre}${tsuf} )
+	    fi
           else
 	    exppaths=( "$exppaths[@]" ${tpre}${tsuf} )
 	  fi
@@ -453,7 +458,7 @@ done
 # expanded paths that are different from the string on the line, we add
 # them as possible matches.
 
-exppaths=( "${(@)exppaths:#$orig}" )
+exppaths=( "${(@)exppaths:#$eorig}" )
 
 if zstyle -t ":completion${curcontext}:paths" expand prefix &&
    [[ $#exppaths -gt 0 && nm -eq compstate[nmatches] ]]; then
diff --git a/Completion/Core/_sort_tags b/Completion/Core/_sort_tags
index 20897823a..6f07eec1c 100644
--- a/Completion/Core/_sort_tags
+++ b/Completion/Core/_sort_tags
@@ -1,39 +1,28 @@
 #autoload
 
-local stags tag
+comptry arguments values
+comptry options
 
-if zstyle -a ":completion${curcontext}" sort-tags stags; then
+case "$curcontext" in
+# Some silly examples commented out:
+#
+# *::*p[bgpn]m:*)           # change the order for file-completion
+#   comptry globbed-files directories
+#   comptry all-files
+#   ;;
+# *::dvips::-o*)            # automatic context set by _arguments
+#   comptry all-files
+#   return
+#   ;;
+# *::kill:*)
+#   comptry processes
+#   return                  # this return ensures that we use only processes
+#   ;;
+*)
+  comptry globbed-files
+  comptry directories
+  comptry all-files
+  ;;
+esac
 
-  for tag in $stags; do
-    [[ $tag != '' ]] && comptry ${=tag}
-  done
-
-else
-
-  comptry arguments values
-  comptry options
-
-  case "$curcontext" in
-  # Some silly examples commented out:
-  #
-  # *::*p[bgpn]m:*)           # change the order for file-completion
-  #   comptry globbed-files directories
-  #   comptry all-files
-  #   ;;
-  # *::dvips::-o*)            # automatic context set by _arguments
-  #   comptry all-files
-  #   return
-  #   ;;
-  # *::kill:*)
-  #   comptry processes
-  #   return                  # this return ensures that we use only processes
-  #   ;;
-  *)
-    comptry globbed-files
-    comptry directories
-    comptry all-files
-    ;;
-  esac
-
-  comptry "$@"
-fi
+comptry "$@"
diff --git a/Completion/Core/_tags b/Completion/Core/_tags
index fcef91061..e913095c4 100644
--- a/Completion/Core/_tags
+++ b/Completion/Core/_tags
@@ -4,7 +4,7 @@ if (( $# )); then
 
   # We have arguments: the tags supported in this context.
 
-  local curcontext="$curcontext" order
+  local curcontext="$curcontext" order tag nodef
 
   if [[ "$1" = -C?* ]]; then
     curcontext="${curcontext}:${1[3,-1]}"
@@ -38,9 +38,24 @@ if (( $# )); then
   _offered_tags=( "$_offered_tags[@]" "$@" )
   _last_tags=()
 
-  # Call the function that sorts the tags into sets.
+  # Sort the tags.
 
-  "${_sort_tags:-_sort_tags}" "$@"
+  if [[ -n "$_sort_tags" ]]; then
+    "$_sort_tags" "$@"
+  elif zstyle -a ":completion${curcontext}" tag-order order; then
+
+    for tag in $order; do
+      case $tag in
+      -)     nodef=yes;;
+      *\(\)) "${${tag%%[ 	]#\(\)}##[ 	]#}" "$@";;
+      ?*)    comptry ${=tag};;
+      esac
+    done
+
+    [[ -z "$nodef" ]] && comptry "$@"
+  else
+    comptry "$@"
+  fi
 
   # Return non-zero if at least one set of tags should be used.
 
diff --git a/Completion/Core/compinit b/Completion/Core/compinit
index 09fb68467..8d6d20459 100644
--- a/Completion/Core/compinit
+++ b/Completion/Core/compinit
@@ -479,6 +479,8 @@ zstyle ':completion:correct'  max-errors    '2' numeric
 zstyle ':completion:correct'  prompt        'correct to:'
 zstyle ':completion:*'        completer     '_complete'
 zstyle ':completion*:default' list-colors   no=0 fi=0 di=0 ln=0 pi=0 so=0 bd=0 cd=0 ex=0
+zstyle ':completion:*' tag-order 'arguments values' options \
+                                 globbed-files directories all-files
 
 # Now we automatically make the definition files autoloaded.
 
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index ba863cfe8..07dca151c 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -302,13 +302,11 @@ In many of the possible contexts the completion system can generate
 matches, often multiple types of matches.  These types are represented as
 simple names called `tags'.  The completion system will decide internally
 what sort of tags are allowed; a list of the standard possibilities is given
-below.  The list of tags is passed as the arguments of the function
-(tt(_sort_tags)), which can then determine the order in which the  tags are
-to be used by the completion function.  Only those types of matches whose
-tags were selected by the tt(_sort_tags) function will be produced, and in
-the order given.  Instead of altering tt(_sort_tags), you may define
-a `tt(sort-tags)' style for the appropriate context, as described in the
-list of standard styles below.
+below.  To determine in which order the tags are to be used by the
+completion function, the `tt(tag-order)' style for the appropriate
+context may be set, as described in the list of standard styles below.
+Only those types of matches whose tags were selected by this style
+will be produced, and in the order given.
 
 The tt(_complete_help) bindable command described in 
 ifzman(the section `Bindable Commands' below)\
@@ -317,8 +315,8 @@ can be invoked to find out the context and tag names used at a particular
 point in completion.  It shows a list of context names and the 
 tag names used in those contexts if completion were tried at the
 current cursor position.  Hence one can easily find out all the
-information needed to change the behaviour of the tt(_sort_tags) function
-or the tt(sort_tags) style for a particular context.
+information needed to change the behaviour of the tt(tag-order) style
+for a particular context.
 
 Completion behaviour can be modified by various other
 `styles' defined with the tt(zstyle) builtin command
@@ -756,9 +754,9 @@ ifnzman(noderef(The zutil Module))\
 .
 )
 item(tt(glob))(
-Like tt(complete), this is used by the tt(_expand) completer.
+Like tt(completions), this is used by the tt(_expand) completer.
 
-The value is used like the one for tt(complete) and if it evaluates to 
+The value is used like the one for tt(completions) and if it evaluates to 
 `tt(1)', globbing will be attempted on the words resulting from
 substitution (see the tt(substitute) style) or the original string
 from the line.
@@ -819,7 +817,7 @@ 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 tt(_sort_tags) function can be modified as described
+completions at all the tt(tag-order) style can be modified as described
 below.
 )
 item(tt(hosts))(
@@ -1012,6 +1010,15 @@ tt(TAB) at this point would start trying to complete the line as it now
 appears.  With tt(_oldlist), it will instead continue to cycle through the
 list of completions.
 )
+item(tt(numbers))(
+This is used with the tt(jobs) tag. If it is `true', the completions
+will use the job numbers instead of the shortest unambiguous strings
+of the jobs' command lines. If the value is a number, job numbers will 
+only be used if for at least one of the jobs that many (or more) words 
+from the command line string have to be used to make the strings
+unambiguous. E.g. if it is set to `tt(1)', strings will only be used
+if all jobs differ in the first word on their command lines.
+)
 item(tt(original))(
 This is used by the tt(_approximate), tt(_correct) and tt(_match)
 completers. The first two use it to decide if the original string should
@@ -1096,10 +1103,9 @@ to tt(menu), then the expansions are only sorted when they are offered
 as single strings (not in the string containing all possible
 expansions).
 )
-item(tt(sort-tags))(
+item(tt(tag-order))(
 This provides a mechanism for sorting how the tags available in a
-particular context will be used.  It assumes you have not redefined the
-standard tt(_sort_tags) function.
+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
@@ -1108,18 +1114,27 @@ found, the next value is used.
 For example,
 
 example(
-  zstyle :completion:complete::gunzip: sort-tags \ 
+  zstyle :completion:complete::gunzip: tag-order \ 
     'globbed-files directories' all-files
 )
 
 specifies that, when completing arguments of the command tt(gunzip),
 files generated by patterns (in this case, those ending in tt(.gz)) and
 any directories will be presented first, and if that fails, any other files
-will be tried.  If no valid tags are present, nothing will be completed. so
-this can be used to turn off completion in a particular context.
+will be tried.  If any string in the value consists of only a hyphen
+(`tt(-)'), then only the tags selected by the other strings will be
+generated. Normally all tags not explicitly selected will be tried at
+the end if the selected tags did not generate any matches.  This means 
+that a value of only one hyphen turns off completion in a particular
+context.
+
+Strings in the value may also be of the form `var(func)tt(())'. In
+this case the function var(func) will be called which can then define
+in which order tags are to be used based on additional context
+information. See the tt(_sort_tags) function below for a description
+of how such functions can be implemented.
 
-If no style has been defined for a context, the tt(_sort_tags) function
-provides defaults, as given below.
+If no style has been defined for a context, all tags will be used.
 )
 item(tt(special-dirs))(
 Normally, the completion code will not produce the directory names
@@ -1133,11 +1148,6 @@ command will always insert matches as if menucompletion were started
 and it will stop when the last match is inserted. If this style is set
 to tt(verbose) a message will be displayed when the last match is reached.
 )
-item(tt(strings))(
-This is used with the tt(jobs) tag. If it is `true', the completions
-will use the shortest unambiguous strings of the jobs' command lines
-instead of the job numbers.
-)
 item(tt(substitute))(
 If this is unset or set to the empty string, the tt(_expand) completer
 will first try to expand all substitutions in the string (such as
@@ -1399,7 +1409,7 @@ adding the possible expansions as single matches and tt(original) when
 adding the original string from the line. In which order these strings 
 are generated and which of these strings are generated at all can be
 controlled by using the tt(group-order) style and by modifying the
-tt(sort-tags) style or tt(_sort_tags) function, as usual.
+tt(tag-order) style, as usual.
 
 The format string for tt(all-expansions) and for tt(expansions) may
 contain the sequence `tt(%o)' which will be replaced by the original
@@ -1642,7 +1652,7 @@ item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])(
 If called with arguments, these are taken as the names of the tags for 
 the types of matches the calling completion function can generate in
 the current context. These tags are stored internally and sorted by
-calling the tt(_sort_tags) function. Following calls to this function
+using the tt(tag-order) style. Following calls to this function
 without arguments from the same function will then select the first,
 second, etc. set of tags requested by the user. To test if a certain
 tag should be tried, the tt(_requested) function has to be called (see 
@@ -1654,10 +1664,9 @@ non-zero otherwise.
 This function also accepts the tt(-C) option followed by a
 var(name). This name is temporarily (i.e. not visible outside
 tt(_tags)) appended (with a colon before it) to the contents of the
-tt(curcontext) parameter. This allows to make tt(_tags) and
-tt(_sort_tags) use a more specific context name without having to
-change and reset the tt(curcontext) parameter (which would otherwise
-have the same effect).
+tt(curcontext) parameter. This allows to make tt(_tags) use a more
+specific context name without having to change and reset the
+tt(curcontext) parameter (which would otherwise have the same effect).
 )
 findex(_requested)
 item(tt(_requested) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
@@ -2313,12 +2322,10 @@ the functions for the fields if they are called.
 )
 findex(_sort_tags)
 item(tt(_sort_tags) var(tag) ...)(
-As described above, this may be redefined by the user, although a default
-implementation is provided.  In most cases, you will probably find it
-easier to define a tt(sort-tags) style for the context whose behaviour you
-wish to alter.
+As described above for the tt(tag-order) style, this is only provided
+to show how functions that sort tags can be implemented.
 
-Inside the tt(_sort_tags) function the name of the current context can
+Inside such functions the name of the current context can
 be accessed using the tt(curcontext) parameter. For example, the
 function generating file names (called tt(_files)) in the completion
 system is often called to generate only filenames matching a given
@@ -2357,7 +2364,7 @@ the glob pattern (if any glob pattern is used). If that doesn't yield
 any matches, names of directories are generated, and if that doesn't
 yield any matching names either, all filenames will be generated.
 
-In every context the tt(_sort_tags) function may call tt(comptry) as
+In every context the function may call tt(comptry) as
 often as it wants. Also, every string may be given as argument, even
 if no tag with such a name was offered by the completion
 function. This allows one to give a preferred ordering for some common 
@@ -2365,7 +2372,7 @@ tag sets without having to worry about sensible patterns for context
 names. For example, many completion functions can generate both
 arguments and option names for commands. These functions normally use
 the tags tt(arguments) and tt(options). Depending on your preference
-you may write in your tt(_sort_tags) function:
+you may write in your sorting function:
 
 example(_sort_tags() {
   comptry arguments options
@@ -2395,8 +2402,8 @@ names that can be completed.
 Since the completion functions are free to choose the tag names they
 use, there can't be a complete list. So to make sure that all types of 
 matches are eventually tried as completions, one should  use a call to 
-tt(comptry) with all arguments at the end of tt(_sort_tags). For those
-contexts where one really wants to make sure that certain tags are
+tt(comptry) with all arguments at the end of the sorting function. For
+those contexts where one really wants to make sure that certain tags are
 never used one can then use a call to tt(return) to circumvent that
 last tt(comptry). For example:
 
@@ -2419,30 +2426,6 @@ identifiers are generated as possible matches by using only the
 tt(processes) tag in a call to tt(comptry). The immediate call to
 tt(return) then makes sure that the default tt(comptry) at the end is
 not executed.
-
-The default implementation of tt(_sort_tags) is the following:
-
-example(_sort_tags() {
-  local stags tag
-
-  if zstyle -a ":completion${curcontext}" sort-tags stags; then
-    for tag in $stags; do
-      [[ $tags != '' ]] && comptry ${=tag}
-    done
-
-  else		   
-    comptry arguments values
-    comptry options
-    case "$curcontext" in
-      (*) comptry globbed-files
-  	  comptry directories
-  	  comptry all-files
-          ;;
-    esac
-    comptry "$@"
-  fi
-})
-
 )
 
 enditem()