PATCH: Explain array append a bit better

PATCH: Explain array append a bit better

[Bart Schaefer]

My apologies if this is a duplicate, I was in the middle of sending it
when my desktop box briefly lost contact with the UPS due to a USB
error and decided that this meant power was failing and it needed to
shut down.  I don't see it in the archives so I presume it didn't go.

This moves the description of the "+=" assignment up to the intro where
other assignments are discussed, and explains "appending" to associative
arrays.

diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index dcca455..5833d6b 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -94,7 +94,12 @@ indent(var(name)tt(=LPAR())var(value) ...tt(RPAR()))
 
 If no parameter var(name) exists, an ordinary array parameter is created.
 If the parameter var(name) exists and is a scalar, it is replaced by a new
-array.  Ordinary array parameters may also be explicitly declared with:
+array.  To append to an array without changing the existing values, use
+the syntax:
+ifzman()
+indent(var(name)tt(+=LPAR())var(value) ...tt(RPAR()))
+
+Ordinary array parameters may also be explicitly declared with:
 findex(typeset, use of)
 ifzman()
 indent(tt(typeset -a) var(name))
@@ -110,8 +115,13 @@ indent(set -A var(name) var(key) var(value) ...)
 indent(var(name)tt(=LPAR())var(key) var(value) ...tt(RPAR()))
 
 Every var(key) must have a var(value) in this case.  Note that this
-assigns to the entire array, deleting any elements that do not appear
-in the list.
+assigns to the entire array, deleting any elements that do not appear in
+the list.  The append syntax may also be used with an associative array:
+ifzman()
+indent(var(name)tt(+=LPAR())var(key) var(value) ...tt(RPAR()))
+
+This adds a new key/value pair if the key is not already present, and
+replaces the value for the existing key if it is.
 
 To create an empty array (including associative arrays), use one of:
 ifzman()
@@ -211,7 +221,6 @@ indent(tt(unset) tt(")var(name)tt([)var(exp)tt(]"))
 
 subsect(Subscript Flags)
 cindex(subscript flags)
-
 If the opening bracket, or the comma in a range, in any subscript
 expression is directly followed by an opening parenthesis, the string up
 to the matching closing one is considered to be a list of flags, as in
@@ -351,16 +360,13 @@ patterns used for reverse subscripting (the `tt(r)', `tt(R)', `tt(i)',
 etc. flags), but it may also affect parameter substitutions that appear
 as part of an arithmetic expression in an ordinary subscript.
 
-It is possible to avoid the use of subscripts in assignments to associative
-array elements by using the syntax:
+To avoid subscript parsing limitations in assignments to associative array
+elements, use the append syntax:
 
 example(
    aa+=('key with "*strange*" characters' 'value string')
 )
 
-This adds a new key/value pair if the key is not already present, and
-replaces the value for the existing key if it is.
-
 The basic rule to remember when writing a subscript expression is that all
 text between the opening `tt([)' and the closing `tt(])' is interpreted
 em(as if) it were in double quotes (\

-- 
Barton E. Schaefer

Re: PATCH: Explain array append a bit better

[Mikael Magnusson]

On Thu, Dec 4, 2014 at 5:51 AM, Bart Schaefer <schaefer@brasslantern.com> wrote:
> My apologies if this is a duplicate, I was in the middle of sending it
> when my desktop box briefly lost contact with the UPS due to a USB
> error and decided that this meant power was failing and it needed to
> shut down.  I don't see it in the archives so I presume it didn't go.
>
> This moves the description of the "+=" assignment up to the intro where
> other assignments are discussed, and explains "appending" to associative
> arrays.

Should we perhaps mention array prepending somewhere too? I read the
sections "Array Subscripts" and "Array Element Assignment", and
searched for the string 1,0 and came up with nothing.

diff --git i/Doc/Zsh/params.yo w/Doc/Zsh/params.yo
index 5833d6b..cd09d70 100644
--- i/Doc/Zsh/params.yo
+++ w/Doc/Zsh/params.yo
@@ -99,6 +99,11 @@ the syntax:
 ifzman()
 indent(var(name)tt(+=LPAR())var(value) ...tt(RPAR()))

+To prepend to an array, use the syntax (requires that tt(KSH_ARRAYS)
+and tt(KSH_ZERO_SUBSCRIPT) are not set):
+ifzman()
+indent(var(name)tt([)var(1,0)tt(]=LPAR())var(value) ...tt(RPAR()))
+
 Ordinary array parameters may also be explicitly declared with:
 findex(typeset, use of)
 ifzman()


-- 
Mikael Magnusson

Re: PATCH: Explain array append a bit better

[Bart Schaefer]

On Dec 5,  8:28am, Mikael Magnusson wrote:
}
} Should we perhaps mention array prepending somewhere too?

I suppose, but it's a special case of array slice assignment whereas
append is a whole different assignment operator with special behavior
for associative arrays.

Consequently I think this text ...

} +To prepend to an array, use the syntax (requires that tt(KSH_ARRAYS)
} +and tt(KSH_ZERO_SUBSCRIPT) are not set):
} +ifzman()
} +indent(var(name)tt([)var(1,0)tt(]=LPAR())var(value) ...tt(RPAR()))

... ought to be in "15.2.2 Array Element Assignment" rather than in
the introductory paragraphs in "15.2 Array Parameters".  Otherwise
you're introducing subscript assignment syntax without having told
the reader what it means.

Re: PATCH: Explain array append a bit better

[Oliver Kiddle]

Mikael Magnusson wrote:
> Should we perhaps mention array prepending somewhere too? I read the
> sections "Array Subscripts" and "Array Element Assignment", and
> searched for the string 1,0 and came up with nothing.

I think that was left undocumented intentionally in the first place. I
could be wrong but, in the code, it looks like behaviour that fell out
of the implementation rather than something that was designed in. It
isn't exactly nice and I wouldn't ever use it in scripts. Interactively,
I have an abbreviation for it that I rarely use but also have aliases
like: alias -- +fpath='fpath=( ~+ $fpath)'

I don't really have an opinion either way on whether we should document
it now. I'd prefer to see some other syntax introduced. When we last
discussed prepending (30962), []= was the best suggestion we had
but needs to touch the current subscript code so is trickier to to
implement. -= ^= and /= were rejected before.

Another option that occurs to me now is
  +var=( ... )

Oliver