lisp/erc/erc-log.el

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