mirrors/zsh
1
0
Fork 0
mirror of git://git.code.sf.net/p/zsh/code synced 2025-06-16 20:58:05 +02:00
Code Releases Activity

51375: Clarify documentation, fix typos, add indexing.

Browse source
This commit is contained in:
Bart Schaefer 2023-02-12 11:32:11 -08:00
parent 3e55a135c1
commit e807ac1157
5 changed files with 44 additions and 19 deletions

3
ChangeLog
View file

@ -1,5 +1,8 @@
2023-02-12 Bart Schaefer <schaefer@zsh.org>
* 51375: Doc/Zsh/builtins.yo, Doc/Zsh/expn.yo, Doc/Zsh/params.yo,
Doc/Zsh/mod_parameter.yo: Clarify, fix typos, add indexing.
* 51374: Src/Modules/parameter.c, Src/params.c, Test/README,
Test/K01nameref.ztst: Expose named references in $parameters,
fix substitution error.

12
Doc/Zsh/builtins.yo
View file

@ -2041,16 +2041,22 @@ 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 other attribute flags may be used in conjunction with
tt(-n). The var(name) assigned-to may not be an array element nor use
created. No attributes except tt(-g) 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 (incuding an associative
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.
See ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)) and
ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)) for details of the
behavior of named references.
Local function scoping rules for `tt(typeset)' do apply with `tt(-n)',
so a declaration within a function persists only until the end of the
function unless `tt(-g -n)' is specified, and any local parameter (of
any type) with the same var(name) supplants a named reference from a
surrounding scope.
If no attribute flags are given, and either no var(name) arguments are
present or the flag tt(+m) is used, then each parameter name printed is
preceded by a list of the attributes of that parameter (tt(array),

4
Doc/Zsh/expn.yo
View file

@ -1592,8 +1592,8 @@ tt(${)var(name)tt(:|)var(pname)tt(}))
Expansions of the form `tt(${LPAR()t)tt(RPAR())var(pname)tt(})' expand
the type information of var(rname), unless var(rname) is empty, in which
case `tt(nameref)' is expanded, or when no variable var(rname) exists,
in which case the expansion is empty.
case the expansion is `tt(nameref)', or when no variable var(rname)
exists, in which case the expansion is empty.
See also ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)).

8
Doc/Zsh/mod_parameter.yo
View file

@ -127,6 +127,14 @@ noderef(Parameter Expansion)
)\
. The value may also be `tt(undefined)' indicating a parameter that
may be autoloaded from a module but has not yet been referenced.
When the key is the name of a named reference, the value is
`tt(nameref-)' prepended to the type of the referenced parameter,
for example
ifzman()
example(tt(% typeset -n parms=parameters)
tt(% print -r ${parameters[parms]})
tt(nameref-association-readonly-hide-hideval-special))
Setting or unsetting keys in this array is not possible.
)
vindex(modules)

36
Doc/Zsh/params.yo
View file

@ -85,6 +85,8 @@ menu(Parameters Set By The Shell)
menu(Parameters Used By The Shell)
endmenu()
texinode(Array Parameters)(Positional Parameters)()(Parameters)
cindex(array parameters)
cindex(parameters, array)
sect(Array Parameters)
To assign an array value, write one of:
findex(set, use of)
@ -567,6 +569,8 @@ entire second parameter concatenated with the filename generation pattern
`tt([3,5])'.
texinode(Positional Parameters)(Local Parameters)(Array Parameters)(Parameters)
cindex(positional parameters)
cindex(parameters, positional)
sect(Positional Parameters)
The positional parameters provide access to the command-line arguments
of a shell function, shell script, or the shell itself; see
@ -594,6 +598,8 @@ allowed, and has the effect of shifting all the values at positions greater
than var(n) by as many positions as necessary to accommodate the new values.
texinode(Local Parameters)(Named References)(Positional Parameters)(Parameters)
cindex(local parameters)
cindex(parameters, local)
sect(Local Parameters)
Shell function executions delimit scopes for shell parameters.
(Parameters are dynamically scoped.) The tt(typeset) builtin, and its
@ -627,9 +633,9 @@ find the programs in tt(/new/directory) inside a function.
Note that the restriction in older versions of zsh that local parameters
were never exported has been removed.
texinode(Named References)(Parameters Set By The Shell)(Local Parameters)(Parameters)
cindex(named references)
cindex(references, named)
texinode(Named References)(Parameters Set By The Shell)(Local Parameters)(Parameters)
sect(Named References)
Zsh supports two different mechanisms for indirect parameter referencing:
ifzman()
@ -641,24 +647,24 @@ tt(print -r -- ${)var(pname)tt(}))
The `tt((P))' flag method is older and should be used when a script
needs to be backwards-compatible. This is described fully in
ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)).
the Parameter Expansion Flags section of
ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)). Zsh
versions em(greater than) tt(5.9.0) are required for `tt(typeset -n)'.
This manual was generated with Zsh tt(version()).
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)', so to remove a named reference it is necessary to
use:
`tt(typeset -n)' and `tt(typeset +n)', so to remove a named reference
it is necessary to use one of:
ifzman()
example(tt(typeset +n )var(pname)
tt(unset )var(pname))
example(tt(typeset -n )var(pname)
tt(typeset +n )var(pname))
When `tt(typeset -n )var(pname)tt(=)var(rname)' appears in a given
(global or function) scope, `tt(${)var(pname)tt(})' refers to
var(rname) in the scope of the tt(typeset) command. This differs
from ksh93 where the scope used is that of var(rname) even if the
current var(rname) would be found in a surrounding scope.
em(This is a misfeature.)
followed by
ifzman()
indent(tt(unset )var(pname))
An empty reference such as one of
ifzman()
@ -668,9 +674,11 @@ tt(typeset -n )var(pname)tt(=""))
acts as a placeholder. The first non-empty assignment to var(pname)
initializes the reference, and subsequently any expansions of, or
assignments to, var(pname) act on the referenced parameter.
assignments to, var(pname) act on the referenced parameter. This
is explained in the Named References section of
ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)).
texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters)
texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Named References)(Parameters)
sect(Parameters Set By The Shell)
In the parameter lists that follow, the mark `<S>' indicates that the
parameter is special. `<Z>' indicates that the parameter does not exist