Function: erc-display-message

erc-display-message is a byte-compiled function defined in erc.el.gz.

Signature

(erc-display-message PARSED TYPE BUFFER MSG &rest ARGS)

Documentation

Display MSG in BUFFER.

Insert MSG or text derived from MSG into an ERC buffer, possibly after applying formatting by way of either a format-spec known to a message-catalog entry or a TYPE known to a specialized string handler. Additionally, derive metadata, faces, and other text properties from the various overloaded parameters, such as PARSED, when it's an erc-response object, and MSG, when it's a key (symbol) for a "message catalog" entry. Expect ARGS, when applicable, to be format-spec args known to such an entry, and TYPE, when non-nil, to be a symbol handled by erc-display-message-highlight (necessarily accompanied by a string MSG). Expect BUFFER to be among the sort accepted by the function erc-display-line.

When non-nil, expect BUFFER to be a live erc-mode buffer, a list of such buffers, or the symbols all or active. If all, insert STRING in all buffers for the current session. If active, defer to the function erc-active-buffer(var)/erc-active-buffer(fun), which may return the session's server buffer if the previously active buffer has been killed. If BUFFER is nil or a network process, pretend it's set to the appropriate server buffer. Otherwise, use the current buffer.

When TYPE is a list of symbols, call handlers from left to right without influencing how they behave when encountering existing faces. As of ERC 5.6, expect a TYPE of (notice error) to insert MSG with font-lock-face as erc-error-face throughout. However, when the list of symbols begins with t, tell compatible handlers to compose rather than clobber faces. For example, expect a TYPE of (t notice error) to result in font-lock-face being (erc-error-face erc-notice-face) throughout MSG when erc-notice-highlight-type is left at its default, all.

As of ERC 5.6, assume third-party code will use this function instead of lower-level ones, like erc-insert-line, to insert arbitrary informative messages as if sent by the server. That is, tell modules to treat a "local" message for which PARSED is nil like any other server-sent message. Finally, expect users to treat the return value of this function as undefined even though various default response handlers may appear to presume nil.

Source Code

;; Defined in /usr/src/emacs/lisp/erc/erc.el.gz
(defun erc-display-message (parsed type buffer msg &rest args)
  "Display MSG in BUFFER.

Insert MSG or text derived from MSG into an ERC buffer, possibly
after applying formatting by way of either a `format-spec' known
to a message-catalog entry or a TYPE known to a specialized
string handler.  Additionally, derive metadata, faces, and other
text properties from the various overloaded parameters, such as
PARSED, when it's an `erc-response' object, and MSG, when it's a
key (symbol) for a \"message catalog\" entry.  Expect ARGS, when
applicable, to be `format-spec' args known to such an entry, and
TYPE, when non-nil, to be a symbol handled by
`erc-display-message-highlight' (necessarily accompanied by a
string MSG).  Expect BUFFER to be among the sort accepted by the
function `erc-display-line'.

When non-nil, expect BUFFER to be a live `erc-mode' buffer, a
list of such buffers, or the symbols `all' or `active'.  If
`all', insert STRING in all buffers for the current session.  If
`active', defer to the function `erc-active-buffer', which may
return the session's server buffer if the previously active
buffer has been killed.  If BUFFER is nil or a network process,
pretend it's set to the appropriate server buffer.  Otherwise,
use the current buffer.

When TYPE is a list of symbols, call handlers from left to right
without influencing how they behave when encountering existing
faces.  As of ERC 5.6, expect a TYPE of (notice error) to insert
MSG with `font-lock-face' as `erc-error-face' throughout.
However, when the list of symbols begins with t, tell compatible
handlers to compose rather than clobber faces.  For example,
expect a TYPE of (t notice error) to result in `font-lock-face'
being (erc-error-face erc-notice-face) throughout MSG when
`erc-notice-highlight-type' is left at its default, `all'.

As of ERC 5.6, assume third-party code will use this function
instead of lower-level ones, like `erc-insert-line', to insert
arbitrary informative messages as if sent by the server.  That
is, tell modules to treat a \"local\" message for which PARSED is
nil like any other server-sent message.  Finally, expect users to
treat the return value of this function as undefined even though
various default response handlers may appear to presume nil."
  (let* ((erc--msg-props
          (or erc--msg-props
              (let ((table (make-hash-table))
                    (cmd (and parsed (erc--get-eq-comparable-cmd
                                      (erc-response.command parsed)))))
                (puthash 'erc--msg
                         (cond ((and msg (symbolp msg)) msg)
                               (type (pcase type
                                       ((pred symbolp) type)
                                       ((pred listp)
                                        (intern (mapconcat #'prin1-to-string
                                                           type "-")))
                                       (_ 'unknown)))
                               (t 'unknown))
                         table)
                (when cmd
                  (puthash 'erc--cmd cmd table))
                (when erc--msg-prop-overrides
                  (pcase-dolist (`(,k . ,v) (reverse erc--msg-prop-overrides))
                    (when v (puthash k v table))))
                table)))
         (erc-message-parsed parsed)
         (string (if (symbolp msg) (apply #'erc-format-message msg args) msg)))
    (setq string
          (cond
           ((null type)
            string)
           ((listp type)
            (let ((erc--merge-text-properties-p
                   (and (eq (car type) t) (setq type (cdr type)))))
              (dolist (type type)
                (setq string (erc-display-message-highlight type string))))
            string)
           ((symbolp type)
            (erc-display-message-highlight type string))))

    (if (not (erc-response-p parsed))
        (erc--route-insertion string buffer)
      (unless (erc-hide-current-message-p parsed)
        (erc-put-text-property 0 (length string) 'erc-parsed parsed string)
	(when (erc-response.tags parsed)
	  (erc-put-text-property 0 (length string) 'tags (erc-response.tags parsed)
				 string))
        (erc--route-insertion string buffer)))))