Function: erc-insert-line

erc-insert-line is a byte-compiled function defined in erc.el.gz.

Signature

(erc-insert-line STRING BUFFER)

Documentation

Insert STRING in an erc-mode BUFFER.

When STRING is nil, do nothing. Otherwise, start off by running erc-insert-pre-hook in BUFFER with erc-insert-this bound to t. If the latter remains non-nil afterward, insert STRING into BUFFER, ensuring a trailing newline. After that, narrow BUFFER around STRING, along with its final line ending, and run erc-insert-modify and erc-insert-post-hook, respectively. In all cases, run erc-insert-done-hook unnarrowed before exiting, and update positions in buffer-undo-list.

In general, expect to be called from a higher-level insertion function, like erc-display-message, especially when modules should consider STRING as a candidate for formatting with enhancements like indentation, fontification, timestamping, etc. Otherwise, when called directly, allow built-in modules to ignore STRING, which may make it appear incongruous in situ (unless preformatted or anticipated by third-party members of the various modification hooks).

Aliases

erc-display-line-1 (obsolete since 30.1)

Source Code

;; Defined in /usr/src/emacs/lisp/erc/erc.el.gz
(defun erc-insert-line (string buffer)
  "Insert STRING in an `erc-mode' BUFFER.
When STRING is nil, do nothing.  Otherwise, start off by running
`erc-insert-pre-hook' in BUFFER with `erc-insert-this' bound to
t.  If the latter remains non-nil afterward, insert STRING into
BUFFER, ensuring a trailing newline.  After that, narrow BUFFER
around STRING, along with its final line ending, and run
`erc-insert-modify' and `erc-insert-post-hook', respectively.  In
all cases, run `erc-insert-done-hook' unnarrowed before exiting,
and update positions in `buffer-undo-list'.

In general, expect to be called from a higher-level insertion
function, like `erc-display-message', especially when modules
should consider STRING as a candidate for formatting with
enhancements like indentation, fontification, timestamping, etc.
Otherwise, when called directly, allow built-in modules to ignore
STRING, which may make it appear incongruous in situ (unless
preformatted or anticipated by third-party members of the various
modification hooks)."
  (when string
    (with-current-buffer (or buffer (process-buffer erc-server-process))
      (let (insert-position)
        ;; Initialize ^ below to thwart rogue `erc-insert-pre-hook'
        ;; members that dare to modify the buffer's length.
        (let ((buffer-undo-list t)
              (inhibit-read-only t))
          (unless (string-suffix-p "\n" string)
            (setq string (concat string "\n"))
            (when (and erc--insert-invisible-as-intangible-p
                       (erc-string-invisible-p string))
              (erc-put-text-properties 0 (length string)
                                       '(invisible intangible) string)))
          (erc-log (concat "erc-display-message: " string
                           (format "(%S)" string) " in buffer "
                           (format "%s" buffer)))
          (setq erc-insert-this t)
          (run-hook-with-args 'erc-insert-pre-hook string)
          (setq insert-position (marker-position (or erc--insert-marker
                                                     erc-insert-marker)))
          (if (null erc-insert-this)
              ;; Leave erc-insert-this set to t as much as possible.  Fran
              ;; Litterio <franl> has seen erc-insert-this set to nil while
              ;; erc-send-pre-hook is running, which should never happen.  This
              ;; may cure it.
              (setq erc-insert-this t)
            (save-excursion ;; to restore point in the new buffer
              (save-restriction
                (widen)
                (goto-char insert-position)
                (if erc--insert-line-function
                    (funcall erc--insert-line-function string)
                  (insert string))
                (erc--assert-input-bounds)
                ;; run insertion hook, with point at restored location
                (save-restriction
                  (narrow-to-region insert-position (point))
                  (run-hooks 'erc-insert-modify-hook)
                  (run-hooks 'erc-insert-post-hook)
                  (when erc-remove-parsed-property
                    (remove-text-properties (point-min) (point-max)
                                            '(erc-parsed nil tags nil)))
                  (cl-assert (> (- (point-max) (point-min)) 1))
                  (let ((props (if erc--msg-props
                                   (erc--order-text-properties-from-hash
                                    erc--msg-props)
                                 '(erc--msg unknown))))
                    (add-text-properties (point-min) (1+ (point-min)) props)))
                (erc--refresh-prompt)))))
        (run-hooks 'erc-insert-done-hook)
        (erc-update-undo-list (- (or erc--insert-marker erc-insert-marker
                                     (point-max))
                                 insert-position))))))