lisp/savehist.el

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