lisp/savehist.el

   1 ;;; savehist.el --- Save minibuffer history.
   2
   3 ;; Copyright (C) 1997, 2005, 2006 Free Software Foundation
   4
   5 ;; Author: Hrvoje Niksic <hniksic@xemacs.org>
   6 ;; Keywords: minibuffer
   7 ;; Version: 24
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  24 ;; Boston, MA 02110-1301, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; Many editors (e.g. Vim) have the feature of saving minibuffer
  29 ;; history to an external file after exit.  This package provides the
  30 ;; same feature in Emacs.  When set up, it saves recorded minibuffer
  31 ;; histories to a file (`~/.emacs-history' by default).  Additional
  32 ;; variables may be specified by customizing
  33 ;; `savehist-additional-variables'.
  34
  35 ;; To use savehist, turn on savehist-mode by putting the following in
  36 ;; `~/.emacs':
  37 ;;
  38 ;;     (savehist-mode 1)
  39 ;;
  40 ;; or with customize: `M-x customize-option RET savehist-mode RET'.
  41 ;;
  42 ;; You can also explicitly save history with `M-x savehist-save' and
  43 ;; load it by loading the `savehist-file' with `M-x load-file'.
  44
  45 ;; If you are using a version of Emacs that does not ship with this
  46 ;; package, be sure to have `savehist.el' in a directory that is in
  47 ;; your load-path, and to byte-compile it.
  48
  49 ;;; Code:
  50
  51 (require 'custom)
  52 (eval-when-compile
  53   (require 'cl))
  54
  55 ;; User variables
  56
  57 (defgroup savehist nil
  58   "Save minibuffer history."
  59   :group 'minibuffer)
  60
  61 ;;;###autoload
  62 (defcustom savehist-mode nil
  63   "Mode for automatic saving of minibuffer history.
  64 Set this by calling the `savehist-mode' function or using the customize
  65 interface."
  66   :type 'boolean
  67   :set (lambda (symbol value) (savehist-mode (or value 0)))
  68   :initialize 'custom-initialize-default
  69   :require 'savehist
  70   :group 'savehist)
  71
  72 (defcustom savehist-save-minibuffer-history t
  73   "*If non-nil, save all recorded minibuffer histories.
  74 If you want to save only specific histories, use `savehist-save-hook' to
  75 modify the value of `savehist-minibuffer-history-variables'."
  76   :type 'boolean
  77   :group 'savehist)
  78
  79 (defcustom savehist-additional-variables ()
  80   "*List of additional variables to save.
  81 Each element is a symbol whose value will be persisted across Emacs
  82 sessions that use savehist.  The contents of variables should be
  83 printable with the Lisp printer.  You don't need to add minibuffer
  84 history variables to this list, all minibuffer histories will be
  85 saved automatically as long as `savehist-save-minibuffer-history' is
  86 non-nil.
  87
  88 User options should be saved with the customize interface.  This
  89 list is useful for saving automatically updated variables that are not
  90 minibuffer histories, such as `compile-command' or `kill-ring'."
  91   :type '(repeat variable)
  92   :group 'savehist)
  93
  94 (defcustom savehist-file
  95   (cond
  96    ;; Backward compatibility with previous versions of savehist.
  97    ((file-exists-p "~/.emacs-history") "~/.emacs-history")
  98    ((and (not (featurep 'xemacs)) (file-directory-p "~/.emacs.d/"))
  99     "~/.emacs.d/history")
 100    ((and (featurep 'xemacs) (file-directory-p "~/.xemacs/"))
 101     "~/.xemacs/history")
 102    ;; For users without `~/.emacs.d/' or `~/.xemacs/'.
 103    (t "~/.emacs-history"))
 104   "*File name where minibuffer history is saved to and loaded from.
 105 The minibuffer history is a series of Lisp expressions loaded
 106 automatically when `savehist-mode' is turned on.  See `savehist-mode'
 107 for more details.
 108
 109 If you want your minibuffer history shared between Emacs and XEmacs,
 110 customize this value and make sure that `savehist-coding-system' is
 111 set to a coding system that exists in both emacsen."
 112   :type 'file
 113   :group 'savehist)
 114
 115 (defcustom savehist-file-modes #o600
 116   "*Default permissions of the history file.
 117 This is decimal, not octal.  The default is 384 (0600 in octal).
 118 Set to nil to use the default permissions that Emacs uses, typically
 119 mandated by umask.  The default is a bit more restrictive to protect
 120 the user's privacy."
 121   :type 'integer
 122   :group 'savehist)
 123
 124 (defcustom savehist-autosave-interval (* 5 60)
 125   "*The interval between autosaves of minibuffer history.
 126 If set to nil, disables timer-based autosaving."
 127   :type 'integer
 128   :group 'savehist)
 129
 130 (defcustom savehist-mode-hook nil
 131   "Hook called when `savehist-mode' is turned on."
 132   :type 'hook
 133   :group 'savehist)
 134
 135 (defcustom savehist-save-hook nil
 136   "Hook called by `savehist-save' before saving the variables.
 137 You can use this hook to influence choice and content of variables to
 138 save."
 139   :type 'hook
 140   :group 'savehist)
 141
 142 ;; This should be capable of representing characters used by Emacs.
 143 ;; We prefer UTF-8 over ISO 2022 because it is well-known outside
 144 ;; Mule.  XEmacs prir to 21.5 had UTF-8 provided by an external
 145 ;; package which may not be loaded, which is why we check for version.
 146 (defvar savehist-coding-system (if (and (featurep 'xemacs)
 147                                         (<= emacs-major-version 21)
 148                                         (< emacs-minor-version 5))
 149                                    'iso-2022-8 'utf-8)
 150   "The coding system savehist uses for saving the minibuffer history.
 151 Changing this value while Emacs is running is supported, but considered
 152 unwise, unless you know what you are doing.")
 153
 154 ;; Internal variables.
 155
 156 (defvar savehist-timer nil)
 157
 158 (defvar savehist-last-checksum nil)
 159
 160 (defvar savehist-minibuffer-history-variables nil
 161   "List of minibuffer histories.
 162 The contents of this variable is built while Emacs is running, and saved
 163 along with minibuffer history.  You can change its value off
 164 `savehist-save-hook' to influence which variables are saved.")
 165
 166 (defconst savehist-no-conversion (if (featurep 'xemacs) 'binary 'no-conversion)
 167   "Coding system without any conversion.
 168 This is used for calculating an internal checksum.  Should be as fast
 169 as possible, ideally simply exposing the internal representation of
 170 buffer text.")
 171
 172 (defvar savehist-loaded nil
 173   "Whether the history has already been loaded.
 174 This prevents toggling `savehist-mode' from destroying existing
 175 minibuffer history.")
 176
 177 (when (featurep 'xemacs)
 178   ;; Must declare this under XEmacs, which doesn't have built-in
 179   ;; minibuffer history truncation.
 180   (defvar history-length 100))
 181 \f
 182 ;; Functions.
 183
 184 ;;;###autoload
 185 (defun savehist-mode (arg)
 186   "Toggle savehist-mode.
 187 Positive ARG turns on `savehist-mode'.  When on, savehist-mode causes
 188 minibuffer history to be saved periodically and when exiting Emacs.
 189 When turned on for the first time in an Emacs session, it causes the
 190 previous minibuffer history to be loaded from `savehist-file'.
 191
 192 This mode should normally be turned on from your Emacs init file.
 193 Calling it at any other time replaces your current minibuffer histories,
 194 which is probably undesirable."
 195   (interactive "P")
 196   (setq savehist-mode
 197         (if (null arg)
 198             (not savehist-mode)
 199           (> (prefix-numeric-value arg) 0)))
 200   (if (not savehist-mode)
 201       (savehist-uninstall)
 202     (when (and (not savehist-loaded)
 203                (file-exists-p savehist-file))
 204       (condition-case errvar
 205           (progn
 206             ;; Don't set coding-system-for-read -- we rely on the
 207             ;; coding cookie to convey that information.  That way, if
 208             ;; the user changes the value of savehist-coding-system,
 209             ;; we can still correctly load the old file.
 210             (load savehist-file nil (not (interactive-p)))
 211             (setq savehist-loaded t))
 212         (error
 213          ;; Don't install the mode if reading failed.  Doing so would
 214          ;; effectively destroy the user's data at the next save.
 215          (setq savehist-mode nil)
 216          (savehist-uninstall)
 217          (signal (car errvar) (cdr errvar)))))
 218     (savehist-install)
 219     (run-hooks 'savehist-mode-hook))
 220   ;; Return the new setting.
 221   savehist-mode)
 222 (add-minor-mode 'savehist-mode "")
 223
 224 (defun savehist-load ()
 225   "Obsolete function provided for transition from old versions of savehist.
 226 Don't call this from new code, use (savehist-mode 1) instead.
 227
 228 This function loads the variables stored in `savehist-file' and turns on
 229 `savehist-mode'.  If `savehist-file' is in the old format that doesn't
 230 record the value of `savehist-minibuffer-history-variables', that value
 231 is deducted from the contents of the file."
 232   (savehist-mode 1)
 233   ;; Old versions of savehist distributed with XEmacs didn't save
 234   ;; savehist-minibuffer-history-variables.  If that variable is nil
 235   ;; after loading the file, try to intuit the intended value.
 236   (when (null savehist-minibuffer-history-variables)
 237     (setq savehist-minibuffer-history-variables
 238           (with-temp-buffer
 239             (ignore-errors
 240               (insert-file-contents savehist-file))
 241             (let ((vars ()) form)
 242               (while (setq form (condition-case nil
 243                                     (read (current-buffer)) (error nil)))
 244                 ;; Each form read is of the form (setq VAR VALUE).
 245                 ;; Collect VAR, i.e. (nth form 1).
 246                 (push (nth 1 form) vars))
 247               vars)))))
 248 (make-obsolete 'savehist-load 'savehist-mode)
 249
 250 (defun savehist-install ()
 251   "Hook savehist into Emacs.
 252 Normally invoked by calling `savehist-mode' to set the minor mode.
 253 Installs `savehist-autosave' in `kill-emacs-hook' and on a timer.
 254 To undo this, call `savehist-uninstall'."
 255   (add-hook 'minibuffer-setup-hook 'savehist-minibuffer-hook)
 256   (add-hook 'kill-emacs-hook 'savehist-autosave)
 257   ;; Install an invocation of savehist-autosave on a timer.  This
 258   ;; should not cause noticeable delays for users -- savehist-autosave
 259   ;; executes in under 5 ms on my system.
 260   (when (and savehist-autosave-interval
 261              (null savehist-timer))
 262     (setq savehist-timer
 263           (if (featurep 'xemacs)
 264               (start-itimer
 265                "savehist" 'savehist-autosave savehist-autosave-interval
 266                savehist-autosave-interval)
 267             (run-with-timer savehist-autosave-interval
 268                             savehist-autosave-interval 'savehist-autosave)))))
 269
 270 (defun savehist-uninstall ()
 271   "Undo installing savehist.
 272 Normally invoked by calling `savehist-mode' to unset the minor mode."
 273   (remove-hook 'minibuffer-setup-hook 'savehist-minibuffer-hook)
 274   (remove-hook 'kill-emacs-hook 'savehist-autosave)
 275   (when savehist-timer
 276     (if (featurep 'xemacs)
 277         (delete-itimer savehist-timer)
 278       (cancel-timer savehist-timer))
 279     (setq savehist-timer nil)))
 280
 281 (defun savehist-save (&optional auto-save)
 282   "Save the values of minibuffer history variables.
 283 Unbound symbols referenced in `savehist-additional-variables' are ignored.
 284 If AUTO-SAVE is non-nil, compare the saved contents to the one last saved,
 285  and don't save the buffer if they are the same."
 286   (interactive)
 287   (with-temp-buffer
 288     (insert
 289      (format ";; -*- mode: emacs-lisp; coding: %s -*-\n" savehist-coding-system)
 290      ";; Minibuffer history file, automatically generated by `savehist'.\n\n")
 291     (run-hooks 'savehist-save-hook)
 292     (let ((print-length nil)
 293           (print-string-length nil)
 294           (print-level nil)
 295           (print-readably t)
 296           (print-quoted t))
 297       ;; Save the minibuffer histories, along with the value of
 298       ;; savehist-minibuffer-history-variables itself.
 299       (when savehist-save-minibuffer-history
 300         (prin1 `(setq savehist-minibuffer-history-variables
 301                       ',savehist-minibuffer-history-variables)
 302                (current-buffer))
 303         (insert ?\n)
 304         (dolist (symbol savehist-minibuffer-history-variables)
 305           (when (boundp symbol)
 306             (let ((value (savehist-trim-history (symbol-value symbol))))
 307               (when value               ; don't save empty histories
 308                 (prin1 `(setq ,symbol ',value) (current-buffer))
 309                 (insert ?\n))))))
 310       ;; Save the additional variables.
 311       (dolist (symbol savehist-additional-variables)
 312         (when (boundp symbol)
 313           (let ((value (symbol-value symbol)))
 314             (when (savehist-printable value)
 315               (prin1 `(setq ,symbol ',value) (current-buffer))
 316               (insert ?\n))))))
 317     ;; If autosaving, avoid writing if nothing has changed since the
 318     ;; last write.
 319     (let ((checksum (md5 (current-buffer) nil nil savehist-no-conversion)))
 320       (unless (and auto-save (equal checksum savehist-last-checksum))
 321         ;; Set file-precious-flag when saving the buffer because we
 322         ;; don't want a half-finished write ruining the entire
 323         ;; history.  Remember that this is run from a timer and from
 324         ;; kill-emacs-hook, and also that multiple Emacs instances
 325         ;; could write to this file at once.
 326         (let ((file-precious-flag t)
 327               (coding-system-for-write savehist-coding-system))
 328           (write-region (point-min) (point-max) savehist-file nil
 329                         (unless (interactive-p) 'quiet)))
 330         (when savehist-file-modes
 331           (set-file-modes savehist-file savehist-file-modes))
 332         (setq savehist-last-checksum checksum)))))
 333
 334 (defun savehist-autosave ()
 335   "Save the minibuffer history if it has been modified since the last save.
 336 Does nothing if `savehist-mode' is off."
 337   (when savehist-mode
 338     (savehist-save t)))
 339
 340 (defun savehist-trim-history (value)
 341   "Retain only the first `history-length' items in VALUE.
 342 Only used under XEmacs, which doesn't (yet) implement automatic
 343 trimming of history lists to `history-length' items."
 344   (if (and (featurep 'xemacs)
 345            (natnump history-length)
 346            (> (length value) history-length))
 347       ;; Equivalent to `(subseq value 0 history-length)', but doesn't
 348       ;; need cl-extra at run-time.
 349       (loop repeat history-length collect (pop value))
 350     value))
 351
 352 (defun savehist-printable (value)
 353   "Return non-nil if VALUE is printable."
 354   (cond
 355    ;; Quick response for oft-encountered types known to be printable.
 356    ((stringp value))
 357    ((numberp value))
 358    ((symbolp value))
 359    (t
 360     ;; For others, check explicitly.
 361     (with-temp-buffer
 362       (condition-case nil
 363           (let ((print-readably t) (print-level nil))
 364           ;; Print the value into a buffer...
 365           (prin1 value (current-buffer))
 366           ;; ...and attempt to read it.
 367           (read (point-min-marker))
 368           ;; The attempt worked: the object is printable.
 369           t)
 370         ;; The attempt failed: the object is not printable.
 371         (error nil))))))
 372
 373 (defun savehist-minibuffer-hook ()
 374   ;; XEmacs sets minibuffer-history-variable to t to mean "no history
 375   ;; is being recorded".
 376   (unless (eq minibuffer-history-variable t)
 377     (add-to-list 'savehist-minibuffer-history-variables
 378                  minibuffer-history-variable)))
 379
 380 (provide 'savehist)
 381 \f
 382 ;; arch-tag: b3ce47f4-c5ad-4ebc-ad02-73aba705cf9f
 383
 384 ;;; savehist.el ends here