master 61b22ae9f37 03/19: Sequester some special-variable declarations in ERC

[F. Jason Park]

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

    Sequester some special-variable declarations in ERC
    
    * lisp/erc/erc-backend.el (erc-log-p): Remove declaration entirely.
    (erc-server-reconnect): Move declaration for `erc-reuse-buffers' here.
    (erc-process-sentinel-1): Move `erc-kill-server-buffer-on-quit'
    declaration here.
    (erc--conceal-prompt): Move `erc-prompt-hidden' declaration here.
    (erc-server-INVITE): Move `erc-invitation' declaration here.
    (erc-server-PART): Move `erc-kill-buffer-on-part' declaration here.
    (erc-server-PRIVMSG): Move declarations for `erc-minibuffer-ignored',
    `erc-receive-query-display', `erc-receive-query-display-defer',
    `erc--cmem-from-nick-function', `erc-format-nick-function', and
    `erc-format-query-as-channel-p' here.
    (erc-server-401): Move `erc-whowas-on-nosuchnick' declaration here.
    (erc-server-475): Move `erc--called-as-input-p' and
    `erc-prompt-for-channel-key' declarations here.
    * lisp/erc/erc-common.el (erc-log-p): Remove declaration for
    `erc-log-p' and replace with actual definition.
    (erc-log-aux): Move `erc-dbuf' declaration from top level into
    function body.
    * lisp/erc/erc-fill.el (erc-fill--wrap-continued-message-p): Note in
    the doc string that this function produces side effects.
    * lisp/erc/erc-networks.el (erc-determine-network,
    erc-networks--copy-server-buffer-functions): Move some variable
    declarations to function body.
    (erc-settings, erc-get): Deprecate for now and explain why in doc
    strings.  We could deprecate them unconditionally, but they never
    provided usable code, and their names are short and valuable.
    * lisp/erc/erc.el (tabbar--local-hlf, motif-version-string,
    gtk-version-string): Prefer moving these single-serving declarations
    to function bodies, if only to make closures from this library less
    cluttered when debugging.  This should also help avoid stray
    declarations.
    (erc-hooks, erc-timer-hook): Revise doc strings.
    (erc-log-p): Move definition to erc-common.el.
    (erc-cmd-SV): Mimic `emacs-version' and stick with `featurep', here in
    combination with special-variable declarations, instead of `boundp' or
    similar.
    (erc-header-line-uses-tabbar-p): Explain that this has nothing to do
    with `tab-bar'.
    (erc-update-mode-line-buffer): Only assign when bound.  This has been
    verified to work with version 2.0 on EmacsWiki.
    * test/lisp/erc/erc-scenarios-base-reconnect.el: Timeouts.
    * test/lisp/erc/erc-scenarios-base-renick.el: Timeouts.
    * test/lisp/erc/resources/join/network-id/foonet-again.eld: Timeouts.
---
 lisp/erc/erc-backend.el                            | 29 +++++++++---------
 lisp/erc/erc-common.el                             |  6 ++--
 lisp/erc/erc-fill.el                               |  4 ++-
 lisp/erc/erc-networks.el                           | 23 ++++++++++++---
 lisp/erc/erc.el                                    | 34 +++++++++++++---------
 test/lisp/erc/erc-scenarios-base-reconnect.el      |  2 +-
 test/lisp/erc/erc-scenarios-base-renick.el         |  2 +-
 .../erc/resources/join/network-id/foonet-again.eld |  2 +-
 8 files changed, 64 insertions(+), 38 deletions(-)

diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el
index 7ff55de0d0c..500e025e5a1 100644
--- a/lisp/erc/erc-backend.el
+++ b/lisp/erc/erc-backend.el
@@ -101,36 +101,21 @@
 (eval-when-compile (require 'cl-lib))
 (require 'erc-common)
 
-(defvar erc--called-as-input-p)
 (defvar erc--display-context)
 (defvar erc--target)
-(defvar erc--cmem-from-nick-function)
 (defvar erc-channel-list)
 (defvar erc-channel-users)
 (defvar erc-default-nicks)
 (defvar erc-default-recipients)
 (defvar erc-ensure-target-buffer-on-privmsg)
-(defvar erc-format-nick-function)
-(defvar erc-format-query-as-channel-p)
 (defvar erc-hide-prompt)
 (defvar erc-input-marker)
 (defvar erc-insert-marker)
-(defvar erc-invitation)
 (defvar erc-join-buffer)
-(defvar erc-kill-buffer-on-part)
-(defvar erc-kill-server-buffer-on-quit)
-(defvar erc-log-p)
-(defvar erc-minibuffer-ignored)
 (defvar erc-networks--id)
 (defvar erc-nick)
 (defvar erc-nick-change-attempt-count)
-(defvar erc-prompt-for-channel-key)
-(defvar erc-prompt-hidden)
-(defvar erc-receive-query-display)
-(defvar erc-receive-query-display-defer)
-(defvar erc-reuse-buffers)
 (defvar erc-verbose-server-ping)
-(defvar erc-whowas-on-nosuchnick)
 
 (declare-function erc--init-channel-modes "erc" (channel raw-args))
 (declare-function erc--open-target "erc" (target))
@@ -816,6 +801,7 @@ Make sure you are in an ERC buffer when running this."
                   nil nil nil erc-session-client-certificate
                   erc-session-username
                   (erc-networks--id-given erc-networks--id))
+        (defvar erc-reuse-buffers)
         (unless (with-suppressed-warnings ((obsolete erc-reuse-buffers))
                   erc-reuse-buffers)
           (cl-assert (not (eq buffer (current-buffer)))))))))
@@ -1038,6 +1024,7 @@ Conditionally try to reconnect and take appropriate 
action."
           (erc-update-mode-line)
           ;; Kill server buffer if user wants it
           (set-buffer-modified-p nil)
+          (defvar erc-kill-server-buffer-on-quit)
           (when erc-kill-server-buffer-on-quit
             (kill-buffer (current-buffer))))
       ;; unexpected disconnect
@@ -1055,6 +1042,7 @@ Conditionally try to reconnect and take appropriate 
action."
   (when-let (((null erc--hidden-prompt-overlay))
              (ov (make-overlay erc-insert-marker (1- erc-input-marker)
                                nil 'front-advance)))
+    (defvar erc-prompt-hidden)
     (overlay-put ov 'display erc-prompt-hidden)
     (setq erc--hidden-prompt-overlay ov)))
 
@@ -1716,6 +1704,7 @@ add things to `%s' instead."
         (chnl (erc-response.contents parsed)))
     (pcase-let ((`(,nick ,login ,host)
                  (erc-parse-user (erc-response.sender parsed))))
+      (defvar erc-invitation)
       (setq erc-invitation chnl)
       (when (string= target (erc-current-nick))
         (erc-display-message
@@ -1888,6 +1877,7 @@ add things to `%s' instead."
         (with-suppressed-warnings ((obsolete erc-delete-default-channel))
           (erc-delete-default-channel chnl buffer))
         (erc-update-mode-line buffer)
+        (defvar erc-kill-buffer-on-part)
         (when erc-kill-buffer-on-part
           (kill-buffer buffer))))))
 
@@ -1921,6 +1911,7 @@ add things to `%s' instead."
         (cmd (erc-response.command parsed))
         (tgt (car (erc-response.command-args parsed)))
         (msg (erc-response.contents parsed)))
+    (defvar erc-minibuffer-ignored)
     (if (or (erc-ignored-user-p sender-spec)
             (erc-ignored-reply-p msg tgt proc))
         (when erc-minibuffer-ignored
@@ -1942,6 +1933,8 @@ add things to `%s' instead."
         ;; Even worth checking for empty target here? (invalid anyway)
         (unless (or buffer noticep (string-empty-p tgt) (eq ?$ (aref tgt 0))
                     (erc-is-message-ctcp-and-not-action-p msg))
+          (defvar erc-receive-query-display)
+          (defvar erc-receive-query-display-defer)
           (if privp
               (when-let ((erc-join-buffer
                           (or (and (not erc-receive-query-display-defer)
@@ -1963,6 +1956,8 @@ add things to `%s' instead."
             ;; at this point.
             (erc-update-channel-member (if privp nick tgt) nick nick
                                        privp nil nil nil nil nil host login 
nil nil t)
+            (defvar erc--cmem-from-nick-function)
+            (defvar erc-format-nick-function)
             (let ((cdata (funcall erc--cmem-from-nick-function
                                   (erc-downcase nick) sndr parsed)))
               (setq fnick (funcall erc-format-nick-function
@@ -1975,6 +1970,7 @@ add things to `%s' instead."
                                             (match-string 1 msg)))))
          (t
           (setq erc-server-last-peers (cons nick (cdr erc-server-last-peers)))
+          (defvar erc-format-query-as-channel-p)
           (setq s (erc-format-privmessage
                    (or fnick nick) msg
                    ;; If buffer is a query buffer,
@@ -2479,6 +2475,7 @@ See `erc-display-server-message'." nil
 (define-erc-response-handler (401)
   "No such nick/channel." nil
   (let ((nick/channel (cadr (erc-response.command-args parsed))))
+    (defvar erc-whowas-on-nosuchnick)
     (when erc-whowas-on-nosuchnick
       (erc-log (format "cmd: WHOWAS: %s" nick/channel))
       (erc-server-send (format "WHOWAS %s 1" nick/channel)))
@@ -2579,6 +2576,8 @@ See `erc-display-server-message'." nil
   "Channel key needed." nil
   (erc-display-message parsed '(notice error) nil 's475
                        ?c (cadr (erc-response.command-args parsed)))
+  (defvar erc-prompt-for-channel-key)
+  (defvar erc--called-as-input-p)
   (when erc-prompt-for-channel-key
     (let ((channel (cadr (erc-response.command-args parsed)))
           (erc--called-as-input-p t)
diff --git a/lisp/erc/erc-common.el b/lisp/erc/erc-common.el
index 3b138b394bd..c79954cdee5 100644
--- a/lisp/erc/erc-common.el
+++ b/lisp/erc/erc-common.el
@@ -29,9 +29,7 @@
 (defvar erc--casemapping-rfc1459)
 (defvar erc--casemapping-rfc1459-strict)
 (defvar erc-channel-users)
-(defvar erc-dbuf)
 (defvar erc-insert-this)
-(defvar erc-log-p)
 (defvar erc-modules)
 (defvar erc-send-this)
 (defvar erc-server-process)
@@ -458,6 +456,7 @@ nil."
     (if session-buffer
         (progn
           (set-buffer session-buffer)
+          (defvar erc-dbuf)
           (if (not (and erc-dbuf (bufferp erc-dbuf) (buffer-live-p erc-dbuf)))
               (progn
                 (setq erc-dbuf (get-buffer-create
@@ -473,6 +472,9 @@ nil."
           (set-buffer cb))
       (message "ERC: ** %s" string))))
 
+(defvar erc-log-p nil
+  "When non-nil, generate debug messages in an \"*ERC-DEBUG*\" buffer.")
+
 (define-inline erc-log (string)
   "Logs STRING if logging is on (see `erc-log-p')."
   (inline-quote
diff --git a/lisp/erc/erc-fill.el b/lisp/erc/erc-fill.el
index 82e881cb71c..9b0c74b518d 100644
--- a/lisp/erc/erc-fill.el
+++ b/lisp/erc/erc-fill.el
@@ -553,7 +553,9 @@ parties.")
 (defun erc-fill--wrap-continued-message-p ()
   "Return non-nil when the current speaker hasn't changed.
 That is, indicate whether the text just inserted is from the same
-sender as that of the previous \"PRIVMSG\"."
+sender as that of the previous \"PRIVMSG\".  As a side effect,
+advance `erc-fill--wrap-last-msg' unless the message has been
+marked as being ephemeral."
   (and
    (not (erc--check-msg-prop 'erc-ephemeral))
    (progn ; preserve blame for now, unprogn on next major change
diff --git a/lisp/erc/erc-networks.el b/lisp/erc/erc-networks.el
index f168c90df65..694f56ed0d5 100644
--- a/lisp/erc/erc-networks.el
+++ b/lisp/erc/erc-networks.el
@@ -42,16 +42,12 @@
 
 (defvar erc--target)
 (defvar erc-insert-marker)
-(defvar erc-kill-buffer-hook)
-(defvar erc-kill-server-hook)
 (defvar erc-modules)
 (defvar erc-rename-buffers)
 (defvar erc-reuse-buffers)
 (defvar erc-server-announced-name)
 (defvar erc-server-connected)
-(defvar erc-server-parameters)
 (defvar erc-server-process)
-(defvar erc-session-server)
 
 (declare-function erc--get-isupport-entry "erc-backend" (key &optional single))
 (declare-function erc-buffer-filter "erc" (predicate &optional proc))
@@ -1229,6 +1225,8 @@ Use the server parameter NETWORK if provided, otherwise 
parse the
 server name and search for a match in `erc-networks-alist'."
   ;; The server made it easy for us and told us the name of the NETWORK
   (declare (obsolete "maybe see `erc-networks--determine'" "29.1"))
+  (defvar erc-server-parameters)
+  (defvar erc-session-server)
   (let ((network-name (cdr (assoc "NETWORK" erc-server-parameters))))
     (if network-name
        (intern network-name)
@@ -1381,6 +1379,8 @@ already been copied over to the current, replacement 
buffer.")
 (defun erc-networks--copy-over-server-buffer-contents (existing name)
   "Kill off existing server buffer after copying its contents.
 Must be called from the replacement buffer."
+  (defvar erc-kill-buffer-hook)
+  (defvar erc-kill-server-hook)
   ;; ERC expects `erc-open' to be idempotent when setting up local
   ;; vars and other context properties for a new identity.  Thus, it's
   ;; unlikely we'll have to copy anything else over besides text.  And
@@ -1586,14 +1586,29 @@ return the host alone sans URL formatting (for 
compatibility)."
   '((pals Libera.Chat ("kensanata" "shapr" "anti\\(fuchs\\|gone\\)"))
     (format-nick-function (Libera.Chat "#emacs") erc-format-@nick))
   "Experimental: Alist of configuration options.
+
+WARNING: this variable is a vestige from a long-abandoned
+experiment.  ERC may redefine it using the same name for any
+purpose at any time.
+
 The format is (VARNAME SCOPE VALUE) where
 VARNAME is a symbol identifying the configuration option,
 SCOPE is either a symbol which identifies an entry from
   `erc-networks-alist' or a list (NET TARGET) where NET is a network symbol and
   TARGET is a string identifying the channel/query target.
 VALUE is the options value.")
+(make-obsolete-variable 'erc-settings
+                        "temporarily deprecated for later repurposing" "30.1")
 
 (defun erc-get (var &optional net target)
+  "Retrieve configuration values from `erc-settings'.
+
+WARNING: this function is a non-functioning remnant from a
+long-abandoned experiment.  ERC may redefine it using the same
+name for any purpose at any time.
+
+\(fn &rest UNKNOWN)"
+  (declare (obsolete "temporarily deprecated for later repurposing" "30.1"))
   (let ((items erc-settings)
        elt val)
     (while items
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index e39e50a7343..558b17788bf 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -191,10 +191,6 @@ front shadow any that follow.  Ignored when 
`erc--msg-props' is
 already non-nil.")
 
 ;; Forward declarations
-(defvar tabbar--local-hlf)
-(defvar motif-version-string)
-(defvar gtk-version-string)
-
 (declare-function decoded-time-period "time-date" (time))
 (declare-function iso8601-parse-duration "iso8601" (string))
 (declare-function word-at-point "thingatpt" (&optional no-properties))
@@ -1138,7 +1134,13 @@ user after \"/PART\"."
 ;; Hooks
 
 (defgroup erc-hooks nil
-  "Hook variables for fancy customizations of ERC."
+  "Hooks for ERC.
+Users of the interactive client should be aware that many of
+these hooks have names predating the modern convention of
+conveying abnormality via the \"-function\" suffix.  Users should
+likewise be aware that built-in and third-party modules use these
+hooks as well, and some of their variables may be buffer-local in
+particular sessions and/or `let'-bound for spells."
   :group 'erc)
 
 (defcustom erc-mode-hook nil
@@ -1148,9 +1150,8 @@ user after \"/PART\"."
   :options '(erc-add-scroll-to-bottom))
 
 (defcustom erc-timer-hook nil
-  "Put functions which should get called more or less periodically here.
-The idea is that servers always play ping pong with the client, and so there
-is no need for any idle-timer games with Emacs."
+  "Abnormal hook run after each response handler.
+Called with a float returned from `erc-current-time'."
   :group 'erc-hooks
   :type 'hook)
 
@@ -1450,9 +1451,8 @@ See also `erc-show-my-nick'."
 
 ;; Debugging support
 
-(defvar erc-log-p nil
-  "When set to t, generate debug messages in a separate debug buffer.")
-
+;; FIXME if this variable plays some role, indicate that here.
+;; Otherwise, deprecate.
 (defvar erc-debug-log-file (expand-file-name "ERC.debug")
   "Debug log file name.")
 
@@ -4969,9 +4969,11 @@ connection or, with -A, all applicable connections.
                             system-configuration
                             (concat
                              (cond ((featurep 'motif)
+                                    (defvar motif-version-string)
                                     (concat ", " (substring
                                                   motif-version-string 4)))
                                    ((featurep 'gtk)
+                                    (defvar gtk-version-string)
                                     (concat ", GTK+ Version "
                                             gtk-version-string))
                                    ((featurep 'x-toolkit) ", X toolkit")
@@ -8288,8 +8290,13 @@ See `erc-mode-line-format' for which characters are can 
be used."
   :type '(choice (const :tag "Disabled" nil)
                  string))
 
+;; This should optionally support the built-in `tab-bar'.
 (defcustom erc-header-line-uses-tabbar-p nil
-  "Use tabbar mode instead of the header line to display the header."
+  "Use `tabbar-mode' integration instead of the header line.
+This concerns a historical integration with the external library
+`tabbar' <https://www.emacswiki.org/emacs/tabbar.el>, which
+shouldn't be confused with the built-in `tab-bar' described in
+Info node `(emacs) Tab Bars'."
   :group 'erc-mode-line-and-header
   :type 'boolean)
 
@@ -8496,7 +8503,8 @@ buffers.  Also return nil when mode information is 
unavailable."
                         (format-spec erc-header-line-format spec)
                       nil)))
         (cond (erc-header-line-uses-tabbar-p
-               (setq-local tabbar--local-hlf header-line-format)
+               (when (boundp 'tabbar--local-hlf)
+                 (setq-local tabbar--local-hlf header-line-format))
                (kill-local-variable 'header-line-format))
               ((null header)
                (setq header-line-format nil))
diff --git a/test/lisp/erc/erc-scenarios-base-reconnect.el 
b/test/lisp/erc/erc-scenarios-base-reconnect.el
index 7bd16d1ed14..163521f4a7b 100644
--- a/test/lisp/erc/erc-scenarios-base-reconnect.el
+++ b/test/lisp/erc/erc-scenarios-base-reconnect.el
@@ -171,7 +171,7 @@
           (funcall expect 2 "Canceled")
           (funcall expect 3 "Opening connection")
           (funcall expect 2 "Password incorrect")
-          (funcall expect 2 "Connection failed!")
+          (funcall expect 10 "Connection failed!")
           (funcall expect 2 "Re-establishing connection"))
         (ert-info ("Explicitly cancel timer")
           (erc-cmd-RECONNECT "cancel")
diff --git a/test/lisp/erc/erc-scenarios-base-renick.el 
b/test/lisp/erc/erc-scenarios-base-renick.el
index 5a87e5871f7..689f962812a 100644
--- a/test/lisp/erc/erc-scenarios-base-renick.el
+++ b/test/lisp/erc/erc-scenarios-base-renick.el
@@ -267,7 +267,7 @@
 
     (ert-info ("Sync convo for rando@foonet")
       (with-current-buffer "rando@foonet"
-        (funcall expect 1 "u are dumb")
+        (funcall expect 10 "u are dumb")
         (erc-scenarios-common-say "not so")))
 
     (ert-info ("Sync convo for rando@barnet")
diff --git a/test/lisp/erc/resources/join/network-id/foonet-again.eld 
b/test/lisp/erc/resources/join/network-id/foonet-again.eld
index b230eff27c7..a8b8a52f87a 100644
--- a/test/lisp/erc/resources/join/network-id/foonet-again.eld
+++ b/test/lisp/erc/resources/join/network-id/foonet-again.eld
@@ -43,4 +43,4 @@
  (0.1 ":bob!~u@q6ddatxcq6txy.irc PRIVMSG #chan :alice: But we are spirits of 
another sort.")
  (0.1 ":alice!~u@q6ddatxcq6txy.irc PRIVMSG #chan :bob: It was not given me, 
nor I did not buy it."))
 
-((linger 6 LINGER))
+((linger 30 LINGER))