[frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Clint Adams]

The wording is different in >= 4.0.9, but "Subscript Flags" is still the
reference.  The entire thread is available at
http://bugs.debian.org/236748

----- Forwarded message from Frederik Eaton <frederik@ugcs.caltech.edu> -----

Date: Sun, 07 Mar 2004 18:44:50 -0800
From: Frederik Eaton <frederik@ugcs.caltech.edu>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Bug#236748: zsh: associative array documentation reference broken

Package: zsh
Version: 4.0.8-1
Severity: minor

The zshparam man page says:

 For associative arrays, `[*]' or `[@]' evaluate to all the values
 (not the keys, but see Subscript Flags below), in no particular
 order.

There is nothing relevant to this syntax under Subscript Flags. My
guess is that something was moved from Subscript Flags in this page to
Parameter Expansion Flags in zshexpn. Also, it would be helpful if the
reference told the reader where to look in the referred-to section,
rather than making him read all of the entries.

The above sentence should probably read:

 For associative arrays, `[*]' or `[@]' evaluate to all the values
 (not the keys, but see the documentation for the 'k' flag under
 Parameter Expansion Flags in zshexpn(1)), in no particular order.

Thanks.

-- System Information:
Debian Release: testing/unstable
Architecture: powerpc
Kernel: Linux a5.repetae.net 2.4.22-powerpc #1 jeu déc 18 10:17:34 CET 2003 ppc
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8

Versions of packages zsh depends on:
ii  debconf                   1.2.35         Debian configuration management sy
ii  libc6                     2.3.2.ds1-11   GNU C Library: Shared libraries an
ii  libcap1                   1:1.10-12      support for getting/setting POSIX.
ii  libncurses5               5.3.20030719-4 Shared libraries for terminal hand
ii  passwd                    1:4.0.3-16     Change and administer password and

-- debconf information:
* zsh/rcmove: 


----- End forwarded message -----

Re: [frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Peter Stephenson]

Clint Adams wrote:
> The wording is different in >= 4.0.9, but "Subscript Flags" is still the
> reference.  The entire thread is available at
> http://bugs.debian.org/236748

Could someone produce a patch?  As I've been saying, I'm just snowed
under at the moment.

Thanks.

pws


**********************************************************************
This email and any files transmitted with it are confidential and
intended solely for the use of the individual or entity to whom they
are addressed. If you have received this email in error please notify
the system manager.

This footnote also confirms that this email message has been swept by
MIMEsweeper for the presence of computer viruses.

www.mimesweeper.com
**********************************************************************

Re: [frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Clint Adams]

> Could someone produce a patch?  As I've been saying, I'm just snowed
> under at the moment.

Here it is almost verbatim; should I commit it?

Index: Doc/Zsh/params.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/params.yo,v
retrieving revision 1.19
diff -u -r1.19 params.yo
--- Doc/Zsh/params.yo	30 Aug 2003 19:06:10 -0000	1.19
+++ Doc/Zsh/params.yo	8 Mar 2004 16:26:17 -0000
@@ -108,7 +108,10 @@
 `tt("$foo[*]")' evaluates to `tt("$foo[1] $foo[2] )...tt(")', whereas
 `tt("$foo[@]")' evaluates to `tt("$foo[1]" "$foo[2]" )...'.  For
 associative arrays, `tt([*])' or `tt([@])' evaluate to all the values (not
-the keys, but see em(Subscript Flags) below), in no particular order.
+the keys, but see the documentation for the `tt(k)' flag under
+ifzman(em(Parameter Expansion Flags) in zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion))
+for complete details.), in no particular order.
 When an array parameter is referenced as `tt($)var(name)' (with no
 subscript) it evaluates to `tt($)var(name)tt([*])', unless the tt(KSH_ARRAYS)
 option is set in which case it evaluates to `tt(${)var(name)tt([0]})' (for

Re: [frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Peter Stephenson]

Clint Adams wrote:
> Here it is almost verbatim; should I commit it?

Probably better to rephrase the parenthesis so that it says something
like

  For associative arrays, `tt([*])' or `tt([@])' evaluate to all the
  values, in no particular order.  Note this does not substitute
  the keys; see the documentation for the `tt(k)' flag under
  ifzman(em(Parameter Expansion Flags) in zmanref(zshexpn))\
  ifnzman(noderef(Parameter Expansion))
  for complete details.

but otherwise looks OK.  Thanks.

-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR Ltd., Science Park, Milton Road,
Cambridge, CB4 0WH, UK                          Tel: +44 (0)1223 692070


**********************************************************************
This email and any files transmitted with it are confidential and
intended solely for the use of the individual or entity to whom they
are addressed. If you have received this email in error please notify
the system manager.

This footnote also confirms that this email message has been swept by
MIMEsweeper for the presence of computer viruses.

www.mimesweeper.com
**********************************************************************

Re: [frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Clint Adams]

> Probably better to rephrase the parenthesis so that it says something
> like

Committing this then

Index: Doc/Zsh/params.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/params.yo,v
retrieving revision 1.19
diff -u -r1.19 params.yo
--- Doc/Zsh/params.yo	30 Aug 2003 19:06:10 -0000	1.19
+++ Doc/Zsh/params.yo	8 Mar 2004 16:53:20 -0000
@@ -107,8 +107,12 @@
 appear within double quotes.
 `tt("$foo[*]")' evaluates to `tt("$foo[1] $foo[2] )...tt(")', whereas
 `tt("$foo[@]")' evaluates to `tt("$foo[1]" "$foo[2]" )...'.  For
-associative arrays, `tt([*])' or `tt([@])' evaluate to all the values (not
-the keys, but see em(Subscript Flags) below), in no particular order.
+associative arrays, `tt([*])' or `tt([@])' evaluate to all the values,
+in no particular order.  Note that this does not substitute
+the keys; see the documentation for the `tt(k)' flag under
+ifzman(em(Parameter Expansion Flags) in zmanref(zshexpn))\
+ifnzman(noderef(Parameter Expansion))
+for complete details.
 When an array parameter is referenced as `tt($)var(name)' (with no
 subscript) it evaluates to `tt($)var(name)tt([*])', unless the tt(KSH_ARRAYS)
 option is set in which case it evaluates to `tt(${)var(name)tt([0]})' (for

Re: [frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Bart Schaefer]

On Mar 8, 10:23am, Clint Adams wrote:
}
}  For associative arrays, `[*]' or `[@]' evaluate to all the values
}  (not the keys, but see Subscript Flags below), in no particular
}  order.
} 
} There is nothing relevant to this syntax under Subscript Flags.

Yes, there is.  The k, K, and e subscript flags all affect the
intepretation of * and @.  It's true that [(K)*] is nearly the same
as [*], but [(k)*] is quite different, as both [(k)@] and [(K)@] are
from [@].

}  For associative arrays, `[*]' or `[@]' evaluate to all the values
}  (not the keys, but see the documentation for the 'k' flag under
}  Parameter Expansion Flags in zshexpn(1)), in no particular order.

No, this is NOT what it should say, or at least not ALL that it should
say.

Re: [frederik@ugcs.caltech.edu: Bug#236748: zsh: associative array documentation reference broken]

[Oliver Kiddle]

Bart wrote:
> On Mar 8, 10:23am, Clint Adams wrote:
> }
> }  For associative arrays, `[*]' or `[@]' evaluate to all the values
> }  (not the keys, but see Subscript Flags below), in no particular
> }  order.
> } 
> } There is nothing relevant to this syntax under Subscript Flags.
> 
> Yes, there is.  The k, K, and e subscript flags all affect the
> intepretation of * and @.  It's true that [(K)*] is nearly the same
> as [*], but [(k)*] is quite different, as both [(k)@] and [(K)@] are
> from [@].

Yes, I mentioned this in the original thread
(http://bugs.debian.org/236748), though I didn't check which flags
apply.

> }  For associative arrays, `[*]' or `[@]' evaluate to all the values
> }  (not the keys, but see the documentation for the 'k' flag under
> }  Parameter Expansion Flags in zshexpn(1)), in no particular order.
> 
> No, this is NOT what it should say, or at least not ALL that it should
> say.

I think the change as currently proposed is an improvement because it
is far easier to remember (k) and (v) as the way to control whether
keys or values are output. So the emphasis should be on the expansion
flag but it might be useful to mention the subscript flags too.

I've been meaning to make (k) and (kv) work for normal arrays too. The
subscript flags do too many different things which makes them
complicated to remember. Whether things can be changed in a backward
compatible way, I don't know but in any case changes would probably 
need the long overdue parameter code rewrite. I'll bore you with my
thoughts anyway.

The only unique feature the subscript flags offer is the ability to do
reverse subscripting (i.e. looking things up by value instead of key)
and to use pattern matching instead of exact string matches. Those two
features require just two flags (and even the latter is very similar to
${var:#pat}).

We have (k) and (v) flags to control what is returned and if an array
of results is returned, subsequent array indexing such as [1] and [-1]
would replace the abilities of (i) and (I) to return just highest and
lowest values. That'd be easier to read and easier to remember at the
expense of being more to type.

Oliver