From acb15e3cc9af6c5b51e570765e6734e958d32aef Mon Sep 17 00:00:00 2001 From: Bart Schaefer Date: Sun, 12 Feb 2023 11:57:31 -0800 Subject: 51403: Tests and documentation for 51402, clean up some other tests. --- Doc/Zsh/builtins.yo | 16 ++++++++++------ Doc/Zsh/expn.yo | 5 ++++- Doc/Zsh/func.yo | 34 ++++++++++++++++++++++++++++++++++ Doc/Zsh/grammar.yo | 3 +++ Doc/Zsh/params.yo | 4 ++-- 5 files changed, 53 insertions(+), 9 deletions(-) (limited to 'Doc') 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)) -- cgit 1.4.1