GNU bug report logs - #6599
23.2; cl.texi docs loop hash-values

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6599 in the body.
You can then email your comments to 6599 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Kevin Ryde <user42 <at> zip.com.au>
To: bug-gnu-emacs <at> gnu.org
Subject: 23.2; cl.texi docs loop hash-values
Date: Sat, 10 Jul 2010 09:58:03 +1000

[Message part 1 (text/plain, inline)]

In the cl.texi docs for the `loop' macro I had to read a few times
before noticing the way hash values are accessed.  I think showing as
items and adding an example would make it easier for the newcomer :-).

2010-07-09  Kevin Ryde  <user42 <at> zip.com.au>

	* cl.texi (For Clauses): @items for hash-values and key-bindings
	to make them more visible when skimming.  Add examples of `using'
	clause to them, examples being clearer than a description in
	words.

[cl.texi.hash-values.diff (text/x-diff, inline)]

--- cl.texi.~1.15.~	2009-11-27 18:28:09.000000000 +1100
+++ cl.texi	2010-07-10 09:50:54.000000000 +1000
@@ -2476,22 +2476,33 @@
 or @code{while}.
 
 @item for @var{var} being the hash-keys of @var{hash-table}
-This clause iterates over the entries in @var{hash-table}.  For each
-hash table entry, @var{var} is bound to the entry's key.  If you write
-@samp{the hash-values} instead, @var{var} is bound to the values
-of the entries.  The clause may be followed by the additional
-term @samp{using (hash-values @var{var2})} (where @code{hash-values}
-is the opposite word of the word following @code{the}) to cause
-@var{var} and @var{var2} to be bound to the two parts of each
-hash table entry.
+@itemx for @var{var} being the hash-values of @var{hash-table}
+This clause iterates over the entries in @var{hash-table} with
+@var{var} bound to each key, or value.  A @samp{using} clause can bind
+a second variable to the opposite part.
+
+@example
+(loop for k being the hash-keys of h
+            using (hash-values v)
+      do
+      (message "key %S -> value %S" k v))
+@end example
 
 @item for @var{var} being the key-codes of @var{keymap}
+@itemx for @var{var} being the key-bindings of @var{keymap}
 This clause iterates over the entries in @var{keymap}.
 The iteration does not enter nested keymaps but does enter inherited
 (parent) keymaps.
-You can use @samp{the key-bindings} to access the commands bound to
-the keys rather than the key codes, and you can add a @code{using}
-clause to access both the codes and the bindings together.
+A @code{using} clause can access both the codes and the bindings
+together.
+
+@example
+(loop for c being the key-codes of (current-local-map)
+            using (key-bindings b)
+      do
+      (message "key %S -> binding %S" c b))
+@end example
+
 
 @item for @var{var} being the key-seqs of @var{keymap}
 This clause iterates over all key sequences defined by @var{keymap}

[Message part 3 (text/plain, inline)]

In GNU Emacs 23.2.1 (i486-pc-linux-gnu, GTK+ Version 2.20.0)
 of 2010-05-16 on raven, modified by Debian
configured using `configure  '--build' 'i486-linux-gnu' '--build' 'i486-linux-gnu' '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib' '--localstatedir=/var/lib' '--infodir=/usr/share/info' '--mandir=/usr/share/man' '--with-pop=yes' '--enable-locallisppath=/etc/emacs23:/etc/emacs:/usr/local/share/emacs/23.2/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/23.2/site-lisp:/usr/share/emacs/site-lisp:/usr/share/emacs/23.2/leim' '--with-x=yes' '--with-x-toolkit=gtk' '--with-toolkit-scroll-bars' 'build_alias=i486-linux-gnu' 'CFLAGS=-DDEBIAN -g -O2' 'LDFLAGS=-g' 'CPPFLAGS=''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_AU
  value of $XMODIFIERS: nil
  locale-coding-system: iso-latin-1-unix
  default enable-multibyte-characters: t

Message #12 received at 6599 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Kevin Ryde <user42 <at> zip.com.au>
Cc: 6599 <at> debbugs.gnu.org
Subject: Re: 23.2; cl.texi docs loop hash-values
Date: Sun, 03 Jul 2011 14:41:52 +0200

Kevin Ryde <user42 <at> zip.com.au> writes:

> In the cl.texi docs for the `loop' macro I had to read a few times
> before noticing the way hash values are accessed.  I think showing as
> items and adding an example would make it easier for the newcomer :-).

Yes, I think your version clarifies things greatly.

I've applied it to Emacs 24.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.