lisp/erc/erc-log.el

   1 ;;; erc-log.el --- Logging facilities for ERC.
   2
   3 ;; Copyright (C) 2003-2013 Free Software Foundation, Inc.
   4
   5 ;; Author: Lawrence Mitchell <wence@gmx.li>
   6 ;; Maintainer: FSF
   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 <http://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
  97   (require 'erc-networks)
  98   (require 'cl))
  99
 100 (defgroup erc-log nil
 101   "Logging facilities for ERC."
 102   :group 'erc)
 103
 104 (defcustom erc-generate-log-file-name-function 'erc-generate-log-file-name-long
 105   "A function to generate a log filename.
 106 The function must take five arguments: BUFFER, TARGET, NICK, SERVER and PORT.
 107 BUFFER is the buffer to be saved,
 108 TARGET is the name of the channel, or the target of the query,
 109 NICK is the current nick,
 110 SERVER and PORT are the parameters that were used to connect to BUFFERs
 111 `erc-server-process'.
 112
 113 If you want to write logs into different directories, make a
 114 custom function which returns the directory part and set
 115 `erc-log-channels-directory' to its name."
 116   :group 'erc-log
 117   :type '(choice (const :tag "#channel!nick@server:port.txt"
 118                         erc-generate-log-file-name-long)
 119                  (const :tag "#channel!nick@network.txt"
 120                         erc-generate-log-file-name-network)
 121                  (const :tag "#channel.txt" erc-generate-log-file-name-short)
 122                  (const :tag "#channel@date.txt"
 123                         erc-generate-log-file-name-with-date)
 124                  (function :tag "Other function")))
 125
 126 (defcustom erc-truncate-buffer-on-save nil
 127   "Truncate any ERC (channel, query, server) buffer when it is saved."
 128   :group 'erc-log
 129   :type 'boolean)
 130
 131 (defcustom erc-enable-logging t
 132   "If non-nil, ERC will log IRC conversations.
 133 This can either be a boolean value of nil or t, or a function.
 134 If the value is a function, it will be called with one argument, the
 135 name of the current ERC buffer.  One possible function, which saves
 136 all but server buffers is `erc-log-all-but-server-buffers'.
 137
 138 This variable is buffer local.  Setting it via \\[customize] sets the
 139 default value.
 140
 141 Log files are stored in `erc-log-channels-directory'."
 142   :group 'erc-log
 143   :type '(choice boolean
 144                  function))
 145 (make-variable-buffer-local 'erc-enable-logging)
 146
 147 (defcustom erc-log-channels-directory "~/log"
 148   "The directory to place log files for channels.
 149 Leave blank to disable logging.  If not nil, all the channel
 150 buffers are logged in separate files in that directory.  The
 151 directory should not end with a trailing slash.
 152
 153 If this is the name of a function, the function will be called
 154 with the buffer, target, nick, server, and port arguments.  See
 155 `erc-generate-log-file-name-function' for a description of these
 156 arguments."
 157   :group 'erc-log
 158   :type '(choice directory
 159                  (function "Function")
 160                  (const :tag "Disable logging" nil)))
 161
 162 (defcustom erc-log-insert-log-on-open nil
 163   "Insert log file contents into the buffer if a log file exists."
 164   :group 'erc-log
 165   :type 'boolean)
 166
 167 (defcustom erc-save-buffer-on-part t
 168   "Save the channel buffer content using `erc-save-buffer-in-logs' on PART.
 169
 170 If you set this to nil, you may want to enable both
 171 `erc-log-write-after-send' and `erc-log-write-after-insert'."
 172   :group 'erc-log
 173   :type 'boolean)
 174
 175 (defcustom erc-save-queries-on-quit t
 176   "Save all query (also channel) buffers of the server on QUIT.
 177
 178 If you set this to nil, you may want to enable both
 179 `erc-log-write-after-send' and `erc-log-write-after-insert'."
 180   :group 'erc-log
 181   :type 'boolean)
 182
 183 (defcustom erc-log-write-after-send nil
 184   "If non-nil, write to log file after every message you send.
 185
 186 If you set this to nil, you may want to enable both
 187 `erc-save-buffer-on-part' and `erc-save-queries-on-quit'."
 188   :group 'erc-log
 189   :type 'boolean)
 190
 191 (defcustom erc-log-write-after-insert nil
 192   "If non-nil, write to log file when new text is added to a
 193 logged ERC buffer.
 194
 195 If you set this to nil, you may want to enable both
 196 `erc-save-buffer-on-part' and `erc-save-queries-on-quit'."
 197   :group 'erc-log
 198   :type 'boolean)
 199
 200 (defcustom erc-log-file-coding-system (if (featurep 'xemacs)
 201                                           'binary
 202                                         'emacs-mule)
 203   "The coding system ERC should use for writing log files.
 204
 205 This should ideally, be a \"catch-all\" coding system, like
 206 `emacs-mule', or `iso-2022-7bit'."
 207   :group 'erc-log)
 208
 209 (defcustom erc-log-filter-function nil
 210   "If non-nil, pass text through the given function before writing it to
 211 a log file.
 212
 213 The function should take one argument, which is the text to filter."
 214   :group 'erc-log
 215   :type '(choice (function "Function")
 216                  (const :tag "No filtering" nil)))
 217
 218
 219 ;;;###autoload (autoload 'erc-log-mode "erc-log" nil t)
 220 (define-erc-module log nil
 221   "Automatically logs things you receive on IRC into files.
 222 Files are stored in `erc-log-channels-directory'; file name
 223 format is defined through a formatting function on
 224 `erc-generate-log-file-name-function'.
 225
 226 Since automatic logging is not always a Good Thing (especially if
 227 people say things in different coding systems), you can turn logging
 228 behavior on and off with the variable `erc-enable-logging', which can
 229 also be a predicate function.  To only log when you are not set away, use:
 230
 231 \(setq erc-enable-logging
 232       (lambda (buffer)
 233         (with-current-buffer buffer
 234           (null (erc-away-time)))))"
 235   ;; enable
 236   ((when erc-log-write-after-insert
 237      (add-hook 'erc-insert-post-hook 'erc-save-buffer-in-logs))
 238    (when erc-log-write-after-send
 239      (add-hook 'erc-send-post-hook 'erc-save-buffer-in-logs))
 240    (add-hook 'erc-kill-buffer-hook 'erc-save-buffer-in-logs)
 241    (add-hook 'erc-kill-channel-hook 'erc-save-buffer-in-logs)
 242    (add-hook 'kill-emacs-hook 'erc-log-save-all-buffers)
 243    (add-hook 'erc-quit-hook 'erc-conditional-save-queries)
 244    (add-hook 'erc-part-hook 'erc-conditional-save-buffer)
 245    ;; append, so that 'erc-initialize-log-marker runs first
 246    (add-hook 'erc-connect-pre-hook 'erc-log-setup-logging 'append)
 247    (dolist (buffer (erc-buffer-list))
 248      (erc-log-setup-logging buffer)))
 249   ;; disable
 250   ((remove-hook 'erc-insert-post-hook 'erc-save-buffer-in-logs)
 251    (remove-hook 'erc-send-post-hook 'erc-save-buffer-in-logs)
 252    (remove-hook 'erc-kill-buffer-hook 'erc-save-buffer-in-logs)
 253    (remove-hook 'erc-kill-channel-hook 'erc-save-buffer-in-logs)
 254    (remove-hook 'kill-emacs-hook 'erc-log-save-all-buffers)
 255    (remove-hook 'erc-quit-hook 'erc-conditional-save-queries)
 256    (remove-hook 'erc-part-hook 'erc-conditional-save-buffer)
 257    (remove-hook 'erc-connect-pre-hook 'erc-log-setup-logging)
 258    (dolist (buffer (erc-buffer-list))
 259      (erc-log-disable-logging buffer))))
 260
 261 (define-key erc-mode-map "\C-c\C-l" 'erc-save-buffer-in-logs)
 262
 263 ;;; functionality referenced from erc.el
 264 (defun erc-log-setup-logging (buffer)
 265   "Setup the buffer-local logging variables in the current buffer.
 266 This function is destined to be run from `erc-connect-pre-hook'.
 267 The current buffer is given by BUFFER."
 268   (when (erc-logging-enabled buffer)
 269     (with-current-buffer buffer
 270       (auto-save-mode -1)
 271       (setq buffer-file-name nil)
 272       (erc-set-write-file-functions '(erc-save-buffer-in-logs))
 273       (when erc-log-insert-log-on-open
 274         (ignore-errors (insert-file-contents (erc-current-logfile))
 275                        (move-marker erc-last-saved-position
 276                                     (1- (point-max))))))))
 277
 278 (defun erc-log-disable-logging (buffer)
 279   "Disable logging in BUFFER."
 280   (when (erc-logging-enabled buffer)
 281     (with-current-buffer buffer
 282       (setq buffer-offer-save nil
 283             erc-enable-logging nil))))
 284
 285 (defun erc-log-all-but-server-buffers (buffer)
 286   "Returns t if logging should be enabled in BUFFER.
 287 Returns nil if `erc-server-buffer-p' returns t."
 288   (save-excursion
 289     (save-window-excursion
 290       (set-buffer buffer)
 291       (not (erc-server-buffer-p)))))
 292
 293 (defun erc-save-query-buffers (process)
 294   "Save all buffers of the given PROCESS."
 295   (erc-with-all-buffers-of-server process
 296                                   nil
 297                                   (erc-save-buffer-in-logs)))
 298
 299 (defun erc-conditional-save-buffer (buffer)
 300   "Save Query BUFFER if `erc-save-queries-on-quit' is t."
 301   (when erc-save-buffer-on-part
 302     (erc-save-buffer-in-logs buffer)))
 303
 304 (defun erc-conditional-save-queries (process)
 305   "Save Query buffers of PROCESS if `erc-save-queries-on-quit' is t."
 306   (when erc-save-queries-on-quit
 307     (erc-save-query-buffers process)))
 308
 309 ;; Make sure that logs get saved, even if someone overrides the active
 310 ;; process prompt for a quick exit from Emacs
 311 (defun erc-log-save-all-buffers ()
 312   (dolist (buffer (erc-buffer-list))
 313     (erc-save-buffer-in-logs buffer)))
 314
 315 ;;;###autoload
 316 (defun erc-logging-enabled (&optional buffer)
 317   "Return non-nil if logging is enabled for BUFFER.
 318 If BUFFER is nil, the value of `current-buffer' is used.
 319 Logging is enabled if `erc-log-channels-directory' is non-nil, the directory
 320 is writable (it will be created as necessary) and
 321 `erc-enable-logging' returns a non-nil value."
 322   (and erc-log-channels-directory
 323        (or (functionp erc-log-channels-directory)
 324            (erc-directory-writable-p erc-log-channels-directory))
 325        (if (functionp erc-enable-logging)
 326            (funcall erc-enable-logging (or buffer (current-buffer)))
 327          erc-enable-logging)))
 328
 329 (defun erc-log-standardize-name (filename)
 330   "Make FILENAME safe to use as the name of an ERC log.
 331 This will not work with full paths, only names.
 332
 333 Any unsafe characters in the name are replaced with \"!\".  The
 334 filename is downcased."
 335   (downcase (erc-replace-regexp-in-string
 336              "[/\\]" "!" (convert-standard-filename filename))))
 337
 338 (defun erc-current-logfile (&optional buffer)
 339   "Return the logfile to use for BUFFER.
 340 If BUFFER is nil, the value of `current-buffer' is used.
 341 This is determined by `erc-generate-log-file-name-function'.
 342 The result is converted to lowercase, as IRC is case-insensitive"
 343   (unless buffer (setq buffer (current-buffer)))
 344   (let ((target (or (buffer-name buffer) (erc-default-target)))
 345         (nick (erc-current-nick))
 346         (server erc-session-server)
 347         (port erc-session-port))
 348     (expand-file-name
 349      (erc-log-standardize-name
 350       (funcall erc-generate-log-file-name-function
 351                buffer target nick server port))
 352      (if (functionp erc-log-channels-directory)
 353          (funcall erc-log-channels-directory
 354                   buffer target nick server port)
 355        erc-log-channels-directory))))
 356
 357 (defun erc-generate-log-file-name-with-date (buffer &rest ignore)
 358   "This function computes a short log file name.
 359 The name of the log file is composed of BUFFER and the current date.
 360 This function is a possible value for `erc-generate-log-file-name-function'."
 361   (concat (buffer-name buffer) "-" (format-time-string "%Y-%m-%d") ".txt"))
 362
 363 (defun erc-generate-log-file-name-short (buffer &rest ignore)
 364   "This function computes a short log file name.
 365 In fact, it only uses the buffer name of the BUFFER argument, so
 366 you can affect that using `rename-buffer' and the-like.  This
 367 function is a possible value for
 368 `erc-generate-log-file-name-function'."
 369   (concat (buffer-name buffer) ".txt"))
 370
 371 (defun erc-generate-log-file-name-long (buffer target nick server port)
 372   "Generates a log-file name in the way ERC always did it.
 373 This results in a file name of the form #channel!nick@server:port.txt.
 374 This function is a possible value for `erc-generate-log-file-name-function'."
 375   (let ((file (concat
 376                (if target (concat target "!"))
 377                nick "@" server ":" (cond ((stringp port) port)
 378                                          ((numberp port)
 379                                           (number-to-string port))) ".txt")))
 380     ;; we need a make-safe-file-name function.
 381     (convert-standard-filename file)))
 382
 383 (defun erc-generate-log-file-name-network (buffer target nick server port)
 384   "Generates a log-file name using the network name rather than server name.
 385 This results in a file name of the form #channel!nick@network.txt.
 386 This function is a possible value for `erc-generate-log-file-name-function'."
 387   (require 'erc-networks)
 388   (let ((file (concat
 389                (if target (concat target "!"))
 390                nick "@"
 391                (or (with-current-buffer buffer (erc-network-name)) server)
 392                ".txt")))
 393     ;; we need a make-safe-file-name function.
 394     (convert-standard-filename file)))
 395
 396 ;;;###autoload
 397 (defun erc-save-buffer-in-logs (&optional buffer)
 398   "Append BUFFER contents to the log file, if logging is enabled.
 399 If BUFFER is not provided, current buffer is used.
 400 Logging is enabled if `erc-logging-enabled' returns non-nil.
 401
 402 This is normally done on exit, to save the unsaved portion of the
 403 buffer, since only the text that runs off the buffer limit is logged
 404 automatically.
 405
 406 You can save every individual message by putting this function on
 407 `erc-insert-post-hook'."
 408   (interactive)
 409   (or buffer (setq buffer (current-buffer)))
 410   (when (erc-logging-enabled buffer)
 411     (let ((file (erc-current-logfile buffer))
 412           (coding-system erc-log-file-coding-system)
 413           (inhibit-clash-detection t))  ; needed for XEmacs
 414       (save-excursion
 415         (with-current-buffer buffer
 416           (save-restriction
 417             (widen)
 418             ;; early on in the initialization, don't try and write the log out
 419             (when (and (markerp erc-last-saved-position)
 420                        (> erc-insert-marker (1+ erc-last-saved-position)))
 421               (let ((start (1+ (marker-position erc-last-saved-position)))
 422                     (end (marker-position erc-insert-marker)))
 423                 (if (functionp erc-log-filter-function)
 424                     (let ((text (buffer-substring start end)))
 425                       (with-temp-buffer
 426                         (insert (funcall erc-log-filter-function text))
 427                         (let ((coding-system-for-write coding-system))
 428                           (write-region (point-min) (point-max)
 429                                         file t 'nomessage))))
 430                   (let ((coding-system-for-write coding-system))
 431                     (write-region start end file t 'nomessage))))
 432               (if (and erc-truncate-buffer-on-save (interactive-p))
 433                   (progn
 434                     (let ((inhibit-read-only t)) (erase-buffer))
 435                     (move-marker erc-last-saved-position (point-max))
 436                     (erc-display-prompt))
 437                 (move-marker erc-last-saved-position
 438                              ;; If we place erc-last-saved-position at
 439                              ;; erc-insert-marker, because text gets
 440                              ;; inserted /before/ erc-insert-marker,
 441                              ;; the log file will not be saved
 442                              ;; (erc-last-saved-position will always
 443                              ;; be equal to erc-insert-marker).
 444                              (1- (marker-position erc-insert-marker)))))
 445             (set-buffer-modified-p nil))))))
 446   t)
 447
 448 (provide 'erc-log)
 449
 450 ;;; erc-log.el ends here
 451 ;;
 452 ;; Local Variables:
 453 ;; indent-tabs-mode: t
 454 ;; tab-width: 8
 455 ;; End: