From 231cbbc5b12f9d7135fea1e9015c100dffba91e0 Mon Sep 17 00:00:00 2001 From: "Barton E. Schaefer" Date: Thu, 4 Dec 2014 02:17:58 -0800 Subject: 33841: explain array append a bit better --- ChangeLog | 6 +++++- Doc/Zsh/params.yo | 24 +++++++++++++++--------- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/ChangeLog b/ChangeLog index fad5d820d..c03501faf 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2014-12-04 Barton E. Schaefer + + * 33841: Doc/Zsh/params.yo: explain array append a bit better + 2014-12-03 Mikael Magnusson * Eric Cook: 33689: Completion/Unix/Command/_cp: make cp @@ -23,7 +27,7 @@ Src/exec.c, Src/sort.c, Src/utils.c: fix types passed to sizeof detected by coverity as being wrong -2014-11-28 Barton E. Schaefer +2014-11-28 Barton E. Schaefer * 33819: Test/A06assign.ztst: regression tests for 33816 diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo index dcca455d8..5833d6be9 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 (\ -- cgit 1.4.1