PATCH: nested substitution documentation

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>]

This is more or less the explanation I gave in my last message of the way
nested subsitution currently works.

One thing is a little inconsistent: if $foo is an array, "${foo[1]}"
produces the first word of foo (this is certainly correct), but
"${${(@)foo}[1]}" produces the first character.  I wanted to say `the
result of a nested substitution is treated exactly as if came directly from
a scalar or array parameter', but that's not true in this case.  Maybe all
array values should be subscripted word-wise by the next enclosing
substitution, regardless of double quotes.  But then how do you index on
characters?  And is this (which was my guess of how to do it) right:

% foo=(bar baz)
% print ${foo[@][1]}
bar
% print "${foo[@][1]}"
bar

([*] does the same in both cases)?  "${foo[1][1]}" does work the way I
would expect.

--- Doc/Zsh/expn.yo.nest	Mon Mar  1 09:53:19 1999
+++ Doc/Zsh/expn.yo	Wed Mar 17 11:51:19 1999
@@ -494,6 +494,12 @@
 substitues the value of tt($foo) with both tt(head) and tt(tail)
 deleted.  The form with tt($LPAR())...tt(RPAR()) is often useful in
 combination with the flags described next; see the example below.
+
+Note that when nested parameter expansion takes place the flags are em(not)
+propagated back.  Each level of expansion uses three factors: whether it
+is in double quotes, what flags it has been provided with, and whether the
+value it has is a scalar or an array.  Some examples are given below.
+
 subsect(Parameter Expansion Flags)
 cindex(parameter expansion flags)
 cindex(flags, parameter expansion)
@@ -693,7 +699,7 @@
 Include the length of the match in the result.
 )
 enditem()
-subsect(Example)
+subsect(Examples)
 The flag tt(f) is useful to split a double-quoted substitution line by
 line.  For example, `tt("${(f)$LPAR()<)var(file)tt(RPAR()}")'
 substitutes the contents of var(file) divided so that each line is
@@ -701,6 +707,28 @@
 `tt($)tt(LPAR()<)var(file)tt(RPAR())' alone, which divides the file
 up by words, or the same inside double quotes, which makes the entire
 content of the file a single string.
+
+The following illustrates the rules for nested parameter expansions.
+Suppose that tt($foo) contains the array tt(LPAR()bar baz)tt(RPAR()):
+startitem()
+item(tt("${(@)${foo}[1]}"))(
+This produces the result tt(bar baz).  First, the inner substitution
+tt("${foo}"), which has no array (tt(@)) flag, produces a single word
+result.  The outer substitution tt("${(@)...[1]}") acts on this result as
+if it were a one word array, because of the array flag, so the result is
+just that single word.
+)
+item(tt("${${(@)foo}[1]}"))(
+The produces the result tt(b).  In this case, the inner substitution
+tt("${(@)foo}") produces the array tt(LPAR()bar baz)tt(RPAR()).  The outer
+substitution tt("${...[1]}"), however, has no array flag, so that it joins
+the array it has to a single word and indexes as if it were a string.  Note
+that this is not identical to the case tt("${foo[1]}"), since here the
+expression tt(foo[1]) is recognised immediately as an index into an array,
+so that the result in that case is tt(bar).
+)
+enditem()
+
 texinode(Command Substitution)(Arithmetic Expansion)(Parameter Expansion)(Expansion)
 sect(Command Substitution)
 cindex(command substitution)

-- 
Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy