[PATCH] Fix named reference documentation
Philippe Altherr <[email protected]>
| Newsgroups | gmane.comp.shells.zsh.devel |
|---|---|
| Message-ID | <CAGdYchsdu1yriE-sMo4XK0-wR9n98KiAPNFq5pdd9Q-7fh8uMA@mail.gmail.com> |
I reviewed the documentation of named references to remove all language
about subscripted references. I also made the following changes:
- Added -h as another flag compatible with -n
- Dropped "In ksh emulation, the parens around this flag are optional"
from the documentation of (!) because it gives the false impression that
${(!)name} and ${!name} are somehow related (see workers/55047
<https://zsh.org/workers/55047>).
- Fixed a paragraph that inverted pname and rname.
I have a question about section 14.3.3 "Rules":
Note that, unless the ‘(P)’ flag or a named reference is present, the flags
> and any subscripts apply directly to the value of the nested substitution;
> for example, the expansion ${${foo}} behaves exactly the same as ${foo}. *When
> a named reference or the ‘(P)’ flag is used in a nested substitution, the
> other substitution rules are applied to the value before it is interpreted
> as a name, so ${${(P)foo}} may differ from ${(P)foo}.* When both a named
> reference and the ‘(P)’ flag appear, the named reference is resolved before
> ‘(P)’ is applied.
I don't understand what the highlighted part is about. What are examples
of ${${(P)foo}} that differ from ${(P)foo} and examples of ${${ref}} that
differ from ${ref}?
- Fix named reference documentation
<https://github.com/zsh-users/zsh/compare/master...paltherr:zsh:fix-named-refs-documentation>
Philippe
fix-named-refs-documentation.txt
(text/plain, 4.8 KB)
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index ca9ba996b..b9dd8faa5 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -2037,14 +2037,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. Only the tt(-H), tt(-g), and tt(-r) flags may be used in
-conjunction with tt(-n), having their usual meanings. The tt(-u)
+created. Only the tt(-H), tt(-g), tt(-h), and tt(-r) flags may be used
+in conjunction with tt(-n), having their usual meanings. The tt(-u)
flag is special and may be applied to alter the scope of the reference.
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. It is an error for a named reference to refer
+name, but not a subscripted array (or associative array) element nor
+an array slice. It is an error for a named reference to refer
to itself, even indirectly through a chain of references. When tt(-u)
is applied to a named reference, the parameter identified by var(value)
is always found in the calling function scope rather than the current
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index cbdaddead..c5995f4e4 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -976,8 +976,7 @@ following flags are supported:
startitem()
item(tt(!))(
When the parameter being expanded is a named reference, the reference
-itself is examined and thus is em(not) resolved to its referent. In
-ksh emulation, the parens around this flag are optional.
+itself is examined and thus is em(not) resolved to its referent.
)
item(tt(#))(
Evaluate the resulting words as numeric expressions and interpret
@@ -1615,26 +1614,15 @@ Note, however, that named references to em(special) parameters acquire
the behavior of the special parameter, regardless of the scope where
the reference is declared.
-In the event that the local var(pname) goes out of scope (its declaring
-function returns) before the reference var(rname) goes out of scope,
+In the event that the local var(rname) goes out of scope (its declaring
+function returns) before the reference var(pname) goes out of scope,
the reference may change to another parameter having the same name as
-var(pname), or assignments may fail as described above. Keep the
-declaration of var(rname) as close as possible to its initialization
-to var(pname) to avoid confusion.
-
-When var(rname) includes an array subscript, the subscript expression
-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. 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
-var(arrayname), so these are equivalent:
+var(rname), or assignments may fail as described above. Keep the
+initialization of var(pname) as close as possible to the declaration of
+var(rname) to avoid confusion.
+
+When var(rname) is an array, the named reference may also be used in
+substitutions requiring an var(arrayname), so these are equivalent:
ifzman()
example(tt(${)var(name)tt(:|)var(rname)tt(})
tt(${)var(name)tt(:|)var(pname)tt(}))
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index 7d16083fb..e2db24880 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -22,10 +22,10 @@ place of any other parameter having the same name that was assigned or
declared in an earlier function scope.
(See sectref(Local Parameters)(zshparam).)
-A named parameter declared with the `tt(-n)' option to any of the
-`tt(typeset)' acts as a reference to another parameter, which may
-be at a different call level than the declaring function. When the
-`tt(-u)' option is also given, the referenced parameter is always
+A named reference declared with the `tt(-n)' option to any of the
+`tt(typeset)' commands acts as a reference to another parameter, which
+may be at a different call level than the declaring function. When
+the `tt(-u)' option is also given, the referenced parameter is always
found at a call level above the function where the reference is
declared, otherwise the reference scope is dynamic. For this reason,
it is good practice to declare a named reference as soon as the