lisp/erc/erc-log.el

   1 ;;; erc-log.el --- Logging facilities for ERC.
   2
   3 ;; Copyright (C) 2003-2018 Free Software Foundation, Inc.
   4
   5 ;; Author: Lawrence Mitchell <wence@gmx.li>
   6 ;; Maintainer: emacs-devel@gnu.org
   7 ;; Keywords: IRC, chat, client, Internet, logging
   8
   9 ;; Created 2003-04-26
  10 ;; Logging code taken from erc.el and modified to use markers.
  11
  12 ;; This file is part of GNU Emacs.
  13
  14 ;; GNU Emacs is free software: you can redistribute it and/or modify
  15 ;; it under the terms of the GNU General Public License as published by
  16 ;; the Free Software Foundation, either version 3 of the License, or
  17 ;; (at your option) any later version.
  18
  19 ;; GNU Emacs is distributed in the hope that it will be useful,
  20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 ;; GNU General Public License for more details.
  23
  24 ;; You should have received a copy of the GNU General Public License
  25 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
  26
  27 ;;; Commentary:
  28
  29 ;; This file implements log file writing support for ERC.
  30
  31 ;; Quick start:
  32 ;;
  33 ;; (require 'erc-log)
  34 ;; (setq erc-log-channels-directory "/path/to/logfiles") ; must be writable
  35 ;; (erc-log-enable)
  36 ;;
  37 ;; Or:
  38 ;;
  39 ;; M-x customize-variable erc-modules, and add "log".
  40 ;;
  41 ;; There are two ways to setup logging.  The first (default) method
  42 ;; will save buffers on /part, /quit, or killing the channel
  43 ;; buffer.
  44 ;;
  45 ;; The second will write to the log files on each incoming or outgoing
  46 ;; line - this may not be optimal on a laptop HDD.  To use this
  47 ;; method, add the following to the above instructions.
  48 ;;
  49 ;; (setq erc-save-buffer-on-part nil
  50 ;;       erc-save-queries-on-quit nil
  51 ;;       erc-log-write-after-send t
  52 ;;       erc-log-write-after-insert t)
  53 ;;
  54 ;; If you only want to save logs for some buffers, customize the
  55 ;; variable `erc-enable-logging'.
  56
  57 ;; How it works:
  58 ;;
  59 ;; If logging is enabled, at some point, `erc-save-buffer-in-logs'
  60 ;; will be called.  The "end" of the buffer is taken from
  61 ;; `erc-insert-marker', while `erc-last-saved-position' holds the
  62 ;; position the buffer was last saved at (as a marker, or if the
  63 ;; buffer hasn't been saved before, as the number 1 (point-min)).
  64
  65 ;; The region between `erc-last-saved-position' and
  66 ;; `erc-insert-marker' is saved to the current buffer's logfile, and
  67 ;; `erc-last-saved-position' is updated to reflect this.
  68
  69 ;;; History:
  70 ;; 2003-04-26: logging code pulled out of erc.el.  Switched to using
  71 ;; markers.
  72
  73 ;;; TODO:
  74 ;;
  75 ;; * Really, we need to lock the logfiles somehow, so that if a user
  76 ;;   is running multiple emacsen and/or on the same channel as more
  77 ;;   than one user, only one process writes to the logfile.  This is
  78 ;;   especially needed for those logfiles with no nick in them, as
  79 ;;   these would become corrupted.
  80 ;;   For a single emacs process, the problem could be solved using a
  81 ;;   variable which contained the names of buffers already being
  82 ;;   logged.  This would require that logging be buffer-local,
  83 ;;   possibly not a bad thing anyway, since many people don't want to
  84 ;;   log the server buffer.
  85 ;;   For multiple emacsen the problem is trickier.  On some systems,
  86 ;;   on could use the function `lock-buffer' and `unlock-buffer'.
  87 ;;   However, file locking isn't implemented on all platforms, for
  88 ;;   example, there is none on w32 systems.
  89 ;;   A third possibility might be to fake lockfiles.  However, this
  90 ;;   might lead to problems if an emacs crashes, as the lockfile
  91 ;;   would be left lying around.
  92
  93 ;;; Code:
  94
  95 (require 'erc)
  96 (eval-when-compile (require 'erc-networks))
  97
  98 (defgroup erc-log nil
  99   "Logging facilities for ERC."
 100   :group 'erc)
 101
 102 (defcustom erc-generate-log-file-name-function 'erc-generate-log-file-name-long
 103   "A function to generate a log filename.
 104 The function must take five arguments: BUFFER, TARGET, NICK, SERVER and PORT.
 105 BUFFER is the buffer to be saved,
 106 TARGET is the name of the channel, or the target of the query,
 107 NICK is the current nick,
 108 SERVER and PORT are the parameters that were used to connect to BUFFERs
 109 `erc-server-process'.
 110
 111 If you want to write logs into different directories, make a
 112 custom function which returns the directory part and set
 113 `erc-log-channels-directory' to its name."
 114   :group 'erc-log
 115   :type '(choice (const :tag "#channel!nick@server:port.txt"
 116                         erc-generate-log-file-name-long)
 117                  (const :tag "#channel!nick@network.txt"
 118                         erc-generate-log-file-name-network)
 119                  (const :tag "#channel.txt" erc-generate-log-file-name-short)
 120                  (const :tag "#channel@date.txt"
 121                         erc-generate-log-file-name-with-date)
 122                  (function :tag "Other function")))
 123
 124 (defcustom erc-truncate-buffer-on-save nil
 125   "Truncate any ERC (channel, query, server) buffer when it is saved."
 126   :group 'erc-log
 127   :type 'boolean)
 128
 129 (defcustom erc-enable-logging t
 130   "If non-nil, ERC will log IRC conversations.
 131 This can either be a boolean value of nil or t, or a function.
 132 If the value is a function, it will be called with one argument, the
 133 name of the current ERC buffer.  One possible function, which saves
 134 all but server buffers is `erc-log-all-but-server-buffers'.
 135
 136 This variable is buffer local.  Setting it via \\[customize] sets the
 137 default value.
 138
 139 Log files are stored in `erc-log-channels-directory'."
 140   :group 'erc-log
 141   :type '(choice boolean
 142                  function))
 143 (make-variable-buffer-local 'erc-enable-logging)
 144
 145 (defcustom erc-log-channels-directory "~/log"
 146   "The directory to place log files for channels.
 147 Leave blank to disable logging.  If not nil, all the channel
 148 buffers are logged in separate files in that directory.  The
 149 directory should not end with a trailing slash.
 150
 151 If this is the name of a function, the function will be called
 152 with the buffer, target, nick, server, and port arguments.  See
 153 `erc-generate-log-file-name-function' for a description of these
 154 arguments."
 155   :group 'erc-log
 156   :type '(choice directory
 157                  (function "Function")
 158                  (const :tag "Disable logging" nil)))
 159
 160 (defcustom erc-log-insert-log-on-open nil
 161   "Insert log file contents into the buffer if a log file exists."
 162   :group 'erc-log
 163   :type 'boolean)
 164
 165 (defcustom erc-save-buffer-on-part t
 166   "Save the channel buffer content using `erc-save-buffer-in-logs' on PART.
 167
 168 If you set this to nil, you may want to enable both
 169 `erc-log-write-after-send' and `erc-log-write-after-insert'."
 170   :group 'erc-log
 171   :type 'boolean)
 172
 173 (defcustom erc-save-queries-on-quit t
 174   "Save all query (also channel) buffers of the server on QUIT.
 175
 176 If you set this to nil, you may want to enable both
 177 `erc-log-write-after-send' and `erc-log-write-after-insert'."
 178   :group 'erc-log
 179   :type 'boolean)
 180
 181 (defcustom erc-log-write-after-send nil
 182   "If non-nil, write to log file after every message you send.
 183
 184 If you set this to nil, you may want to enable both
 185 `erc-save-buffer-on-part' and `erc-save-queries-on-quit'."
 186   :group 'erc-log
 187   :type 'boolean)
 188
 189 (defcustom erc-log-write-after-insert nil
 190   "If non-nil, write to log file when new text is added to a
 191 logged ERC buffer.
 192
 193 If you set this to nil, you may want to enable both
 194 `erc-save-buffer-on-part' and `erc-save-queries-on-quit'."
 195   :group 'erc-log
 196   :type 'boolean)
 197
 198 (defcustom erc-log-file-coding-system (if (featurep 'xemacs)
 199                                           'binary
 200                                         'emacs-mule)
 201   "The coding system ERC should use for writing log files.
 202
 203 This should ideally, be a \"catch-all\" coding system, like
 204 `emacs-mule', or `iso-2022-7bit'."
 205   :type 'coding-system
 206   :group 'erc-log)
 207
 208 (defcustom erc-log-filter-function nil
 209   "If non-nil, pass text through the given function before writing it to
 210 a log file.
 211
 212 The function should take one argument, which is the text to filter."
 213   :group 'erc-log
 214   :type '(choice (function "Function")
 215                  (const :tag "No filtering" nil)))
 216
 217
 218 ;;;###autoload (autoload 'erc-log-mode "erc-log" nil t)
 219 (define-erc-module log nil
 220   "Automatically logs things you receive on IRC into files.
 221 Files are stored in `erc-log-channels-directory'; file name
 222 format is defined through a formatting function on
 223 `erc-generate-log-file-name-function'.
 224
 225 Since automatic logging is not always a Good Thing (especially if
 226 people say things in different coding systems), you can turn logging
 227 behavior on and off with the variable `erc-enable-logging', which can
 228 also be a predicate function.  To only log when you are not set away, use:
 229
 230 \(setq erc-enable-logging
 231       (lambda (buffer)
 232         (with-current-buffer buffer
 233           (null (erc-away-time)))))"
 234   ;; enable
 235   ((when erc-log-write-after-insert
 236      (add-hook 'erc-insert-post-hook 'erc-save-buffer-in-logs))
 237    (when erc-log-write-after-send
 238      (add-hook 'erc-send-post-hook 'erc-save-buffer-in-logs))
 239    (add-hook 'erc-kill-buffer-hook 'erc-save-buffer-in-logs)
 240    (add-hook 'erc-kill-channel-hook 'erc-save-buffer-in-logs)
 241    (add-hook 'kill-emacs-hook 'erc-log-save-all-buffers)
 242    (add-hook 'erc-quit-hook 'erc-conditional-save-queries)
 243    (add-hook 'erc-part-hook 'erc-conditional-save-buffer)
 244    ;; append, so that 'erc-initialize-log-marker runs first
 245    (add-hook 'erc-connect-pre-hook 'erc-log-setup-logging 'append)
 246    (dolist (buffer (erc-buffer-list))
 247      (erc-log-setup-logging buffer)))
 248   ;; disable
 249   ((remove-hook 'erc-insert-post-hook 'erc-save-buffer-in-logs)
 250    (remove-hook 'erc-send-post-hook 'erc-save-buffer-in-logs)
 251    (remove-hook 'erc-kill-buffer-hook 'erc-save-buffer-in-logs)
 252    (remove-hook 'erc-kill-channel-hook 'erc-save-buffer-in-logs)
 253    (remove-hook 'kill-emacs-hook 'erc-log-save-all-buffers)
 254    (remove-hook 'erc-quit-hook 'erc-conditional-save-queries)
 255    (remove-hook 'erc-part-hook 'erc-conditional-save-buffer)
 256    (remove-hook 'erc-connect-pre-hook 'erc-log-setup-logging)
 257    (dolist (buffer (erc-buffer-list))
 258      (erc-log-disable-logging buffer))))
 259
 260 (define-key erc-mode-map "\C-c\C-l" 'erc-save-buffer-in-logs)
 261
 262 ;;; functionality referenced from erc.el
 263 (defun erc-log-setup-logging (buffer)
 264   "Setup the buffer-local logging variables in the current buffer.
 265 This function is destined to be run from `erc-connect-pre-hook'.
 266 The current buffer is given by BUFFER."
 267   (when (erc-logging-enabled buffer)
 268     (with-current-buffer buffer
 269       (auto-save-mode -1)
 270       (setq buffer-file-name nil)
 271       (erc-set-write-file-functions '(erc-save-buffer-in-logs))
 272       (when erc-log-insert-log-on-open
 273         (ignore-errors
 274           (save-excursion
 275             (goto-char (point-min))
 276             (insert-file-contents (erc-current-logfile)))
 277           (move-marker erc-last-saved-position
 278                        (1- (point-max))))))))
 279
 280 (defun erc-log-disable-logging (buffer)
 281   "Disable logging in BUFFER."
 282   (when (erc-logging-enabled buffer)
 283     (with-current-buffer buffer
 284       (setq buffer-offer-save nil
 285             erc-enable-logging nil))))
 286
 287 (defun erc-log-all-but-server-buffers (buffer)
 288   "Returns t if logging should be enabled in BUFFER.
 289 Returns nil if `erc-server-buffer-p' returns t."
 290   (save-excursion
 291     (save-window-excursion
 292       (set-buffer buffer)
 293       (not (erc-server-buffer-p)))))
 294
 295 (defun erc-save-query-buffers (process)
 296   "Save all buffers of the given PROCESS."
 297   (erc-with-all-buffers-of-server process
 298                                   nil
 299                                   (erc-save-buffer-in-logs)))
 300
 301 (defun erc-conditional-save-buffer (buffer)
 302   "Save Query BUFFER if `erc-save-queries-on-quit' is t."
 303   (when erc-save-buffer-on-part
 304     (erc-save-buffer-in-logs buffer)))
 305
 306 (defun erc-conditional-save-queries (process)
 307   "Save Query buffers of PROCESS if `erc-save-queries-on-quit' is t."
 308   (when erc-save-queries-on-quit
 309     (erc-save-query-buffers process)))
 310
 311 ;; Make sure that logs get saved, even if someone overrides the active
 312 ;; process prompt for a quick exit from Emacs
 313 (defun erc-log-save-all-buffers ()
 314   (dolist (buffer (erc-buffer-list))
 315     (erc-save-buffer-in-logs buffer)))
 316
 317 ;;;###autoload
 318 (defun erc-logging-enabled (&optional buffer)
 319   "Return non-nil if logging is enabled for BUFFER.
 320 If BUFFER is nil, the value of `current-buffer' is used.
 321 Logging is enabled if `erc-log-channels-directory' is non-nil, the directory
 322 is writable (it will be created as necessary) and
 323 `erc-enable-logging' returns a non-nil value."
 324   (or buffer (setq buffer (current-buffer)))
 325   (and erc-log-channels-directory
 326        (or (functionp erc-log-channels-directory)
 327            (erc-directory-writable-p erc-log-channels-directory))
 328        (if (functionp erc-enable-logging)
 329            (funcall erc-enable-logging buffer)
 330          (buffer-local-value 'erc-enable-logging buffer))))
 331
 332 (defun erc-log-standardize-name (filename)
 333   "Make FILENAME safe to use as the name of an ERC log.
 334 This will not work with full paths, only names.
 335
 336 Any unsafe characters in the name are replaced with \"!\".  The
 337 filename is downcased."
 338   (downcase (erc-replace-regexp-in-string
 339              "[/\\]" "!" (convert-standard-filename filename))))
 340
 341 (defun erc-current-logfile (&optional buffer)
 342   "Return the logfile to use for BUFFER.
 343 If BUFFER is nil, the value of `current-buffer' is used.
 344 This is determined by `erc-generate-log-file-name-function'.
 345 The result is converted to lowercase, as IRC is case-insensitive"
 346   (unless buffer (setq buffer (current-buffer)))
 347   (let ((target (or (buffer-name buffer) (erc-default-target)))
 348         (nick (erc-current-nick))
 349         (server erc-session-server)
 350         (port erc-session-port))
 351     (expand-file-name
 352      (erc-log-standardize-name
 353       (funcall erc-generate-log-file-name-function
 354                buffer target nick server port))
 355      (if (functionp erc-log-channels-directory)
 356          (funcall erc-log-channels-directory
 357                   buffer target nick server port)
 358        erc-log-channels-directory))))
 359
 360 (defun erc-generate-log-file-name-with-date (buffer &rest ignore)
 361   "This function computes a short log file name.
 362 The name of the log file is composed of BUFFER and the current date.
 363 This function is a possible value for `erc-generate-log-file-name-function'."
 364   (concat (buffer-name buffer) "-" (format-time-string "%Y-%m-%d") ".txt"))
 365
 366 (defun erc-generate-log-file-name-short (buffer &rest ignore)
 367   "This function computes a short log file name.
 368 In fact, it only uses the buffer name of the BUFFER argument, so
 369 you can affect that using `rename-buffer' and the-like.  This
 370 function is a possible value for
 371 `erc-generate-log-file-name-function'."
 372   (concat (buffer-name buffer) ".txt"))
 373
 374 (defun erc-generate-log-file-name-long (buffer target nick server port)
 375   "Generates a log-file name in the way ERC always did it.
 376 This results in a file name of the form #channel!nick@server:port.txt.
 377 This function is a possible value for `erc-generate-log-file-name-function'."
 378   (let ((file (concat
 379                (if target (concat target "!"))
 380                nick "@" server ":" (cond ((stringp port) port)
 381                                          ((numberp port)
 382                                           (number-to-string port))) ".txt")))
 383     ;; we need a make-safe-file-name function.
 384     (convert-standard-filename file)))
 385
 386 (declare-function erc-network-name "erc-networks" ())
 387
 388 (defun erc-generate-log-file-name-network (buffer target nick server port)
 389   "Generates a log-file name using the network name rather than server name.
 390 This results in a file name of the form #channel!nick@network.txt.
 391 This function is a possible value for `erc-generate-log-file-name-function'."
 392   (require 'erc-networks)
 393   (let ((file (concat
 394                (if target (concat target "!"))
 395                nick "@"
 396                (or (with-current-buffer buffer (erc-network-name)) server)
 397                ".txt")))
 398     ;; we need a make-safe-file-name function.
 399     (convert-standard-filename file)))
 400
 401 ;;;###autoload
 402 (defun erc-save-buffer-in-logs (&optional buffer)
 403   "Append BUFFER contents to the log file, if logging is enabled.
 404 If BUFFER is not provided, current buffer is used.
 405 Logging is enabled if `erc-logging-enabled' returns non-nil.
 406
 407 This is normally done on exit, to save the unsaved portion of the
 408 buffer, since only the text that runs off the buffer limit is logged
 409 automatically.
 410
 411 You can save every individual message by putting this function on
 412 `erc-insert-post-hook'."
 413   (interactive)
 414   (or buffer (setq buffer (current-buffer)))
 415   (when (erc-logging-enabled buffer)
 416     (let ((file (erc-current-logfile buffer))
 417           (coding-system erc-log-file-coding-system)
 418           (inhibit-clash-detection t))  ; needed for XEmacs
 419       (save-excursion
 420         (with-current-buffer buffer
 421           (save-restriction
 422             (widen)
 423             ;; early on in the initialization, don't try and write the log out
 424             (when (and (markerp erc-last-saved-position)
 425                        (> erc-insert-marker (1+ erc-last-saved-position)))
 426               (let ((start (1+ (marker-position erc-last-saved-position)))
 427                     (end (marker-position erc-insert-marker)))
 428                 (if (functionp erc-log-filter-function)
 429                     (let ((text (buffer-substring start end)))
 430                       (with-temp-buffer
 431                         (insert (funcall erc-log-filter-function text))
 432                         (let ((coding-system-for-write coding-system))
 433                           (write-region (point-min) (point-max)
 434                                         file t 'nomessage))))
 435                   (let ((coding-system-for-write coding-system))
 436                     (write-region start end file t 'nomessage))))
 437               (if (and erc-truncate-buffer-on-save
 438                        (called-interactively-p 'interactive))
 439                   (progn
 440                     (let ((inhibit-read-only t)) (erase-buffer))
 441                     (move-marker erc-last-saved-position (point-max))
 442                     (erc-display-prompt))
 443                 (move-marker erc-last-saved-position
 444                              ;; If we place erc-last-saved-position at
 445                              ;; erc-insert-marker, because text gets
 446                              ;; inserted /before/ erc-insert-marker,
 447                              ;; the log file will not be saved
 448                              ;; (erc-last-saved-position will always
 449                              ;; be equal to erc-insert-marker).
 450                              (1- (marker-position erc-insert-marker)))))
 451             (set-buffer-modified-p nil))))))
 452   t)
 453
 454 (provide 'erc-log)
 455
 456 ;;; erc-log.el ends here
 457 ;;
 458 ;; Local Variables:
 459 ;; indent-tabs-mode: t
 460 ;; tab-width: 8
 461 ;; End: