51403: Tests and documentation for 51402, clean up some other tests.

5 files changed, 53 insertions, 9 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 97a82226b..92917c06c 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -2041,12 +2041,13 @@ cindex(named reference)
 cindex(reference, named)
 The flag tt(-n) creates a em(named reference) to another parameter.
 The second parameter need not exist at the time the reference is
-created.  No attributes except tt(-g) may be used in conjunction with
+created.  Only tt(-g) and tt(-r) may be used in conjunction with
 tt(-n).  The var(name) so created may not be an array element nor use
 a subscript, but the var(value) assigned may be any valid parameter
 name syntax, even a subscripted array element (including an associative
 array element) or an array slice, which is evaluated when the named
-reference is expanded.
+reference is expanded.  It is an error for a named reference to refer
+to itself, even indirectly through a chain of references.
 See ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)) and
 ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)) for details of the
 behavior of named references.
@@ -2443,7 +2444,7 @@ with the command `tt(zmodload -F zsh/rlimits b:unlimit)'.
 )
 findex(unset)
 cindex(parameters, unsetting)
-item(tt(unset) [ tt(-fmv) ] var(name) ...)(
+item(tt(unset) [ tt(-fmv) ] [ tt(-n) ] var(name) ...)(
 Each named parameter is unset.
 Local parameters remain local even if unset; they appear unset within scope,
 but the previous value will still reappear when the scope ends.
@@ -2457,10 +2458,13 @@ be quoted) and all parameters with matching names are unset.  Note that this
 cannot be used when unsetting associative array elements, as the subscript
 will be treated as part of the pattern.
 
-The tt(-v) flag specifies that var(name) refers to parameters. This is the
-default behaviour.
+The tt(-v) flag specifies that var(name) refers to parameters. This is
+the default behaviour.  If the tt(-n) option is supplied, and
+var(name) is a a named reference, var(name) will be unset rather than
+the variable it references.
 
-tt(unset -f) is equivalent to tt(unfunction).
+tt(unset -f) is equivalent to tt(unfunction).  The tt(-n) option has
+no effect with tt(-f).
 )
 findex(unsetopt)
 cindex(options, unsetting)
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 8b1c69c55..ef01794e6 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1581,7 +1581,10 @@ is interpreted at the time tt(${)var(pname)tt(}) is expanded.  Any
 form of subscript is allowed, including those that select individual
 elements, substrings of scalar strings, or multiple elements as with
 array slices or the `tt((i))', `tt((I))', `tt((r))', `tt((R))' and
-`tt((w))' subscript flags.
+`tt((w))' subscript flags.  However, the subscript is evaluated with
+the tt(NO_EXEC) option in effect, so command substitution and other
+similar constructs produce no output, although are not syntactically
+excluded.
 
 When var(rname) is an array (but not an array element or slice), the
 named reference may also be used in substitutions requiring an
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index 12db3f56a..d4914df7a 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -13,6 +13,40 @@ Functions are executed like commands with the arguments
 passed as positional parameters.
 (See noderef(Command Execution).)
 
+Parameters declared by any of the `tt(typeset)' family of commands
+during the execution of a function become em(local) to the function
+unless the `tt(-g)' option is used.  This is the em(scope) of the
+parameter, which extends dynamically to any other functions called by
+the declaring function.  In most cases, local parameters take the
+place of any other parameter having the same name that was assigned or
+declared in an earlier function scope.
+(See noderef(Local Parameters).)
+
+A named parameter declared with the `tt(-n)' option to any of the
+`tt(typeset)' commands becomes a reference to a parameter in scope at
+the time of assignment to the named reference, which may be at a
+different call level than the declaring function.  For this reason,
+it is good practice to declare a named reference as soon as the
+referent parameter is in scope, and as early as possible in the
+function if the reference is to a parameter in a calling scope.
+
+A typical use of named references is to pass the name
+of the referent as a positional parameter.  For example,
+ifzman()
+example(pop+LPAR()RPAR() {
+  local -n ref=$1
+  local last=$ref[$#ref]
+  ref[$#ref]=LPAR()RPAR()
+  print -r -- $last
+}
+array=LPAR() a list of five values RPAR()
+pop array)
+
+prints the word `tt(values)' and shortens `tt($array)' to
+`tt(LPAR() a list of five RPAR())'.  There are no local parameters in
+tt(pop) at the time `tt(ref=$1)' is assigned, so `tt(ref)' becomes a
+reference to `tt(array)' in the caller.
+
 Functions execute in the same process as the caller and
 share all files
 and present working directory with the
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index 9af211090..1b834f41a 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -187,6 +187,9 @@ Expand the list of var(word)s, and set the parameter
 var(name) to each of them in turn, executing var(list)
 each time.  If the `tt(in) var(word)' is omitted,
 use the positional parameters instead of the var(word)s.
+If any var(name) has been declared as a named reference,
+the corresponding var(word) is treated as the name of a
+parameter and var(name) is made a reference to that.
 
 The var(term) consists of one or more newline or tt(;)
 which terminate the var(word)s, and are optional when the
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index c7ecf0f64..946c00793 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -656,8 +656,8 @@ When a em(named reference) is created with `tt(typeset -n)', all uses
 of var(pname) in assignments and expansions instead assign to or
 expand var(rname).  This also applies to `tt(unset )var(pname)' and to
 most subsequent uses of `tt(typeset)' with the exception of
-`tt(typeset -n)' and `tt(typeset +n)', so to remove a named reference
-it is necessary to use one of:
+`tt(typeset -n)' and `tt(typeset +n)', so to remove a named reference,
+use either `tt(unset -n )var(pname)' or one of:
 ifzman()
 example(tt(typeset -n )var(pname)
 tt(typeset +n )var(pname))