diff options
author | Bart Schaefer <schaefer@zsh.org> | 2023-02-12 11:25:42 -0800 |
---|---|---|
committer | Bart Schaefer <schaefer@zsh.org> | 2023-02-12 11:25:42 -0800 |
commit | 102145b0487ddd7d2a048a0787b79146434d2cd6 (patch) | |
tree | d853cde249ea4c2cce901ff8dc5612c18fcb0c92 /Doc/Zsh/params.yo | |
parent | 143e153259efbb6b6b0d804b753bc2a69e422660 (diff) | |
download | zsh-102145b0487ddd7d2a048a0787b79146434d2cd6.tar.gz zsh-102145b0487ddd7d2a048a0787b79146434d2cd6.tar.xz zsh-102145b0487ddd7d2a048a0787b79146434d2cd6.zip |
51362: Begin documentation for named references.
Diffstat (limited to 'Doc/Zsh/params.yo')
-rw-r--r-- | Doc/Zsh/params.yo | 46 |
1 files changed, 45 insertions, 1 deletions
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index 55009c6de..2dfd5bd14 100644 --- a/Doc/Zsh/params.yo +++ b/Doc/Zsh/params.yo @@ -80,6 +80,7 @@ startmenu() menu(Array Parameters) menu(Positional Parameters) menu(Local Parameters) +menu(Named References) menu(Parameters Set By The Shell) menu(Parameters Used By The Shell) endmenu() @@ -592,7 +593,7 @@ array assignment of the form `var(n)tt(=LPAR())var(value) ...tt(RPAR())' is 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)(Parameters Set By The Shell)(Positional Parameters)(Parameters) +texinode(Local Parameters)(Named References)(Positional Parameters)(Parameters) sect(Local Parameters) Shell function executions delimit scopes for shell parameters. (Parameters are dynamically scoped.) The tt(typeset) builtin, and its @@ -626,6 +627,49 @@ 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. +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() +example(tt(typeset )var(name)tt(=)var(rname) +tt(print -r -- ${LPAR()P)tt(RPAR())var(name)tt(})) +ifzman() +example(tt(typeset -n )var(pname)tt(=)var(rname) +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)). + +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: +ifzman() +example(tt(typeset +n )var(pname) +tt(unset )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.) + +An empty reference such as one of +ifzman() +example(tt(typeset -n )var(pname) +tt(typeset -n )var(pname)tt(=) +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. + texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Local Parameters)(Parameters) sect(Parameters Set By The Shell) In the parameter lists that follow, the mark `<S>' indicates that the |