From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Wed, 20 Oct 2021 03:52:18 -0700 Subject: [PATCH 09/28] Discourage ill-defined use of buffer targets in ERC * lisp/erc/erc.el (erc-default-recipients, erc-default-target): Explain that the variable has fallen out of favor and that the function may have been used historically by third-party code for detecting channel subscription status, even though that's never been the case internally since at least the adoption of version control. Recommend newer alternatives. (erc-add-default-channel, erc-delete-default-channel, erc-add-query, erc-delete-query): Deprecate these helpers, which rely on an unused usage variant of `erc-default-recipients'. * lisp/erc/erc-services.el: remove stray `erc-default-recipients' declaration. * lisp/erc/erc-backend.el (erc-server-NICK, erc-server-JOIN, erc-server-KICK, erc-server-PART): wrap deprecated helpers to suppress warnings. --- lisp/erc/erc-backend.el | 10 +++++++--- lisp/erc/erc-track.el | 2 -- lisp/erc/erc.el | 28 +++++++++++++++++++++++++++- 3 files changed, 34 insertions(+), 6 deletions(-) diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el index e7256cd793..e0cbe308fd 100644 --- a/lisp/erc/erc-backend.el +++ b/lisp/erc/erc-backend.el @@ -1300,7 +1300,9 @@ define-erc-response-handler erc-server-process)) (when buffer (set-buffer buffer) - (erc-add-default-channel chnl) + (with-suppressed-warnings + ((obsolete erc-add-default-channel)) + (erc-add-default-channel chnl)) (erc-server-send (format "MODE %s" chnl))) (erc-with-buffer (chnl proc) (erc-channel-begin-receiving-names)) @@ -1337,7 +1339,8 @@ define-erc-response-handler (erc-with-buffer (buffer) (erc-remove-channel-users)) - (erc-delete-default-channel ch buffer) + (with-suppressed-warnings ((obsolete erc-delete-default-channel)) + (erc-delete-default-channel ch buffer)) (erc-update-mode-line buffer)) ((string= nick (erc-current-nick)) (erc-display-message @@ -1426,7 +1429,8 @@ define-erc-response-handler (erc-with-buffer (buffer) (erc-remove-channel-users)) - (erc-delete-default-channel chnl buffer) + (with-suppressed-warnings ((obsolete erc-delete-default-channel)) + (erc-delete-default-channel chnl buffer)) (erc-update-mode-line buffer) (when erc-kill-buffer-on-part (kill-buffer buffer)))))) diff --git a/lisp/erc/erc-track.el b/lisp/erc/erc-track.el index 5755384490..6b1a70102e 100644 --- a/lisp/erc/erc-track.el +++ b/lisp/erc/erc-track.el @@ -353,8 +353,6 @@ erc-track-shorten-names (> (length s) erc-track-shorten-cutoff)) erc-track-shorten-start)) -(defvar erc-default-recipients) - (defun erc-all-buffer-names () "Return all channel or query buffer names. Note that we cannot use `erc-channel-list' with a nil argument, diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el index 0c2cbb9d82..63f7133f96 100644 --- a/lisp/erc/erc.el +++ b/lisp/erc/erc.el @@ -1847,6 +1847,17 @@ erc-buffer-list-with-nick ;; Some local variables +;; FIXME deprecate this variable +;; +;; In the ancient, pre-CVS days (prior to June 2001), this list may +;; have been used for supporting the changing of a buffer's target on +;; the fly (mid-session). Such usage, which allowed cons cells like +;; (QUERY . bob) to serve as the list's head, was either never fully +;; integrated or was partially clobbered prior to the introduction of +;; version control. But vestiges remain (see `erc-dcc-chat-mode'). +;; +;; New library code should use the `erc--target' struct instead. +;; Third-party code should consider doing so as well. (defvar-local erc-default-recipients nil "List of default recipients of the current buffer.") @@ -5834,6 +5845,18 @@ erc-nick-equal-p ;; default target handling +;; This function happens to return nil in channel buffers previously +;; parted or those from which a user had been kicked. While this +;; "works" for detecting whether a channel is currently subscribed to, +;; new code should consider using +;; +;; (erc-get-channel-user (erc-current-nick)) +;; +;; instead. For retrieving a target regardless of subscription or +;; connection status, use replacements based on `erc--target'. +;; (Coming soon.) +;; +;; TODO deprecate this (defun erc-default-target () "Return the current default target (as a character string) or nil if none." (let ((tgt (car erc-default-recipients))) @@ -5844,12 +5867,14 @@ erc-default-target (defun erc-add-default-channel (channel) "Add CHANNEL to the default channel list." + (declare (obsolete "use `erc-cmd-JOIN' or similar instead" "29.1")) (let ((chl (downcase channel))) (setq erc-default-recipients (cons chl erc-default-recipients)))) (defun erc-delete-default-channel (channel &optional buffer) "Delete CHANNEL from the default channel list." + (declare (obsolete "use `erc-cmd-PART' or similar instead" "29.1")) (with-current-buffer (if (and buffer (bufferp buffer)) buffer @@ -5861,6 +5886,7 @@ erc-add-query "Add QUERY'd NICKNAME to the default channel list. The previous default target of QUERY type gets removed." + (declare (obsolete "use `erc-cmd-QUERY' or similar instead" "29.1")) (let ((d1 (car erc-default-recipients)) (d2 (cdr erc-default-recipients)) (qt (cons 'QUERY (downcase nickname)))) @@ -5871,7 +5897,7 @@ erc-add-query (defun erc-delete-query () "Delete the topmost target if it is a QUERY." - + (declare (obsolete "use one query buffer per target instead" "29.1")) (let ((d1 (car erc-default-recipients)) (d2 (cdr erc-default-recipients))) (if (and (listp d1) -- 2.31.1