master 08ec3e89793 15/19: Rename erc-channel-users to erc-channel-members

[F. Jason Park]

branch: master
commit 08ec3e89793646787698cb5edd1681f498c266cf
Author: F. Jason Park <jp@neverwas.me>
Commit: F. Jason Park <jp@neverwas.me>

    Rename erc-channel-users to erc-channel-members
    
    * etc/ERC-NEWS: Mention name change.
    * lisp/erc/erc-backend.el (erc-process-sentinel): Don't create an
    empty `erc-channel-users' hash table in server buffers.  This is
    arguably a bug fix as well as a minor breaking change.
    * lisp/erc/erc-common.el (erc-get-channel-user,
    erc-get-channel-member): Rename and alias former to latter.
    * lisp/erc/erc.el (erc-channel-users, erc-channel-members): Rename
    former to latter.  The old name invited much confusion because the
    table's values are not mere `erc-channel-user' instances but cons
    cells that include them and their corresponding server users.
---
 etc/ERC-NEWS            | 10 ++++++++++
 lisp/erc/erc-backend.el | 11 +++++------
 lisp/erc/erc-common.el  |  5 +++--
 lisp/erc/erc.el         | 13 +++++++------
 4 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS
index 9609be7206e..bd8e95fa4ac 100644
--- a/etc/ERC-NEWS
+++ b/etc/ERC-NEWS
@@ -460,6 +460,16 @@ like "+" (for "voice"), and to avoid confusion with user 
modes, like
 "+i" (for "invisible").  Additionally, its lone parameter is now
 overloaded to accept an 'erc-channel-user' object as well as a string.
 
+*** Channel-membership table 'erc-channel-users' renamed.
+Distinguishing between 'erc-channel-user' objects and values of the
+'erc-channel-users' (plural) hash-table has been a constant source of
+confusion, even within ERC's own code base.  The hash-table's values
+are cons cells whose CDR slot is an 'erc-channel-user'.  To help keep
+things sane, 'erc-channel-users' (plural) is now officially being
+redubbed 'erc-channel-members'.  Similarly, the utility function
+'erc-get-channel-user' has been renamed to 'erc-get-channel-member'.
+Expect deprecations of the old names to follow in a future release.
+
 *** The 'erc-channel-user' struct has a changed internally.
 The five boolean slots for membership prefixes have been folded
 ("encoded") into a single integer slot.  However, the old 'setf'-able
diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el
index 1aee8cff345..0c336540483 100644
--- a/lisp/erc/erc-backend.el
+++ b/lisp/erc/erc-backend.el
@@ -104,7 +104,7 @@
 (defvar erc--display-context)
 (defvar erc--target)
 (defvar erc-channel-list)
-(defvar erc-channel-users)
+(defvar erc-channel-members)
 (defvar erc-default-nicks)
 (defvar erc-default-recipients)
 (defvar erc-ensure-target-buffer-on-privmsg)
@@ -1108,11 +1108,10 @@ Change value of property `erc-prompt' from t to 
`hidden'."
                    (setq erc-server-ping-handler nil)))
           (run-hook-with-args 'erc-disconnected-hook
                               (erc-current-nick) (system-name) "")
-          (dolist (buf (erc-buffer-filter (lambda () (boundp 
'erc-channel-users)) cproc))
-            (with-current-buffer buf
-              (when (erc--target-channel-p erc--target)
-                (setf (erc--target-channel-joined-p erc--target) nil))
-              (setq erc-channel-users (make-hash-table :test 'equal))))
+          (erc-with-all-buffers-of-server cproc (lambda () erc-channel-members)
+            (when (erc--target-channel-p erc--target)
+              (setf (erc--target-channel-joined-p erc--target) nil))
+            (clrhash erc-channel-members))
           ;; Hide the prompt
           (erc--hide-prompt cproc)
           ;; Decide what to do with the buffer
diff --git a/lisp/erc/erc-common.el b/lisp/erc/erc-common.el
index a45bdd833e8..64312e51f41 100644
--- a/lisp/erc/erc-common.el
+++ b/lisp/erc/erc-common.el
@@ -523,9 +523,10 @@ Use the CASEMAPPING ISUPPORT parameter to determine the 
style."
                      (_ erc--casemapping-rfc1459))
     (downcase string)))
 
-(define-inline erc-get-channel-user (nick)
-  "Find NICK in the current buffer's `erc-channel-users' hash table."
+(define-inline erc-get-channel-member (nick)
+  "Find NICK in the current buffer's `erc-channel-members' hash table."
   (inline-quote (gethash (erc-downcase ,nick) erc-channel-users)))
+(defalias 'erc-get-channel-user #'erc-get-channel-member)
 
 (define-inline erc-get-server-user (nick)
   "Find NICK in the current server's `erc-server-users' hash table."
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 556682b729f..d2452c5ca24 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -474,13 +474,14 @@ Functions are passed a buffer as the first argument."
   :group 'erc-hooks
   :type 'hook)
 
-
-(defvar-local erc-channel-users nil
+(defvaralias 'erc-channel-users 'erc-channel-members)
+(defvar-local erc-channel-members nil
   "Hash table of members in the current channel.
-It associates nicknames with cons cells of the form:
-\(USER . MEMBER-DATA) where USER is a pointer to an
-erc-server-user struct, and MEMBER-DATA is a pointer to an
-erc-channel-user struct.")
+It associates nicknames with cons cells of the form
+\(SERVER-USER . MEMBER-DATA), where SERVER-USER is a
+`erc-server-user' object and MEMBER-DATA is a `erc-channel-user'
+object.  Convenient abbreviations for these two components are
+`susr' and `cusr', along with `cmem' for the pair.")
 
 (defvar-local erc-server-users nil
   "Hash table of users on the current server.